Ревізії Plan Build

Vernon Wee Hong KOH ревизій цього gist 3 weeks ago. До ревизії

6 files changed, 31 insertions, 288 deletions

ADR.md (файл видалено)

		@@ -1,55 +0,0 @@
1	-	# Architecture Decision Records
2	-
3	-	## ADR-001: Make plan-build a dedicated standalone gist
4	-
5	-	Status: Accepted
6	-
7	-	The implementation previously lived inside the broad Zsh Setup `func` file while its workflows and history were spread across that repository. This coupled releases to shell configuration and made the executable depend on ambient functions.
8	-
9	-	The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, workflow-preflight, payload, and Claude-launch helpers. Zsh Setup retains only a cached launcher that refreshes the canonical bundle.
10	-
11	-	The Zsh Setup migration is maintained separately from the canonical executable so shell installation concerns do not leak back into this repository.
12	-
13	-	## ADR-002: Keep one supported workflow surface
14	-
15	-	Status: Superseded by ADR-006
16	-
17	-	The former supported surface was standard, prompt enhancement, brainstorm, writing-plan, architect, new architect state, and permissive Claude execution. The removed v2 entry point remained rejected as an unknown option, and stale v2-only distribution concepts were excluded from the canonical skills.
18	-
19	-	This avoids multiple remote implementations and prevents documentation drift.
20	-
21	-	## ADR-003: Translate convenience flags at the process boundary
22	-
23	-	Status: Accepted
24	-
25	-	`--yolo` remains the plan-build user interface for continuity, but `_plan_build_launch_claude` translates it to Claude Code's actual `--dangerously-skip-permissions` argument. Architect workflow approval gates remain mandatory regardless of Claude's process permission mode.
26	-
27	-	## ADR-004: Test through replaceable command seams
28	-
29	-	Status: Accepted
30	-
31	-	The executable is sourceable and its `_plan_build_` helpers form test seams. Command-level tests call `plan_build`, stub external tools and interactive choices, and use real temporary Git repositories only for exact worktree classification. Tests never use the network.
32	-
33	-	## ADR-005: Activate immutable complete releases through one symlink
34	-
35	-	Status: Accepted
36	-
37	-	The thin launcher stages `plan_build.zsh`, `SKILL.md`, and `ARCHITECT.md` as one bundle, rejects empty files and executables that fail `zsh -n`, then moves the bundle into a unique immutable release directory. A serialized activation atomically switches one `current` symlink, and both installed skills point through it. Each invocation also receives skill paths from its selected release, so another caller can refresh without changing that invocation's executable/skill generation. The mutable HTTPS `HEAD` URL remains the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content, establish update provenance, or make the three separate requests one remote snapshot.
38	-
39	-	## ADR-006: Make Matt Pocock's workflow the default
40	-
41	-	Status: Accepted
42	-
43	-	The Superpowers brainstorm and writing-plan flags created parallel planning surfaces and required Claude to transition between plugin workflows inside one launcher mode. Matt Pocock's flow already distinguishes discovery, specifications, tracer-bullet tickets, TDD, diagnosis, and large wayfinding efforts while defining where fresh contexts are required.
44	-
45	-	The standard invocation now routes through Matt's workflow by default. `--brainstorm` and `--writing-plan` are removed without compatibility aliases. Matt entry skills that disable model invocation remain explicit user gates. Multi-session planning stops after approved tickets, and each ticket starts in a fresh plan-build session. The standard workflow overrides Matt `/implement`'s automatic commit step so uncommitted changes receive two-axis, Codex, and CodeRabbit review before user approval.
46	-
47	-	## ADR-007: Scope continuity with a committed AgentMemory identity
48	-
49	-	Status: Accepted
50	-
51	-	AgentMemory's default project fallback uses a directory basename, which can collide across unrelated repositories and vary across worktrees. Every target repository therefore commits `.agentmemory-project`, and the launcher exports that stable value as `AGENTMEMORY_PROJECT_NAME` to Claude and inherited Codex processes.
52	-
53	-	Hooks provide automatic capture and context injection, but they tolerate server failure and cannot guarantee that the active case was restored. Both workflow skills therefore require an explicit recall gate and exactly one project-scoped `workflow_status` slot. Current Git and approved artifacts outrank recalled state. Durable memories store only verified decisions, fixes, constraints, gotchas, relationships, and preferences; the status slot carries temporary handoff state.
54	-
55	-	When the server or either agent plugin is unavailable, an interactive user may retry, approve clearly reported degraded mode, or stop. Non-interactive failure stops. This preserves user control without silently claiming continuity.

AGENTMEMORY.md (файл видалено)

		@@ -1,21 +0,0 @@
1	-	# AgentMemory Contract
2	-
3	-	This repository's stable AgentMemory identity is stored in `.agentmemory-project`. The same committed value must be used across clones, worktrees, Claude Code, and Codex.
4	-
5	-	## Authority
6	-
7	-	Current Git, approved issues/specifications, repository documentation, and ADRs override recalled memory. The `workflow_status` slot is the current handoff checkpoint. Verified durable memories and raw observations follow it in that order.
8	-
9	-	## Active Checkpoint
10	-
11	-	Maintain exactly one project-scoped slot named `workflow_status`. Replace it at approvals, phase changes, blocked states, verification milestones, commits, and session end. Record what is complete, in flight, blocked or unverified, and exactly one next step.
12	-
13	-	## Durable Memory
14	-
15	-	Save approved architectural decisions, rejected alternatives, non-obvious constraints, verified recurring bug fixes, deployment or migration gotchas, important module relationships, and durable preferences. Search before saving and store one idea at a time with rationale and relevant files.
16	-
17	-	Do not explicitly save routine output, temporary progress outside the checkpoint, unverified hypotheses, generated content, credentials, personal data, or production data.
18	-
19	-	## Availability
20	-
21	-	If AgentMemory preflight fails, plan-build asks the interactive user to retry, continue in explicitly degraded mode, or stop. A non-interactive failure stops. Degraded sessions must report that previous context was not restored.

CHANGELOG.md (файл видалено)

		@@ -1,33 +0,0 @@
1	-	# Changelog
2	-
3	-	## Unreleased
4	-
5	-	### Added
6	-
7	-	- Standalone executable `plan_build.zsh`.
8	-	- Canonical standard and architect Claude skills.
9	-	- Standard Matt, prompt-enhanced Matt, and architect workflows.
10	-	- Architect safe-resume and archive-and-start-new launch modes.
11	-	- Command-level, network-free Zsh regression tests.
12	-	- Dedicated installation, integration, architecture, task, and troubleshooting documentation.
13	-	- Memory-aware Matt Pocock routing as the default workflow.
14	-	- Stable committed `.agentmemory-project` identity shared by Claude and Codex.
15	-	- AgentMemory server and Claude/Codex plugin preflight with explicit degraded-mode approval.
16	-	- Mandatory project recall and one canonical `workflow_status` checkpoint in standard and architect workflows.
17	-
18	-	### Changed
19	-
20	-	- Plan-build-specific implementation and documentation now belong to the dedicated `plan-build` gist rather than the Zsh Setup repository.
21	-	- `--yolo` is translated to Claude Code's `--dangerously-skip-permissions` argument.
22	-	- Active workflow documentation no longer describes removed v2 or distribution modes.
23	-	- Prompt enhancement now uses valid, immediately flushed platform `script` invocations, including util-linux `script -e` for child-status propagation, and cleans up temporary state and child processes on return or interruption.
24	-	- The Zsh Setup cache contract now activates immutable three-file releases through one atomic `current` symlink and identifies mutable HTTPS `HEAD` as the update trust boundary.
25	-	- Standard planning now follows Matt Pocock's grilling, specification, tracer-ticket, TDD, diagnosis, and wayfinding flows.
26	-	- Matt implementation commits are deferred until working-tree review, validation, and explicit user approval.
27	-	- Architect mode recalls and reconciles previous state before document-based resume detection and passes the same memory identity to Codex.
28	-
29	-	### Removed
30	-
31	-	- Dependence on `~/.func` and ambient shell functions.
32	-	- The obsolete v2 downloader and its former workflow variants.
33	-	- The `--brainstorm` and `--writing-plan` options and Claude Superpowers dependency.

README.md

			@@ -37,19 +37,9 @@ codex plugin list
37	37
38	38		No LLM provider is required for continuity. AgentMemory's local embeddings, keyword retrieval, automatic hooks, explicit recall gate, and project-scoped status slot work without LLM compression.
39	39
40		-	## Plan-Build Installation
	40	+	## Quick Start
41	41
42		-	Install the executable somewhere on `PATH`:
43		-
44		-	```zsh
45		-	mkdir -p "$HOME/.local/bin"
46		-	curl -fsSL \
47		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh \
48		-	-o "$HOME/.local/bin/plan_build"
49		-	chmod +x "$HOME/.local/bin/plan_build"
50		-	```
51		-
52		-	Install both plan-build skills:
	42	+	Install both plan-build skills once:
53	43
54	44		```zsh
55	45		mkdir -p \
			@@ -63,6 +53,34 @@ curl -fsSL \
63	53		-o "$HOME/.claude/skills/plan-build-architect/SKILL.md"
64	54		```
65	55
	56	+	Then change to the Git repository you want to work on and run plan-build directly from OpenGist:
	57	+
	58	+	```zsh
	59	+	zsh <(curl -s https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh)
	60	+	```
	61	+
	62	+	When prompted, type or paste the request. Put `EOF` alone on a new line and press Enter to launch the workflow:
	63	+
	64	+	```text
	65	+	Implement pagination for the audit log.
	66	+	Preserve existing API compatibility.
	67	+	EOF
	68	+	```
	69	+
	70	+	The command executes the current remote script, so review the source and trust the OpenGist URL before running it.
	71	+
	72	+	## Optional Local Installation
	73	+
	74	+	To use the shorter `plan_build` command and avoid downloading the launcher on every run, install it somewhere on `PATH`:
	75	+
	76	+	```zsh
	77	+	mkdir -p "$HOME/.local/bin"
	78	+	curl -fsSL \
	79	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh \
	80	+	-o "$HOME/.local/bin/plan_build"
	81	+	chmod +x "$HOME/.local/bin/plan_build"
	82	+	```
	83	+
66	84		For production automation, download to a temporary file in the destination directory and rename it atomically after successful validation.
67	85
68	86		## Project Identity
			@@ -81,7 +99,7 @@ The launcher exports the ID as `AGENTMEMORY_PROJECT_NAME` and enables context in
81	99
82	100		## Usage
83	101
84		-	Run the command in the project to change, enter the payload, then put `EOF` alone on a line:
	102	+	If you installed the launcher locally, run it in the project to change, enter the payload, then put `EOF` alone on a line:
85	103
86	104		```zsh
87	105		plan_build

SPEC.md (файл видалено)

		@@ -1,99 +0,0 @@
1	-	# Plan-Build Specification
2	-
3	-	## Purpose
4	-
5	-	Plan-build is a self-contained Zsh launcher for memory-aware Claude Code engineering workflows. Matt Pocock's skills define discovery through delivery, AgentMemory provides project continuity across Claude and Codex sessions, Codex performs independent review or architect-dispatched implementation, and CodeRabbit reviews local changes. This repository is canonical for the executable, both plan-build skills, command tests, and documentation.
6	-
7	-	## Public Interface
8	-
9	-	```text
10	-	plan_build [--yolo] [--prompt]
11	-	plan_build --architect [--new] [--yolo]
12	-	```
13	-
14	-	The executable reads standard input until a line exactly equal to `EOF`. Empty payloads, duplicate flags, and unknown flags fail. `--brainstorm`, `--writing-plan`, and `--v2` are intentionally unknown.
15	-
16	-	- Default mode uses the memory-aware Matt workflow.
17	-	- `--prompt` enhances the payload through Auggie and requires interactive approval before Claude launches.
18	-	- `--yolo` translates to `--dangerously-skip-permissions` without bypassing workflow gates.
19	-	- `--architect` keeps Claude documentation-only and makes Codex the implementation executor.
20	-	- `--architect --new` archives active workflow documents before starting new state.
21	-
22	-	`--architect` may combine only with `--new` and `--yolo`.
23	-
24	-	## Common Preflight
25	-
26	-	All modes require an interactive terminal, a normal Git worktree, Claude, Codex, CodeRabbit, Git, AgentMemory, and a readable non-empty selected workflow skill. Claude safe mode is rejected.
27	-
28	-	Default mode additionally requires the enabled Claude plugin `mattpocock-skills@mattpocock`. Every mode checks the AgentMemory server and enabled `agentmemory@agentmemory` plugins for Claude and Codex.
29	-
30	-	When memory preflight fails, an interactive user may retry, explicitly approve degraded memoryless mode, or stop. Non-interactive memory failure stops. Other preflight failures are not degradable.
31	-
32	-	## Stable Memory Identity
33	-
34	-	Every target worktree uses a committed `.agentmemory-project` containing one stable 2-128 character identifier. Its exact grammar is `[A-Za-z0-9][A-Za-z0-9._:/-]{1,127}`; whitespace is forbidden. On first interactive use, the launcher proposes a normalized `origin` identity or asks for an explicit ID, writes the file after approval, and stops. A later invocation proceeds only when the file exists in `HEAD` and its working-tree value matches the committed value.
35	-
36	-	The launcher exports:
37	-
38	-	```text
39	-	AGENTMEMORY_PROJECT_NAME=<committed-id>
40	-	AGENTMEMORY_INJECT_CONTEXT=<true unless degraded>
41	-	PLAN_BUILD_MEMORY_MODE=<required\|degraded>
42	-	```
43	-
44	-	Claude and inherited Codex processes therefore share one scope across worktrees, clones, and machines.
45	-
46	-	## Mandatory Recall And Checkpoint
47	-
48	-	When memory is available, before routing, discovery, workflow detection, or modification, each skill reads or creates one project-scoped `workflow_status` slot, retrieves related decisions, bugs, lessons, and file history, and reconciles them with current Git and approved artifacts.
49	-
50	-	In explicitly approved degraded mode, the skill skips memory calls, reports that recall and checkpoint persistence are unavailable, proceeds only from current repository evidence, and never claims previous context was restored. A later memory failure requires the same retry, explicitly degrade, or stop choice.
51	-
52	-	The slot records phase, active work and source, completed milestone, in-flight work, blockers, pending decisions, relevant files, last verification, one next step, and update time. It is replaced at meaningful milestones and before session end. Durable decisions and verified fixes are saved separately; routine output, secrets, personal data, generated content, and unverified hypotheses are not.
53	-
54	-	Authority order is current Git and approved issue/spec, repository documentation and ADRs, active status slot, verified durable memory, then raw observations.
55	-
56	-	## Matt Workflow
57	-
58	-	The standard skill routes ordinary ideas to grilling, approved tickets to implementation, hard bugs to diagnosis, huge foggy efforts to wayfinding, incoming external issues to triage, and codebase health requests to architecture improvement.
59	-
60	-	Matt entry skills requiring explicit user invocation are never silently simulated. Small approved work remains in the discovery context. Multi-session work creates an approved spec and tracer-bullet tickets, then stops; every unblocked ticket starts in a fresh plan-build invocation.
61	-
62	-	Implementation uses pre-agreed public test seams and red-green vertical slices. Matt's automatic commit instruction is overridden. The uncommitted working tree receives Matt-equivalent Standards and Spec review, Codex review, CodeRabbit review, and complete validation before the user approves one commit. Plan-build never pushes automatically.
63	-
64	-	## Architect Mode
65	-
66	-	Architect mode runs memory recall before existing-state detection. Claude may modify only its documented Markdown scope. Codex receives the project ID, task/spec references, and compact checkpoint, recalls relevant history independently, and remains prohibited from commits or out-of-scope edits.
67	-
68	-	Archive-and-start-new preserves historical memories but replaces the active slot after successful document archival. Historical memory is context, not approval for the new requirement.
69	-
70	-	## Installed Skills
71	-
72	-	```text
73	-	~/.claude/skills/plan-build/SKILL.md
74	-	~/.claude/skills/plan-build-architect/SKILL.md
75	-	```
76	-
77	-	Canonical sources are `SKILL.md` and `ARCHITECT.md`.
78	-
79	-	## Standalone Constraints
80	-
81	-	- Support Zsh on macOS, Ubuntu, and WSL.
82	-	- Do not source user shell configuration.
83	-	- Keep helpers in the `_plan_build_` namespace.
84	-	- Keep external command and interaction boundaries replaceable.
85	-	- Keep tests network-free and prevent real agent launches.
86	-	- Remain safely sourceable and run main only when executed directly.
87	-	- Preserve the three-file immutable cache release contract.
88	-
89	-	## Acceptance Criteria
90	-
91	-	- Default, prompt-enhanced, permissive, architect resume, and architect-new modes have command coverage.
92	-	- Removed options, invalid combinations, duplicates, and empty payloads are covered.
93	-	- Stable project IDs are validated and reach Claude's environment.
94	-	- AgentMemory success, degraded approval, and rejection paths are covered without network access.
95	-	- Recall requirements appear in standard and architect launch prompts.
96	-	- Common preflight happens before payload input.
97	-	- Prompt enhancement cannot launch Claude without approval.
98	-	- `--yolo` reaches Claude only as `--dangerously-skip-permissions`.
99	-	- Syntax checks, command tests, and `git diff --check` pass.

TASKS.md (файл видалено)

		@@ -1,67 +0,0 @@
1	-	# Plan-Build Tasks
2	-
3	-	## Completed
4	-
5	-	### PB-001: Establish the dedicated project boundary
6	-
7	-	- Extract the executable from Zsh Setup into `plan_build.zsh`.
8	-	- Remove dependencies on `~/.func` and unrelated shell helpers.
9	-	- Make the executable directly runnable and safely sourceable.
10	-
11	-	### PB-002: Preserve supported workflows
12	-
13	-	- Preserve standard and prompt-enhancement behavior.
14	-	- Preserve architect safe-resume and archive-and-start-new modes.
15	-	- Preserve EOF-terminated payload input and interactive enhanced-prompt approval.
16	-	- Translate `--yolo` to Claude Code's real `--dangerously-skip-permissions` option.
17	-	- Keep `--v2` rejected through the unknown-option path.
18	-
19	-	### PB-003: Canonicalize skills and documentation
20	-
21	-	- Publish the standard workflow as `SKILL.md`.
22	-	- Publish the architect workflow as `ARCHITECT.md`.
23	-	- Remove obsolete v2-only and distribution workflow claims from the active standard skill.
24	-	- Document installation, prerequisites, cache integration, compatibility, testing, and troubleshooting.
25	-
26	-	### PB-004: Add standalone regression coverage
27	-
28	-	- Stub external CLIs, Claude launch, Auggie enhancement, and interactive approval.
29	-	- Cover all modes, invalid combinations, preflight ordering, safe-resume/new architect prompts, and normal versus bare Git repositories.
30	-	- Keep the suite network-free.
31	-
32	-	### PB-005: Replace Superpowers planning with Matt Pocock's workflow
33	-
34	-	- Make Matt routing the default standard workflow.
35	-	- Remove `--brainstorm`, `--writing-plan`, and the Superpowers dependency.
36	-	- Preserve Auggie prompt enhancement and architect modes.
37	-	- Route discovery, specifications, tracer-bullet tickets, TDD, diagnosis, and wayfinding through explicit namespaced Matt skills.
38	-	- Override automatic commits with review, validation, and explicit approval.
39	-
40	-	### PB-006: Add AgentMemory continuity
41	-
42	-	- Require a committed stable `.agentmemory-project` identity.
43	-	- Verify the shared AgentMemory server and Claude/Codex plugins before payload input.
44	-	- Allow only an explicitly approved interactive degraded mode when memory is unavailable.
45	-	- Pass one memory scope through Claude and inherited Codex processes.
46	-	- Require project-scoped recall and one canonical `workflow_status` checkpoint in both standard and architect skills.
47	-	- Add network-free tests for project identity, memory preflight outcomes, recall prompts, and child environment propagation.
48	-
49	-	## Completed outside this repository
50	-
51	-	### ZS-001: Migrate the Zsh Setup launcher
52	-
53	-	Replace the old in-repository implementation with a thin cached launcher that downloads the canonical executable and skills from the `plan-build` gist. The Zsh Setup migration now uses immutable complete release directories, a serialized atomic `current` symlink switch, and skill links through that same release.
54	-
55	-	Required launcher contract:
56	-
57	-	```text
58	-	zsh <selected-release>/plan_build.zsh "$@"
59	-	```
60	-
61	-	Required remote files:
62	-
63	-	```text
64	-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
65	-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
66	-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
67	-	```

Vernon Wee Hong KOH ревизій цього gist 3 weeks ago. До ревизії

11 files changed, 749 insertions, 328 deletions

.agentmemory-project(файл створено)

			@@ -0,0 +1 @@
	1	+	opengist.resetrix.work/weehong/plan-build

ADR.md

			@@ -6,15 +6,15 @@
6	6
7	7		The implementation previously lived inside the broad Zsh Setup `func` file while its workflows and history were spread across that repository. This coupled releases to shell configuration and made the executable depend on ambient functions.
8	8
9		-	The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, Superpowers, Git-worktree, architect-preflight, payload, and Claude-launch helpers. Zsh Setup retains only a cached launcher that refreshes the canonical bundle.
	9	+	The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, workflow-preflight, payload, and Claude-launch helpers. Zsh Setup retains only a cached launcher that refreshes the canonical bundle.
10	10
11	11		The Zsh Setup migration is maintained separately from the canonical executable so shell installation concerns do not leak back into this repository.
12	12
13	13		## ADR-002: Keep one supported workflow surface
14	14
15		-	Status: Accepted
	15	+	Status: Superseded by ADR-006
16	16
17		-	The supported surface is standard, prompt enhancement, brainstorm, writing-plan, architect, new architect state, and permissive Claude execution. The removed v2 entry point remains rejected as an unknown option, and stale v2-only distribution concepts are not part of the canonical skills.
	17	+	The former supported surface was standard, prompt enhancement, brainstorm, writing-plan, architect, new architect state, and permissive Claude execution. The removed v2 entry point remained rejected as an unknown option, and stale v2-only distribution concepts were excluded from the canonical skills.
18	18
19	19		This avoids multiple remote implementations and prevents documentation drift.
20	20
			@@ -35,3 +35,21 @@ The executable is sourceable and its `_plan_build_` helpers form test seams. Com
35	35		Status: Accepted
36	36
37	37		The thin launcher stages `plan_build.zsh`, `SKILL.md`, and `ARCHITECT.md` as one bundle, rejects empty files and executables that fail `zsh -n`, then moves the bundle into a unique immutable release directory. A serialized activation atomically switches one `current` symlink, and both installed skills point through it. Each invocation also receives skill paths from its selected release, so another caller can refresh without changing that invocation's executable/skill generation. The mutable HTTPS `HEAD` URL remains the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content, establish update provenance, or make the three separate requests one remote snapshot.
	38	+
	39	+	## ADR-006: Make Matt Pocock's workflow the default
	40	+
	41	+	Status: Accepted
	42	+
	43	+	The Superpowers brainstorm and writing-plan flags created parallel planning surfaces and required Claude to transition between plugin workflows inside one launcher mode. Matt Pocock's flow already distinguishes discovery, specifications, tracer-bullet tickets, TDD, diagnosis, and large wayfinding efforts while defining where fresh contexts are required.
	44	+
	45	+	The standard invocation now routes through Matt's workflow by default. `--brainstorm` and `--writing-plan` are removed without compatibility aliases. Matt entry skills that disable model invocation remain explicit user gates. Multi-session planning stops after approved tickets, and each ticket starts in a fresh plan-build session. The standard workflow overrides Matt `/implement`'s automatic commit step so uncommitted changes receive two-axis, Codex, and CodeRabbit review before user approval.
	46	+
	47	+	## ADR-007: Scope continuity with a committed AgentMemory identity
	48	+
	49	+	Status: Accepted
	50	+
	51	+	AgentMemory's default project fallback uses a directory basename, which can collide across unrelated repositories and vary across worktrees. Every target repository therefore commits `.agentmemory-project`, and the launcher exports that stable value as `AGENTMEMORY_PROJECT_NAME` to Claude and inherited Codex processes.
	52	+
	53	+	Hooks provide automatic capture and context injection, but they tolerate server failure and cannot guarantee that the active case was restored. Both workflow skills therefore require an explicit recall gate and exactly one project-scoped `workflow_status` slot. Current Git and approved artifacts outrank recalled state. Durable memories store only verified decisions, fixes, constraints, gotchas, relationships, and preferences; the status slot carries temporary handoff state.
	54	+
	55	+	When the server or either agent plugin is unavailable, an interactive user may retry, approve clearly reported degraded mode, or stop. Non-interactive failure stops. This preserves user control without silently claiming continuity.

AGENTMEMORY.md(файл створено)

		@@ -0,0 +1,21 @@
1	+	# AgentMemory Contract
2	+
3	+	This repository's stable AgentMemory identity is stored in `.agentmemory-project`. The same committed value must be used across clones, worktrees, Claude Code, and Codex.
4	+
5	+	## Authority
6	+
7	+	Current Git, approved issues/specifications, repository documentation, and ADRs override recalled memory. The `workflow_status` slot is the current handoff checkpoint. Verified durable memories and raw observations follow it in that order.
8	+
9	+	## Active Checkpoint
10	+
11	+	Maintain exactly one project-scoped slot named `workflow_status`. Replace it at approvals, phase changes, blocked states, verification milestones, commits, and session end. Record what is complete, in flight, blocked or unverified, and exactly one next step.
12	+
13	+	## Durable Memory
14	+
15	+	Save approved architectural decisions, rejected alternatives, non-obvious constraints, verified recurring bug fixes, deployment or migration gotchas, important module relationships, and durable preferences. Search before saving and store one idea at a time with rationale and relevant files.
16	+
17	+	Do not explicitly save routine output, temporary progress outside the checkpoint, unverified hypotheses, generated content, credentials, personal data, or production data.
18	+
19	+	## Availability
20	+
21	+	If AgentMemory preflight fails, plan-build asks the interactive user to retry, continue in explicitly degraded mode, or stop. A non-interactive failure stops. Degraded sessions must report that previous context was not restored.

ARCHITECT.md

			@@ -2,6 +2,8 @@
2	2
3	3		Use this workflow only when `plan_build --architect` launches Claude Code. Claude is the lead architect, documentation manager, task dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit is the required automated reviewer.
4	4
	5	+	AgentMemory is the continuity layer for Claude and Codex. Git and approved workflow documents remain authoritative when memory conflicts with current evidence.
	6	+
5	7		## Non-Negotiable Role Boundary
6	8
7	9		Claude may inspect every project file but may create or modify only:
			@@ -27,11 +29,25 @@ Before discovery or project-file modification:
27	29		2. Record `git status --short` and preserve all pre-existing work.
28	30		3. Confirm an interactive terminal is available.
29	31		4. Confirm `codex`, `coderabbit`, and `git` are available.
30		-	5. Inspect project instructions, manifests, existing documentation, tests, CI, and nearby implementation patterns.
31		-	6. Never request or expose credential values. Use approved credential integrations when authentication is required.
	32	+	5. Confirm `.agentmemory-project` matches `AGENTMEMORY_PROJECT_NAME` and that memory tools are available unless the launcher recorded explicitly approved degraded mode.
	33	+	6. Run the mandatory memory recall gate below.
	34	+	7. Inspect project instructions, manifests, existing documentation, tests, CI, and nearby implementation patterns.
	35	+	8. Never request or expose credential values. Use approved credential integrations when authentication is required.
32	36
33	37		If a requirement is missing, stop with exact remediation guidance.
34	38
	39	+	## Mandatory Memory Recall
	40	+
	41	+	Initialize a session-local memory mode from `PLAN_BUILD_MEMORY_MODE`. Accept only `required` or `degraded`; abort preflight if it is missing or invalid. Before existing-workflow detection, run this gate unless that local mode is degraded:
	42	+
	43	+	1. Read the project-scoped `workflow_status` slot. Create it with project scope if it is absent.
	44	+	2. Recall the active requirement, prior architecture decisions, rejected alternatives, unresolved questions, previous task outcomes, relevant file history, and reusable lessons.
	45	+	3. Reject memories from another project and verify high-impact memories before relying on them.
	46	+	4. Reconcile memory with Git, `SPEC.md`, `TASKS.md`, `ADR.md`, `CHANGELOG.md`, `CONTEXT.md`, and the issue tracker. Those current artifacts win every conflict.
	47	+	5. Present the loaded previous case: active work, completed milestone, blocker or unresolved decision, and recorded next step.
	48	+
	49	+	Maintain exactly one `workflow_status` slot containing phase, active work and source, completed milestone, in-flight work, blockers, pending decisions, relevant files, last verification, next step, and update time. Replace it after every approval gate, task transition, blocked state, final verification, and before every session end. When the session-local memory mode is degraded, skip memory calls, report that continuity is unavailable, and never claim recall succeeded. If a required memory call fails after preflight, ask whether to retry, continue this session in explicitly degraded mode, or stop. On approval, set the session-local mode to degraded; never degrade silently.
	50	+
35	51		## Existing Workflow Detection
36	52
37	53		If `SPEC.md`, `TASKS.md`, `ADR.md`, or `CHANGELOG.md` exists:
			@@ -43,6 +59,8 @@ If `SPEC.md`, `TASKS.md`, `ADR.md`, or `CHANGELOG.md` exists:
43	59
44	60		When the launch instruction says `Start mode: archive-and-start-new`, archive existing workflow documents in a timestamped documentation archive before creating replacements. Never overwrite them silently.
45	61
	62	+	Archive-and-start-new replaces the active `workflow_status` only after the archive succeeds. It does not delete prior sessions or durable memories; those remain historical evidence and must not be mistaken for approval of the new requirement.
	63	+
46	64		## Phase 1: Discovery and Architecture
47	65
48	66		Interview the user until product, architecture, data, integration, operational, security, and handover requirements are clear.
			@@ -105,6 +123,8 @@ Every task must include:
105	123
106	124		Every Codex prompt must explicitly prohibit commits and out-of-scope edits. Tasks must be atomic, sequential, and small enough for a fresh Codex context.
107	125
	126	+	Every Codex prompt must also include `AGENTMEMORY_PROJECT_NAME`, the active task and specification references, and a compact checkpoint summary. Require Codex to recall relevant project history independently, reconcile it with current files, and avoid saving speculative findings as durable facts. The launcher environment must be inherited unchanged by Codex.
	127	+
108	128		Present `TASKS.md` and wait for explicit approval before execution.
109	129
110	130		## Documentation Records
			@@ -156,7 +176,9 @@ For each approved task, in dependency order:
156	176		10. Delegate valid fixes back to Codex within the same task scope.
157	177		11. Rerun focused verification and CodeRabbit after substantive fixes.
158	178		12. Record commands, results, findings, and completion evidence.
159		-	13. Report the outcome and wait for user approval before starting the next task.
	179	+	13. Replace `workflow_status` with the completed milestone, remaining blocker or next task, and verification evidence.
	180	+	14. Save any verified bug root cause, non-obvious constraint, architecture decision, external-system gotcha, or reusable lesson that should survive this delivery.
	181	+	15. Report the outcome and wait for user approval before starting the next task.
160	182
161	183		Use non-interactive Codex execution in this form, adapting only supported sandbox flags to the installed CLI:
162	184
			@@ -198,6 +220,8 @@ If no test framework exists, the first applicable task establishes the smallest
198	220		- Use native credential helpers and approved credential stores.
199	221		- Run available secret scanning before final completion.
200	222		- Treat suspected credentials as blocking findings.
	223	+	- Never save credentials, tokens, personal data, production data, or unverified hypotheses to AgentMemory.
	224	+	- Automatic hook capture does not make memory authoritative; verify recalled claims against current artifacts.
201	225
202	226		## Final Review and Single Commit
203	227
			@@ -214,6 +238,7 @@ After every task is `Complete`:
214	238		9. Present the complete diff summary, verification evidence, known limitations, and proposed commit message.
215	239		10. Wait for explicit user approval.
216	240		11. Stage only approved files and create one commit.
217		-	12. Do not push.
	241	+	12. Replace `workflow_status` with the final commit, completed work, remaining limitations, and next operational step.
	242	+	13. Do not push.
218	243
219	244		Never call the delivery complete when required verification has not run. Report environmental or unrelated failures with evidence.

CHANGELOG.md

			@@ -6,10 +6,14 @@
6	6
7	7		- Standalone executable `plan_build.zsh`.
8	8		- Canonical standard and architect Claude skills.
9		-	- Standard, prompt-enhanced, brainstorm, writing-plan, and architect workflows.
	9	+	- Standard Matt, prompt-enhanced Matt, and architect workflows.
10	10		- Architect safe-resume and archive-and-start-new launch modes.
11	11		- Command-level, network-free Zsh regression tests.
12	12		- Dedicated installation, integration, architecture, task, and troubleshooting documentation.
	13	+	- Memory-aware Matt Pocock routing as the default workflow.
	14	+	- Stable committed `.agentmemory-project` identity shared by Claude and Codex.
	15	+	- AgentMemory server and Claude/Codex plugin preflight with explicit degraded-mode approval.
	16	+	- Mandatory project recall and one canonical `workflow_status` checkpoint in standard and architect workflows.
13	17
14	18		### Changed
15	19
			@@ -18,8 +22,12 @@
18	22		- Active workflow documentation no longer describes removed v2 or distribution modes.
19	23		- Prompt enhancement now uses valid, immediately flushed platform `script` invocations, including util-linux `script -e` for child-status propagation, and cleans up temporary state and child processes on return or interruption.
20	24		- The Zsh Setup cache contract now activates immutable three-file releases through one atomic `current` symlink and identifies mutable HTTPS `HEAD` as the update trust boundary.
	25	+	- Standard planning now follows Matt Pocock's grilling, specification, tracer-ticket, TDD, diagnosis, and wayfinding flows.
	26	+	- Matt implementation commits are deferred until working-tree review, validation, and explicit user approval.
	27	+	- Architect mode recalls and reconciles previous state before document-based resume detection and passes the same memory identity to Codex.
21	28
22	29		### Removed
23	30
24	31		- Dependence on `~/.func` and ambient shell functions.
25	32		- The obsolete v2 downloader and its former workflow variants.
	33	+	- The `--brainstorm` and `--writing-plan` options and Claude Superpowers dependency.

README.md

			@@ -1,23 +1,43 @@
1	1		# plan-build
2	2
3		-	`plan-build` is a standalone Zsh tool that launches Claude Code with a structured multi-agent implementation workflow. Claude orchestrates, Codex provides independent implementation review, and CodeRabbit reviews the resulting changes. Architect mode instead keeps Claude within a documentation-first architecture and task-dispatch role while Codex performs implementation.
	3	+	`plan-build` is a standalone Zsh launcher for a memory-aware multi-agent engineering workflow. Claude Code follows Matt Pocock's discovery, specification, ticketing, TDD, and review flows. AgentMemory restores the active project case and related history across fresh Claude and Codex sessions. Codex and CodeRabbit provide independent review. Architect mode keeps Claude documentation-only while Codex performs approved implementation tasks.
4	4
5	5		## Prerequisites
6	6
7	7		- Zsh
	8	+	- Git and a checked-out Git worktree
8	9		- Claude Code CLI (`claude`)
9	10		- OpenAI Codex CLI (`codex`)
10	11		- CodeRabbit CLI (`coderabbit`)
11		-	- Git
	12	+	- AgentMemory CLI and a running AgentMemory server
	13	+	- Enabled Claude Code plugins `mattpocock-skills@mattpocock` and `agentmemory@agentmemory`
	14	+	- Enabled Codex plugin `agentmemory@agentmemory`
12	15		- The installed plan-build skills described below
13	16
14		-	`--prompt` also requires Auggie (`auggie`), an authenticated `~/.augment/session.json`, Perl, and the platform `script` utility.
	17	+	Claude Code safe mode must be disabled because it disables both required plugins. All modes require an interactive terminal. `--prompt` additionally requires Auggie (`auggie`), an authenticated `~/.augment/session.json`, Perl, and the platform `script` utility.
15	18
16		-	`--brainstorm` and `--writing-plan` require the enabled Claude Code plugin `superpowers@claude-plugins-official`. Claude Code safe mode must be disabled for those modes.
	19	+	## Agent Setup
17	20
18		-	Architect mode additionally requires an interactive terminal and a normal Git worktree. Bare repositories are rejected.
	21	+	Start and connect AgentMemory according to its current installation guide. The core wiring is:
19	22
20		-	## Installation
	23	+	```zsh
	24	+	agentmemory
	25	+	agentmemory connect claude-code
	26	+	codex plugin marketplace add rohitg00/agentmemory
	27	+	codex plugin add agentmemory@agentmemory
	28	+	```
	29	+
	30	+	Install and enable the AgentMemory and Matt Pocock plugins in Claude Code. Verify the shared server before using plan-build:
	31	+
	32	+	```zsh
	33	+	agentmemory status
	34	+	claude plugin list
	35	+	codex plugin list
	36	+	```
	37	+
	38	+	No LLM provider is required for continuity. AgentMemory's local embeddings, keyword retrieval, automatic hooks, explicit recall gate, and project-scoped status slot work without LLM compression.
	39	+
	40	+	## Plan-Build Installation
21	41
22	42		Install the executable somewhere on `PATH`:
23	43
			@@ -29,7 +49,7 @@ curl -fsSL \
29	49		chmod +x "$HOME/.local/bin/plan_build"
30	50		```
31	51
32		-	Then install both skills:
	52	+	Install both plan-build skills:
33	53
34	54		```zsh
35	55		mkdir -p \
			@@ -43,11 +63,25 @@ curl -fsSL \
43	63		-o "$HOME/.claude/skills/plan-build-architect/SKILL.md"
44	64		```
45	65
46		-	For production automation, download to a temporary file in the destination directory and rename it atomically after a successful transfer.
	66	+	For production automation, download to a temporary file in the destination directory and rename it atomically after successful validation.
	67	+
	68	+	## Project Identity
	69	+
	70	+	Every target repository must commit a `.agentmemory-project` file containing one stable identifier. The exact grammar is `[A-Za-z0-9][A-Za-z0-9._:/-]{1,127}`: 2-128 characters with no whitespace. Use the normalized remote repository identity when possible:
	71	+
	72	+	```text
	73	+	github.com/owner/repository
	74	+	```
	75	+
	76	+	For a repository without a durable remote, use a stable UUID-based value such as `local/550e8400-e29b-41d4-a716-446655440000`.
	77	+
	78	+	On the first interactive run, plan-build proposes the normalized `origin` URL and creates `.agentmemory-project` after approval. That setup run then stops: commit the file and rerun plan-build. Directory names are deliberately not used because unrelated repositories can share the same basename. A working-tree identity that differs from `HEAD` is rejected.
	79	+
	80	+	The launcher exports the ID as `AGENTMEMORY_PROJECT_NAME` and enables context injection for Claude except in explicitly degraded mode. Codex inherits the same environment, so both agents use one memory scope across clones and worktrees.
47	81
48	82		## Usage
49	83
50		-	Run the command in the project you want to change, enter the payload, then put `EOF` alone on a line:
	84	+	Run the command in the project to change, enter the payload, then put `EOF` alone on a line:
51	85
52	86		```zsh
53	87		plan_build
			@@ -59,51 +93,60 @@ EOF
59	93		Available modes:
60	94
61	95		```text
62		-	plan_build Standard short-plan workflow
63		-	plan_build --prompt Enhance with Auggie and approve
64		-	plan_build --brainstorm Superpowers design and plan
65		-	plan_build --writing-plan Superpowers implementation plan
66		-	plan_build --prompt --brainstorm Enhance, design, plan, and build
67		-	plan_build --yolo --writing-plan Permissive Claude process mode
68		-	plan_build --architect Safely resume architect state
69		-	plan_build --architect --new Archive state and start fresh
70		-	plan_build --architect --yolo Architect with permissive process mode
	96	+	plan_build Memory-aware Matt workflow
	97	+	plan_build --prompt Auggie enhancement, approval, then Matt workflow
	98	+	plan_build --yolo Permissive Claude process mode; gates remain active
	99	+	plan_build --architect Memory-aware architect safe resume
	100	+	plan_build --architect --new Archive active documents and start new state
	101	+	plan_build --architect --yolo Architect with permissive Claude process mode
71	102		```
72	103
73		-	`--brainstorm` and `--writing-plan` are mutually exclusive. `--prompt` can combine with either. `--architect` can combine only with `--new` and `--yolo`; `--new` is invalid without `--architect`. Duplicate flags and all other flags fail. `--v2` is intentionally unsupported.
	104	+	`--architect` may combine only with `--new` and `--yolo`; `--new` is invalid without `--architect`. Duplicate and unknown flags fail. Removed `--brainstorm`, `--writing-plan`, and `--v2` options are intentionally unknown.
74	105
75		-	The user-facing `--yolo` option is translated to Claude Code's `--dangerously-skip-permissions` argument. It never bypasses approval gates defined by either workflow.
	106	+	The user-facing `--yolo` option translates to Claude Code's `--dangerously-skip-permissions`. It never bypasses memory, planning, review, or commit approval gates.
76	107
77		-	## Zsh Setup cache launcher
	108	+	## Workflow
78	109
79		-	When curl is available, the Zsh Setup integration attempts to download this complete release bundle on every invocation:
	110	+	Except in explicitly degraded mode, every session starts by loading the project-scoped `workflow_status` slot and retrieving related decisions, bugs, lessons, and file history. Claude reconciles this memory with Git, the current issue or specification, `CONTEXT.md`, and ADRs before acting.
80	111
81		-	```text
82		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
83		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
84		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
85		-	```
	112	+	The default Matt route is:
86	113
87		-	It stages all three non-empty files, requires `plan_build.zsh` to pass `zsh -n`, moves the bundle into a unique immutable release directory, and atomically switches a single `current` symlink. Activation is serialized with a kernel-backed Zsh file lock. Failed refreshes leave the prior validated release active and repair its skill links before execution.
	114	+	1. Ordinary ideas enter `/mattpocock-skills:grill-with-docs`.
	115	+	2. Small approved work continues through `/mattpocock-skills:implement` and TDD in the same context.
	116	+	3. Multi-session work uses `/mattpocock-skills:to-spec`, then `/mattpocock-skills:to-tickets`.
	117	+	4. Each unblocked ticket starts in a fresh `plan_build` session and recovers its case through AgentMemory.
	118	+	5. Hard bugs use `/mattpocock-skills:diagnosing-bugs`; huge foggy efforts use `/mattpocock-skills:wayfinder`.
	119	+	6. Matt two-axis review, Codex review, CodeRabbit, and complete validation run before an approval-gated commit.
88	120
89		-	The launcher invokes the executable from the selected immutable release and binds both internal skill paths to that same release:
	121	+	Matt's workflow entry skills require explicit invocation. Claude tells the user the exact namespaced command and waits rather than silently approximating it. The standard workflow overrides Matt `/implement`'s automatic commit instruction: plan-build commits only after explicit approval and never pushes automatically.
90	122
91		-	```zsh
92		-	PLAN_BUILD_SKILL_PATH=<selected-release>/SKILL.md \
93		-	PLAN_BUILD_ARCHITECT_SKILL_PATH=<selected-release>/ARCHITECT.md \
94		-	zsh <selected-release>/plan_build.zsh "$@"
95		-	```
	123	+	## Memory Availability
	124	+
	125	+	AgentMemory captures prompts, tool activity, session boundaries, subagents, compaction, and commits automatically. Plan-build adds an explicit recall and checkpoint protocol because hooks alone fail silently when the server is unavailable.
	126	+
	127	+	If AgentMemory, its Claude plugin, or its Codex plugin fails preflight, plan-build asks whether to retry, continue in explicitly degraded memoryless mode, or stop. A non-interactive failure stops. Degraded mode is always reported and must never claim previous context was restored.
96	128
97		-	It never sources remote code into the caller shell. The mutable HTTPS `HEAD` download is the explicit update trust boundary: transport security authenticates the server, but the URL provides neither immutable-version pinning nor content-integrity verification. Complete-release activation and syntax validation prevent partial or syntactically invalid active releases; they do not establish provenance or guarantee that three independent downloads observed the same remote revision if publication occurs during refresh.
	129	+	Memory supplements the repository; it does not replace specs, tickets, `CONTEXT.md`, ADRs, tests, or Git. Current approved artifacts win conflicts with old memory. Secrets, personal data, production data, and unverified hypotheses must not be explicitly saved.
98	130
99		-	The installed Claude skill files are symlinks through the same `current` release:
	131	+	## Architect Mode
	132	+
	133	+	Architect mode recalls the previous case before detecting `SPEC.md`, `TASKS.md`, ADRs, or changelog state. Claude remains documentation-only and passes the same AgentMemory project ID and checkpoint summary to every Codex task.
	134	+
	135	+	`--architect --new` archives the active workflow documents and replaces the active status slot only after successful archival. Historical sessions and durable memories remain available but do not count as approval for the new requirement.
	136	+
	137	+	## Zsh Setup Cache Launcher
	138	+
	139	+	The Zsh Setup integration downloads this complete release bundle:
100	140
101	141		```text
102		-	~/.claude/skills/plan-build/SKILL.md
103		-	~/.claude/skills/plan-build-architect/SKILL.md
	142	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
	143	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
	144	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
104	145		```
105	146
106		-	The launcher defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/plan-build`; Zsh Setup exposes `PLAN_BUILD_CACHE_DIR` and `PLAN_BUILD_BASE_URL` overrides. Skill paths stay fixed at `~/.claude/skills` to match the canonical executable.
	147	+	It stages all three non-empty files, requires `plan_build.zsh` to pass `zsh -n`, moves them into one immutable release directory, and atomically switches a serialized `current` symlink. Failed refreshes leave the previous validated release active. Both internal skill paths are bound to the selected release, so concurrent refreshes cannot mix generations.
	148	+
	149	+	The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS protects transport but does not pin content, establish provenance, or guarantee that separate requests observed one remote revision.
107	150
108	151		## Testing
109	152
			@@ -117,11 +160,12 @@ git diff --check
117	160
118	161		## Troubleshooting
119	162
120		-	- CLI is missing: install the named program and ensure its executable is on `PATH`.
121		-	- Superpowers is missing: in Claude Code run `/plugin install superpowers@claude-plugins-official`.
122		-	- Superpowers is disabled: run `claude plugin enable superpowers@claude-plugins-official`.
123		-	- Safe mode blocks planning: unset `CLAUDE_CODE_SAFE_MODE`.
	163	+	- AgentMemory unavailable: run `agentmemory status`, start the server, and retry.
	164	+	- AgentMemory tools missing: confirm the Claude and Codex plugins are enabled and connected to the same server.
	165	+	- Matt skills missing: install or enable `mattpocock-skills@mattpocock` in Claude Code.
	166	+	- Safe mode blocks plugins: unset `CLAUDE_CODE_SAFE_MODE`.
	167	+	- Project ID rejected: keep `.agentmemory-project` to one valid 2-128 character identifier with no whitespace.
124	168		- Auggie cannot authenticate: run `auggie login` and confirm `~/.augment/session.json` is non-empty.
125		-	- Prompt enhancement does not continue: `--prompt` requires an interactive terminal to approve both optional project indexing and the final enhanced prompt.
126		-	- Architect preflight fails in Git: change to a checked-out worktree rather than the `.git` directory or a bare repository.
127		-	- Architect skill is missing: install `ARCHITECT.md` at the exact skill path shown above.
	169	+	- Prompt enhancement does not continue: `--prompt` requires approval for optional indexing and the enhanced prompt.
	170	+	- Git preflight fails: run from a checked-out worktree, not a bare repository or `.git` directory.
	171	+	- Workflow skill missing: install `SKILL.md` and `ARCHITECT.md` at the exact paths above.

SKILL.md

			@@ -1,127 +1,135 @@
1		-	# Plan-Build Orchestrate Loop
	1	+	# Plan-Build Memory-Aware Matt Workflow
2	2
3		-	Use this workflow when `plan_build` hands Claude Code an implementation task. The goal is to keep Claude as the orchestrator while using Codex and CodeRabbit as independent review and validation agents.
	3	+	Use this workflow when `plan_build` hands Claude Code a project request. Matt Pocock's skills provide discovery, specification, ticketing, TDD, and review. AgentMemory restores prior project context across Claude and Codex sessions. Codex and CodeRabbit remain independent reviewers.
4	4
5		-	## Operating Rules
	5	+	## Non-Negotiable Rules
6	6
7		-	- Run from the project root. Treat the current working directory as the project to modify.
8		-	- Preserve user work. Check `git status` before edits and do not revert unrelated changes.
9		-	- Keep implementation scoped to the payload unless repository context proves a wider change is required.
10		-	- Prefer existing project conventions, scripts, test commands, and dependency managers.
11		-	- Do not call the task complete until validation has run or the reason it cannot run is documented.
12		-	- If any agent reports a plausible correctness, security, data-loss, migration, or test risk, resolve it or explicitly document why it is not applicable.
	7	+	- Run from the project root and preserve all pre-existing work.
	8	+	- Treat Git, the approved issue or specification, `CONTEXT.md`, and ADRs as authoritative. Memory supplements them and never overrides contradictory current evidence.
	9	+	- Use the `AGENTMEMORY_PROJECT_NAME` supplied by the launcher for every memory operation and child Codex process.
	10	+	- Do not expose or save credentials, tokens, personal data, or production secrets.
	11	+	- Matt entry skills marked `disable-model-invocation` require explicit user invocation. Tell the user the exact namespaced slash command and wait for it instead of simulating the skill.
	12	+	- Override `/implement`'s automatic commit instruction. Keep changes uncommitted until review and validation pass and the user explicitly approves the commit. Never push automatically.
13	13
14		-	## The 8-Step Workflow
	14	+	## Memory Precedence
15	15
16		-	### 1. Intake
	16	+	Resolve conflicts in this order:
17	17
18		-	Read the user payload fully. Identify:
	18	+	1. Current Git state and the approved issue or specification.
	19	+	2. Current repository documentation, `CONTEXT.md`, and ADRs.
	20	+	3. The project-scoped `workflow_status` slot.
	21	+	4. Verified durable memories and lessons.
	22	+	5. Raw historical observations.
19	23
20		-	- Objective and expected user-visible behavior.
21		-	- Files, modules, commands, and frameworks likely involved.
22		-	- Constraints from repository docs, package scripts, CI config, and existing patterns.
23		-	- Any ambiguity that blocks safe execution.
	24	+	Report conflicts and correct stale memory. Never bend current implementation or requirements to match an old observation.
24	25
25		-	Only ask the user a question when no reasonable project-local assumption is safe.
	26	+	## Mandatory Recall Gate
26	27
27		-	### 2. Baseline
	28	+	Run this gate before routing the request, asking discovery questions, or modifying files. Initialize a session-local memory mode from `PLAN_BUILD_MEMORY_MODE`, accepting only `required` or `degraded`. Treat an unset or invalid value as `required` and fail closed if mandatory recall cannot run. Only a launcher-supplied `degraded` value or an explicit user approval after a later memory failure may set the local mode to degraded and permit skipping memory calls.
28	29
29		-	Inspect the repository before changing files:
	30	+	1. Confirm the current project matches `AGENTMEMORY_PROJECT_NAME` and read `.agentmemory-project`.
	31	+	2. Read the project-scoped `workflow_status` slot with `memory_slot_get`. If it does not exist, create it with project scope, a 4,000-character limit, and the template below.
	32	+	3. Redact the request before search. Query only sanitized issue or ticket identifiers and non-sensitive domain terms; remove or reject credentials, tokens, personal data, production data, and other sensitive payload values. Search for related prior bugs, decisions, and lessons, and reject results belonging to another project.
	33	+	4. After likely files are known, use file history to recover prior changes and gotchas for those files.
	34	+	5. Verify high-impact memories before relying on them. Never invent context when retrieval is empty.
	35	+	6. Reconcile recalled state with Git, the tracker, `CONTEXT.md`, ADRs, and current documentation.
	36	+	7. Tell the user what previous case was loaded: active work, last completed milestone, unresolved decision or blocker, and recorded next step.
30	37
31		-	```bash
32		-	git status --short
33		-	rg --files
34		-	```
35		-
36		-	Then read the smallest useful set of files. Prefer `rg`, package manifests, tests, routing files, and nearby implementations over broad file dumps.
37		-
38		-	### 3. Plan
39		-
40		-	Follow the planning mode supplied by `plan_build`:
41		-
42		-	- `standard`: Create a short implementation plan with concrete steps and validation commands.
43		-	- `brainstorm`: Invoke `superpowers:brainstorming`, honor its design and written-spec approval gates, and let it transition to `superpowers:writing-plans` after approval.
44		-	- `writing-plan`: Invoke `superpowers:writing-plans` directly, treating the payload as the requirements or specification.
45		-
46		-	For either Superpowers mode, save the artifacts at the paths selected by the skills. When `writing-plans` reaches its execution handoff, return to this workflow instead of starting implementation: Codex must review the plan first. If the user rejects or cancels a required approval, stop cleanly without modifying implementation files.
47		-
48		-	If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note.
49		-
50		-	### 4. Codex Plan Review
51		-
52		-	Run this step only for `brainstorm` and `writing-plan` modes. Ask Codex for an independent, read-only review of the approved spec, when present, and the implementation plan before touching implementation files. Provide the original payload and artifact paths. Ask it to focus on requirement coverage, incorrect assumptions, unsafe migrations, missing edge cases, inadequate tests, and steps that are too vague to execute.
53		-
54		-	Recommended prompt shape:
	38	+	Use this slot shape and replace it at milestones rather than appending an unlimited log:
55	39
56	40		```text
57		-	Review these planning artifacts before implementation. Check requirement coverage, technical correctness, repository fit, edge cases, migration or rollback risk, test coverage, and whether every step is executable. Report concrete findings only; do not modify files.
58		-
59		-	Task:
60		-	<payload>
	41	+	Phase: <discovery\|specification\|ticketing\|implementation\|review\|blocked\|complete>
	42	+	Active work: <title and stable issue/spec reference>
	43	+	Completed: <latest completed milestone>
	44	+	In flight: <current operation>
	45	+	Blocked: <blocker or None>
	46	+	Pending decisions: <decisions or None>
	47	+	Relevant files: <paths or Unknown>
	48	+	Last verified: <commands and result or Not run>
	49	+	Next step: <one concrete action>
	50	+	Updated: <ISO-8601 timestamp>
	51	+	```
61	52
62		-	Spec:
63		-	<spec path, if present>
	53	+	When AgentMemory is healthy but no prior state exists, say so and initialize the slot. If any required memory call fails after launcher preflight, ask the user whether to retry, continue this session in explicitly degraded mode, or stop. On approval, record the session-local mode as degraded, skip remaining memory calls, and report the loss of continuity. Do not continue memoryless without that approval and never claim previous context was loaded.
64	54
65		-	Implementation plan:
66		-	<plan path>
67		-	```
	55	+	## Route Through Matt
68	56
69		-	Use a read-only, ephemeral Codex invocation. Resolve every valid finding in the artifacts and repeat the review if revisions are substantial. If an artifact is missing or empty, or Codex cannot complete the review, stop before implementation and report the failure.
	57	+	After recall, route the request using Matt's `/ask-matt` model:
70	58
71		-	In `standard` mode, skip this step and continue directly to implementation.
	59	+	\| Request \| Entry skill \|
	60	+	\| --- \| --- \|
	61	+	\| Ordinary feature or idea \| `/mattpocock-skills:grill-with-docs` \|
	62	+	\| Approved specification or ready ticket \| `/mattpocock-skills:implement` \|
	63	+	\| Difficult, intermittent, or unclear bug \| `/mattpocock-skills:diagnosing-bugs` \|
	64	+	\| Huge and foggy multi-session effort \| `/mattpocock-skills:wayfinder` \|
	65	+	\| Unrefined incoming external issue \| `/mattpocock-skills:triage` \|
	66	+	\| Codebase-health exploration \| `/mattpocock-skills:improve-codebase-architecture` \|
72	67
73		-	### 5. Implement
	68	+	Do not triage tickets produced by `/mattpocock-skills:to-tickets`; they are already agent-ready.
74	69
75		-	Make the change in small, reviewable edits:
	70	+	## Feature Flow
76	71
77		-	- Follow existing style and abstractions.
78		-	- Add or update tests when behavior changes.
79		-	- Update docs only when user-facing usage changes.
80		-	- Avoid unrelated refactors and formatting churn.
	72	+	For an ordinary idea:
81	73
82		-	After each meaningful edit group, re-check the diff for accidental changes.
	74	+	1. Ask the user to invoke `/mattpocock-skills:grill-with-docs` with the payload.
	75	+	2. Resolve repository facts locally and ask one decision at a time with a recommended answer.
	76	+	3. Use `/mattpocock-skills:research` for external facts.
	77	+	4. For a runnable design question, use `/mattpocock-skills:handoff`, continue in a fresh prototype session, invoke `/mattpocock-skills:prototype`, then hand the learned decision back. Do not confuse Matt's file handoff with `/agentmemory:handoff`, which resumes recorded sessions.
	78	+	5. Do not implement until the user confirms shared understanding.
	79	+	6. Update `workflow_status` after shared understanding and after every later approval gate.
83	80
84		-	### 6. Codex Code Review Pass
	81	+	If the work fits one context window, agree on public testing seams, obtain a read-only Codex review of the requirements and seams, then ask the user to invoke `/mattpocock-skills:implement` in the same session.
85	82
86		-	Ask Codex for an independent review of the local diff before finalizing. Provide the task, constraints, and current diff. Ask it to focus on bugs, edge cases, missing tests, regressions, and simpler project-native alternatives.
	83	+	If the work needs multiple sessions:
87	84
88		-	Recommended prompt shape:
	85	+	1. Ask the user to invoke `/mattpocock-skills:to-spec`.
	86	+	2. Confirm the proposed public testing seams before publishing.
	87	+	3. Ask the user to invoke `/mattpocock-skills:to-tickets`.
	88	+	4. Obtain approval for vertical tracer-bullet tickets and their blocking edges.
	89	+	5. Run a read-only Codex review of the approved specification and tickets. Resolve valid findings and reapprove material scope changes.
	90	+	6. Record the specification, ticket frontier, and first unblocked ticket in `workflow_status`, then stop.
	91	+	7. Start each unblocked ticket in a fresh `plan_build` invocation so it gets a clean context plus the mandatory recall gate.
89	92
90		-	```text
91		-	Review this change for correctness and risk. Prioritize bugs, regressions, missing tests, and mismatches with existing project patterns. Do not rewrite the whole solution unless a specific issue requires it.
	93	+	## Implementation Flow
92	94
93		-	Task:
94		-	<payload>
	95	+	For a ready ticket or approved small task:
95	96
96		-	Diff:
97		-	<git diff>
98		-	```
	97	+	1. Record the baseline SHA, `git status --short`, and pre-existing diff.
	98	+	2. Load the full ticket or specification and verify dependency completion.
	99	+	3. Recall blocker outcomes, relevant file history, durable decisions, and lessons.
	100	+	4. Confirm public testing seams with the user before writing tests.
	101	+	5. Follow `/mattpocock-skills:implement` and `/mattpocock-skills:tdd` one red-green vertical slice at a time.
	102	+	6. Run focused tests and type checking regularly; run the full project validation suite at the end.
	103	+	7. Update `workflow_status` when a red test is established, implementation turns green, focused validation passes, full validation passes, review begins, or work becomes blocked.
	104	+	8. Do not commit when the Matt implementation skill requests it. Continue through plan-build review and explicit approval instead.
99	105
100		-	Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial.
	106	+	Every Codex prompt must include the project ID, active ticket or specification, and checkpoint summary. Require Codex to recall the same project independently and to treat current repository evidence as authoritative. Read-only review prompts must prohibit edits and durable saves of speculative findings.
101	107
102		-	### 7. CodeRabbit Review Pass
	108	+	## Review Stack
103	109
104		-	Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding.
	110	+	Review only the intended change against its captured baseline. Capture the startup patch, then use a three-way, patch-aware comparison between `HEAD`, that baseline, and the current staged, unstaged, and intended untracked files. Preserve and exclude unrelated baseline changes throughout review, approval, and staging. If intended and pre-existing edits overlap in a file or hunk, stop and ask the user instead of subtracting or guessing.
105	111
106		-	If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely.
	112	+	1. Run Matt's two axes in parallel against that filtered intended change: repository Standards and originating Spec. The stock `/mattpocock-skills:code-review` only compares committed `HEAD` history, so apply its standards and spec briefs directly to the filtered working tree before the approval commit.
	113	+	2. Ask Codex for an independent review focused on bugs, regressions, unsafe assumptions, missing tests, and repository fit.
	114	+	3. Run CodeRabbit on the local change. Investigate every concrete finding.
	115	+	4. Fix valid findings and repeat affected reviews after substantive changes.
	116	+	5. Rerun focused validation and the complete suite.
	117	+	6. Reconstruct the filtered change and confirm final staging contains only approved work, preserves every baseline change, and has no secret exposure.
	118	+	7. Present the diff summary, validation evidence, known limitations, and proposed commit message.
	119	+	8. Wait for explicit approval, stage only intended files, create one commit, and do not push.
107	120
108		-	### 8. Validate And Close
	121	+	## Durable Memory Writes
109	122
110		-	Run the planned validation commands, such as:
	123	+	Search before saving and store one durable idea at a time with the project ID, rationale, real file paths where relevant, and specific concept tags.
111	124
112		-	```bash
113		-	npm test
114		-	npm run lint
115		-	pytest
116		-	cargo test
117		-	go test ./...
118		-	```
	125	+	Save durable memory for:
119	126
120		-	Use the commands that actually exist in the project. If validation fails, fix the issue and rerun the relevant command. If a failure is unrelated or environmental, capture the evidence.
	127	+	- Approved architecture decisions and rejected alternatives.
	128	+	- Non-obvious constraints and important module relationships.
	129	+	- Repeated bugs with verified root causes and fixes.
	130	+	- Deployment, migration, integration, and external-system gotchas.
	131	+	- Durable user or team preferences.
121	132
122		-	Before final response:
	133	+	Save reusable lessons separately. Do not save routine output, temporary progress outside `workflow_status`, unverified hypotheses, generated content, or secrets.
123	134
124		-	- Confirm `git diff` contains only intended changes.
125		-	- Summarize what changed.
126		-	- Report validation run and result.
127		-	- Note any remaining risks or commands that could not run.
	135	+	Before ending any session, update `workflow_status` with what is done, in flight, blocked or unverified, and exactly one next step. Automatic hooks capture raw activity; this explicit checkpoint is what makes the next case resumable.

SPEC.md

			@@ -2,88 +2,98 @@
2	2
3	3		## Purpose
4	4
5		-	Plan-build is a self-contained Zsh launcher for Claude Code multi-agent implementation workflows. This repository is the canonical boundary for the executable, both Claude skills, command tests, and project documentation. It does not depend on the Zsh Setup repository or on functions from `~/.func`.
	5	+	Plan-build is a self-contained Zsh launcher for memory-aware Claude Code engineering workflows. Matt Pocock's skills define discovery through delivery, AgentMemory provides project continuity across Claude and Codex sessions, Codex performs independent review or architect-dispatched implementation, and CodeRabbit reviews local changes. This repository is canonical for the executable, both plan-build skills, command tests, and documentation.
6	6
7		-	## Public interface
	7	+	## Public Interface
8	8
9	9		```text
10		-	plan_build [--yolo] [--prompt] [--brainstorm \| --writing-plan]
	10	+	plan_build [--yolo] [--prompt]
11	11		plan_build --architect [--new] [--yolo]
12	12		```
13	13
14		-	The executable reads standard input until a line exactly equal to `EOF`. Empty payloads fail. Unknown and duplicate options fail with usage text. `--v2` is intentionally unknown.
	14	+	The executable reads standard input until a line exactly equal to `EOF`. Empty payloads, duplicate flags, and unknown flags fail. `--brainstorm`, `--writing-plan`, and `--v2` are intentionally unknown.
15	15
16		-	### Standard modes
	16	+	- Default mode uses the memory-aware Matt workflow.
	17	+	- `--prompt` enhances the payload through Auggie and requires interactive approval before Claude launches.
	18	+	- `--yolo` translates to `--dangerously-skip-permissions` without bypassing workflow gates.
	19	+	- `--architect` keeps Claude documentation-only and makes Codex the implementation executor.
	20	+	- `--architect --new` archives active workflow documents before starting new state.
17	21
18		-	- No planning flag: use the normal short-plan eight-step workflow.
19		-	- `--prompt`: enhance the payload through Auggie, display the result, and require interactive approval before Claude launches.
20		-	- `--brainstorm`: require enabled Claude Superpowers, then use brainstorming and writing-plans approval gates.
21		-	- `--writing-plan`: require enabled Claude Superpowers and create the implementation plan directly.
22		-	- `--yolo`: launch Claude Code with `--dangerously-skip-permissions`.
	22	+	`--architect` may combine only with `--new` and `--yolo`.
23	23
24		-	`--brainstorm` and `--writing-plan` are mutually exclusive. `--prompt` may be combined with either.
	24	+	## Common Preflight
25	25
26		-	### Architect mode
	26	+	All modes require an interactive terminal, a normal Git worktree, Claude, Codex, CodeRabbit, Git, AgentMemory, and a readable non-empty selected workflow skill. Claude safe mode is rejected.
27	27
28		-	`--architect` makes Claude the documentation-first architect and dispatcher. It may combine only with `--new` and `--yolo`.
	28	+	Default mode additionally requires the enabled Claude plugin `mattpocock-skills@mattpocock`. Every mode checks the AgentMemory server and enabled `agentmemory@agentmemory` plugins for Claude and Codex.
29	29
30		-	- Default: safely detect and resume existing planning state.
31		-	- `--new`: archive existing planning documents as directed by the architect skill and start fresh.
32		-	- `--yolo`: changes Claude Code permissions only; every workflow approval gate remains mandatory.
	30	+	When memory preflight fails, an interactive user may retry, explicitly approve degraded memoryless mode, or stop. Non-interactive memory failure stops. Other preflight failures are not degradable.
33	31
34		-	Architect preflight happens before payload input and verifies an interactive terminal, Claude Code, Codex, CodeRabbit, Git, an exact normal Git worktree, and a readable non-empty architect skill.
	32	+	## Stable Memory Identity
35	33
36		-	## Installed skills
	34	+	Every target worktree uses a committed `.agentmemory-project` containing one stable 2-128 character identifier. Its exact grammar is `[A-Za-z0-9][A-Za-z0-9._:/-]{1,127}`; whitespace is forbidden. On first interactive use, the launcher proposes a normalized `origin` identity or asks for an explicit ID, writes the file after approval, and stops. A later invocation proceeds only when the file exists in `HEAD` and its working-tree value matches the committed value.
37	35
38		-	The executable expects:
	36	+	The launcher exports:
39	37
40	38		```text
41		-	~/.claude/skills/plan-build/SKILL.md
42		-	~/.claude/skills/plan-build-architect/SKILL.md
	39	+	AGENTMEMORY_PROJECT_NAME=<committed-id>
	40	+	AGENTMEMORY_INJECT_CONTEXT=<true unless degraded>
	41	+	PLAN_BUILD_MEMORY_MODE=<required\|degraded>
43	42		```
44	43
45		-	The canonical repository sources are `SKILL.md` and `ARCHITECT.md`.
	44	+	Claude and inherited Codex processes therefore share one scope across worktrees, clones, and machines.
46	45
47		-	## Standalone constraints
	46	+	## Mandatory Recall And Checkpoint
48	47
49		-	- Zsh on macOS, Ubuntu, and WSL.
50		-	- No sourcing of user shell configuration.
51		-	- All internal helpers use the `_plan_build_` namespace.
52		-	- External command boundaries remain replaceable for tests.
53		-	- Tests use no network and do not launch real agent CLIs.
54		-	- The program remains sourceable and runs main only when executed directly.
	48	+	When memory is available, before routing, discovery, workflow detection, or modification, each skill reads or creates one project-scoped `workflow_status` slot, retrieves related decisions, bugs, lessons, and file history, and reconciles them with current Git and approved artifacts.
55	49
56		-	## Zsh Setup launcher integration
	50	+	In explicitly approved degraded mode, the skill skips memory calls, reports that recall and checkpoint persistence are unavailable, proceeds only from current repository evidence, and never claims previous context was restored. A later memory failure requires the same retry, explicitly degrade, or stop choice.
57	51
58		-	A thin Zsh Setup launcher downloads one release bundle:
	52	+	The slot records phase, active work and source, completed milestone, in-flight work, blockers, pending decisions, relevant files, last verification, one next step, and update time. It is replaced at meaningful milestones and before session end. Durable decisions and verified fixes are saved separately; routine output, secrets, personal data, generated content, and unverified hypotheses are not.
59	53
60		-	```text
61		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
62		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
63		-	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
64		-	```
	54	+	Authority order is current Git and approved issue/spec, repository documentation and ADRs, active status slot, verified durable memory, then raw observations.
	55	+
	56	+	## Matt Workflow
	57	+
	58	+	The standard skill routes ordinary ideas to grilling, approved tickets to implementation, hard bugs to diagnosis, huge foggy efforts to wayfinding, incoming external issues to triage, and codebase health requests to architecture improvement.
	59	+
	60	+	Matt entry skills requiring explicit user invocation are never silently simulated. Small approved work remains in the discovery context. Multi-session work creates an approved spec and tracer-bullet tickets, then stops; every unblocked ticket starts in a fresh plan-build invocation.
65	61
66		-	It must stage all three files, require each to be non-empty, and require the executable to pass `zsh -n`. A validated bundle moves into a unique immutable release directory. Activation is serialized by a kernel-backed Zsh file lock and occurs by atomically replacing one `current` symlink. The installed skill paths symlink to `SKILL.md` and `ARCHITECT.md` through `current`, so executable and skills always resolve through one release boundary. Cached fallback repairs missing or stale skill links before execution.
	62	+	Implementation uses pre-agreed public test seams and red-green vertical slices. Matt's automatic commit instruction is overridden. The uncommitted working tree receives Matt-equivalent Standards and Spec review, Codex review, CodeRabbit review, and complete validation before the user approves one commit. Plan-build never pushes automatically.
67	63
68		-	The launcher executes the selected release with `PLAN_BUILD_SKILL_PATH` and `PLAN_BUILD_ARCHITECT_SKILL_PATH` bound to that same immutable directory:
	64	+	## Architect Mode
	65	+
	66	+	Architect mode runs memory recall before existing-state detection. Claude may modify only its documented Markdown scope. Codex receives the project ID, task/spec references, and compact checkpoint, recalls relevant history independently, and remains prohibited from commits or out-of-scope edits.
	67	+
	68	+	Archive-and-start-new preserves historical memories but replaces the active slot after successful document archival. Historical memory is context, not approval for the new requirement.
	69	+
	70	+	## Installed Skills
69	71
70	72		```text
71		-	PLAN_BUILD_SKILL_PATH=<selected-release>/SKILL.md \
72		-	PLAN_BUILD_ARCHITECT_SKILL_PATH=<selected-release>/ARCHITECT.md \
73		-	zsh <selected-release>/plan_build.zsh "$@"
	73	+	~/.claude/skills/plan-build/SKILL.md
	74	+	~/.claude/skills/plan-build-architect/SKILL.md
74	75		```
75	76
76		-	It does not source the downloaded executable. Refresh failure falls back to the last complete validated release; without one, launch fails. Curl is optional only when that fallback exists. Signals stop an in-flight refresh, clean temporary state, and return the conventional signal status.
	77	+	Canonical sources are `SKILL.md` and `ARCHITECT.md`.
	78	+
	79	+	## Standalone Constraints
77	80
78		-	The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS authenticates the transport endpoint, but without an immutable version or pinned digest it does not provide content-integrity or provenance guarantees for updates. Because the three files are separate requests, publication during refresh can also expose different remote revisions; publishers should update the gist only from complete, tested commits.
	81	+	- Support Zsh on macOS, Ubuntu, and WSL.
	82	+	- Do not source user shell configuration.
	83	+	- Keep helpers in the `_plan_build_` namespace.
	84	+	- Keep external command and interaction boundaries replaceable.
	85	+	- Keep tests network-free and prevent real agent launches.
	86	+	- Remain safely sourceable and run main only when executed directly.
	87	+	- Preserve the three-file immutable cache release contract.
79	88
80		-	## Acceptance criteria
	89	+	## Acceptance Criteria
81	90
82		-	- Every documented mode has command-level coverage.
83		-	- Invalid combinations, duplicate flags, empty payloads, and `--v2` rejection are covered.
84		-	- Superpowers checks precede Auggie and payload input.
85		-	- Architect preflight precedes payload input and distinguishes normal worktrees from bare repositories.
86		-	- Prompt enhancement cannot launch Claude without explicit approval.
87		-	- `--yolo` reaches the Claude binary only as `--dangerously-skip-permissions`.
	91	+	- Default, prompt-enhanced, permissive, architect resume, and architect-new modes have command coverage.
	92	+	- Removed options, invalid combinations, duplicates, and empty payloads are covered.
	93	+	- Stable project IDs are validated and reach Claude's environment.
	94	+	- AgentMemory success, degraded approval, and rejection paths are covered without network access.
	95	+	- Recall requirements appear in standard and architect launch prompts.
	96	+	- Common preflight happens before payload input.
	97	+	- Prompt enhancement cannot launch Claude without approval.
	98	+	- `--yolo` reaches Claude only as `--dangerously-skip-permissions`.
88	99		- Syntax checks, command tests, and `git diff --check` pass.
89		-	- The Zsh Setup launcher activates and falls back only in complete three-file releases.

TASKS.md

			@@ -10,7 +10,7 @@
10	10
11	11		### PB-002: Preserve supported workflows
12	12
13		-	- Preserve standard, prompt enhancement, brainstorm, and writing-plan behavior.
	13	+	- Preserve standard and prompt-enhancement behavior.
14	14		- Preserve architect safe-resume and archive-and-start-new modes.
15	15		- Preserve EOF-terminated payload input and interactive enhanced-prompt approval.
16	16		- Translate `--yolo` to Claude Code's real `--dangerously-skip-permissions` option.
			@@ -29,6 +29,23 @@
29	29		- Cover all modes, invalid combinations, preflight ordering, safe-resume/new architect prompts, and normal versus bare Git repositories.
30	30		- Keep the suite network-free.
31	31
	32	+	### PB-005: Replace Superpowers planning with Matt Pocock's workflow
	33	+
	34	+	- Make Matt routing the default standard workflow.
	35	+	- Remove `--brainstorm`, `--writing-plan`, and the Superpowers dependency.
	36	+	- Preserve Auggie prompt enhancement and architect modes.
	37	+	- Route discovery, specifications, tracer-bullet tickets, TDD, diagnosis, and wayfinding through explicit namespaced Matt skills.
	38	+	- Override automatic commits with review, validation, and explicit approval.
	39	+
	40	+	### PB-006: Add AgentMemory continuity
	41	+
	42	+	- Require a committed stable `.agentmemory-project` identity.
	43	+	- Verify the shared AgentMemory server and Claude/Codex plugins before payload input.
	44	+	- Allow only an explicitly approved interactive degraded mode when memory is unavailable.
	45	+	- Pass one memory scope through Claude and inherited Codex processes.
	46	+	- Require project-scoped recall and one canonical `workflow_status` checkpoint in both standard and architect skills.
	47	+	- Add network-free tests for project identity, memory preflight outcomes, recall prompts, and child environment propagation.
	48	+
32	49		## Completed outside this repository
33	50
34	51		### ZS-001: Migrate the Zsh Setup launcher

plan_build.zsh

			@@ -4,7 +4,7 @@
4	4		# command seams can be replaced by the test suite.
5	5
6	6		_plan_build_usage() {
7		-	print -r -- "Usage: plan_build [--yolo] [--prompt] [--brainstorm \| --writing-plan]
	7	+	print -r -- "Usage: plan_build [--yolo] [--prompt]
8	8		plan_build --architect [--new] [--yolo]"
9	9		}
10	10
			@@ -218,55 +218,272 @@ _plan_build_confirm_enhanced_prompt() {
218	218		[[ "$reply" == (y\|Y\|yes\|YES\|Yes) ]]
219	219		}
220	220
221		-	_plan_build_superpowers_state() {
222		-	awk '
223		-	BEGIN { RS = "}"; state = "missing"; printed = 0 }
224		-	/"id"[[:space:]]:[[:space:]]"superpowers@claude-plugins-official"/ {
225		-	state = "installed"
226		-	if ($0 ~ /"enabled"[[:space:]]:[[:space:]]true/) state = "enabled"
227		-	else if ($0 ~ /"enabled"[[:space:]]:[[:space:]]false/) state = "disabled"
228		-	print state
	221	+	_plan_build_claude_plugin_state() {
	222	+	local plugin_id="$1"
	223	+	awk -v plugin_id="$plugin_id" '
	224	+	$0 ~ plugin_id {
	225	+	found = 1
	226	+	next
	227	+	}
	228	+	found && /Status:/ {
	229	+	if ($0 ~ /enabled/) print "enabled"
	230	+	else print "disabled"
	231	+	printed = 1
	232	+	exit
	233	+	}
	234	+	found && /❯/ {
	235	+	print "installed"
229	236		printed = 1
230	237		exit
231	238		}
232		-	END { if (!printed) print state }
	239	+	END { if (!printed) print found ? "installed" : "missing" }
233	240		'
234	241		}
235	242
236		-	_plan_build_superpowers_preflight() {
237		-	local plugin_json plugin_state
238		-
	243	+	_plan_build_safe_mode_preflight() {
239	244		case "${CLAUDE_CODE_SAFE_MODE:-}" in
240	245		1\|true\|TRUE\|yes\|YES\|on\|ON)
241		-	print -r -- "❌ Error: Claude Code safe mode disables Superpowers."
242		-	print -r -- "Unset CLAUDE_CODE_SAFE_MODE before using --brainstorm or --writing-plan."
	246	+	print -r -- "Error: Claude Code safe mode disables the Matt Pocock and AgentMemory plugins."
	247	+	print -r -- "Unset CLAUDE_CODE_SAFE_MODE before using plan_build."
243	248		return 1
244	249		;;
245	250		esac
246		-	if ! plugin_json="$(command claude plugin list --json 2>/dev/null)"; then
247		-	print -r -- "❌ Error: Unable to inspect Claude Code plugins."
	251	+	}
	252	+
	253	+	_plan_build_matt_preflight() {
	254	+	local plugin_json plugin_state
	255	+
	256	+	if ! plugin_json="$(command claude plugin list 2>/dev/null)"; then
	257	+	print -r -- "Error: Unable to inspect Claude Code plugins."
248	258		print -r -- "Run 'claude plugin list' to diagnose the problem."
249	259		return 1
250	260		fi
251		-	plugin_state="$(print -r -- "$plugin_json" \| _plan_build_superpowers_state)"
	261	+	plugin_state="$(print -r -- "$plugin_json" \| _plan_build_claude_plugin_state \
	262	+	"mattpocock-skills@mattpocock")"
252	263		case "$plugin_state" in
253	264		enabled) return 0 ;;
254	265		disabled)
255		-	print -r -- "❌ Error: Claude Code Superpowers is installed but disabled."
256		-	print -r -- "Enable it with: claude plugin enable superpowers@claude-plugins-official"
	266	+	print -r -- "Error: Matt Pocock skills are installed in Claude Code but disabled."
	267	+	print -r -- "Enable the mattpocock-skills@mattpocock plugin, then retry."
257	268		;;
258	269		missing)
259		-	print -r -- "❌ Error: Claude Code Superpowers is required for --brainstorm and --writing-plan."
260		-	print -r -- "Install it in Claude Code with: /plugin install superpowers@claude-plugins-official"
	270	+	print -r -- "Error: Matt Pocock skills are required for the default workflow."
	271	+	print -r -- "Install the mattpocock-skills@mattpocock Claude Code plugin, then retry."
261	272		;;
262	273		*)
263		-	print -r -- "❌ Error: Unable to determine Claude Code Superpowers status."
	274	+	print -r -- "Error: Unable to determine Matt Pocock plugin status."
264	275		print -r -- "Run 'claude plugin list' to diagnose the problem."
265	276		;;
266	277		esac
267	278		return 1
268	279		}
269	280
	281	+	_plan_build_agentmemory_health() {
	282	+	local pid exit_status waited=0
	283	+	command -v agentmemory >/dev/null 2>&1 \|\| return 2
	284	+	command agentmemory status >/dev/null 2>&1 &
	285	+	pid=$!
	286	+	while kill -0 "$pid" >/dev/null 2>&1; do
	287	+	if (( waited >= 10 )); then
	288	+	kill "$pid" >/dev/null 2>&1 \|\| true
	289	+	wait "$pid" >/dev/null 2>&1 \|\| true
	290	+	return 124
	291	+	fi
	292	+	sleep 1
	293	+	waited=$((waited + 1))
	294	+	done
	295	+	wait "$pid"
	296	+	exit_status=$?
	297	+	return "$exit_status"
	298	+	}
	299	+
	300	+	_plan_build_claude_agentmemory_state() {
	301	+	local plugin_json
	302	+	plugin_json="$(command claude plugin list 2>/dev/null)" \|\| return 1
	303	+	print -r -- "$plugin_json" \| _plan_build_claude_plugin_state \
	304	+	"agentmemory@agentmemory"
	305	+	}
	306	+
	307	+	_plan_build_codex_agentmemory_state() {
	308	+	local plugin_list
	309	+	plugin_list="$(command codex plugin list 2>/dev/null)" \|\| return 1
	310	+	print -r -- "$plugin_list" \| _plan_build_codex_plugin_state
	311	+	}
	312	+
	313	+	_plan_build_codex_plugin_state() {
	314	+	awk '
	315	+	$1 == "agentmemory@agentmemory" {
	316	+	if ($0 ~ /installed, enabled/) print "enabled"
	317	+	else print "disabled"
	318	+	found = 1
	319	+	exit
	320	+	}
	321	+	END { if (!found) print "missing" }
	322	+	'
	323	+	}
	324	+
	325	+	_plan_build_agentmemory_check() {
	326	+	local claude_state codex_state failed=0 health_status
	327	+
	328	+	_plan_build_agentmemory_health
	329	+	health_status=$?
	330	+	case "$health_status" in
	331	+	0) ;;
	332	+	2)
	333	+	print -r -- "AgentMemory CLI is not installed or not in PATH."
	334	+	print -r -- "Install @agentmemory/agentmemory, then retry."
	335	+	failed=1
	336	+	;;
	337	+	124)
	338	+	print -r -- "AgentMemory status check timed out after 10 seconds."
	339	+	failed=1
	340	+	;;
	341	+	*)
	342	+	print -r -- "AgentMemory server is unavailable."
	343	+	failed=1
	344	+	;;
	345	+	esac
	346	+	claude_state="$(_plan_build_claude_agentmemory_state)" \|\| claude_state="unknown"
	347	+	if [[ "$claude_state" != enabled ]]; then
	348	+	print -r -- "Claude Code AgentMemory plugin state: $claude_state."
	349	+	failed=1
	350	+	fi
	351	+	codex_state="$(_plan_build_codex_agentmemory_state)" \|\| codex_state="unknown"
	352	+	if [[ "$codex_state" != enabled ]]; then
	353	+	print -r -- "Codex AgentMemory plugin state: $codex_state."
	354	+	failed=1
	355	+	fi
	356	+
	357	+	(( failed == 0 ))
	358	+	}
	359	+
	360	+	_plan_build_confirm_memory_action() {
	361	+	local reply
	362	+
	363	+	if ! _plan_build_has_tty; then
	364	+	print -r -- "Error: AgentMemory preflight failed without an interactive terminal."
	365	+	return 1
	366	+	fi
	367	+	printf "AgentMemory preflight failed. [r]etry, [c]ontinue without memory, or [s]top? " >/dev/tty
	368	+	if ! IFS= read -r reply </dev/tty; then
	369	+	return 1
	370	+	fi
	371	+	_plan_build_memory_action_from_reply "$reply"
	372	+	}
	373	+
	374	+	_plan_build_memory_action_from_reply() {
	375	+	local reply="$1"
	376	+	case "$reply" in
	377	+	r\|R\|retry\|Retry\|RETRY) return 2 ;;
	378	+	c\|C\|continue\|Continue\|CONTINUE) return 0 ;;
	379	+	*) return 1 ;;
	380	+	esac
	381	+	}
	382	+
	383	+	_plan_build_agentmemory_preflight() {
	384	+	local action_status
	385	+
	386	+	while ! _plan_build_agentmemory_check; do
	387	+	_plan_build_confirm_memory_action
	388	+	action_status=$?
	389	+	if (( action_status == 2 )); then
	390	+	continue
	391	+	elif (( action_status == 0 )); then
	392	+	print -r -- "Warning: Continuing in explicitly approved memoryless mode."
	393	+	REPLY="degraded"
	394	+	return 0
	395	+	fi
	396	+	print -r -- "Memory preflight was not approved; Claude was not launched."
	397	+	return 1
	398	+	done
	399	+	REPLY="required"
	400	+	}
	401	+
	402	+	_plan_build_project_root() {
	403	+	command git rev-parse --show-toplevel 2>/dev/null
	404	+	}
	405	+
	406	+	_plan_build_project_id_is_valid() {
	407	+	[[ "$1" =~ '^[A-Za-z0-9][A-Za-z0-9._:/-]{1,127}$' ]]
	408	+	}
	409	+
	410	+	_plan_build_default_project_id() {
	411	+	local root="$1" remote is_url=0
	412	+	remote="$(command git -C "$root" remote get-url origin 2>/dev/null)" \|\| return 1
	413	+	[[ "$remote" == :// ]] && is_url=1
	414	+	remote="${remote#*://}"
	415	+	remote="${remote#*@}"
	416	+	if (( ! is_url )) && [[ "$remote" == : ]]; then
	417	+	remote="${remote%%:}/${remote#:}"
	418	+	fi
	419	+	remote="${remote%.git}"
	420	+	[[ -n "$remote" ]] \|\| return 1
	421	+	print -r -- "$remote"
	422	+	}
	423	+
	424	+	_plan_build_initialize_project_id() {
	425	+	local root="$1" candidate reply
	426	+
	427	+	if ! _plan_build_has_tty; then
	428	+	print -r -- "Error: Missing $root/.agentmemory-project and no interactive terminal is available."
	429	+	return 1
	430	+	fi
	431	+	candidate="$(_plan_build_default_project_id "$root")" \|\| candidate=""
	432	+	if [[ -n "$candidate" ]] && ! _plan_build_project_id_is_valid "$candidate"; then
	433	+	candidate=""
	434	+	fi
	435	+	if [[ -n "$candidate" ]]; then
	436	+	printf "Create .agentmemory-project with ID '%s'? (Y/n) " "$candidate" >/dev/tty
	437	+	if ! IFS= read -r reply </dev/tty; then
	438	+	return 1
	439	+	fi
	440	+	case "$reply" in
	441	+	n\|N\|no\|No\|NO) candidate="" ;;
	442	+	esac
	443	+	fi
	444	+	if [[ -z "$candidate" ]]; then
	445	+	printf "Enter a stable AgentMemory project ID: " >/dev/tty
	446	+	if ! IFS= read -r candidate </dev/tty; then
	447	+	return 1
	448	+	fi
	449	+	fi
	450	+	if ! _plan_build_project_id_is_valid "$candidate"; then
	451	+	print -r -- "Error: Project ID must be 2-128 characters using letters, numbers, '.', '_', ':', '/', or '-'."
	452	+	return 1
	453	+	fi
	454	+	print -r -- "$candidate" >\| "$root/.agentmemory-project" \|\| return 1
	455	+	print -r -- "Created $root/.agentmemory-project. Commit it, then rerun plan_build."
	456	+	return 1
	457	+	}
	458	+
	459	+	_plan_build_resolve_project_id() {
	460	+	local root project_file project_id committed_id
	461	+	root="$(_plan_build_project_root)" \|\| return 1
	462	+	project_file="$root/.agentmemory-project"
	463	+	if [[ ! -e "$project_file" ]]; then
	464	+	_plan_build_initialize_project_id "$root"
	465	+	return $?
	466	+	fi
	467	+	if [[ ! -f "$project_file" \|\| ! -r "$project_file" ]]; then
	468	+	print -r -- "Error: AgentMemory project ID file is not a readable regular file: $project_file"
	469	+	return 1
	470	+	fi
	471	+	project_id="$(<"$project_file")"
	472	+	if ! _plan_build_project_id_is_valid "$project_id"; then
	473	+	print -r -- "Error: Invalid AgentMemory project ID in $project_file"
	474	+	return 1
	475	+	fi
	476	+	committed_id="$(command git -C "$root" show HEAD:.agentmemory-project 2>/dev/null)" \|\| {
	477	+	print -r -- "Error: .agentmemory-project must be committed before plan_build can use it."
	478	+	return 1
	479	+	}
	480	+	if [[ "$project_id" != "$committed_id" ]]; then
	481	+	print -r -- "Error: Working-tree .agentmemory-project differs from the committed identity."
	482	+	return 1
	483	+	fi
	484	+	REPLY="$project_id"
	485	+	}
	486	+
270	487		_plan_build_is_worktree() {
271	488		local inside_work_tree
272	489		inside_work_tree="$(command git rev-parse --is-inside-work-tree 2>/dev/null)" \|\| return 1
			@@ -277,12 +494,11 @@ _plan_build_has_tty() {
277	494		(: </dev/tty) 2>/dev/null
278	495		}
279	496
280		-	_plan_build_architect_preflight() {
281		-	local skill_path="${PLAN_BUILD_ARCHITECT_SKILL_PATH:-$HOME/.claude/skills/plan-build-architect/SKILL.md}"
	497	+	_plan_build_common_preflight() {
	498	+	local skill_path="$1" require_matt="$2"
282	499
283	500		if ! _plan_build_has_tty; then
284		-	print -r -- "❌ Error: Architect mode requires an interactive terminal."
285		-	print -r -- "Run plan_build --architect from an interactive terminal."
	501	+	print -r -- "Error: plan_build requires an interactive terminal."
286	502		return 1
287	503		fi
288	504		_plan_build_require_cli claude "Claude Code CLI" \|\| return 1
			@@ -290,24 +506,32 @@ _plan_build_architect_preflight() {
290	506		_plan_build_require_cli coderabbit "CodeRabbit CLI" \|\| return 1
291	507		_plan_build_require_cli git "Git CLI" \|\| return 1
292	508		if ! _plan_build_is_worktree; then
293		-	print -r -- "❌ Error: Architect mode must run inside a Git worktree."
294		-	print -r -- "Change to a Git worktree, then retry plan_build --architect."
	509	+	print -r -- "Error: plan_build must run inside a Git worktree."
	510	+	print -r -- "Change to a checked-out Git worktree, then retry."
295	511		return 1
296	512		fi
297	513		if [[ ! -r "$skill_path" \|\| ! -s "$skill_path" ]]; then
298		-	print -r -- "❌ Error: Architect skill is missing, unreadable, or empty: $skill_path"
299		-	print -r -- "Install a readable, non-empty plan-build-architect skill at that path."
	514	+	print -r -- "Error: Workflow skill is missing, unreadable, or empty: $skill_path"
300	515		return 1
301	516		fi
	517	+	_plan_build_safe_mode_preflight \|\| return 1
	518	+	if (( require_matt )); then
	519	+	_plan_build_matt_preflight \|\| return 1
	520	+	fi
302	521		}
303	522
304	523		_plan_build_launch_claude() {
305		-	local use_yolo="$1"
306		-	shift
	524	+	local use_yolo="$1" project_id="$2" memory_mode="$3"
	525	+	local inject_context="true"
	526	+	shift 3
	527	+	[[ "$memory_mode" == degraded ]] && inject_context="false"
307	528		if (( use_yolo )); then
308		-	command claude --dangerously-skip-permissions "$@"
	529	+	AGENTMEMORY_PROJECT_NAME="$project_id" AGENTMEMORY_INJECT_CONTEXT="$inject_context" \
	530	+	PLAN_BUILD_MEMORY_MODE="$memory_mode" \
	531	+	command claude --dangerously-skip-permissions "$@"
309	532		else
310		-	command claude "$@"
	533	+	AGENTMEMORY_PROJECT_NAME="$project_id" AGENTMEMORY_INJECT_CONTEXT="$inject_context" \
	534	+	PLAN_BUILD_MEMORY_MODE="$memory_mode" command claude "$@"
311	535		fi
312	536		}
313	537
			@@ -328,8 +552,8 @@ plan_build() {
328	552		emulate -L zsh
329	553		setopt localtraps
330	554		local use_yolo=0 use_architect=0 use_new=0 enhance_payload=0
331		-	local planning_mode="standard"
332		-	local payload enhanced_file= confirm_status enhance_status planning_instruction architect_start_mode
	555	+	local payload enhanced_file= confirm_status enhance_status architect_start_mode
	556	+	local project_id memory_mode
333	557		local standard_skill="${PLAN_BUILD_SKILL_PATH:-$HOME/.claude/skills/plan-build/SKILL.md}"
334	558		local architect_skill="${PLAN_BUILD_ARCHITECT_SKILL_PATH:-$HOME/.claude/skills/plan-build-architect/SKILL.md}"
335	559
			@@ -371,32 +595,6 @@ plan_build() {
371	595		}
372	596		enhance_payload=1
373	597		;;
374		-	--brainstorm)
375		-	[[ "$planning_mode" == brainstorm ]] && {
376		-	print -r -- "Error: Duplicate argument: --brainstorm"
377		-	_plan_build_usage
378		-	return 1
379		-	}
380		-	[[ "$planning_mode" != standard ]] && {
381		-	print -r -- "Error: --brainstorm and --writing-plan are mutually exclusive."
382		-	_plan_build_usage
383		-	return 1
384		-	}
385		-	planning_mode="brainstorm"
386		-	;;
387		-	--writing-plan)
388		-	[[ "$planning_mode" == writing-plan ]] && {
389		-	print -r -- "Error: Duplicate argument: --writing-plan"
390		-	_plan_build_usage
391		-	return 1
392		-	}
393		-	[[ "$planning_mode" != standard ]] && {
394		-	print -r -- "Error: --brainstorm and --writing-plan are mutually exclusive."
395		-	_plan_build_usage
396		-	return 1
397		-	}
398		-	planning_mode="writing-plan"
399		-	;;
400	598		*)
401	599		print -r -- "Error: Unknown argument: $1"
402	600		_plan_build_usage
			@@ -411,28 +609,26 @@ plan_build() {
411	609		_plan_build_usage
412	610		return 1
413	611		fi
414		-	if (( use_architect && enhance_payload )) \|\|
415		-	{ (( use_architect )) && [[ "$planning_mode" != standard ]]; }; then
	612	+	if (( use_architect && enhance_payload )); then
416	613		print -r -- "Error: --architect may combine only with --new and --yolo."
417	614		_plan_build_usage
418	615		return 1
419	616		fi
420	617
421	618		if (( use_architect )); then
422		-	_plan_build_architect_preflight \|\| return 1
	619	+	_plan_build_common_preflight "$architect_skill" 0 \|\| return 1
423	620		else
424		-	_plan_build_require_cli claude "Claude Code CLI" \|\| return 1
425		-	if [[ "$planning_mode" != standard ]]; then
426		-	_plan_build_superpowers_preflight \|\| return 1
427		-	fi
428		-	_plan_build_require_cli codex "Codex CLI" \|\| return 1
429		-	_plan_build_require_cli coderabbit "CodeRabbit CLI" \|\| return 1
	621	+	_plan_build_common_preflight "$standard_skill" 1 \|\| return 1
430	622		if (( enhance_payload )); then
431	623		_plan_build_require_cli auggie "Auggie CLI" \|\| return 1
432	624		_plan_build_require_cli script "script utility" \|\| return 1
433	625		_plan_build_require_cli perl "Perl" \|\| return 1
434	626		fi
435	627		fi
	628	+	_plan_build_resolve_project_id \|\| return 1
	629	+	project_id="$REPLY"
	630	+	_plan_build_agentmemory_preflight \|\| return 1
	631	+	memory_mode="$REPLY"
436	632
437	633		print -r -- "📥 Reading payload... Type 'EOF' on a new line and press Enter when finished."
438	634		payload="$(_plan_build_read_payload)"
			@@ -481,7 +677,10 @@ plan_build() {
481	677		architect_start_mode="Start mode: safe-resume-detection. Safely detect whether an existing architecture planning session should be resumed; do not archive or replace it automatically."
482	678		fi
483	679		print -r -- "🚀 Launching Claude Code in architect mode..."
484		-	_plan_build_launch_claude "$use_yolo" "Read \`$architect_skill\` and follow it strictly, including every gate even when permissive Claude execution is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement.
	680	+	_plan_build_launch_claude "$use_yolo" "$project_id" "$memory_mode" "Read \`$architect_skill\` and follow it strictly, including every gate even when permissive Claude execution is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement.
	681	+
	682	+	AgentMemory project: $project_id
	683	+	Memory mode: $memory_mode. Run the skill's mandatory recall gate before workflow detection or repository modification. Pass this same project identity to every Codex process.
485	684
486	685		$architect_start_mode
487	686
			@@ -491,22 +690,11 @@ $payload"
491	690		return $?
492	691		fi
493	692
494		-	case "$planning_mode" in
495		-	brainstorm)
496		-	planning_instruction="Planning mode: brainstorm. Use the superpowers:brainstorming skill, including its approval gates and transition to superpowers:writing-plans. After the implementation plan is saved, return to the plan-build workflow for Codex plan review before implementation."
497		-	;;
498		-	writing-plan)
499		-	planning_instruction="Planning mode: writing-plan. Use the superpowers:writing-plans skill with the payload as the requirements. After the implementation plan is saved, return to the plan-build workflow for Codex plan review before implementation."
500		-	;;
501		-	*)
502		-	planning_instruction="Planning mode: standard. Create the workflow's normal short implementation plan."
503		-	;;
504		-	esac
505		-
506		-	print -r -- "🚀 Launching Claude Code with your multi-agent workflow (${planning_mode} planning)..."
507		-	_plan_build_launch_claude "$use_yolo" "Please read \`$standard_skill\` and strictly follow the 8-step multi-agent workflow to implement the following task.
	693	+	print -r -- "🚀 Launching Claude Code with the memory-aware Matt workflow..."
	694	+	_plan_build_launch_claude "$use_yolo" "$project_id" "$memory_mode" "Read \`$standard_skill\` and strictly follow its memory-aware Matt Pocock workflow.
508	695
509		-	$planning_instruction
	696	+	AgentMemory project: $project_id
	697	+	Memory mode: $memory_mode. Run the mandatory recall gate before routing or modifying the repository. Pass this same project identity to every Codex process.
510	698
511	699		$payload"
512	700		}

Vernon Wee Hong KOH ревизій цього gist 3 weeks ago. До ревизії

7 files changed, 52 insertions, 32 deletions

ADR.md

			@@ -6,9 +6,9 @@
6	6
7	7		The implementation previously lived inside the broad Zsh Setup `func` file while its workflows and history were spread across that repository. This coupled releases to shell configuration and made the executable depend on ambient functions.
8	8
9		-	The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, Superpowers, Git-worktree, architect-preflight, payload, and Claude-launch helpers. Zsh Setup will eventually retain only an atomic cache launcher and skill downloader.
	9	+	The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, Superpowers, Git-worktree, architect-preflight, payload, and Claude-launch helpers. Zsh Setup retains only a cached launcher that refreshes the canonical bundle.
10	10
11		-	The old launcher migration is a separate, still-pending change because this extraction must not modify the source repository.
	11	+	The Zsh Setup migration is maintained separately from the canonical executable so shell installation concerns do not leak back into this repository.
12	12
13	13		## ADR-002: Keep one supported workflow surface
14	14
			@@ -30,8 +30,8 @@ This avoids multiple remote implementations and prevents documentation drift.
30	30
31	31		The executable is sourceable and its `_plan_build_` helpers form test seams. Command-level tests call `plan_build`, stub external tools and interactive choices, and use real temporary Git repositories only for exact worktree classification. Tests never use the network.
32	32
33		-	## ADR-005: Validate mutable cache updates before atomic activation
	33	+	## ADR-005: Activate immutable complete releases through one symlink
34	34
35	35		Status: Accepted
36	36
37		-	The thin launcher must stage `plan_build.zsh` beside its cache target, reject empty downloads and files that fail `zsh -n`, and only then atomically rename the candidate into place. The mutable HTTPS `HEAD` URL is the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content or establish update provenance.
	37	+	The thin launcher stages `plan_build.zsh`, `SKILL.md`, and `ARCHITECT.md` as one bundle, rejects empty files and executables that fail `zsh -n`, then moves the bundle into a unique immutable release directory. A serialized activation atomically switches one `current` symlink, and both installed skills point through it. Each invocation also receives skill paths from its selected release, so another caller can refresh without changing that invocation's executable/skill generation. The mutable HTTPS `HEAD` URL remains the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content, establish update provenance, or make the three separate requests one remote snapshot.

CHANGELOG.md

			@@ -16,14 +16,10 @@
16	16		- Plan-build-specific implementation and documentation now belong to the dedicated `plan-build` gist rather than the Zsh Setup repository.
17	17		- `--yolo` is translated to Claude Code's `--dangerously-skip-permissions` argument.
18	18		- Active workflow documentation no longer describes removed v2 or distribution modes.
19		-	- Prompt enhancement now uses valid, immediately flushed platform `script` invocations, propagates natural child failures, and cleans up temporary state and child processes on return or interruption.
20		-	- The cache contract now rejects empty or syntactically invalid downloads before atomic activation and identifies mutable HTTPS `HEAD` as the update trust boundary.
	19	+	- Prompt enhancement now uses valid, immediately flushed platform `script` invocations, including util-linux `script -e` for child-status propagation, and cleans up temporary state and child processes on return or interruption.
	20	+	- The Zsh Setup cache contract now activates immutable three-file releases through one atomic `current` symlink and identifies mutable HTTPS `HEAD` as the update trust boundary.
21	21
22	22		### Removed
23	23
24	24		- Dependence on `~/.func` and ambient shell functions.
25	25		- The obsolete v2 downloader and its former workflow variants.
26		-
27		-	### Pending
28		-
29		-	- The Zsh Setup repository still needs a separate migration to the thin atomic-cache launcher. This extraction does not claim that migration is complete.

README.md

			@@ -74,30 +74,36 @@ plan_build --architect --yolo Architect with permissive proces
74	74
75	75		The user-facing `--yolo` option is translated to Claude Code's `--dangerously-skip-permissions` argument. It never bypasses approval gates defined by either workflow.
76	76
77		-	## Cache-launcher integration contract
	77	+	## Zsh Setup cache launcher
78	78
79		-	The future thin Zsh Setup launcher must download:
	79	+	When curl is available, the Zsh Setup integration attempts to download this complete release bundle on every invocation:
80	80
81	81		```text
82	82		https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
	83	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
	84	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
83	85		```
84	86
85		-	It must download into a temporary file beside the cache target, validate that the download succeeded, is non-empty, and passes `zsh -n`, then atomically rename it into place. It invokes the cached program exactly as:
	87	+	It stages all three non-empty files, requires `plan_build.zsh` to pass `zsh -n`, moves the bundle into a unique immutable release directory, and atomically switches a single `current` symlink. Activation is serialized with a kernel-backed Zsh file lock. Failed refreshes leave the prior validated release active and repair its skill links before execution.
	88	+
	89	+	The launcher invokes the executable from the selected immutable release and binds both internal skill paths to that same release:
86	90
87	91		```zsh
88		-	zsh <cache> "$@"
	92	+	PLAN_BUILD_SKILL_PATH=<selected-release>/SKILL.md \
	93	+	PLAN_BUILD_ARCHITECT_SKILL_PATH=<selected-release>/ARCHITECT.md \
	94	+	zsh <selected-release>/plan_build.zsh "$@"
89	95		```
90	96
91		-	This mutable HTTPS `HEAD` download is the explicit update trust boundary: transport security authenticates the server, but the URL provides neither immutable-version pinning nor content-integrity verification. Atomic activation and syntax validation prevent partial or syntactically invalid cache entries; they do not establish provenance for changed remote content.
	97	+	It never sources remote code into the caller shell. The mutable HTTPS `HEAD` download is the explicit update trust boundary: transport security authenticates the server, but the URL provides neither immutable-version pinning nor content-integrity verification. Complete-release activation and syntax validation prevent partial or syntactically invalid active releases; they do not establish provenance or guarantee that three independent downloads observed the same remote revision if publication occurs during refresh.
92	98
93		-	The same launcher or installer downloads `SKILL.md` and `ARCHITECT.md` from the same gist to:
	99	+	The installed Claude skill files are symlinks through the same `current` release:
94	100
95	101		```text
96	102		~/.claude/skills/plan-build/SKILL.md
97	103		~/.claude/skills/plan-build-architect/SKILL.md
98	104		```
99	105
100		-	The launcher migration in the Zsh Setup repository is not part of this extraction and is not yet complete.
	106	+	The launcher defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/plan-build`; Zsh Setup exposes `PLAN_BUILD_CACHE_DIR` and `PLAN_BUILD_BASE_URL` overrides. Skill paths stay fixed at `~/.claude/skills` to match the canonical executable.
101	107
102	108		## Testing
103	109

SPEC.md

			@@ -53,23 +53,29 @@ The canonical repository sources are `SKILL.md` and `ARCHITECT.md`.
53	53		- Tests use no network and do not launch real agent CLIs.
54	54		- The program remains sourceable and runs main only when executed directly.
55	55
56		-	## Thin-launcher integration
	56	+	## Zsh Setup launcher integration
57	57
58		-	A future Zsh Setup launcher will download:
	58	+	A thin Zsh Setup launcher downloads one release bundle:
59	59
60	60		```text
61	61		https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
	62	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
	63	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
62	64		```
63	65
64		-	It must write to a temporary file in the cache directory, require the download to be non-empty and pass `zsh -n`, make the validated file atomically visible, then execute:
	66	+	It must stage all three files, require each to be non-empty, and require the executable to pass `zsh -n`. A validated bundle moves into a unique immutable release directory. Activation is serialized by a kernel-backed Zsh file lock and occurs by atomically replacing one `current` symlink. The installed skill paths symlink to `SKILL.md` and `ARCHITECT.md` through `current`, so executable and skills always resolve through one release boundary. Cached fallback repairs missing or stale skill links before execution.
	67	+
	68	+	The launcher executes the selected release with `PLAN_BUILD_SKILL_PATH` and `PLAN_BUILD_ARCHITECT_SKILL_PATH` bound to that same immutable directory:
65	69
66	70		```text
67		-	zsh <cache> "$@"
	71	+	PLAN_BUILD_SKILL_PATH=<selected-release>/SKILL.md \
	72	+	PLAN_BUILD_ARCHITECT_SKILL_PATH=<selected-release>/ARCHITECT.md \
	73	+	zsh <selected-release>/plan_build.zsh "$@"
68	74		```
69	75
70		-	The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS authenticates the transport endpoint, but without an immutable version or pinned digest it does not provide content-integrity or provenance guarantees for updates.
	76	+	It does not source the downloaded executable. Refresh failure falls back to the last complete validated release; without one, launch fails. Curl is optional only when that fallback exists. Signals stop an in-flight refresh, clean temporary state, and return the conventional signal status.
71	77
72		-	It will download `SKILL.md` and `ARCHITECT.md` from the same gist into the installed skill paths above. Migration of that old launcher is deliberately outside this repository and is not yet complete.
	78	+	The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS authenticates the transport endpoint, but without an immutable version or pinned digest it does not provide content-integrity or provenance guarantees for updates. Because the three files are separate requests, publication during refresh can also expose different remote revisions; publishers should update the gist only from complete, tested commits.
73	79
74	80		## Acceptance criteria
75	81
			@@ -80,3 +86,4 @@ It will download `SKILL.md` and `ARCHITECT.md` from the same gist into the insta
80	86		- Prompt enhancement cannot launch Claude without explicit approval.
81	87		- `--yolo` reaches the Claude binary only as `--dangerously-skip-permissions`.
82	88		- Syntax checks, command tests, and `git diff --check` pass.
	89	+	- The Zsh Setup launcher activates and falls back only in complete three-file releases.

TASKS.md

			@@ -29,16 +29,16 @@
29	29		- Cover all modes, invalid combinations, preflight ordering, safe-resume/new architect prompts, and normal versus bare Git repositories.
30	30		- Keep the suite network-free.
31	31
32		-	## Pending outside this repository
	32	+	## Completed outside this repository
33	33
34	34		### ZS-001: Migrate the Zsh Setup launcher
35	35
36		-	Replace the old in-repository function with a thin atomic-cache launcher that downloads the canonical executable and skills from the `plan-build` gist. This task belongs to the Zsh Setup repository and is not complete.
	36	+	Replace the old in-repository implementation with a thin cached launcher that downloads the canonical executable and skills from the `plan-build` gist. The Zsh Setup migration now uses immutable complete release directories, a serialized atomic `current` symlink switch, and skill links through that same release.
37	37
38	38		Required launcher contract:
39	39
40	40		```text
41		-	zsh <cache> "$@"
	41	+	zsh <selected-release>/plan_build.zsh "$@"
42	42		```
43	43
44	44		Required remote files:

plan_build.zsh

			@@ -83,7 +83,7 @@ _plan_build_start_auggie_script() {
83	83		AUGGIE_WORKSPACE="$workspace" AUGGIE_CACHE_DIR="$cache_dir" \
84	84		AUGGIE_AUTH_FILE="$auth_file" AUGGIE_PROMPT_FILE="$prompt_file" \
85	85		AUGGIE_INDEXING="$use_project_context" \
86		-	command script -q -f -O "$log_file" -c '
	86	+	command script -q -f -e -O "$log_file" -c '
87	87		if [ "$AUGGIE_INDEXING" = 1 ]; then
88	88		exec auggie --print --enhance-prompt --workspace-root "$AUGGIE_WORKSPACE" --augment-cache-dir "$AUGGIE_CACHE_DIR" --augment-session-json "$AUGGIE_AUTH_FILE" --allow-indexing --wait-for-indexing --dont-save-session --instruction-file "$AUGGIE_PROMPT_FILE"
89	89		else
			@@ -278,7 +278,7 @@ _plan_build_has_tty() {
278	278		}
279	279
280	280		_plan_build_architect_preflight() {
281		-	local skill_path="$HOME/.claude/skills/plan-build-architect/SKILL.md"
	281	+	local skill_path="${PLAN_BUILD_ARCHITECT_SKILL_PATH:-$HOME/.claude/skills/plan-build-architect/SKILL.md}"
282	282
283	283		if ! _plan_build_has_tty; then
284	284		print -r -- "❌ Error: Architect mode requires an interactive terminal."
			@@ -330,6 +330,8 @@ plan_build() {
330	330		local use_yolo=0 use_architect=0 use_new=0 enhance_payload=0
331	331		local planning_mode="standard"
332	332		local payload enhanced_file= confirm_status enhance_status planning_instruction architect_start_mode
	333	+	local standard_skill="${PLAN_BUILD_SKILL_PATH:-$HOME/.claude/skills/plan-build/SKILL.md}"
	334	+	local architect_skill="${PLAN_BUILD_ARCHITECT_SKILL_PATH:-$HOME/.claude/skills/plan-build-architect/SKILL.md}"
333	335
334	336		trap 'return 130' INT
335	337		trap 'return 143' TERM
			@@ -479,7 +481,7 @@ plan_build() {
479	481		architect_start_mode="Start mode: safe-resume-detection. Safely detect whether an existing architecture planning session should be resumed; do not archive or replace it automatically."
480	482		fi
481	483		print -r -- "🚀 Launching Claude Code in architect mode..."
482		-	_plan_build_launch_claude "$use_yolo" "Read \`~/.claude/skills/plan-build-architect/SKILL.md\` and follow it strictly, including every gate even when permissive Claude execution is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement.
	484	+	_plan_build_launch_claude "$use_yolo" "Read \`$architect_skill\` and follow it strictly, including every gate even when permissive Claude execution is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement.
483	485
484	486		$architect_start_mode
485	487
			@@ -502,7 +504,7 @@ $payload"
502	504		esac
503	505
504	506		print -r -- "🚀 Launching Claude Code with your multi-agent workflow (${planning_mode} planning)..."
505		-	_plan_build_launch_claude "$use_yolo" "Please read \`~/.claude/skills/plan-build/SKILL.md\` and strictly follow the 8-step multi-agent workflow to implement the following task.
	507	+	_plan_build_launch_claude "$use_yolo" "Please read \`$standard_skill\` and strictly follow the 8-step multi-agent workflow to implement the following task.
506	508
507	509		$planning_instruction
508	510

test_plan_build.zsh

			@@ -104,7 +104,7 @@ print -r -- '{}' >\| "$fixture_dir/home/.augment/session.json"
104	104		print -r -- '#!/bin/sh' >\| "$fixture_dir/bin/script"
105	105		print -r -- 'printf "%s\n" "$@" > "$PLAN_BUILD_SCRIPT_ARGS"' >> "$fixture_dir/bin/script"
106	106		print -r -- 'if [ "$1" = -q ] && [ "$2" = -t ]; then log_file=$4; shift 4; "$@" > "$log_file"; exit $?; fi' >> "$fixture_dir/bin/script"
107		-	print -r -- 'log_file=$4; printf "Enhanced prompt: linux result\n" > "$log_file"; exit "${PLAN_BUILD_SCRIPT_STATUS:-0}"' >> "$fixture_dir/bin/script"
	107	+	print -r -- 'log_file=$5; printf "Enhanced prompt: linux result\n" > "$log_file"; exit "${PLAN_BUILD_SCRIPT_STATUS:-0}"' >> "$fixture_dir/bin/script"
108	108		print -r -- '#!/bin/sh' >\| "$fixture_dir/bin/auggie"
109	109		print -r -- 'printf "Enhanced prompt: mac result\n"; exit "${PLAN_BUILD_AUGGIE_STATUS:-0}"' >> "$fixture_dir/bin/auggie"
110	110		chmod +x "$fixture_dir/bin/script" "$fixture_dir/bin/auggie"
			@@ -130,7 +130,8 @@ for platform in Darwin Linux; do
130	130		assert_not_contains "$script_args" $'\ncommand\n' "macOS script excludes shell builtin"
131	131		assert_equal "mac result" "$(<"$enhance_output")" "macOS parsed enhancement"
132	132		else
133		-	assert_contains "$script_args" $'-f\n-O' "Linux script immediate flushing"
	133	+	assert_contains "$script_args" $'-q\n-f' "Linux script immediate flushing"
	134	+	assert_contains "$script_args" $'-e\n-O' "Linux script propagates child status"
134	135		assert_contains "$script_args" "-c" "Linux script command mode"
135	136		assert_equal "linux result" "$(<"$enhance_output")" "Linux parsed enhancement"
136	137		fi
			@@ -149,6 +150,14 @@ assert_equal 7 "$rc" "nonzero Auggie status propagated"
149	150		[[ ! -e "$fixture_dir/failed-enhancement" ]] \|\| fail "failed Auggie output was accepted"
150	151		assert_equal 0 "$(count_matches "$fixture_dir/enhance-tmp" plan-build-auggie)" "failed run directory cleanup"
151	152
	153	+	platform=Linux
	154	+	PLAN_BUILD_SCRIPT_STATUS=7 HOME="$fixture_dir/home" TMPDIR="$fixture_dir/enhance-tmp" \
	155	+	PATH="$fixture_dir/bin:$PATH" PLAN_BUILD_SCRIPT_ARGS="$fixture_dir/script-args" \
	156	+	_plan_build_real_enhance_prompt "partial prompt" "$fixture_dir/failed-linux-enhancement" >/dev/null 2>&1
	157	+	rc=$?
	158	+	assert_equal 7 "$rc" "Linux script child status propagated"
	159	+	[[ ! -e "$fixture_dir/failed-linux-enhancement" ]] \|\| fail "failed Linux Auggie output was accepted"
	160	+
152	161		print -r -- $'noise\r\n\e[32m✨ Enhanced prompt: first\e[0m\r\nsecond\r\n🤖 tool' >\| "$fixture_dir/parser.log"
153	162		_plan_build_parse_auggie_output "$fixture_dir/parser.log" "$fixture_dir/parser.out"
154	163		assert_equal $'first\nsecond' "$(<"$fixture_dir/parser.out")" "parser strips terminal output and stops at marker"

Vernon Wee Hong KOH ревизій цього gist 3 weeks ago. До ревизії

9 files changed, 1452 insertions

ADR.md(файл створено)

		@@ -0,0 +1,37 @@
1	+	# Architecture Decision Records
2	+
3	+	## ADR-001: Make plan-build a dedicated standalone gist
4	+
5	+	Status: Accepted
6	+
7	+	The implementation previously lived inside the broad Zsh Setup `func` file while its workflows and history were spread across that repository. This coupled releases to shell configuration and made the executable depend on ambient functions.
8	+
9	+	The dedicated `plan-build` gist is now canonical for `plan_build.zsh`, `SKILL.md`, `ARCHITECT.md`, tests, and documentation. The executable contains namespaced CLI, Auggie, Superpowers, Git-worktree, architect-preflight, payload, and Claude-launch helpers. Zsh Setup will eventually retain only an atomic cache launcher and skill downloader.
10	+
11	+	The old launcher migration is a separate, still-pending change because this extraction must not modify the source repository.
12	+
13	+	## ADR-002: Keep one supported workflow surface
14	+
15	+	Status: Accepted
16	+
17	+	The supported surface is standard, prompt enhancement, brainstorm, writing-plan, architect, new architect state, and permissive Claude execution. The removed v2 entry point remains rejected as an unknown option, and stale v2-only distribution concepts are not part of the canonical skills.
18	+
19	+	This avoids multiple remote implementations and prevents documentation drift.
20	+
21	+	## ADR-003: Translate convenience flags at the process boundary
22	+
23	+	Status: Accepted
24	+
25	+	`--yolo` remains the plan-build user interface for continuity, but `_plan_build_launch_claude` translates it to Claude Code's actual `--dangerously-skip-permissions` argument. Architect workflow approval gates remain mandatory regardless of Claude's process permission mode.
26	+
27	+	## ADR-004: Test through replaceable command seams
28	+
29	+	Status: Accepted
30	+
31	+	The executable is sourceable and its `_plan_build_` helpers form test seams. Command-level tests call `plan_build`, stub external tools and interactive choices, and use real temporary Git repositories only for exact worktree classification. Tests never use the network.
32	+
33	+	## ADR-005: Validate mutable cache updates before atomic activation
34	+
35	+	Status: Accepted
36	+
37	+	The thin launcher must stage `plan_build.zsh` beside its cache target, reject empty downloads and files that fail `zsh -n`, and only then atomically rename the candidate into place. The mutable HTTPS `HEAD` URL is the explicit update trust boundary: HTTPS protects transport to the endpoint, but does not pin the downloaded content or establish update provenance.

ARCHITECT.md(файл створено)

		@@ -0,0 +1,219 @@
1	+	# Plan Build Architect Workflow
2	+
3	+	Use this workflow only when `plan_build --architect` launches Claude Code. Claude is the lead architect, documentation manager, task dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit is the required automated reviewer.
4	+
5	+	## Non-Negotiable Role Boundary
6	+
7	+	Claude may inspect every project file but may create or modify only:
8	+
9	+	- `SPEC.md`
10	+	- `TASKS.md`
11	+	- `ADR.md`
12	+	- `CHANGELOG.md`
13	+	- `README.md`
14	+	- Markdown files under `docs/`
15	+
16	+	Claude must not write application code, test code, migrations, generated source, or executable configuration. Delegate those changes to Codex through an approved task prompt.
17	+
18	+	Codex must not commit, stage, push, reset, restore, or discard changes. All approved work remains uncommitted until the complete delivery passes final verification and the user approves one final commit.
19	+
20	+	Never push automatically.
21	+
22	+	## Startup Preflight
23	+
24	+	Before discovery or project-file modification:
25	+
26	+	1. Confirm the current directory is a Git worktree.
27	+	2. Record `git status --short` and preserve all pre-existing work.
28	+	3. Confirm an interactive terminal is available.
29	+	4. Confirm `codex`, `coderabbit`, and `git` are available.
30	+	5. Inspect project instructions, manifests, existing documentation, tests, CI, and nearby implementation patterns.
31	+	6. Never request or expose credential values. Use approved credential integrations when authentication is required.
32	+
33	+	If a requirement is missing, stop with exact remediation guidance.
34	+
35	+	## Existing Workflow Detection
36	+
37	+	If `SPEC.md`, `TASKS.md`, `ADR.md`, or `CHANGELOG.md` exists:
38	+
39	+	1. Read all existing workflow records.
40	+	2. Compare their claims with Git and the current worktree.
41	+	3. Identify the first incomplete or inconsistent task.
42	+	4. Present the detected state and ask whether to resume.
43	+
44	+	When the launch instruction says `Start mode: archive-and-start-new`, archive existing workflow documents in a timestamped documentation archive before creating replacements. Never overwrite them silently.
45	+
46	+	## Phase 1: Discovery and Architecture
47	+
48	+	Interview the user until product, architecture, data, integration, operational, security, and handover requirements are clear.
49	+
50	+	Rules:
51	+
52	+	- Ask exactly one question at a time.
53	+	- Include a recommended default answer with every question.
54	+	- Resolve facts from the repository instead of asking the user.
55	+	- Ask the user only for decisions, priorities, business rules, and information that cannot be discovered safely.
56	+	- Probe user roles, workflows, data structures, API or component contracts, technology constraints, integrations, edge cases, failure modes, migration, rollback, testing, deployment, monitoring, security, compliance, support, and ownership.
57	+	- Collect project name, client or owner, purpose, target users, repository scope, supported environments, deployment owner, operational owner, support role, compliance constraints, and intended handover date.
58	+	- Do not implement or dispatch Codex during discovery.
59	+
60	+	Do not enter Phase 2 until the user explicitly states either:
61	+
62	+	- `I am ready to generate the spec`
63	+	- `Phase 1 complete`
64	+
65	+	## Phase 2: Specification
66	+
67	+	After the explicit Phase 1 completion phrase:
68	+
69	+	1. Ask no more discovery questions.
70	+	2. Create or reconcile `SPEC.md` without discarding valid existing content.
71	+	3. Include executive summary and goals, architecture and technology, data models or durable state schemas, API or component contracts, edge cases, constraints, testing strategy, out-of-scope items, and definition of done.
72	+	4. Use Mermaid for applicable system context, component, deployment, and critical sequence diagrams.
73	+	5. Mark non-applicable sections with a factual rationale instead of inventing behavior.
74	+	6. Treat the approved specification as the requirements baseline.
75	+	7. Present the specification and wait for explicit approval.
76	+
77	+	Any later requirement change is a visible amendment. Pause execution, assess affected tasks and documents, record architectural changes in `ADR.md`, and obtain approval before continuing.
78	+
79	+	## Phase 3: Codex Task Plan
80	+
81	+	After `SPEC.md` approval, create or reconcile `TASKS.md`.
82	+
83	+	Use stable task IDs such as `TASK-001`. Allowed states are:
84	+
85	+	- `Pending`
86	+	- `In Progress`
87	+	- `Blocked`
88	+	- `Review`
89	+	- `Complete`
90	+
91	+	Only one task may be `In Progress`.
92	+
93	+	Every task must include:
94	+
95	+	- ID, title, status, and dependencies
96	+	- Objective
97	+	- Exhaustive allowed file scope
98	+	- Context and interfaces
99	+	- Self-contained prompt for Codex
100	+	- Acceptance criteria
101	+	- Unit or integration test requirements
102	+	- Verification commands
103	+	- CodeRabbit outcome
104	+	- Completion evidence
105	+
106	+	Every Codex prompt must explicitly prohibit commits and out-of-scope edits. Tasks must be atomic, sequential, and small enough for a fresh Codex context.
107	+
108	+	Present `TASKS.md` and wait for explicit approval before execution.
109	+
110	+	## Documentation Records
111	+
112	+	Maintain these root engineering records throughout execution:
113	+
114	+	- `SPEC.md`: approved requirements baseline and amendments
115	+	- `TASKS.md`: task state, prompts, reviews, and evidence
116	+	- `ADR.md`: append-only architecture decisions
117	+	- `CHANGELOG.md`: Keep a Changelog-compatible `Unreleased` entries referencing task IDs
118	+	- `README.md`: product overview, prerequisites, quick start, and configuration
119	+
120	+	Every ADR uses a stable ID and records status, date, context, decision, alternatives, consequences, and affected components. Keep superseded decisions and link their replacements.
121	+
122	+	## Mandatory Client Handover Package
123	+
124	+	The following files are mandatory without exception:
125	+
126	+	- `docs/USER_MANUAL.md`
127	+	- `docs/RUNBOOK.md`
128	+	- `docs/API.md`
129	+	- `docs/DEPLOYMENT.md`
130	+	- `docs/SECURITY.md`
131	+	- `docs/HANDOVER.md`
132	+
133	+	Create missing documents and reconcile existing ones. Do not replace valid project-specific content wholesale.
134	+
135	+	When a document or section is not applicable, retain it and state `Not Applicable` with a short factual rationale.
136	+
137	+	Client-facing documents describe the delivered system, not Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless disclosure is contractually required.
138	+
139	+	Implementation claims must reference relevant source files, configuration, schemas, endpoints, or verified commands. Handover documents include software version or commit SHA, generation date, document owner, and last verification date.
140	+
141	+	`docs/HANDOVER.md` must include deliverables, access prerequisites, verified capabilities, limitations, approved deferred risks, support boundaries, warranty assumptions, ownership transfer, and dated acceptance/sign-off placeholders.
142	+
143	+	## Task Execution Loop
144	+
145	+	For each approved task, in dependency order:
146	+
147	+	1. Confirm dependencies are `Complete`.
148	+	2. Set exactly that task to `In Progress`.
149	+	3. Record the current Git status and task baseline.
150	+	4. Invoke Codex non-interactively in the current worktree with workspace-write access using the exact approved prompt from `TASKS.md`.
151	+	5. Capture Codex's result.
152	+	6. Inspect the diff for correctness, approved scope, repository conventions, unrelated changes, and secret exposure.
153	+	7. Independently run the task's verification commands.
154	+	8. Set the task to `Review` and run CodeRabbit on the task diff.
155	+	9. Investigate every concrete finding.
156	+	10. Delegate valid fixes back to Codex within the same task scope.
157	+	11. Rerun focused verification and CodeRabbit after substantive fixes.
158	+	12. Record commands, results, findings, and completion evidence.
159	+	13. Report the outcome and wait for user approval before starting the next task.
160	+
161	+	Use non-interactive Codex execution in this form, adapting only supported sandbox flags to the installed CLI:
162	+
163	+	```bash
164	+	codex exec --sandbox workspace-write "<exact approved task prompt>"
165	+	```
166	+
167	+	Critical, high, and medium CodeRabbit findings block completion. Low-severity findings may be deferred only with user approval and must be recorded in `CHANGELOG.md` and `docs/HANDOVER.md`.
168	+
169	+	## Scope Expansion
170	+
171	+	If Codex reports that required work exceeds the allowed file scope:
172	+
173	+	1. Do not permit out-of-scope edits.
174	+	2. Assess requirement, architecture, dependency, and test impact.
175	+	3. Update `SPEC.md`, `TASKS.md`, and `ADR.md` when appropriate.
176	+	4. Ask the user to approve the revised scope.
177	+	5. Redispatch only after approval.
178	+
179	+	## Failure and Retry Policy
180	+
181	+	Allow the initial Codex attempt plus at most two focused correction attempts.
182	+
183	+	If acceptance still fails:
184	+
185	+	1. Stop the workflow.
186	+	2. Mark the task `Blocked`.
187	+	3. Preserve the partial diff.
188	+	4. Record diagnostics and attempted fixes in task evidence.
189	+	5. Ask whether to revise architecture, scope, or acceptance criteria.
190	+	6. Do not start dependent tasks.
191	+
192	+	If no test framework exists, the first applicable task establishes the smallest project-appropriate validation setup. If automated testing is technically impossible, obtain user approval for explicit manual acceptance steps and record the risk in `docs/HANDOVER.md`.
193	+
194	+	## Security Rules
195	+
196	+	- Never include credential values, tokens, private keys, personal data, or production secrets in prompts or documentation.
197	+	- Document only secret names, required environment variables, approved storage, ownership, and rotation procedures.
198	+	- Use native credential helpers and approved credential stores.
199	+	- Run available secret scanning before final completion.
200	+	- Treat suspected credentials as blocking findings.
201	+
202	+	## Final Review and Single Commit
203	+
204	+	After every task is `Complete`:
205	+
206	+	1. Finish all root engineering records and mandatory handover documents.
207	+	2. Run CodeRabbit over the complete uncommitted diff.
208	+	3. Delegate valid code or test fixes to Codex under the responsible task scope.
209	+	4. Run the complete project lint, type-check, build, and test suite.
210	+	5. Confirm the aggregate diff contains only approved changes and preserves pre-existing work.
211	+	6. Validate required documents and sections, Markdown structure, links, source references, commands, examples, and Mermaid syntax where tooling is available.
212	+	7. Ensure no unresolved `TODO`, placeholder, or template text remains. Approved limitations belong in `docs/HANDOVER.md`.
213	+	8. Run available secret scanning.
214	+	9. Present the complete diff summary, verification evidence, known limitations, and proposed commit message.
215	+	10. Wait for explicit user approval.
216	+	11. Stage only approved files and create one commit.
217	+	12. Do not push.
218	+
219	+	Never call the delivery complete when required verification has not run. Report environmental or unrelated failures with evidence.

CHANGELOG.md(файл створено)

		@@ -0,0 +1,29 @@
1	+	# Changelog
2	+
3	+	## Unreleased
4	+
5	+	### Added
6	+
7	+	- Standalone executable `plan_build.zsh`.
8	+	- Canonical standard and architect Claude skills.
9	+	- Standard, prompt-enhanced, brainstorm, writing-plan, and architect workflows.
10	+	- Architect safe-resume and archive-and-start-new launch modes.
11	+	- Command-level, network-free Zsh regression tests.
12	+	- Dedicated installation, integration, architecture, task, and troubleshooting documentation.
13	+
14	+	### Changed
15	+
16	+	- Plan-build-specific implementation and documentation now belong to the dedicated `plan-build` gist rather than the Zsh Setup repository.
17	+	- `--yolo` is translated to Claude Code's `--dangerously-skip-permissions` argument.
18	+	- Active workflow documentation no longer describes removed v2 or distribution modes.
19	+	- Prompt enhancement now uses valid, immediately flushed platform `script` invocations, propagates natural child failures, and cleans up temporary state and child processes on return or interruption.
20	+	- The cache contract now rejects empty or syntactically invalid downloads before atomic activation and identifies mutable HTTPS `HEAD` as the update trust boundary.
21	+
22	+	### Removed
23	+
24	+	- Dependence on `~/.func` and ambient shell functions.
25	+	- The obsolete v2 downloader and its former workflow variants.
26	+
27	+	### Pending
28	+
29	+	- The Zsh Setup repository still needs a separate migration to the thin atomic-cache launcher. This extraction does not claim that migration is complete.

README.md(файл створено)

		@@ -0,0 +1,121 @@
1	+	# plan-build
2	+
3	+	`plan-build` is a standalone Zsh tool that launches Claude Code with a structured multi-agent implementation workflow. Claude orchestrates, Codex provides independent implementation review, and CodeRabbit reviews the resulting changes. Architect mode instead keeps Claude within a documentation-first architecture and task-dispatch role while Codex performs implementation.
4	+
5	+	## Prerequisites
6	+
7	+	- Zsh
8	+	- Claude Code CLI (`claude`)
9	+	- OpenAI Codex CLI (`codex`)
10	+	- CodeRabbit CLI (`coderabbit`)
11	+	- Git
12	+	- The installed plan-build skills described below
13	+
14	+	`--prompt` also requires Auggie (`auggie`), an authenticated `~/.augment/session.json`, Perl, and the platform `script` utility.
15	+
16	+	`--brainstorm` and `--writing-plan` require the enabled Claude Code plugin `superpowers@claude-plugins-official`. Claude Code safe mode must be disabled for those modes.
17	+
18	+	Architect mode additionally requires an interactive terminal and a normal Git worktree. Bare repositories are rejected.
19	+
20	+	## Installation
21	+
22	+	Install the executable somewhere on `PATH`:
23	+
24	+	```zsh
25	+	mkdir -p "$HOME/.local/bin"
26	+	curl -fsSL \
27	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh \
28	+	-o "$HOME/.local/bin/plan_build"
29	+	chmod +x "$HOME/.local/bin/plan_build"
30	+	```
31	+
32	+	Then install both skills:
33	+
34	+	```zsh
35	+	mkdir -p \
36	+	"$HOME/.claude/skills/plan-build" \
37	+	"$HOME/.claude/skills/plan-build-architect"
38	+	curl -fsSL \
39	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md \
40	+	-o "$HOME/.claude/skills/plan-build/SKILL.md"
41	+	curl -fsSL \
42	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md \
43	+	-o "$HOME/.claude/skills/plan-build-architect/SKILL.md"
44	+	```
45	+
46	+	For production automation, download to a temporary file in the destination directory and rename it atomically after a successful transfer.
47	+
48	+	## Usage
49	+
50	+	Run the command in the project you want to change, enter the payload, then put `EOF` alone on a line:
51	+
52	+	```zsh
53	+	plan_build
54	+	Implement pagination for the audit log.
55	+	Preserve existing API compatibility.
56	+	EOF
57	+	```
58	+
59	+	Available modes:
60	+
61	+	```text
62	+	plan_build Standard short-plan workflow
63	+	plan_build --prompt Enhance with Auggie and approve
64	+	plan_build --brainstorm Superpowers design and plan
65	+	plan_build --writing-plan Superpowers implementation plan
66	+	plan_build --prompt --brainstorm Enhance, design, plan, and build
67	+	plan_build --yolo --writing-plan Permissive Claude process mode
68	+	plan_build --architect Safely resume architect state
69	+	plan_build --architect --new Archive state and start fresh
70	+	plan_build --architect --yolo Architect with permissive process mode
71	+	```
72	+
73	+	`--brainstorm` and `--writing-plan` are mutually exclusive. `--prompt` can combine with either. `--architect` can combine only with `--new` and `--yolo`; `--new` is invalid without `--architect`. Duplicate flags and all other flags fail. `--v2` is intentionally unsupported.
74	+
75	+	The user-facing `--yolo` option is translated to Claude Code's `--dangerously-skip-permissions` argument. It never bypasses approval gates defined by either workflow.
76	+
77	+	## Cache-launcher integration contract
78	+
79	+	The future thin Zsh Setup launcher must download:
80	+
81	+	```text
82	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
83	+	```
84	+
85	+	It must download into a temporary file beside the cache target, validate that the download succeeded, is non-empty, and passes `zsh -n`, then atomically rename it into place. It invokes the cached program exactly as:
86	+
87	+	```zsh
88	+	zsh <cache> "$@"
89	+	```
90	+
91	+	This mutable HTTPS `HEAD` download is the explicit update trust boundary: transport security authenticates the server, but the URL provides neither immutable-version pinning nor content-integrity verification. Atomic activation and syntax validation prevent partial or syntactically invalid cache entries; they do not establish provenance for changed remote content.
92	+
93	+	The same launcher or installer downloads `SKILL.md` and `ARCHITECT.md` from the same gist to:
94	+
95	+	```text
96	+	~/.claude/skills/plan-build/SKILL.md
97	+	~/.claude/skills/plan-build-architect/SKILL.md
98	+	```
99	+
100	+	The launcher migration in the Zsh Setup repository is not part of this extraction and is not yet complete.
101	+
102	+	## Testing
103	+
104	+	The suite is self-contained and never accesses the network or launches real agent CLIs:
105	+
106	+	```zsh
107	+	zsh -n plan_build.zsh test_plan_build.zsh
108	+	zsh test_plan_build.zsh
109	+	git diff --check
110	+	```
111	+
112	+	## Troubleshooting
113	+
114	+	- CLI is missing: install the named program and ensure its executable is on `PATH`.
115	+	- Superpowers is missing: in Claude Code run `/plugin install superpowers@claude-plugins-official`.
116	+	- Superpowers is disabled: run `claude plugin enable superpowers@claude-plugins-official`.
117	+	- Safe mode blocks planning: unset `CLAUDE_CODE_SAFE_MODE`.
118	+	- Auggie cannot authenticate: run `auggie login` and confirm `~/.augment/session.json` is non-empty.
119	+	- Prompt enhancement does not continue: `--prompt` requires an interactive terminal to approve both optional project indexing and the final enhanced prompt.
120	+	- Architect preflight fails in Git: change to a checked-out worktree rather than the `.git` directory or a bare repository.
121	+	- Architect skill is missing: install `ARCHITECT.md` at the exact skill path shown above.

SKILL.md(файл створено)

		@@ -0,0 +1,127 @@
1	+	# Plan-Build Orchestrate Loop
2	+
3	+	Use this workflow when `plan_build` hands Claude Code an implementation task. The goal is to keep Claude as the orchestrator while using Codex and CodeRabbit as independent review and validation agents.
4	+
5	+	## Operating Rules
6	+
7	+	- Run from the project root. Treat the current working directory as the project to modify.
8	+	- Preserve user work. Check `git status` before edits and do not revert unrelated changes.
9	+	- Keep implementation scoped to the payload unless repository context proves a wider change is required.
10	+	- Prefer existing project conventions, scripts, test commands, and dependency managers.
11	+	- Do not call the task complete until validation has run or the reason it cannot run is documented.
12	+	- If any agent reports a plausible correctness, security, data-loss, migration, or test risk, resolve it or explicitly document why it is not applicable.
13	+
14	+	## The 8-Step Workflow
15	+
16	+	### 1. Intake
17	+
18	+	Read the user payload fully. Identify:
19	+
20	+	- Objective and expected user-visible behavior.
21	+	- Files, modules, commands, and frameworks likely involved.
22	+	- Constraints from repository docs, package scripts, CI config, and existing patterns.
23	+	- Any ambiguity that blocks safe execution.
24	+
25	+	Only ask the user a question when no reasonable project-local assumption is safe.
26	+
27	+	### 2. Baseline
28	+
29	+	Inspect the repository before changing files:
30	+
31	+	```bash
32	+	git status --short
33	+	rg --files
34	+	```
35	+
36	+	Then read the smallest useful set of files. Prefer `rg`, package manifests, tests, routing files, and nearby implementations over broad file dumps.
37	+
38	+	### 3. Plan
39	+
40	+	Follow the planning mode supplied by `plan_build`:
41	+
42	+	- `standard`: Create a short implementation plan with concrete steps and validation commands.
43	+	- `brainstorm`: Invoke `superpowers:brainstorming`, honor its design and written-spec approval gates, and let it transition to `superpowers:writing-plans` after approval.
44	+	- `writing-plan`: Invoke `superpowers:writing-plans` directly, treating the payload as the requirements or specification.
45	+
46	+	For either Superpowers mode, save the artifacts at the paths selected by the skills. When `writing-plans` reaches its execution handoff, return to this workflow instead of starting implementation: Codex must review the plan first. If the user rejects or cancels a required approval, stop cleanly without modifying implementation files.
47	+
48	+	If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note.
49	+
50	+	### 4. Codex Plan Review
51	+
52	+	Run this step only for `brainstorm` and `writing-plan` modes. Ask Codex for an independent, read-only review of the approved spec, when present, and the implementation plan before touching implementation files. Provide the original payload and artifact paths. Ask it to focus on requirement coverage, incorrect assumptions, unsafe migrations, missing edge cases, inadequate tests, and steps that are too vague to execute.
53	+
54	+	Recommended prompt shape:
55	+
56	+	```text
57	+	Review these planning artifacts before implementation. Check requirement coverage, technical correctness, repository fit, edge cases, migration or rollback risk, test coverage, and whether every step is executable. Report concrete findings only; do not modify files.
58	+
59	+	Task:
60	+	<payload>
61	+
62	+	Spec:
63	+	<spec path, if present>
64	+
65	+	Implementation plan:
66	+	<plan path>
67	+	```
68	+
69	+	Use a read-only, ephemeral Codex invocation. Resolve every valid finding in the artifacts and repeat the review if revisions are substantial. If an artifact is missing or empty, or Codex cannot complete the review, stop before implementation and report the failure.
70	+
71	+	In `standard` mode, skip this step and continue directly to implementation.
72	+
73	+	### 5. Implement
74	+
75	+	Make the change in small, reviewable edits:
76	+
77	+	- Follow existing style and abstractions.
78	+	- Add or update tests when behavior changes.
79	+	- Update docs only when user-facing usage changes.
80	+	- Avoid unrelated refactors and formatting churn.
81	+
82	+	After each meaningful edit group, re-check the diff for accidental changes.
83	+
84	+	### 6. Codex Code Review Pass
85	+
86	+	Ask Codex for an independent review of the local diff before finalizing. Provide the task, constraints, and current diff. Ask it to focus on bugs, edge cases, missing tests, regressions, and simpler project-native alternatives.
87	+
88	+	Recommended prompt shape:
89	+
90	+	```text
91	+	Review this change for correctness and risk. Prioritize bugs, regressions, missing tests, and mismatches with existing project patterns. Do not rewrite the whole solution unless a specific issue requires it.
92	+
93	+	Task:
94	+	<payload>
95	+
96	+	Diff:
97	+	<git diff>
98	+	```
99	+
100	+	Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial.
101	+
102	+	### 7. CodeRabbit Review Pass
103	+
104	+	Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding.
105	+
106	+	If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely.
107	+
108	+	### 8. Validate And Close
109	+
110	+	Run the planned validation commands, such as:
111	+
112	+	```bash
113	+	npm test
114	+	npm run lint
115	+	pytest
116	+	cargo test
117	+	go test ./...
118	+	```
119	+
120	+	Use the commands that actually exist in the project. If validation fails, fix the issue and rerun the relevant command. If a failure is unrelated or environmental, capture the evidence.
121	+
122	+	Before final response:
123	+
124	+	- Confirm `git diff` contains only intended changes.
125	+	- Summarize what changed.
126	+	- Report validation run and result.
127	+	- Note any remaining risks or commands that could not run.

SPEC.md(файл створено)

		@@ -0,0 +1,82 @@
1	+	# Plan-Build Specification
2	+
3	+	## Purpose
4	+
5	+	Plan-build is a self-contained Zsh launcher for Claude Code multi-agent implementation workflows. This repository is the canonical boundary for the executable, both Claude skills, command tests, and project documentation. It does not depend on the Zsh Setup repository or on functions from `~/.func`.
6	+
7	+	## Public interface
8	+
9	+	```text
10	+	plan_build [--yolo] [--prompt] [--brainstorm \| --writing-plan]
11	+	plan_build --architect [--new] [--yolo]
12	+	```
13	+
14	+	The executable reads standard input until a line exactly equal to `EOF`. Empty payloads fail. Unknown and duplicate options fail with usage text. `--v2` is intentionally unknown.
15	+
16	+	### Standard modes
17	+
18	+	- No planning flag: use the normal short-plan eight-step workflow.
19	+	- `--prompt`: enhance the payload through Auggie, display the result, and require interactive approval before Claude launches.
20	+	- `--brainstorm`: require enabled Claude Superpowers, then use brainstorming and writing-plans approval gates.
21	+	- `--writing-plan`: require enabled Claude Superpowers and create the implementation plan directly.
22	+	- `--yolo`: launch Claude Code with `--dangerously-skip-permissions`.
23	+
24	+	`--brainstorm` and `--writing-plan` are mutually exclusive. `--prompt` may be combined with either.
25	+
26	+	### Architect mode
27	+
28	+	`--architect` makes Claude the documentation-first architect and dispatcher. It may combine only with `--new` and `--yolo`.
29	+
30	+	- Default: safely detect and resume existing planning state.
31	+	- `--new`: archive existing planning documents as directed by the architect skill and start fresh.
32	+	- `--yolo`: changes Claude Code permissions only; every workflow approval gate remains mandatory.
33	+
34	+	Architect preflight happens before payload input and verifies an interactive terminal, Claude Code, Codex, CodeRabbit, Git, an exact normal Git worktree, and a readable non-empty architect skill.
35	+
36	+	## Installed skills
37	+
38	+	The executable expects:
39	+
40	+	```text
41	+	~/.claude/skills/plan-build/SKILL.md
42	+	~/.claude/skills/plan-build-architect/SKILL.md
43	+	```
44	+
45	+	The canonical repository sources are `SKILL.md` and `ARCHITECT.md`.
46	+
47	+	## Standalone constraints
48	+
49	+	- Zsh on macOS, Ubuntu, and WSL.
50	+	- No sourcing of user shell configuration.
51	+	- All internal helpers use the `_plan_build_` namespace.
52	+	- External command boundaries remain replaceable for tests.
53	+	- Tests use no network and do not launch real agent CLIs.
54	+	- The program remains sourceable and runs main only when executed directly.
55	+
56	+	## Thin-launcher integration
57	+
58	+	A future Zsh Setup launcher will download:
59	+
60	+	```text
61	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
62	+	```
63	+
64	+	It must write to a temporary file in the cache directory, require the download to be non-empty and pass `zsh -n`, make the validated file atomically visible, then execute:
65	+
66	+	```text
67	+	zsh <cache> "$@"
68	+	```
69	+
70	+	The mutable HTTPS `HEAD` URL is the explicit update trust boundary. HTTPS authenticates the transport endpoint, but without an immutable version or pinned digest it does not provide content-integrity or provenance guarantees for updates.
71	+
72	+	It will download `SKILL.md` and `ARCHITECT.md` from the same gist into the installed skill paths above. Migration of that old launcher is deliberately outside this repository and is not yet complete.
73	+
74	+	## Acceptance criteria
75	+
76	+	- Every documented mode has command-level coverage.
77	+	- Invalid combinations, duplicate flags, empty payloads, and `--v2` rejection are covered.
78	+	- Superpowers checks precede Auggie and payload input.
79	+	- Architect preflight precedes payload input and distinguishes normal worktrees from bare repositories.
80	+	- Prompt enhancement cannot launch Claude without explicit approval.
81	+	- `--yolo` reaches the Claude binary only as `--dangerously-skip-permissions`.
82	+	- Syntax checks, command tests, and `git diff --check` pass.

TASKS.md(файл створено)

		@@ -0,0 +1,50 @@
1	+	# Plan-Build Tasks
2	+
3	+	## Completed
4	+
5	+	### PB-001: Establish the dedicated project boundary
6	+
7	+	- Extract the executable from Zsh Setup into `plan_build.zsh`.
8	+	- Remove dependencies on `~/.func` and unrelated shell helpers.
9	+	- Make the executable directly runnable and safely sourceable.
10	+
11	+	### PB-002: Preserve supported workflows
12	+
13	+	- Preserve standard, prompt enhancement, brainstorm, and writing-plan behavior.
14	+	- Preserve architect safe-resume and archive-and-start-new modes.
15	+	- Preserve EOF-terminated payload input and interactive enhanced-prompt approval.
16	+	- Translate `--yolo` to Claude Code's real `--dangerously-skip-permissions` option.
17	+	- Keep `--v2` rejected through the unknown-option path.
18	+
19	+	### PB-003: Canonicalize skills and documentation
20	+
21	+	- Publish the standard workflow as `SKILL.md`.
22	+	- Publish the architect workflow as `ARCHITECT.md`.
23	+	- Remove obsolete v2-only and distribution workflow claims from the active standard skill.
24	+	- Document installation, prerequisites, cache integration, compatibility, testing, and troubleshooting.
25	+
26	+	### PB-004: Add standalone regression coverage
27	+
28	+	- Stub external CLIs, Claude launch, Auggie enhancement, and interactive approval.
29	+	- Cover all modes, invalid combinations, preflight ordering, safe-resume/new architect prompts, and normal versus bare Git repositories.
30	+	- Keep the suite network-free.
31	+
32	+	## Pending outside this repository
33	+
34	+	### ZS-001: Migrate the Zsh Setup launcher
35	+
36	+	Replace the old in-repository function with a thin atomic-cache launcher that downloads the canonical executable and skills from the `plan-build` gist. This task belongs to the Zsh Setup repository and is not complete.
37	+
38	+	Required launcher contract:
39	+
40	+	```text
41	+	zsh <cache> "$@"
42	+	```
43	+
44	+	Required remote files:
45	+
46	+	```text
47	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.zsh
48	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md
49	+	https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/ARCHITECT.md
50	+	```

plan_build.zsh(файл створено)

		@@ -0,0 +1,518 @@
1	+	#!/usr/bin/env zsh
2	+
3	+	# Standalone plan-build launcher. This file is intentionally sourceable so its
4	+	# command seams can be replaced by the test suite.
5	+
6	+	_plan_build_usage() {
7	+	print -r -- "Usage: plan_build [--yolo] [--prompt] [--brainstorm \| --writing-plan]
8	+	plan_build --architect [--new] [--yolo]"
9	+	}
10	+
11	+	_plan_build_require_cli() {
12	+	local binary="$1"
13	+	local label="$2"
14	+	local resolved
15	+
16	+	resolved="$(command -v "$binary" 2>/dev/null)" \|\| resolved=""
17	+	if [[ -n "$resolved" && -x "$resolved" ]]; then
18	+	return 0
19	+	fi
20	+
21	+	print -u2 -r -- "Error: ${label} ('${binary}') is not installed or not in your PATH."
22	+	return 1
23	+	}
24	+
25	+	_plan_build_confirm_indexing() {
26	+	local project_root="$1"
27	+	local reply
28	+
29	+	if ! (: </dev/tty) 2>/dev/null; then
30	+	print -u2 -r -- "Notice: No interactive terminal available; enhancing without project indexing."
31	+	return 1
32	+	fi
33	+
34	+	printf "Allow Auggie to index and use project context from '%s'? (y/N) " "$project_root" >/dev/tty
35	+	if ! IFS= read -r reply </dev/tty; then
36	+	print -u2 -r -- "\nNotice: Unable to read confirmation; enhancing without project indexing."
37	+	return 1
38	+	fi
39	+
40	+	[[ "$reply" == (y\|Y\|yes\|YES\|Yes) ]]
41	+	}
42	+
43	+	_plan_build_parse_auggie_output() {
44	+	local log_file="$1"
45	+	local output_file="$2"
46	+
47	+	perl -ne '
48	+	s/\r$//;
49	+	s/.*\r//;
50	+	1 while s/[^\x08]\x08//g;
51	+	s/\x08//g;
52	+	s/\e\][^\a]*(?:\a\|\e\\)//g;
53	+	s/\e\[[0-?][ -\/][@-~]//g;
54	+	next if /Script started on/ \|\| /Script done on/;
55	+	if (/^(?:✨\s)?Enhanced prompt:\s(.*)$/) {
56	+	$capturing = 1;
57	+	$output .= "$1\n" if length $1;
58	+	next;
59	+	}
60	+	next unless $capturing;
61	+	exit if /^🤖/ \|\| /Tool call:/ \|\| /Session terminated/;
62	+	$output .= $_;
63	+	END {
64	+	$output =~ s/^\s*\n//;
65	+	$output =~ s/\s+\z//;
66	+	print "$output\n" if length $output;
67	+	}
68	+	' "$log_file" >\| "$output_file"
69	+	}
70	+
71	+	_plan_build_platform() {
72	+	command uname -s
73	+	}
74	+
75	+	_plan_build_start_auggie_script() {
76	+	local platform="$1" log_file="$2" workspace="$3" cache_dir="$4"
77	+	local auth_file="$5" prompt_file="$6" use_project_context="$7"
78	+	shift 7
79	+
80	+	if [[ "$platform" == Darwin ]]; then
81	+	command script -q -t 0 "$log_file" auggie "$@" </dev/null >/dev/null 2>&1 &
82	+	else
83	+	AUGGIE_WORKSPACE="$workspace" AUGGIE_CACHE_DIR="$cache_dir" \
84	+	AUGGIE_AUTH_FILE="$auth_file" AUGGIE_PROMPT_FILE="$prompt_file" \
85	+	AUGGIE_INDEXING="$use_project_context" \
86	+	command script -q -f -O "$log_file" -c '
87	+	if [ "$AUGGIE_INDEXING" = 1 ]; then
88	+	exec auggie --print --enhance-prompt --workspace-root "$AUGGIE_WORKSPACE" --augment-cache-dir "$AUGGIE_CACHE_DIR" --augment-session-json "$AUGGIE_AUTH_FILE" --allow-indexing --wait-for-indexing --dont-save-session --instruction-file "$AUGGIE_PROMPT_FILE"
89	+	else
90	+	exec auggie --print --enhance-prompt --no-discover-workspaces --workspace-root "$AUGGIE_WORKSPACE" --augment-cache-dir "$AUGGIE_CACHE_DIR" --augment-session-json "$AUGGIE_AUTH_FILE" --dont-save-session --instruction-file "$AUGGIE_PROMPT_FILE"
91	+	fi
92	+	' </dev/null >/dev/null 2>&1 &
93	+	fi
94	+	REPLY=$!
95	+	}
96	+
97	+	_plan_build_enhance_prompt() {
98	+	emulate -L zsh
99	+	setopt localtraps
100	+	local prompt="$1"
101	+	local output_file="$2"
102	+	local run_dir prompt_file workspace cache_dir auth_file log_file parsed_file
103	+	local project_root use_project_context timeout_seconds script_pid= waited child_status=0
104	+	local -a auggie_args
105	+
106	+	trap 'return 130' INT
107	+	trap 'return 143' TERM
108	+	trap 'return 129' HUP
109	+
110	+	if [[ -z "$prompt" ]]; then
111	+	print -u2 -r -- "Error: Prompt was empty."
112	+	return 1
113	+	fi
114	+	if [[ ! -s "$HOME/.augment/session.json" ]]; then
115	+	print -u2 -r -- "Error: Auggie session file not found. Run 'auggie login' first."
116	+	return 1
117	+	fi
118	+
119	+	run_dir="$(mktemp -d "${TMPDIR:-/tmp}/plan-build-auggie.XXXXXX")" \|\| return 1
120	+	trap "rm -rf -- ${(q)run_dir}" EXIT
121	+	prompt_file="$run_dir/prompt.txt"
122	+	workspace="$run_dir/workspace"
123	+	cache_dir="$run_dir/cache"
124	+	auth_file="$HOME/.augment/session.json"
125	+	log_file="$run_dir/auggie.log"
126	+	parsed_file="$run_dir/enhanced.txt"
127	+	mkdir -p "$workspace" "$cache_dir" \|\| {
128	+	return 1
129	+	}
130	+	print -r -- "$prompt" >\| "$prompt_file" \|\| return 1
131	+
132	+	project_root="$(command git rev-parse --show-toplevel 2>/dev/null)" \|\| project_root="$PWD"
133	+	use_project_context=0
134	+	timeout_seconds=90
135	+	if _plan_build_confirm_indexing "$project_root"; then
136	+	use_project_context=1
137	+	timeout_seconds=300
138	+	workspace="$project_root"
139	+	cache_dir="$HOME/.augment"
140	+	print -u2 -r -- "Indexing approved; enhancing with project context from '${project_root}'."
141	+	else
142	+	print -u2 -r -- "Enhancing without project indexing."
143	+	fi
144	+
145	+	auggie_args=(--print --enhance-prompt --workspace-root "$workspace"
146	+	--augment-cache-dir "$cache_dir" --augment-session-json "$auth_file"
147	+	--dont-save-session --instruction-file "$prompt_file")
148	+	if (( use_project_context )); then
149	+	auggie_args+=(--allow-indexing --wait-for-indexing)
150	+	else
151	+	auggie_args+=(--no-discover-workspaces)
152	+	fi
153	+
154	+	_plan_build_start_auggie_script "$(_plan_build_platform)" "$log_file" \
155	+	"$workspace" "$cache_dir" "$auth_file" "$prompt_file" \
156	+	"$use_project_context" "${auggie_args[@]}" \|\| return 1
157	+	script_pid="$REPLY"
158	+	trap "kill ${(q)script_pid} >/dev/null 2>&1
159	+	wait ${(q)script_pid} >/dev/null 2>&1
160	+	rm -rf -- ${(q)run_dir}" EXIT
161	+	waited=0
162	+	while kill -0 "$script_pid" >/dev/null 2>&1; do
163	+	if command grep -aq "🤖" "$log_file" 2>/dev/null \|\|
164	+	command grep -aq "Tool call:" "$log_file" 2>/dev/null; then
165	+	kill "$script_pid" >/dev/null 2>&1 \|\| true
166	+	wait "$script_pid" >/dev/null 2>&1 \|\| true
167	+	script_pid=
168	+	trap "rm -rf -- ${(q)run_dir}" EXIT
169	+	child_status=0
170	+	break
171	+	fi
172	+	if (( waited >= timeout_seconds )); then
173	+	kill "$script_pid" >/dev/null 2>&1 \|\| true
174	+	wait "$script_pid" >/dev/null 2>&1 \|\| true
175	+	script_pid=
176	+	trap "rm -rf -- ${(q)run_dir}" EXIT
177	+	print -u2 -r -- "Error: Timed out waiting for Auggie to enhance the prompt."
178	+	return 124
179	+	fi
180	+	sleep 1
181	+	waited=$((waited + 1))
182	+	done
183	+	if [[ -n "$script_pid" ]]; then
184	+	wait "$script_pid"
185	+	child_status=$?
186	+	script_pid=
187	+	trap "rm -rf -- ${(q)run_dir}" EXIT
188	+	fi
189	+	if (( child_status != 0 )); then
190	+	print -u2 -r -- "Error: Auggie process failed with status ${child_status}."
191	+	return "$child_status"
192	+	fi
193	+
194	+	_plan_build_parse_auggie_output "$log_file" "$parsed_file"
195	+	if [[ ! -s "$parsed_file" ]]; then
196	+	print -u2 -r -- "Error: Auggie did not return an enhanced prompt."
197	+	return 1
198	+	fi
199	+	command cp "$parsed_file" "$output_file" \|\| {
200	+	print -u2 -r -- "Error: Unable to save the enhanced prompt."
201	+	return 1
202	+	}
203	+	}
204	+
205	+	_plan_build_confirm_enhanced_prompt() {
206	+	local reply
207	+
208	+	if ! (: </dev/tty) 2>/dev/null; then
209	+	print -r -- "❌ Error: Cannot review the enhanced prompt without an interactive terminal; Claude was not launched."
210	+	return 2
211	+	fi
212	+	printf "Proceed with this enhanced prompt? (y/N) " >/dev/tty
213	+	if ! IFS= read -r reply </dev/tty; then
214	+	printf '\n' >/dev/tty
215	+	print -r -- "🛑 Review cancelled; Claude was not launched."
216	+	return 2
217	+	fi
218	+	[[ "$reply" == (y\|Y\|yes\|YES\|Yes) ]]
219	+	}
220	+
221	+	_plan_build_superpowers_state() {
222	+	awk '
223	+	BEGIN { RS = "}"; state = "missing"; printed = 0 }
224	+	/"id"[[:space:]]:[[:space:]]"superpowers@claude-plugins-official"/ {
225	+	state = "installed"
226	+	if ($0 ~ /"enabled"[[:space:]]:[[:space:]]true/) state = "enabled"
227	+	else if ($0 ~ /"enabled"[[:space:]]:[[:space:]]false/) state = "disabled"
228	+	print state
229	+	printed = 1
230	+	exit
231	+	}
232	+	END { if (!printed) print state }
233	+	'
234	+	}
235	+
236	+	_plan_build_superpowers_preflight() {
237	+	local plugin_json plugin_state
238	+
239	+	case "${CLAUDE_CODE_SAFE_MODE:-}" in
240	+	1\|true\|TRUE\|yes\|YES\|on\|ON)
241	+	print -r -- "❌ Error: Claude Code safe mode disables Superpowers."
242	+	print -r -- "Unset CLAUDE_CODE_SAFE_MODE before using --brainstorm or --writing-plan."
243	+	return 1
244	+	;;
245	+	esac
246	+	if ! plugin_json="$(command claude plugin list --json 2>/dev/null)"; then
247	+	print -r -- "❌ Error: Unable to inspect Claude Code plugins."
248	+	print -r -- "Run 'claude plugin list' to diagnose the problem."
249	+	return 1
250	+	fi
251	+	plugin_state="$(print -r -- "$plugin_json" \| _plan_build_superpowers_state)"
252	+	case "$plugin_state" in
253	+	enabled) return 0 ;;
254	+	disabled)
255	+	print -r -- "❌ Error: Claude Code Superpowers is installed but disabled."
256	+	print -r -- "Enable it with: claude plugin enable superpowers@claude-plugins-official"
257	+	;;
258	+	missing)
259	+	print -r -- "❌ Error: Claude Code Superpowers is required for --brainstorm and --writing-plan."
260	+	print -r -- "Install it in Claude Code with: /plugin install superpowers@claude-plugins-official"
261	+	;;
262	+	*)
263	+	print -r -- "❌ Error: Unable to determine Claude Code Superpowers status."
264	+	print -r -- "Run 'claude plugin list' to diagnose the problem."
265	+	;;
266	+	esac
267	+	return 1
268	+	}
269	+
270	+	_plan_build_is_worktree() {
271	+	local inside_work_tree
272	+	inside_work_tree="$(command git rev-parse --is-inside-work-tree 2>/dev/null)" \|\| return 1
273	+	[[ "$inside_work_tree" == true ]]
274	+	}
275	+
276	+	_plan_build_has_tty() {
277	+	(: </dev/tty) 2>/dev/null
278	+	}
279	+
280	+	_plan_build_architect_preflight() {
281	+	local skill_path="$HOME/.claude/skills/plan-build-architect/SKILL.md"
282	+
283	+	if ! _plan_build_has_tty; then
284	+	print -r -- "❌ Error: Architect mode requires an interactive terminal."
285	+	print -r -- "Run plan_build --architect from an interactive terminal."
286	+	return 1
287	+	fi
288	+	_plan_build_require_cli claude "Claude Code CLI" \|\| return 1
289	+	_plan_build_require_cli codex "Codex CLI" \|\| return 1
290	+	_plan_build_require_cli coderabbit "CodeRabbit CLI" \|\| return 1
291	+	_plan_build_require_cli git "Git CLI" \|\| return 1
292	+	if ! _plan_build_is_worktree; then
293	+	print -r -- "❌ Error: Architect mode must run inside a Git worktree."
294	+	print -r -- "Change to a Git worktree, then retry plan_build --architect."
295	+	return 1
296	+	fi
297	+	if [[ ! -r "$skill_path" \|\| ! -s "$skill_path" ]]; then
298	+	print -r -- "❌ Error: Architect skill is missing, unreadable, or empty: $skill_path"
299	+	print -r -- "Install a readable, non-empty plan-build-architect skill at that path."
300	+	return 1
301	+	fi
302	+	}
303	+
304	+	_plan_build_launch_claude() {
305	+	local use_yolo="$1"
306	+	shift
307	+	if (( use_yolo )); then
308	+	command claude --dangerously-skip-permissions "$@"
309	+	else
310	+	command claude "$@"
311	+	fi
312	+	}
313	+
314	+	_plan_build_read_payload() {
315	+	local line payload=""
316	+	while IFS= read -r line; do
317	+	[[ "$line" == EOF ]] && break
318	+	if [[ -z "$payload" ]]; then
319	+	payload="$line"
320	+	else
321	+	payload+=$'\n'"$line"
322	+	fi
323	+	done
324	+	print -r -- "$payload"
325	+	}
326	+
327	+	plan_build() {
328	+	emulate -L zsh
329	+	setopt localtraps
330	+	local use_yolo=0 use_architect=0 use_new=0 enhance_payload=0
331	+	local planning_mode="standard"
332	+	local payload enhanced_file= confirm_status enhance_status planning_instruction architect_start_mode
333	+
334	+	trap 'return 130' INT
335	+	trap 'return 143' TERM
336	+	trap 'return 129' HUP
337	+
338	+	while (( $# )); do
339	+	case "$1" in
340	+	--yolo)
341	+	(( use_yolo )) && {
342	+	print -r -- "Error: Duplicate argument: --yolo"
343	+	_plan_build_usage
344	+	return 1
345	+	}
346	+	use_yolo=1
347	+	;;
348	+	--architect)
349	+	(( use_architect )) && {
350	+	print -r -- "Error: Duplicate argument: --architect"
351	+	_plan_build_usage
352	+	return 1
353	+	}
354	+	use_architect=1
355	+	;;
356	+	--new)
357	+	(( use_new )) && {
358	+	print -r -- "Error: Duplicate argument: --new"
359	+	_plan_build_usage
360	+	return 1
361	+	}
362	+	use_new=1
363	+	;;
364	+	--prompt)
365	+	(( enhance_payload )) && {
366	+	print -r -- "Error: Duplicate argument: --prompt"
367	+	_plan_build_usage
368	+	return 1
369	+	}
370	+	enhance_payload=1
371	+	;;
372	+	--brainstorm)
373	+	[[ "$planning_mode" == brainstorm ]] && {
374	+	print -r -- "Error: Duplicate argument: --brainstorm"
375	+	_plan_build_usage
376	+	return 1
377	+	}
378	+	[[ "$planning_mode" != standard ]] && {
379	+	print -r -- "Error: --brainstorm and --writing-plan are mutually exclusive."
380	+	_plan_build_usage
381	+	return 1
382	+	}
383	+	planning_mode="brainstorm"
384	+	;;
385	+	--writing-plan)
386	+	[[ "$planning_mode" == writing-plan ]] && {
387	+	print -r -- "Error: Duplicate argument: --writing-plan"
388	+	_plan_build_usage
389	+	return 1
390	+	}
391	+	[[ "$planning_mode" != standard ]] && {
392	+	print -r -- "Error: --brainstorm and --writing-plan are mutually exclusive."
393	+	_plan_build_usage
394	+	return 1
395	+	}
396	+	planning_mode="writing-plan"
397	+	;;
398	+	*)
399	+	print -r -- "Error: Unknown argument: $1"
400	+	_plan_build_usage
401	+	return 1
402	+	;;
403	+	esac
404	+	shift
405	+	done
406	+
407	+	if (( use_new && ! use_architect )); then
408	+	print -r -- "Error: --new requires --architect."
409	+	_plan_build_usage
410	+	return 1
411	+	fi
412	+	if (( use_architect && enhance_payload )) \|\|
413	+	{ (( use_architect )) && [[ "$planning_mode" != standard ]]; }; then
414	+	print -r -- "Error: --architect may combine only with --new and --yolo."
415	+	_plan_build_usage
416	+	return 1
417	+	fi
418	+
419	+	if (( use_architect )); then
420	+	_plan_build_architect_preflight \|\| return 1
421	+	else
422	+	_plan_build_require_cli claude "Claude Code CLI" \|\| return 1
423	+	if [[ "$planning_mode" != standard ]]; then
424	+	_plan_build_superpowers_preflight \|\| return 1
425	+	fi
426	+	_plan_build_require_cli codex "Codex CLI" \|\| return 1
427	+	_plan_build_require_cli coderabbit "CodeRabbit CLI" \|\| return 1
428	+	if (( enhance_payload )); then
429	+	_plan_build_require_cli auggie "Auggie CLI" \|\| return 1
430	+	_plan_build_require_cli script "script utility" \|\| return 1
431	+	_plan_build_require_cli perl "Perl" \|\| return 1
432	+	fi
433	+	fi
434	+
435	+	print -r -- "📥 Reading payload... Type 'EOF' on a new line and press Enter when finished."
436	+	payload="$(_plan_build_read_payload)"
437	+	if [[ -z "$payload" ]]; then
438	+	print -r -- "❌ Error: Payload was empty."
439	+	return 1
440	+	fi
441	+
442	+	if (( enhance_payload )); then
443	+	enhanced_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-enhanced.XXXXXX")" \|\| return 1
444	+	trap "rm -f -- ${(q)enhanced_file}" EXIT
445	+	print -r -- "✨ Enhancing payload with Auggie..."
446	+	_plan_build_enhance_prompt "$payload" "$enhanced_file"
447	+	enhance_status=$?
448	+	if (( enhance_status != 0 )); then
449	+	print -r -- "❌ Error: Prompt enhancement failed; Claude was not launched."
450	+	return "$enhance_status"
451	+	fi
452	+	payload="$(<"$enhanced_file")"
453	+	rm -f -- "$enhanced_file"
454	+	enhanced_file=
455	+	trap - EXIT
456	+	if [[ -z "$payload" ]]; then
457	+	print -r -- "❌ Error: Enhanced payload was empty; Claude was not launched."
458	+	return 1
459	+	fi
460	+	printf '\n%s\n%s\n%s\n\n' \
461	+	"━━━━━━━━━━━━━━━━ Auggie enhanced prompt ━━━━━━━━━━━━━━━━" \
462	+	"$payload" \
463	+	"━━━━━━━━━━━━━━━━ End enhanced prompt ━━━━━━━━━━━━━━━━━"
464	+	_plan_build_confirm_enhanced_prompt
465	+	confirm_status=$?
466	+	if (( confirm_status == 2 )); then
467	+	return 1
468	+	elif (( confirm_status != 0 )); then
469	+	print -r -- "🛑 Enhanced prompt not approved; Claude was not launched."
470	+	return 0
471	+	fi
472	+	print -r -- "✅ Enhanced prompt approved."
473	+	fi
474	+
475	+	if (( use_architect )); then
476	+	if (( use_new )); then
477	+	architect_start_mode="Start mode: archive-and-start-new. Explicitly archive the prior planning state as the skill directs, then begin a new architecture plan."
478	+	else
479	+	architect_start_mode="Start mode: safe-resume-detection. Safely detect whether an existing architecture planning session should be resumed; do not archive or replace it automatically."
480	+	fi
481	+	print -r -- "🚀 Launching Claude Code in architect mode..."
482	+	_plan_build_launch_claude "$use_yolo" "Read \`~/.claude/skills/plan-build-architect/SKILL.md\` and follow it strictly, including every gate even when permissive Claude execution is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement.
483	+
484	+	$architect_start_mode
485	+
486	+	Use the following payload as the initial requirement:
487	+
488	+	$payload"
489	+	return $?
490	+	fi
491	+
492	+	case "$planning_mode" in
493	+	brainstorm)
494	+	planning_instruction="Planning mode: brainstorm. Use the superpowers:brainstorming skill, including its approval gates and transition to superpowers:writing-plans. After the implementation plan is saved, return to the plan-build workflow for Codex plan review before implementation."
495	+	;;
496	+	writing-plan)
497	+	planning_instruction="Planning mode: writing-plan. Use the superpowers:writing-plans skill with the payload as the requirements. After the implementation plan is saved, return to the plan-build workflow for Codex plan review before implementation."
498	+	;;
499	+	*)
500	+	planning_instruction="Planning mode: standard. Create the workflow's normal short implementation plan."
501	+	;;
502	+	esac
503	+
504	+	print -r -- "🚀 Launching Claude Code with your multi-agent workflow (${planning_mode} planning)..."
505	+	_plan_build_launch_claude "$use_yolo" "Please read \`~/.claude/skills/plan-build/SKILL.md\` and strictly follow the 8-step multi-agent workflow to implement the following task.
506	+
507	+	$planning_instruction
508	+
509	+	$payload"
510	+	}
511	+
512	+	_plan_build_main() {
513	+	plan_build "$@"
514	+	}
515	+
516	+	if [[ "${ZSH_EVAL_CONTEXT:-}" == toplevel ]]; then
517	+	_plan_build_main "$@"
518	+	fi

test_plan_build.zsh(файл створено)

		@@ -0,0 +1,269 @@
1	+	#!/usr/bin/env zsh
2	+
3	+	set -u
4	+
5	+	typeset -r repo_dir="${0:A:h}"
6	+	source "$repo_dir/plan_build.zsh"
7	+
8	+	typeset -gi failures=0
9	+	functions[_plan_build_real_launch_claude]="${functions[_plan_build_launch_claude]}"
10	+	functions[_plan_build_real_enhance_prompt]="${functions[_plan_build_enhance_prompt]}"
11	+	functions[_plan_build_real_start_auggie_script]="${functions[_plan_build_start_auggie_script]}"
12	+
13	+	fail() {
14	+	print -u2 -r -- "FAIL: $1"
15	+	failures=$((failures + 1))
16	+	}
17	+
18	+	assert_equal() {
19	+	local expected="$1" actual="$2" label="$3"
20	+	[[ "$actual" == "$expected" ]] \|\| fail "$label (expected '$expected', got '$actual')"
21	+	}
22	+
23	+	assert_contains() {
24	+	local output="$1" expected="$2" label="$3"
25	+	[[ "$output" == "$expected" ]] \|\| fail "$label (missing '$expected')"
26	+	}
27	+
28	+	assert_not_contains() {
29	+	local output="$1" unexpected="$2" label="$3"
30	+	[[ "$output" != "$unexpected" ]] \|\| fail "$label (unexpected '$unexpected')"
31	+	}
32	+
33	+	run_plan() {
34	+	local args="$1" input="${2:-EOF\n}"
35	+	output="$(printf '%b' "$input" \| plan_build ${(z)args} 2>&1)"
36	+	rc=$?
37	+	}
38	+
39	+	seam_events() {
40	+	print -r -- "$1" \| sed -n 's/^SEAM://p' \| paste -sd ' ' -
41	+	}
42	+
43	+	count_matches() {
44	+	local directory="$1" prefix="$2"
45	+	local -a matches
46	+	matches=("$directory"/"$prefix".*(N))
47	+	print -r -- "$#matches"
48	+	}
49	+
50	+	typeset fixture_dir
51	+	fixture_dir="$(mktemp -d "${TMPDIR:-/tmp}/plan-build-tests.XXXXXX")" \|\| exit 1
52	+	trap 'rm -rf -- "$fixture_dir"' EXIT
53	+	mkdir -p "$fixture_dir/tmp"
54	+	export TMPDIR="$fixture_dir/tmp"
55	+
56	+	command git init -q "$fixture_dir/worktree"
57	+	command git init -q --bare "$fixture_dir/bare.git"
58	+
59	+	(cd "$fixture_dir/worktree" && _plan_build_is_worktree)
60	+	assert_equal 0 "$?" "normal Git worktree accepted"
61	+	(cd "$fixture_dir/bare.git" && _plan_build_is_worktree)
62	+	assert_equal 1 "$?" "bare Git repository rejected"
63	+	(cd "$fixture_dir" && _plan_build_is_worktree)
64	+	assert_equal 1 "$?" "non-repository rejected"
65	+
66	+	plugin_state() {
67	+	print -r -- "$1" \| _plan_build_superpowers_state
68	+	}
69	+
70	+	assert_equal enabled "$(plugin_state '[{"id":"superpowers@claude-plugins-official","enabled":true}]')" "enabled plugin JSON"
71	+	assert_equal disabled "$(plugin_state $'[\n{"enabled":false,\n"id":"superpowers@claude-plugins-official"}\n]')" "reordered disabled plugin JSON"
72	+	assert_equal missing "$(plugin_state '[{"id":"other@market","enabled":true}]')" "missing plugin JSON"
73	+	assert_equal installed "$(plugin_state '[{"id":"superpowers@claude-plugins-official"}]')" "installed plugin JSON"
74	+
75	+	typeset args expected label
76	+	for args expected label in \
77	+	"--v2" "Unknown argument: --v2" "v2 rejection" \
78	+	"--unknown" "Unknown argument: --unknown" "unknown option" \
79	+	"--yolo --yolo" "Duplicate argument: --yolo" "duplicate yolo" \
80	+	"--prompt --prompt" "Duplicate argument: --prompt" "duplicate prompt" \
81	+	"--brainstorm --brainstorm" "Duplicate argument: --brainstorm" "duplicate brainstorm" \
82	+	"--writing-plan --writing-plan" "Duplicate argument: --writing-plan" "duplicate writing plan" \
83	+	"--architect --architect" "Duplicate argument: --architect" "duplicate architect" \
84	+	"--architect --new --new" "Duplicate argument: --new" "duplicate new" \
85	+	"--brainstorm --writing-plan" "mutually exclusive" "planning mode conflict" \
86	+	"--new" "--new requires --architect" "orphan new" \
87	+	"--architect --prompt" "may combine only with --new and --yolo" "architect prompt conflict" \
88	+	"--architect --brainstorm" "may combine only with --new and --yolo" "architect brainstorm conflict" \
89	+	"--architect --writing-plan" "may combine only with --new and --yolo" "architect writing conflict"; do
90	+	run_plan "$args"
91	+	assert_equal 1 "$rc" "$label status"
92	+	assert_contains "$output" "$expected" "$label message"
93	+	done
94	+
95	+	export CLAUDE_CODE_SAFE_MODE=1
96	+	output="$(_plan_build_superpowers_preflight 2>&1)"
97	+	rc=$?
98	+	unset CLAUDE_CODE_SAFE_MODE
99	+	assert_equal 1 "$rc" "safe mode failure"
100	+	assert_contains "$output" "safe mode disables Superpowers" "safe mode guidance"
101	+
102	+	mkdir -p "$fixture_dir/bin" "$fixture_dir/home/.augment" "$fixture_dir/enhance-tmp"
103	+	print -r -- '{}' >\| "$fixture_dir/home/.augment/session.json"
104	+	print -r -- '#!/bin/sh' >\| "$fixture_dir/bin/script"
105	+	print -r -- 'printf "%s\n" "$@" > "$PLAN_BUILD_SCRIPT_ARGS"' >> "$fixture_dir/bin/script"
106	+	print -r -- 'if [ "$1" = -q ] && [ "$2" = -t ]; then log_file=$4; shift 4; "$@" > "$log_file"; exit $?; fi' >> "$fixture_dir/bin/script"
107	+	print -r -- 'log_file=$4; printf "Enhanced prompt: linux result\n" > "$log_file"; exit "${PLAN_BUILD_SCRIPT_STATUS:-0}"' >> "$fixture_dir/bin/script"
108	+	print -r -- '#!/bin/sh' >\| "$fixture_dir/bin/auggie"
109	+	print -r -- 'printf "Enhanced prompt: mac result\n"; exit "${PLAN_BUILD_AUGGIE_STATUS:-0}"' >> "$fixture_dir/bin/auggie"
110	+	chmod +x "$fixture_dir/bin/script" "$fixture_dir/bin/auggie"
111	+
112	+	_plan_build_confirm_indexing() { return 1 }
113	+
114	+	typeset platform script_args enhance_output
115	+	trap 'print -u2 -r -- "test INT trap"' INT
116	+	typeset caller_int_trap="$(trap -p INT)"
117	+	for platform in Darwin Linux; do
118	+	_plan_build_platform() { print -r -- "$platform" }
119	+	: >\| "$fixture_dir/script-args"
120	+	enhance_output="$fixture_dir/enhanced-$platform"
121	+	HOME="$fixture_dir/home" TMPDIR="$fixture_dir/enhance-tmp" \
122	+	PATH="$fixture_dir/bin:$PATH" PLAN_BUILD_SCRIPT_ARGS="$fixture_dir/script-args" \
123	+	_plan_build_real_enhance_prompt "raw prompt" "$enhance_output"
124	+	rc=$?
125	+	assert_equal 0 "$rc" "$platform script enhancement status"
126	+	script_args="$(<"$fixture_dir/script-args")"
127	+	if [[ "$platform" == Darwin ]]; then
128	+	assert_contains "$script_args" $'-t\n0' "macOS script immediate flushing"
129	+	assert_contains "$script_args" $'auggie\n--print' "macOS script direct executable dispatch"
130	+	assert_not_contains "$script_args" $'\ncommand\n' "macOS script excludes shell builtin"
131	+	assert_equal "mac result" "$(<"$enhance_output")" "macOS parsed enhancement"
132	+	else
133	+	assert_contains "$script_args" $'-f\n-O' "Linux script immediate flushing"
134	+	assert_contains "$script_args" "-c" "Linux script command mode"
135	+	assert_equal "linux result" "$(<"$enhance_output")" "Linux parsed enhancement"
136	+	fi
137	+	assert_equal 0 "$(count_matches "$fixture_dir/enhance-tmp" plan-build-auggie)" "$platform run directory cleanup"
138	+	done
139	+	assert_equal "$caller_int_trap" "$(trap -p INT)" "enhancement traps remain local to caller"
140	+	trap - INT
141	+
142	+	platform=Darwin
143	+	_plan_build_platform() { print -r -- "$platform" }
144	+	PLAN_BUILD_AUGGIE_STATUS=7 HOME="$fixture_dir/home" TMPDIR="$fixture_dir/enhance-tmp" \
145	+	PATH="$fixture_dir/bin:$PATH" PLAN_BUILD_SCRIPT_ARGS="$fixture_dir/script-args" \
146	+	_plan_build_real_enhance_prompt "partial prompt" "$fixture_dir/failed-enhancement" >/dev/null 2>&1
147	+	rc=$?
148	+	assert_equal 7 "$rc" "nonzero Auggie status propagated"
149	+	[[ ! -e "$fixture_dir/failed-enhancement" ]] \|\| fail "failed Auggie output was accepted"
150	+	assert_equal 0 "$(count_matches "$fixture_dir/enhance-tmp" plan-build-auggie)" "failed run directory cleanup"
151	+
152	+	print -r -- $'noise\r\n\e[32m✨ Enhanced prompt: first\e[0m\r\nsecond\r\n🤖 tool' >\| "$fixture_dir/parser.log"
153	+	_plan_build_parse_auggie_output "$fixture_dir/parser.log" "$fixture_dir/parser.out"
154	+	assert_equal $'first\nsecond' "$(<"$fixture_dir/parser.out")" "parser strips terminal output and stops at marker"
155	+	print -r -- "no enhanced prompt" >\| "$fixture_dir/parser-empty.log"
156	+	_plan_build_parse_auggie_output "$fixture_dir/parser-empty.log" "$fixture_dir/parser-empty.out"
157	+	[[ ! -s "$fixture_dir/parser-empty.out" ]] \|\| fail "parser accepted output without marker"
158	+
159	+	typeset -g enhanced_text="enhanced payload"
160	+	typeset -gi enhanced_approval=0
161	+	typeset -gi architect_preflight_result=0
162	+	typeset -gi enhancement_result=0
163	+
164	+	_plan_build_require_cli() {
165	+	print -r -- "SEAM:cli:$1"
166	+	return 0
167	+	}
168	+	_plan_build_superpowers_preflight() {
169	+	print -r -- "SEAM:superpowers"
170	+	return 0
171	+	}
172	+	_plan_build_architect_preflight() {
173	+	print -r -- "SEAM:architect-preflight"
174	+	return "$architect_preflight_result"
175	+	}
176	+	_plan_build_enhance_prompt() {
177	+	print -r -- "SEAM:auggie:$1"
178	+	print -r -- "$enhanced_text" >\| "$2"
179	+	return "$enhancement_result"
180	+	}
181	+	_plan_build_confirm_enhanced_prompt() {
182	+	print -r -- "SEAM:enhanced-approval"
183	+	return "$enhanced_approval"
184	+	}
185	+	_plan_build_launch_claude() {
186	+	print -r -- "SEAM:claude"
187	+	printf 'CLAUDE_YOLO=<%s>\nCLAUDE_PROMPT=<%s>\n' "$1" "$2"
188	+	}
189	+
190	+	run_plan "" "first line\nsecond line\nEOF\nignored line\n"
191	+	assert_equal 0 "$rc" "standard mode status"
192	+	assert_contains "$output" "Planning mode: standard" "standard planning prompt"
193	+	assert_contains "$output" $'first line\nsecond line' "multiline payload"
194	+	assert_not_contains "$output" "ignored line" "EOF terminates payload"
195	+
196	+	run_plan "--brainstorm" "build feature\nEOF\n"
197	+	assert_equal 0 "$rc" "brainstorm status"
198	+	assert_contains "$output" "Planning mode: brainstorm" "brainstorm prompt"
199	+	assert_equal "cli:claude superpowers cli:codex cli:coderabbit claude" "$(seam_events "$output")" "brainstorm preflight ordering"
200	+
201	+	run_plan "--writing-plan" "build feature\nEOF\n"
202	+	assert_equal 0 "$rc" "writing-plan status"
203	+	assert_contains "$output" "Planning mode: writing-plan" "writing-plan prompt"
204	+
205	+	enhanced_approval=0
206	+	run_plan "--prompt" "raw payload\nEOF\n"
207	+	assert_equal 0 "$rc" "prompt mode approved status"
208	+	assert_contains "$output" "enhanced payload" "enhanced prompt used"
209	+	assert_contains "$output" "Enhanced prompt approved" "enhanced approval reported"
210	+	assert_equal "cli:claude cli:codex cli:coderabbit cli:auggie cli:script cli:perl auggie:raw payload enhanced-approval claude" "$(seam_events "$output")" "prompt seams ordering"
211	+
212	+	enhancement_result=9
213	+	run_plan "--prompt" "failed child\nEOF\n"
214	+	assert_equal 9 "$rc" "prompt child failure status propagated"
215	+	assert_not_contains "$output" "enhanced-approval" "failed enhancement is never parsed or approved"
216	+	assert_not_contains "$output" "SEAM:claude" "failed enhancement prevents launch"
217	+	assert_equal 0 "$(count_matches "$TMPDIR" plan-build-enhanced)" "enhanced temporary file cleanup"
218	+	enhancement_result=0
219	+
220	+	run_plan "--prompt --brainstorm" "raw combination\nEOF\n"
221	+	assert_equal 0 "$rc" "prompt brainstorm status"
222	+	assert_contains "$output" "Planning mode: brainstorm" "prompt brainstorm planning"
223	+
224	+	enhanced_approval=1
225	+	run_plan "--prompt" "declined\nEOF\n"
226	+	assert_equal 0 "$rc" "prompt rejection exits cleanly"
227	+	assert_contains "$output" "not approved" "prompt rejection message"
228	+	assert_equal "cli:claude cli:codex cli:coderabbit cli:auggie cli:script cli:perl auggie:declined enhanced-approval" "$(seam_events "$output")" "prompt rejection prevents launch"
229	+	enhanced_approval=0
230	+
231	+	run_plan "--architect" "design feature\nEOF\n"
232	+	assert_equal 0 "$rc" "architect safe-resume status"
233	+	assert_contains "$output" "Start mode: safe-resume-detection" "architect safe-resume mode"
234	+	assert_contains "$output" "documentation-first architect/orchestrator role" "architect role boundary"
235	+	assert_equal "architect-preflight claude" "$(seam_events "$output")" "architect preflight before launch"
236	+
237	+	run_plan "--architect --new" "fresh design\nEOF\n"
238	+	assert_equal 0 "$rc" "architect new status"
239	+	assert_contains "$output" "Start mode: archive-and-start-new" "architect new mode"
240	+
241	+	run_plan "--architect --yolo" "fast design\nEOF\n"
242	+	assert_equal 0 "$rc" "architect yolo status"
243	+	assert_contains "$output" "CLAUDE_YOLO=<1>" "architect yolo reaches launch seam"
244	+	assert_contains "$output" "including every gate" "architect yolo retains gates"
245	+
246	+	architect_preflight_result=1
247	+	run_plan "--architect" "must not be read\nEOF\n"
248	+	assert_equal 1 "$rc" "architect preflight failure status"
249	+	assert_not_contains "$output" "Reading payload" "architect preflight precedes payload"
250	+	assert_equal "architect-preflight" "$(seam_events "$output")" "architect failure stops processing"
251	+	architect_preflight_result=0
252	+
253	+	run_plan "" "EOF\n"
254	+	assert_equal 1 "$rc" "empty payload status"
255	+	assert_contains "$output" "Payload was empty" "empty payload message"
256	+
257	+	print -r -- '#!/bin/sh' >\| "$fixture_dir/bin/claude"
258	+	print -r -- 'printf "REAL_CLAUDE:"; printf " <%s>" "$@"; printf "\n"' >> "$fixture_dir/bin/claude"
259	+	chmod +x "$fixture_dir/bin/claude"
260	+	output="$(PATH="$fixture_dir/bin:$PATH" _plan_build_real_launch_claude 1 "payload")"
261	+	assert_contains "$output" "<--dangerously-skip-permissions>" "yolo translates to real Claude argument"
262	+	assert_not_contains "$output" "<--yolo>" "yolo alias not forwarded"
263	+
264	+	if (( failures )); then
265	+	print -u2 -r -- "FAIL: $failures plan_build test(s)"
266	+	exit 1
267	+	fi
268	+
269	+	print -r -- "PASS: plan_build tests"

Новіше Пізніше