Document the complete workflow in flow, artifact, and reference views

[taspinar]

What changed

• New docs/workflow.md:
  • Flow: Mermaid diagrams of the overview, the planning phase, and the feature phase, with return arrows for review rounds and bypasses when a review has no findings. The text covers finishing after a revision or triage without adopted or FIX_NOW findings, and escalations.
  • Artifacts: a Mermaid figure per phase showing what each step writes and where: committed, working file (ignored by Git), or GitHub. Steps that run verify.sh say so.
  • Reference: a table per step (agent role and profile, your decision, what is written and committed, verify.sh), the checks that stop each step, and the helper scripts.
• New docs/project-map.md: what every rule file, document, script, library, contract, schema, and working directory is for.
• New docs/example.md: a sample project (a household recipe box) through every step, with the commands, prompts, and resulting files and GitHub items.
• README: a compact overview diagram, links to the new documents, and short command sequences including the worktree changes.
• docs/agentic-workflow.md and docs/development.md: duplicate lifecycle descriptions replaced by references to docs/workflow.md.
• start-planning.sh now ends by pointing to review-planning.sh instead of the old commit steps.
• New verification check docs-scripts: every script and library must appear in the project map.

Issue / acceptance criteria

Closes #53

Risk

• Low
• Medium
• High

Verification evidence

• ./scripts/verify.sh passed, also without global or system Git configuration
• Tests added/updated where appropriate (documentation check in scripts/verify.conf)
• Independent review completed when required
• Architecture/docs/ADR updated when required

All six Mermaid diagrams (README and docs/workflow.md) were parsed and rendered with Mermaid 11 in a browser. They have not been viewed on GitHub itself yet.

The worked example follows the scripts' prompts and messages, but has not been run end to end with real agents and a real GitHub repository.

Independent review: Codex (gpt-6-astra), read-only. PASS WITH MINOR FINDINGS; all four fixed:

• MIN1: the quick-start commands now include the cd into each worktree and the re-review before finishing.
• MIN2: the escalation guidance no longer suggests start-planning.sh can resume a planning worktree; it describes the manual route and says that no script exists for it yet.
• MIN3: cleanup commands now include the worktree path.
• MIN4: README references are links.

Agent involvement

Planner: —
Implementer: Claude (Opus 5.5)
Reviewer: Codex (gpt-6-astra)

Production impact

None.

🤖 Generated with Claude Code