eventsource-py Agent Operating Manual
Welcome to eventsource-py, managed via SpecOpsβthe opinionated, autonomous Project Management as Code (PMaC) engine for human architects and AI coding assistants.
All specifications, user stories, tasks, and architectural decisions are version-locked directly in git alongside implementation code.
Hard Invariants
These rules are non-negotiable. Autonomous agents and human contributors must follow them without exception:
- File Length Limit (<500 lines):
- Source files over ~500 lines are strictly forbidden. Decompose large files into focused, single-responsibility modules.
- Enforced by
uv run spec-ops health(warns proactively at >=400 lines). Governed by ADR-0002.
- Blackbox Frontdoor Verification:
- Tests must exercise public interfaces (CLI commands, public module entry points, domain models) rather than reaching into private internals or backdoor state manipulation.
- Governed by ADR-0003.
- Strict Backlog Isolation:
- Multi-agent workers execute in isolated git worktrees (
.worktrees/) on dedicated task branches (task/orfeat/). - Shared backlog files (
docs/project/backlog/) must never be modified directly on feature branches; transitions are synchronized upon integration. - Governed by ADR-0005.
- UV Workspace Package Management:
- All Python tools and dependencies are managed through root UV workspace (
uv run pytest,uv run pytest -m "not integration and not postgres and not redis and not e2e and not benchmark",uv run spec-ops ...). Never invoke barepipor create ad-hoc virtual environments.
- Specification as Code (PMaC):
- Every requirement, persona, architectural decision, and work item lives under
docs/project/as Markdown with YAML frontmatter. - Governed by ADR-0001.
- Executable BDD User Stories & Frontdoor Testing:
- User stories in
docs/project/user_stories/accepted/must provide executable Gherkin scenarios. - All acceptance tests must verify observable outcomes without private mock backdoors.
- Governed by ADR-0006.
- Domain-Driven Design (DDD) & Bounded Contexts:
- Code is segmented into explicit bounded contexts with pure domain models isolated from infrastructure.
- Governed by ADR-0007.
- Property-Based Testing (Hypothesis) & Mutation Testing (Mutmut):
- Domain models, state machines, parsers, and health algorithms must maintain generative property tests (
@given(...)). - Core domain modules must maintain a minimum 80% mutation kill score under
mutmut. - Governed by ADR-0009.
- Security & Supply-Chain Hard Invariants:
- Autonomous agents are strictly forbidden from hardcoding credentials, modifying unapproved lockfiles, or executing non-allowlisted shell commands.
- Enforced by
uv run spec-ops health --securityand preflight secret scanners. Governed by ADR-0010, ADR-0011, and ADR-0012.
Security & Supply-Chain Hard Invariants
These security and supply-chain guardrails are non-negotiable across all autonomous worker streams:
- No Hardcoded Credentials: Autonomous agents are strictly forbidden from hardcoding credentials, API keys, tokens, or high-entropy secrets in source code, tests, or git commits.
- Lockfile Immutability: Autonomous agents are strictly forbidden from modifying unapproved lockfiles (
uv.lock,package-lock.json) without explicit human architectural approval. - Allowlisted Command Execution: Autonomous agents are strictly forbidden from executing non-allowlisted shell commands outside approved development toolchains.
- Dependency Management with UV:
- Never edit
pyproject.tomldependency tables by hand β useuv add,uv add --optional, oruv remove. - Always re-sync with
uv sync --all-extrasafter any dependency modification.
- Ring Layering & Invariant Isolation:
- Ring layering:
adaptersoverapplicationoverportsoverdomain. domainandportsmust not importobservability.- Inner rings must not import the
testingtoolkit. - Governed by ADR-0102 (ADR-0002: Hexagonal Ring Layering and Dependency Isolation).
Landing the Plane (Session Completion)
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
- Record remaining work - Add anything that needs follow-up to
BACKLOG.md - Run quality gates (if code changed) - Tests, linters, builds
- Update the backlog - Remove finished items, note in-progress ones
- PUSH TO REMOTE - This is MANDATORY: ``
bash git pull --rebase git push git status # MUST show "up to date with origin"`` - Clean up - Clear stashes, prune remote branches
- Verify - All changes committed AND pushed
- Hand off - Provide context for next session
CRITICAL RULES:
- Work is NOT complete until
git pushsucceeds - NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
Orchestration Failure Protocol (Dogfooding SpecOps)
When using the SpecOps orchestrator skill on this project, any orchestration failure is an actionable task:
- Immediate Bug Documentation: Orchestrators must document all failures as high-priority bugs/tasks in the backlog (
docs/project/backlog/proposed/or active queue). - Dispatch Remediation: Orchestrators must dispatch through them to resolve root causes and improve the life of all future maintainers.
Design Principles
- Version-Locked Specifications: Requirements, user stories, and tasks live in the exact same git commit history as implementation code.
- Thin Vertical Slicing: Decompose PRDs into thin, single-pass vertical slices and architectural spikes rather than speculative horizontal layers.
- Just-In-Time (JIT) Refinement: Maintain a lean buffer of ~10 ready tasks in
refined/to prevent specification rot before work begins. - Living Relational Graph: Maintain bidirectional traceability from Personas -> PRDs -> Stories -> Tasks -> ADRs -> Commits.
Project Structure & Navigation
All project management specifications live under docs/project/:
| Directory | Purpose |
|---|---|
docs/project/user_stories/PERSONAS.md |
Core user personas defining user needs and pain points |
docs/project/product/ |
PRDs progressing from idea/ to shaped/, accepted/, and shipped/ |
docs/project/user_stories/ |
Gherkin user stories defining end-to-end user journeys |
docs/project/adrs/ |
Architectural Decision Records organized with REGISTRY.md |
docs/project/backlog/ |
Work items in complete/, refined/, and proposed/ |
docs/project/backlog/PRIORITY.md |
Strict sequential priority queue for engineering tasks |
docs/project/backlog/ROADMAP.md |
High-level delivery milestones |
Documentation Directives (Diataxis Standards)
All system documentation outside docs/project/ follows the Diataxis framework (tutorials/, how-to/, reference/, explanation/):
- Consult Existing Docs: Search
docs/before implementing changes or adding new conventions. - Fix Stale Documentation: Update inaccurate or outdated documentation discovered during your work.
- Document Reusable Capabilities: When introducing or modifying public CLI flags, APIs, or architectural patterns, author corresponding how-to recipes or reference specs in
docs/.
Definition of Ready (DoR)
A backlog task or feature may only be transitioned to refined/ and pulled into active development when:
- Task Metadata Complete: Task frontmatter contains
id,title,status: Refined,target_bc, and explicit dependencies. - Governing Artifacts Linked: Reference PRD in
docs/project/product/accepted/, Persona indocs/project/user_stories/PERSONAS.md, and governing ADRs indocs/project/adrs/accepted/are cited. - Executable BDD Specification: Governing user story in
docs/project/user_stories/accepted/provides executable Gherkin scenarios (Given ... When ... Then) whose test setup is achievable strictly through public frontdoors without backdoor tampering (ADR-0006). - Generative Property Invariants Identified: Core domain state spaces, combinatorial parsers, and health algorithms identify invariant properties for Hypothesis
@given(...)testing (ADR-0009). - Mutation Testing Scope Defined: Target modules for Mutmut mutation testing identified with target >=80% mutant kill score (ADR-0009).
- INVEST Criteria Satisfied: Validated as a thin vertical slice (Independent, Negotiable, Valuable, Estimable, Small [<500 lines per file], Testable) with zero speculative horizontal layers.
- Documentation Review: Relevant existing documentation in
docs/reviewed to prevent conflicting conventions.
Definition of Done (DoD)
Work is complete and ready for integration into main only when:
- Blackbox Frontdoor Verification: 100% test pass rate (
uv run pytest) verifying observable contracts through public frontdoors with zero private mock backdoors (ADR-0003). - Executable BDD Scenarios Passing: All Gherkin acceptance criteria executed via
pytest-bddpass cleanly without mock backdoors (ADR-0006). - Hypothesis Property Tests Passing: Generative property tests verify domain invariants across randomized inputs without shrinking failures (ADR-0009).
- Mutmut Mutation Score Attained: Target domain modules achieve >=80% mutant kill score under
mutmut(ADR-0009). - Codebase Health Check:
uv run spec-ops healthreports 0 file limit violations (<500 lines) and 0 proactive warnings (<400 lines), and verifiesPRIORITY.mdsync (ADR-0002). - Lockfile Integrity:
uv lock --checkpasses cleanly without unstaged dependency drifts. - Documentation Integrity (Diataxis):
- Inaccurate or stale docs discovered during work are corrected.
- Reusable patterns, CLI commands, and architectural changes documented in
docs/how-to/ordocs/reference/. - Documentation builds cleanly (
uv run spec-ops docs build).
- Strict Backlog Progression: Task is moved from
refined/tocomplete/(or viaspec-ops queue complete) andPRIORITY.mdupdated atomically upon integration (ADR-0005). - Commit Provenance: Commits include structured trailers referencing governing tasks and stories (
SpecOps-Task: TASK-XXXX).
Task Execution Workflow
When picking up engineering work:
- Select Task: Always select the highest-priority unassigned task in
docs/project/backlog/PRIORITY.mdlocated inrefined/. - Review Invariants & DoR: Verify task meets the Definition of Ready (DoR); read governing ADRs, PRDs, and user stories cited in the frontmatter.
- Implement: Develop the solution using test-driven development through public frontdoors. Maintain BDD scenarios and Hypothesis property tests alongside feature code.
- Preflight Verification:
- Run
uv run spec-ops health(verify 0 file limit violations, 0 warnings, and PRIORITY.md sync). - Run
uv run pytest(verify 100% test pass rate across unit, BDD, and Hypothesis property tests). - Run
uv run pytest -m "not integration and not postgres and not redis and not e2e and not benchmark"(verify quality preflight passes). - Run
uv run mutmut run(verify mutant kill score on mutated domain modules). - Run
uv lock --check(verify lockfile synchronization).
- Complete: Verify all Definition of Done (DoD) criteria; move task to
complete/or usespec-ops queue complete, updatePRIORITY.md, and link commit or PR.