tracerkit 1.18.3 → 1.19.1

package/README.md

@@ -21,7 +21,16 @@ Named after the tracer-bullet technique from _The Pragmatic Programmer_: **Trace
 
 AI assistants work best with small, well-scoped tasks — not sprawling layers or flat task lists. TracerKit structures every feature as **tracer-bullet vertical slices**: each phase cuts through every layer (schema → service → API → UI → tests) and is demoable on its own. Integration problems surface early, not at the end.
 
-Three skills drive the workflow: **define** (`/tk:prd`), **plan** (`/tk:plan`), **verify** (`/tk:check`). The AI reads your specs directly, counts progress, and marks completed work done. Pure Markdown, zero runtime deps.
+Four skills drive the workflow: **define** (`/tk:prd`), **plan** (`/tk:plan`), **build** (`/tk:build`), **verify** (`/tk:check`). The AI reads your specs directly, counts progress, and marks completed work done. Pure Markdown, zero runtime deps.
+
+```
+DEFINE          PLAN           BUILD            VERIFY
+/tk:prd  ───▶  /tk:plan  ───▶  /tk:build  ───▶  /tk:check
+  │               │               │                 │
+  ▼               ▼               ▼                 ▼
+PRD doc       Phased plan    Implement phase    Pass/fail
+                              + feedback loops   + status
+```
 
 ## Get Started
 
@@ -111,7 +120,9 @@ AI:  Phase 1 — Theme visible end-to-end
      Written .tracerkit/plans/dark-mode-support.md
      Run `/tk:check dark-mode-support` when ready?
 
-You: # open the plan, implement each phase, write tests...
+You: /tk:build dark-mode-support
+AI:  Phase 1 — Theme visible end-to-end (3 remaining)
+     Implementing... all checks pass. Commit?
 
 You: /tk:check dark-mode-support
 AI:  Status: done | Total: 5/5
@@ -131,49 +142,28 @@ AI:  | Feature           | Status      | Age | Progress | Next
 
 See [Examples](docs/examples.md) for full walkthroughs.
 
-<details>
-<summary>GitHub Issues as storage backend</summary>
-
-Same skills, same workflow. Storage is configured per-project:
-
-```bash
-tracerkit config storage github         # set current project to use GitHub
-```
-
-PRDs and plans become GitHub Issues with `tk:prd` and `tk:plan` labels. On `/tk:check` pass, issues are closed with `completed` reason and any related PRs are linked automatically. Each project can use a different backend; local is the default. See [Configuration](docs/configuration.md) for details.
-
-To migrate existing artifacts between backends:
-
-```bash
-tracerkit migrate-storage           # local→github or github→local (auto-detected)
-```
-
-Direction is inferred from the current `storage` config. All artifacts are migrated, existing duplicates are skipped, and the config is flipped to the target backend. Source artifacts are left intact as backup.
-
-</details>
-
 ## Skills
 
-| Skill              | What it does                                           | Output                                                                                          |
-| ------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `/tk:prd <idea>`   | Interview → codebase scan → structured PRD             | `.tracerkit/prds/<slug>.md` or GitHub Issue                                                     |
-| `/tk:plan <slug>`  | PRD → phased vertical slices, each demoable on its own | `.tracerkit/plans/<slug>.md` or GitHub Issue                                                    |
-| `/tk:brief`        | Feature dashboard with progress and suggested focus    | Terminal only, no files                                                                         |
-| `/tk:check [slug]` | Verify done-when checkboxes against codebase and tests | Verdict block in plan. On `done`: status updated (local) or issues closed + PRs linked (GitHub) |
+| Skill              | What it does                                           | Output                                              |
+| ------------------ | ------------------------------------------------------ | --------------------------------------------------- |
+| `/tk:prd <idea>`   | Interview → codebase scan → structured PRD             | `.tracerkit/prds/<slug>.md`                         |
+| `/tk:plan <slug>`  | PRD → phased vertical slices, each demoable on its own | `.tracerkit/plans/<slug>.md`                        |
+| `/tk:build <slug>` | Implement next incomplete phase, run feedback loops    | Code changes + checked items in plan                |
+| `/tk:brief`        | Feature dashboard with progress and suggested focus    | Terminal only, no files                             |
+| `/tk:check [slug]` | Verify done-when checkboxes against codebase and tests | Verdict block in plan, status updated when all pass |
 
 ## Docs
 
-| Document                                         | Description                                                |
-| ------------------------------------------------ | ---------------------------------------------------------- |
-| [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios                    |
-| [CLI Reference](docs/cli-reference.md)           | Commands: init, update, config, migrate-storage, uninstall |
-| [Configuration](docs/configuration.md)           | Storage backends, GitHub options, custom paths             |
-| [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions         |
-| [Comparison](docs/comparison.md)                 | Compare TracerKit to Spec Kit, Kiro, and OpenSpec          |
-| [Cursor Setup](docs/cursor-setup.md)             | Use TracerKit skills in Cursor                             |
-| [Gemini CLI Setup](docs/gemini-cli-setup.md)     | Use TracerKit skills in Gemini CLI                         |
-| [Copilot Setup](docs/copilot-setup.md)           | Use TracerKit skills in GitHub Copilot                     |
-| [OpenCode Setup](docs/opencode-setup.md)         | Use TracerKit skills in OpenCode                           |
+| Document                                         | Description                                        |
+| ------------------------------------------------ | -------------------------------------------------- |
+| [Examples](docs/examples.md)                     | Walk through end-to-end usage scenarios            |
+| [CLI Reference](docs/cli-reference.md)           | Commands: init, update, uninstall                  |
+| [Metadata Lifecycle](docs/metadata-lifecycle.md) | Understand YAML frontmatter states and transitions |
+| [Comparison](docs/comparison.md)                 | Compare TracerKit to Spec Kit, Kiro, and OpenSpec  |
+| [Cursor Setup](docs/cursor-setup.md)             | Use TracerKit skills in Cursor                     |
+| [Gemini CLI Setup](docs/gemini-cli-setup.md)     | Use TracerKit skills in Gemini CLI                 |
+| [Copilot Setup](docs/copilot-setup.md)           | Use TracerKit skills in GitHub Copilot             |
+| [OpenCode Setup](docs/opencode-setup.md)         | Use TracerKit skills in OpenCode                   |
 
 ## Contributing
 

package/dist/bin.js

@@ -1,99 +1,44 @@
 #!/usr/bin/env node
-import { a as e, f as t, i as n, l as r, n as i, o as a, p as o, r as s, s as c, t as l, u } from "./uninstall-CNw_7khV.js";
-import { existsSync as d, readFileSync as f, statSync as p } from "node:fs";
-import { dirname as m, join as h, resolve as g } from "node:path";
-import { fileURLToPath as _ } from "node:url";
-import { homedir as v } from "node:os";
-//#region src/commands/config.ts
-function y(e, t) {
-	let [n, r] = t;
-	return n ? r ? S(e, n, r) : x(e, n) : b(e);
-}
-function b(e) {
-	let n = t(e), r = n.storage === "local" ? {
-		storage: n.storage,
-		paths: n.paths
-	} : n;
-	return JSON.stringify(r, null, 2).split("\n");
-}
-function x(e, n) {
-	let r = w(t(e), n);
-	return r === void 0 ? [`Unknown key: ${n}`] : typeof r == "object" ? [JSON.stringify(r, null, 2)] : [String(r)];
-}
-function S(e, t, n) {
-	o(e, T(t, n));
-	let r = [`✓ Set ${t} = ${n}`];
-	return C(e, r), r;
-}
-function C(n, r) {
-	u.some((e) => d(h(n, ".claude", "skills", e))) && (e(n, t(n)), r.push("✓ Skills re-rendered"));
-}
-function w(e, t) {
-	let n = t.split("."), r = e;
-	for (let e of n) {
-		if (typeof r != "object" || !r) return;
-		r = r[e];
-	}
-	return r;
-}
-function T(e, t) {
-	let n = e.split("."), r = {}, i = r;
-	for (let e = 0; e < n.length - 1; e++) {
-		let t = {};
-		i[n[e]] = t, i = t;
-	}
-	return i[n[n.length - 1]] = t, r;
-}
-//#endregion
+import { a as e, i as t, n, r, s as i, t as a } from "./uninstall-4Qp75twq.js";
+import { readFileSync as o } from "node:fs";
+import { dirname as s, resolve as c } from "node:path";
+import { fileURLToPath as l } from "node:url";
+import { homedir as u } from "node:os";
 //#region src/cli.ts
-var { version: E } = JSON.parse(f(g(m(_(import.meta.url)), "..", "package.json"), "utf8")), D = Math.max(...a.map((e) => `${e.name} ${e.args}`.length)), O = [
+var { version: d } = JSON.parse(o(c(s(l(import.meta.url)), "..", "package.json"), "utf8")), f = Math.max(...t.map((e) => `${e.name} ${e.args}`.length)), p = [
 	"Usage: tracerkit <command> [path]",
 	"",
 	"Commands:",
-	...a.map((e) => `  ${`${e.name} ${e.args}`.padEnd(D + 2)}${e.desc}`),
+	...t.map((e) => `  ${`${e.name} ${e.args}`.padEnd(f + 2)}${e.desc}`),
 	"",
 	"Options:",
 	"  --force           Overwrite modified files during update",
 	"  --help, -h        Show this help message",
 	"  --version, -v     Print version",
 	"",
-	"init/update/uninstall default to the home directory when no path is given.",
-	"config defaults to the current working directory."
+	"Defaults to the home directory when no path is given."
 ];
-function k(e) {
-	if (!e) return !1;
-	try {
-		return p(g(e)).isDirectory();
-	} catch {
-		return !1;
-	}
-}
-function A(e, t = v()) {
+function m(e, t = u()) {
 	let n = e.find((e) => !e.startsWith("-"));
-	return n ? g(n) : t;
-}
-function j(e) {
-	if (e.includes(r.help) || e.includes("-h")) return O;
-	if (e.includes(r.version) || e.includes("-v")) return [`tracerkit/${E}`];
-	let t = e[0], a = e.slice(1);
-	if (c.includes(t)) return [`"${t}" has been removed — skills handle this now.`, "Run `tracerkit update` to get the latest skills."];
-	switch (t) {
-		case "init": return s(A(a));
+	return n ? c(n) : t;
+}
+function h(t) {
+	if (t.includes(i.help) || t.includes("-h")) return p;
+	if (t.includes(i.version) || t.includes("-v")) return [`tracerkit/${d}`];
+	let o = t[0], s = t.slice(1);
+	if (e.includes(o)) return [`"${o}" has been removed — skills handle this now.`, "Run `tracerkit update` to get the latest skills."];
+	switch (o) {
+		case "init": return n(m(s));
 		case "update": {
-			let e = a.includes(r.force), t = n(A(a.filter((e) => e !== r.force)), { force: e });
+			let e = s.includes(i.force), t = r(m(s.filter((e) => e !== i.force)), { force: e });
 			return t.push("", "Updated to the latest TracerKit."), t.push("If using Claude Code, restart your session to load changes."), t;
 		}
-		case "config": {
-			let e = k(a[0]);
-			return y(e ? g(a[0]) : process.cwd(), e ? a.slice(1) : a);
-		}
-		case "uninstall": return l(A(a));
-		case "migrate-storage": return i(k(a[0]) ? g(a[0]) : process.cwd());
-		default: return O;
+		case "uninstall": return a(m(s));
+		default: return p;
 	}
 }
 //#endregion
 //#region src/bin.ts
-var M = j(process.argv.slice(2));
-for (let e of M) console.log(e);
+var g = h(process.argv.slice(2));
+for (let e of g) console.log(e);
 //#endregion

package/dist/index.js

@@ -1,2 +1,2 @@
-import { c as e, i as t, n, o as r, r as i, t as a, u as o } from "./uninstall-CNw_7khV.js";
-export { r as COMMANDS, e as DEPRECATED_SKILLS, o as SKILL_NAMES, i as init, n as migrateStorage, a as uninstall, t as update };
+import { c as e, i as t, n, o as r, r as i, t as a } from "./uninstall-4Qp75twq.js";
+export { t as COMMANDS, r as DEPRECATED_SKILLS, e as SKILL_NAMES, n as init, a as uninstall, i as update };

package/dist/uninstall-4Qp75twq.js

@@ -0,0 +1,130 @@
+import { existsSync as e, mkdirSync as t, readFileSync as n, readdirSync as r, rmSync as i, writeFileSync as a } from "node:fs";
+import { dirname as o, join as s } from "node:path";
+import { createHash as c } from "node:crypto";
+import { fileURLToPath as l } from "node:url";
+var u = [
+	"tk:brief",
+	"tk:prd",
+	"tk:plan",
+	"tk:build",
+	"tk:check"
+], d = ["tk:verify"], f = {
+	force: "--force",
+	help: "--help",
+	version: "--version"
+}, p = [
+	"brief",
+	"progress",
+	"archive",
+	"config",
+	"migrate-storage"
+], m = [
+	{
+		name: "init",
+		args: "[path]",
+		desc: "Install skills to ~/.claude/skills/ (or [path] if given)"
+	},
+	{
+		name: "update",
+		args: "[path]",
+		desc: "Refresh unchanged files from latest version, skip modified"
+	},
+	{
+		name: "uninstall",
+		args: "[path]",
+		desc: "Remove TracerKit skill directories, keep .tracerkit/ artifacts"
+	}
+], h = s(o(l(import.meta.url)), "..", "skills");
+function g(e, t = "") {
+	let n = r(e, { withFileTypes: !0 }), i = [];
+	for (let r of n) {
+		let n = t ? `${t}/${r.name}` : r.name;
+		r.isDirectory() ? i.push(...g(s(e, r.name), n)) : i.push(n);
+	}
+	return i.sort();
+}
+function _(e) {
+	return `.claude/skills/tk:${e}`;
+}
+function v(e) {
+	return e.slice(18);
+}
+function y(e, r) {
+	let i = r ?? g(h).map(_);
+	for (let r of i) {
+		let i = s(h, v(r)), c = s(e, r);
+		t(o(c), { recursive: !0 }), a(c, n(i, "utf8"));
+	}
+	return { copied: i };
+}
+function b(e) {
+	return c("sha256").update(e).digest("hex");
+}
+function x(t) {
+	let r = g(h).map(_), i = [], a = [], o = [];
+	for (let c of r) {
+		let r = s(t, c);
+		if (!e(r)) o.push(c);
+		else {
+			let e = n(s(h, v(c)), "utf8");
+			b(Buffer.from(e)) === b(n(r)) ? i.push(c) : a.push(c);
+		}
+	}
+	return {
+		unchanged: i,
+		modified: a,
+		missing: o
+	};
+}
+//#endregion
+//#region src/commands/update.ts
+function S(t, n) {
+	if (!u.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — run `tracerkit init` first");
+	let { unchanged: r, modified: a, missing: o } = x(t), c = [];
+	for (let n of d) {
+		let r = s(t, ".claude", "skills", n);
+		e(r) && (i(r, {
+			recursive: !0,
+			force: !0
+		}), c.push(`✗ .claude/skills/${n}/ removed (deprecated)`));
+	}
+	let l = n?.force ?? !1, f = [
+		...r,
+		...o,
+		...l ? a : []
+	];
+	if (f.length > 0) {
+		y(t, f);
+		for (let e of r) c.push(`✓ ${e}`);
+		for (let e of o) c.push(`✓ ${e} (added)`);
+		if (l) for (let e of a) c.push(`✓ ${e} (replaced)`);
+	}
+	if (!l && a.length > 0) {
+		for (let e of a) c.push(`⚠ ${e} (skipped — modified)`);
+		c.push("", "Run `tracerkit update --force` to replace modified files with latest versions.");
+	}
+	return c;
+}
+//#endregion
+//#region src/commands/init.ts
+function C(t) {
+	if (u.some((n) => e(s(t, ".claude", "skills", n)))) return S(t, { force: !1 });
+	let { copied: n } = y(t);
+	return n.map((e) => `✓ ${e}`);
+}
+//#endregion
+//#region src/commands/uninstall.ts
+function w(t) {
+	if (!u.some((n) => e(s(t, ".claude", "skills", n)))) throw Error("TracerKit not initialized — nothing to uninstall");
+	let n = [];
+	for (let r of u) {
+		let a = s(t, ".claude", "skills", r);
+		e(a) && (i(a, {
+			recursive: !0,
+			force: !0
+		}), n.push(`✗ .claude/skills/${r}/ removed`));
+	}
+	return n;
+}
+//#endregion
+export { p as a, u as c, m as i, C as n, d as o, S as r, f as s, w as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tracerkit",
-  "version": "1.18.3",
-  "description": "Spec-driven workflow for AI coding agents — PRD → plan → verify. Pure Markdown skills, zero runtime deps.",
+  "version": "1.19.1",
+  "description": "Spec-driven workflow for AI coding agents — PRD → plan → build → verify. Pure Markdown skills, zero runtime deps.",
   "license": "MIT",
   "author": {
     "name": "helderberto",

package/skills/brief/SKILL.md

@@ -1,60 +1,27 @@
 ---
-description: Session briefing — shows active features, progress, and suggested focus. Use at the start of a session to orient.
+description: Session briefing — shows active features, progress, and suggested focus. Use at the start of a session, when asking what to work on, or when checking active features.
 ---
 
-**Config**: read `.tracerkit/config.json` (default: `local`). Follow matching `<!-- if:local/github -->` blocks.
-
 # Session Briefing
 
 Overview of active features, progress, and suggested focus.
 
 ## Pre-loaded context
 
-<!-- if:local -->
-
 - Available PRDs: !`ls .tracerkit/prds/*.md 2>/dev/null || echo "(none)"`
-  <!-- end:local -->
-  <!-- if:github -->
-- Available PRDs: list open GitHub Issues with label `{{github.labels.prd}}`
-<!-- end:github -->
 
 ## Algorithm
 
 ### 1. Discover features
 
-<!-- if:local -->
-
 For each `.md` file in `.tracerkit/prds/`: parse frontmatter, extract `status` and `created`. Skip `status: done`. Slug = filename without `.md`.
 
-   <!-- end:local -->
-   <!-- if:github -->
-
-List open GitHub Issues with label `{{github.labels.prd}}`:
-
-1. For each issue, parse the `<!-- tk:metadata -->` comment in the body
-2. Extract `status` and `created` fields from the metadata
-3. Also check labels: `tk:created`, `tk:in-progress`
-4. Skip issues with `tk:done` label
-5. The slug is extracted from the title: `[{{github.labels.prd}}] <slug>: ...`
-<!-- end:github -->
-
 ### 2. Count progress from plans
 
-<!-- if:local -->
-
 For each slug with a plan at `.tracerkit/plans/<slug>.md`:
 
 Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Sum → `checked/total`. First unchecked item → "Next" (strip trailing `[tag]`). No plan → `—`.
 
-<!-- end:local -->
-<!-- if:github -->
-
-For each slug, find plan issue with label `{{github.labels.plan}}` and matching title. If found:
-
-Count `- [x]` and `- [ ]` lines under each `## Phase N` heading. Sum → `checked/total`. First unchecked item → "Next" (strip trailing `[tag]`). No plan → `—`.
-
-<!-- end:github -->
-
 ### 3. Build the table
 
 Sort by `created` ascending (no-date last). Age from `created`:
@@ -89,13 +56,8 @@ Append below the table:
 
 ### 5. Offer next steps
 
-<!-- if:local -->
-
-Options: continue focused feature (read plan at `.tracerkit/plans/<slug>.md`), `/tk:prd` for new feature, `/tk:check <slug>` for progress.
-
-<!-- end:local -->
-<!-- if:github -->
-
-Options: continue focused feature (read plan issue), `/tk:prd` for new feature, `/tk:check <slug>` for progress.
+Present options and wait for the user's choice:
 
-<!-- end:github -->
+1. Continue focused feature — read plan at `.tracerkit/plans/<slug>.md` (Recommended)
+2. Start new feature — `/tk:prd`
+3. Check progress — `/tk:check <slug>`

package/skills/build/SKILL.md

@@ -0,0 +1,164 @@
+---
+description: Implement one phase of a plan. Reads plan, finds next incomplete phase, implements it, runs feedback loops, marks checkboxes, offers commit. One phase per invocation. Use when the user wants to implement, code, build, or work on the next phase of a plan.
+argument-hint: '[slug]'
+---
+
+# Build Phase
+
+Implement the next incomplete phase of a plan — one phase per invocation.
+
+**Context window**: recommend `/clear` before starting to maximize token budget.
+
+**Interactive prompts**: present options as a numbered list and wait for the user's choice.
+
+## Pre-loaded context
+
+- Available plans: !`ls .tracerkit/plans/*.md 2>/dev/null || echo "(none)"`
+
+## Input
+
+The argument (if provided) is: $ARGUMENTS
+
+Use argument as `<slug>`. If empty, list plans as numbered options and wait for the user's choice.
+
+Accepts slug or `@file` reference:
+
+```
+/tk:build dark-mode-support
+/tk:build @.tracerkit/plans/dark-mode-support.md
+```
+
+If argument starts with `@`, treat it as a file path — read that file directly as the plan.
+
+## Workflow
+
+### 1. Load the plan
+
+Read `.tracerkit/plans/<slug>.md`. If missing, list plans as numbered options and wait for the user's choice.
+
+### 2. Find the next incomplete phase
+
+Scan the plan for `## Phase N` headings. For each phase, count `- [ ]` and `- [x]` checkboxes.
+
+The **next incomplete phase** is the first phase that has at least one unchecked `- [ ]` item.
+
+If all phases are complete (zero unchecked items across all phases):
+
+> All phases complete. Run `/tk:check <slug>` to verify.
+
+Stop here.
+
+### 3. Present the phase
+
+Show the phase title and its unchecked items:
+
+```
+Phase N — <title> (M remaining)
+- [ ] First unchecked item
+- [ ] Second unchecked item
+```
+
+### 4. Offer a feature branch
+
+If on the default branch (main/master), ask:
+
+> Create branch `feat/<slug>`?
+>
+> 1. Yes, create branch (Recommended)
+> 2. No, stay on current branch
+
+If accepted, create and switch to the branch.
+
+If already on a feature branch, skip this step.
+
+### 5. Implement the phase
+
+Work through each unchecked item in order. For each item:
+
+1. Read the plan's architectural decisions and the current item's context
+2. Explore relevant code to understand existing patterns and conventions
+3. Implement the change — follow the project's conventions (CLAUDE.md, linter config, test setup)
+4. Write tests alongside implementation (follow the project's existing test patterns)
+
+**Do not** impose coding rules, style, or conventions. Follow what the project already uses.
+
+**Do not** implement items from other phases. Stay within the current phase boundary.
+
+### 6. Run feedback loops
+
+After implementing the phase, detect and run available project scripts. Check `package.json` for these scripts (run only what exists):
+
+| Script pattern                     | Purpose       |
+| ---------------------------------- | ------------- |
+| `typecheck`, `tsc`, `type-check`   | Type checking |
+| `test`, `vitest`, `jest`           | Tests         |
+| `lint`, `eslint`                   | Linting       |
+| `format:check`, `prettier --check` | Formatting    |
+
+Run each detected script. If any fails:
+
+1. Read the error output
+2. Fix the issue
+3. Re-run the failing script
+4. Repeat until all pass (max 3 attempts per script)
+
+If a script still fails after 3 attempts, treat it as a **blocker** — pause and ask the user for help:
+
+> **Blocker**: `<script>` fails after 3 attempts.
+> Last error: `<error summary>`
+>
+> How to proceed?
+>
+> 1. I'll fix it — pause and wait
+> 2. Skip this check and continue
+> 3. Abort this phase
+
+Wait for the user's response before continuing.
+
+### 7. Mark checkboxes
+
+After all feedback loops pass, for each completed item change `- [ ]` → `- [x]` in `.tracerkit/plans/<slug>.md`.
+
+### 8. Offer commit
+
+Present the changes and ask:
+
+> Phase N complete — all checks pass. Commit?
+>
+> 1. Yes, commit
+> 2. No, I'll review first
+
+If the user chooses to commit:
+
+1. Stage the implementation files (not `.tracerkit/` artifacts unless the project dogfoods TracerKit)
+2. Create a commit with a message following the project's commit conventions
+3. Confirm: "Committed. Run `/tk:build <slug>` for Phase N+1, or `/tk:check <slug>` to verify."
+
+If the user chooses to review:
+
+> Ready for review. Run `/tk:build <slug>` again when ready to continue.
+
+### 9. Blockers during implementation
+
+If implementation requires something the agent cannot provide (API key, external service, manual setup, design decision):
+
+> **Blocker**: <description of what's needed>
+>
+> How to proceed?
+>
+> 1. I've resolved it — continue
+> 2. Skip this item for now
+> 3. Abort this phase
+
+Wait for the user's response. Never guess or work around a blocker silently.
+
+## Rules
+
+- **One phase per invocation** — never auto-advance to the next phase
+- **Never modify PRD content** — the PRD is read-only
+- **Never modify plan content** beyond marking checkboxes `[x]`
+- **Never skip a phase** — phases must be completed in order
+- **Never impose conventions** — follow the project's existing setup
+- **HITL at every decision point** — commits, blockers, and branch creation require user approval
+- **Feedback loops are mandatory** — always run available checks before marking items complete
+- **Do not push to remote** — only commit locally