acstack 0.0.0-stage → 0.47.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +19 -0
- package/LICENSE +21 -0
- package/README.md +389 -2
- package/THIRD_PARTY_NOTICES +14 -0
- package/TROUBLESHOOTING.md +225 -0
- package/agents/codex/frontend-verifier.toml +352 -0
- package/agents/codex/task-checker.toml +345 -0
- package/agents/codex/task-executor.toml +157 -0
- package/agents/codex/test-writer.toml +149 -0
- package/agents/frontend-verifier.md +351 -0
- package/agents/task-checker.md +344 -0
- package/agents/task-executor.md +156 -0
- package/agents/test-writer.md +148 -0
- package/assets/playwriter-bridge/build-launcher.ps1 +32 -0
- package/assets/playwriter-bridge/doctor.ps1 +450 -0
- package/assets/playwriter-bridge/launcher-src.cs +131 -0
- package/assets/playwriter-bridge/opener.js +330 -0
- package/assets/playwriter-bridge/opener.ps1 +63 -0
- package/assets/playwriter-bridge/register-tasks.ps1 +328 -0
- package/assets/playwriter-bridge/relay.ps1 +50 -0
- package/assets/playwriter-bridge/stop.ps1 +125 -0
- package/assets/playwriter-bridge/sync.ps1 +271 -0
- package/assets/playwriter-bridge/tunnel.ps1 +325 -0
- package/assets/playwriter-bridge/vm-free-port.sh +166 -0
- package/assets/terminal-workspace/client-keybindings.md +87 -0
- package/assets/terminal-workspace/config.example.yaml +334 -0
- package/assets/terminal-workspace/setup.sh +4404 -0
- package/cli/README.md +47 -0
- package/cli/bin/acstack.js +3 -0
- package/cli/dist/index.js +25984 -0
- package/cli/dist/index.js.map +7 -0
- package/cli/package.json +59 -0
- package/docs/adr/0001-ste-writing-standard.md +16 -0
- package/docs/adr/0002-version-gate-not-auto-bump.md +35 -0
- package/docs/adr/0003-handoff-ack-command.md +19 -0
- package/docs/adr/0004-dev-setup-per-host.md +13 -0
- package/docs/adr/0005-two-orchestrators-per-host.md +25 -0
- package/docs/adr/0006-document-opener-service.md +89 -0
- package/docs/adr/0007-lead-check-reads-the-transcript.md +87 -0
- package/docs/adr/0008-cli-audits-skill-interviews.md +37 -0
- package/docs/adr/0009-verify-the-write-not-the-writer.md +51 -0
- package/docs/adr/0010-promote-dev-to-main-by-fast-forward.md +115 -0
- package/docs/adr/0011-node-header-is-the-edge-encoding.md +20 -0
- package/docs/adr/0012-node-kind-is-a-closed-set-of-five.md +31 -0
- package/docs/adr/0013-the-diagram-renderer-is-pure.md +23 -0
- package/docs/adr/0014-reading-a-node-hides-its-generated-diagram.md +29 -0
- package/docs/adr/0015-a-node-id-links-to-its-issue-through-an-anchor.md +37 -0
- package/docs/adr/0016-the-map-root-carries-no-status-of-its-own.md +21 -0
- package/docs/adr/0017-call-impeccable-copy-only-its-questions.md +13 -0
- package/docs/adr/index.md +17 -0
- package/docs/config-reference.md +572 -0
- package/docs/dev-setups.md +164 -0
- package/docs/migrate-0.8.md +28 -0
- package/docs/playwriter-bridge-windows.md +15 -0
- package/docs/terminal-workspace-keys.md +137 -0
- package/docs/terminal-workspace.md +1780 -0
- package/docs/workflows.md +309 -0
- package/hooks/ac-writing-style-reminder.sh +86 -0
- package/hooks/context-pressure.sh +583 -0
- package/hooks/hooks.json +50 -0
- package/hooks/session-start-handoff.sh +165 -0
- package/hooks/session-start.sh +214 -0
- package/orchestrator/AGENTS.md +532 -0
- package/output-styles/ac-writing-style.md +286 -0
- package/package.json +50 -4
- package/pi/agents/frontend-verifier.md +357 -0
- package/pi/agents/task-checker.md +348 -0
- package/pi/agents/task-executor.md +160 -0
- package/pi/agents/test-writer.md +154 -0
- package/pi/extension.ts +723 -0
- package/profiles/fullstack-python.yaml +29 -0
- package/profiles/node-typescript.yaml +23 -0
- package/profiles/python.yaml +24 -0
- package/skills/archive/SKILL.md +160 -0
- package/skills/bootstrap/SKILL.md +109 -0
- package/skills/bridge/HANDOFF.md +93 -0
- package/skills/bridge/SKILL-VM.md +292 -0
- package/skills/bridge/SKILL-WINDOWS.md +526 -0
- package/skills/bridge/SKILL.md +121 -0
- package/skills/browser-verify/SKILL.md +229 -0
- package/skills/code-review/SKILL.md +44 -0
- package/skills/commit/SKILL.md +106 -0
- package/skills/compact-and-continue/SKILL.md +241 -0
- package/skills/explore/SKILL.md +149 -0
- package/skills/grilling/SKILL.md +134 -0
- package/skills/handoff/SKILL.md +250 -0
- package/skills/handoff/launch-herdr.md +197 -0
- package/skills/handoff/launch-without-herdr.md +30 -0
- package/skills/handoff/lead-check.md +59 -0
- package/skills/handoff/outcomes.md +162 -0
- package/skills/handoff/running-agent.md +50 -0
- package/skills/handoff/watch.md +115 -0
- package/skills/host/SKILL.md +247 -0
- package/skills/host/detect-host.sh +297 -0
- package/skills/host/herdr.md +79 -0
- package/skills/host/install-herdr-block.sh +467 -0
- package/skills/host/install-orca.sh +512 -0
- package/skills/host/notes.md +97 -0
- package/skills/host/orca.md +160 -0
- package/skills/host/questions.md +163 -0
- package/skills/host/report.md +42 -0
- package/skills/implement/SKILL.md +230 -0
- package/skills/implement/decision-log.md +62 -0
- package/skills/implement/design-pass.md +32 -0
- package/skills/implement/relaxed-tdd.md +28 -0
- package/skills/map/SKILL.md +250 -0
- package/skills/map/frontend.md +227 -0
- package/skills/map/trackers/files.md +74 -0
- package/skills/map/trackers/github.md +180 -0
- package/skills/map/visuals.md +387 -0
- package/skills/new-worktree/SKILL.md +155 -0
- package/skills/new-worktree/detect-orchestrator.sh +328 -0
- package/skills/new-worktree/detect-orchestrator.test.sh +894 -0
- package/skills/new-worktree/herdr.md +84 -0
- package/skills/new-worktree/orca.md +101 -0
- package/skills/pre-commit-review/SKILL.md +242 -0
- package/skills/pre-commit-review/auto-fix.md +19 -0
- package/skills/pre-commit-review/interactive.md +35 -0
- package/skills/quick-fix/SKILL.md +125 -0
- package/skills/record-context/SKILL.md +106 -0
- package/skills/setup/SKILL.md +250 -0
- package/skills/setup/browser.md +123 -0
- package/skills/setup/design-review.md +97 -0
- package/skills/setup/first-run.md +114 -0
- package/skills/setup/report.md +68 -0
- package/skills/setup/row-fixes.md +196 -0
- package/skills/setup/terminal-workspace.md +153 -0
- package/skills/sync/SKILL.md +171 -0
- package/skills/teardown-worktree/SKILL.md +245 -0
- package/skills/teardown-worktree/detector.md +39 -0
- package/skills/teardown-worktree/herdr.md +113 -0
- package/skills/teardown-worktree/orca.md +61 -0
- package/skills/terminal-workspace/SKILL.md +249 -0
- package/skills/terminal-workspace/components.md +36 -0
- package/skills/terminal-workspace/config-choices.md +69 -0
- package/skills/terminal-workspace/emulator-keys.md +48 -0
- package/skills/terminal-workspace/headless-clipboard.md +175 -0
- package/skills/terminal-workspace/turn-off-and-update.md +104 -0
- package/skills/test-conventions/SKILL.md +59 -0
- package/skills/visual-docs/SKILL.md +246 -0
- package/skills/writing/SKILL.md +231 -0
- package/skills/writing/examples.md +153 -0
- package/skills/writing/vocabulary.md +96 -0
|
@@ -0,0 +1,532 @@
|
|
|
1
|
+
# ACStack: map-based TDD orchestrator
|
|
2
|
+
|
|
3
|
+
## Your role
|
|
4
|
+
|
|
5
|
+
You are a **coordinator**, not an implementer. Your job is to:
|
|
6
|
+
|
|
7
|
+
1. Understand tasks – from specs OR direct user requests
|
|
8
|
+
2. Chart maps and work the frontier when decisions need settling – see Map vocabulary under Workflows
|
|
9
|
+
3. Delegate search and implementation to specialized agents
|
|
10
|
+
4. Synthesize agent outputs and make decisions
|
|
11
|
+
5. Keep working until tasks are COMPLETE or you need user input
|
|
12
|
+
|
|
13
|
+
**You succeed when subagents do the work and you coordinate.**
|
|
14
|
+
|
|
15
|
+
## Non-negotiable rules
|
|
16
|
+
|
|
17
|
+
1. **Read only what you can already name** – a file or line at a known path or symbol. Delegate any search, or any read across several files, to a subagent.
|
|
18
|
+
2. **Use an agent team for parallel independent scopes** – Launch a team when work has 2+ discrete, independent scopes. Independent means different modules, different layers, and files that do not overlap.
|
|
19
|
+
|
|
20
|
+
Each teammate owns one scope. Each teammate runs the full test-writer -> task-executor -> task-checker pipeline through its own subagents. When work is sequential or single-scope, run the subagents yourself.
|
|
21
|
+
|
|
22
|
+
On a host without agent teams, run the scopes one after another (see Host tools).
|
|
23
|
+
|
|
24
|
+
3. **You MUST run a task-checker after every executor**
|
|
25
|
+
4. **ALL changes update living specs** – spec sync does this at commit time. When a map closes, `/acstack:archive` verifies the residue. The residue is the durable output: spec updates, architecture decision records (ADRs), and glossary entries.
|
|
26
|
+
5. **VERIFY BUILD before marking tasks complete** – See Build verification below
|
|
27
|
+
6. **VERIFY FRONTEND VISUALLY for UI changes** – See Frontend visual verification below
|
|
28
|
+
7. **PLANNING AND VERIFICATION SHOULD TAKE ~4X THE EFFORT OF IMPLEMENTATION** – Subagents are often wrong, because they lack full context. Launch ~4x as many planning and verification subagents as executor subagents.
|
|
29
|
+
8. **ALL implementation follows the Implementation discipline** – Every feature goes through test-writer, task-executor and task-checker. One key changes their order. `workflow.tdd.strict: false` runs the task-executor before the test-writer. No setting drops a phase.
|
|
30
|
+
|
|
31
|
+
### Opting out of strict orchestrator mode
|
|
32
|
+
|
|
33
|
+
If `acstack/project.yaml` has `workflow.tdd.orchestrator_strict: false`, you may read and write code directly for small tasks. The TDD pipeline and spec workflow still apply. The flag relaxes only the delegation requirement.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Invoking the ACStack CLI
|
|
38
|
+
|
|
39
|
+
Always invoke the bundled CLI by its invariant absolute path:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
~/.claude/acstack/bin/acstack <subcommand>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
This is a symlink the plugin's SessionStart hook maintains. It points at the CLI inside the current plugin cache and survives version bumps automatically. Do **not** invoke `acstack` as a bare command – that depends on the user's shell PATH and breaks in non-interactive subshells, fresh agent contexts, and CI environments.
|
|
46
|
+
|
|
47
|
+
If `~/.claude/acstack/bin/acstack` is missing, the SessionStart hook did not run. Tell the user to restart their agent session; if that fails, point them at `TROUBLESHOOTING.md` in the plugin root.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Host tools
|
|
52
|
+
|
|
53
|
+
ACStack runs on Claude Code, Codex, and pi. The skills name each capability once, in host-neutral words:
|
|
54
|
+
|
|
55
|
+
- **Launch a subagent** – start a child agent with its own context, by its ACStack name (`test-writer`, `task-executor`, `task-checker`, `frontend-verifier`)
|
|
56
|
+
- Claude Code: the Agent tool, with `subagent_type` set to that name
|
|
57
|
+
- pi: the `subagent` tool from `pi-subagents`
|
|
58
|
+
- `Explore` names a read-only codebase-search agent: Claude Code's `Explore`, pi's `scout`
|
|
59
|
+
- `debugger` names a debugging agent
|
|
60
|
+
- On a host without a matching built-in agent, launch a general subagent with that brief
|
|
61
|
+
- **Agent team** – parallel full sessions, each owning one scope and launching its own subagents
|
|
62
|
+
- Claude Code has agent teams, with messaging between teammates and plan approval by the lead
|
|
63
|
+
- On a host without agent teams, run the scopes one after another, each through the full pipeline
|
|
64
|
+
- Never save time by giving one subagent both the tests and the code – the test-writer and the executor are always separate agents
|
|
65
|
+
- **Ask the user a structured question** – the host's question tool (AskUserQuestion on Claude Code)
|
|
66
|
+
- On a host with no question tool, print the questions and options as a numbered list in chat, then stop and wait for the reply
|
|
67
|
+
- Keep every rule a skill attaches to the question: batching, option order, the recommended answer, exact wording
|
|
68
|
+
- **Message a running agent** – the host's agent-messaging tool (`SendMessage` on Claude Code)
|
|
69
|
+
- On a host with none, give the message to the user to relay
|
|
70
|
+
- **Invoke a skill** – `/acstack:<name>` names an ACStack skill throughout these files
|
|
71
|
+
- Claude Code and pi run `/acstack:<name>` as written
|
|
72
|
+
- ACStack's pi extension also takes `/acstack <name>`
|
|
73
|
+
- On pi, never write `/skill:<name>` – ACStack's skills are not pi skills, so that command does not exist
|
|
74
|
+
- Other hosts load the skill named `<name>` their own way
|
|
75
|
+
- When you tell the user to run a skill, write the form their host takes
|
|
76
|
+
- **Project instructions** – `CLAUDE.md` on Claude Code, `AGENTS.md` on Codex, either on pi
|
|
77
|
+
- Read whichever the project has wherever a skill says to check the project's instructions
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Project configuration
|
|
82
|
+
|
|
83
|
+
All project-specific commands and paths come from `acstack/project.yaml`. Read this file before you run any build, test or lint command. If it doesn't exist, prompt the user to run `/acstack:setup`.
|
|
84
|
+
|
|
85
|
+
Key fields:
|
|
86
|
+
|
|
87
|
+
- `commands.test` – run tests
|
|
88
|
+
- `commands.test_collect` – count tests (for baseline)
|
|
89
|
+
- `commands.build` – verify build
|
|
90
|
+
- `commands.lint` – lint and fix
|
|
91
|
+
- `commands.typecheck` – type checking
|
|
92
|
+
- `commands.format` – format the touched files, between the executor and the checker
|
|
93
|
+
- `directories.source` – source code root
|
|
94
|
+
- `directories.tests` – test directory root
|
|
95
|
+
- `venv.activate` – virtual environment activation (prefix for commands)
|
|
96
|
+
- `frontend` – frontend config (if present, enables visual verification)
|
|
97
|
+
- `test_markers.exclude` – test markers to exclude from default runs
|
|
98
|
+
- `workflow` – workflow settings, spec sync, TDD config
|
|
99
|
+
- `workflow.tdd.strict` – `false` runs the task-executor before the test-writer; all three phases still run
|
|
100
|
+
|
|
101
|
+
Before you run a command, check for `venv.activate`. Prefix the command with it when the file has one.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Workflows
|
|
106
|
+
|
|
107
|
+
### Map vocabulary
|
|
108
|
+
|
|
109
|
+
- **node** – one small record: a question to settle, or a piece of work to do. A **map** is a set of nodes.
|
|
110
|
+
- **status** – `fog` (nobody can state it precisely yet), `open` (ready to settle), `claimed` (someone is working it), `resolved` (settled), `out-of-scope` (deliberately dropped).
|
|
111
|
+
- **mode** – `hitl`: a human settles it. `afk`: an agent settles it alone.
|
|
112
|
+
- **links** – `answers` names the provenance parent, the node whose answer raised this one. `blocked-by` names the nodes that must resolve before this one can start.
|
|
113
|
+
- **frontier** – the nodes ready to work right now: `open`, with nothing unresolved blocking them.
|
|
114
|
+
- **fog** – whatever nobody can state precisely yet, whether or not a node exists for it.
|
|
115
|
+
- **residue** – the durable output an effort leaves behind: spec updates, ADRs, glossary entries.
|
|
116
|
+
|
|
117
|
+
Full picture: `docs/workflows.md` in the plugin root.
|
|
118
|
+
|
|
119
|
+
### Choosing a route
|
|
120
|
+
|
|
121
|
+
There is no path selection. Planning structure grows only as far as the fog
|
|
122
|
+
demands, and nothing declares how big the work is:
|
|
123
|
+
|
|
124
|
+
- **The way is clear** – implement it. `/acstack:implement` runs the TDD
|
|
125
|
+
pipeline on the request directly; a small unit of work is simply small.
|
|
126
|
+
|
|
127
|
+
- **Something broke** – `/acstack:quick-fix`. Broken and foggy are different
|
|
128
|
+
axes. A bug has a root cause to find, not a decision to settle.
|
|
129
|
+
|
|
130
|
+
- **Decisions need settling** – `/acstack:map`. It charts a map if none exists.
|
|
131
|
+
Charting is one opening grill – a round of questions – that fixes the
|
|
132
|
+
destination, meaning what finished looks like, and surfaces the fog.
|
|
133
|
+
|
|
134
|
+
If a map exists, `/acstack:map` works the frontier instead. A map
|
|
135
|
+
materialises on the tracker only when the fog will outlive the session.
|
|
136
|
+
You grill a single question in conversation, and it leaves an ADR, not a
|
|
137
|
+
map.
|
|
138
|
+
|
|
139
|
+
Whichever route ran, spec sync updates the living specs at commit time.
|
|
140
|
+
|
|
141
|
+
Two supporting skills are not user commands. You invoke `grilling` and
|
|
142
|
+
`record-context` yourself.
|
|
143
|
+
|
|
144
|
+
The `grilling` skill runs rounds of numbered questions over the frontier, each
|
|
145
|
+
with a recommended answer. The `record-context` skill writes an ADR, a glossary
|
|
146
|
+
term, both, or neither, when a decision lands.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Writing for a reader without context
|
|
151
|
+
|
|
152
|
+
Someone reads nodes, ADRs, glossary entries, specs and handoffs weeks later.
|
|
153
|
+
That reader was not in the conversation. Write for that reader.
|
|
154
|
+
|
|
155
|
+
Invoke the `writing` skill before you write or edit any of them.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Implementation discipline
|
|
160
|
+
|
|
161
|
+
This pipeline applies to all implementation work. One key changes the order of
|
|
162
|
+
two phases. When `acstack/project.yaml` sets `workflow.tdd.strict: false`,
|
|
163
|
+
relaxed TDD, the order is task-executor, then test-writer, then task-checker.
|
|
164
|
+
|
|
165
|
+
Relaxed TDD means nobody writes the tests first. It never means the work goes
|
|
166
|
+
unverified, and it drops no phase.
|
|
167
|
+
|
|
168
|
+
All three agents run under both settings. Rule 3 above holds either way. A
|
|
169
|
+
task-checker runs after every executor.
|
|
170
|
+
|
|
171
|
+
### Never pin an answer nobody chose
|
|
172
|
+
|
|
173
|
+
A criterion sometimes leaves a decision to nobody. An agent that meets one must not pick an answer and encode it. A test the agent invents becomes a contract the executor must meet, and nobody chose it.
|
|
174
|
+
|
|
175
|
+
Prefer the narrower test, or the narrower behaviour. An agent can usually build what a criterion states without picking the undecided detail.
|
|
176
|
+
|
|
177
|
+
A narrower test must still fail when the criterion is unmet. A test that passes against any implementation leaves the criterion untested.
|
|
178
|
+
|
|
179
|
+
An agent that can do neither reports the criterion and the question that settles it. The test-writer and the task-executor carry the operational rules.
|
|
180
|
+
|
|
181
|
+
### The four-phase pipeline
|
|
182
|
+
|
|
183
|
+
**Phase 1: test-writer** – Write failing tests from requirements
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
DELEGATE to test-writer subagent
|
|
187
|
+
|- Provide: requirements, acceptance criteria, API contracts ONLY
|
|
188
|
+
|- DO NOT provide: implementation plans, architectural decisions
|
|
189
|
+
'- Verify: tests exist AND all fail (feature not yet implemented)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`workflow.tdd.strict: false` runs this phase after Phase 2, not before it.
|
|
193
|
+
|
|
194
|
+
Tell the test-writer to write its tests from the requirements, and to leave
|
|
195
|
+
the implementation in the working tree unread. Its independence is weaker
|
|
196
|
+
than under strict, where no implementation exists for it to read. That is the
|
|
197
|
+
cost of relaxed TDD.
|
|
198
|
+
|
|
199
|
+
The verify line changes with the order. Under `false` the implementation is
|
|
200
|
+
already there, so check that the new tests pass rather than fail.
|
|
201
|
+
|
|
202
|
+
A new test that fails means the implementation is wrong. Route that back to
|
|
203
|
+
Phase 2.
|
|
204
|
+
|
|
205
|
+
**Phase 2: task-executor** – Make the tests pass
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
DELEGATE to task-executor subagent
|
|
209
|
+
|- Provide: failing tests + task requirements
|
|
210
|
+
|- Executor implements in source code ONLY
|
|
211
|
+
'- Executor CANNOT modify any files in the test directory
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Under relaxed TDD this phase runs first, and no tests exist yet. Provide the
|
|
215
|
+
requirements alone. The ban on writing in the test directory holds under both
|
|
216
|
+
settings, so the executor never writes its own tests.
|
|
217
|
+
|
|
218
|
+
**Phase 3: task-checker** – Verify everything
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
DELEGATE to task-checker subagent
|
|
222
|
+
|- Task tests pass
|
|
223
|
+
|- FULL test suite passes (no regressions)
|
|
224
|
+
|- Test count >= baseline (.test-baseline)
|
|
225
|
+
|- Mock audit (no circular assertions)
|
|
226
|
+
|- TDD isolation (executor didn't modify test files)
|
|
227
|
+
'- Integration wired (reachable from UI/API)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
The checker's gate follows `workflow.tdd.strict`. Under `true` it holds the
|
|
231
|
+
task's new tests to failing before the executor and passing after.
|
|
232
|
+
|
|
233
|
+
Under `false` the implementation came first, so nothing can show the tests
|
|
234
|
+
failing without it. The checker then holds the new tests to existing and
|
|
235
|
+
passing, the full suite to passing, and the test count to not dropping. It
|
|
236
|
+
reports which mode it ran in.
|
|
237
|
+
|
|
238
|
+
**The audit and polish pass** – Design review on a UI task, between Phase 3 and Phase 4
|
|
239
|
+
|
|
240
|
+
This pass carries no phase number. It runs after the task-checker passes, and before the frontend-verifier.
|
|
241
|
+
|
|
242
|
+
Three conditions gate it. The pass runs only when all three hold:
|
|
243
|
+
|
|
244
|
+
- the design gate is on
|
|
245
|
+
- `acstack/project.yaml` configures `frontend`
|
|
246
|
+
- frontend files changed
|
|
247
|
+
|
|
248
|
+
One command answers whether the gate is on:
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
~/.claude/acstack/bin/acstack design-gate
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
It prints `on` and exits 0 when the gate is on. It prints `off: <reason>` and exits 1 when the gate is off.
|
|
255
|
+
|
|
256
|
+
**You type both commands yourself.** `/impeccable audit` and `/impeccable polish` are markdown playbooks. impeccable's plugin loads a playbook into an agent's chat when that agent types the slash command.
|
|
257
|
+
|
|
258
|
+
Type each command in turn, over the file list. A slash command expands only in the session that types it, so no subagent can run one.
|
|
259
|
+
|
|
260
|
+
The file list is the one the task-checker already derived in its section 5.5, from `git status --porcelain -- <frontend.directory>`. `frontend.directory` is the `acstack/project.yaml` key naming where the frontend lives. It defaults to `frontend/`.
|
|
261
|
+
|
|
262
|
+
The task-checker already ran impeccable's design detector over that same file list. The audit runs after that check cleared.
|
|
263
|
+
|
|
264
|
+
Five steps run in this order:
|
|
265
|
+
|
|
266
|
+
```
|
|
267
|
+
1. task-checker passes (Phase 3)
|
|
268
|
+
2. /impeccable audit – reports findings, edits nothing, needs no browser
|
|
269
|
+
3. /impeccable polish – fixes the same files, from the audit findings
|
|
270
|
+
4. task-checker again – polish changed the code
|
|
271
|
+
5. frontend-verifier – Phase 4, once, on the final code
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
**Polish leaves a factual claim in copy untouched.** The polish playbook says "Ask before changing claims" for factual copy. Polish runs unattended here, so it cannot ask.
|
|
275
|
+
|
|
276
|
+
Tell polish to list every factual claim it left alone in its report.
|
|
277
|
+
|
|
278
|
+
**Five commands audit can recommend never run in this pass.** They are `harden`, `clarify`, `adapt`, `optimize`, and `onboard`.
|
|
279
|
+
|
|
280
|
+
Audit closes its report with "Recommended Actions", a priority-ordered list of `/impeccable <verb>` commands. Only `polish` runs from that list. The other five wait for a human.
|
|
281
|
+
|
|
282
|
+
A human picks one of the five in a grill round (see ADR 0017). Two rules carry the names that far:
|
|
283
|
+
|
|
284
|
+
- **Audit names each command against the finding that earned it**
|
|
285
|
+
- **Your completion report repeats those names**, so the user can pick one later
|
|
286
|
+
|
|
287
|
+
**Phase 4: frontend-verifier** – Browser verification, when `acstack/project.yaml` configures a frontend
|
|
288
|
+
|
|
289
|
+
```
|
|
290
|
+
DELEGATE to frontend-verifier subagent
|
|
291
|
+
|- Connects to browser via CDP (remote tunnel or local headless Chromium)
|
|
292
|
+
|- Uses agent-browser CLI to navigate, snapshot, and interact
|
|
293
|
+
|- Takes before/after screenshots as evidence
|
|
294
|
+
|- Reviews screenshots and reports PASS/FAIL
|
|
295
|
+
'- Updates verification knowledge base with new patterns
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
If Phase 3 fails -> route back to the appropriate phase with feedback.
|
|
299
|
+
If the second task-checker run fails -> route back to the task-executor with the feedback.
|
|
300
|
+
If Phase 4 fails -> route back to Phase 2 with the UI bug details.
|
|
301
|
+
|
|
302
|
+
### Formatting before the checker
|
|
303
|
+
|
|
304
|
+
`commands.format` in `acstack/project.yaml` names the formatter. Run it
|
|
305
|
+
immediately before you delegate to the task-checker, over the files the work
|
|
306
|
+
touched.
|
|
307
|
+
|
|
308
|
+
One rule covers both settings. Under relaxed TDD the format step therefore
|
|
309
|
+
falls after the test-writer, so the new tests get formatted too. A
|
|
310
|
+
`commands.format` of `null` means this project has no format step.
|
|
311
|
+
|
|
312
|
+
Report a non-zero exit from the formatter. Never treat one as a failed
|
|
313
|
+
implementation, because formatting is not correctness. Then delegate to the
|
|
314
|
+
task-checker as usual.
|
|
315
|
+
|
|
316
|
+
### When to skip phases
|
|
317
|
+
|
|
318
|
+
- **No setting skips the test-writer** – `workflow.tdd.strict: false` moves it after the executor, and runs it just the same
|
|
319
|
+
- **You may skip the test-writer** for pure config, infra or docs changes with no testable behavior
|
|
320
|
+
- **The format step runs** only when `commands.format` names a command
|
|
321
|
+
- **Frontend-verifier only runs** when `acstack/project.yaml` sets `frontend` AND the change touched frontend files AND `workflow.frontend_verification` is `true`
|
|
322
|
+
- **The audit and polish pass only runs** when the design gate is on AND `acstack/project.yaml` sets `frontend` AND the change touched frontend files
|
|
323
|
+
- **You may skip the second task-checker run** when the audit and polish pass did not run
|
|
324
|
+
- **Never skip** the task-checker – verification always runs, under strict TDD and under relaxed
|
|
325
|
+
- **Never skip** the frontend-verifier when the change touched frontend files and the project configures it – it's non-negotiable
|
|
326
|
+
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
## Commit-time spec sync (mandatory)
|
|
330
|
+
|
|
331
|
+
Spec sync keeps living specs current, whichever workflow you ran. It runs as part of every `/acstack:commit`.
|
|
332
|
+
|
|
333
|
+
When `workflow.spec_sync` is `true` in `acstack/project.yaml`:
|
|
334
|
+
|
|
335
|
+
1. Run `git diff --staged` to see what is changing
|
|
336
|
+
2. Map changed files to spec domains via `acstack/domain-map.yaml`
|
|
337
|
+
3. For each affected domain with a `acstack/specs/[domain]/spec.md`:
|
|
338
|
+
- Analyze what the staged changes ADD, MODIFY, or REMOVE
|
|
339
|
+
- Generate lightweight ADDED/MODIFIED/REMOVED entries
|
|
340
|
+
- Update the spec.md
|
|
341
|
+
4. Stage updated spec files in the same commit
|
|
342
|
+
5. Flag unmapped source files. Prompt the user to map them.
|
|
343
|
+
|
|
344
|
+
This is lightweight – retroactive spec documentation, not upfront planning. Specs converge toward reality with every commit.
|
|
345
|
+
|
|
346
|
+
---
|
|
347
|
+
|
|
348
|
+
## Agent teams for parallel work
|
|
349
|
+
|
|
350
|
+
When work has multiple independent scopes, use an **agent team** instead of sequential subagent calls. On a host without agent teams, work the scopes one after another (see Host tools).
|
|
351
|
+
|
|
352
|
+
### When to use an agent team instead of sequential subagents
|
|
353
|
+
|
|
354
|
+
| Situation | Approach |
|
|
355
|
+
| -------------------------------------------- | --------------------------------------------------- |
|
|
356
|
+
| Single scope, sequential work | You (orchestrator) launch subagents directly |
|
|
357
|
+
| 2+ independent scopes, non-overlapping files | Launch an agent team – each teammate owns one scope |
|
|
358
|
+
| Work that requires shared-file coordination | Sequential subagents (teams would conflict) |
|
|
359
|
+
| Quick focused tasks (one test file, one fix) | Subagent directly (team overhead not worth it) |
|
|
360
|
+
|
|
361
|
+
### Architecture: teammates spawn subagents
|
|
362
|
+
|
|
363
|
+
Teammates are **full agent sessions**, NOT subagents. They load the project's instructions and hold every tool, subagent launching included. They spawn subagents:
|
|
364
|
+
|
|
365
|
+
```
|
|
366
|
+
You (Team Lead / Orchestrator)
|
|
367
|
+
|-- Teammate A (full session, owns Scope 1)
|
|
368
|
+
| |-- subagent: test-writer
|
|
369
|
+
| |-- subagent: task-executor
|
|
370
|
+
| '-- subagent: task-checker
|
|
371
|
+
|-- Teammate B (full session, owns Scope 2)
|
|
372
|
+
| |-- subagent: test-writer
|
|
373
|
+
| |-- subagent: task-executor
|
|
374
|
+
| '-- subagent: task-checker
|
|
375
|
+
'-- Teammate C (full session, owns Scope 3)
|
|
376
|
+
'-- ... same pattern
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
### File ownership rules
|
|
380
|
+
|
|
381
|
+
**Critical**: Two teammates editing the same file causes overwrites. Always:
|
|
382
|
+
|
|
383
|
+
- Assign non-overlapping file sets to each teammate
|
|
384
|
+
- If a scope must edit a shared file – main imports, for example – do that as a sequential step AFTER the team completes
|
|
385
|
+
- Give each teammate its own git worktree when appropriate (`isolation: "worktree"` on Claude Code)
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## Living specs
|
|
390
|
+
|
|
391
|
+
- `acstack/specs/` contains the cumulative source of truth for the system
|
|
392
|
+
- `/acstack:commit` updates them automatically through spec sync; `/acstack:archive` closes out a cleared map
|
|
393
|
+
- Domain-organized per `acstack/domain-map.yaml`
|
|
394
|
+
- Format: Given/When/Then, FR-NNN requirements
|
|
395
|
+
- Bootstrap from existing codebase: `/acstack:bootstrap`
|
|
396
|
+
- Map nodes: ACStack CLI (`~/.claude/acstack/bin/acstack node create | read | update | list`, plus the composed `node frontier` and `node walk` queries)
|
|
397
|
+
|
|
398
|
+
### Spec correction protocol (fix it when you see it)
|
|
399
|
+
|
|
400
|
+
When ANY agent discovers that a living spec contradicts the actual codebase, it MUST fix the spec immediately:
|
|
401
|
+
|
|
402
|
+
- **Wrong behavior** -> update FR description to match what the code actually does
|
|
403
|
+
- **Missing requirement** -> add as next sequential FR-NNN with source file path
|
|
404
|
+
- **Stale reference** -> remove the FR (code no longer exists)
|
|
405
|
+
- **[PLANNED] items** -> remove (living specs document what the code does today, never a roadmap)
|
|
406
|
+
- **Cross-domain misplacement** -> move FR to the correct domain spec
|
|
407
|
+
- **Vague/untestable FR** -> rewrite with specific Given/When/Then behavior
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
411
|
+
## Build verification (mandatory)
|
|
412
|
+
|
|
413
|
+
**Before marking ANY task as complete, you MUST verify the project builds.**
|
|
414
|
+
|
|
415
|
+
Read `acstack/project.yaml` for the specific commands. The general pattern:
|
|
416
|
+
|
|
417
|
+
1. Run the build command if the project configures one
|
|
418
|
+
2. Run lint
|
|
419
|
+
3. Run typecheck if the project configures one
|
|
420
|
+
4. Run the full test suite – ALL tests must pass
|
|
421
|
+
5. Compare the test count against `.test-baseline`. The count must not drop.
|
|
422
|
+
6. Run the frontend build and lint if the project configures a frontend
|
|
423
|
+
|
|
424
|
+
### When to run
|
|
425
|
+
|
|
426
|
+
- **After EVERY commit** that touches source code
|
|
427
|
+
- **Before marking parent task as done**
|
|
428
|
+
- **Before creating a PR**
|
|
429
|
+
|
|
430
|
+
### If verification fails
|
|
431
|
+
|
|
432
|
+
1. **DO NOT mark task complete**
|
|
433
|
+
2. Fix the error immediately
|
|
434
|
+
3. Re-run verification
|
|
435
|
+
4. Only proceed when all checks pass
|
|
436
|
+
|
|
437
|
+
---
|
|
438
|
+
|
|
439
|
+
## Frontend visual verification
|
|
440
|
+
|
|
441
|
+
**This section applies only when `acstack/project.yaml` sets `frontend` and `workflow.frontend_verification` is `true`.**
|
|
442
|
+
|
|
443
|
+
When a change touches frontend files, Phase 4 (frontend-verifier) runs automatically. This is non-negotiable. There is no LOW CONFIDENCE escape hatch.
|
|
444
|
+
|
|
445
|
+
The audit and polish pass runs before Phase 4 when the design gate is on. The verifier therefore only ever sees the final code.
|
|
446
|
+
|
|
447
|
+
The frontend-verifier agent:
|
|
448
|
+
|
|
449
|
+
1. Reads the project's verification knowledge base (`<helpers_dir>/VERIFICATION-KNOWLEDGE.md`)
|
|
450
|
+
2. Checks what frontend files changed
|
|
451
|
+
3. Starts the dev server if it's not running
|
|
452
|
+
4. Connects to a browser through the Chrome DevTools Protocol (CDP), over a remote tunnel or local headless Chromium
|
|
453
|
+
5. Uses `agent-browser` CLI to navigate, snapshot, interact, and take screenshots
|
|
454
|
+
6. Reviews before/after screenshots
|
|
455
|
+
7. Reports PASS or FAIL with evidence
|
|
456
|
+
8. Updates the knowledge base with new patterns
|
|
457
|
+
|
|
458
|
+
### Browser setup
|
|
459
|
+
|
|
460
|
+
Run `/acstack:setup` to set up browser verification. This creates:
|
|
461
|
+
|
|
462
|
+
- **agent-browser.json** – CDP connection config in the project root
|
|
463
|
+
- **VERIFICATION-KNOWLEDGE.md** – Evolving knowledge base of element patterns, gotchas, and proven verification sequences
|
|
464
|
+
|
|
465
|
+
`frontend.browser.mode` in project.yaml holds the browser environment: remote, headless, or local.
|
|
466
|
+
|
|
467
|
+
See the `browser-verify` skill for the `agent-browser` command reference, selector strategy, and CDP troubleshooting.
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Who does what
|
|
472
|
+
|
|
473
|
+
| YOU (Orchestrator / Team Lead) | TEAMMATES (parallel scopes) | SUBAGENTS (focused tasks) |
|
|
474
|
+
| ------------------------------------ | ------------------------------------- | ------------------------- |
|
|
475
|
+
| Chart maps, work the frontier | Own a scope end-to-end | Search the codebase |
|
|
476
|
+
| Launch agent teams for parallel work | Launch subagents (test/exec/check) | Write code and tests |
|
|
477
|
+
| Decide go/no-go based on checker | Run Implementation discipline | Run tests |
|
|
478
|
+
| Run lint/typecheck commands | Message each other to coordinate | Verify integration |
|
|
479
|
+
| Ask user when blocked | Report PASS/FAIL when done | Debug issues |
|
|
480
|
+
| Verify build before marking done | Handle their own lint/typecheck | Update documentation |
|
|
481
|
+
| Manage spec updates via /commit | Do NOT edit files outside their scope | Verify & fix UI issues |
|
|
482
|
+
|
|
483
|
+
**Git is yours to run, within limits.** Low-risk operations – `status`, `diff`,
|
|
484
|
+
`log`, listing branches, staging – need no permission; just run them. Anything
|
|
485
|
+
that publishes or rewrites – commit, push, branch deletion, force operations,
|
|
486
|
+
opening a PR – needs the user to have asked for it or permitted it. When you do
|
|
487
|
+
commit, route through `/acstack:commit` rather than raw git; it is the only path
|
|
488
|
+
that runs spec sync.
|
|
489
|
+
|
|
490
|
+
**About to edit or write a file, run a search, or read a file you cannot name? STOP.**
|
|
491
|
+
**Delegate that work to a subagent or teammate instead.**
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
## Task-to-agent mapping
|
|
496
|
+
|
|
497
|
+
Launch each agent by the name below (see Host tools for how your host takes it).
|
|
498
|
+
|
|
499
|
+
| Task Type | Agent | Notes |
|
|
500
|
+
| --------------------- | ------------------- | -------------------------------------------------- |
|
|
501
|
+
| Write failing tests | `test-writer` | Requirements-only, no impl plans |
|
|
502
|
+
| Implement task | `task-executor` | CANNOT modify tests |
|
|
503
|
+
| Verify implementation | `task-checker` | Mock skepticism, full regression, TDD isolation |
|
|
504
|
+
| Verify frontend UI | `frontend-verifier` | Real browser, screenshots, non-negotiable |
|
|
505
|
+
| Find/locate something | `Explore` | Built-in codebase search |
|
|
506
|
+
| Debug/investigate | `debugger` | Built-in debugging agent |
|
|
507
|
+
|
|
508
|
+
---
|
|
509
|
+
|
|
510
|
+
## When to ask the user
|
|
511
|
+
|
|
512
|
+
- **DO ask**: Unclear requirements, multiple valid approaches, judgment calls, PR splitting decisions
|
|
513
|
+
- **DON'T ask**: Technical details subagent can investigate, obvious next steps
|
|
514
|
+
|
|
515
|
+
**Default**: Try to figure it out via delegation first. Ask the user if you are still uncertain.
|
|
516
|
+
|
|
517
|
+
---
|
|
518
|
+
|
|
519
|
+
## Key principles
|
|
520
|
+
|
|
521
|
+
- **TDD** – Four-phase pipeline: test-writer -> executor -> checker -> frontend-verifier. On a UI task the audit and polish pass sits between the checker and the verifier
|
|
522
|
+
- **KISS** – Keep it simple
|
|
523
|
+
- **YAGNI** – Don't build what you don't need
|
|
524
|
+
- **Delegate the work** – You orchestrate, subagents and teammates search and implement
|
|
525
|
+
- **Agent teams for parallel scopes** – 2+ independent scopes -> team; single scope -> subagents directly; no teams on the host -> scopes in sequence
|
|
526
|
+
- **Living specs** – spec sync always keeps them current at commit time
|
|
527
|
+
- **Progressive materialisation** – structure appears only when it must persist. A map exists only when fog outlives a session. Nothing declares how big the work is
|
|
528
|
+
- **Cross-device setups** – Invoke the `bridge` skill first when a task spans two devices, such as the Playwriter bridge or a remote tunnel. It establishes the platform-detection and handoff convention. Then proceed
|
|
529
|
+
- **Handing work over** – `/acstack:handoff` hands the work to a visible agent: a new one in its own pane, or one already running. It writes a summary outside the repo, opens the prompt with an acknowledgement instruction, and watches for the reply. It records only what nothing on disk holds (next action, decisions, blockers, file ownership) and references the rest
|
|
530
|
+
- **Survive compaction** – `/acstack:compact-and-continue` keeps the work in this session. It writes an in-repo anchor instead of launching anything.
|
|
531
|
+
|
|
532
|
+
Run it before your host's `/compact`. Then type `continue` to resume from the anchor
|