Planning Workflow

Agent rule sheet: current rules only. History and reasoning are in the factory log.

The pipeline

• Substantial work runs Backlog task → durable docs → implementation. Update docs before code when the task is ahead of them.
• backlog/tasks/ is the sole queue. content/docs/ owns settled contracts and decision records. backlog/decisions/ holds open owner questions.
• There is no plan tier. Structural reasoning goes in a decision record under content/docs/decisions/; sequencing goes in a parent task and its subtasks; interrupted state goes in the task's Notes. plans/archived/, plans/references/ and plans/deprecated/ are history only: read one when a decision cites it, never create or revive one.
• References run one way: task documentation → one content/docs page; docs → sourcePlans slug for historical provenance. No hand-kept cross-reference lists.
• Where shipped and pending behaviour mix, label Current, Target and Gap; never present a target as current.

Choose the lightest planning tier that is safe

Task plan is the default. Reassess when scope or decisions grow.

Quick fix

No task or plan when all hold:

• bun run verify:changed --list reports the cosmetic tier (frontend, story or docs files only, small reach; see Repository Operations).
• No product, schema, workflow, permission, persistence, billing, routing or agent-behaviour impact; no changed public API, data contract, user-visible workflow or reusable component convention.
• No existing task or plan governs the affected behaviour (if one does, reconcile it).

Edit directly; do not file a receipt-only task afterwards. Promote to a task when the work grows a reusable component, helper or prop contract.

Task plan

• Description: outcome and current evidence. Acceptance Criteria: checkable results. Implementation Plan: approach, opening with the reading line. Notes: concise current state, rewritten not appended. Final Summary: verified outcome.
• Use parent/subtasks for long work, never short plans.

Structural work

Schema, permissions, risky migration, cross-cutting architecture or several linked decisions: create the parent task, write or extend a decision record for the settled reasoning (grill it first with grill-with-docs), and split the build into subtasks. Owner questions that block a subtask go to backlog/decisions/ and the subtask waits on the ruling.

Execution routing

• The primary builder implements serial work and runs gates directly.
• Delegate only for genuine parallelism, a bounded specialist investigation or materially different tools; state the benefit and the bounded assignment first. A role file is a checklist, not a reason for another context.
• Never run two Backlog CLI writers at once: task and decision ids are assigned from the files on disk, and scripts/check-backlog-comments.sh creates scratch tasks while it runs. Create tasks serially from one context.
• Independent work shares no unresolved decision, authority or editing surface; disjoint files alone are not enough. Worktrees and shared deployments follow Repository Operations.
• A delegated report's claims need located evidence (file and line, test name, verbatim gate output). Re-run claimed checks before relying on them; reject what cannot be located.

Review proportionate to risk

The tier printed by verify:changed decides:

• Classify by what changes, not by filename: a script bundled in a skill is code.
• Review never waives gates, regression evidence, structural cleanup or backend safeguards.
• Until 2026-10-06, record in the work item's authority whether review was required, requested or omitted, and any defects found by review or after landing (GB-192 measurement). Do not add shadow reviews.

Review personas

• Required or requested review uses code-reviewer in a fresh context; the builder cannot review its own context by adopting the persona.
• Specialists for one named uncertainty only: test-engineer (test strategy, sensitivity), security-auditor (trust boundaries, exposure, agent capabilities), web-performance-auditor (measured bottlenecks).
• Give a reviewer: outcome, authority, acceptance criteria, risk, base/candidate identity, the full scoped diff and verbatim gate evidence. Missing evidence is not a pass.
• Reviewers are read-only: no edits, commits, task changes, pushes, reseeds or production probes. No persona-to-persona fan-out. The builder fixes, then returns the delta with refreshed evidence; avoid a third full reread.

Model routing hints

At most one advisory label per task: model:fast (bounded docs, search, mechanical, test work), model:standard (contained implementation/UI), model:frontier (auth, schema/lifecycle migration, cross-slice agent work, ambiguous architecture). Labels never change scope, authority or gates.

Decision records

• A settled ruling or structural design lives in content/docs/decisions/, one page per decision, linked from the decisions index: title, date, who ruled, the ruling, the alternatives refused, consequences, and Current versus Target where the build is behind. Add an "In plain terms" aid.
• Provenance is the sourcePlans slug in frontmatter for pages that grew out of a retired plan; new pages need none.
• Code links to docs only where it helps (public interfaces, invariants, non-obvious rules); no blanket doc comments. Code cites a task only for an explicitly temporary implementation.
• bun run docs:trace while working; preflight --close runs it strict.

Maintenance loop

• Strategy changes update the plan and docs before work resumes.
• Blocked work moves the task to Blocked with its real blocker.
• One dated log entry per meaningful creation, review, revision or approval: YYYY-MM-DD — Actor: Action; outcome. Silence is not approval.

One record per landed boundary

The commit carries the story, findings and red/green evidence; the docs carry settled facts in the same commit; the task gets one dated receipt with commit, gate results and Verified against tree: YYYY-MM-DD. Keep task Notes as the current state, rewritten not appended.

Ceremony budget

• The task receipt and docs updates ride in the work commit for each boundary. No separate paperwork commits; the Final Summary lands in the last work commit. Filing a task is paperwork too: stage it with the next work commit unless the session ends there. The commit guard prints a reminder when only backlog/ or plans/ is staged.
• Measure the ceremony share with bun run factory:ledger on its default 30-day window. The lifetime figure (--since the first commit) reads old habits as a standing gap: on 2026-09-15 it said 28% against the 17% target while the 30-day window said 14%.

Backlog task rules

• Start with bunx backlog task list --plain. BACKLOG.md is a tombstone.

• Every task carries, from filing: one documentation authority, the verified label, and a latest comment Verified against tree: YYYY-MM-DD. Refresh the date only after checking the task against the tree. bun run task:new "Title" --doc path/to/authority files all three in one call and refuses an authority that is not in the tree (GB-276).

• Every task opens its Implementation Plan with a reading line: the authority plus at most two coding-rule sections by heading.

• Open owner questions live in backlog/decisions/ at status: proposed; settled rulings move to content/docs/decisions/.

• In Progress means a session is on it, and at most eight tasks are (GB-294, 2026-09-17). Leaving a task you are not returning to costs the status its meaning: on 2026-09-17 eighteen tasks held it at once, four untouched for more than three weeks, so the board could not be read. Moving on is free — To Do keeps the Notes, the acceptance criteria and the queue position, and Blocked or Parked says why with its real blocker. The number is measured, not chosen: over the seventeen active days from 2026-09-01 a commit named a median of five distinct tasks a day, so eight leaves room for work that spans sessions.

  preflight --close reports the count and names the tasks over it, and reports any In Progress task whose acceptance criteria are all met. Both are advisory and neither fails the close (owner ruling, 2026-09-17): an overflowing board is rarely the fault of the landing that finds it, and a session blocked by someone else's housekeeping pays more than the drift costs.

  In plain terms: a matter is open because someone is acting on it this week. Closing the file, or marking it awaiting-instructions, is not giving up — it is what makes the open ones mean something.

Backlog.md CLI loop

• If bunx backlog says "No .backlog project found", another global CLI is shadowing it: use bunx backlog.md@1.50.1.
• Use the CLI for task files; never hand-edit generated Markdown.
• Never type a standalone --- line inside --comment text; prove the corpus with bash scripts/check-backlog-comments.sh after bulk edits.
• Unfamiliar operation: bunx backlog instructions task-creation (also task-execution, task-finalization).

bunx backlog task list --plain
bunx backlog task view GB-12 --plain
bun run task:new "Outcome" --description "Why" --ac "Checkable result" --doc path/to/authority
# task:new wraps `backlog task create` and applies the verified label and dated comment;
# its last line is `Filed GB-NN`, the new id.
bunx backlog task edit GB-NN --add-label verified --comment "Verified against tree: YYYY-MM-DD." --plain
bunx backlog task edit GB-12 --status "In Progress" --plan "1. First step" --plain
bunx backlog task create -p GB-12 "Independent subtask" --doc path/to/authority --plain
bunx backlog task edit GB-12 --check-ac 1 --final-summary "What landed and how it was verified" --status Done --plain
bunx backlog decision create "Question to settle" --status proposed --plain

Session handoffs

• No routine end-of-session summary and no handoff files: commits, docs and tasks are the record. Interrupted state (a partial migration, a diagnosis in progress, a temporary external condition) goes in the task's Notes with the safe resumption point and hazards; a fresh-session prompt goes in the task's Notes too.
• Before resuming from Notes, audit them against the tree: grep each named symbol or file, since another session may have landed the step. Prefer recorded evidence (eval-results/ on the dev machine) over re-running.