# Scenarios Illustrative walk-throughs of common work shapes. Each shows where the protocol kicks in, where PM helps, and what manual mode looks like. None are normative — the [primitives overview](./primitives/), the [PR conventions](./primitives/pr.md), and the [PM role spec](./agents/pm.md) are the contract. The four scenarios below are chosen to span two axes: _trivial vs. substantial scope_, and _low vs. high risk_. Most real work is some blend; pick the closest match and adjust. --- ## 1. Trivial, low risk — update copyright year **Shape:** change a small set of strings in obvious files. No behavioral effect. No external surface. **Spec needed?** No. Falls under AGENTS.md's "trivial = typo, comment, obvious one-line fix." **Flow:** 1. Issue opened: "update copyright to 2026" 2. You proceed without `/needs-spec` 3. Developer claims (applies `agent/working`), edits files, runs `just validate` 4. Developer opens PR with a one-line body, links the issue, sets `agent/review` on the issue 5. You merge after a quick visual **PM contribution:** minimal. No brief required — the issue body is self-explanatory. The PM ledger may not even exist for this issue. **Manual mode:** identical. PM's absence is not noticeable. --- ## 2. Trivial scope, high risk — bump dependencies **Shape:** Developer change is small. Risk lives in what the bump may break or expose: API drift, transitive-dependency churn, security posture. The substantive work is _QA_ work, not Developer work. **Spec needed?** No. There is no design to make. Forcing this through a spec routes work to the wrong role and produces a Developer-flavored artifact for a problem the QA owns. The QA's own audit/findings _is_ the durable artifact. **Flow:** 1. Issue opened: "bump deno_std to 0.220" 2. Developer makes the change (edit `deno.json`, regenerate locks, run `just validate`). Ledger is brief. PR opened 3. **QA engages with their own discipline:** - Changelog review against the codebase's actual API surface (QA greps for usage of changed/removed APIs) - Summarize CI validation results in its ledger - Findings posted in its ledger: pass | concerns | fail 4. If concerns: Developer revises in a follow-up cycle. If pass, leave for you to merge. **PM contribution:** brief for the _QA_ (not the Developer) includes the changelog URL, a pre-computed list of `deno_std` API surfaces used in the codebase, and prior dependency-bump QA findings from `wiki/`. QA starts hot instead of cold. **Manual mode:** you do the QA checklist yourself, or skip items at your own risk. **Why no spec:** specs capture _design_ thinking. Bumping a dependency has no design surface — the version is the version. What it has is a _verification_ surface, which is the QA's home turf. Trusting the QA to apply their own discipline produces a better artifact (the audit) than a Developer-authored risk-assessment spec would. --- ## 3. Typical new feature — `/healthz` endpoint **Shape:** new functionality. Touches code, tests, possibly docs and a runbook. **Spec needed?** Yes (default for new features). **Flow:** The Developer cycles through `{assignee=agent-dev → agent/working → agent/review}` twice — once for the spec, once for the implementation. Same state machine; the brief carries the phase. 1. Issue opened with the feature description and rough acceptance criteria; you include `/needs-spec` in the body or as a comment 2. PM reads `agent/new`, sees `/needs-spec`, writes an initial brief asking for a spec proposal, strips `agent/new`, assigns the issue to agent-dev 3. **Spec cycle:** the Developer picks up its assignment, claims (`agent/working`), drafts an OpenSpec proposal (behavior, contract, test plan, edge cases, `???` for ambiguity), opens a draft PR with the proposal only, runs `fjx dev done ` which sets `agent/review` on the issue, reassigns it to agent-pm, and assigns the PR to `$FJX_OWNER`. PM recognises the spec proposal and holds the issue for you. 4. You review the spec. Ask questions in comments if needed; reassign to agent-dev for revisions 5. When the spec is right, you comment `/spec-approved`. PM refreshes the brief to "implement against the approved spec", removes `agent/review`, reassigns issue to agent-dev 6. **Implementation cycle:** Developer claims again, implements per the approved spec, runs `fjx dev done ` which lands the issue on agent-pm. PM writes the QA brief and dispatches to agent-qa. 7. QA reviews the implementation against the spec. On concerns/fail, QA reassigns directly back to agent-dev with `agent/review` — no PM hop 8. You merge. Issue gets `agent/release` after the release flow If the spec is rejected at step 5, comment `/spec-rejected` instead. PM refreshes the brief with feedback from your comments and reassigns the issue to agent-dev; Developer revises in another spec cycle. **PM contribution:** the brief evolves across cycles. Initial brief points to relevant scaffolding (e.g., `doc/`, `runbooks/`) and similar prior PRs. Post-`/spec-approved` brief includes the approved spec content as the implementation contract. Post-`/spec-rejected` brief incorporates the rejection feedback verbatim. **Manual mode:** you transition labels yourself, write the brief by hand (or skip), and rely on comments to convey approve/reject feedback. The OpenSpec artifact lives in `openspec/` regardless of PM. --- ## 4. Bug of unknown veracity and unknown impact — "sometimes the API returns 500" **Shape:** report is vague. Reproduction unclear. Scope unclear. Root cause unknown. **Spec needed?** Unknown until investigation completes. The investigation itself is work. **Flow:** 1. Issue opened with the report and any reproduction info 2. No `/needs-spec` yet — investigation comes first. Developer claims (`agent/working`) 3. Developer's first ledger tasks are investigative: reproduce, narrow, identify root cause. Evidence is logs, repro steps, suspect commits — not necessarily code changes 4. Developer opens a PR adding `./wiki/findings/-.md` with sections: - **Veracity:** confirmed | not reproducible | flaky | environmental - **Root cause:** identified (with evidence) | unknown - **Impact:** scope and severity - **Proposed fix:** brief sketch, or none PR body includes `Refs #`. Set `agent/review` on the issue. 5. Decision point, based on findings: - **Trivial fix** (one-line, obvious): proceed without spec, scenario 1 path - **Non-trivial fix**: you `/needs-spec` now; scenario 3 path with the findings as preamble - **Not reproducible / not a bug**: the findings PR IS the closure artifact — merge it (recording the justification in `./wiki/findings/-.md`) and close the issue. Ledger Notes on the issue preserve the process 6. From here, the path is whichever scenario the findings dictate **PM contribution:** initial brief can include recent error-pattern runbooks, related closed bugs, monitoring dashboards from `wiki/`. If `/needs-spec` is issued mid-flight, PM refreshes the brief with the findings as context. **Manual mode:** same investigation discipline; you decide the path and apply labels yourself. **Why this is the most interesting scenario:** the type of work isn't fixed up front. The Developer's first job is to reduce uncertainty enough that you can make a routing decision. The failure mode to avoid is "patch it and move on" before veracity is established — investigation is real work. The findings file under `./wiki/findings/` is the durable artifact; the ledger on the issue captures the process. --- ## Cross-cutting notes - **The risk axis is independent of the scope axis.** Scenario 2 is the canonical reminder that small diffs can carry big risk. Don't let "trivial" mean "don't think." - **Each role has its own discipline; route to the role, not to a spec.** Specs are Developer artifacts capturing design intent. QA agents produce findings and audits. Builders produce build manifests and deployment plans. Don't force every kind of substantive work through the spec funnel — pick the role whose discipline fits the problem and trust them to apply it. - **High risk ≠ needs spec.** Risk routes to the role that can address it. Design risk → Developer + spec. Verification risk → QA + audit. Operational risk → Builder + plan. Diagnostic risk → whichever role can investigate, with findings as the artifact. - **PM is opportunistic in every scenario.** Removing PM never blocks delivery; it just means more clicks and more cold reads. - **The working-agent ledger ([issue conventions](./primitives/issue.md)) and the PM ledger ([PM role](./agents/pm.md)) are independent.** The working-agent ledger is the agent's task surface; the PM ledger is the assistant's record of `/commands` and briefs. Both live on the issue, with distinct markers, and do not overlap. - **`???` is mandatory for unknowns.** In specs, in findings, in PR descriptions. Never hallucinate to close the gap.