Vernon Wee Hong KOH ha revisionato questo gist 3 weeks ago. Vai alla revisione
6 files changed, 31 insertions, 288 deletions
ADR.md (file eliminato)
| @@ -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 (file eliminato)
| @@ -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 (file eliminato)
| @@ -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 (file eliminato)
| @@ -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 (file eliminato)
| @@ -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 ha revisionato questo gist 3 weeks ago. Vai alla revisione
11 files changed, 749 insertions, 328 deletions
.agentmemory-project(file creato)
| @@ -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(file creato)
| @@ -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 ha revisionato questo gist 3 weeks ago. Vai alla revisione
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 ha revisionato questo gist 3 weeks ago. Vai alla revisione
9 files changed, 1452 insertions
ADR.md(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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(file creato)
| @@ -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" | |
Più nuovi
Più vecchi