Forgejo Accelerated
Powered by

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, the PR conventions, and the PM role spec 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 <N> 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 <N> 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/<N>-<slug>.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 #<N>. 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/<N>-<slug>.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) and the PM ledger (PM role) 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.

© Copyright 2026. All rights reserved.