@rasensio/aidlc-content 1.51.0 → 1.53.0

package/capabilities/claude-code.yaml

@@ -25,3 +25,10 @@ capabilities:
       the problem space, identify constraints, and outline the approach before
       committing to a structure. Exit plan mode only when you begin writing the
       artifact.
+  subagents:
+    phases: [implementation]
+    activation: >-
+      Sub-agents are available on this platform: the Agent tool starts an agent
+      with a fresh context of its own. When a tasks.md is being implemented, one
+      agent per task may be offered, as .aidlc/resources/rules/task-agents.md
+      describes.

package/docs/lifecycle.md

@@ -165,6 +165,18 @@ file says, and it prints the lines those parsers could not read. It writes nothi
 exits 0 whatever it finds, and no gate runs it — the implementation skill offers it before the first
 task, and acting on a gap is a person's call: fix the open artifact, or amend a completed one.
 
+**One agent per task** is the other way to run implementation, where the platform has sub-agents
+(Claude Code today). Each task goes to an agent that starts fresh, so task 8 does not inherit tasks 1–7;
+a second agent that edits nothing reviews it, and the box is ticked only after that review passes. The
+reviewer is handed one fixed `git diff` listing every test or spec file that existed before the task
+and was modified, deleted or renamed — and fails each one the task did not ask to change. The listing
+is mechanical on purpose: the agent that wrote the code also used to be the one deciding the tests that
+define done were fine, and a loosened assertion looks like a pass from inside. It is asked once per
+instance and off by default, because it roughly doubles the agents. Tasks that may run at the same time
+carry `(wave: <n>)` in `tasks.md`; a wave must be a run of consecutive tasks, and a bad marker keeps
+the task and warns rather than dropping it from gate coverage. The whole loop is one rule file,
+`.aidlc/resources/rules/task-agents.md`, so a session that runs its tasks itself never reads it.
+
 ## Where the code lives
 
 - `packages/cli/src/core` — templates, scope resolution, and the gate engine.
@@ -172,7 +184,7 @@ task, and acting on a gap is a person's call: fix the open artifact, or amend a
 - `packages/cli/src/state` — reading and writing the instance folders and `transitions.log`.
 - `packages/cli/src/traceability` — the acceptance-criteria parser and the test scanner behind the
   traceability gate. The AC grammar is closed on purpose; near-misses warn rather than vanish.
-- `packages/cli/src/tasks` — the `tasks.md` breakdown parser.
+- `packages/cli/src/tasks` — the `tasks.md` breakdown parser, including the `(wave: <n>)` marker.
 - `packages/cli/src/change` — the amendment grammar, the read-only impact walk, and the `reopen`
   transition. `parser.ts` is fence-aware and treats a wrapped bullet as one bullet, because the first
   version truncated a wrapped `Retires:` list to half its ids and dropped three fields silently.

package/docs/skills-and-platforms.md

@@ -57,6 +57,13 @@ per-platform features a phase can opt into — plan mode during ideation, for in
 and phase. Note the vocabulary collision: "capability" in that directory means a platform feature, not a
 subsystem of this repo. These pages are organised by **topic** for that reason.
 
+Claude Code's `subagents` entry, for the implementation phase, is a fact rather than a mode: it tells
+the agent sub-agents exist, which is the condition for offering one agent per task. It sits in the map
+rather than on the implementation skill because the map reaches every implementation-phase entry —
+including `aidlc-continue`, the route an unattended run takes into implementation. Add another platform
+only once it is confirmed to have sub-agents; a skill naming a tool the platform lacks is worse than
+not offering the mode.
+
 Those files also carry a **top-level `questions:` key**, outside the phase-keyed `capabilities:` map, and
 the reason it sits outside is not cosmetic. Capability resolution returns exactly one activation string
 per phase, and three platforms already occupy `requirements` and `design` — the two phases questions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/resources/rules/task-agents.md

@@ -0,0 +1,55 @@
+# The task-agents rule
+
+This file is the only statement of the rule. The implementation skill points here instead of restating it, so a session that runs its tasks itself carries none of this.
+
+**One agent per task** hands each task in `tasks.md` to a fresh agent, then has a second fresh agent review it. Task 8 gets the attention task 1 got, and the agent that wrote the code does not decide it is done. It costs at least twice the agents, so it is off unless chosen.
+
+## When it is offered
+
+Only for an instance with a task-bearing `tasks.md`, and only where the platform's entry for the skill says sub-agents are available — the line above the pointer in the skill file the platform loaded. Without it, every task runs in the session.
+
+## Choosing, once per instance
+
+Ask through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`), in `.aidlc/state/<instance>/implementation-questions.md`, before the first task:
+
+- **One session** — every task runs here. Cheapest; later tasks inherit earlier context.
+- **One agent per task** — each task in a fresh agent, checked by a reviewer that edits nothing. Roughly twice the tokens.
+
+Recommend **One session**, unless the prompt that started this session or the instance's `roadmap-item.md` asks for one agent per task — then recommend that. An `[Answer]:` already recorded is followed, never re-asked. Unattended, take the recommendation as the open-question default.
+
+## The loop, task by task
+
+Take open tasks in number order. For each one:
+
+1. **Record where it starts.** `BASE=$(git rev-parse HEAD)`.
+2. **Implement, in a fresh agent.** Give it only: the task line; the text of each criterion it cites, from `requirements.md`; the `design.md` sections it names; `.aidlc/context/style-guide.md`; the files it touches. Tell it:
+   - change no test file that already exists unless the task's own text says to — add new tests instead;
+   - do not edit `requirements.md` or `tasks.md`;
+   - do not commit and do not tick the checkbox;
+   - reply with the files it changed.
+3. **Review, in a second fresh agent that edits nothing.** First run `git add --intent-to-add .`, so files the implementer created show up in a diff without being staged. Then give the reviewer the same task line and criteria text, the output of `git diff $BASE`, and the output of this command, run by you:
+
+   ```
+   git diff --name-status --diff-filter=MDR $BASE -- '*test*' '*spec*' .aidlc/state/<instance>/requirements.md .aidlc/state/<instance>/tasks.md
+   ```
+
+   It lists every test or spec file, and the two files that define done, that existed at `BASE` and was modified, deleted or renamed. Adding a test is never a flag. Tell the reviewer:
+   - judge the diff against each cited criterion — met, or not and why;
+   - every listed file is flagged; it fails the task unless the task's own text calls for that change — a loosened assertion, a skipped test or a narrowed criterion is what this catches;
+   - reply `PASS` or `REJECT`, the reasons, and the flagged files with a verdict on each.
+4. **On `REJECT`**, a new implementing agent, given the reviewer's reasons, fixes what is on disk; review again from the same `BASE`. **After a second `REJECT`**, stop handing the task out: finish it in this session and review it once more, or defer it in place with a dated reason.
+5. **On `PASS`**, tick the task's checkbox and commit the task — one commit per task, on the instance branch.
+
+## Waves
+
+Adjacent open tasks carrying the same `(wave: <n>)` may be handed out at once, each to its own implementing agent, in this one checkout — never in separate worktrees. `BASE` is where the wave starts. Each task still gets its own reviewer, told which files its implementer reported, so it judges its own task within the shared diff; run the listing command once and give every reviewer its output. Commit task by task as each passes, staging only the files its implementer reported. A task that fails twice does not hold the others: they commit, and it is finished in the session afterwards.
+
+## The record
+
+Add a `## Task reviews` section to `code-complete.md`, one line per task:
+
+```
+- T4: PASS — attempts 1 — flagged: none
+- T5: REJECT → PASS — attempts 2 — flagged: packages/cli/test/parser.test.ts (task asks to update its fixture)
+- T6: finished in session — attempts 2 — flagged: none
+```

package/skills/00-overview.md

@@ -28,7 +28,7 @@ The AIDLC defines seven ordered phases. Not all apply to every task:
 1. **Ideation** — Problem exploration, goals, constraints
 2. **Requirements** — Acceptance criteria, user stories, scope
 3. **Design** — Architecture, interfaces, data flow
-4. **Implementation** — Code production following the design
+4. **Implementation** — Code following the design; agent per task: `.aidlc/resources/rules/task-agents.md`
 5. **Testing** — Verification against requirements
 6. **Deployment** — Release preparation and execution
 7. **Maintenance** — Monitoring, iteration, documentation updates
@@ -36,7 +36,7 @@ The AIDLC defines seven ordered phases. Not all apply to every task:
 ## Cycle Scopes
 
 | Scope | Starting Phase | Applicable Phases |
-|-------|---------------|-------------------|
+|---|---|---|
 | Full | Ideation | All seven phases |
 | Standard | Requirements | Requirements through Deployment |
 | Micro | Implementation | Implementation and Testing only |

package/skills/04-roadmap.md

@@ -145,6 +145,8 @@ For a `hold/` item, show whether it is **parked or declined**, with its reason,
 
 **`aidlc roadmap next`** is the deterministic answer to "what next?": the `backlog/` item with the lowest `priority` among those whose `depends_on` are all `done`, unranked items last, ties by file name (`--explain` shows the order and what was skipped and why; `--json` for scripts). It is read-only and never promotes — promoting stays a person's decision. `priority` is an ordinary extension field a project declares in `roadmap.item_fields`; a rank, where 1 is first. Where it is declared, `--explain` also lists every unranked backlog item, so one sitting last is visible rather than silently last. **`aidlc roadmap rank <item> <n>`** is the one way to change a rank: it puts the item at `n` and renumbers every ranked backlog item 1…k, so ranks stay unique and gap-free.
 
+**Dependency graphs.** `.aidlc/roadmap/graph-backlog.mmd` (backlog items and the `depends_on` edges between them) and `.aidlc/roadmap/graph-full.mmd` (every status, one subgraph each, every edge) are Mermaid files generated from the items — never edit them. Every CLI move rebuilds them. **After moving, adding or deleting an item by hand, run `aidlc roadmap graph`** and commit the graphs with the move; nothing else can see a hand move. When someone asks to see the dependencies, point them at these files rather than drawing a graph.
+
 The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
 
 A filename appearing in two status directories is an error: report it rather than guessing which one is current.

package/skills/30-design.md

@@ -58,10 +58,13 @@ transcript. See **The context rule** (`.aidlc/resources/rules/context.md`).
    - [ ] T<n>: <title> (AC-1, AC-2)
    - [x] T<n>: <title> (AC-3)
    - [>] T<n>: <title> (AC-4) (deferred YYYY-MM-DD: <reason>)
+   - [ ] T<n>: <title> (AC-5) (wave: 2)
    ```
 
    Number tasks sequentially (`T1`, `T2`, ...) — IDs are never renumbered or reused; a task overtaken by events is deferred with a reason, never deleted. Reference the acceptance criteria each task satisfies where any apply; chore or infrastructure tasks may legitimately have none (the implementation gate surfaces them as warnings, never failures).
 
+   **Mark tasks that can run at the same time with `(wave: <n>)`**, `<n>` a whole number from 1. Tasks sharing a wave may be handed to separate agents at once, so give two tasks the same wave only when they touch different files and neither needs the other's output. A wave is a run of consecutive tasks — T4, T5 and T6, never T4 and T6 with T5 between them; the parser warns on a split wave. A task with no wave runs alone, in number order. Leave waves out when nothing can run alongside anything else: they matter only when implementation runs one agent per task.
+
 ## Exit Criteria
 
 - `design.md` exists with architecture, interfaces, and at least one design decision with rationale

package/skills/40-implementation.md

@@ -28,6 +28,7 @@ Read only:
 - `requirements.md` — the acceptance criteria the next task claims
 - the always-read guidance layers named in `.aidlc/guidance/index.yaml` (see **The always-read rule** (`.aidlc/resources/rules/always-read.md`))
 - `.aidlc/context/style-guide.md`
+- `implementation-questions.md`, when it exists — whether tasks go to one agent each
 
 Then the source files that task touches. See **The context rule** (`.aidlc/resources/rules/context.md`).
 
@@ -44,6 +45,8 @@ Then the source files that task touches. See **The context rule** (`.aidlc/resou
 2. **Load guidance.** Read the always-read guidance layers from `.aidlc/guidance/index.yaml` — see **The always-read rule** (`.aidlc/resources/rules/always-read.md`) for which layers those are and when to reach for the full `lessons.md`. Apply their rules during implementation.
 3. **Check that the planning artifacts agree.** Before the first task, run `aidlc cross-check <instance>` and show the user the list. It reads `requirements.md`, `design.md` and `tasks.md` side by side and prints one line per gap — a criterion no task cites, a task citing no criterion, a criterion design never mentions — each naming both artifacts and the ID. It is a report: it writes nothing and never blocks, and acting on a gap is the user's call. A gap in `tasks.md` is fixed in place, since its phase is still open here; a gap in a completed `requirements.md` or `design.md` is fixed through an amendment (**Amending a Completed Phase**, in the requirements skill), never by editing it silently. Unattended (`AIDLC_UNATTENDED=1`): record the list in `code-complete.md` and carry on.
 4. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
+
+   **One agent per task.** Where the platform's entry for this skill says sub-agents are available and the instance has a task-bearing `tasks.md`, offer it before the first task — or follow the answer already recorded in `implementation-questions.md` — exactly as **The task-agents rule** (`.aidlc/resources/rules/task-agents.md`) says. Chosen, it replaces the task-by-task work above: each task goes to a fresh agent, a second agent reviews it, and the box is ticked only after that review passes. Not offered, or not chosen, run every task in this session as before.
 5. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
 6. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation (unattended, `AIDLC_UNATTENDED=1`: each is a hard stop except reverting this session's own changes, per `.aidlc/resources/rules/unattended.md`):
    - File deletions or destructive operations