taspinar · taspinar · Oct 2, 2026 · Oct 2, 2026
diff --git 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<br/>review ↔ revise"] --> approval["Planning<br/>approved"]
+  approval --> issue["Feature<br/>Issue"] --> feature["Feature<br/>review ↔ fix"] --> pr["Feature PR<br/>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 ../<repository>-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 ../<repository>-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/<issue>-<slug>.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 ../<repository>-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 ../<repository>-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
@@ -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
@@ -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`.