agent-templates 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-templates",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Catalog of multi-agent development architecture patterns - design write-ups plus drop-in scaffolding (agents, slash commands, workflows, templates).",
   "license": "MIT",
   "author": "Horace Hou",

package/patterns/three-agent-architect-builder-reviewer/README.md

@@ -152,6 +152,7 @@ Install steps and usage modes: [scaffold/INSTALL.md](scaffold/INSTALL.md). Front
 | 2026-07-17 | Gate 1 made concrete: `/start-milestone` = the human start signal → tickets auto-published as tracker issues (`publish-tickets.mjs`, adapted from fx-eye-tracking `create-issues.mjs`; `[<id>]` title prefix as dedupe key; smoke-tested dry-run/no-CLI/usage paths) → deterministic milestone runner (`run-milestone.js` Workflow script: stage order, reviewer freshness, bounce cap, merge policy in code). Added `templates/ticket.template.md` (adapted from fx ticket discipline). Recorded the Bash guard boundary as a known pitfall. Clarified `ultracode`: a session setting (`xhigh` + automatic workflow orchestration), not a model effort level — role efforts unchanged. | Maintainer direction (Horace Hou), 2026-07-17. fx-eye-tracking conventions read the same day (read-only). Workflow tool, `.claude/workflows/`, and `ultracode` semantics verified against live docs (workflows, claude-directory, model-config — record in `scaffold/INSTALL.md`). | Horace Hou (direction) / Claude Fable 5 (write-up) |
 | 2026-07-18 | **`/start-all` shipped** (catalog issue #20; maintainer-decided semantics: failed module blocks dependents, independent branches continue in `autonomous`, any non-CLEAR stops everything in `supervised`, no cost cap, resume via closed-issue filtering): deterministic DAG script (`milestone-dag.mjs`, ticket `blocked_by` as ground truth, cycles/dangling refs are hard errors) + `start-all` workflow composing `run-milestone` per module + `/start-all` command. 19 new E2E checks (DAG fixtures incl. cycle; module-policy scenarios via stubbed child workflows). Per-ticket stages unchanged. | Maintainer answers on issue #20, 2026-07-18. | Horace Hou (decisions) / Claude Fable 5 (build) |
 | 2026-07-18 | **First field bug fixed** (catalog issue #21, reported from Ruihang2017/Groundwork through the upstream feedback channel): CRLF-rewritten workflow scripts are rejected by the Workflow tool on Windows. Fix: repo-wide `.gitattributes` (`eol=lf`), working tree renormalized (67 files), `adopt.mjs` installs all text as LF, E2E `\r` guards added. Recorded as the pattern's first true `[internal]` pitfall observation. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-19 | **Pipeline tool surface explicitly pre-allowed** (catalog issue #30, maintainer direction): scaffold `settings.json` now enumerates allow rules for everything the stages legitimately run — deterministic scripts, git branch/commit/push/read set, `npm test`-family, `gh`/`glab` issue list/view/comment/edit|update|note/close/create — so a fully autonomous `/start-all` → deliver → nightly cycle triggers zero interactive approvals. Deliberately not pre-allowed (role discipline stays mechanical): `git merge`/`rebase`/`reset`/`clean`, `gh pr *`, and bare `git:*`/`gh:*`/`glab:*` wildcards — E2E asserts both directions so drift fails the gate. Risk accepted and recorded: `git push:*` includes force variants; `gh issue create:*` is broader than the publish-tickets discipline (nightly report issue needs it); prefix-deny of flags is structurally incomplete so not attempted. | Maintainer direction (Horace Hou), 2026-07-19. | Horace Hou (direction) / Claude Fable 5 (build) |
 | 2026-07-19 | **Delivery made deterministic** (catalog issue #26, field report: harness safety classifiers blocked the agent-run deliver stage 3/3 after journaled CLEARs): new `.claude/scripts/deliver-ticket.mjs` — clean-tree guard, `--no-ff` merge (idempotent on re-runs, conflicts abort clean), push, tracker close with post-close verification (`--issue` or `[<id>]` title-prefix lookup), deterministic DoD, `DELIVER-SUMMARY-JSON` contract; run-milestone's deliver agent reduced to executing that one command and relaying its summary; `settings.json` gained explicit allow rules for the three deterministic scripts. E2E: new suite-deliver (12 scenarios on real temp git repos + fake CLIs). The tracker close only happens after merge AND push actually landed — a closed issue is what resume filtering treats as delivered, so closing on a failed delivery would silently drop the ticket. One DoD item relocated: the post-merge test run executes deterministically when `testCmd` is supplied (workflow arg, forwarded as `--test-cmd`; `/start-all` passes it through) and otherwise stays with `/verify-delivery` — builder and reviewer both already ran tests on the branch. Per-ticket stages before deliver, and the model/effort table, unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18; fix direction proposed in the issue itself. | Horace Hou (report) / Claude Fable 5 (fix) |
 | 2026-07-19 | **Field bug #3 fixed** (catalog issue #27, reported from Ruihang2017/Groundwork2): `/start-all` step 3 never stated that `modules[].tickets` elements must be `{id, path, issue}` objects joined from two sources (DAG plan order + per-module `PUBLISH-SUMMARY-JSON`) — the DAG JSON alone emits bare id strings, which run-milestone's validator rejects. Command doc now names the exact shape and the join; `/start-milestone` already documented it. (The issue's other defect — stringified Workflow `args` — was already fixed under #23 / v0.2.1.) | Field report (Horace Hou via Groundwork2), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
 | 2026-07-18 | **Field bug #2 fixed** (catalog issue #23, same reporter channel): (a) #21's install-time LF fix did not survive target-side git checkouts — `adopt.mjs` now installs/appends a target-repo `.gitattributes` pinning `.claude/workflows/*.js` + `.claude/scripts/*.mjs` to `eol=lf` (marker-checked, append-once); (b) Workflow `args` can arrive JSON-stringified — all three workflow scripts gained the `typeof args === 'string' ? JSON.parse(args) : (args \|\| {})` shim. Both recorded as §4 pitfalls; E2E extended (stringified-args runner + start-all scenarios; `.gitattributes` install/append/idempotency). Per-ticket stages and model/effort table unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/settings.json

@@ -3,7 +3,43 @@
     "allow": [
       "Bash(node .claude/scripts/milestone-dag.mjs:*)",
       "Bash(node .claude/scripts/publish-tickets.mjs:*)",
-      "Bash(node .claude/scripts/deliver-ticket.mjs:*)"
+      "Bash(node .claude/scripts/deliver-ticket.mjs:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git switch:*)",
+      "Bash(git restore:*)",
+      "Bash(git add:*)",
+      "Bash(git rm:*)",
+      "Bash(git mv:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git fetch:*)",
+      "Bash(git pull:*)",
+      "Bash(git stash:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git remote get-url:*)",
+      "Bash(git merge-base:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run test:*)",
+      "Bash(node --test:*)",
+      "Bash(gh auth status)",
+      "Bash(gh issue list:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh issue comment:*)",
+      "Bash(gh issue edit:*)",
+      "Bash(gh issue close:*)",
+      "Bash(gh issue create:*)",
+      "Bash(glab auth status)",
+      "Bash(glab issue list:*)",
+      "Bash(glab issue view:*)",
+      "Bash(glab issue note:*)",
+      "Bash(glab issue update:*)",
+      "Bash(glab issue close:*)",
+      "Bash(glab issue create:*)"
     ]
   },
   "hooks": {

package/patterns/three-agent-architect-builder-reviewer/scaffold/INSTALL.md

@@ -11,7 +11,7 @@ From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-bu
 1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry and the `permissions.allow` list instead of overwriting.
 2. Install the catalog's **universal templates** (shared by all patterns — source of truth is the catalog root, not this scaffold): `templates/ticket.template.md` → the target repo's `templates/`; the platform half of `templates/tracker/` → `.github/` (ISSUE_TEMPLATE/ + PULL_REQUEST_TEMPLATE.md) or `.gitlab/` (issue_templates/ + merge_request_templates/). Then fill the PR/MR template's **Constraint check** section with the target repo's CLAUDE.md non-negotiables. Hand-written issues and pipeline PRs now share one format that triage can convert and reviewers can verify.
 3. The write-guard hook needs Node.js ≥ 18 on PATH. It denies main-session Edit/Write with a dispatch instruction; subagent writes pass. Override switch for human-approved out-of-pipeline edits: create `.claude/allow-main-writes`, delete it afterwards — and add that path to `.gitignore`.
-4. The tracker steps (`publish-tickets.mjs`, `deliver-ticket.mjs`, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides). Delivery (merge `--no-ff` + push + verified issue close + deterministic DoD) is `deliver-ticket.mjs` — never an agent improvising git/tracker writes; `settings.json` carries explicit allow rules for the three deterministic scripts so unattended runs do not stall waiting for interactive approval (catalog issue #26).
+4. The tracker steps (`publish-tickets.mjs`, `deliver-ticket.mjs`, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides). Delivery (merge `--no-ff` + push + verified issue close + deterministic DoD) is `deliver-ticket.mjs` — never an agent improvising git/tracker writes; `settings.json` carries explicit allow rules for the pipeline's whole tool surface (the three deterministic scripts, the enumerated git branch/commit/push set, `npm test`-family test commands, and the enumerated `gh`/`glab` issue commands) so unattended runs do not stall waiting for interactive approval (catalog issues #26, #30). Deliberately NOT pre-allowed: `git merge` / `rebase` / `reset` / `clean` and `gh pr *` — merging belongs to `deliver-ticket.mjs`. If your project's test command is not `npm test` / `npm run test` / `node --test`, add one more allow rule for it (e.g. `Bash(pytest:*)`).
 5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target).
 6. Ensure the docs layout the pipeline assumes exists: `docs/PRD.md`, `docs/prd/<module>/README.md` (the sub-PRD — `/start-milestone` hard-requires it), `docs/prd/<module>/tickets/` (author tickets from `templates/ticket.template.md`), `docs/adr/`, and an empty `docs/plans/`.
 7. Check the pattern entry's expiry (README metadata table). If expired, re-verify the model/effort table against current official docs before adopting — do not copy an expired recommendation into a new project.
@@ -25,7 +25,7 @@ From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-bu
 ## Nightly sweep (unattended)
 
 - **Entry:** `claude -p "/nightly-issues"` — slash commands expand in headless `-p` mode. `[official]`
-- **Permissions:** pre-approve exactly what the pipeline needs in the target repo's `.claude/settings.json` (`permissions.allow`, e.g. `Bash(git:*)`, `Bash(gh:*)` or `Bash(glab:*)`, `Bash(node:*)`, `Bash(npm:*)`), then run with `--permission-mode dontAsk` — the documented CI recommendation: pre-approved tools run, everything else is auto-denied instead of blocking. Subagents run in `acceptEdits` mode (their file edits are auto-approved). Avoid `bypassPermissions` outside isolated containers (documented warning). `[official]`
+- **Permissions:** the scaffold's `settings.json` already enumerates the pipeline's whole tool surface in `permissions.allow` (see step 4 — deterministic scripts, git branch/commit/push set, test commands, `gh`/`glab` issue commands; catalog issue #30). Do NOT widen it to bare wildcards like `Bash(git:*)` or `Bash(gh:*)` — that would re-allow the role-discipline-forbidden surface (`git merge`, `gh pr …`) the enumeration deliberately excludes. Add only your project-specific test-command rule, then run with `--permission-mode dontAsk` — the documented CI recommendation: pre-approved tools run, everything else is auto-denied instead of blocking. Subagents run in `acceptEdits` mode (their file edits are auto-approved). Avoid `bypassPermissions` outside isolated containers (documented warning). `[official]`
 - **Scheduling (Windows, primary):** Task Scheduler — runs whenever the machine is on at the trigger time:
 
   ```