@pmelab/gtd 6.6.0 → 6.8.0

package/docs/examples/advanced-workflow.md

@@ -1,481 +0,0 @@
-# The `advanced` template: the full grilling → architecting → decompose → picking → review machine
-
-This walks through the **`advanced`** bundled workflow template — the fuller
-machine `gtd init advanced` scaffolds (`src/workflows/advanced.yaml`). The other
-bundled template, **`simple`** (`gtd init simple`), is the smaller 10-state
-machine walked through in
-[STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates) — including
-the two steering-file validation loops it carries over `.gtd/TODO.md` and
-`.gtd/REVIEW.md`, which this machine's own `grilling`/`reviewing` phases predate
-and don't validate. `gtd init advanced` writes the block below directly, so you
-normally don't paste it by hand; it's reproduced here as the annotated
-reference.
-
-Compared to the `simple` template, this machine adds:
-
-- **Two-phase human-in-the-loop planning with Q&A loops** — `grilling` ⇄
-  `grilling-answer` develops a product-level plan from `.gtd/TODO.md` one open
-  question at a time; `architecting` ⇄ `architecting-answer` repeats the same
-  shape for `.gtd/ARCHITECTURE.md`, the technical plan built on top of the
-  converged product plan.
-- **Task decomposition** — `decompose` turns the converged architecture into an
-  ordered set of self-contained task files under `.gtd/tasks/`.
-- **The deterministic `picking` queue arbiter** — a `script` state that feeds
-  tasks into `.gtd/NEXT.md` one at a time, with a per-task `building` →
-  `checking`/`fixing` loop, until the queue empties.
-- **Agent-prepared review** — `reviewing` has the agent write `.gtd/REVIEW.md`
-  summarizing the full cycle diff for a human to check before `await-review`
-  resolves an approval or feedback. `reviewing` also declares
-  `reviewEntry: true`, so `gtd review <commitish>` can start a review process
-  here directly over `<commitish>..HEAD` (e.g. a colleague's PR branch) — see
-  [STATES.md §11](../../STATES.md#11-the-review-checkout-window).
-- **A squash finale** — approval at `await-review` moves to `squashing` (the
-  agent authors `.gtd/COMMIT_MSG.md`) and then `done`, a `commit:` state that
-  squashes the whole cycle into one commit. The `simple` template drops this: it
-  rests at `idle` on approval instead and leaves every turn commit in history
-  for the human to squash (or not) however they choose.
-
-This example also carries `file:`/`mode:` annotations on every state that rests
-on a steering file (see the state table below and
-[docs/design/state-file-association.md](../design/state-file-association.md)) —
-it is the LSP-heavy flow, with `gtd lsp` dispatching document symbols/code
-actions/diagnostics off those declarations rather than a hardcoded basename:
-`grilling`/`grilling-answer` and `architecting`/`architecting-answer` are
-`qa`-format (`vars.todoFile`/`vars.architectureFile` respectively — a new
-`architectureFile` var joins `testCommand`), `reviewing`/`await-review` are
-`review`-format (`vars.reviewFile`), and `fixing`/`escalate` declare `file:`
-alone (`vars.feedbackFile` is plain text, no LSP format).
-
-Running `gtd init advanced` writes this whole definition into `.gtdrc.json`
-under a `workflow:` key for you. The block below is the same definition in YAML
-form (the source is `src/workflows/advanced.yaml`), nested under `workflow:` —
-paste it into your own `.gtdrc`/`.gtdrc.yaml` if you'd rather hand-author or
-tweak it. See [Configuration](../configuration.md) for the `.gtdrc` schema this
-slots into.
-
-## State table
-
-| State                 | Actor | Content | `on`                                                                              | Retry              | Model   | File                    | Mode     |
-| --------------------- | ----- | ------- | --------------------------------------------------------------------------------- | ------------------ | ------- | ----------------------- | -------- |
-| `idle` (initial)      | human | message | `* **` → `grilling`                                                               | —                  | —       | —                       | —        |
-| `grilling`            | agent | prompt  | `* **` → `grilling-answer`                                                        | —                  | `smart` | `vars.todoFile`         | `qa`     |
-| `grilling-answer`     | human | message | `C` → `architecting`; `* **` → `grilling`                                         | —                  | —       | `vars.todoFile`         | `qa`     |
-| `architecting`        | agent | prompt  | `* **` → `architecting-answer`                                                    | —                  | `smart` | `vars.architectureFile` | `qa`     |
-| `architecting-answer` | human | message | `C` → `decompose`; `* **` → `architecting`                                        | —                  | —       | `vars.architectureFile` | `qa`     |
-| `decompose`           | agent | prompt  | `* .gtd/tasks/**` → `picking`                                                     | —                  | `base`  | —                       | —        |
-| `picking`             | check | script  | `D .gtd/NEXT.md` → `reviewing`; `* .gtd/NEXT.md` → `building`; `C` → `reviewing`  | —                  | —       | —                       | —        |
-| `building`            | agent | prompt  | `* **` → `checking`                                                               | —                  | `base`  | —                       | —        |
-| `checking`            | check | script  | `A .gtd/FEEDBACK.md` → `fixing`; `M .gtd/FEEDBACK.md` → `fixing`; `C` → `picking` | —                  | —       | —                       | —        |
-| `fixing`              | agent | prompt  | `* **` → `checking`                                                               | max 3 → `escalate` | `base`  | `vars.feedbackFile`     | —        |
-| `escalate`            | human | message | `* **` → `checking`                                                               | —                  | —       | `vars.feedbackFile`     | —        |
-| `reviewing`           | agent | prompt  | `* .gtd/REVIEW.md` → `await-review`                                               | —                  | `smart` | `vars.reviewFile`       | `review` |
-| `await-review`        | human | message | `D .gtd/REVIEW.md` → `squashing`; `* **` → `grilling`                             | —                  | —       | `vars.reviewFile`       | `review` |
-| `squashing`           | agent | prompt  | `A .gtd/COMMIT_MSG.md` → `done`; `M .gtd/COMMIT_MSG.md` → `done`                  | —                  | `base`  | —                       | —        |
-| `done`                | —     | commit  | (final — squashes the whole cycle, message read from `.gtd/COMMIT_MSG.md`)        | —                  | —       |
-
-## The `.gtdrc` recipe
-
-````yaml
-workflow:
-  vars:
-    testCommand: npm test
-    todoFile: .gtd/TODO.md
-    architectureFile: .gtd/ARCHITECTURE.md
-    reviewFile: .gtd/REVIEW.md
-    feedbackFile: .gtd/FEEDBACK.md
-    # The two model tiers every agent state draws from — opaque harness hints,
-    # repointed here (or via a top-level .gtdrc `vars:` / `GTD_VAR_` override)
-    # to change every state on that tier at once.
-    plannerModel: smart
-    coderModel: base
-
-  states:
-    idle:
-      actor: human
-      initial: true
-      message: |
-        No active gtd cycle.
-
-        To start one: write `.gtd/TODO.md` with a short sketch of what you want
-        built — a few sentences is enough — then run `gtd step human`.
-      on:
-        "* **": grilling
-
-    grilling:
-      actor: agent
-      file: <%= it.vars.todoFile %>
-      mode: qa
-      # `model` is an opaque harness hint — gtd never interprets this string, it
-      # only passes it through to `gtd next --json`/`gtd status --json` so the
-      # driving loop can map it onto whatever models its agent harness provides.
-      # Every agent state draws its tier from a `vars` model entry (see `vars:`
-      # above): `plannerModel` (default "smart") for the one-shot planning/
-      # architecting/reviewing turns, `coderModel` (default "base") for the
-      # decompose/build/fix/squash turns.
-      model: <%= it.vars.plannerModel %>
-      prompt: |
-        You are an autonomous coding agent. `.gtd/` holds this workflow's own
-        state (plans, task specs, review records) — never create, edit, or
-        delete anything under `.gtd/` except `<%= it.vars.todoFile %>`, which
-        this prompt tells you to write.
-
-        `<%= it.vars.todoFile %>` holds the plan under development. Read it,
-        then develop it into a concrete, product-level plan in this one turn —
-        explore the codebase before asking anything, so every open question is
-        one the codebase genuinely cannot answer.
-
-        Scope: product and user-facing decisions only. Leave implementation
-        details (file/module structure, data models, tech-stack choices) for
-        the next phase (`.gtd/ARCHITECTURE.md`).
-
-        For every remaining open question, add it under a `## Open Questions`
-        heading near the top, one `### <question>` sub-heading each, its body
-        your suggested answer in plain prose (always suggest one — the human
-        accepts it by leaving it untouched, or overrides it by editing it). Omit
-        the section entirely once there are none.
-
-        If `.gtd/TODO.md` already carries a `## Open Questions` section from a
-        previous lap, the human has now responded to that whole batch: fold every
-        one of those questions into the plan — the human's edit where they gave
-        one, your own suggestion where they left it untouched (an untouched
-        suggestion IS acceptance) — and MOVE each resolved `### <question>` block
-        down into a `## Answered Questions` section at the bottom. Raise any
-        genuinely new questions under `## Open Questions` at the top.
-
-        Leave `.gtd/TODO.md` uncommitted and finish your turn — do not commit,
-        and do not run `gtd step agent` yourself; the harness does that.
-      on:
-        "* **": grilling-answer
-
-    grilling-answer:
-      actor: human
-      file: <%= it.vars.todoFile %>
-      mode: qa
-      message: |
-        `<%= it.vars.todoFile %>` holds the plan under development, with any
-        open questions under `## Open Questions` — each carrying a suggested
-        answer.
-
-        To answer a question, edit its body in place, then run
-        `gtd step human`; leave a suggestion untouched to accept it as-is. On the
-        next lap the agent folds every answered question into the plan and moves
-        it down to `## Answered Questions`.
-
-        To accept all suggested answers as-is and move on to technical
-        architecting, run `gtd step human` with no edits.
-      on:
-        "C": architecting
-        "* **": grilling
-
-    architecting:
-      actor: agent
-      file: <%= it.vars.architectureFile %>
-      mode: qa
-      model: <%= it.vars.plannerModel %>
-      prompt: |
-        You are an autonomous coding agent. `.gtd/` holds this workflow's own
-        state — never create, edit, or delete anything under `.gtd/` except
-        `<%= it.vars.architectureFile %>` and `<%= it.vars.todoFile %>`, which
-        this prompt tells you to write and delete respectively.
-
-        Read `<%= it.vars.todoFile %>` (the converged product plan) and
-        develop `<%= it.vars.architectureFile %>` from it in this one turn:
-        file/module structure, data models, library/tech-stack choices,
-        error-handling strategy — the *how*, building on the *what* already
-        settled. Do not re-open product-level decisions from
-        `<%= it.vars.todoFile %>`; treat them as settled.
-
-        For every remaining open question, add it under a `## Open Questions`
-        heading the same way as the grilling phase (one `### <question>`
-        sub-heading, its body your suggested answer in plain prose). Omit the
-        section once there are none. On a return lap, fold the whole answered
-        batch into the plan and move each resolved `### <question>` block down
-        into a `## Answered Questions` section at the bottom, exactly as grilling
-        does.
-
-        Once `<%= it.vars.architectureFile %>` is written, delete
-        `<%= it.vars.todoFile %>` — its content has been folded in and it must
-        not linger.
-
-        Leave everything uncommitted and finish your turn.
-      on:
-        "* **": architecting-answer
-
-    architecting-answer:
-      actor: human
-      file: <%= it.vars.architectureFile %>
-      mode: qa
-      message: |
-        `<%= it.vars.architectureFile %>` holds the technical plan under
-        development, with any open questions under `## Open Questions`.
-
-        To answer a question, edit its body in place, then run `gtd step human`;
-        leave a suggestion untouched to accept it as-is.
-
-        To accept all suggested answers as-is and move on to decomposing the
-        work, run `gtd step human` with no edits.
-      on:
-        "C": decompose
-        "* **": architecting
-
-    decompose:
-      actor: agent
-      model: <%= it.vars.coderModel %>
-      prompt: |
-        You are an autonomous coding agent. `.gtd/` holds this workflow's own
-        state — never create, edit, or delete anything under `.gtd/` except the
-        task-spec files this prompt tells you to write (under `.gtd/tasks/`),
-        and `.gtd/ARCHITECTURE.md`, which it tells you to delete.
-
-        Read `.gtd/ARCHITECTURE.md` (the converged technical plan) and
-        decompose it into an ordered set of self-contained task files under
-        `.gtd/tasks/` (e.g. `.gtd/tasks/01-short-name.md`,
-        `.gtd/tasks/02-short-name.md`, ...). Order them so the test suite can
-        pass again after each one lands; each file is self-contained
-        (description, acceptance criteria as `- [ ]` checkboxes, relevant
-        paths) since a building turn receives only that one file as context.
-
-        No task file may reference any other `.gtd/` file, or a requirement to
-        preserve/update workflow state — `.gtd/` is machine-managed and gets
-        cleaned up as the cycle proceeds.
-
-        Once the task files are written, delete `.gtd/ARCHITECTURE.md`. Leave
-        everything uncommitted and finish your turn.
-      on:
-        "* .gtd/tasks/**": picking
-
-    picking:
-      actor: check
-      script: |
-        #!/usr/bin/env bash
-        # gtd check turn (the queue arbiter) — the loop driver executes
-        # this verbatim, then steps the check actor. Mechanics only: take the
-        # first task file (by name) under .gtd/tasks/ into .gtd/NEXT.md, or
-        # remove .gtd/NEXT.md when the queue is empty. What NEXT.md's
-        # presence/absence MEANS (another task to build vs. the queue closing
-        # out to review) is decided by this state's own `on` rules at capture
-        # time — never here.
-        set +e
-        next=$(ls .gtd/tasks/*.md 2>/dev/null | head -n 1)
-        if [ -n "$next" ]; then
-          printf '%s' "$next" > .gtd/NEXT.md
-        else
-          rm -f .gtd/NEXT.md
-        fi
-      on:
-        "D .gtd/NEXT.md": reviewing
-        "* .gtd/NEXT.md": building
-        "C": reviewing
-
-    building:
-      actor: agent
-      model: <%= it.vars.coderModel %>
-      prompt: |
-        You are an autonomous coding agent. `.gtd/` holds this workflow's own
-        state — never create or edit anything under `.gtd/` except deleting the
-        one task file this prompt tells you to delete; never touch
-        `.gtd/NEXT.md` yourself — the `picking` state owns it.
-
-        The task file to implement is: <%~ it.read(".gtd/NEXT.md") %>
-
-        Read that file and implement EXACTLY the one task it describes — no
-        more, no less; leave every other task file under `.gtd/tasks/`
-        untouched. Use TDD discipline: one test, then the implementation that
-        passes it, then the next — never write all the tests first.
-
-        Delete the task file once its work is complete and verified. Leave
-        everything else uncommitted and finish your turn.
-      on:
-        "* **": checking
-
-    checking:
-      actor: check
-      script: |
-        #!/usr/bin/env bash
-        # gtd check turn — the loop driver executes this verbatim, then
-        # steps the check actor. Mechanics only: run the test suite and record a
-        # red run's output as .gtd/FEEDBACK.md. What that output MEANS (another
-        # fix round vs escalation) is decided by the workflow's own `on`/`retry`
-        # rules at capture time — never here.
-        #
-        # `it.vars.testCommand` defaults to "npm test" (this workflow's own
-        # `vars:` above) — override it with a top-level `.gtdrc`
-        # `vars: { testCommand: ... }` key, or a `GTD_VAR_testCommand`
-        # environment variable (highest precedence).
-        set +e
-        mkdir -p .gtd
-        <%~ it.vars.testCommand %> > .gtd/.check-output 2>&1
-        code=$?
-        if [ "$code" -ne 0 ]; then
-          if [ -s .gtd/.check-output ]; then
-            mv .gtd/.check-output .gtd/FEEDBACK.md
-          else
-            rm -f .gtd/.check-output
-            printf 'npm test failed with exit code %s and produced no output.' "$code" > .gtd/FEEDBACK.md
-          fi
-        else
-          rm -f .gtd/.check-output
-        fi
-      on:
-        "A .gtd/FEEDBACK.md": fixing
-        "M .gtd/FEEDBACK.md": fixing
-        "C": picking
-
-    fixing:
-      actor: agent
-      file: <%= it.vars.feedbackFile %>
-      model: <%= it.vars.coderModel %>
-      retry:
-        max: 3
-        otherwise: escalate
-      prompt: |
-        You are an autonomous coding agent. `.gtd/` holds this workflow's own
-        state — never create, edit, or delete anything under `.gtd/` except
-        `<%= it.vars.feedbackFile %>`, which this prompt tells you to address.
-
-        Read `<%= it.vars.feedbackFile %>` (the failing test output) and fix
-        the code so the suite passes. Keep the change focused — do not
-        refactor unrelated code. If the feedback is wrong, empty or delete
-        `<%= it.vars.feedbackFile %>` instead of "fixing" a non-issue; the
-        machine picks the dispute up either way.
-
-        Leave everything uncommitted and finish your turn — do not commit.
-      on:
-        "* **": checking
-
-    escalate:
-      actor: human
-      file: <%= it.vars.feedbackFile %>
-      message: |
-        The agent could not get the check to pass after repeated attempts.
-        `<%= it.vars.feedbackFile %>` holds the last failing output.
-
-        Investigate and fix it yourself (editing code and/or
-        `<%= it.vars.feedbackFile %>`), then run `gtd step human` to try the
-        check again.
-      on:
-        "* **": checking
-
-    reviewing:
-      actor: agent
-      file: <%= it.vars.reviewFile %>
-      mode: review
-      model: <%= it.vars.plannerModel %>
-      # A second way in: `gtd review <commitish>` (clean tree, resting at the
-      # initial state) enters here directly over <commitish>..HEAD — see
-      # STATES.md §11.
-      reviewEntry: true
-      prompt: |
-        You are an autonomous coding agent. `.gtd/` holds this workflow's own
-        state — never create, edit, or delete anything under `.gtd/` except
-        `<%= it.vars.reviewFile %>`, which this prompt tells you to write.
-
-        Write `<%= it.vars.reviewFile %>` to help a human review the cycle's
-        full diff (inlined below): group hunks semantically (same
-        feature/refactor/fix, even across files), and for each group write a
-        short heading, an explanation of what changed and why, and
-        `- [ ] ./path/to/file.ts#42` style file pointers (checkboxes are for
-        the human to tick, not you).
-
-        Leave `<%= it.vars.reviewFile %>` uncommitted and finish your turn.
-        <% if (it.processDiff.trim()) { %>
-
-        ## Full cycle diff
-
-        ```diff
-        <%~ it.processDiff %>
-        ```
-        <% } %>
-      on:
-        "* .gtd/REVIEW.md": await-review
-
-    await-review:
-      actor: human
-      file: <%= it.vars.reviewFile %>
-      mode: review
-      # Opens the review checkout window: HEAD/index are rewound to the cycle
-      # start so the whole diff shows as uncommitted changes in the editor
-      # (see STATES.md §11). Closes automatically once the cycle rests elsewhere.
-      reviewWindow: true
-      message: |
-        `<%= it.vars.reviewFile %>` holds the review record for the completed
-        cycle.
-
-        To approve: delete `<%= it.vars.reviewFile %>` and run
-        `gtd step human`.
-
-        To request changes: edit `<%= it.vars.reviewFile %>` (or the code)
-        with what's wrong — including just ticking its checkboxes — then run
-        `gtd step human`; this sends the cycle back through grilling with your
-        feedback as the new input.
-      on:
-        "D .gtd/REVIEW.md": squashing
-        "* **": grilling
-
-    squashing:
-      actor: agent
-      model: <%= it.vars.coderModel %>
-      prompt: |
-        You are an autonomous coding agent. The cycle is approved and done.
-        `.gtd/` holds this workflow's own state — never create, edit, or delete
-        anything under `.gtd/` except `.gtd/COMMIT_MSG.md`, which this prompt
-        tells you to write.
-
-        Write `.gtd/COMMIT_MSG.md` with ONE conventional-commits message for
-        the entire cycle (subject line `type(scope): subject`, imperative mood,
-        <= 72 characters; a body explaining the why, trade-offs, and key
-        decisions). Plain text, no markdown wrapper.
-
-        Leave `.gtd/COMMIT_MSG.md` uncommitted and finish your turn — entering
-        this file squashes the whole cycle into one commit using its content as
-        the message.
-        <% if (it.processDiff.trim()) { %>
-
-        ## Full cycle diff
-
-        ```diff
-        <%~ it.processDiff %>
-        ```
-        <% } %>
-      on:
-        "A .gtd/COMMIT_MSG.md": done
-        "M .gtd/COMMIT_MSG.md": done
-
-    done:
-      commit: |
-        <%~ it.read(".gtd/COMMIT_MSG.md") %>
-
-        Token cost: <%= it.processCost %>
-        <% it.processCostByModel.forEach(function(m){ %>
-        - <%= m.model %>: <%= m.cost %>
-        <% }) %>
-````
-
-The `done` commit appends a token-cost summary to the squashed message: if the
-loop driving this workflow passes `gtd step <actor> --cost=<n> --model=<name>`
-after each agent turn, `it.processCost` is the summed cost of the whole cycle
-(including the `squashing` step itself) and `it.processCostByModel` itemizes it
-per model — so the single squash commit records the feature's complete cost,
-broken down by which model spent what, even though the per-turn trailers are
-discarded with the turns they collapsed. Drop these lines if your driver doesn't
-track cost — `it.processCost` is `0` and `it.processCostByModel` empty then. See
-[Configuration: Token cost](../configuration.md#token-cost).
-
-A clean `gtd step human` at `grilling-answer`/`architecting-answer` (the `C`
-event) accepts the current phase's draft and moves on; any other pending change
-loops back for another round. `picking` is a `script` state whose only job is to
-inspect `.gtd/tasks/` (a tree property patterns can't see directly) and turn it
-into a diff patterns CAN see — see the walkthrough in
-[STATES.md §10](../../STATES.md#10-the-bundled-workflow-templates) (the version
-of that section frozen alongside this example) for the full state-by-state
-narrative, including the `on`-declaration-order subtlety at `picking` and the
-`fixing` retry-cap pooling caveat.
-
-## See also
-
-- [docs/design/work-packages.md](../design/work-packages.md) — the arbiter's
-  decision record: why the scripted `picking` state (Option A) was chosen over
-  the agent-encoded-verdict, tree-predicate-guard, and template-enumeration
-  alternatives, plus the process-per-task topology variant.
-- [STATES.md](../../STATES.md) — the pattern-machine model this recipe compiles
-  against (pattern grammar, resolution, retry, the squash lifecycle).