From 69e745f2db82f0f08cd86b9f8409efceef9b291e Mon Sep 17 00:00:00 2001 From: Ahmet Taspinar Date: Sat, 3 Oct 2026 00:45:38 +0200 Subject: [PATCH] Document the complete workflow in flow, artifact, and reference views docs/workflow.md shows the overview, planning, and feature flows with their loops as Mermaid diagrams, an artifact figure per phase (committed, working file, or GitHub), and a reference table per step. New docs/project-map.md explains every file and docs/example.md walks a sample project through the whole workflow. The README links to them, and duplicate lifecycle descriptions are replaced by references. start-planning.sh now ends by pointing to the planning review, and a verification check keeps the project map complete. Closes #53 Co-Authored-By: Claude Opus 5.5 --- README.md | 102 ++++++--------- docs/agentic-workflow.md | 72 ++--------- docs/development.md | 9 +- docs/example.md | 257 ++++++++++++++++++++++++++++++++++++++ docs/project-map.md | 93 ++++++++++++++ docs/workflow.md | 218 ++++++++++++++++++++++++++++++++ scripts/start-planning.sh | 13 +- scripts/verify.conf | 1 + 8 files changed, 623 insertions(+), 142 deletions(-) create mode 100644 docs/example.md create mode 100644 docs/project-map.md create mode 100644 docs/workflow.md diff --git a/README.md b/README.md index c29257f..c8494b9 100644 --- a/README.md +++ b/README.md @@ -2,84 +2,58 @@ A lightweight, model-agnostic repository template for agentic software engineering. It applies the useful parts of GH-600 at individual/small-team scale: plan → act → evaluate, GitHub as control plane, isolated execution, explicit agent contracts, risk-based autonomy, evidence, independent review, CI, and human gates for high-risk actions. -## Start a new project -1. Create a repository from this GitHub template (or clone it and point it at a new remote). - Then check that your machine has the required tools: +## How it works - ```bash - ./scripts/doctor.sh - ``` -2. Record the initial project idea in `README.md`, complete - `docs/repository-setup.md`, and configure the new remote. Set the agent and - model of each workflow role in `.agents/agents.conf` to ones your accounts - support. -3. Start the two-phase project bootstrap: +A project goes from an idea to merged features in two phases, each with an +independent, read-only review loop and explicit human approvals. - ```bash - ./scripts/start-planning.sh - # or, with an existing project description: - ./scripts/start-planning.sh --description path/to/description.md - ``` +```mermaid +flowchart LR + idea["Idea"] --> planning["Planning
review ↔ revise"] --> approval["Planning
approved"] + approval --> issue["Feature
Issue"] --> feature["Feature
review ↔ fix"] --> pr["Feature PR
merged"] + pr -- next feature --> issue +``` + +- [Workflow](docs/workflow.md): the workflow in flow, artifact, and reference views. +- [Worked example](docs/example.md): a complete run with a sample project. +- [Development](docs/development.md): every command and its options. +- [Project map](docs/project-map.md): what each file in the template is for. - The script creates `planning/project-bootstrap` in a sibling worktree. The - first interactive session runs Project Grill and drafts - `docs/PROJECT_REQUIREMENTS.md`. After you explicitly approve those - requirements, a separate project-planning session creates the architecture, - necessary ADRs, and roadmap. The script does not commit or push. -4. In the planning worktree, review and revise the planning until the review - passes, then approve it: +## Start a new project + +1. Create a repository from this template, complete `docs/repository-setup.md`, + and check your machine with `./scripts/doctor.sh`. +2. Set the provider and model of each role in `.agents/agents.conf`. +3. Plan the project in a planning worktree: ```bash + ./scripts/start-planning.sh --description path/to/idea.md + cd ../-planning-project-bootstrap ./scripts/review-planning.sh ./scripts/revise-planning.sh --review .agents/reviews/planning-project-bootstrap-review-01.json - ./scripts/review-planning.sh + ./scripts/review-planning.sh # again after each revision, until it passes ./scripts/finish-planning.sh ``` - Commit and push the planning branch as `finish-planning.sh` shows, then merge - it through a PR before feature development. -5. Create a GitHub Issue only for the next actionable roadmap feature, from its - block in `docs/roadmap.md`: + Commit, push, and merge the planning PR as `finish-planning.sh` shows, then + remove the planning worktree with + `./scripts/cleanup-worktree.sh ../-planning-project-bootstrap`. +4. For each roadmap feature, from the primary checkout and then the feature + worktree: ```bash ./scripts/create-feature-issue.sh F01 - ``` - - For non-trivial work, create `.agents/plans/-.md` using - `.agents/prompts/planner.md`. -6. Start the feature and implementation agent: - - ```bash - ./scripts/start-feature.sh 12 player-movement - ``` - - This creates `feature/12-player-movement` in an isolated worktree and starts the configured implementation agent there. -7. In the feature worktree, verify and run an independent review when required by `.agents/policies/autonomy.md`: - - ```bash - ./scripts/verify.sh + ./scripts/start-feature.sh 12 recipes + cd ../-12-recipes ./scripts/review-feature.sh 12 - ./scripts/triage-review.sh \ - .agents/reviews/feature-12-player-movement-review-01.json - ``` - -8. Approve the proposed triage and apply its `FIX_NOW` scope: - - ```bash - ./scripts/apply-triage.sh \ - .agents/triage/feature-12-player-movement-review-01-triage.json - ``` - - The script starts a write-capable agent only after confirmation and verifies - the resulting implementation. - Approved `DEFER` findings become linked follow-up Issues; `ACCEPT` findings - retain their rationale in the triage artifact. -9. After a new review round confirms the fixes, commit with the closing checks: - - ```bash - ./scripts/finish-feature.sh 12 "Implement player movement" + ./scripts/triage-review.sh .agents/reviews/feature-12-recipes-review-01.json + ./scripts/apply-triage.sh .agents/triage/feature-12-recipes-review-01-triage.json + ./scripts/review-feature.sh 12 # again after fixes, until it is resolved + ./scripts/finish-feature.sh 12 "Add recipes" ``` - Then push and open a PR containing `Closes #12`. After CI and required gates pass, merge the PR and clean up the worktree. + Push, open a PR containing `Closes #12`, merge it after CI, and remove the + worktree from the primary checkout with + `./scripts/cleanup-worktree.sh ../-12-recipes`. -See `docs/development.md` for commands, `docs/agentic-workflow.md` for the lifecycle, and `.agents/policies/` for boundaries. +Rules for agents are in `AGENTS.md`; boundaries are in `.agents/policies/`. diff --git a/docs/agentic-workflow.md b/docs/agentic-workflow.md index 8cb24fc..ad719b2 100644 --- a/docs/agentic-workflow.md +++ b/docs/agentic-workflow.md @@ -1,27 +1,16 @@ # Agentic Development Workflow -## Project bootstrap -Template → Project Grill → draft project requirements → human approval → -architecture/roadmap and necessary ADRs → planning PR → GitHub Issues for -ready work. - -## Feature lifecycle -Roadmap item → GitHub Issue → feature plan (when warranted) → isolated -branch/worktree → implementation → local verification → independent review -when required → review triage → approved fix-now application → -verification/re-review when needed → `finish-feature.sh` → push/PR → CI → human gate where -required → merge → automatic Issue closure → cleanup. +## Lifecycle + +The steps, loops, artifacts, and approvals of project bootstrap and feature +development are described in `docs/workflow.md`. This document covers the +principles behind them. Independent review happens before the implementation commit so it can include -uncommitted working-tree changes. The reviewer runs read-only and -non-interactively; `review-feature.sh` supplies the Issue and diff and stores -the returned report. `triage-review.sh` classifies every finding as -`FIX_NOW`, `DEFER`, or `ACCEPT` and displays the proposal before side effects. -Critical and Major findings must be `FIX_NOW`. Human approval is required -before triage artifacts or provenance-prefixed deferred follow-up Issues are -created. `apply-triage.sh` requires the approved artifact explicitly and starts -a write-capable agent for only its `FIX_NOW` scope after a second confirmation. -See `docs/development.md` for the concrete commands. +uncommitted working-tree changes. Reviewers run read-only; their results are +validated JSON, and the reports of each feature review round are published on +the feature Issue. Critical and major findings must be fixed and confirmed by +a newer review round before a feature or the planning can be finished. ## Persistent state - GitHub Issue: what/why, acceptance criteria, priority/status. @@ -42,49 +31,6 @@ See `docs/development.md` for the concrete commands. - Git history: what actually changed. - PR + CI: review discussion and deterministic evidence. -## Project bootstrap workflow - -A newly created project should be bootstrapped before feature development -starts. - -Recommended sequence: - -1. Create the repository from this template. -2. Complete `docs/repository-setup.md`. -3. Set the agent and model per role in `.agents/agents.conf`, then run the - bootstrap entrypoint: - - `./scripts/start-planning.sh` - -4. The script creates `planning/project-bootstrap` in an isolated sibling - worktree from the current `origin/main`. -5. Project Grill asks material project-level questions and writes: - - - `docs/PROJECT_REQUIREMENTS.md` - -6. Review the proposed requirements. The script records approval only after an - explicit human confirmation. -7. A separate project-planner session may then create or update: - - `docs/architecture.md` - - `docs/roadmap.md` - - required ADRs under `docs/decisions/` - -8. An independent agent reviews the planning (`review-planning.sh`). The - planner decides per finding and revises the adopted ones - (`revise-planning.sh`). Repeat until the review passes. -9. Approve the planning with `finish-planning.sh`, which records - `docs/PLANNING_APPROVAL.md`. -10. Verify, commit, and push the planning branch. -11. Open a Pull Request. -12. Merge the approved bootstrap into `main`. -13. Convert only ready roadmap items into GitHub Issues with - `create-feature-issue.sh`, which requires a current planning approval. -14. Start feature clarification and development. - -Declining requirements approval or an agent failure preserves the worktree and -stops later phases. The script does not fall back to another model, implement -features, create Issues, commit, push, open or merge a PR, or deploy. - ## Roadmap to GitHub Issues `docs/roadmap.md` describes the intended project direction and contains diff --git a/docs/development.md b/docs/development.md index f40358c..a750a4c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -540,10 +540,7 @@ The helper manages one delimited plan block in the Issue body. Re-running it updates that block instead of appending duplicates. It stores only the repository-relative plan path; the detailed plan remains in `.agents/plans/`. -## Lifecycle summary +## Lifecycle -Roadmap item → GitHub Issue → optional implementation plan → isolated feature -worktree → implementation → verification → independent review when required → -triage → apply approved `FIX_NOW` findings → verification/re-review when needed -→ `finish-feature.sh` (checks and commit) → push/PR → CI and gates → merge → -automatic Issue closure → worktree cleanup. +The complete lifecycle, with diagrams and a reference table per step, is in +`docs/workflow.md`. diff --git a/docs/example.md b/docs/example.md new file mode 100644 index 0000000..0e96bec --- /dev/null +++ b/docs/example.md @@ -0,0 +1,257 @@ +# Worked example + +A complete run of the workflow with a small sample project: a recipe box that +a household shares. The repository is called `recipe-box`. Agent output +differs per run; the prompts, files, and checks shown here are what the +scripts produce. + +The flow diagrams are in `docs/workflow.md`; every option is in +`docs/development.md`. + +## 0. Prepare the repository + +Create `recipe-box` from the template, complete `docs/repository-setup.md`, +and check your machine: + +```bash +./scripts/doctor.sh +``` + +Every line should read `OK`. A missing agent CLI that `.agents/agents.conf` +assigns to a role is `FAILED`. Set each role to a provider and model your +accounts support, for example: + +```text +project-grill: claude fable +project-planner: claude fable +planning-reviewer: codex gpt-6-astra +implementer: codex gpt-6-astra +reviewer: claude fable +triage: claude fable +triage-implementer: codex gpt-6-astra +``` + +Write the idea down, anywhere, in a few sentences: + +```text +A web app where a household keeps its shared recipes and plans the meals for +the week. It should work on a phone in the kitchen. +``` + +## 1. Plan the project + +```bash +./scripts/start-planning.sh --description ~/notes/recipe-box.md +``` + +The script creates the branch `planning/project-bootstrap` in +`../recipe-box-planning-project-bootstrap` and copies the idea to +`docs/PROJECT_DESCRIPTION.md` there. + +**Project Grill** reads the idea and asks only what it leaves open, for example +whether members need accounts, whether the plan is shared live, and whether the +MVP needs offline use. It writes `docs/PROJECT_REQUIREMENTS.md` and the script +shows it: + +```text +Approve these project requirements and continue to architecture planning? [y/N] +``` + +After `y`, the **project planner** writes `docs/architecture.md`, +`docs/roadmap.md` with features such as `F01 — Recipes` and +`F02 — Weekly meal plan`, and ADRs where a decision needs a record. The script +ends with: + +```text +Project bootstrap planning completed. +Next, in the planning worktree, review the planning with an independent agent: +``` + +## 2. Review and revise the planning + +```bash +cd ../recipe-box-planning-project-bootstrap +./scripts/review-planning.sh +``` + +The planning reviewer reads the documents read-only. The script reports the +verdict, for example `Review completed: CHANGES REQUIRED (2 findings)`, and the +report lists findings such as: + +```text +M1 [major] Household access is required but no feature plans it +MIN1 [minor] F02 has no acceptance criterion for an empty week +``` + +They are stored in `.agents/reviews/planning-project-bootstrap-review-01.json` +and a readable `.md` report next to it. The script suggests the next step: + +```bash +./scripts/revise-planning.sh --review .agents/reviews/planning-project-bootstrap-review-01.json +``` + +The planner first decides per finding, read-only, and you see: + +```text +ADOPT +- M1 [major] Household access is required but no feature plans it — The requirements make access per household part of the MVP. +REJECT +- MIN1 [minor] F02 has no acceptance criterion for an empty week — An empty week is the default state and covered by F02's criteria. +... +Record these decisions and revise the planning for the adopted findings? [y/N] +``` + +After `y`, the decisions are recorded in `…-review-01-revision.json` and the +planner changes only the architecture, roadmap, and ADRs, for example by adding +`F03 — Household access`. The review is now stale, so run round 2: + +```bash +./scripts/review-planning.sh +``` + +Repeat until a round passes, or until its remaining minor findings are +rejected or deferred. + +## 3. Approve and merge the planning + +```bash +./scripts/finish-planning.sh +``` + +The script checks that the latest round is current and resolved, shows every +finding that was not adopted with its rationale, and asks: + +```text +Approve this planning? [y/N] +``` + +It records `docs/PLANNING_APPROVAL.md` and prints the commit steps: + +```bash +./scripts/verify.sh +git add docs/PROJECT_DESCRIPTION.md docs/PROJECT_REQUIREMENTS.md docs/architecture.md docs/roadmap.md docs/decisions docs/PLANNING_APPROVAL.md +git commit -m "Plan project bootstrap" +git push -u origin planning/project-bootstrap +``` + +Open the planning PR, paste the summary from `docs/PLANNING_APPROVAL.md` into +its description, and merge it after CI. Remove the planning worktree from the +primary checkout: + +```bash +./scripts/cleanup-worktree.sh ../recipe-box-planning-project-bootstrap +``` + +## 4. Start the first feature + +In the primary checkout, on an up-to-date `main`: + +```bash +./scripts/create-feature-issue.sh F01 +``` + +The script checks that the planning approval still matches the roadmap, shows +the Issue it would create from the `F01` block, and asks +`Create this Issue? [y/N]`. Say the Issue is `#12`: + +```bash +./scripts/start-feature.sh 12 recipes +``` + +This creates `feature/12-recipes` in `../recipe-box-12-recipes` and starts the +implementer there. It writes code and tests and does not commit. + +## 5. Review, triage, and fix + +In the feature worktree: + +```bash +cd ../recipe-box-12-recipes +./scripts/verify.sh +./scripts/review-feature.sh 12 +``` + +The reviewer receives the Issue and the complete diff, including uncommitted +files, and cannot change anything. The report of round 1 might list: + +```text +M1 [major] Deleting a recipe removes it for other households +MIN1 [minor] Recipe titles are not trimmed +``` + +Triage the round: + +```bash +./scripts/triage-review.sh .agents/reviews/feature-12-recipes-review-01.json +``` + +The triage agent proposes `FIX_NOW` for `M1` and, for example, `DEFER` for +`MIN1` with a follow-up Issue titled `[F01][R01][MIN1] Trim recipe titles`. +After `Proceed with this triage? [y/N]`, the script creates that follow-up +Issue and publishes the review and triage reports as one comment on `#12`. + +Fix the approved scope: + +```bash +./scripts/apply-triage.sh .agents/triage/feature-12-recipes-review-01-triage.json +``` + +After `Start a write-capable codex agent for this scope? [y/N]`, the +implementer resolves only `M1`, and the script runs `./scripts/verify.sh`. The +code changed, so review round 1 is stale; run round 2: + +```bash +./scripts/review-feature.sh 12 +``` + +When round 2 passes, there is nothing to triage. + +## 6. Finish the feature + +```bash +./scripts/finish-feature.sh 12 "Add recipes" +``` + +The script runs the verification and checks that round 2 is current and that +round 1's triage was published. Your editor opens with: + +```text +Add recipes + +Issue: #12 + +Changes: +- TODO: summarize the main changes + +Verification: +- ./scripts/verify.sh passed + +Review: round 2, PASS, by claude (fable); triage published on #12 + +Refs #12 +``` + +Replace the TODO, save, and close the editor. Then: + +```bash +git push -u origin feature/12-recipes +``` + +Open a pull request containing `Closes #12` and merge it after CI. Remove the +worktree from the primary checkout: + +```bash +./scripts/cleanup-worktree.sh ../recipe-box-12-recipes +``` + +The next feature starts again at step 4 with `create-feature-issue.sh F02`. + +## Where everything ended up + +| Item | Where | +|---|---| +| Idea, requirements, architecture, roadmap, ADRs, planning approval | `docs/`, committed with the planning PR | +| Planning reviews and revisions | `.agents/reviews/` in the planning worktree, not committed; summarized in `PLANNING_APPROVAL.md` | +| Feature Issue `#12` and follow-up Issue for `MIN1` | GitHub | +| Feature reviews and triage | `.agents/` in the feature worktree, not committed; published as a comment on `#12` | +| Code, tests, and the fix for `M1` | The commit made by `finish-feature.sh`, merged with the feature PR | diff --git a/docs/project-map.md b/docs/project-map.md new file mode 100644 index 0000000..18a6912 --- /dev/null +++ b/docs/project-map.md @@ -0,0 +1,93 @@ +# Project map + +What each part of the template is for. The workflow that connects them is in +`docs/workflow.md`. + +## Rules and configuration + +| Path | Purpose | +|---|---| +| `AGENTS.md` | Durable working rules for every agent: source precedence, Definition of Done, boundaries, branch policy | +| `.agents/agents.conf` | Provider and model per workflow role | +| `.agents/policies/` | Risk-based autonomy, execution limits, recovery, conflict resolution, and tool permissions | +| `scripts/verify.conf` | The required verification checks of the project | +| `.github/` | CI workflow, Issue templates, PR template, and code owners | +| `CONTRIBUTING.md`, `SECURITY.md` | How to contribute and how to handle security-sensitive findings | + +## Project documents + +| Path | Purpose | Written by | +|---|---|---| +| `README.md` | What the project is and how to start | You | +| `docs/PROJECT_DESCRIPTION.md` | Your original project idea, unchanged | `start-planning.sh --description` | +| `docs/PROJECT_REQUIREMENTS.md` | The requirements you approved | Project Grill, approved by you | +| `docs/architecture.md` | The current system design | Project planner | +| `docs/roadmap.md` | Roadmap features with stable IDs (F01, F02, …) | Project planner | +| `docs/decisions/` | Architecture decision records | Project planner | +| `docs/PLANNING_APPROVAL.md` | Your approval of the reviewed planning, with its fingerprint | `finish-planning.sh` | +| `docs/repository-setup.md` | GitHub settings for a new repository | You | +| `docs/development.md` | Every command and its behaviour | Template | +| `docs/workflow.md` | The workflow in flow, artifact, and reference views | Template | +| `docs/example.md` | A complete run with a sample project | Template | +| `docs/agentic-workflow.md` | Principles: persistent state, roadmap versus Issues, plans versus Issues | Template | +| `docs/evaluation.md` | Review criteria, finding severities, and the testing principle | Template | +| `docs/deployment.md`, `docs/operations.md` | Deployment and operations of the project | You | + +## Workflow scripts + +| Script | Purpose | +|---|---| +| `scripts/doctor.sh` | Checks the local prerequisites | +| `scripts/verify.sh` | Runs the checks in `scripts/verify.conf`; used by humans, agents, and CI | +| `scripts/start-planning.sh` | Project Grill, requirements approval, and project planning in a planning worktree | +| `scripts/review-planning.sh` | Independent, read-only review of the planning documents | +| `scripts/revise-planning.sh` | The planner's decision per planning finding, then the revision | +| `scripts/finish-planning.sh` | Checks and records your approval of the planning; `--check` tests it | +| `scripts/create-feature-issue.sh` | Creates the Issue of one roadmap feature | +| `scripts/start-feature.sh` | Creates the feature worktree and starts the implementer | +| `scripts/review-feature.sh` | Independent, read-only review of the complete feature diff | +| `scripts/triage-review.sh` | Classifies review findings, creates follow-up Issues, and publishes the reports on the Issue | +| `scripts/apply-triage.sh` | Lets an implementer resolve only the `FIX_NOW` findings | +| `scripts/finish-feature.sh` | Checks the feature and creates the commit | +| `scripts/check-review.sh` | Reports whether a review still matches what it covers | +| `scripts/update-issue-with-plan.sh` | Links an optional feature plan to its Issue | +| `scripts/cleanup-worktree.sh` | Removes a worktree after its merge | + +## Script libraries + +| Path | Purpose | +|---|---| +| `scripts/lib/agent.sh` | Role configuration, `--agent`/`--model` overrides, and starting agents with the `write` or `read-only` profile | +| `scripts/lib/review-data.sh` | Validation and rendering of review, triage, and revision JSON | +| `scripts/lib/review-run.sh` | Running a read-only agent with one retry, and storing a review | +| `scripts/lib/fingerprint.sh` | Content fingerprints of a working tree or a set of files | +| `scripts/lib/scope.sh` | File-scope enforcement for write sessions | +| `scripts/lib/planning.sh` | The planning scope and the planning approval check | + +## Agent contracts and schemas + +| Path | Used by | +|---|---| +| `.agents/prompts/project-grill.md` | Project Grill in `start-planning.sh` | +| `.agents/prompts/project-planner.md` | The project planner in `start-planning.sh` | +| `.agents/prompts/planning-reviewer.md` | `review-planning.sh` | +| `.agents/prompts/planning-reviser.md` | `revise-planning.sh` | +| `.agents/prompts/planner.md` | Optional feature plans in `.agents/plans/` | +| `.agents/prompts/implementer.md` | `start-feature.sh` | +| `.agents/prompts/reviewer.md` | `review-feature.sh` | +| `.agents/prompts/triage-reviewer.md` | `triage-review.sh` | +| `.agents/prompts/triage-implementer.md` | `apply-triage.sh` | +| `.agents/schemas/review.schema.json` | Results of feature and planning reviews | +| `.agents/schemas/triage.schema.json` | Triage decisions | +| `.agents/schemas/revision.schema.json` | Planning revision decisions | + +## Working directories + +| Path | Contents | Committed | +|---|---|---| +| `.agents/reviews/` | Review and revision results (JSON and generated reports) | No | +| `.agents/triage/` | Approved triage results (JSON and generated reports) | No | +| `.agents/plans/` | Optional feature plans | Yes | +| `.agents/handoffs/` | Continuation notes for interrupted work | Yes | +| `.agents/lessons/` | Recurring agent failures and the rules learned from them | Yes | +| `tests/` | Integration tests of the workflow scripts, run by `verify.sh` | Yes | diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 0000000..cf155dc --- /dev/null +++ b/docs/workflow.md @@ -0,0 +1,218 @@ +# Workflow + +How a project goes from an idea to merged features, in three views: + +1. [Flow](#flow): the steps and the loops between them. +2. [Artifacts](#artifacts): what each step produces and where it lives. +3. [Reference](#reference): per step, who acts, where you approve, and what is + written and committed. + +The commands and their options are described in `docs/development.md`. A +complete run with a sample project is in `docs/example.md`. What each file in +the repository is for is in `docs/project-map.md`. + +## Flow + +### Overview + +The project planning happens once. Every roadmap feature then goes through its +own Issue, feature work, and pull request. + +```mermaid +flowchart TD + idea["Project idea
PROJECT_DESCRIPTION.md"] + planning["Project planning
start-planning.sh … finish-planning.sh"] + planpr["Planning PR merged
docs/ and PLANNING_APPROVAL.md"] + issue["Feature Issue
create-feature-issue.sh F01"] + feature["Feature work
start-feature.sh … finish-feature.sh"] + featurepr["Feature PR merged
Closes the feature Issue"] + + idea --> planning --> planpr --> issue --> feature --> featurepr + featurepr -- next roadmap feature --> issue + + classDef plan fill:#E1F5EE,stroke:#0F6E56,color:#085041 + classDef feat fill:#EEEDFE,stroke:#534AB7,color:#3C3489 + classDef neutral fill:#F1EFE8,stroke:#5F5E5A,color:#444441 + class planning plan + class issue,feature feat + class idea,planpr,featurepr neutral +``` + +### Planning phase + +All planning steps run in the planning worktree (`planning/`). + +```mermaid +flowchart TD + start["start-planning.sh
Project Grill, your approval, planner"] + review["review-planning.sh
independent review, read-only"] + revise["revise-planning.sh
decisions, your approval, revision"] + finish["finish-planning.sh
checks, your final approval"] + + start --> review + review -- findings --> revise + revise -- review again --> review + review -- no findings --> finish + revise -- nothing adopted --> finish + + classDef plan fill:#E1F5EE,stroke:#0F6E56,color:#085041 + class start,review,revise,finish plan +``` + +- A revision that adopts findings changes the planning documents, so the + review becomes stale and the next step is a new review round. +- When the planner rejects or defers every finding, nothing changes and you + can finish directly. +- A finding that the planner escalates needs your decision: either it does not + apply, or the approved requirements must change. There is no script yet that + runs Project Grill again in an existing planning worktree, and + `start-planning.sh` always starts a fresh planning branch. To change the + requirements, edit `docs/PROJECT_REQUIREMENTS.md` in the planning worktree, + or start a Project Grill session there by hand with + `.agents/prompts/project-grill.md`, and run a new review round. The planning + review covers the requirements, and `finish-planning.sh` records your + approval of exactly the reviewed documents. It refuses while an escalation + of the latest round is unresolved and asks you to confirm earlier ones. + +### Feature phase + +All feature steps run in the feature worktree (`feature/-`). + +```mermaid +flowchart TD + start["start-feature.sh
own worktree, implementer writes"] + review["review-feature.sh
independent review, read-only"] + triage["triage-review.sh
your approval, report on the Issue"] + apply["apply-triage.sh
fix only FIX_NOW findings"] + finish["finish-feature.sh
checks, commit in your editor"] + + start --> review + review -- findings --> triage + triage --> apply + apply -- review again --> review + review -- no findings --> finish + triage -- no FIX_NOW --> finish + + classDef feat fill:#EEEDFE,stroke:#534AB7,color:#3C3489 + class start,review,triage,apply,finish feat +``` + +- Fixes change the code, so the review becomes stale and the next step is a new + review round. A passed newer round confirms the fixes of earlier rounds. +- When the triage has no `FIX_NOW` findings, only deferred and accepted ones, + you can finish directly. +- After `finish-feature.sh`, push the branch, open a pull request containing + `Closes #`, and merge it after CI. Then remove the worktree with + `cleanup-worktree.sh`. + +## Artifacts + +Every step writes to one of three places: + +- **Repository**: committed with the planning or feature pull request. +- **Working file**: under `.agents/reviews/` or `.agents/triage/`, read by the + scripts and ignored by Git. +- **GitHub**: Issues, comments, and pull requests. + +### Planning phase + +```mermaid +flowchart LR + sp["start-planning.sh"] --> docs["PROJECT_DESCRIPTION.md
PROJECT_REQUIREMENTS.md
architecture.md, roadmap.md, ADRs"] + rp["review-planning.sh"] --> prv["planning-NAME-review-NN.json and .md"] + rv["revise-planning.sh"] --> rvd["…-review-NN-revision.json and .md"] + rv --> rdocs["architecture.md, roadmap.md, ADRs
for adopted findings"] + fp["finish-planning.sh"] --> appr["PLANNING_APPROVAL.md"] + cfi["create-feature-issue.sh F01"] --> fi["Feature Issue"] + + classDef repo fill:#E1F5EE,stroke:#0F6E56,color:#085041 + classDef local fill:#F1EFE8,stroke:#5F5E5A,color:#444441 + classDef github fill:#FAECE7,stroke:#993C1D,color:#712B13 + class docs,rdocs,appr repo + class prv,rvd local + class fi github + classDef step fill:#FFFFFF,stroke:#888780,color:#2C2C2A + class sp,rp,rv,fp,cfi step +``` + +Green is committed, grey is a working file, orange is on GitHub. Because +review and revision files are not committed, `PLANNING_APPROVAL.md` records +the review rounds and every finding that was not adopted; use it for the +planning PR description. + +### Feature phase + +```mermaid +flowchart LR + sf["start-feature.sh"] --> code["code and tests"] + rf["review-feature.sh"] --> rev["feature-ISSUE-SLUG-review-NN.json and .md"] + tr["triage-review.sh"] --> tri["…-review-NN-triage.json and .md"] + tr --> gh["follow-up Issues for DEFER
comment with both reports"] + at["apply-triage.sh
runs verify.sh"] --> fixes["fixes for FIX_NOW"] + ff["finish-feature.sh
runs verify.sh"] --> commit["commit with review round
and a reference to the Issue"] + pr["push and PR
CI runs verify.sh"] --> prgh["pull request that closes the Issue"] + + classDef repo fill:#E1F5EE,stroke:#0F6E56,color:#085041 + classDef local fill:#F1EFE8,stroke:#5F5E5A,color:#444441 + classDef github fill:#FAECE7,stroke:#993C1D,color:#712B13 + class code,fixes,commit repo + class rev,tri local + class gh,prgh github + classDef step fill:#FFFFFF,stroke:#888780,color:#2C2C2A + class sf,rf,tr,at,ff,pr step +``` + +Code, tests, and fixes stay uncommitted until `finish-feature.sh`, so every +review covers the complete change. The lasting record of each review round is +the comment on the feature Issue and the follow-up Issues, each of which names +its source finding. + +## Reference + +Agent roles and models come from `.agents/agents.conf`; every agent script +accepts `--agent` and `--model` to override them for one run. Profiles are +described in `docs/development.md`: `write` sessions may change files in their +worktree, `read-only` sessions cannot and get no MCP servers or other remote +tools. + +### Steps + +| Step | Agent: role (profile) | Your decision | Writes | Committed | `verify.sh` | +|---|---|---|---|---|---| +| `start-planning.sh` | `project-grill` (write), then `project-planner` (write) | Approve the requirements | Description, requirements, architecture, roadmap, ADRs | Yes, with the planning PR | No | +| `review-planning.sh` | `planning-reviewer` (read-only) | None | Planning review JSON and report | No | No | +| `revise-planning.sh` | `project-planner` (read-only, then write) | Approve the decisions | Revision JSON and report; architecture, roadmap, ADRs | Documents yes, revision no | No | +| `finish-planning.sh` | None | Confirm earlier escalations; approve the planning | `docs/PLANNING_APPROVAL.md` | Yes | No | +| `create-feature-issue.sh` | None | Create the Issue | Feature Issue on GitHub | Not applicable | No | +| `start-feature.sh` | `implementer` (write) | None | Code and tests | Yes, by `finish-feature.sh` | No | +| `review-feature.sh` | `reviewer` (read-only) | None | Review JSON and report | No | No | +| `triage-review.sh` | `triage` (read-only) | Approve the triage | Triage JSON and report; follow-up Issues and a comment on GitHub | No | No | +| `apply-triage.sh` | `triage-implementer` (write) | Start the fixes | Fixes for `FIX_NOW` findings | Yes, by `finish-feature.sh` | Yes | +| `finish-feature.sh` | None | Edit and confirm the commit message | The commit | Yes | Yes | +| Push and PR | None | Merge after CI | Pull request | Not applicable | Yes, in CI | + +### Checks that stop a step + +| Step | Refuses when | +|---|---| +| `start-planning.sh` | The checkout is dirty (except an uncommitted description), the planning branch or worktree exists, or an agent leaves its file scope or commits | +| `review-planning.sh` | Not on a planning branch, a planning document is missing, or the requirements are not approved | +| `revise-planning.sh` | The planning review is stale, or the planner leaves its file scope, commits, or changes nothing for adopted findings | +| `finish-planning.sh` | No current review, a critical or major finding in the latest round, an undecided or unapplied finding, or an unresolved escalation | +| `create-feature-issue.sh` | The planning approval is missing or stale, the feature ID is unknown, duplicated, or empty, or the feature already has an Issue | +| `review-feature.sh` | Not on `feature/-*`, or nothing to review | +| `triage-review.sh` | The review is stale or invalid, or it is a planning review | +| `apply-triage.sh` | The triage is unapproved, invalid, or does not match its review, or the review is stale | +| `finish-feature.sh` | Verification fails, the latest review is stale or has a critical or major finding, a round with findings has no published triage, or `FIX_NOW` findings are left | + +### Helper scripts + +| Script | When to use it | +|---|---| +| `doctor.sh` | Once after creating a repository from the template, and whenever a tool may be missing | +| `verify.sh` | Any time; runs the checks in `scripts/verify.conf`, and is run by `apply-triage.sh`, `finish-feature.sh`, and CI | +| `check-review.sh ` | To see whether a review still matches the content it covers | +| `finish-planning.sh --check` | To see whether the planning approval still matches the planning documents | +| `triage-review.sh --publish ` | To repeat a failed publication of the review and triage reports | +| `update-issue-with-plan.sh ` | To link an optional feature plan in `.agents/plans/` to its Issue | +| `cleanup-worktree.sh ` | After a merge, from the primary checkout, to remove the worktree | diff --git a/scripts/start-planning.sh b/scripts/start-planning.sh index 9cc136e..81365ce 100755 --- a/scripts/start-planning.sh +++ b/scripts/start-planning.sh @@ -484,14 +484,9 @@ echo echo "Project bootstrap planning completed." echo "Planning worktree: $worktree" echo -echo "Review the planning artifacts, then run:" +echo "Next, in the planning worktree, review the planning with an independent agent:" echo " cd \"$worktree\"" -echo " ./scripts/verify.sh" -if [[ -n "$description_source" ]]; then - echo " git add $description_relative" -fi -echo " git add docs/PROJECT_REQUIREMENTS.md docs/architecture.md docs/roadmap.md docs/decisions" -echo " git commit -m \"Plan project bootstrap\"" -echo " git push -u origin \"$branch\"" +echo " ./scripts/review-planning.sh" echo -echo "Open a planning PR and merge it before creating feature Issues." +echo "Revise and review until the review passes, then approve with ./scripts/finish-planning.sh," +echo "which prints the commit and push steps for the planning PR." diff --git a/scripts/verify.conf b/scripts/verify.conf index 9776f38..0e0c109 100644 --- a/scripts/verify.conf +++ b/scripts/verify.conf @@ -24,6 +24,7 @@ template-structure: test -f AGENTS.md -a -f docs/architecture.md -a -f .agents/prompts/reviewer.md shell-syntax: for file in scripts/*.sh scripts/lib/*.sh tests/*.sh; do bash -n "$file" || exit 1; done +docs-scripts: for script in scripts/*.sh scripts/lib/*.sh; do grep -Fq "$(basename "$script")" docs/project-map.md || { echo "docs/project-map.md does not mention $script"; exit 1; }; done verify: ./tests/verify-test.sh doctor: ./tests/doctor-test.sh agent: ./tests/agent-test.sh