Vernon Wee Hong KOH ревизий этого фрагмента 1 week ago. К ревизии
7 files changed, 33 insertions, 1 deletion
README.md
| @@ -31,6 +31,16 @@ eval "$(starship init zsh)" | |||
| 31 | 31 | ||
| 32 | 32 | Starship owns the prompt and loads after Oh My Zsh. The managed Starship config is installed at `~/.config/starship.toml`. A Nerd Font is required for the Powerline symbols. | |
| 33 | 33 | ||
| 34 | + | ## AI commits | |
| 35 | + | ||
| 36 | + | The managed `aicommit` function can use Claude, Codex, Copilot, or OpenCode to create a commit from staged changes: | |
| 37 | + | ||
| 38 | + | ```zsh | |
| 39 | + | aicommit opencode | |
| 40 | + | ``` | |
| 41 | + | ||
| 42 | + | The installers place the required OpenCode agent at `~/.config/opencode/agents/ai-commit.md`. The agent may inspect Git status, the cached diff, and recent history, and may execute `git commit`; all unrelated tools and shell commands are denied. The shared commit instructions must exist at `~/.config/ai-commit-prompt.txt`. | |
| 43 | + | ||
| 34 | 44 | ## Plan-build workflow | |
| 35 | 45 | ||
| 36 | 46 | The local `plan_build` function is a thin cached launcher for the canonical public [plan-build gist](https://opengist.resetrix.work/weehong/plan-build). When curl is available, each invocation stages `plan_build.zsh`, `SKILL.md`, and `ARCHITECT.md`, requires all three to be non-empty, and syntax-checks the executable. It then moves the complete bundle into a unique immutable release directory and atomically switches one `current` symlink. Refresh activation is serialized with a kernel-backed Zsh file lock so concurrent callers cannot mix releases and crashes cannot leave a stale lock. If refresh fails, the launcher preserves and uses the last complete, validated release and repairs its skill links. Zsh is always required; curl is required only when no valid cached release exists. | |
ai-commit.md(файл создан)
| @@ -0,0 +1,14 @@ | |||
| 1 | + | --- | |
| 2 | + | description: Creates one conventional commit from the staged diff supplied in the prompt. | |
| 3 | + | mode: primary | |
| 4 | + | permission: | |
| 5 | + | "*": deny | |
| 6 | + | bash: | |
| 7 | + | "*": deny | |
| 8 | + | "git status *": allow | |
| 9 | + | "git diff --cached*": allow | |
| 10 | + | "git log *": allow | |
| 11 | + | "git commit *": allow | |
| 12 | + | --- | |
| 13 | + | ||
| 14 | + | Follow the supplied commit instructions and staged diff. Generate a concise conventional commit message, then execute exactly one `git commit` with that message. You may inspect Git status, the cached diff, and recent log. Do not modify files or change the staged set. | |
config.sh
| @@ -11,6 +11,7 @@ CONFIG_FILES=( | |||
| 11 | 11 | ".vimrc" | |
| 12 | 12 | ".zshrc" | |
| 13 | 13 | ".config/starship.toml" | |
| 14 | + | ".config/opencode/agents/ai-commit.md" | |
| 14 | 15 | ) | |
| 15 | 16 | ||
| 16 | 17 | echo "Starting configuration download..." | |
| @@ -20,6 +21,7 @@ for f in "${CONFIG_FILES[@]}"; do | |||
| 20 | 21 | # Remove the leading dot for the URL path | |
| 21 | 22 | remote_name="${f#.}" | |
| 22 | 23 | [[ "$f" == ".config/starship.toml" ]] && remote_name="starship.toml" | |
| 24 | + | [[ "$f" == ".config/opencode/agents/ai-commit.md" ]] && remote_name="ai-commit.md" | |
| 23 | 25 | url="$GIST_RAW_BASE/$remote_name" | |
| 24 | 26 | target="$HOME/$f" | |
| 25 | 27 | tmp="${target}.tmp.$$" | |
func
| @@ -733,7 +733,7 @@ $diff" -s --no-ask-user --allow-tool='shell(git:*)' | |||
| 733 | 733 | ||
| 734 | 734 | opencode) | |
| 735 | 735 | echo "🤖 OpenCode is analyzing staged changes..." | |
| 736 | - | cat "$HOME/.config/ai-commit-prompt.txt" <(echo -e "\n\nHere is the git diff:\n$diff") | opencode run --agent "AI commit" | |
| 736 | + | cat "$HOME/.config/ai-commit-prompt.txt" <(echo -e "\n\nHere is the git diff:\n$diff") | opencode run --agent ai-commit | |
| 737 | 737 | ;; | |
| 738 | 738 | ||
| 739 | 739 | *) | |
zsh_macos.sh
| @@ -28,6 +28,7 @@ CONFIG_FILES=( | |||
| 28 | 28 | ".vimrc" | |
| 29 | 29 | ".zshrc" | |
| 30 | 30 | ".config/starship.toml" | |
| 31 | + | ".config/opencode/agents/ai-commit.md" | |
| 31 | 32 | ) | |
| 32 | 33 | ||
| 33 | 34 | # ============================= | |
| @@ -92,6 +93,7 @@ download_configs() { | |||
| 92 | 93 | # Strip the leading dot for the download URL | |
| 93 | 94 | local remote_file="${f#.}" | |
| 94 | 95 | [[ "$f" == ".config/starship.toml" ]] && remote_file="starship.toml" | |
| 96 | + | [[ "$f" == ".config/opencode/agents/ai-commit.md" ]] && remote_file="ai-commit.md" | |
| 95 | 97 | local url="$GIST_RAW_BASE/$remote_file" | |
| 96 | 98 | local target="$HOME/$f" | |
| 97 | 99 | local tmp="${target}.tmp.$$" | |
zsh_ubuntu.sh
| @@ -31,6 +31,7 @@ CONFIG_FILES=( | |||
| 31 | 31 | ".vimrc" | |
| 32 | 32 | ".zshrc" | |
| 33 | 33 | ".config/starship.toml" | |
| 34 | + | ".config/opencode/agents/ai-commit.md" | |
| 34 | 35 | ) | |
| 35 | 36 | ||
| 36 | 37 | # ============================= | |
| @@ -183,6 +184,7 @@ download_configs() { | |||
| 183 | 184 | for f in "${CONFIG_FILES[@]}"; do | |
| 184 | 185 | local remote_file="${f#.}" | |
| 185 | 186 | [[ "$f" == ".config/starship.toml" ]] && remote_file="starship.toml" | |
| 187 | + | [[ "$f" == ".config/opencode/agents/ai-commit.md" ]] && remote_file="ai-commit.md" | |
| 186 | 188 | local url="$GIST_RAW_BASE/$remote_file" | |
| 187 | 189 | local target="$HOME/$f" | |
| 188 | 190 | local tmp="${target}.tmp.$$" | |
zsh_wsl.sh
| @@ -31,6 +31,7 @@ CONFIG_FILES=( | |||
| 31 | 31 | ".vimrc" | |
| 32 | 32 | ".zshrc" | |
| 33 | 33 | ".config/starship.toml" | |
| 34 | + | ".config/opencode/agents/ai-commit.md" | |
| 34 | 35 | ) | |
| 35 | 36 | ||
| 36 | 37 | # ============================= | |
| @@ -185,6 +186,7 @@ download_configs() { | |||
| 185 | 186 | for f in "${CONFIG_FILES[@]}"; do | |
| 186 | 187 | local remote_file="${f#.}" | |
| 187 | 188 | [[ "$f" == ".config/starship.toml" ]] && remote_file="starship.toml" | |
| 189 | + | [[ "$f" == ".config/opencode/agents/ai-commit.md" ]] && remote_file="ai-commit.md" | |
| 188 | 190 | local url="$GIST_RAW_BASE/$remote_file" | |
| 189 | 191 | local target="$HOME/$f" | |
| 190 | 192 | local tmp="${target}.tmp.$$" | |
Vernon Wee Hong KOH ревизий этого фрагмента 2 weeks ago. К ревизии
1 file changed, 1 insertion, 1 deletion
func
| @@ -733,7 +733,7 @@ $diff" -s --no-ask-user --allow-tool='shell(git:*)' | |||
| 733 | 733 | ||
| 734 | 734 | opencode) | |
| 735 | 735 | echo "🤖 OpenCode is analyzing staged changes..." | |
| 736 | - | cat "$HOME/.config/ai-commit-prompt.txt" <(echo -e "\n\nHere is the git diff:\n$diff") | opencode run | |
| 736 | + | cat "$HOME/.config/ai-commit-prompt.txt" <(echo -e "\n\nHere is the git diff:\n$diff") | opencode run --agent "AI commit" | |
| 737 | 737 | ;; | |
| 738 | 738 | ||
| 739 | 739 | *) | |
Vernon Wee Hong KOH ревизий этого фрагмента 2 weeks ago. К ревизии
1 file changed, 4 insertions
func
| @@ -420,6 +420,10 @@ prompt() { | |||
| 420 | 420 | return 1 | |
| 421 | 421 | fi | |
| 422 | 422 | ||
| 423 | + | if [ -t 1 ]; then | |
| 424 | + | clear | |
| 425 | + | fi | |
| 426 | + | ||
| 423 | 427 | printf "Enhanced prompt:\n" | |
| 424 | 428 | command cat "$output_file" | |
| 425 | 429 | rm -f "$output_file" | |
Vernon Wee Hong KOH ревизий этого фрагмента 2 weeks ago. К ревизии
1 file changed, 1 deletion
sourcerc
| @@ -13,7 +13,6 @@ fi | |||
| 13 | 13 | # ============================================================================= | |
| 14 | 14 | # CLAUDE CODE / AI GATEWAY | |
| 15 | 15 | # ============================================================================= | |
| 16 | - | export ANTHROPIC_BASE_URL="https://gateway.ai.cloudflare.com/v1/9a71825e3842e918e0dff9ad84f50484/claude-code-gateway/anthropic" | |
| 17 | 16 | ||
| 18 | 17 | # ============================================================================= | |
| 19 | 18 | # SDKMAN (Java/Kotlin/Scala Version Manager) | |
Vernon Wee Hong KOH ревизий этого фрагмента 2 weeks ago. К ревизии
3 files changed, 45 insertions, 18 deletions
zsh_macos.sh
| @@ -173,6 +173,13 @@ EOF | |||
| 173 | 173 | ok ".zshrc configured for Oh My Zsh framework with Starship prompt" | |
| 174 | 174 | } | |
| 175 | 175 | ||
| 176 | + | configure_git_identity() { | |
| 177 | + | log "Configuring global Git identity..." | |
| 178 | + | git config --global user.name "Vernon Wee Hong KOH" | |
| 179 | + | git config --global user.email "261549452+weehong@users.noreply.github.com" | |
| 180 | + | ok "Global Git identity configured" | |
| 181 | + | } | |
| 182 | + | ||
| 176 | 183 | switch_shell() { | |
| 177 | 184 | log "Starting Zsh session..." | |
| 178 | 185 | echo -e "${YELLOW}Type 'exit' to return to this installer menu.${NC}" | |
| @@ -189,13 +196,14 @@ show_menu() { | |||
| 189 | 196 | echo "===========================================" | |
| 190 | 197 | echo "macOS Minimal Zsh Setup - Choose what to do" | |
| 191 | 198 | echo "===========================================" | |
| 192 | - | echo " 0) Run ALL steps (1-5)" | |
| 199 | + | echo " 0) Run ALL steps (1-6)" | |
| 193 | 200 | echo " 1) Install Oh My Zsh + plugins" | |
| 194 | 201 | echo " 2) Install Starship prompt" | |
| 195 | 202 | echo " 3) Download custom configs (~/.alias, .func, .vimrc, etc.)" | |
| 196 | 203 | echo " 4) Configure ~/.zshrc (Oh My Zsh + Starship)" | |
| 197 | - | echo " 5) Switch to Zsh (Temporary Sub-shell)" | |
| 198 | - | echo " 6) Quit" | |
| 204 | + | echo " 5) Configure global Git identity" | |
| 205 | + | echo " 6) Switch to Zsh (Temporary Sub-shell)" | |
| 206 | + | echo " 7) Quit" | |
| 199 | 207 | echo "===========================================" | |
| 200 | 208 | } | |
| 201 | 209 | ||
| @@ -211,7 +219,7 @@ run_choices() { | |||
| 211 | 219 | if [[ "$item" == !* ]]; then | |
| 212 | 220 | to_exclude+=("${item:1}") | |
| 213 | 221 | elif [[ "$item" == "0" ]]; then | |
| 214 | - | to_run+=(1 2 3 4 5) | |
| 222 | + | to_run+=(1 2 3 4 5 6) | |
| 215 | 223 | else | |
| 216 | 224 | to_run+=("$item") | |
| 217 | 225 | fi | |
| @@ -237,8 +245,9 @@ run_choices() { | |||
| 237 | 245 | 2) install_starship ;; | |
| 238 | 246 | 3) download_configs ;; | |
| 239 | 247 | 4) configure_zshrc ;; | |
| 240 | - | 5) switch_shell ;; | |
| 241 | - | 6) exit 0 ;; | |
| 248 | + | 5) configure_git_identity ;; | |
| 249 | + | 6) switch_shell ;; | |
| 250 | + | 7) exit 0 ;; | |
| 242 | 251 | *) warn "Skipping invalid option: $choice" ;; | |
| 243 | 252 | esac | |
| 244 | 253 | echo | |
zsh_ubuntu.sh
| @@ -264,6 +264,13 @@ EOF | |||
| 264 | 264 | ok ".zshrc configured for Oh My Zsh framework with Starship prompt" | |
| 265 | 265 | } | |
| 266 | 266 | ||
| 267 | + | configure_git_identity() { | |
| 268 | + | log "Configuring global Git identity..." | |
| 269 | + | git config --global user.name "Vernon Wee Hong KOH" | |
| 270 | + | git config --global user.email "261549452+weehong@users.noreply.github.com" | |
| 271 | + | ok "Global Git identity configured" | |
| 272 | + | } | |
| 273 | + | ||
| 267 | 274 | switch_shell() { | |
| 268 | 275 | log "Starting Zsh session..." | |
| 269 | 276 | echo -e "${YELLOW}Type 'exit' to return to this installer menu.${NC}" | |
| @@ -280,7 +287,7 @@ show_menu() { | |||
| 280 | 287 | echo "===========================================" | |
| 281 | 288 | echo "Minimal Zsh Installer - Choose what to do" | |
| 282 | 289 | echo "===========================================" | |
| 283 | - | echo " 0) Run ALL steps (1-10)" | |
| 290 | + | echo " 0) Run ALL steps (1-11)" | |
| 284 | 291 | echo " 1) Update system packages" | |
| 285 | 292 | echo " 2) Install core packages (zsh, git, vim, etc.)" | |
| 286 | 293 | echo " 3) Set Timezone (Asia/Singapore)" | |
| @@ -290,8 +297,9 @@ show_menu() { | |||
| 290 | 297 | echo " 7) Install Starship prompt" | |
| 291 | 298 | echo " 8) Download custom configs (from OpenGist)" | |
| 292 | 299 | echo " 9) Configure ~/.zshrc (Oh My Zsh + Starship)" | |
| 293 | - | echo "10) Switch to Zsh (Temporary Sub-shell)" | |
| 294 | - | echo "11) Quit" | |
| 300 | + | echo "10) Configure global Git identity" | |
| 301 | + | echo "11) Switch to Zsh (Temporary Sub-shell)" | |
| 302 | + | echo "12) Quit" | |
| 295 | 303 | echo "===========================================" | |
| 296 | 304 | } | |
| 297 | 305 | ||
| @@ -307,7 +315,7 @@ run_choices() { | |||
| 307 | 315 | if [[ "$item" == !* ]]; then | |
| 308 | 316 | to_exclude+=("${item:1}") | |
| 309 | 317 | elif [[ "$item" == "0" ]]; then | |
| 310 | - | to_run+=(1 2 3 4 5 6 7 8 9 10) | |
| 318 | + | to_run+=(1 2 3 4 5 6 7 8 9 10 11) | |
| 311 | 319 | else | |
| 312 | 320 | to_run+=("$item") | |
| 313 | 321 | fi | |
| @@ -335,8 +343,9 @@ run_choices() { | |||
| 335 | 343 | 7) install_starship ;; | |
| 336 | 344 | 8) download_configs ;; | |
| 337 | 345 | 9) configure_zshrc ;; | |
| 338 | - | 10) switch_shell ;; | |
| 339 | - | 11) log "Exiting..."; exit 0 ;; | |
| 346 | + | 10) configure_git_identity ;; | |
| 347 | + | 11) switch_shell ;; | |
| 348 | + | 12) log "Exiting..."; exit 0 ;; | |
| 340 | 349 | *) warn "Skipping invalid option: $choice" ;; | |
| 341 | 350 | esac | |
| 342 | 351 | echo | |
zsh_wsl.sh
| @@ -266,6 +266,13 @@ EOF | |||
| 266 | 266 | ok ".zshrc configured for Oh My Zsh framework with Starship prompt" | |
| 267 | 267 | } | |
| 268 | 268 | ||
| 269 | + | configure_git_identity() { | |
| 270 | + | log "Configuring global Git identity..." | |
| 271 | + | git config --global user.name "Vernon Wee Hong KOH" | |
| 272 | + | git config --global user.email "261549452+weehong@users.noreply.github.com" | |
| 273 | + | ok "Global Git identity configured" | |
| 274 | + | } | |
| 275 | + | ||
| 269 | 276 | switch_shell() { | |
| 270 | 277 | log "Starting Zsh session..." | |
| 271 | 278 | echo -e "${YELLOW}Type 'exit' to return to this installer menu.${NC}" | |
| @@ -282,7 +289,7 @@ show_menu() { | |||
| 282 | 289 | echo "===========================================" | |
| 283 | 290 | echo "WSL Minimal Zsh Installer - Choose what to do" | |
| 284 | 291 | echo "===========================================" | |
| 285 | - | echo " 0) Run ALL steps (1-10)" | |
| 292 | + | echo " 0) Run ALL steps (1-11)" | |
| 286 | 293 | echo " 1) Update system packages" | |
| 287 | 294 | echo " 2) Install core packages (zsh, git, vim, etc.)" | |
| 288 | 295 | echo " 3) Set Timezone (best effort)" | |
| @@ -292,8 +299,9 @@ show_menu() { | |||
| 292 | 299 | echo " 7) Install Starship prompt" | |
| 293 | 300 | echo " 8) Download custom configs (from OpenGist)" | |
| 294 | 301 | echo " 9) Configure ~/.zshrc (Oh My Zsh + Starship)" | |
| 295 | - | echo "10) Switch to Zsh (Temporary Sub-shell)" | |
| 296 | - | echo "11) Quit" | |
| 302 | + | echo "10) Configure global Git identity" | |
| 303 | + | echo "11) Switch to Zsh (Temporary Sub-shell)" | |
| 304 | + | echo "12) Quit" | |
| 297 | 305 | echo "===========================================" | |
| 298 | 306 | } | |
| 299 | 307 | ||
| @@ -309,7 +317,7 @@ run_choices() { | |||
| 309 | 317 | if [[ "$item" == !* ]]; then | |
| 310 | 318 | to_exclude+=("${item:1}") | |
| 311 | 319 | elif [[ "$item" == "0" ]]; then | |
| 312 | - | to_run+=(1 2 3 4 5 6 7 8 9 10) | |
| 320 | + | to_run+=(1 2 3 4 5 6 7 8 9 10 11) | |
| 313 | 321 | else | |
| 314 | 322 | to_run+=("$item") | |
| 315 | 323 | fi | |
| @@ -337,8 +345,9 @@ run_choices() { | |||
| 337 | 345 | 7) install_starship ;; | |
| 338 | 346 | 8) download_configs ;; | |
| 339 | 347 | 9) configure_zshrc ;; | |
| 340 | - | 10) switch_shell ;; | |
| 341 | - | 11) log "Exiting..."; exit 0 ;; | |
| 348 | + | 10) configure_git_identity ;; | |
| 349 | + | 11) switch_shell ;; | |
| 350 | + | 12) log "Exiting..."; exit 0 ;; | |
| 342 | 351 | *) warn "Skipping invalid option: $choice" ;; | |
| 343 | 352 | esac | |
| 344 | 353 | echo | |
Vernon Wee Hong KOH ревизий этого фрагмента 3 weeks ago. К ревизии
13 files changed, 447 insertions, 1884 deletions
ADR.md (файл удалён)
| @@ -1,64 +0,0 @@ | |||
| 1 | - | # Architecture Decision Records | |
| 2 | - | ||
| 3 | - | ## ADR-001: Documentation-First Architect Mode | |
| 4 | - | ||
| 5 | - | **Status:** Accepted | |
| 6 | - | ||
| 7 | - | **Date:** 2026-07-28 | |
| 8 | - | ||
| 9 | - | ### Context | |
| 10 | - | ||
| 11 | - | The existing `plan_build` workflow makes Claude Code the implementation orchestrator but does not enforce durable specifications, atomic Codex task prompts, client handover documentation, or a strict separation between documentation and code execution. | |
| 12 | - | ||
| 13 | - | ### Decision | |
| 14 | - | ||
| 15 | - | Add an opt-in built-in `--architect` mode. Claude Code owns discovery, architecture, documentation, dispatch, and verification. Codex is the sole code and test-code executor. CodeRabbit reviews every task and the final aggregate diff. Tasks execute sequentially, and all approved work is committed once after final verification and explicit user approval. | |
| 16 | - | ||
| 17 | - | ### Alternatives Considered | |
| 18 | - | ||
| 19 | - | - Replace the default workflow: rejected because direct implementation remains useful. | |
| 20 | - | - Keep Claude as an implementation fallback: rejected because it weakens the requested role boundary. | |
| 21 | - | - Execute tasks in parallel: rejected because sequential execution provides clearer scope, review, and failure attribution. | |
| 22 | - | ||
| 23 | - | ### Consequences | |
| 24 | - | ||
| 25 | - | - Architect mode requires an interactive terminal and additional workflow state documents. | |
| 26 | - | - Long-running work can resume from repository records rather than chat history. | |
| 27 | - | - Delivery takes more approval steps but produces a complete auditable handover package. | |
| 28 | - | ||
| 29 | - | ### Affected Components | |
| 30 | - | ||
| 31 | - | - `func` | |
| 32 | - | - `test_plan_build.zsh` | |
| 33 | - | - `architect-workflow.md` | |
| 34 | - | - Installer scripts addressed by `TASK-003` | |
| 35 | - | ||
| 36 | - | ## ADR-002: Remove the Standalone v2 Integration | |
| 37 | - | ||
| 38 | - | **Status:** Accepted | |
| 39 | - | ||
| 40 | - | **Date:** 2026-07-28 | |
| 41 | - | ||
| 42 | - | ### Context | |
| 43 | - | ||
| 44 | - | The built-in `--v2` path downloads a standalone script from an unavailable endpoint. Retaining the path exposes a broken user interface and creates a second workflow source that can drift. | |
| 45 | - | ||
| 46 | - | ### Decision | |
| 47 | - | ||
| 48 | - | Remove the v2 downloader, parser branch, passthrough behavior, usage text, and documentation. `--v2` now follows the normal unknown-argument path. | |
| 49 | - | ||
| 50 | - | ### Alternatives Considered | |
| 51 | - | ||
| 52 | - | - Repair or recreate the standalone gist: rejected because v2 is no longer required. | |
| 53 | - | - Preserve the broken option as undocumented behavior: rejected because it would remain a misleading public contract. | |
| 54 | - | ||
| 55 | - | ### Consequences | |
| 56 | - | ||
| 57 | - | - `--grill` and `--distribute` are no longer reachable through `plan_build`. | |
| 58 | - | - The built-in command has one maintained implementation path. | |
| 59 | - | ||
| 60 | - | ### Affected Components | |
| 61 | - | ||
| 62 | - | - `func` | |
| 63 | - | - `test_plan_build.zsh` | |
| 64 | - | - `README.md` | |
CHANGELOG.md (файл удалён)
| @@ -1,22 +0,0 @@ | |||
| 1 | - | # Changelog | |
| 2 | - | ||
| 3 | - | All notable changes to this project are documented in this file. | |
| 4 | - | ||
| 5 | - | ## Unreleased | |
| 6 | - | ||
| 7 | - | ### Added | |
| 8 | - | ||
| 9 | - | - `TASK-002`: Added built-in `plan_build --architect` with safe-resume, new-workflow, yolo, preflight, and command-level regression coverage. | |
| 10 | - | - Added the canonical documentation-first architect workflow source. | |
| 11 | - | ||
| 12 | - | ### Changed | |
| 13 | - | ||
| 14 | - | - Documented architect mode prerequisites and supported flag combinations. | |
| 15 | - | ||
| 16 | - | ### Removed | |
| 17 | - | ||
| 18 | - | - `TASK-001`: Removed the obsolete standalone v2 downloader, forwarding behavior, and public usage contract. | |
| 19 | - | ||
| 20 | - | ### Fixed | |
| 21 | - | ||
| 22 | - | - `TASK-002`: Reject bare Git repositories during architect preflight while accepting normal worktrees. | |
README.md
| @@ -33,29 +33,24 @@ Starship owns the prompt and loads after Oh My Zsh. The managed Starship config | |||
| 33 | 33 | ||
| 34 | 34 | ## Plan-build workflow | |
| 35 | 35 | ||
| 36 | - | `plan_build` launches Claude Code as the implementation orchestrator, with Codex and CodeRabbit as independent reviewers. The configuration installer also installs its workflow at `~/.claude/skills/plan-build/SKILL.md`. | |
| 37 | - | ||
| 38 | - | Architect mode keeps Claude focused on architecture and documentation while Codex implements one approved task at a time and CodeRabbit reviews each task. It uses `~/.claude/skills/plan-build-architect/SKILL.md`. | |
| 36 | + | The local `plan_build` function is a thin cached launcher for the canonical public [plan-build gist](https://opengist.resetrix.work/weehong/plan-build). When curl is available, each invocation stages `plan_build.zsh`, `SKILL.md`, and `ARCHITECT.md`, requires all three to be non-empty, and syntax-checks the executable. It then moves the complete bundle into a unique immutable release directory and atomically switches one `current` symlink. Refresh activation is serialized with a kernel-backed Zsh file lock so concurrent callers cannot mix releases and crashes cannot leave a stale lock. If refresh fails, the launcher preserves and uses the last complete, validated release and repairs its skill links. Zsh is always required; curl is required only when no valid cached release exists. | |
| 39 | 37 | ||
| 40 | 38 | ```zsh | |
| 41 | - | plan_build # Standard plan and build | |
| 42 | - | plan_build --prompt # Enhance the payload with Auggie first | |
| 43 | - | plan_build --writing-plan # Superpowers implementation plan, Codex review, then build | |
| 44 | - | plan_build --prompt --brainstorm # Auggie, Superpowers design and plan, Codex review, then build | |
| 45 | - | plan_build --yolo --writing-plan # Pass --yolo through to Claude Code | |
| 46 | - | plan_build --architect # Documentation-first architecture workflow | |
| 47 | - | plan_build --architect --new # Archive existing planning state and start a new workflow | |
| 48 | - | plan_build --architect --yolo # Forward --yolo without bypassing workflow approval gates | |
| 39 | + | plan_build | |
| 40 | + | plan_build --prompt | |
| 41 | + | plan_build --writing-plan | |
| 42 | + | plan_build --prompt --brainstorm | |
| 43 | + | plan_build --yolo --writing-plan | |
| 44 | + | plan_build --architect | |
| 45 | + | plan_build --architect --new | |
| 46 | + | plan_build --architect --yolo | |
| 49 | 47 | ``` | |
| 50 | 48 | ||
| 51 | - | `--brainstorm` and `--writing-plan` are mutually exclusive. They require the enabled `superpowers@claude-plugins-official` Claude Code plugin; `plan_build` reports the install or enable command and exits before Auggie when the requirement is not met. | |
| 49 | + | The canonical executable defines the current command behavior and options. Each invocation binds the executable and both skills to its selected immutable release. The launcher also points the installed Claude Code skill paths through the active `current` release: | |
| 52 | 50 | ||
| 53 | - | `--architect` may combine only with `--new` and `--yolo`. It requires an interactive terminal, a Git worktree, Claude Code, Codex, CodeRabbit, Git, and the installed architect skill. The obsolete `--v2` integration has been removed. | |
| 51 | + | - `SKILL.md` → `~/.claude/skills/plan-build/SKILL.md` | |
| 52 | + | - `ARCHITECT.md` → `~/.claude/skills/plan-build-architect/SKILL.md` | |
| 54 | 53 | ||
| 55 | - | On a machine without this full setup (`config.sh` normally installs the skill), install just the plan-build skill with: | |
| 54 | + | The launcher defaults to `https://opengist.resetrix.work/weehong/plan-build/raw/HEAD` and `${XDG_CACHE_HOME:-$HOME/.cache}/plan-build`. Override these with `PLAN_BUILD_BASE_URL` and `PLAN_BUILD_CACHE_DIR`. Installed skill paths remain fixed at `~/.claude/skills`; cached invocations receive immutable release paths through environment variables. The downloaded script is remote executable code: syntax validation catches malformed Zsh but is not a security sandbox, so only point `PLAN_BUILD_BASE_URL` at a source you trust. Remote code is executed in a child Zsh process and is never sourced into the caller shell. | |
| 56 | 55 | ||
| 57 | - | ```zsh | |
| 58 | - | mkdir -p ~/.claude/skills/plan-build ~/.claude/skills/plan-build-architect | |
| 59 | - | curl -fsSL https://opengist.resetrix.work/weehong/f0d940c3c1214bf5b7996195199fdc09/raw/HEAD/orchestrate-loop.md -o ~/.claude/skills/plan-build/SKILL.md | |
| 60 | - | curl -fsSL https://opengist.resetrix.work/weehong/f0d940c3c1214bf5b7996195199fdc09/raw/HEAD/architect-workflow.md -o ~/.claude/skills/plan-build-architect/SKILL.md | |
| 61 | - | ``` | |
| 56 | + | Invoking `plan_build` once installs or repairs both skill links. To install standalone files without the cached launcher, follow the installation instructions in the canonical gist instead. | |
SPEC.md (файл удалён)
| @@ -1,500 +0,0 @@ | |||
| 1 | - | # Plan Build Architect Mode Specification | |
| 2 | - | ||
| 3 | - | ## 1. Executive Summary & Goals | |
| 4 | - | ||
| 5 | - | ### Problem Statement | |
| 6 | - | ||
| 7 | - | The existing `plan_build` command asks Claude Code to plan and implement a task through an eight-step multi-agent workflow. It does not provide a documentation-first delivery mode in which Claude acts strictly as architect and documentation manager while OpenAI Codex performs all implementation work. | |
| 8 | - | ||
| 9 | - | This creates three handover risks: | |
| 10 | - | ||
| 11 | - | 1. Requirements and architecture decisions can remain implicit in agent conversations. | |
| 12 | - | 2. Implementation tasks may not have durable, atomic scopes and acceptance criteria. | |
| 13 | - | 3. The final repository may lack the user, operational, API, deployment, security, and acceptance documentation required for a client handover. | |
| 14 | - | ||
| 15 | - | ### Solution | |
| 16 | - | ||
| 17 | - | Add an optional built-in `plan_build --architect` mode. In this mode, Claude Code owns discovery, specifications, task decomposition, review orchestration, progress records, and final handover documentation. Codex is the sole implementation executor. CodeRabbit reviews every completed task and the final aggregate diff. | |
| 18 | - | ||
| 19 | - | Architect mode follows three gated phases: | |
| 20 | - | ||
| 21 | - | 1. **Discovery and Architecture:** Claude interviews the user one question at a time and recommends a default answer for each decision. | |
| 22 | - | 2. **Documentation Synthesis:** After an explicit phase-completion phrase, Claude writes the approved requirements into `SPEC.md` without asking additional questions. | |
| 23 | - | 3. **Codex Execution Plan:** After specification approval, Claude writes atomic sequential task briefs and self-contained Codex prompts into `TASKS.md`. | |
| 24 | - | ||
| 25 | - | Codex tasks execute only after `TASKS.md` approval. Exactly one task may be active at a time. All implementation and documentation changes remain uncommitted until the complete workflow, reviews, tests, and client handover package pass final verification. The user must approve the single final commit. The workflow never pushes automatically. | |
| 26 | - | ||
| 27 | - | ### Goals | |
| 28 | - | ||
| 29 | - | - Preserve the existing default `plan_build` behavior. | |
| 30 | - | - Add `--architect` as an explicit opt-in mode. | |
| 31 | - | - Remove the obsolete and broken `--v2` integration from the built-in command. | |
| 32 | - | - Keep Claude from writing implementation or test code in architect mode. | |
| 33 | - | - Make Codex tasks atomic, sequential, auditable, and constrained by file scope. | |
| 34 | - | - Require explicit approval at every phase and execution boundary. | |
| 35 | - | - Require CodeRabbit review after every task and over the final combined diff. | |
| 36 | - | - Produce complete internal engineering records and client-facing handover documentation. | |
| 37 | - | - Resume interrupted architect workflows safely. | |
| 38 | - | - Preserve existing project documentation and user work. | |
| 39 | - | - Produce one user-approved commit only after all tasks are complete. | |
| 40 | - | ||
| 41 | - | ### Non-Goals | |
| 42 | - | ||
| 43 | - | - Replacing the existing standard, brainstorm, writing-plan, prompt-enhancement, or yolo workflows. | |
| 44 | - | - Allowing unattended architect execution. | |
| 45 | - | - Allowing Claude to implement application or test code. | |
| 46 | - | - Automatically pushing the final commit. | |
| 47 | - | - Inventing project behavior, infrastructure, controls, or APIs that do not exist. | |
| 48 | - | ||
| 49 | - | ## 2. User Stories | |
| 50 | - | ||
| 51 | - | 1. As a project owner, I want Claude to interview me one question at a time, so that architectural decisions remain understandable and deliberate. | |
| 52 | - | 2. As a project owner, I want each question to include a recommended default, so that discovery can proceed efficiently. | |
| 53 | - | 3. As a project owner, I want explicit phase gates, so that no specification or implementation begins before I approve it. | |
| 54 | - | 4. As a project owner, I want a cohesive `SPEC.md`, so that requirements and contracts have one approved baseline. | |
| 55 | - | 5. As a project owner, I want atomic Codex prompts in `TASKS.md`, so that implementation work has clear boundaries. | |
| 56 | - | 6. As a project owner, I want only one Codex task active at a time, so that failures and diffs remain attributable. | |
| 57 | - | 7. As a project owner, I want Claude to inspect but not implement code, so that architecture and execution responsibilities remain separated. | |
| 58 | - | 8. As a project owner, I want CodeRabbit to review every task, so that defects are found before dependent work begins. | |
| 59 | - | 9. As a project owner, I want one final holistic review, so that cross-task regressions are detected. | |
| 60 | - | 10. As a project owner, I want all work committed once at the end, so that the complete delivery appears as one coherent change. | |
| 61 | - | 11. As a project owner, I want interrupted sessions to resume from durable records, so that long projects do not lose state. | |
| 62 | - | 12. As a client, I want user and operational documentation, so that I can adopt and run the delivered system. | |
| 63 | - | 13. As a client, I want deployment and rollback instructions, so that releases can be managed safely. | |
| 64 | - | 14. As a client, I want security and ownership documentation, so that operational responsibilities are explicit. | |
| 65 | - | 15. As a client, I want a formal acceptance checklist, so that handover completion is objectively verifiable. | |
| 66 | - | 16. As an engineer, I want approved specification changes recorded, so that implementation does not silently drift from requirements. | |
| 67 | - | 17. As an engineer, I want file-scope enforcement, so that Codex cannot introduce unrelated changes. | |
| 68 | - | 18. As an engineer, I want focused tests per task and full verification at completion, so that failures are localized without sacrificing system confidence. | |
| 69 | - | 19. As an operator, I want documentation claims tied to source files and verified commands, so that instructions can be trusted. | |
| 70 | - | 20. As a security reviewer, I want secrets excluded from prompts and documents, so that the workflow does not leak credentials. | |
| 71 | - | ||
| 72 | - | ## 3. System Architecture & Tech Stack | |
| 73 | - | ||
| 74 | - | ### Existing Context | |
| 75 | - | ||
| 76 | - | The feature extends a Zsh function-based command distributed through the Zsh Setup OpenGist. The current command launches Claude Code with an installed workflow document. Existing behavior is covered by a Zsh test script that stubs external CLIs and asserts command-level output and argument contracts. | |
| 77 | - | ||
| 78 | - | ### Runtime Components | |
| 79 | - | ||
| 80 | - | | Component | Responsibility in architect mode | | |
| 81 | - | | --- | --- | | |
| 82 | - | | `plan_build` Zsh function | Parse flags, reject incompatible combinations, run preflight, collect the initial payload, and launch Claude with the architect workflow. | | |
| 83 | - | | Claude Code | Lead architect, documentation manager, task dispatcher, scope verifier, review triager, and phase-gate controller. | | |
| 84 | - | | OpenAI Codex CLI | Sole application and test-code executor, invoked non-interactively for one approved task at a time. | | |
| 85 | - | | CodeRabbit CLI | Automated reviewer after every task and over the final aggregate diff. | | |
| 86 | - | | Git | Baseline detection, diff isolation, traceability, and one final user-approved commit. | | |
| 87 | - | | Markdown files | Durable workflow state, approved requirements, decisions, execution records, and client handover package. | | |
| 88 | - | ||
| 89 | - | ### Canonical Workflow Source | |
| 90 | - | ||
| 91 | - | Architect mode must have one canonical workflow document in the Zsh Setup gist. The configuration installer and all supported platform installers distribute that same document to: | |
| 92 | - | ||
| 93 | - | `~/.claude/skills/plan-build-architect/SKILL.md` | |
| 94 | - | ||
| 95 | - | The active local installation and published OpenGist source must remain identical after rollout. | |
| 96 | - | ||
| 97 | - | ### Execution Topology | |
| 98 | - | ||
| 99 | - | ```mermaid | |
| 100 | - | flowchart TD | |
| 101 | - | U[Project Owner] -->|Initial payload| PB[plan_build --architect] | |
| 102 | - | PB -->|Preflight and architect prompt| C[Claude Code] | |
| 103 | - | C -->|One question at a time| U | |
| 104 | - | U -->|Explicit phase approvals| C | |
| 105 | - | C -->|Writes and maintains| D[Engineering and handover Markdown] | |
| 106 | - | C -->|One approved task prompt| X[Codex CLI] | |
| 107 | - | X -->|Scoped code and tests| W[Shared Git worktree] | |
| 108 | - | C -->|Inspect diff and verify| W | |
| 109 | - | C -->|Review request| R[CodeRabbit CLI] | |
| 110 | - | R -->|Findings| C | |
| 111 | - | C -->|Valid fixes delegated| X | |
| 112 | - | C -->|Task and final approval requests| U | |
| 113 | - | U -->|Final commit approval| C | |
| 114 | - | C -->|One commit, no push| G[Git history] | |
| 115 | - | ``` | |
| 116 | - | ||
| 117 | - | ### Responsibility Boundary | |
| 118 | - | ||
| 119 | - | Claude may inspect every project file but may create or modify only documentation and orchestration records during architect execution: | |
| 120 | - | ||
| 121 | - | - `SPEC.md` | |
| 122 | - | - `TASKS.md` | |
| 123 | - | - `ADR.md` | |
| 124 | - | - `CHANGELOG.md` | |
| 125 | - | - `README.md` | |
| 126 | - | - Files under `docs/` that form the client handover package | |
| 127 | - | ||
| 128 | - | Codex owns all application code, configuration code, migrations, generated source, and test-code modifications. If a required change falls outside an approved task scope, Codex stops and reports the required expansion rather than modifying the file. | |
| 129 | - | ||
| 130 | - | ### Interactive Constraint | |
| 131 | - | ||
| 132 | - | Architect mode requires a usable interactive terminal. It must fail before modifying project files when a TTY is unavailable. This protects all mandatory approval gates. | |
| 133 | - | ||
| 134 | - | ## 4. Data Models & Schemas | |
| 135 | - | ||
| 136 | - | Architect mode introduces no application database schema. Its durable state is represented by structured Markdown documents. | |
| 137 | - | ||
| 138 | - | ### Project Metadata | |
| 139 | - | ||
| 140 | - | Discovery must collect: | |
| 141 | - | ||
| 142 | - | - Project name | |
| 143 | - | - Client or owning organization | |
| 144 | - | - Product purpose | |
| 145 | - | - Target users | |
| 146 | - | - Repository scope | |
| 147 | - | - Supported environments | |
| 148 | - | - Deployment owner | |
| 149 | - | - Operational owner | |
| 150 | - | - Support contact role | |
| 151 | - | - Compliance constraints | |
| 152 | - | - Intended handover date | |
| 153 | - | ||
| 154 | - | Sensitive identities may use user-approved placeholders. | |
| 155 | - | ||
| 156 | - | ### Task Record | |
| 157 | - | ||
| 158 | - | Every `TASKS.md` task must contain: | |
| 159 | - | ||
| 160 | - | | Field | Requirement | | |
| 161 | - | | --- | --- | | |
| 162 | - | | ID | Stable sequential identifier such as `TASK-001`. | | |
| 163 | - | | Title | Concise implementation outcome. | | |
| 164 | - | | Status | One of `Pending`, `In Progress`, `Blocked`, `Review`, or `Complete`. | | |
| 165 | - | | Dependencies | IDs that must be complete first, or `None`. | | |
| 166 | - | | Objective | Exact feature, behavior, or function Codex must implement. | | |
| 167 | - | | Allowed File Scope | Exhaustive files or bounded path patterns Codex may create or modify. | | |
| 168 | - | | Context / Interfaces | Approved schemas, contracts, imports, conventions, and relevant existing behavior. | | |
| 169 | - | | Prompt for Codex | Self-contained non-interactive execution prompt. | | |
| 170 | - | | Acceptance Criteria | Observable behavior and required test coverage. | | |
| 171 | - | | Verification Commands | Focused lint, type-check, unit, integration, or build commands. | | |
| 172 | - | | CodeRabbit Outcome | Findings, triage result, and rerun status. | | |
| 173 | - | | Completion Evidence | Commands run, results, and relevant diff evidence. | | |
| 174 | - | ||
| 175 | - | Only one task may have `In Progress` status. | |
| 176 | - | ||
| 177 | - | ### Task State Transitions | |
| 178 | - | ||
| 179 | - | ```mermaid | |
| 180 | - | stateDiagram-v2 | |
| 181 | - | [*] --> Pending | |
| 182 | - | Pending --> InProgress: approved and dependencies complete | |
| 183 | - | InProgress --> Review: Codex reports completion | |
| 184 | - | InProgress --> Blocked: execution or scope blocker | |
| 185 | - | Review --> InProgress: valid findings require fixes | |
| 186 | - | Review --> Complete: acceptance and review pass | |
| 187 | - | Blocked --> Pending: user approves revised scope or architecture | |
| 188 | - | Complete --> [*] | |
| 189 | - | ``` | |
| 190 | - | ||
| 191 | - | ### Architecture Decision Record | |
| 192 | - | ||
| 193 | - | `ADR.md` is append-only. Every decision uses a stable ID such as `ADR-001` and records: | |
| 194 | - | ||
| 195 | - | - Status | |
| 196 | - | - Date | |
| 197 | - | - Context | |
| 198 | - | - Decision | |
| 199 | - | - Alternatives considered | |
| 200 | - | - Consequences | |
| 201 | - | - Affected files or components | |
| 202 | - | - Superseding ADR, when applicable | |
| 203 | - | ||
| 204 | - | Superseded decisions remain visible. | |
| 205 | - | ||
| 206 | - | ### Changelog | |
| 207 | - | ||
| 208 | - | `CHANGELOG.md` follows Keep a Changelog conventions. Work remains under `Unreleased` until the final delivery and is grouped under: | |
| 209 | - | ||
| 210 | - | - Added | |
| 211 | - | - Changed | |
| 212 | - | - Fixed | |
| 213 | - | - Security | |
| 214 | - | - Deprecated | |
| 215 | - | - Removed | |
| 216 | - | ||
| 217 | - | Entries reference task IDs. Detailed execution evidence remains in `TASKS.md`. | |
| 218 | - | ||
| 219 | - | ### Mandatory Handover Package | |
| 220 | - | ||
| 221 | - | The following files are mandatory without exception: | |
| 222 | - | ||
| 223 | - | | File | Audience and purpose | | |
| 224 | - | | --- | --- | | |
| 225 | - | | `README.md` | Product overview, prerequisites, quick start, and configuration. | | |
| 226 | - | | `SPEC.md` | Approved requirements, architecture, schemas, contracts, constraints, and acceptance baseline. | | |
| 227 | - | | `TASKS.md` | Internal task execution and evidence record. | | |
| 228 | - | | `ADR.md` | Internal architecture decision history. | | |
| 229 | - | | `CHANGELOG.md` | Delivery and release history. | | |
| 230 | - | | `docs/USER_MANUAL.md` | End-user workflows and expected outcomes. | | |
| 231 | - | | `docs/RUNBOOK.md` | Operations, monitoring, backup, recovery, and troubleshooting. | | |
| 232 | - | | `docs/API.md` | Authentication, endpoints or commands, examples, and errors. | | |
| 233 | - | | `docs/DEPLOYMENT.md` | Environments, infrastructure, release, rollback, and validation. | | |
| 234 | - | | `docs/SECURITY.md` | Access control, secret handling, data protection, rotation, and known risks. | | |
| 235 | - | | `docs/HANDOVER.md` | Deliverables, ownership, support boundaries, limitations, and formal acceptance. | | |
| 236 | - | ||
| 237 | - | Non-applicable material must be marked `Not Applicable` with a factual rationale. Files may not be omitted. | |
| 238 | - | ||
| 239 | - | ## 5. CLI & Component Contracts | |
| 240 | - | ||
| 241 | - | ### Supported Invocation | |
| 242 | - | ||
| 243 | - | `plan_build --architect` | |
| 244 | - | ||
| 245 | - | Optional architect flags: | |
| 246 | - | ||
| 247 | - | - `--new`: Start a new architect workflow after archiving existing workflow documents. | |
| 248 | - | - `--yolo`: Forward Claude's permissive execution mode but never bypass architect approval gates. | |
| 249 | - | ||
| 250 | - | ### Incompatible Flags | |
| 251 | - | ||
| 252 | - | Architect mode must reject combinations with: | |
| 253 | - | ||
| 254 | - | - `--brainstorm` | |
| 255 | - | - `--writing-plan` | |
| 256 | - | - `--prompt` | |
| 257 | - | ||
| 258 | - | The `--v2` option, its downloader function, and its usage documentation must be removed entirely. After removal, passing `--v2` follows the normal unknown-argument error path. The built-in workflow does not expose the former v2-only `--grill` or `--distribute` concepts. | |
| 259 | - | ||
| 260 | - | ### Preflight Contract | |
| 261 | - | ||
| 262 | - | Before discovery or file modification, architect mode verifies: | |
| 263 | - | ||
| 264 | - | - Interactive TTY | |
| 265 | - | - Git repository context | |
| 266 | - | - `claude` | |
| 267 | - | - `codex` | |
| 268 | - | - `coderabbit` | |
| 269 | - | - `git` | |
| 270 | - | - Installed architect workflow document | |
| 271 | - | ||
| 272 | - | A missing requirement causes a non-zero exit with exact remediation guidance. Project-specific tools are checked when their approved tasks require them. | |
| 273 | - | ||
| 274 | - | ### Phase-Gate Contract | |
| 275 | - | ||
| 276 | - | #### Phase 1 to Phase 2 | |
| 277 | - | ||
| 278 | - | Claude may leave discovery only after the user states either: | |
| 279 | - | ||
| 280 | - | - `I am ready to generate the spec` | |
| 281 | - | - `Phase 1 complete` | |
| 282 | - | ||
| 283 | - | Claude asks one question at a time and includes one recommended default with every question. | |
| 284 | - | ||
| 285 | - | #### Phase 2 to Phase 3 | |
| 286 | - | ||
| 287 | - | Claude writes `SPEC.md` without asking more questions. It waits for explicit specification approval before creating `TASKS.md`. | |
| 288 | - | ||
| 289 | - | #### Phase 3 to Execution | |
| 290 | - | ||
| 291 | - | Claude writes `TASKS.md` and waits for explicit task-plan approval before invoking Codex. | |
| 292 | - | ||
| 293 | - | #### Between Tasks | |
| 294 | - | ||
| 295 | - | Claude dispatches one task, verifies scope and acceptance criteria, completes CodeRabbit triage, reports evidence, and waits for user approval before starting the next task. | |
| 296 | - | ||
| 297 | - | #### Final Commit | |
| 298 | - | ||
| 299 | - | Claude presents the final verification results, aggregate diff summary, and proposed commit message. It stages and commits only after explicit user approval. It never pushes. | |
| 300 | - | ||
| 301 | - | ### Codex Invocation Contract | |
| 302 | - | ||
| 303 | - | Claude invokes Codex non-interactively in the current project worktree with workspace-write access. The exact prompt stored in the approved task record is passed to Codex. Every prompt includes: | |
| 304 | - | ||
| 305 | - | - Objective | |
| 306 | - | - Allowed File Scope | |
| 307 | - | - Context / Interfaces | |
| 308 | - | - Acceptance Criteria | |
| 309 | - | - Unit or integration test requirements | |
| 310 | - | - Verification commands | |
| 311 | - | - Prohibition on commits | |
| 312 | - | - Instruction to stop before touching out-of-scope files | |
| 313 | - | ||
| 314 | - | Codex execution output is captured for verification. Claude independently inspects the diff and reruns required commands. | |
| 315 | - | ||
| 316 | - | ### CodeRabbit Contract | |
| 317 | - | ||
| 318 | - | CodeRabbit runs after each Codex task and once over the final combined diff. | |
| 319 | - | ||
| 320 | - | - Claude investigates every concrete finding. | |
| 321 | - | - Valid findings are delegated to Codex within the same task. | |
| 322 | - | - Critical, high, and medium findings block progress until resolved. | |
| 323 | - | - Low-severity findings may be deferred only with user approval. | |
| 324 | - | - Approved deferrals are recorded in `CHANGELOG.md` and `docs/HANDOVER.md`. | |
| 325 | - | - Tests and CodeRabbit rerun after substantive fixes. | |
| 326 | - | ||
| 327 | - | ### Retry Contract | |
| 328 | - | ||
| 329 | - | After the initial Codex attempt, Claude may dispatch at most two focused correction attempts. If acceptance criteria still fail: | |
| 330 | - | ||
| 331 | - | 1. Stop execution. | |
| 332 | - | 2. Mark the task `Blocked`. | |
| 333 | - | 3. Preserve the partial diff. | |
| 334 | - | 4. Record diagnostics and attempted corrections. | |
| 335 | - | 5. Ask the user whether to revise architecture, scope, or acceptance criteria. | |
| 336 | - | 6. Do not start dependent tasks. | |
| 337 | - | ||
| 338 | - | ### Resume Contract | |
| 339 | - | ||
| 340 | - | When workflow documents already exist, Claude: | |
| 341 | - | ||
| 342 | - | 1. Reads `SPEC.md`, `TASKS.md`, `ADR.md`, and `CHANGELOG.md`. | |
| 343 | - | 2. Compares their recorded state with Git and the current worktree. | |
| 344 | - | 3. Identifies the first incomplete task. | |
| 345 | - | 4. Presents the detected state and asks whether to resume. | |
| 346 | - | ||
| 347 | - | `--new` must archive existing workflow documents before creating replacements. It must never overwrite them silently. | |
| 348 | - | ||
| 349 | - | ## 6. Documentation Contracts | |
| 350 | - | ||
| 351 | - | ### Existing Documentation | |
| 352 | - | ||
| 353 | - | Claude updates existing documents in place and preserves valid project-specific content. It creates only missing files. Wholesale replacement is prohibited unless reconciliation proves that no valid content would be lost. | |
| 354 | - | ||
| 355 | - | ### Client-Facing Content | |
| 356 | - | ||
| 357 | - | Client documents describe the delivered system and do not expose Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless contractual or compliance requirements require AI disclosure. | |
| 358 | - | ||
| 359 | - | ### Traceability | |
| 360 | - | ||
| 361 | - | Implementation-specific claims reference relevant source files, configurations, schemas, endpoints, or verified commands. Handover documents include: | |
| 362 | - | ||
| 363 | - | - Software version or final commit SHA | |
| 364 | - | - Generation date | |
| 365 | - | - Document owner | |
| 366 | - | - Last verification date | |
| 367 | - | ||
| 368 | - | ### Diagrams | |
| 369 | - | ||
| 370 | - | Use maintainable Mermaid diagrams for system context, component interactions, deployment topology, and critical operational sequences when applicable. If a diagram is not applicable, state why. | |
| 371 | - | ||
| 372 | - | ### Handover Acceptance | |
| 373 | - | ||
| 374 | - | `docs/HANDOVER.md` includes: | |
| 375 | - | ||
| 376 | - | - Deliverables | |
| 377 | - | - Environment and access prerequisites | |
| 378 | - | - Verified capabilities | |
| 379 | - | - Known limitations | |
| 380 | - | - Approved deferred risks | |
| 381 | - | - Support boundaries | |
| 382 | - | - Warranty assumptions | |
| 383 | - | - Ownership transfer | |
| 384 | - | - Dated client acceptance checklist | |
| 385 | - | - Sign-off placeholders | |
| 386 | - | ||
| 387 | - | ## 7. Edge Cases & Constraints | |
| 388 | - | ||
| 389 | - | ### Existing Dirty Worktree | |
| 390 | - | ||
| 391 | - | Claude records the initial Git status and preserves pre-existing work. It may not revert, overwrite, stage, or include unrelated changes. If approved and pre-existing changes cannot be distinguished safely, execution stops for user direction. | |
| 392 | - | ||
| 393 | - | ### Scope Expansion | |
| 394 | - | ||
| 395 | - | Codex stops when required work exceeds the task's allowed scope. Claude assesses the impact, updates `SPEC.md`, `TASKS.md`, and `ADR.md` as appropriate, and requests approval before redispatch. | |
| 396 | - | ||
| 397 | - | ### Requirement Changes | |
| 398 | - | ||
| 399 | - | Approved `SPEC.md` is the baseline. Later requirements are explicit amendments. Execution pauses while Claude assesses affected tasks and documentation. Architectural amendments require an ADR. No changed task is dispatched without approval. | |
| 400 | - | ||
| 401 | - | ### Missing Test Framework | |
| 402 | - | ||
| 403 | - | The first applicable task establishes the smallest project-appropriate test and validation setup. If automated testing is technically impossible, Claude obtains approval for explicit manual acceptance steps and records the risk in `docs/HANDOVER.md`. | |
| 404 | - | ||
| 405 | - | ### Secrets and Sensitive Data | |
| 406 | - | ||
| 407 | - | Prompts and documents never contain credential values, tokens, private keys, personal data, or production secrets. They may document secret names, environment variables, storage systems, ownership, and rotation procedures. Available secret scanning runs before final commit, and suspected credentials block completion. | |
| 408 | - | ||
| 409 | - | ### Non-Applicable Documentation | |
| 410 | - | ||
| 411 | - | Mandatory documents remain present and mark irrelevant sections as `Not Applicable` with rationale. The workflow never fabricates content to fill a template. | |
| 412 | - | ||
| 413 | - | ### Single Commit | |
| 414 | - | ||
| 415 | - | No task-level commits are created. All approved implementation, tests, engineering records, and client documents remain in the worktree until every task is complete and final verification passes. The final commit includes only approved files. | |
| 416 | - | ||
| 417 | - | ### Interrupted Sessions | |
| 418 | - | ||
| 419 | - | Durable task states and evidence, not chat history, determine resume position. Claude must validate recorded state against actual files and Git before continuing. | |
| 420 | - | ||
| 421 | - | ## 8. Testing & Acceptance Strategy | |
| 422 | - | ||
| 423 | - | ### Primary Test Seam | |
| 424 | - | ||
| 425 | - | The highest existing seam is command-level testing of the sourced Zsh function with external CLI stubs. Extend this seam rather than testing private parser details independently. | |
| 426 | - | ||
| 427 | - | ### Required Workflow Tests | |
| 428 | - | ||
| 429 | - | - `--architect` produces the expected Claude invocation and architect workflow instruction. | |
| 430 | - | - `--architect --new` is accepted. | |
| 431 | - | - `--architect --yolo` forwards yolo behavior while preserving the architect instruction. | |
| 432 | - | - `--architect` rejects every incompatible flag combination. | |
| 433 | - | - Duplicate architect flags fail with usage guidance. | |
| 434 | - | - Missing TTY fails before workflow modification. | |
| 435 | - | - Missing required CLI or skill fails with remediation guidance. | |
| 436 | - | - Existing non-architect modes retain their current observable behavior. | |
| 437 | - | - `--v2` is rejected as an unknown argument and no v2 downloader remains. | |
| 438 | - | - Existing non-v2 modes retain their current observable behavior after v2 removal. | |
| 439 | - | ||
| 440 | - | ### Per-Task Verification | |
| 441 | - | ||
| 442 | - | Every Codex task includes focused unit or integration tests and relevant lint, type-check, build, and test commands. Claude reruns them independently before CodeRabbit review is considered complete. | |
| 443 | - | ||
| 444 | - | ### Final Verification | |
| 445 | - | ||
| 446 | - | Before requesting commit approval, Claude verifies: | |
| 447 | - | ||
| 448 | - | - Every task is `Complete`. | |
| 449 | - | - No task has unresolved blocking review findings. | |
| 450 | - | - The complete project lint, type-check, build, and test suite passes. | |
| 451 | - | - The aggregate diff contains only approved changes. | |
| 452 | - | - Required documentation files and sections exist. | |
| 453 | - | - Markdown structure and internal links are valid. | |
| 454 | - | - Referenced source paths and commands exist and are accurate. | |
| 455 | - | - Endpoint and command examples match implementation. | |
| 456 | - | - Mermaid syntax is validated where tooling is available. | |
| 457 | - | - No unresolved `TODO`, placeholder, or template text remains. | |
| 458 | - | - Approved known limitations are recorded in `docs/HANDOVER.md`. | |
| 459 | - | - Available secret scanning reports no suspected credentials. | |
| 460 | - | - Handover documents match the final implementation. | |
| 461 | - | ||
| 462 | - | ## 9. Implementation Decisions | |
| 463 | - | ||
| 464 | - | - Architect mode is opt-in and does not replace existing `plan_build` modes. | |
| 465 | - | - Architect mode is implemented only for the built-in workflow. | |
| 466 | - | - The obsolete `_plan_build_v2` downloader, `--v2` parser branch, passthrough logic, usage text, README examples, and standalone-install references are removed. | |
| 467 | - | - Claude is the architect and documentation manager, not an implementation agent. | |
| 468 | - | - Codex is the sole implementation and test-code executor. | |
| 469 | - | - CodeRabbit is mandatory for task and final reviews. | |
| 470 | - | - Execution is sequential with one active task. | |
| 471 | - | - User approval is mandatory at phase, task, deferral, and commit boundaries. | |
| 472 | - | - All changes are committed once after complete verification. | |
| 473 | - | - The final commit is never pushed automatically. | |
| 474 | - | - Existing documentation is reconciled rather than overwritten. | |
| 475 | - | - Complete client handover documentation is mandatory without exception. | |
| 476 | - | ||
| 477 | - | ## 10. Out of Scope | |
| 478 | - | ||
| 479 | - | - Repairing, replacing, or migrating the unavailable standalone v2 script or remote endpoint; only the built-in integration and references are removed. | |
| 480 | - | - Parallel task execution. | |
| 481 | - | - Frontend/backend distribution to different executors. | |
| 482 | - | - Autonomous approval decisions. | |
| 483 | - | - Multiple task commits. | |
| 484 | - | - Automatic pushes, releases, or deployments. | |
| 485 | - | - Replacement of project issue trackers or external documentation systems. | |
| 486 | - | - Generating implementation code during specification work. | |
| 487 | - | ||
| 488 | - | ## 11. Definition of Done | |
| 489 | - | ||
| 490 | - | Architect mode is complete when: | |
| 491 | - | ||
| 492 | - | 1. The built-in command exposes the approved CLI contract. | |
| 493 | - | 2. No built-in v2 downloader, flag parser, usage text, or documentation reference remains. | |
| 494 | - | 3. The canonical architect skill is distributed by every supported installer. | |
| 495 | - | 4. The current machine can refresh the active function and skill from the published source. | |
| 496 | - | 5. Command-level tests cover architect behavior, v2 rejection, and preservation of existing non-v2 modes. | |
| 497 | - | 6. The workflow enforces role boundaries, phase gates, task states, retries, reviews, and the single-commit policy. | |
| 498 | - | 7. The workflow mandates the complete internal and client documentation package. | |
| 499 | - | 8. Syntax and workflow tests pass. | |
| 500 | - | 9. Published OpenGist content matches the verified local source. | |
TASKS.md (файл удалён)
| @@ -1,388 +0,0 @@ | |||
| 1 | - | # Plan Build Architect Mode Execution Plan | |
| 2 | - | ||
| 3 | - | ## Execution Policy | |
| 4 | - | ||
| 5 | - | This plan implements the approved `SPEC.md`. Claude Code is the architect, documentation manager, dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit reviews every task and the final aggregate diff. | |
| 6 | - | ||
| 7 | - | The following rules apply to every task: | |
| 8 | - | ||
| 9 | - | 1. Execute tasks sequentially in ID order. | |
| 10 | - | 2. Only one task may be `In Progress` at a time. | |
| 11 | - | 3. Do not start a task until its dependencies are `Complete` and the user approves dispatch. | |
| 12 | - | 4. Codex may modify only the task's Allowed File Scope. | |
| 13 | - | 5. Codex must stop and report when required work exceeds that scope. | |
| 14 | - | 6. Codex must not commit, stage, push, reset, restore, or discard changes. | |
| 15 | - | 7. Claude independently checks the diff and reruns verification commands. | |
| 16 | - | 8. CodeRabbit reviews each task. Valid critical, high, and medium findings must be fixed before completion. | |
| 17 | - | 9. Codex receives at most two focused correction attempts after its initial execution. | |
| 18 | - | 10. All changes remain uncommitted until every task, final review, full verification, and handover document passes. | |
| 19 | - | 11. Claude updates `SPEC.md`, `ADR.md`, `CHANGELOG.md`, `README.md`, and the mandatory `docs/` handover package. Codex does not edit those documents unless a later approved scope amendment explicitly says otherwise. | |
| 20 | - | ||
| 21 | - | ## Claude Documentation Workstream | |
| 22 | - | ||
| 23 | - | This workstream runs alongside Codex execution and is not delegated: | |
| 24 | - | ||
| 25 | - | - Preserve and reconcile existing documentation rather than replacing it blindly. | |
| 26 | - | - Maintain `SPEC.md` as the approved baseline and record approved amendments. | |
| 27 | - | - Create and maintain append-only `ADR.md` decisions. | |
| 28 | - | - Maintain Keep a Changelog-compatible `CHANGELOG.md` entries referencing task IDs. | |
| 29 | - | - Remove obsolete v2 usage and standalone-install references from `README.md` after `TASK-001` passes. | |
| 30 | - | - Document `plan_build --architect`, `--new`, compatibility rules, prerequisites, and examples after `TASK-002` passes. | |
| 31 | - | - Document installer distribution and local refresh behavior after `TASK-003` passes. | |
| 32 | - | - Create or update `docs/USER_MANUAL.md`, `docs/RUNBOOK.md`, `docs/API.md`, `docs/DEPLOYMENT.md`, `docs/SECURITY.md`, and `docs/HANDOVER.md` before final review. | |
| 33 | - | - Mark non-applicable sections explicitly with a factual rationale rather than omitting files or inventing behavior. | |
| 34 | - | - Add final commit SHA placeholders only until the final commit exists; replace or explain the self-reference limitation during finalization. | |
| 35 | - | ||
| 36 | - | --- | |
| 37 | - | ||
| 38 | - | ## TASK-001: Remove the obsolete v2 integration | |
| 39 | - | ||
| 40 | - | **Status:** Complete | |
| 41 | - | ||
| 42 | - | **Dependencies:** None | |
| 43 | - | ||
| 44 | - | ### Objective | |
| 45 | - | ||
| 46 | - | Remove the broken standalone v2 downloader and all `--v2` parsing and forwarding behavior from the built-in `plan_build` function. Preserve every existing non-v2 mode. Make `--v2` use the normal unknown-argument failure path. | |
| 47 | - | ||
| 48 | - | ### Allowed File Scope | |
| 49 | - | ||
| 50 | - | - `func` | |
| 51 | - | - `test_plan_build.zsh` | |
| 52 | - | ||
| 53 | - | No other file may be created, modified, renamed, or deleted by Codex. | |
| 54 | - | ||
| 55 | - | ### Context / Interfaces | |
| 56 | - | ||
| 57 | - | - `func` currently defines `_plan_build_v2()`, which downloads a now-unavailable standalone script. | |
| 58 | - | - `plan_build()` currently performs a preliminary argument pass to strip `--v2` and forward all remaining arguments. | |
| 59 | - | - The normal parser already rejects unknown arguments with a non-zero status and usage output. | |
| 60 | - | - Existing supported behavior includes `--yolo`, `--prompt`, `--brainstorm`, and `--writing-plan`. | |
| 61 | - | - `test_plan_build.zsh` is the highest command-level test seam. It sources `func`, stubs external commands, invokes `plan_build`, and asserts status and output. | |
| 62 | - | - Do not redesign the existing parser beyond the smallest change required to remove v2. | |
| 63 | - | ||
| 64 | - | ### Acceptance Criteria | |
| 65 | - | ||
| 66 | - | - `_plan_build_v2()` no longer exists. | |
| 67 | - | - The v2 URL, temporary-file logic, Bash forwarding, and v2 status handling no longer exist. | |
| 68 | - | - `plan_build()` no longer performs a v2 pre-parse or maintains v2 passthrough arguments. | |
| 69 | - | - Usage output contains no `--v2`, `--grill`, or `--distribute` text. | |
| 70 | - | - `plan_build --v2` returns non-zero through the standard unknown-argument path and identifies `--v2` as unknown. | |
| 71 | - | - Existing standard, yolo, prompt, brainstorm, and writing-plan behavior remains unchanged. | |
| 72 | - | - Tests cover v2 rejection and continue covering existing modes. | |
| 73 | - | - Zsh syntax validation and the complete existing plan-build test suite pass. | |
| 74 | - | ||
| 75 | - | ### Verification Commands | |
| 76 | - | ||
| 77 | - | ```bash | |
| 78 | - | zsh -n func | |
| 79 | - | zsh -n test_plan_build.zsh | |
| 80 | - | zsh test_plan_build.zsh | |
| 81 | - | git diff --check -- func test_plan_build.zsh | |
| 82 | - | git diff -- func test_plan_build.zsh | |
| 83 | - | ``` | |
| 84 | - | ||
| 85 | - | ### Prompt for Codex | |
| 86 | - | ||
| 87 | - | ```text | |
| 88 | - | Objective: | |
| 89 | - | Remove the obsolete standalone v2 integration from the built-in plan_build Zsh function. Delete the _plan_build_v2 downloader and remove all --v2 pre-parsing, passthrough, forwarding, and usage text. After the change, --v2 must be handled by the existing normal unknown-argument branch. Preserve all non-v2 behavior. | |
| 90 | - | ||
| 91 | - | Allowed File Scope: | |
| 92 | - | - func | |
| 93 | - | - test_plan_build.zsh | |
| 94 | - | Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. | |
| 95 | - | ||
| 96 | - | Context / Interfaces: | |
| 97 | - | - func defines _plan_build_v2() immediately before plan_build(). It downloads a missing remote plan_build.sh and executes it with Bash. | |
| 98 | - | - plan_build() currently strips --v2 in a preliminary argument loop, then either forwards to _plan_build_v2 or enters the normal parser. | |
| 99 | - | - The normal parser already prints "Error: Unknown argument: <argument>", prints usage, and returns 1. | |
| 100 | - | - Supported non-v2 flags are --yolo, --prompt, --brainstorm, and --writing-plan. | |
| 101 | - | - test_plan_build.zsh is a command-level Zsh test that sources func, stubs external CLI checks and Claude, and asserts output/status. | |
| 102 | - | - Make the smallest correct parser change. Do not refactor unrelated shell functions or reformat unrelated content. | |
| 103 | - | ||
| 104 | - | Acceptance Criteria: | |
| 105 | - | 1. _plan_build_v2 and all of its URL/download/temporary-file/forwarding code are removed. | |
| 106 | - | 2. plan_build has no use_v2 or passthrough state and no preliminary v2 argument pass. | |
| 107 | - | 3. Usage text has no v2, grill, or distribute reference. | |
| 108 | - | 4. plan_build --v2 returns status 1 and includes "Unknown argument: --v2". | |
| 109 | - | 5. Standard, --yolo, --prompt, --brainstorm, and --writing-plan behavior remains unchanged. | |
| 110 | - | 6. Add a command-level regression assertion for --v2 rejection. | |
| 111 | - | 7. All existing tests pass. | |
| 112 | - | ||
| 113 | - | Required Verification: | |
| 114 | - | - zsh -n func | |
| 115 | - | - zsh -n test_plan_build.zsh | |
| 116 | - | - zsh test_plan_build.zsh | |
| 117 | - | - git diff --check -- func test_plan_build.zsh | |
| 118 | - | ||
| 119 | - | Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. | |
| 120 | - | ``` | |
| 121 | - | ||
| 122 | - | ### CodeRabbit Outcome | |
| 123 | - | ||
| 124 | - | Passed with zero findings. | |
| 125 | - | ||
| 126 | - | ### Completion Evidence | |
| 127 | - | ||
| 128 | - | - Codex removed the v2 downloader and parser forwarding only within the approved files. | |
| 129 | - | - `plan_build --v2` now returns the normal unknown-argument error. | |
| 130 | - | - `zsh -n func` passed. | |
| 131 | - | - `zsh -n test_plan_build.zsh` passed. | |
| 132 | - | - `zsh test_plan_build.zsh` passed. | |
| 133 | - | - `git diff --check -- func test_plan_build.zsh` passed. | |
| 134 | - | ||
| 135 | - | --- | |
| 136 | - | ||
| 137 | - | ## TASK-002: Add the built-in architect command contract | |
| 138 | - | ||
| 139 | - | **Status:** Complete | |
| 140 | - | ||
| 141 | - | **Dependencies:** TASK-001 | |
| 142 | - | ||
| 143 | - | ### Objective | |
| 144 | - | ||
| 145 | - | Add `--architect` to the built-in `plan_build` function. Support `--new` and `--yolo`, enforce incompatible and duplicate flag rules, run fail-fast architect preflight, collect the initial payload through the existing input contract, and launch Claude with the canonical installed architect skill. Preserve existing non-architect modes. | |
| 146 | - | ||
| 147 | - | ### Allowed File Scope | |
| 148 | - | ||
| 149 | - | - `func` | |
| 150 | - | - `test_plan_build.zsh` | |
| 151 | - | ||
| 152 | - | No other file may be created, modified, renamed, or deleted by Codex. | |
| 153 | - | ||
| 154 | - | ### Context / Interfaces | |
| 155 | - | ||
| 156 | - | - Claude will create the canonical repository workflow document `architect-workflow.md` before this task is dispatched. | |
| 157 | - | - Installers will later distribute it to `~/.claude/skills/plan-build-architect/SKILL.md` in `TASK-003`. | |
| 158 | - | - Architect mode is interactive and requires `claude`, `codex`, `coderabbit`, `git`, a Git worktree, a usable TTY, and a readable non-empty installed skill. | |
| 159 | - | - Preflight must run before payload collection or any project-file modification. | |
| 160 | - | - `--new` is valid only with `--architect`. | |
| 161 | - | - `--architect` may combine only with `--new` and `--yolo`. | |
| 162 | - | - Architect mode must reject `--prompt`, `--brainstorm`, and `--writing-plan` combinations. | |
| 163 | - | - `--yolo` is forwarded to Claude but the architect workflow itself retains mandatory human gates. | |
| 164 | - | - The initial payload continues using the existing `EOF`-terminated stdin behavior. | |
| 165 | - | - Existing command-level tests stub helpers and Claude. Architect tests must not launch real external CLIs or require a real TTY. | |
| 166 | - | ||
| 167 | - | ### Acceptance Criteria | |
| 168 | - | ||
| 169 | - | - Usage documents built-in architect syntax and no v2 syntax. | |
| 170 | - | - Duplicate `--architect` and duplicate `--new` fail with usage guidance. | |
| 171 | - | - `--new` without `--architect` fails. | |
| 172 | - | - Architect combinations with prompt, brainstorm, or writing-plan fail before external tools launch. | |
| 173 | - | - A dedicated architect preflight checks all required tools, Git context, TTY, and installed skill with actionable errors. | |
| 174 | - | - Architect preflight occurs before payload reading. | |
| 175 | - | - Empty payload remains an error. | |
| 176 | - | - The Claude invocation explicitly directs Claude to read `~/.claude/skills/plan-build-architect/SKILL.md`, obey the architect role boundary, and treat the payload as the initial high-level requirement. | |
| 177 | - | - `--new` is represented unambiguously in the Claude instruction. | |
| 178 | - | - `--yolo` is forwarded to Claude. | |
| 179 | - | - Existing non-architect modes retain current observable behavior. | |
| 180 | - | - Command-level tests cover success, compatibility failures, duplicates, new/resume instruction, yolo forwarding, and preflight failure without invoking real tools. | |
| 181 | - | ||
| 182 | - | ### Verification Commands | |
| 183 | - | ||
| 184 | - | ```bash | |
| 185 | - | zsh -n func | |
| 186 | - | zsh -n test_plan_build.zsh | |
| 187 | - | zsh test_plan_build.zsh | |
| 188 | - | git diff --check -- func test_plan_build.zsh | |
| 189 | - | git diff -- func test_plan_build.zsh | |
| 190 | - | ``` | |
| 191 | - | ||
| 192 | - | ### Prompt for Codex | |
| 193 | - | ||
| 194 | - | ```text | |
| 195 | - | Objective: | |
| 196 | - | Implement the built-in plan_build --architect command contract in Zsh. Architect mode launches Claude as a documentation-first architect/orchestrator using ~/.claude/skills/plan-build-architect/SKILL.md. It must support --new and --yolo, reject incompatible or duplicate flags, run a fail-fast preflight, preserve the existing EOF-terminated payload input, and leave every existing non-architect mode unchanged. | |
| 197 | - | ||
| 198 | - | Allowed File Scope: | |
| 199 | - | - func | |
| 200 | - | - test_plan_build.zsh | |
| 201 | - | Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. | |
| 202 | - | ||
| 203 | - | Context / Interfaces: | |
| 204 | - | - TASK-001 has already removed --v2. | |
| 205 | - | - Existing plan_build supports --yolo, --prompt, --brainstorm, and --writing-plan. | |
| 206 | - | - --architect may combine only with --new and --yolo. | |
| 207 | - | - --new without --architect is invalid. | |
| 208 | - | - --architect combined with --prompt, --brainstorm, or --writing-plan is invalid. | |
| 209 | - | - Duplicate --architect and duplicate --new must fail with usage output. | |
| 210 | - | - Architect preflight must verify, before payload reading: an interactive TTY; a Git worktree; claude, codex, coderabbit, and git availability; and a readable non-empty ~/.claude/skills/plan-build-architect/SKILL.md. | |
| 211 | - | - Error output must identify the missing requirement and provide practical remediation. | |
| 212 | - | - The current input contract reads lines until EOF appears on its own line and rejects an empty payload. | |
| 213 | - | - The Claude prompt must explicitly tell Claude to read ~/.claude/skills/plan-build-architect/SKILL.md, follow it strictly, remain within its documentation/orchestration boundary, and use the payload as the initial high-level requirement. | |
| 214 | - | - When --new is present, the prompt must explicitly request the skill's archive-and-start-new behavior. Otherwise it must permit safe resume detection. | |
| 215 | - | - --yolo forwards the existing Claude yolo argument but does not weaken workflow approval gates. | |
| 216 | - | - test_plan_build.zsh uses function stubs. Add or stub a dedicated architect preflight seam so tests never invoke actual CLIs or depend on the test runner's TTY. | |
| 217 | - | - Prefer the existing command-level test seam. Do not add another test framework. | |
| 218 | - | - Make minimal localized changes and do not refactor unrelated functions. | |
| 219 | - | ||
| 220 | - | Acceptance Criteria: | |
| 221 | - | 1. Usage includes plan_build --architect [--new] [--yolo]. | |
| 222 | - | 2. Duplicate architect/new flags and invalid combinations return status 1 with clear errors and usage. | |
| 223 | - | 3. Architect preflight executes before payload collection and checks every stated dependency. | |
| 224 | - | 4. Empty payload returns status 1. | |
| 225 | - | 5. A successful architect invocation directs Claude to the canonical installed skill and includes the initial payload. | |
| 226 | - | 6. --new changes the instruction to start a new archived workflow; default behavior permits resume detection. | |
| 227 | - | 7. --yolo is forwarded to Claude. | |
| 228 | - | 8. Existing standard, prompt, brainstorm, writing-plan, and yolo tests remain green. | |
| 229 | - | 9. Tests cover architect success and every parser/preflight edge without launching real external processes. | |
| 230 | - | ||
| 231 | - | Required Verification: | |
| 232 | - | - zsh -n func | |
| 233 | - | - zsh -n test_plan_build.zsh | |
| 234 | - | - zsh test_plan_build.zsh | |
| 235 | - | - git diff --check -- func test_plan_build.zsh | |
| 236 | - | ||
| 237 | - | Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. | |
| 238 | - | ``` | |
| 239 | - | ||
| 240 | - | ### CodeRabbit Outcome | |
| 241 | - | ||
| 242 | - | CodeRabbit reported one major finding: checking only the exit status of `git rev-parse --is-inside-work-tree` could accept a bare repository. Codex added an exact `true` check and regression fixtures for normal and bare repositories. The follow-up CodeRabbit review passed with zero findings. | |
| 243 | - | ||
| 244 | - | ### Completion Evidence | |
| 245 | - | ||
| 246 | - | - Codex added the built-in architect parser, preflight, launch prompt, and command-level tests only within the approved files. | |
| 247 | - | - Architect tests cover success, new workflow, safe resume, yolo forwarding, invalid combinations, duplicates, empty payload, preflight ordering, normal worktrees, and bare repository rejection. | |
| 248 | - | - `zsh -n func` passed. | |
| 249 | - | - `zsh -n test_plan_build.zsh` passed. | |
| 250 | - | - `zsh test_plan_build.zsh` passed. | |
| 251 | - | - `git diff --check -- func test_plan_build.zsh` passed. | |
| 252 | - | - Final CodeRabbit review passed with zero findings. | |
| 253 | - | ||
| 254 | - | --- | |
| 255 | - | ||
| 256 | - | ## TASK-003: Distribute and verify the canonical architect skill | |
| 257 | - | ||
| 258 | - | **Status:** Pending | |
| 259 | - | ||
| 260 | - | **Dependencies:** TASK-002 | |
| 261 | - | ||
| 262 | - | ### Objective | |
| 263 | - | ||
| 264 | - | Extend the configuration and platform installers to atomically install the canonical `architect-workflow.md` source as `~/.claude/skills/plan-build-architect/SKILL.md`. Add repository-level tests that verify every supported installer uses the same source and destination while preserving the existing plan-build skill installation. | |
| 265 | - | ||
| 266 | - | ### Allowed File Scope | |
| 267 | - | ||
| 268 | - | - `config.sh` | |
| 269 | - | - `zsh_macos.sh` | |
| 270 | - | - `zsh_ubuntu.sh` | |
| 271 | - | - `zsh_wsl.sh` | |
| 272 | - | - `test_plan_build_installers.zsh` (new) | |
| 273 | - | ||
| 274 | - | Codex must not modify `architect-workflow.md`; Claude owns its approved content. No other file may be created, modified, renamed, or deleted by Codex. | |
| 275 | - | ||
| 276 | - | ### Context / Interfaces | |
| 277 | - | ||
| 278 | - | - `config.sh` currently downloads `orchestrate-loop.md` to `~/.claude/skills/plan-build/SKILL.md` through a temporary file and atomic move. | |
| 279 | - | - Each platform installer has equivalent existing plan-build skill installation logic. | |
| 280 | - | - The new canonical repository source is `architect-workflow.md`. | |
| 281 | - | - The new installed destination is `~/.claude/skills/plan-build-architect/SKILL.md`. | |
| 282 | - | - Existing plan-build skill distribution must continue unchanged. | |
| 283 | - | - All four installers must use their existing gist raw base rather than introducing a new remote endpoint. | |
| 284 | - | - Failure to download or install the architect skill must be visible and must not leave a partial destination file. | |
| 285 | - | - The new test should validate repository contracts without network access, elevated privileges, home-directory changes, or execution of full platform installers. | |
| 286 | - | ||
| 287 | - | ### Acceptance Criteria | |
| 288 | - | ||
| 289 | - | - `config.sh` installs both the existing plan-build skill and the architect skill. | |
| 290 | - | - macOS, Ubuntu, and WSL installers install both skills. | |
| 291 | - | - Every installer downloads `architect-workflow.md` from its existing gist raw base. | |
| 292 | - | - Every installer targets `~/.claude/skills/plan-build-architect/SKILL.md`. | |
| 293 | - | - Parent directories are created safely. | |
| 294 | - | - Downloads use temporary files and atomic moves. | |
| 295 | - | - Failed downloads remove temporary files and emit clear errors or warnings consistent with each installer's existing behavior. | |
| 296 | - | - Existing plan-build skill installation remains intact. | |
| 297 | - | - A new Zsh test validates all four installer contracts statically and runs without external services. | |
| 298 | - | - Bash and Zsh syntax checks pass. | |
| 299 | - | ||
| 300 | - | ### Verification Commands | |
| 301 | - | ||
| 302 | - | ```bash | |
| 303 | - | bash -n config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh | |
| 304 | - | zsh -n test_plan_build_installers.zsh | |
| 305 | - | zsh test_plan_build_installers.zsh | |
| 306 | - | zsh test_plan_build.zsh | |
| 307 | - | git diff --check -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh | |
| 308 | - | git diff -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh | |
| 309 | - | ``` | |
| 310 | - | ||
| 311 | - | ### Prompt for Codex | |
| 312 | - | ||
| 313 | - | ```text | |
| 314 | - | Objective: | |
| 315 | - | Distribute the canonical architect workflow through every supported Zsh Setup installer. Install repository file architect-workflow.md from the existing gist raw base as ~/.claude/skills/plan-build-architect/SKILL.md, using the same safe temporary-file and atomic-move pattern as the existing plan-build skill. Add a network-free repository test for the installer contracts. | |
| 316 | - | ||
| 317 | - | Allowed File Scope: | |
| 318 | - | - config.sh | |
| 319 | - | - zsh_macos.sh | |
| 320 | - | - zsh_ubuntu.sh | |
| 321 | - | - zsh_wsl.sh | |
| 322 | - | - test_plan_build_installers.zsh (new) | |
| 323 | - | Do not modify architect-workflow.md. Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. | |
| 324 | - | ||
| 325 | - | Context / Interfaces: | |
| 326 | - | - config.sh and all three platform installers already install orchestrate-loop.md at ~/.claude/skills/plan-build/SKILL.md. | |
| 327 | - | - Preserve that existing installation exactly. | |
| 328 | - | - Add architect-workflow.md as a second canonical source. | |
| 329 | - | - Install it at ~/.claude/skills/plan-build-architect/SKILL.md. | |
| 330 | - | - Use each script's existing GIST_RAW_BASE. Do not add or depend on another gist or endpoint. | |
| 331 | - | - Follow each script's current logging and failure conventions. | |
| 332 | - | - Create destination directories safely. | |
| 333 | - | - Download to a temporary sibling file and move only after successful curl completion. | |
| 334 | - | - Remove temporary files on failure so partial skills cannot become active. | |
| 335 | - | - test_plan_build_installers.zsh must inspect repository files and assert the source filename, installed destination, existing-skill preservation, and safe download pattern for config.sh plus macOS, Ubuntu, and WSL scripts. | |
| 336 | - | - The test must not access the network, invoke sudo, execute the installers, or write to the real home directory. | |
| 337 | - | - Keep changes localized to existing skill-install blocks. | |
| 338 | - | ||
| 339 | - | Acceptance Criteria: | |
| 340 | - | 1. All four installers install the existing plan-build skill and new architect skill. | |
| 341 | - | 2. All use architect-workflow.md and ~/.claude/skills/plan-build-architect/SKILL.md. | |
| 342 | - | 3. All use temporary download files and atomic moves, with cleanup on failure. | |
| 343 | - | 4. Existing installation behavior remains intact. | |
| 344 | - | 5. The new static contract test passes without external services. | |
| 345 | - | 6. Existing plan_build tests remain green. | |
| 346 | - | ||
| 347 | - | Required Verification: | |
| 348 | - | - bash -n config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh | |
| 349 | - | - zsh -n test_plan_build_installers.zsh | |
| 350 | - | - zsh test_plan_build_installers.zsh | |
| 351 | - | - zsh test_plan_build.zsh | |
| 352 | - | - git diff --check -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh | |
| 353 | - | ||
| 354 | - | Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. | |
| 355 | - | ``` | |
| 356 | - | ||
| 357 | - | ### CodeRabbit Outcome | |
| 358 | - | ||
| 359 | - | Pending. | |
| 360 | - | ||
| 361 | - | ### Completion Evidence | |
| 362 | - | ||
| 363 | - | Pending. | |
| 364 | - | ||
| 365 | - | --- | |
| 366 | - | ||
| 367 | - | ## Final Review and Handover Gate | |
| 368 | - | ||
| 369 | - | This gate begins only after `TASK-001`, `TASK-002`, and `TASK-003` are `Complete`. | |
| 370 | - | ||
| 371 | - | Claude must: | |
| 372 | - | ||
| 373 | - | 1. Complete all root engineering records and mandatory `docs/` handover files. | |
| 374 | - | 2. Run CodeRabbit over the complete uncommitted diff. | |
| 375 | - | 3. Delegate valid code or test fixes to Codex under the responsible task's original scope and retry limit. | |
| 376 | - | 4. Run all focused commands plus the complete repository verification suite. | |
| 377 | - | 5. Validate required documents, links, source references, examples, Mermaid syntax where tooling exists, and absence of unresolved placeholders. | |
| 378 | - | 6. Run available secret scanning and block suspected credentials. | |
| 379 | - | 7. Confirm Git contains only approved changes and preserves pre-existing user work. | |
| 380 | - | 8. Present the final diff summary, verification evidence, known limitations, and proposed single commit message. | |
| 381 | - | 9. Wait for explicit user approval before staging and creating one commit. | |
| 382 | - | 10. Never push automatically. | |
| 383 | - | ||
| 384 | - | ## Final Commit | |
| 385 | - | ||
| 386 | - | **Status:** Pending user approval after final gate. | |
| 387 | - | ||
| 388 | - | **Proposed message:** `feat: add plan_build architect workflow` | |
architect-workflow.md (файл удалён)
| @@ -1,219 +0,0 @@ | |||
| 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. | |
config.sh
| @@ -12,7 +12,6 @@ CONFIG_FILES=( | |||
| 12 | 12 | ".zshrc" | |
| 13 | 13 | ".config/starship.toml" | |
| 14 | 14 | ) | |
| 15 | - | PLAN_BUILD_SKILL_TARGET="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 16 | 15 | ||
| 17 | 16 | echo "Starting configuration download..." | |
| 18 | 17 | download_failed=0 | |
| @@ -38,17 +37,6 @@ for f in "${CONFIG_FILES[@]}"; do | |||
| 38 | 37 | fi | |
| 39 | 38 | done | |
| 40 | 39 | ||
| 41 | - | echo "Downloading Claude Code plan-build workflow..." | |
| 42 | - | mkdir -p "$(dirname "$PLAN_BUILD_SKILL_TARGET")" | |
| 43 | - | skill_tmp="${PLAN_BUILD_SKILL_TARGET}.tmp.$$" | |
| 44 | - | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp" && mv "$skill_tmp" "$PLAN_BUILD_SKILL_TARGET"; then | |
| 45 | - | echo "Successfully updated $PLAN_BUILD_SKILL_TARGET" | |
| 46 | - | else | |
| 47 | - | rm -f "$skill_tmp" | |
| 48 | - | echo "Error: Failed to download the plan-build workflow" >&2 | |
| 49 | - | download_failed=1 | |
| 50 | - | fi | |
| 51 | - | ||
| 52 | 40 | if [ "$download_failed" -ne 0 ]; then | |
| 53 | 41 | echo "Configuration download completed with errors." >&2 | |
| 54 | 42 | exit 1 | |
func
| @@ -428,324 +428,257 @@ prompt() { | |||
| 428 | 428 | } | |
| 429 | 429 | ||
| 430 | 430 | # ----------------------------------------------------------------------------- | |
| 431 | - | # Function: plan_build (Claude Code multi-agent workflow orchestrator) | |
| 431 | + | # Function: plan_build (Cached canonical plan-build launcher) | |
| 432 | 432 | # ----------------------------------------------------------------------------- | |
| 433 | - | _plan_build_superpowers_state() { | |
| 434 | - | awk ' | |
| 435 | - | BEGIN { | |
| 436 | - | RS = "}" | |
| 437 | - | state = "missing" | |
| 438 | - | printed = 0 | |
| 439 | - | } | |
| 440 | - | /"id"[[:space:]]*:[[:space:]]*"superpowers@claude-plugins-official"/ { | |
| 441 | - | state = "installed" | |
| 442 | - | if ($0 ~ /"enabled"[[:space:]]*:[[:space:]]*true/) { | |
| 443 | - | state = "enabled" | |
| 444 | - | } else if ($0 ~ /"enabled"[[:space:]]*:[[:space:]]*false/) { | |
| 445 | - | state = "disabled" | |
| 446 | - | } | |
| 447 | - | print state | |
| 448 | - | printed = 1 | |
| 449 | - | exit | |
| 450 | - | } | |
| 451 | - | END { | |
| 452 | - | if (!printed) { | |
| 453 | - | print state | |
| 454 | - | } | |
| 455 | - | } | |
| 456 | - | ' | |
| 457 | - | } | |
| 458 | - | ||
| 459 | - | _plan_build_superpowers_preflight() { | |
| 460 | - | local plugin_json | |
| 461 | - | local plugin_state | |
| 462 | - | ||
| 463 | - | case "${CLAUDE_CODE_SAFE_MODE:-}" in | |
| 464 | - | 1|true|TRUE|yes|YES|on|ON) | |
| 465 | - | echo "❌ Error: Claude Code safe mode disables Superpowers." | |
| 466 | - | echo "Unset CLAUDE_CODE_SAFE_MODE before using --brainstorm or --writing-plan." | |
| 467 | - | return 1 | |
| 468 | - | ;; | |
| 469 | - | esac | |
| 470 | - | ||
| 471 | - | if ! plugin_json="$(command claude plugin list --json 2>/dev/null)"; then | |
| 472 | - | echo "❌ Error: Unable to inspect Claude Code plugins." | |
| 473 | - | echo "Run 'claude plugin list' to diagnose the problem." | |
| 474 | - | return 1 | |
| 475 | - | fi | |
| 476 | - | ||
| 477 | - | plugin_state="$(printf '%s\n' "$plugin_json" | _plan_build_superpowers_state)" | |
| 478 | - | ||
| 479 | - | case "$plugin_state" in | |
| 480 | - | enabled) | |
| 481 | - | return 0 | |
| 482 | - | ;; | |
| 483 | - | disabled) | |
| 484 | - | echo "❌ Error: Claude Code Superpowers is installed but disabled." | |
| 485 | - | echo "Enable it with: claude plugin enable superpowers@claude-plugins-official" | |
| 486 | - | ;; | |
| 487 | - | missing) | |
| 488 | - | echo "❌ Error: Claude Code Superpowers is required for --brainstorm and --writing-plan." | |
| 489 | - | echo "Install it in Claude Code with: /plugin install superpowers@claude-plugins-official" | |
| 490 | - | ;; | |
| 491 | - | *) | |
| 492 | - | echo "❌ Error: Unable to determine Claude Code Superpowers status." | |
| 493 | - | echo "Run 'claude plugin list' to diagnose the problem." | |
| 494 | - | ;; | |
| 495 | - | esac | |
| 496 | - | ||
| 497 | - | return 1 | |
| 498 | - | } | |
| 499 | - | ||
| 500 | - | _plan_build_is_worktree() { | |
| 501 | - | local inside_work_tree | |
| 502 | - | ||
| 503 | - | inside_work_tree="$(command git rev-parse --is-inside-work-tree 2>/dev/null)" || return 1 | |
| 504 | - | [ "$inside_work_tree" = "true" ] | |
| 505 | - | } | |
| 506 | - | ||
| 507 | - | _plan_build_architect_preflight() { | |
| 508 | - | local skill_path="$HOME/.claude/skills/plan-build-architect/SKILL.md" | |
| 509 | - | ||
| 510 | - | if ! (: </dev/tty) 2>/dev/null; then | |
| 511 | - | echo "❌ Error: Architect mode requires an interactive terminal." | |
| 512 | - | echo "Run plan_build --architect from an interactive terminal." | |
| 513 | - | return 1 | |
| 514 | - | fi | |
| 515 | - | ||
| 516 | - | require_cli claude "Claude Code CLI" || return 1 | |
| 517 | - | require_cli codex "Codex CLI" || return 1 | |
| 518 | - | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 519 | - | require_cli git "Git CLI" || return 1 | |
| 520 | - | ||
| 521 | - | if ! _plan_build_is_worktree; then | |
| 522 | - | echo "❌ Error: Architect mode must run inside a Git worktree." | |
| 523 | - | echo "Change to a Git worktree, then retry plan_build --architect." | |
| 524 | - | return 1 | |
| 525 | - | fi | |
| 526 | - | ||
| 527 | - | if [ ! -r "$skill_path" ] || [ ! -s "$skill_path" ]; then | |
| 528 | - | echo "❌ Error: Architect skill is missing, unreadable, or empty: $skill_path" | |
| 529 | - | echo "Install a readable, non-empty plan-build-architect skill at that path." | |
| 530 | - | return 1 | |
| 531 | - | fi | |
| 532 | - | } | |
| 533 | - | ||
| 534 | 433 | plan_build() { | |
| 535 | - | local claude_args=() | |
| 536 | - | local use_yolo=0 | |
| 537 | - | local use_architect=0 | |
| 538 | - | local use_new=0 | |
| 539 | - | local enhance_payload=0 | |
| 540 | - | local planning_mode="standard" | |
| 541 | - | local usage="Usage: plan_build [--yolo] [--prompt] [--brainstorm | --writing-plan] | |
| 542 | - | plan_build --architect [--new] [--yolo]" | |
| 543 | - | ||
| 544 | - | while [ $# -gt 0 ]; do | |
| 545 | - | case "$1" in | |
| 546 | - | --yolo) | |
| 547 | - | if [ "$use_yolo" -eq 1 ]; then | |
| 548 | - | echo "Error: Duplicate argument: --yolo" | |
| 549 | - | echo "$usage" | |
| 550 | - | return 1 | |
| 551 | - | fi | |
| 552 | - | use_yolo=1 | |
| 553 | - | claude_args=(--yolo) | |
| 554 | - | ;; | |
| 555 | - | --architect) | |
| 556 | - | if [ "$use_architect" -eq 1 ]; then | |
| 557 | - | echo "Error: Duplicate argument: --architect" | |
| 558 | - | echo "$usage" | |
| 559 | - | return 1 | |
| 560 | - | fi | |
| 561 | - | use_architect=1 | |
| 562 | - | ;; | |
| 563 | - | --new) | |
| 564 | - | if [ "$use_new" -eq 1 ]; then | |
| 565 | - | echo "Error: Duplicate argument: --new" | |
| 566 | - | echo "$usage" | |
| 567 | - | return 1 | |
| 568 | - | fi | |
| 569 | - | use_new=1 | |
| 570 | - | ;; | |
| 571 | - | --prompt) | |
| 572 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 573 | - | echo "Error: Duplicate argument: --prompt" | |
| 574 | - | echo "$usage" | |
| 575 | - | return 1 | |
| 576 | - | fi | |
| 577 | - | enhance_payload=1 | |
| 578 | - | ;; | |
| 579 | - | --brainstorm) | |
| 580 | - | if [ "$planning_mode" = "brainstorm" ]; then | |
| 581 | - | echo "Error: Duplicate argument: --brainstorm" | |
| 582 | - | echo "$usage" | |
| 583 | - | return 1 | |
| 584 | - | fi | |
| 585 | - | if [ "$planning_mode" != "standard" ]; then | |
| 586 | - | echo "Error: --brainstorm and --writing-plan are mutually exclusive." | |
| 587 | - | echo "$usage" | |
| 588 | - | return 1 | |
| 589 | - | fi | |
| 590 | - | planning_mode="brainstorm" | |
| 591 | - | ;; | |
| 592 | - | --writing-plan) | |
| 593 | - | if [ "$planning_mode" = "writing-plan" ]; then | |
| 594 | - | echo "Error: Duplicate argument: --writing-plan" | |
| 595 | - | echo "$usage" | |
| 596 | - | return 1 | |
| 597 | - | fi | |
| 598 | - | if [ "$planning_mode" != "standard" ]; then | |
| 599 | - | echo "Error: --brainstorm and --writing-plan are mutually exclusive." | |
| 600 | - | echo "$usage" | |
| 601 | - | return 1 | |
| 602 | - | fi | |
| 603 | - | planning_mode="writing-plan" | |
| 604 | - | ;; | |
| 605 | - | *) | |
| 606 | - | echo "Error: Unknown argument: $1" | |
| 607 | - | echo "$usage" | |
| 608 | - | return 1 | |
| 609 | - | ;; | |
| 610 | - | esac | |
| 611 | - | shift | |
| 612 | - | done | |
| 613 | - | ||
| 614 | - | if [ "$use_new" -eq 1 ] && [ "$use_architect" -ne 1 ]; then | |
| 615 | - | echo "Error: --new requires --architect." | |
| 616 | - | echo "$usage" | |
| 434 | + | emulate -L zsh | |
| 435 | + | setopt localtraps | |
| 436 | + | local base_url="${PLAN_BUILD_BASE_URL:-https://opengist.resetrix.work/weehong/plan-build/raw/HEAD}" | |
| 437 | + | local cache_dir="${PLAN_BUILD_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/plan-build}" | |
| 438 | + | local curl_command="${PLAN_BUILD_CURL_COMMAND:-curl}" | |
| 439 | + | local skill_file="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 440 | + | local architect_file="$HOME/.claude/skills/plan-build-architect/SKILL.md" | |
| 441 | + | local stage_dir="" release_dir="" current_tmp="" | |
| 442 | + | local skill_tmp="" architect_tmp="" skill_backup="" architect_backup="" | |
| 443 | + | local activation_lock="$cache_dir/.activate.lock" | |
| 444 | + | local activation_lock_fd="" | |
| 445 | + | local selected_release="" active_pid="" refresh_rc=1 call_rc=0 interrupted_rc=0 | |
| 446 | + | ||
| 447 | + | if ! zmodload zsh/system 2>/dev/null; then | |
| 448 | + | printf "Error: Unable to load the Zsh system module required by plan-build.\n" >&2 | |
| 617 | 449 | return 1 | |
| 618 | 450 | fi | |
| 619 | 451 | ||
| 620 | - | if [ "$use_architect" -eq 1 ] && | |
| 621 | - | { [ "$enhance_payload" -eq 1 ] || [ "$planning_mode" != "standard" ]; }; then | |
| 622 | - | echo "Error: --architect may combine only with --new and --yolo." | |
| 623 | - | echo "$usage" | |
| 452 | + | require_cli zsh "Zsh" || return 1 | |
| 453 | + | ||
| 454 | + | if ! command mkdir -p "$cache_dir" "${skill_file:h}" "${architect_file:h}"; then | |
| 455 | + | printf "Error: Unable to create plan-build cache or skill directories.\n" >&2 | |
| 624 | 456 | return 1 | |
| 625 | 457 | fi | |
| 626 | 458 | ||
| 627 | - | if [ "$use_architect" -eq 1 ]; then | |
| 628 | - | _plan_build_architect_preflight || return 1 | |
| 629 | - | else | |
| 630 | - | require_cli claude "Claude Code CLI" || return 1 | |
| 631 | - | if [ "$planning_mode" != "standard" ]; then | |
| 632 | - | _plan_build_superpowers_preflight || return 1 | |
| 459 | + | _plan_build_cleanup() { | |
| 460 | + | if [[ -n "${active_pid:-}" ]] && command kill -0 "$active_pid" 2>/dev/null; then | |
| 461 | + | command kill "$active_pid" 2>/dev/null || true | |
| 462 | + | wait "$active_pid" 2>/dev/null || true | |
| 633 | 463 | fi | |
| 634 | - | require_cli codex "Codex CLI" || return 1 | |
| 635 | - | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 636 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 637 | - | require_cli auggie "Auggie CLI" || return 1 | |
| 638 | - | require_cli script "script utility" || return 1 | |
| 464 | + | active_pid="" | |
| 465 | + | [[ -n "$stage_dir" && -d "$stage_dir" ]] && command rm -rf -- "$stage_dir" | |
| 466 | + | command rm -f -- "$current_tmp" "$skill_tmp" "$architect_tmp" | |
| 467 | + | command rm -f -- "$skill_backup" "$architect_backup" | |
| 468 | + | if [[ -n "${activation_lock_fd:-}" ]]; then | |
| 469 | + | zsystem flock -u "$activation_lock_fd" 2>/dev/null || true | |
| 470 | + | activation_lock_fd="" | |
| 639 | 471 | fi | |
| 640 | - | fi | |
| 641 | - | ||
| 642 | - | echo "📥 Reading payload... Type 'EOF' on a new line and press Enter when finished." | |
| 643 | - | ||
| 644 | - | local payload | |
| 645 | - | local line | |
| 646 | - | payload="" | |
| 647 | - | ||
| 648 | - | while IFS= read -r line; do | |
| 649 | - | [ "$line" = "EOF" ] && break | |
| 650 | - | if [ -z "$payload" ]; then | |
| 651 | - | payload="$line" | |
| 472 | + | } | |
| 473 | + | _plan_build_cancel() { | |
| 474 | + | interrupted_rc="$1" | |
| 475 | + | [[ -n "${active_pid:-}" ]] && command kill "$active_pid" 2>/dev/null || true | |
| 476 | + | } | |
| 477 | + | trap '_plan_build_cleanup' EXIT | |
| 478 | + | trap '_plan_build_cancel 129' HUP | |
| 479 | + | trap '_plan_build_cancel 130' INT | |
| 480 | + | trap '_plan_build_cancel 143' TERM | |
| 481 | + | ||
| 482 | + | _plan_build_validate_release() { | |
| 483 | + | local candidate="$1" | |
| 484 | + | [[ -d "$candidate" && | |
| 485 | + | -s "$candidate/plan_build.zsh" && | |
| 486 | + | -s "$candidate/SKILL.md" && | |
| 487 | + | -s "$candidate/ARCHITECT.md" ]] && | |
| 488 | + | command zsh -n "$candidate/plan_build.zsh" | |
| 489 | + | } | |
| 490 | + | ||
| 491 | + | _plan_build_replace_path() { | |
| 492 | + | local replacement="$1" destination="$2" | |
| 493 | + | if command mv -fT "$replacement" "$destination" 2>/dev/null; then | |
| 494 | + | return 0 | |
| 495 | + | fi | |
| 496 | + | command mv -fh "$replacement" "$destination" | |
| 497 | + | } | |
| 498 | + | ||
| 499 | + | _plan_build_select_current() { | |
| 500 | + | local resolved | |
| 501 | + | [[ -L "$cache_dir/current" ]] || return 1 | |
| 502 | + | resolved="$cache_dir/current" | |
| 503 | + | resolved="${resolved:A}" | |
| 504 | + | _plan_build_validate_release "$resolved" || return 1 | |
| 505 | + | selected_release="$resolved" | |
| 506 | + | } | |
| 507 | + | ||
| 508 | + | _plan_build_acquire_activation_lock() { | |
| 509 | + | (( interrupted_rc )) && return 1 | |
| 510 | + | command touch "$activation_lock" || return 1 | |
| 511 | + | zsystem flock -t 10 -f activation_lock_fd "$activation_lock" | |
| 512 | + | } | |
| 513 | + | ||
| 514 | + | _plan_build_release_activation_lock() { | |
| 515 | + | [[ -n "$activation_lock_fd" ]] || return 0 | |
| 516 | + | zsystem flock -u "$activation_lock_fd" || return 1 | |
| 517 | + | activation_lock_fd="" | |
| 518 | + | } | |
| 519 | + | ||
| 520 | + | _plan_build_download() { | |
| 521 | + | local remote="$1" destination="$2" download_rc | |
| 522 | + | command "$curl_command" -fsSL "$remote" -o "$destination" & | |
| 523 | + | active_pid=$! | |
| 524 | + | wait "$active_pid" | |
| 525 | + | download_rc=$? | |
| 526 | + | active_pid="" | |
| 527 | + | (( interrupted_rc )) && return "$interrupted_rc" | |
| 528 | + | return "$download_rc" | |
| 529 | + | } | |
| 530 | + | ||
| 531 | + | _plan_build_backup_path() { | |
| 532 | + | local source="$1" backup="$2" | |
| 533 | + | [[ -e "$source" || -L "$source" ]] || return 0 | |
| 534 | + | command rm -f -- "$backup" && command cp -RP "$source" "$backup" | |
| 535 | + | } | |
| 536 | + | ||
| 537 | + | _plan_build_restore_path() { | |
| 538 | + | local destination="$1" backup="$2" had_old="$3" | |
| 539 | + | if (( had_old )); then | |
| 540 | + | _plan_build_replace_path "$backup" "$destination" || return 1 | |
| 652 | 541 | else | |
| 653 | - | payload="${payload}"$'\n'"${line}" | |
| 542 | + | command rm -f -- "$destination" | |
| 543 | + | fi | |
| 544 | + | } | |
| 545 | + | ||
| 546 | + | _plan_build_install_skill_links() { | |
| 547 | + | local activation_ok=1 | |
| 548 | + | local skill_had_old=0 architect_had_old=0 | |
| 549 | + | ||
| 550 | + | skill_tmp="$(command mktemp "${skill_file}.link.XXXXXX")" && | |
| 551 | + | command rm -f "$skill_tmp" && | |
| 552 | + | command ln -s "$cache_dir/current/SKILL.md" "$skill_tmp" || skill_tmp="" | |
| 553 | + | architect_tmp="$(command mktemp "${architect_file}.link.XXXXXX")" && | |
| 554 | + | command rm -f "$architect_tmp" && | |
| 555 | + | command ln -s "$cache_dir/current/ARCHITECT.md" "$architect_tmp" || architect_tmp="" | |
| 556 | + | [[ -n "$skill_tmp" && -L "$skill_tmp" && | |
| 557 | + | -n "$architect_tmp" && -L "$architect_tmp" ]] || return 1 | |
| 558 | + | ||
| 559 | + | skill_backup="${skill_file}.backup.$$.$RANDOM" | |
| 560 | + | architect_backup="${architect_file}.backup.$$.$RANDOM" | |
| 561 | + | [[ -e "$skill_file" || -L "$skill_file" ]] && skill_had_old=1 | |
| 562 | + | [[ -e "$architect_file" || -L "$architect_file" ]] && architect_had_old=1 | |
| 563 | + | _plan_build_backup_path "$skill_file" "$skill_backup" || activation_ok=0 | |
| 564 | + | (( activation_ok )) && _plan_build_backup_path "$architect_file" "$architect_backup" || activation_ok=0 | |
| 565 | + | (( activation_ok && ! interrupted_rc )) && | |
| 566 | + | _plan_build_replace_path "$skill_tmp" "$skill_file" || activation_ok=0 | |
| 567 | + | (( activation_ok )) && skill_tmp="" | |
| 568 | + | (( activation_ok && ! interrupted_rc )) && | |
| 569 | + | _plan_build_replace_path "$architect_tmp" "$architect_file" || activation_ok=0 | |
| 570 | + | (( activation_ok )) && architect_tmp="" | |
| 571 | + | ||
| 572 | + | if (( activation_ok )); then | |
| 573 | + | command rm -f -- "$skill_backup" "$architect_backup" | |
| 574 | + | skill_backup="" architect_backup="" | |
| 575 | + | return 0 | |
| 654 | 576 | fi | |
| 655 | - | done | |
| 656 | 577 | ||
| 657 | - | if [ -z "$payload" ]; then | |
| 658 | - | echo "❌ Error: Payload was empty." | |
| 578 | + | if ! _plan_build_restore_path "$skill_file" "$skill_backup" "$skill_had_old"; then | |
| 579 | + | printf "Error: Unable to restore plan-build skill; backup preserved at %s.\n" "$skill_backup" >&2 | |
| 580 | + | skill_backup="" | |
| 581 | + | fi | |
| 582 | + | if ! _plan_build_restore_path "$architect_file" "$architect_backup" "$architect_had_old"; then | |
| 583 | + | printf "Error: Unable to restore architect skill; backup preserved at %s.\n" "$architect_backup" >&2 | |
| 584 | + | architect_backup="" | |
| 585 | + | fi | |
| 659 | 586 | return 1 | |
| 660 | - | fi | |
| 661 | - | ||
| 662 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 663 | - | local enhanced_file | |
| 664 | - | local review_reply | |
| 665 | - | enhanced_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-enhanced.XXXXXX")" || return 1 | |
| 666 | - | ||
| 667 | - | echo "✨ Enhancing payload with Auggie..." | |
| 668 | - | if ! _enhance_prompt "$payload" "$enhanced_file"; then | |
| 669 | - | rm -f "$enhanced_file" | |
| 670 | - | echo "❌ Error: Prompt enhancement failed; Claude was not launched." | |
| 671 | - | return 1 | |
| 587 | + | } | |
| 588 | + | ||
| 589 | + | if (( $+commands[$curl_command] )) || [[ "$curl_command" == */* && -x "$curl_command" ]]; then | |
| 590 | + | stage_dir="$(command mktemp -d "$cache_dir/.stage.XXXXXX")" || stage_dir="" | |
| 591 | + | if [[ -n "$stage_dir" ]]; then | |
| 592 | + | _plan_build_download "$base_url/plan_build.zsh" "$stage_dir/plan_build.zsh" && | |
| 593 | + | _plan_build_download "$base_url/SKILL.md" "$stage_dir/SKILL.md" && | |
| 594 | + | _plan_build_download "$base_url/ARCHITECT.md" "$stage_dir/ARCHITECT.md" | |
| 595 | + | refresh_rc=$? | |
| 596 | + | if (( interrupted_rc )); then | |
| 597 | + | _plan_build_cleanup | |
| 598 | + | trap - EXIT HUP INT TERM | |
| 599 | + | return "$interrupted_rc" | |
| 600 | + | fi | |
| 601 | + | else | |
| 602 | + | refresh_rc=1 | |
| 672 | 603 | fi | |
| 673 | - | ||
| 674 | - | payload="$(cat "$enhanced_file")" | |
| 675 | - | rm -f "$enhanced_file" | |
| 676 | - | ||
| 677 | - | if [ -z "$payload" ]; then | |
| 678 | - | echo "❌ Error: Enhanced payload was empty; Claude was not launched." | |
| 679 | - | return 1 | |
| 604 | + | if (( refresh_rc == 0 )) && | |
| 605 | + | _plan_build_validate_release "$stage_dir"; then | |
| 606 | + | release_dir="$(command mktemp -d "$cache_dir/release.XXXXXX")" || release_dir="" | |
| 607 | + | if [[ -n "$release_dir" ]] && | |
| 608 | + | command rmdir "$release_dir" && | |
| 609 | + | command mv "$stage_dir" "$release_dir" && | |
| 610 | + | _plan_build_acquire_activation_lock; then | |
| 611 | + | stage_dir="" | |
| 612 | + | release_dir="${release_dir:A}" | |
| 613 | + | current_tmp="$(command mktemp "$cache_dir/.current.XXXXXX")" && | |
| 614 | + | command rm -f "$current_tmp" && | |
| 615 | + | command ln -s "$release_dir" "$current_tmp" || current_tmp="" | |
| 616 | + | ||
| 617 | + | if [[ -n "$current_tmp" && -L "$current_tmp" ]] && | |
| 618 | + | _plan_build_install_skill_links && | |
| 619 | + | _plan_build_replace_path "$current_tmp" "$cache_dir/current"; then | |
| 620 | + | current_tmp="" | |
| 621 | + | selected_release="$release_dir" | |
| 622 | + | fi | |
| 623 | + | _plan_build_release_activation_lock || true | |
| 624 | + | fi | |
| 680 | 625 | fi | |
| 626 | + | fi | |
| 681 | 627 | ||
| 682 | - | printf '\n%s\n' "━━━━━━━━━━━━━━━━ Auggie enhanced prompt ━━━━━━━━━━━━━━━━" | |
| 683 | - | printf '%s\n' "$payload" | |
| 684 | - | printf '%s\n\n' "━━━━━━━━━━━━━━━━ End enhanced prompt ━━━━━━━━━━━━━━━━━" | |
| 685 | - | ||
| 686 | - | if ! (: </dev/tty) 2>/dev/null; then | |
| 687 | - | echo "❌ Error: Cannot review the enhanced prompt without an interactive terminal; Claude was not launched." | |
| 688 | - | return 1 | |
| 689 | - | fi | |
| 628 | + | if (( interrupted_rc )); then | |
| 629 | + | _plan_build_cleanup | |
| 630 | + | trap - EXIT HUP INT TERM | |
| 631 | + | return "$interrupted_rc" | |
| 632 | + | fi | |
| 690 | 633 | ||
| 691 | - | printf "Proceed with this enhanced prompt? (y/N) " >/dev/tty | |
| 692 | - | if ! IFS= read -r review_reply </dev/tty; then | |
| 693 | - | printf '\n' >/dev/tty | |
| 694 | - | echo "🛑 Review cancelled; Claude was not launched." | |
| 634 | + | if [[ -z "$selected_release" ]]; then | |
| 635 | + | if ! _plan_build_select_current; then | |
| 636 | + | if (( ! $+commands[$curl_command] )) && [[ ! ( "$curl_command" == */* && -x "$curl_command" ) ]]; then | |
| 637 | + | printf "Error: curl is required because no valid cached plan-build bundle is available.\n" >&2 | |
| 638 | + | else | |
| 639 | + | printf "Error: Unable to refresh plan-build and no valid cached bundle is available.\n" >&2 | |
| 640 | + | fi | |
| 695 | 641 | return 1 | |
| 696 | 642 | fi | |
| 697 | - | ||
| 698 | - | case "$review_reply" in | |
| 699 | - | y|Y|yes|YES|Yes) | |
| 700 | - | echo "✅ Enhanced prompt approved." | |
| 701 | - | ;; | |
| 702 | - | *) | |
| 703 | - | echo "🛑 Enhanced prompt not approved; Claude was not launched." | |
| 704 | - | return 0 | |
| 705 | - | ;; | |
| 706 | - | esac | |
| 707 | - | fi | |
| 708 | - | ||
| 709 | - | if [ "$use_architect" -eq 1 ]; then | |
| 710 | - | local architect_start_mode | |
| 711 | - | if [ "$use_new" -eq 1 ]; then | |
| 712 | - | 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." | |
| 643 | + | if (( ! $+commands[$curl_command] )) && [[ ! ( "$curl_command" == */* && -x "$curl_command" ) ]]; then | |
| 644 | + | printf "Warning: curl is unavailable; using the validated cached plan-build bundle.\n" >&2 | |
| 713 | 645 | else | |
| 714 | - | 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." | |
| 646 | + | printf "Warning: Unable to refresh plan-build; using the validated cached bundle.\n" >&2 | |
| 715 | 647 | fi | |
| 716 | - | ||
| 717 | - | echo "🚀 Launching Claude Code in architect mode..." | |
| 718 | - | ||
| 719 | - | claude "${claude_args[@]}" "Read \`~/.claude/skills/plan-build-architect/SKILL.md\` and follow it strictly, including every gate even when --yolo is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement. | |
| 720 | - | ||
| 721 | - | $architect_start_mode | |
| 722 | - | ||
| 723 | - | Use the following payload as the initial requirement: | |
| 724 | - | ||
| 725 | - | $payload" | |
| 726 | - | return $? | |
| 727 | 648 | fi | |
| 728 | 649 | ||
| 729 | - | local planning_instruction | |
| 730 | - | case "$planning_mode" in | |
| 731 | - | brainstorm) | |
| 732 | - | 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." | |
| 733 | - | ;; | |
| 734 | - | writing-plan) | |
| 735 | - | 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." | |
| 736 | - | ;; | |
| 737 | - | *) | |
| 738 | - | planning_instruction="Planning mode: standard. Create the workflow's normal short implementation plan." | |
| 739 | - | ;; | |
| 740 | - | esac | |
| 741 | - | ||
| 742 | - | echo "🚀 Launching Claude Code with your multi-agent workflow ($planning_mode planning)..." | |
| 743 | - | ||
| 744 | - | claude "${claude_args[@]}" "Please read \`~/.claude/skills/plan-build/SKILL.md\` and strictly follow the 8-step multi-agent workflow to implement the following task. | |
| 745 | - | ||
| 746 | - | $planning_instruction | |
| 747 | - | ||
| 748 | - | $payload" | |
| 650 | + | if [[ "$(command readlink "$skill_file" 2>/dev/null)" != "$cache_dir/current/SKILL.md" || | |
| 651 | + | "$(command readlink "$architect_file" 2>/dev/null)" != "$cache_dir/current/ARCHITECT.md" ]]; then | |
| 652 | + | if ! _plan_build_acquire_activation_lock || ! _plan_build_install_skill_links; then | |
| 653 | + | _plan_build_release_activation_lock 2>/dev/null || true | |
| 654 | + | if (( interrupted_rc )); then | |
| 655 | + | _plan_build_cleanup | |
| 656 | + | trap - EXIT HUP INT TERM | |
| 657 | + | return "$interrupted_rc" | |
| 658 | + | fi | |
| 659 | + | printf "Error: Unable to install the plan-build skill links.\n" >&2 | |
| 660 | + | return 1 | |
| 661 | + | fi | |
| 662 | + | _plan_build_release_activation_lock || true | |
| 663 | + | fi | |
| 664 | + | ||
| 665 | + | if (( interrupted_rc )); then | |
| 666 | + | _plan_build_cleanup | |
| 667 | + | trap - EXIT HUP INT TERM | |
| 668 | + | return "$interrupted_rc" | |
| 669 | + | fi | |
| 670 | + | ||
| 671 | + | PLAN_BUILD_SKILL_PATH="$selected_release/SKILL.md" \ | |
| 672 | + | PLAN_BUILD_ARCHITECT_SKILL_PATH="$selected_release/ARCHITECT.md" \ | |
| 673 | + | command zsh "$selected_release/plan_build.zsh" "$@" & | |
| 674 | + | active_pid=$! | |
| 675 | + | wait "$active_pid" | |
| 676 | + | call_rc=$? | |
| 677 | + | active_pid="" | |
| 678 | + | (( interrupted_rc )) && call_rc="$interrupted_rc" | |
| 679 | + | _plan_build_cleanup | |
| 680 | + | trap - EXIT HUP INT TERM | |
| 681 | + | return "$call_rc" | |
| 749 | 682 | } | |
| 750 | 683 | ||
| 751 | 684 | # ----------------------------------------------------------------------------- | |
orchestrate-loop.md (файл удалён)
| @@ -1,190 +0,0 @@ | |||
| 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. When `plan_build` supplies "Distribution mode: on", Codex and Kimi Code also become the implementers (backend and frontend respectively) via the Distributed Implementation variant of step 5. | |
| 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 | - | - `grill`: Invoke `mattpocock-skills:grilling` to relentlessly stress-test the payload and your intended approach with the user. After grilling concludes, write the workflow's normal short implementation plan incorporating what survived. | |
| 46 | - | ||
| 47 | - | For either Superpowers mode, save the artifacts at the paths selected by the skills. In `grill` mode, the short implementation plan is the planning artifact. 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. | |
| 48 | - | ||
| 49 | - | If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note. | |
| 50 | - | ||
| 51 | - | ### 4. Codex Plan Review | |
| 52 | - | ||
| 53 | - | Run this step only for `brainstorm`, `writing-plan`, and `grill` 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. | |
| 54 | - | ||
| 55 | - | Recommended prompt shape: | |
| 56 | - | ||
| 57 | - | ```text | |
| 58 | - | 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. | |
| 59 | - | ||
| 60 | - | Task: | |
| 61 | - | <payload> | |
| 62 | - | ||
| 63 | - | Spec: | |
| 64 | - | <spec path, if present> | |
| 65 | - | ||
| 66 | - | Implementation plan: | |
| 67 | - | <plan path> | |
| 68 | - | ``` | |
| 69 | - | ||
| 70 | - | 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. | |
| 71 | - | ||
| 72 | - | In `standard` mode, skip this step and continue directly to implementation. | |
| 73 | - | ||
| 74 | - | ### 5. Implement | |
| 75 | - | ||
| 76 | - | If `plan_build` supplied "Distribution mode: on", skip this step and step 6 | |
| 77 | - | and follow the Distributed Implementation variant (steps 5a–5c) below | |
| 78 | - | instead, then continue at step 7. | |
| 79 | - | ||
| 80 | - | Make the change in small, reviewable edits: | |
| 81 | - | ||
| 82 | - | - Follow existing style and abstractions. | |
| 83 | - | - Add or update tests when behavior changes. | |
| 84 | - | - Update docs only when user-facing usage changes. | |
| 85 | - | - Avoid unrelated refactors and formatting churn. | |
| 86 | - | ||
| 87 | - | After each meaningful edit group, re-check the diff for accidental changes. | |
| 88 | - | ||
| 89 | - | ### Distributed Implementation (distribution mode: on) | |
| 90 | - | ||
| 91 | - | In this variant you orchestrate and review only — you never implement, | |
| 92 | - | not even leftovers. Codex implements backend items; Kimi Code implements | |
| 93 | - | frontend items. | |
| 94 | - | ||
| 95 | - | #### 5a. Split And Confirm | |
| 96 | - | ||
| 97 | - | Tag every work item in the plan as `BE`, `FE`, or `unclear`. Present the | |
| 98 | - | full table to the user (AskUserQuestion) and have them confirm or | |
| 99 | - | reassign each item; `unclear` items must be assigned by the user to `BE` | |
| 100 | - | or `FE`. Dispatch nothing until every item is confirmed. | |
| 101 | - | ||
| 102 | - | #### 5b. Backend Phase (Codex) | |
| 103 | - | ||
| 104 | - | Check `git status` first so pre-existing work is never mixed in or | |
| 105 | - | reverted. Compose a self-contained brief: the task, constraints, the | |
| 106 | - | exact confirmed BE item list with file paths, project conventions, and | |
| 107 | - | validation commands. Dispatch: | |
| 108 | - | ||
| 109 | - | ```bash | |
| 110 | - | codex exec --full-auto "<brief>" | |
| 111 | - | ``` | |
| 112 | - | ||
| 113 | - | Then review the phase diff (`git diff`) yourself for correctness, scope, | |
| 114 | - | and convention fit. Send findings back to Codex as a new brief (findings | |
| 115 | - | plus the original context) — do not fix them yourself. Maximum 2 retry | |
| 116 | - | rounds; if valid findings remain after that, stop and report with the | |
| 117 | - | partial diff intact. | |
| 118 | - | ||
| 119 | - | An empty diff from a delegate counts as a failure: retry once with a | |
| 120 | - | sharpened brief, within the same 2-round bound. If the delegate CLI | |
| 121 | - | crashes or hangs, stop and report, preserving the partial diff. | |
| 122 | - | ||
| 123 | - | #### 5c. Frontend Phase (Kimi Code) | |
| 124 | - | ||
| 125 | - | Check `git status` again, then compose the FE brief the same way, and | |
| 126 | - | additionally include the now-implemented backend API surface (routes, | |
| 127 | - | types, request/response contracts) so the frontend builds against the | |
| 128 | - | real backend. Dispatch: | |
| 129 | - | ||
| 130 | - | ```bash | |
| 131 | - | kimi -p "<brief>" | |
| 132 | - | ``` | |
| 133 | - | ||
| 134 | - | (`-p` runs one prompt non-interactively and manages permissions itself; | |
| 135 | - | it cannot be combined with `--auto` or `--yolo`.) | |
| 136 | - | ||
| 137 | - | Review the phase diff and route findings back to Kimi under the same | |
| 138 | - | 2-round retry bound and failure rules as the backend phase. | |
| 139 | - | ||
| 140 | - | After both phases pass review, skip step 6 (the per-phase reviews above | |
| 141 | - | replace it — Codex cannot impartially review the half it wrote) and | |
| 142 | - | continue at step 7 with the combined diff. | |
| 143 | - | ||
| 144 | - | ### 6. Codex Code Review Pass | |
| 145 | - | ||
| 146 | - | Skip this step in distribution mode; the per-phase reviews in steps | |
| 147 | - | 5b–5c replace it. | |
| 148 | - | ||
| 149 | - | 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. | |
| 150 | - | ||
| 151 | - | Recommended prompt shape: | |
| 152 | - | ||
| 153 | - | ```text | |
| 154 | - | 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. | |
| 155 | - | ||
| 156 | - | Task: | |
| 157 | - | <payload> | |
| 158 | - | ||
| 159 | - | Diff: | |
| 160 | - | <git diff> | |
| 161 | - | ``` | |
| 162 | - | ||
| 163 | - | Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial. | |
| 164 | - | ||
| 165 | - | ### 7. CodeRabbit Review Pass | |
| 166 | - | ||
| 167 | - | Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding. | |
| 168 | - | ||
| 169 | - | If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely. | |
| 170 | - | ||
| 171 | - | ### 8. Validate And Close | |
| 172 | - | ||
| 173 | - | Run the planned validation commands, such as: | |
| 174 | - | ||
| 175 | - | ```bash | |
| 176 | - | npm test | |
| 177 | - | npm run lint | |
| 178 | - | pytest | |
| 179 | - | cargo test | |
| 180 | - | go test ./... | |
| 181 | - | ``` | |
| 182 | - | ||
| 183 | - | 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. | |
| 184 | - | ||
| 185 | - | Before final response: | |
| 186 | - | ||
| 187 | - | - Confirm `git diff` contains only intended changes. | |
| 188 | - | - Summarize what changed. | |
| 189 | - | - Report validation run and result. | |
| 190 | - | - Note any remaining risks or commands that could not run. | |
test_plan_build.zsh
| @@ -1,169 +1,232 @@ | |||
| 1 | 1 | #!/usr/bin/env zsh | |
| 2 | 2 | ||
| 3 | - | set -eu | |
| 3 | + | set -u | |
| 4 | 4 | ||
| 5 | 5 | repo_dir="${0:A:h}" | |
| 6 | 6 | source "$repo_dir/func" | |
| 7 | 7 | ||
| 8 | 8 | failures=0 | |
| 9 | + | fixture_dir="$(mktemp -d "${TMPDIR:-/tmp}/plan build launcher.XXXXXX")" || exit 1 | |
| 10 | + | source_dir="$(mktemp -d "${TMPDIR:-/tmp}/plan-build-source.XXXXXX")" || exit 1 | |
| 11 | + | export PLAN_BUILD_CACHE_DIR="$fixture_dir/cache with spaces" | |
| 12 | + | export PLAN_BUILD_BASE_URL="file://$source_dir" | |
| 13 | + | export HOME="$fixture_dir/home with spaces" | |
| 14 | + | PLAN_BUILD_SKILLS_DIR="$HOME/.claude/skills" | |
| 15 | + | mkdir -p "$source_dir" "$PLAN_BUILD_SKILLS_DIR/plan-build" "$PLAN_BUILD_SKILLS_DIR/plan-build-architect" | |
| 16 | + | print -r -- "old standard" > "$PLAN_BUILD_SKILLS_DIR/plan-build/SKILL.md" | |
| 17 | + | print -r -- "old architect" > "$PLAN_BUILD_SKILLS_DIR/plan-build-architect/SKILL.md" | |
| 18 | + | trap 'rm -rf -- "$fixture_dir" "$source_dir"' EXIT | |
| 19 | + | ||
| 20 | + | fail() { | |
| 21 | + | print -u2 -- "FAIL: $1" | |
| 22 | + | failures=$((failures + 1)) | |
| 23 | + | } | |
| 9 | 24 | ||
| 10 | 25 | assert_equal() { | |
| 11 | - | local expected="$1" | |
| 12 | - | local actual="$2" | |
| 13 | - | local label="$3" | |
| 14 | - | ||
| 15 | - | if [ "$actual" != "$expected" ]; then | |
| 16 | - | print -u2 -- "FAIL: $label (expected '$expected', got '$actual')" | |
| 17 | - | failures=$((failures + 1)) | |
| 18 | - | fi | |
| 26 | + | [[ "$1" = "$2" ]] || fail "$3 (expected '$1', got '$2')" | |
| 19 | 27 | } | |
| 20 | 28 | ||
| 21 | 29 | assert_contains() { | |
| 22 | - | local output="$1" | |
| 23 | - | local expected="$2" | |
| 24 | - | local label="$3" | |
| 25 | - | ||
| 26 | - | if [[ "$output" != *"$expected"* ]]; then | |
| 27 | - | print -u2 -- "FAIL: $label (missing '$expected')" | |
| 28 | - | failures=$((failures + 1)) | |
| 29 | - | fi | |
| 30 | + | [[ "$1" == *"$2"* ]] || fail "$3 (missing '$2')" | |
| 30 | 31 | } | |
| 31 | 32 | ||
| 32 | - | assert_not_contains() { | |
| 33 | - | local output="$1" | |
| 34 | - | local unexpected="$2" | |
| 35 | - | local label="$3" | |
| 36 | - | ||
| 37 | - | if [[ "$output" == *"$unexpected"* ]]; then | |
| 38 | - | print -u2 -- "FAIL: $label (unexpected '$unexpected')" | |
| 39 | - | failures=$((failures + 1)) | |
| 40 | - | fi | |
| 33 | + | assert_file_contains() { | |
| 34 | + | command grep -Fq -- "$2" "$1" || fail "$3" | |
| 41 | 35 | } | |
| 42 | 36 | ||
| 43 | - | preflight_fixture_dir="$(mktemp -d "${TMPDIR:-/tmp}/plan-build-preflight.XXXXXX")" | |
| 44 | - | trap 'rm -rf -- "$preflight_fixture_dir"' EXIT | |
| 45 | - | command git init -q "$preflight_fixture_dir/worktree" | |
| 46 | - | command git init -q --bare "$preflight_fixture_dir/bare.git" | |
| 47 | - | ||
| 48 | - | (cd "$preflight_fixture_dir/worktree" && _plan_build_is_worktree) && rc=0 || rc=$? | |
| 49 | - | assert_equal "0" "$rc" "architect preflight accepts normal worktree" | |
| 50 | - | ||
| 51 | - | (cd "$preflight_fixture_dir/bare.git" && _plan_build_is_worktree) && rc=0 || rc=$? | |
| 52 | - | assert_equal "1" "$rc" "architect preflight rejects bare repository" | |
| 53 | - | ||
| 54 | - | plugin_state() { | |
| 55 | - | printf '%s\n' "$1" | _plan_build_superpowers_state | |
| 37 | + | assert_bundle_consistent() { | |
| 38 | + | local release="$PLAN_BUILD_CACHE_DIR/current" | |
| 39 | + | local script_generation skill_generation architect_generation | |
| 40 | + | release="${release:A}" | |
| 41 | + | [[ -L "$PLAN_BUILD_CACHE_DIR/current" ]] || fail "$1 current is a symlink" | |
| 42 | + | [[ -d "$release" ]] || fail "$1 current resolves to a release" | |
| 43 | + | script_generation="$(command sed -n 's/^# generation: //p' "$release/plan_build.zsh")" | |
| 44 | + | skill_generation="$(command sed -n 's/ standard skill$//p' "$release/SKILL.md")" | |
| 45 | + | architect_generation="$(command sed -n 's/ architect skill$//p' "$release/ARCHITECT.md")" | |
| 46 | + | assert_equal "$script_generation" "$skill_generation" "$1 script/standard generation" | |
| 47 | + | assert_equal "$script_generation" "$architect_generation" "$1 script/architect generation" | |
| 56 | 48 | } | |
| 57 | 49 | ||
| 58 | - | assert_equal "enabled" "$(plugin_state '[{"id":"superpowers@claude-plugins-official","enabled":true}]')" "compact enabled JSON" | |
| 59 | - | assert_equal "disabled" "$(plugin_state $'[\n {\n "enabled": false,\n "id": "superpowers@claude-plugins-official"\n }\n]')" "reordered disabled JSON" | |
| 60 | - | assert_equal "enabled" "$(plugin_state $'[\n {"enabled": false, "id": "other@market"},\n {"enabled": true, "id": "superpowers@claude-plugins-official"}\n]')" "multiple plugin JSON" | |
| 61 | - | assert_equal "missing" "$(plugin_state '[{"id":"coderabbit@claude-plugins-official","enabled":true}]')" "missing plugin JSON" | |
| 62 | - | assert_equal "installed" "$(plugin_state '[{"id":"superpowers@claude-plugins-official"}]')" "malformed plugin JSON" | |
| 63 | - | ||
| 64 | - | output="$(plan_build --brainstorm --writing-plan 2>&1)" && rc=0 || rc=$? | |
| 65 | - | assert_equal "1" "$rc" "mutually exclusive flags status" | |
| 66 | - | assert_contains "$output" "mutually exclusive" "mutually exclusive flags message" | |
| 67 | - | ||
| 68 | - | output="$(plan_build --brainstorm --brainstorm 2>&1)" && rc=0 || rc=$? | |
| 69 | - | assert_equal "1" "$rc" "duplicate brainstorm status" | |
| 70 | - | assert_contains "$output" "Duplicate argument: --brainstorm" "duplicate brainstorm message" | |
| 71 | - | ||
| 72 | - | output="$(plan_build --writing-plan --writing-plan 2>&1)" && rc=0 || rc=$? | |
| 73 | - | assert_equal "1" "$rc" "duplicate writing-plan status" | |
| 74 | - | assert_contains "$output" "Duplicate argument: --writing-plan" "duplicate writing-plan message" | |
| 75 | - | ||
| 76 | - | output="$(plan_build --v2 2>&1)" && rc=0 || rc=$? | |
| 77 | - | assert_equal "1" "$rc" "v2 unknown argument status" | |
| 78 | - | assert_contains "$output" "Unknown argument: --v2" "v2 unknown argument message" | |
| 79 | - | ||
| 80 | - | for args expected label in \ | |
| 81 | - | "--architect --architect" "--architect" "duplicate architect" \ | |
| 82 | - | "--architect --new --new" "--new" "duplicate new"; do | |
| 83 | - | output="$(plan_build ${(z)args} 2>&1)" && rc=0 || rc=$? | |
| 84 | - | assert_equal "1" "$rc" "$label status" | |
| 85 | - | assert_contains "$output" "Duplicate argument: $expected" "$label message" | |
| 86 | - | assert_contains "$output" "plan_build --architect [--new] [--yolo]" "$label usage" | |
| 87 | - | done | |
| 88 | - | ||
| 89 | - | for args in \ | |
| 90 | - | "--architect --prompt" \ | |
| 91 | - | "--architect --brainstorm" \ | |
| 92 | - | "--architect --writing-plan"; do | |
| 93 | - | output="$(plan_build ${(z)args} 2>&1)" && rc=0 || rc=$? | |
| 94 | - | assert_equal "1" "$rc" "$args incompatible status" | |
| 95 | - | assert_contains "$output" "may combine only with --new and --yolo" "$args incompatible message" | |
| 96 | - | done | |
| 97 | - | ||
| 98 | - | output="$(plan_build --new 2>&1)" && rc=0 || rc=$? | |
| 99 | - | assert_equal "1" "$rc" "orphan new status" | |
| 100 | - | assert_contains "$output" "--new requires --architect" "orphan new message" | |
| 101 | - | ||
| 102 | - | export CLAUDE_CODE_SAFE_MODE=1 | |
| 103 | - | output="$(_plan_build_superpowers_preflight 2>&1)" && rc=0 || rc=$? | |
| 104 | - | unset CLAUDE_CODE_SAFE_MODE | |
| 105 | - | assert_equal "1" "$rc" "safe mode status" | |
| 106 | - | assert_contains "$output" "safe mode disables Superpowers" "safe mode message" | |
| 107 | - | ||
| 108 | - | require_cli() { return 0; } | |
| 109 | - | _plan_build_superpowers_preflight() { return 0; } | |
| 110 | - | architect_preflight_calls=0 | |
| 111 | - | _plan_build_architect_preflight() { | |
| 112 | - | architect_preflight_calls=$((architect_preflight_calls + 1)) | |
| 113 | - | return 0 | |
| 50 | + | assert_skill_links() { | |
| 51 | + | [[ -L "$PLAN_BUILD_SKILLS_DIR/plan-build/SKILL.md" ]] || fail "$1 standard path is symlink" | |
| 52 | + | [[ -L "$PLAN_BUILD_SKILLS_DIR/plan-build-architect/SKILL.md" ]] || fail "$1 architect path is symlink" | |
| 53 | + | assert_equal "$PLAN_BUILD_CACHE_DIR/current/SKILL.md" \ | |
| 54 | + | "$(command readlink "$PLAN_BUILD_SKILLS_DIR/plan-build/SKILL.md")" "$1 standard link target" | |
| 55 | + | assert_equal "$PLAN_BUILD_CACHE_DIR/current/ARCHITECT.md" \ | |
| 56 | + | "$(command readlink "$PLAN_BUILD_SKILLS_DIR/plan-build-architect/SKILL.md")" "$1 architect link target" | |
| 114 | 57 | } | |
| 115 | - | claude() { | |
| 116 | - | printf 'CLAUDE_ARGS:' | |
| 117 | - | printf ' <%s>' "$@" | |
| 118 | - | printf '\n' | |
| 58 | + | ||
| 59 | + | write_bundle() { | |
| 60 | + | local generation="$1" | |
| 61 | + | local exit_code="${2:-0}" | |
| 62 | + | local marker_file="${3:-}" | |
| 63 | + | print -r -- '#!/usr/bin/env zsh' > "$source_dir/plan_build.zsh" | |
| 64 | + | print -r -- "# generation: $generation" >> "$source_dir/plan_build.zsh" | |
| 65 | + | print -r -- "print -r -- \"$generation:\${(j:|:)@}\"" >> "$source_dir/plan_build.zsh" | |
| 66 | + | print -r -- "print -r -- \"path:\${0}\"" >> "$source_dir/plan_build.zsh" | |
| 67 | + | print -r -- 'print -r -- "skills:${PLAN_BUILD_SKILL_PATH}|${PLAN_BUILD_ARCHITECT_SKILL_PATH}"' >> "$source_dir/plan_build.zsh" | |
| 68 | + | [[ -n "$marker_file" ]] && print -r -- ": > ${(q)marker_file}" >> "$source_dir/plan_build.zsh" | |
| 69 | + | print -r -- "exit $exit_code" >> "$source_dir/plan_build.zsh" | |
| 70 | + | print -r -- "$generation standard skill" > "$source_dir/SKILL.md" | |
| 71 | + | print -r -- "$generation architect skill" > "$source_dir/ARCHITECT.md" | |
| 119 | 72 | } | |
| 120 | 73 | ||
| 121 | - | output="$(printf 'build feature\nEOF\n' | plan_build --writing-plan --yolo 2>&1)" && rc=0 || rc=$? | |
| 122 | - | assert_equal "0" "$rc" "writing-plan launch status" | |
| 123 | - | assert_contains "$output" "Planning mode: writing-plan" "writing-plan prompt" | |
| 124 | - | assert_contains "$output" "<--yolo>" "yolo forwarding" | |
| 125 | - | ||
| 126 | - | output="$(printf 'build feature\nEOF\n' | plan_build --brainstorm 2>&1)" && rc=0 || rc=$? | |
| 127 | - | assert_equal "0" "$rc" "brainstorm launch status" | |
| 128 | - | assert_contains "$output" "Planning mode: brainstorm" "brainstorm prompt" | |
| 129 | - | ||
| 130 | - | output="$(printf 'build feature\nEOF\n' | plan_build 2>&1)" && rc=0 || rc=$? | |
| 131 | - | assert_equal "0" "$rc" "standard launch status" | |
| 132 | - | assert_contains "$output" "Planning mode: standard" "standard prompt" | |
| 133 | - | ||
| 134 | - | output="$(printf 'design feature\nEOF\n' | plan_build --architect 2>&1)" && rc=0 || rc=$? | |
| 135 | - | assert_equal "0" "$rc" "architect launch status" | |
| 136 | - | assert_contains "$output" "~/.claude/skills/plan-build-architect/SKILL.md" "architect skill path" | |
| 137 | - | assert_contains "$output" "documentation-first architect/orchestrator role" "architect role boundary" | |
| 138 | - | assert_contains "$output" "design feature" "architect payload" | |
| 139 | - | assert_contains "$output" "Start mode: safe-resume-detection" "architect resume mode" | |
| 140 | - | ||
| 141 | - | output="$(printf 'fresh design\nEOF\n' | plan_build --architect --new 2>&1)" && rc=0 || rc=$? | |
| 142 | - | assert_equal "0" "$rc" "architect new launch status" | |
| 143 | - | assert_contains "$output" "Start mode: archive-and-start-new" "architect new mode" | |
| 144 | - | assert_contains "$output" "fresh design" "architect new payload" | |
| 145 | - | ||
| 146 | - | output="$(printf 'fast design\nEOF\n' | plan_build --architect --yolo 2>&1)" && rc=0 || rc=$? | |
| 147 | - | assert_equal "0" "$rc" "architect yolo launch status" | |
| 148 | - | assert_contains "$output" "<--yolo>" "architect yolo forwarding" | |
| 149 | - | assert_contains "$output" "every gate even when --yolo is active" "architect yolo gates" | |
| 150 | - | ||
| 151 | - | output="$(printf 'EOF\n' | plan_build --architect 2>&1)" && rc=0 || rc=$? | |
| 152 | - | assert_equal "1" "$rc" "architect empty payload status" | |
| 153 | - | assert_contains "$output" "Payload was empty" "architect empty payload message" | |
| 154 | - | ||
| 155 | - | _plan_build_architect_preflight() { | |
| 156 | - | echo "architect preflight failed" | |
| 157 | - | return 1 | |
| 74 | + | run_plan_build() { | |
| 75 | + | output="$(plan_build "$@" 2>&1)" | |
| 76 | + | rc=$? | |
| 158 | 77 | } | |
| 159 | - | output="$(printf 'must not be read\nEOF\n' | plan_build --architect 2>&1)" && rc=0 || rc=$? | |
| 160 | - | assert_equal "1" "$rc" "architect preflight failure status" | |
| 161 | - | assert_contains "$output" "architect preflight failed" "architect preflight failure message" | |
| 162 | - | assert_not_contains "$output" "Reading payload" "architect preflight before payload" | |
| 163 | - | assert_not_contains "$output" "CLAUDE_ARGS" "architect preflight prevents launch" | |
| 164 | 78 | ||
| 165 | - | if [ "$failures" -ne 0 ]; then | |
| 79 | + | write_bundle initial | |
| 80 | + | run_plan_build alpha "two words" | |
| 81 | + | assert_equal 0 "$rc" "initial migration status" | |
| 82 | + | assert_contains "$output" "initial:alpha|two words" "argument forwarding" | |
| 83 | + | assert_skill_links "initial migration" | |
| 84 | + | assert_bundle_consistent "initial migration" | |
| 85 | + | assert_file_contains "$PLAN_BUILD_SKILLS_DIR/plan-build/SKILL.md" "initial standard" "initial standard content" | |
| 86 | + | assert_file_contains "$PLAN_BUILD_SKILLS_DIR/plan-build-architect/SKILL.md" "initial architect" "initial architect content" | |
| 87 | + | execution_path="${${(f)output}[(r)path:*]#path:}" | |
| 88 | + | [[ "$execution_path" == "$PLAN_BUILD_CACHE_DIR"/release.*/plan_build.zsh ]] || | |
| 89 | + | fail "execution uses an immutable release path" | |
| 90 | + | assert_contains "$output" "skills:${execution_path:h}/SKILL.md|${execution_path:h}/ARCHITECT.md" \ | |
| 91 | + | "execution binds immutable skill paths" | |
| 92 | + | ||
| 93 | + | old_release="$PLAN_BUILD_CACHE_DIR/current" | |
| 94 | + | old_release="${old_release:A}" | |
| 95 | + | write_bundle replacement 23 | |
| 96 | + | run_plan_build forwarded | |
| 97 | + | assert_equal 23 "$rc" "canonical status forwarding" | |
| 98 | + | assert_contains "$output" "replacement:forwarded" "replacement executes" | |
| 99 | + | new_release="$PLAN_BUILD_CACHE_DIR/current" | |
| 100 | + | new_release="${new_release:A}" | |
| 101 | + | [[ "$new_release" != "$old_release" ]] || fail "refresh activates a unique release" | |
| 102 | + | assert_skill_links "replacement" | |
| 103 | + | assert_bundle_consistent "replacement" | |
| 104 | + | ||
| 105 | + | print -r -- 'if broken' > "$source_dir/plan_build.zsh" | |
| 106 | + | print -r -- "bad standard skill" > "$source_dir/SKILL.md" | |
| 107 | + | print -r -- "bad architect skill" > "$source_dir/ARCHITECT.md" | |
| 108 | + | run_plan_build fallback | |
| 109 | + | assert_equal 23 "$rc" "failed refresh fallback status" | |
| 110 | + | assert_contains "$output" "Warning: Unable to refresh" "failed refresh warning" | |
| 111 | + | assert_contains "$output" "replacement:fallback" "failed refresh executes current" | |
| 112 | + | preserved_release="$PLAN_BUILD_CACHE_DIR/current" | |
| 113 | + | preserved_release="${preserved_release:A}" | |
| 114 | + | assert_equal "$new_release" "$preserved_release" "failed refresh preserves current" | |
| 115 | + | assert_skill_links "failed refresh" | |
| 116 | + | assert_bundle_consistent "failed refresh" | |
| 117 | + | ||
| 118 | + | export PLAN_BUILD_CURL_COMMAND="definitely-missing-plan-build-curl" | |
| 119 | + | run_plan_build no-curl | |
| 120 | + | assert_equal 23 "$rc" "missing curl fallback status" | |
| 121 | + | assert_contains "$output" "curl is unavailable" "missing curl warning" | |
| 122 | + | assert_contains "$output" "replacement:no-curl" "missing curl executes current" | |
| 123 | + | rm -f "$PLAN_BUILD_SKILLS_DIR/plan-build/SKILL.md" "$PLAN_BUILD_SKILLS_DIR/plan-build-architect/SKILL.md" | |
| 124 | + | run_plan_build repaired-offline | |
| 125 | + | assert_equal 23 "$rc" "offline skill repair status" | |
| 126 | + | assert_skill_links "offline skill repair" | |
| 127 | + | unset PLAN_BUILD_CURL_COMMAND | |
| 128 | + | ||
| 129 | + | # An already selected immutable script must not change beneath a concurrent caller. | |
| 130 | + | ready_file="$fixture_dir/ready" | |
| 131 | + | go_file="$fixture_dir/go" | |
| 132 | + | first_output="$fixture_dir/first.out" | |
| 133 | + | print -r -- '#!/usr/bin/env zsh' > "$source_dir/plan_build.zsh" | |
| 134 | + | print -r -- '# generation: concurrent_first' >> "$source_dir/plan_build.zsh" | |
| 135 | + | print -r -- 'print -r -- "concurrent_first:${(j:|:)@}"' >> "$source_dir/plan_build.zsh" | |
| 136 | + | print -r -- ": > ${(q)ready_file}" >> "$source_dir/plan_build.zsh" | |
| 137 | + | print -r -- "while [[ ! -e ${(q)go_file} ]]; do sleep 0.01; done" >> "$source_dir/plan_build.zsh" | |
| 138 | + | print -r -- 'print -r -- "finished:first"' >> "$source_dir/plan_build.zsh" | |
| 139 | + | print -r -- "concurrent_first standard skill" > "$source_dir/SKILL.md" | |
| 140 | + | print -r -- "concurrent_first architect skill" > "$source_dir/ARCHITECT.md" | |
| 141 | + | (plan_build one > "$first_output" 2>&1) & | |
| 142 | + | first_pid=$! | |
| 143 | + | for attempt in {1..500}; do | |
| 144 | + | [[ -e "$ready_file" ]] && break | |
| 145 | + | sleep 0.01 | |
| 146 | + | done | |
| 147 | + | [[ -e "$ready_file" ]] || fail "first concurrent call reached canonical execution" | |
| 148 | + | write_bundle concurrent_second | |
| 149 | + | run_plan_build two | |
| 150 | + | assert_equal 0 "$rc" "second concurrent status" | |
| 151 | + | assert_contains "$output" "concurrent_second:two" "second concurrent generation" | |
| 152 | + | : > "$go_file" | |
| 153 | + | wait "$first_pid" || fail "first concurrent status" | |
| 154 | + | first_text="$(<"$first_output")" | |
| 155 | + | assert_contains "$first_text" "concurrent_first:one" "first call retains selected release" | |
| 156 | + | assert_contains "$first_text" "finished:first" "first immutable script finishes" | |
| 157 | + | assert_bundle_consistent "concurrent final current" | |
| 158 | + | assert_skill_links "concurrent final links" | |
| 159 | + | ||
| 160 | + | # Cancellation while refreshing must clean staging and never execute canonical code. | |
| 161 | + | blocking_curl="$fixture_dir/blocking-curl" | |
| 162 | + | cancel_started="$fixture_dir/cancel.started" | |
| 163 | + | cancel_executed="$fixture_dir/cancel.executed" | |
| 164 | + | write_bundle cancellation-marker 0 "$cancel_executed" | |
| 165 | + | run_plan_build activate-cancellation-marker | |
| 166 | + | assert_equal 0 "$rc" "cancellation marker bundle activation" | |
| 167 | + | rm -f "$cancel_executed" | |
| 168 | + | { | |
| 169 | + | print -r -- '#!/bin/sh' | |
| 170 | + | print -r -- "touch ${(q)cancel_started}" | |
| 171 | + | print -r -- 'while :; do sleep 1; done' | |
| 172 | + | } > "$blocking_curl" | |
| 173 | + | chmod +x "$blocking_curl" | |
| 174 | + | export PLAN_BUILD_CURL_COMMAND="$blocking_curl" | |
| 175 | + | (plan_build cancelled > "$fixture_dir/cancel.out" 2>&1; cancel_rc=$?; print -r -- "$cancel_rc" > "$fixture_dir/cancel.rc"; exit "$cancel_rc") & | |
| 176 | + | cancel_pid=$! | |
| 177 | + | for attempt in {1..500}; do | |
| 178 | + | [[ -e "$cancel_started" ]] && break | |
| 179 | + | sleep 0.01 | |
| 180 | + | done | |
| 181 | + | kill -TERM "$cancel_pid" | |
| 182 | + | wait "$cancel_pid" | |
| 183 | + | cancel_wait_rc=$? | |
| 184 | + | cancel_recorded_rc="" | |
| 185 | + | [[ -s "$fixture_dir/cancel.rc" ]] && cancel_recorded_rc="$(<"$fixture_dir/cancel.rc")" | |
| 186 | + | [[ "$cancel_wait_rc" = 143 || "$cancel_recorded_rc" = 143 ]] || | |
| 187 | + | fail "TERM returns conventional status 143" | |
| 188 | + | [[ ! -e "$cancel_executed" ]] || fail "TERM does not execute canonical plan-build" | |
| 189 | + | unset PLAN_BUILD_CURL_COMMAND | |
| 190 | + | ||
| 191 | + | # A pre-existing lock file must not be mistaken for an active kernel lock. | |
| 192 | + | print -r -- "stale contents" > "$PLAN_BUILD_CACHE_DIR/.activate.lock" | |
| 193 | + | write_bundle stale-lock-recovery | |
| 194 | + | run_plan_build recovered | |
| 195 | + | assert_equal 0 "$rc" "stale activation lock recovery status" | |
| 196 | + | assert_contains "$output" "stale-lock-recovery:recovered" "stale activation lock recovery execution" | |
| 197 | + | ||
| 198 | + | # Cancellation while canonical code runs must terminate the child promptly. | |
| 199 | + | canonical_started="$fixture_dir/canonical.started" | |
| 200 | + | canonical_finished="$fixture_dir/canonical.finished" | |
| 201 | + | print -r -- '#!/usr/bin/env zsh' > "$source_dir/plan_build.zsh" | |
| 202 | + | print -r -- '# generation: canonical-cancel' >> "$source_dir/plan_build.zsh" | |
| 203 | + | print -r -- "trap 'exit 143' TERM" >> "$source_dir/plan_build.zsh" | |
| 204 | + | print -r -- ": > ${(q)canonical_started}" >> "$source_dir/plan_build.zsh" | |
| 205 | + | print -r -- 'while :; do sleep 1; done' >> "$source_dir/plan_build.zsh" | |
| 206 | + | print -r -- ": > ${(q)canonical_finished}" >> "$source_dir/plan_build.zsh" | |
| 207 | + | print -r -- "canonical-cancel standard skill" > "$source_dir/SKILL.md" | |
| 208 | + | print -r -- "canonical-cancel architect skill" > "$source_dir/ARCHITECT.md" | |
| 209 | + | (plan_build canonical-cancel > "$fixture_dir/canonical-cancel.out" 2>&1; print -r -- "$?" > "$fixture_dir/canonical-cancel.rc") & | |
| 210 | + | canonical_pid=$! | |
| 211 | + | for attempt in {1..500}; do | |
| 212 | + | [[ -e "$canonical_started" ]] && break | |
| 213 | + | sleep 0.01 | |
| 214 | + | done | |
| 215 | + | [[ -e "$canonical_started" ]] || fail "canonical cancellation reached execution" | |
| 216 | + | kill -TERM "$canonical_pid" | |
| 217 | + | wait "$canonical_pid" | |
| 218 | + | assert_equal 143 "$(<"$fixture_dir/canonical-cancel.rc")" "canonical cancellation status" | |
| 219 | + | [[ ! -e "$canonical_finished" ]] || fail "canonical child continued after TERM" | |
| 220 | + | ||
| 221 | + | temp_count="$(command find "$PLAN_BUILD_CACHE_DIR" -maxdepth 1 \ | |
| 222 | + | \( -name '.stage.*' -o -name '.current.*' \) -print | command wc -l | command tr -d ' ')" | |
| 223 | + | assert_equal 0 "$temp_count" "cache staging and temporary links cleaned" | |
| 224 | + | skill_temp_count="$(command find "$PLAN_BUILD_SKILLS_DIR" \ | |
| 225 | + | \( -name '*.link.*' -o -name '*.backup.*' \) -print | command wc -l | command tr -d ' ')" | |
| 226 | + | assert_equal 0 "$skill_temp_count" "skill temporary links and backups cleaned" | |
| 227 | + | ||
| 228 | + | if (( failures )); then | |
| 166 | 229 | exit 1 | |
| 167 | 230 | fi | |
| 168 | 231 | ||
| 169 | - | print -- "PASS: plan_build tests" | |
| 232 | + | print -- "PASS: plan_build launcher tests" | |
Vernon Wee Hong KOH ревизий этого фрагмента 3 weeks ago. К ревизии
8 files changed, 1377 insertions, 45 deletions
ADR.md(файл создан)
| @@ -0,0 +1,64 @@ | |||
| 1 | + | # Architecture Decision Records | |
| 2 | + | ||
| 3 | + | ## ADR-001: Documentation-First Architect Mode | |
| 4 | + | ||
| 5 | + | **Status:** Accepted | |
| 6 | + | ||
| 7 | + | **Date:** 2026-07-28 | |
| 8 | + | ||
| 9 | + | ### Context | |
| 10 | + | ||
| 11 | + | The existing `plan_build` workflow makes Claude Code the implementation orchestrator but does not enforce durable specifications, atomic Codex task prompts, client handover documentation, or a strict separation between documentation and code execution. | |
| 12 | + | ||
| 13 | + | ### Decision | |
| 14 | + | ||
| 15 | + | Add an opt-in built-in `--architect` mode. Claude Code owns discovery, architecture, documentation, dispatch, and verification. Codex is the sole code and test-code executor. CodeRabbit reviews every task and the final aggregate diff. Tasks execute sequentially, and all approved work is committed once after final verification and explicit user approval. | |
| 16 | + | ||
| 17 | + | ### Alternatives Considered | |
| 18 | + | ||
| 19 | + | - Replace the default workflow: rejected because direct implementation remains useful. | |
| 20 | + | - Keep Claude as an implementation fallback: rejected because it weakens the requested role boundary. | |
| 21 | + | - Execute tasks in parallel: rejected because sequential execution provides clearer scope, review, and failure attribution. | |
| 22 | + | ||
| 23 | + | ### Consequences | |
| 24 | + | ||
| 25 | + | - Architect mode requires an interactive terminal and additional workflow state documents. | |
| 26 | + | - Long-running work can resume from repository records rather than chat history. | |
| 27 | + | - Delivery takes more approval steps but produces a complete auditable handover package. | |
| 28 | + | ||
| 29 | + | ### Affected Components | |
| 30 | + | ||
| 31 | + | - `func` | |
| 32 | + | - `test_plan_build.zsh` | |
| 33 | + | - `architect-workflow.md` | |
| 34 | + | - Installer scripts addressed by `TASK-003` | |
| 35 | + | ||
| 36 | + | ## ADR-002: Remove the Standalone v2 Integration | |
| 37 | + | ||
| 38 | + | **Status:** Accepted | |
| 39 | + | ||
| 40 | + | **Date:** 2026-07-28 | |
| 41 | + | ||
| 42 | + | ### Context | |
| 43 | + | ||
| 44 | + | The built-in `--v2` path downloads a standalone script from an unavailable endpoint. Retaining the path exposes a broken user interface and creates a second workflow source that can drift. | |
| 45 | + | ||
| 46 | + | ### Decision | |
| 47 | + | ||
| 48 | + | Remove the v2 downloader, parser branch, passthrough behavior, usage text, and documentation. `--v2` now follows the normal unknown-argument path. | |
| 49 | + | ||
| 50 | + | ### Alternatives Considered | |
| 51 | + | ||
| 52 | + | - Repair or recreate the standalone gist: rejected because v2 is no longer required. | |
| 53 | + | - Preserve the broken option as undocumented behavior: rejected because it would remain a misleading public contract. | |
| 54 | + | ||
| 55 | + | ### Consequences | |
| 56 | + | ||
| 57 | + | - `--grill` and `--distribute` are no longer reachable through `plan_build`. | |
| 58 | + | - The built-in command has one maintained implementation path. | |
| 59 | + | ||
| 60 | + | ### Affected Components | |
| 61 | + | ||
| 62 | + | - `func` | |
| 63 | + | - `test_plan_build.zsh` | |
| 64 | + | - `README.md` | |
CHANGELOG.md(файл создан)
| @@ -0,0 +1,22 @@ | |||
| 1 | + | # Changelog | |
| 2 | + | ||
| 3 | + | All notable changes to this project are documented in this file. | |
| 4 | + | ||
| 5 | + | ## Unreleased | |
| 6 | + | ||
| 7 | + | ### Added | |
| 8 | + | ||
| 9 | + | - `TASK-002`: Added built-in `plan_build --architect` with safe-resume, new-workflow, yolo, preflight, and command-level regression coverage. | |
| 10 | + | - Added the canonical documentation-first architect workflow source. | |
| 11 | + | ||
| 12 | + | ### Changed | |
| 13 | + | ||
| 14 | + | - Documented architect mode prerequisites and supported flag combinations. | |
| 15 | + | ||
| 16 | + | ### Removed | |
| 17 | + | ||
| 18 | + | - `TASK-001`: Removed the obsolete standalone v2 downloader, forwarding behavior, and public usage contract. | |
| 19 | + | ||
| 20 | + | ### Fixed | |
| 21 | + | ||
| 22 | + | - `TASK-002`: Reject bare Git repositories during architect preflight while accepting normal worktrees. | |
README.md
| @@ -35,22 +35,27 @@ Starship owns the prompt and loads after Oh My Zsh. The managed Starship config | |||
| 35 | 35 | ||
| 36 | 36 | `plan_build` launches Claude Code as the implementation orchestrator, with Codex and CodeRabbit as independent reviewers. The configuration installer also installs its workflow at `~/.claude/skills/plan-build/SKILL.md`. | |
| 37 | 37 | ||
| 38 | + | Architect mode keeps Claude focused on architecture and documentation while Codex implements one approved task at a time and CodeRabbit reviews each task. It uses `~/.claude/skills/plan-build-architect/SKILL.md`. | |
| 39 | + | ||
| 38 | 40 | ```zsh | |
| 39 | 41 | plan_build # Standard plan and build | |
| 40 | 42 | plan_build --prompt # Enhance the payload with Auggie first | |
| 41 | 43 | plan_build --writing-plan # Superpowers implementation plan, Codex review, then build | |
| 42 | 44 | plan_build --prompt --brainstorm # Auggie, Superpowers design and plan, Codex review, then build | |
| 43 | 45 | plan_build --yolo --writing-plan # Pass --yolo through to Claude Code | |
| 44 | - | plan_build --v2 --grill # Run the standalone v2 script (adds --grill and --distribute) | |
| 45 | - | plan_build --v2 --distribute # v2 distributed mode: Codex implements BE, Kimi Code implements FE | |
| 46 | + | plan_build --architect # Documentation-first architecture workflow | |
| 47 | + | plan_build --architect --new # Archive existing planning state and start a new workflow | |
| 48 | + | plan_build --architect --yolo # Forward --yolo without bypassing workflow approval gates | |
| 46 | 49 | ``` | |
| 47 | 50 | ||
| 48 | 51 | `--brainstorm` and `--writing-plan` are mutually exclusive. They require the enabled `superpowers@claude-plugins-official` Claude Code plugin; `plan_build` reports the install or enable command and exits before Auggie when the requirement is not met. | |
| 49 | 52 | ||
| 50 | - | `--v2` downloads and runs the standalone [plan_build v2 script](https://opengist.resetrix.work/weehong/plan-build) on demand, forwarding every other argument to it. v2 adds the `--grill` planning mode (`mattpocock-skills:grilling`) and `--distribute` (backend items implemented by Codex, frontend items by Kimi Code, sequentially, after the FE/BE split is confirmed). `--distribute` additionally requires the `kimi` CLI. Without `--v2`, `plan_build` runs the built-in v1 function unchanged. | |
| 53 | + | `--architect` may combine only with `--new` and `--yolo`. It requires an interactive terminal, a Git worktree, Claude Code, Codex, CodeRabbit, Git, and the installed architect skill. The obsolete `--v2` integration has been removed. | |
| 51 | 54 | ||
| 52 | 55 | On a machine without this full setup (`config.sh` normally installs the skill), install just the plan-build skill with: | |
| 53 | 56 | ||
| 54 | 57 | ```zsh | |
| 55 | - | mkdir -p ~/.claude/skills/plan-build && curl -fsSL https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md -o ~/.claude/skills/plan-build/SKILL.md | |
| 58 | + | mkdir -p ~/.claude/skills/plan-build ~/.claude/skills/plan-build-architect | |
| 59 | + | curl -fsSL https://opengist.resetrix.work/weehong/f0d940c3c1214bf5b7996195199fdc09/raw/HEAD/orchestrate-loop.md -o ~/.claude/skills/plan-build/SKILL.md | |
| 60 | + | curl -fsSL https://opengist.resetrix.work/weehong/f0d940c3c1214bf5b7996195199fdc09/raw/HEAD/architect-workflow.md -o ~/.claude/skills/plan-build-architect/SKILL.md | |
| 56 | 61 | ``` | |
SPEC.md(файл создан)
| @@ -0,0 +1,500 @@ | |||
| 1 | + | # Plan Build Architect Mode Specification | |
| 2 | + | ||
| 3 | + | ## 1. Executive Summary & Goals | |
| 4 | + | ||
| 5 | + | ### Problem Statement | |
| 6 | + | ||
| 7 | + | The existing `plan_build` command asks Claude Code to plan and implement a task through an eight-step multi-agent workflow. It does not provide a documentation-first delivery mode in which Claude acts strictly as architect and documentation manager while OpenAI Codex performs all implementation work. | |
| 8 | + | ||
| 9 | + | This creates three handover risks: | |
| 10 | + | ||
| 11 | + | 1. Requirements and architecture decisions can remain implicit in agent conversations. | |
| 12 | + | 2. Implementation tasks may not have durable, atomic scopes and acceptance criteria. | |
| 13 | + | 3. The final repository may lack the user, operational, API, deployment, security, and acceptance documentation required for a client handover. | |
| 14 | + | ||
| 15 | + | ### Solution | |
| 16 | + | ||
| 17 | + | Add an optional built-in `plan_build --architect` mode. In this mode, Claude Code owns discovery, specifications, task decomposition, review orchestration, progress records, and final handover documentation. Codex is the sole implementation executor. CodeRabbit reviews every completed task and the final aggregate diff. | |
| 18 | + | ||
| 19 | + | Architect mode follows three gated phases: | |
| 20 | + | ||
| 21 | + | 1. **Discovery and Architecture:** Claude interviews the user one question at a time and recommends a default answer for each decision. | |
| 22 | + | 2. **Documentation Synthesis:** After an explicit phase-completion phrase, Claude writes the approved requirements into `SPEC.md` without asking additional questions. | |
| 23 | + | 3. **Codex Execution Plan:** After specification approval, Claude writes atomic sequential task briefs and self-contained Codex prompts into `TASKS.md`. | |
| 24 | + | ||
| 25 | + | Codex tasks execute only after `TASKS.md` approval. Exactly one task may be active at a time. All implementation and documentation changes remain uncommitted until the complete workflow, reviews, tests, and client handover package pass final verification. The user must approve the single final commit. The workflow never pushes automatically. | |
| 26 | + | ||
| 27 | + | ### Goals | |
| 28 | + | ||
| 29 | + | - Preserve the existing default `plan_build` behavior. | |
| 30 | + | - Add `--architect` as an explicit opt-in mode. | |
| 31 | + | - Remove the obsolete and broken `--v2` integration from the built-in command. | |
| 32 | + | - Keep Claude from writing implementation or test code in architect mode. | |
| 33 | + | - Make Codex tasks atomic, sequential, auditable, and constrained by file scope. | |
| 34 | + | - Require explicit approval at every phase and execution boundary. | |
| 35 | + | - Require CodeRabbit review after every task and over the final combined diff. | |
| 36 | + | - Produce complete internal engineering records and client-facing handover documentation. | |
| 37 | + | - Resume interrupted architect workflows safely. | |
| 38 | + | - Preserve existing project documentation and user work. | |
| 39 | + | - Produce one user-approved commit only after all tasks are complete. | |
| 40 | + | ||
| 41 | + | ### Non-Goals | |
| 42 | + | ||
| 43 | + | - Replacing the existing standard, brainstorm, writing-plan, prompt-enhancement, or yolo workflows. | |
| 44 | + | - Allowing unattended architect execution. | |
| 45 | + | - Allowing Claude to implement application or test code. | |
| 46 | + | - Automatically pushing the final commit. | |
| 47 | + | - Inventing project behavior, infrastructure, controls, or APIs that do not exist. | |
| 48 | + | ||
| 49 | + | ## 2. User Stories | |
| 50 | + | ||
| 51 | + | 1. As a project owner, I want Claude to interview me one question at a time, so that architectural decisions remain understandable and deliberate. | |
| 52 | + | 2. As a project owner, I want each question to include a recommended default, so that discovery can proceed efficiently. | |
| 53 | + | 3. As a project owner, I want explicit phase gates, so that no specification or implementation begins before I approve it. | |
| 54 | + | 4. As a project owner, I want a cohesive `SPEC.md`, so that requirements and contracts have one approved baseline. | |
| 55 | + | 5. As a project owner, I want atomic Codex prompts in `TASKS.md`, so that implementation work has clear boundaries. | |
| 56 | + | 6. As a project owner, I want only one Codex task active at a time, so that failures and diffs remain attributable. | |
| 57 | + | 7. As a project owner, I want Claude to inspect but not implement code, so that architecture and execution responsibilities remain separated. | |
| 58 | + | 8. As a project owner, I want CodeRabbit to review every task, so that defects are found before dependent work begins. | |
| 59 | + | 9. As a project owner, I want one final holistic review, so that cross-task regressions are detected. | |
| 60 | + | 10. As a project owner, I want all work committed once at the end, so that the complete delivery appears as one coherent change. | |
| 61 | + | 11. As a project owner, I want interrupted sessions to resume from durable records, so that long projects do not lose state. | |
| 62 | + | 12. As a client, I want user and operational documentation, so that I can adopt and run the delivered system. | |
| 63 | + | 13. As a client, I want deployment and rollback instructions, so that releases can be managed safely. | |
| 64 | + | 14. As a client, I want security and ownership documentation, so that operational responsibilities are explicit. | |
| 65 | + | 15. As a client, I want a formal acceptance checklist, so that handover completion is objectively verifiable. | |
| 66 | + | 16. As an engineer, I want approved specification changes recorded, so that implementation does not silently drift from requirements. | |
| 67 | + | 17. As an engineer, I want file-scope enforcement, so that Codex cannot introduce unrelated changes. | |
| 68 | + | 18. As an engineer, I want focused tests per task and full verification at completion, so that failures are localized without sacrificing system confidence. | |
| 69 | + | 19. As an operator, I want documentation claims tied to source files and verified commands, so that instructions can be trusted. | |
| 70 | + | 20. As a security reviewer, I want secrets excluded from prompts and documents, so that the workflow does not leak credentials. | |
| 71 | + | ||
| 72 | + | ## 3. System Architecture & Tech Stack | |
| 73 | + | ||
| 74 | + | ### Existing Context | |
| 75 | + | ||
| 76 | + | The feature extends a Zsh function-based command distributed through the Zsh Setup OpenGist. The current command launches Claude Code with an installed workflow document. Existing behavior is covered by a Zsh test script that stubs external CLIs and asserts command-level output and argument contracts. | |
| 77 | + | ||
| 78 | + | ### Runtime Components | |
| 79 | + | ||
| 80 | + | | Component | Responsibility in architect mode | | |
| 81 | + | | --- | --- | | |
| 82 | + | | `plan_build` Zsh function | Parse flags, reject incompatible combinations, run preflight, collect the initial payload, and launch Claude with the architect workflow. | | |
| 83 | + | | Claude Code | Lead architect, documentation manager, task dispatcher, scope verifier, review triager, and phase-gate controller. | | |
| 84 | + | | OpenAI Codex CLI | Sole application and test-code executor, invoked non-interactively for one approved task at a time. | | |
| 85 | + | | CodeRabbit CLI | Automated reviewer after every task and over the final aggregate diff. | | |
| 86 | + | | Git | Baseline detection, diff isolation, traceability, and one final user-approved commit. | | |
| 87 | + | | Markdown files | Durable workflow state, approved requirements, decisions, execution records, and client handover package. | | |
| 88 | + | ||
| 89 | + | ### Canonical Workflow Source | |
| 90 | + | ||
| 91 | + | Architect mode must have one canonical workflow document in the Zsh Setup gist. The configuration installer and all supported platform installers distribute that same document to: | |
| 92 | + | ||
| 93 | + | `~/.claude/skills/plan-build-architect/SKILL.md` | |
| 94 | + | ||
| 95 | + | The active local installation and published OpenGist source must remain identical after rollout. | |
| 96 | + | ||
| 97 | + | ### Execution Topology | |
| 98 | + | ||
| 99 | + | ```mermaid | |
| 100 | + | flowchart TD | |
| 101 | + | U[Project Owner] -->|Initial payload| PB[plan_build --architect] | |
| 102 | + | PB -->|Preflight and architect prompt| C[Claude Code] | |
| 103 | + | C -->|One question at a time| U | |
| 104 | + | U -->|Explicit phase approvals| C | |
| 105 | + | C -->|Writes and maintains| D[Engineering and handover Markdown] | |
| 106 | + | C -->|One approved task prompt| X[Codex CLI] | |
| 107 | + | X -->|Scoped code and tests| W[Shared Git worktree] | |
| 108 | + | C -->|Inspect diff and verify| W | |
| 109 | + | C -->|Review request| R[CodeRabbit CLI] | |
| 110 | + | R -->|Findings| C | |
| 111 | + | C -->|Valid fixes delegated| X | |
| 112 | + | C -->|Task and final approval requests| U | |
| 113 | + | U -->|Final commit approval| C | |
| 114 | + | C -->|One commit, no push| G[Git history] | |
| 115 | + | ``` | |
| 116 | + | ||
| 117 | + | ### Responsibility Boundary | |
| 118 | + | ||
| 119 | + | Claude may inspect every project file but may create or modify only documentation and orchestration records during architect execution: | |
| 120 | + | ||
| 121 | + | - `SPEC.md` | |
| 122 | + | - `TASKS.md` | |
| 123 | + | - `ADR.md` | |
| 124 | + | - `CHANGELOG.md` | |
| 125 | + | - `README.md` | |
| 126 | + | - Files under `docs/` that form the client handover package | |
| 127 | + | ||
| 128 | + | Codex owns all application code, configuration code, migrations, generated source, and test-code modifications. If a required change falls outside an approved task scope, Codex stops and reports the required expansion rather than modifying the file. | |
| 129 | + | ||
| 130 | + | ### Interactive Constraint | |
| 131 | + | ||
| 132 | + | Architect mode requires a usable interactive terminal. It must fail before modifying project files when a TTY is unavailable. This protects all mandatory approval gates. | |
| 133 | + | ||
| 134 | + | ## 4. Data Models & Schemas | |
| 135 | + | ||
| 136 | + | Architect mode introduces no application database schema. Its durable state is represented by structured Markdown documents. | |
| 137 | + | ||
| 138 | + | ### Project Metadata | |
| 139 | + | ||
| 140 | + | Discovery must collect: | |
| 141 | + | ||
| 142 | + | - Project name | |
| 143 | + | - Client or owning organization | |
| 144 | + | - Product purpose | |
| 145 | + | - Target users | |
| 146 | + | - Repository scope | |
| 147 | + | - Supported environments | |
| 148 | + | - Deployment owner | |
| 149 | + | - Operational owner | |
| 150 | + | - Support contact role | |
| 151 | + | - Compliance constraints | |
| 152 | + | - Intended handover date | |
| 153 | + | ||
| 154 | + | Sensitive identities may use user-approved placeholders. | |
| 155 | + | ||
| 156 | + | ### Task Record | |
| 157 | + | ||
| 158 | + | Every `TASKS.md` task must contain: | |
| 159 | + | ||
| 160 | + | | Field | Requirement | | |
| 161 | + | | --- | --- | | |
| 162 | + | | ID | Stable sequential identifier such as `TASK-001`. | | |
| 163 | + | | Title | Concise implementation outcome. | | |
| 164 | + | | Status | One of `Pending`, `In Progress`, `Blocked`, `Review`, or `Complete`. | | |
| 165 | + | | Dependencies | IDs that must be complete first, or `None`. | | |
| 166 | + | | Objective | Exact feature, behavior, or function Codex must implement. | | |
| 167 | + | | Allowed File Scope | Exhaustive files or bounded path patterns Codex may create or modify. | | |
| 168 | + | | Context / Interfaces | Approved schemas, contracts, imports, conventions, and relevant existing behavior. | | |
| 169 | + | | Prompt for Codex | Self-contained non-interactive execution prompt. | | |
| 170 | + | | Acceptance Criteria | Observable behavior and required test coverage. | | |
| 171 | + | | Verification Commands | Focused lint, type-check, unit, integration, or build commands. | | |
| 172 | + | | CodeRabbit Outcome | Findings, triage result, and rerun status. | | |
| 173 | + | | Completion Evidence | Commands run, results, and relevant diff evidence. | | |
| 174 | + | ||
| 175 | + | Only one task may have `In Progress` status. | |
| 176 | + | ||
| 177 | + | ### Task State Transitions | |
| 178 | + | ||
| 179 | + | ```mermaid | |
| 180 | + | stateDiagram-v2 | |
| 181 | + | [*] --> Pending | |
| 182 | + | Pending --> InProgress: approved and dependencies complete | |
| 183 | + | InProgress --> Review: Codex reports completion | |
| 184 | + | InProgress --> Blocked: execution or scope blocker | |
| 185 | + | Review --> InProgress: valid findings require fixes | |
| 186 | + | Review --> Complete: acceptance and review pass | |
| 187 | + | Blocked --> Pending: user approves revised scope or architecture | |
| 188 | + | Complete --> [*] | |
| 189 | + | ``` | |
| 190 | + | ||
| 191 | + | ### Architecture Decision Record | |
| 192 | + | ||
| 193 | + | `ADR.md` is append-only. Every decision uses a stable ID such as `ADR-001` and records: | |
| 194 | + | ||
| 195 | + | - Status | |
| 196 | + | - Date | |
| 197 | + | - Context | |
| 198 | + | - Decision | |
| 199 | + | - Alternatives considered | |
| 200 | + | - Consequences | |
| 201 | + | - Affected files or components | |
| 202 | + | - Superseding ADR, when applicable | |
| 203 | + | ||
| 204 | + | Superseded decisions remain visible. | |
| 205 | + | ||
| 206 | + | ### Changelog | |
| 207 | + | ||
| 208 | + | `CHANGELOG.md` follows Keep a Changelog conventions. Work remains under `Unreleased` until the final delivery and is grouped under: | |
| 209 | + | ||
| 210 | + | - Added | |
| 211 | + | - Changed | |
| 212 | + | - Fixed | |
| 213 | + | - Security | |
| 214 | + | - Deprecated | |
| 215 | + | - Removed | |
| 216 | + | ||
| 217 | + | Entries reference task IDs. Detailed execution evidence remains in `TASKS.md`. | |
| 218 | + | ||
| 219 | + | ### Mandatory Handover Package | |
| 220 | + | ||
| 221 | + | The following files are mandatory without exception: | |
| 222 | + | ||
| 223 | + | | File | Audience and purpose | | |
| 224 | + | | --- | --- | | |
| 225 | + | | `README.md` | Product overview, prerequisites, quick start, and configuration. | | |
| 226 | + | | `SPEC.md` | Approved requirements, architecture, schemas, contracts, constraints, and acceptance baseline. | | |
| 227 | + | | `TASKS.md` | Internal task execution and evidence record. | | |
| 228 | + | | `ADR.md` | Internal architecture decision history. | | |
| 229 | + | | `CHANGELOG.md` | Delivery and release history. | | |
| 230 | + | | `docs/USER_MANUAL.md` | End-user workflows and expected outcomes. | | |
| 231 | + | | `docs/RUNBOOK.md` | Operations, monitoring, backup, recovery, and troubleshooting. | | |
| 232 | + | | `docs/API.md` | Authentication, endpoints or commands, examples, and errors. | | |
| 233 | + | | `docs/DEPLOYMENT.md` | Environments, infrastructure, release, rollback, and validation. | | |
| 234 | + | | `docs/SECURITY.md` | Access control, secret handling, data protection, rotation, and known risks. | | |
| 235 | + | | `docs/HANDOVER.md` | Deliverables, ownership, support boundaries, limitations, and formal acceptance. | | |
| 236 | + | ||
| 237 | + | Non-applicable material must be marked `Not Applicable` with a factual rationale. Files may not be omitted. | |
| 238 | + | ||
| 239 | + | ## 5. CLI & Component Contracts | |
| 240 | + | ||
| 241 | + | ### Supported Invocation | |
| 242 | + | ||
| 243 | + | `plan_build --architect` | |
| 244 | + | ||
| 245 | + | Optional architect flags: | |
| 246 | + | ||
| 247 | + | - `--new`: Start a new architect workflow after archiving existing workflow documents. | |
| 248 | + | - `--yolo`: Forward Claude's permissive execution mode but never bypass architect approval gates. | |
| 249 | + | ||
| 250 | + | ### Incompatible Flags | |
| 251 | + | ||
| 252 | + | Architect mode must reject combinations with: | |
| 253 | + | ||
| 254 | + | - `--brainstorm` | |
| 255 | + | - `--writing-plan` | |
| 256 | + | - `--prompt` | |
| 257 | + | ||
| 258 | + | The `--v2` option, its downloader function, and its usage documentation must be removed entirely. After removal, passing `--v2` follows the normal unknown-argument error path. The built-in workflow does not expose the former v2-only `--grill` or `--distribute` concepts. | |
| 259 | + | ||
| 260 | + | ### Preflight Contract | |
| 261 | + | ||
| 262 | + | Before discovery or file modification, architect mode verifies: | |
| 263 | + | ||
| 264 | + | - Interactive TTY | |
| 265 | + | - Git repository context | |
| 266 | + | - `claude` | |
| 267 | + | - `codex` | |
| 268 | + | - `coderabbit` | |
| 269 | + | - `git` | |
| 270 | + | - Installed architect workflow document | |
| 271 | + | ||
| 272 | + | A missing requirement causes a non-zero exit with exact remediation guidance. Project-specific tools are checked when their approved tasks require them. | |
| 273 | + | ||
| 274 | + | ### Phase-Gate Contract | |
| 275 | + | ||
| 276 | + | #### Phase 1 to Phase 2 | |
| 277 | + | ||
| 278 | + | Claude may leave discovery only after the user states either: | |
| 279 | + | ||
| 280 | + | - `I am ready to generate the spec` | |
| 281 | + | - `Phase 1 complete` | |
| 282 | + | ||
| 283 | + | Claude asks one question at a time and includes one recommended default with every question. | |
| 284 | + | ||
| 285 | + | #### Phase 2 to Phase 3 | |
| 286 | + | ||
| 287 | + | Claude writes `SPEC.md` without asking more questions. It waits for explicit specification approval before creating `TASKS.md`. | |
| 288 | + | ||
| 289 | + | #### Phase 3 to Execution | |
| 290 | + | ||
| 291 | + | Claude writes `TASKS.md` and waits for explicit task-plan approval before invoking Codex. | |
| 292 | + | ||
| 293 | + | #### Between Tasks | |
| 294 | + | ||
| 295 | + | Claude dispatches one task, verifies scope and acceptance criteria, completes CodeRabbit triage, reports evidence, and waits for user approval before starting the next task. | |
| 296 | + | ||
| 297 | + | #### Final Commit | |
| 298 | + | ||
| 299 | + | Claude presents the final verification results, aggregate diff summary, and proposed commit message. It stages and commits only after explicit user approval. It never pushes. | |
| 300 | + | ||
| 301 | + | ### Codex Invocation Contract | |
| 302 | + | ||
| 303 | + | Claude invokes Codex non-interactively in the current project worktree with workspace-write access. The exact prompt stored in the approved task record is passed to Codex. Every prompt includes: | |
| 304 | + | ||
| 305 | + | - Objective | |
| 306 | + | - Allowed File Scope | |
| 307 | + | - Context / Interfaces | |
| 308 | + | - Acceptance Criteria | |
| 309 | + | - Unit or integration test requirements | |
| 310 | + | - Verification commands | |
| 311 | + | - Prohibition on commits | |
| 312 | + | - Instruction to stop before touching out-of-scope files | |
| 313 | + | ||
| 314 | + | Codex execution output is captured for verification. Claude independently inspects the diff and reruns required commands. | |
| 315 | + | ||
| 316 | + | ### CodeRabbit Contract | |
| 317 | + | ||
| 318 | + | CodeRabbit runs after each Codex task and once over the final combined diff. | |
| 319 | + | ||
| 320 | + | - Claude investigates every concrete finding. | |
| 321 | + | - Valid findings are delegated to Codex within the same task. | |
| 322 | + | - Critical, high, and medium findings block progress until resolved. | |
| 323 | + | - Low-severity findings may be deferred only with user approval. | |
| 324 | + | - Approved deferrals are recorded in `CHANGELOG.md` and `docs/HANDOVER.md`. | |
| 325 | + | - Tests and CodeRabbit rerun after substantive fixes. | |
| 326 | + | ||
| 327 | + | ### Retry Contract | |
| 328 | + | ||
| 329 | + | After the initial Codex attempt, Claude may dispatch at most two focused correction attempts. If acceptance criteria still fail: | |
| 330 | + | ||
| 331 | + | 1. Stop execution. | |
| 332 | + | 2. Mark the task `Blocked`. | |
| 333 | + | 3. Preserve the partial diff. | |
| 334 | + | 4. Record diagnostics and attempted corrections. | |
| 335 | + | 5. Ask the user whether to revise architecture, scope, or acceptance criteria. | |
| 336 | + | 6. Do not start dependent tasks. | |
| 337 | + | ||
| 338 | + | ### Resume Contract | |
| 339 | + | ||
| 340 | + | When workflow documents already exist, Claude: | |
| 341 | + | ||
| 342 | + | 1. Reads `SPEC.md`, `TASKS.md`, `ADR.md`, and `CHANGELOG.md`. | |
| 343 | + | 2. Compares their recorded state with Git and the current worktree. | |
| 344 | + | 3. Identifies the first incomplete task. | |
| 345 | + | 4. Presents the detected state and asks whether to resume. | |
| 346 | + | ||
| 347 | + | `--new` must archive existing workflow documents before creating replacements. It must never overwrite them silently. | |
| 348 | + | ||
| 349 | + | ## 6. Documentation Contracts | |
| 350 | + | ||
| 351 | + | ### Existing Documentation | |
| 352 | + | ||
| 353 | + | Claude updates existing documents in place and preserves valid project-specific content. It creates only missing files. Wholesale replacement is prohibited unless reconciliation proves that no valid content would be lost. | |
| 354 | + | ||
| 355 | + | ### Client-Facing Content | |
| 356 | + | ||
| 357 | + | Client documents describe the delivered system and do not expose Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless contractual or compliance requirements require AI disclosure. | |
| 358 | + | ||
| 359 | + | ### Traceability | |
| 360 | + | ||
| 361 | + | Implementation-specific claims reference relevant source files, configurations, schemas, endpoints, or verified commands. Handover documents include: | |
| 362 | + | ||
| 363 | + | - Software version or final commit SHA | |
| 364 | + | - Generation date | |
| 365 | + | - Document owner | |
| 366 | + | - Last verification date | |
| 367 | + | ||
| 368 | + | ### Diagrams | |
| 369 | + | ||
| 370 | + | Use maintainable Mermaid diagrams for system context, component interactions, deployment topology, and critical operational sequences when applicable. If a diagram is not applicable, state why. | |
| 371 | + | ||
| 372 | + | ### Handover Acceptance | |
| 373 | + | ||
| 374 | + | `docs/HANDOVER.md` includes: | |
| 375 | + | ||
| 376 | + | - Deliverables | |
| 377 | + | - Environment and access prerequisites | |
| 378 | + | - Verified capabilities | |
| 379 | + | - Known limitations | |
| 380 | + | - Approved deferred risks | |
| 381 | + | - Support boundaries | |
| 382 | + | - Warranty assumptions | |
| 383 | + | - Ownership transfer | |
| 384 | + | - Dated client acceptance checklist | |
| 385 | + | - Sign-off placeholders | |
| 386 | + | ||
| 387 | + | ## 7. Edge Cases & Constraints | |
| 388 | + | ||
| 389 | + | ### Existing Dirty Worktree | |
| 390 | + | ||
| 391 | + | Claude records the initial Git status and preserves pre-existing work. It may not revert, overwrite, stage, or include unrelated changes. If approved and pre-existing changes cannot be distinguished safely, execution stops for user direction. | |
| 392 | + | ||
| 393 | + | ### Scope Expansion | |
| 394 | + | ||
| 395 | + | Codex stops when required work exceeds the task's allowed scope. Claude assesses the impact, updates `SPEC.md`, `TASKS.md`, and `ADR.md` as appropriate, and requests approval before redispatch. | |
| 396 | + | ||
| 397 | + | ### Requirement Changes | |
| 398 | + | ||
| 399 | + | Approved `SPEC.md` is the baseline. Later requirements are explicit amendments. Execution pauses while Claude assesses affected tasks and documentation. Architectural amendments require an ADR. No changed task is dispatched without approval. | |
| 400 | + | ||
| 401 | + | ### Missing Test Framework | |
| 402 | + | ||
| 403 | + | The first applicable task establishes the smallest project-appropriate test and validation setup. If automated testing is technically impossible, Claude obtains approval for explicit manual acceptance steps and records the risk in `docs/HANDOVER.md`. | |
| 404 | + | ||
| 405 | + | ### Secrets and Sensitive Data | |
| 406 | + | ||
| 407 | + | Prompts and documents never contain credential values, tokens, private keys, personal data, or production secrets. They may document secret names, environment variables, storage systems, ownership, and rotation procedures. Available secret scanning runs before final commit, and suspected credentials block completion. | |
| 408 | + | ||
| 409 | + | ### Non-Applicable Documentation | |
| 410 | + | ||
| 411 | + | Mandatory documents remain present and mark irrelevant sections as `Not Applicable` with rationale. The workflow never fabricates content to fill a template. | |
| 412 | + | ||
| 413 | + | ### Single Commit | |
| 414 | + | ||
| 415 | + | No task-level commits are created. All approved implementation, tests, engineering records, and client documents remain in the worktree until every task is complete and final verification passes. The final commit includes only approved files. | |
| 416 | + | ||
| 417 | + | ### Interrupted Sessions | |
| 418 | + | ||
| 419 | + | Durable task states and evidence, not chat history, determine resume position. Claude must validate recorded state against actual files and Git before continuing. | |
| 420 | + | ||
| 421 | + | ## 8. Testing & Acceptance Strategy | |
| 422 | + | ||
| 423 | + | ### Primary Test Seam | |
| 424 | + | ||
| 425 | + | The highest existing seam is command-level testing of the sourced Zsh function with external CLI stubs. Extend this seam rather than testing private parser details independently. | |
| 426 | + | ||
| 427 | + | ### Required Workflow Tests | |
| 428 | + | ||
| 429 | + | - `--architect` produces the expected Claude invocation and architect workflow instruction. | |
| 430 | + | - `--architect --new` is accepted. | |
| 431 | + | - `--architect --yolo` forwards yolo behavior while preserving the architect instruction. | |
| 432 | + | - `--architect` rejects every incompatible flag combination. | |
| 433 | + | - Duplicate architect flags fail with usage guidance. | |
| 434 | + | - Missing TTY fails before workflow modification. | |
| 435 | + | - Missing required CLI or skill fails with remediation guidance. | |
| 436 | + | - Existing non-architect modes retain their current observable behavior. | |
| 437 | + | - `--v2` is rejected as an unknown argument and no v2 downloader remains. | |
| 438 | + | - Existing non-v2 modes retain their current observable behavior after v2 removal. | |
| 439 | + | ||
| 440 | + | ### Per-Task Verification | |
| 441 | + | ||
| 442 | + | Every Codex task includes focused unit or integration tests and relevant lint, type-check, build, and test commands. Claude reruns them independently before CodeRabbit review is considered complete. | |
| 443 | + | ||
| 444 | + | ### Final Verification | |
| 445 | + | ||
| 446 | + | Before requesting commit approval, Claude verifies: | |
| 447 | + | ||
| 448 | + | - Every task is `Complete`. | |
| 449 | + | - No task has unresolved blocking review findings. | |
| 450 | + | - The complete project lint, type-check, build, and test suite passes. | |
| 451 | + | - The aggregate diff contains only approved changes. | |
| 452 | + | - Required documentation files and sections exist. | |
| 453 | + | - Markdown structure and internal links are valid. | |
| 454 | + | - Referenced source paths and commands exist and are accurate. | |
| 455 | + | - Endpoint and command examples match implementation. | |
| 456 | + | - Mermaid syntax is validated where tooling is available. | |
| 457 | + | - No unresolved `TODO`, placeholder, or template text remains. | |
| 458 | + | - Approved known limitations are recorded in `docs/HANDOVER.md`. | |
| 459 | + | - Available secret scanning reports no suspected credentials. | |
| 460 | + | - Handover documents match the final implementation. | |
| 461 | + | ||
| 462 | + | ## 9. Implementation Decisions | |
| 463 | + | ||
| 464 | + | - Architect mode is opt-in and does not replace existing `plan_build` modes. | |
| 465 | + | - Architect mode is implemented only for the built-in workflow. | |
| 466 | + | - The obsolete `_plan_build_v2` downloader, `--v2` parser branch, passthrough logic, usage text, README examples, and standalone-install references are removed. | |
| 467 | + | - Claude is the architect and documentation manager, not an implementation agent. | |
| 468 | + | - Codex is the sole implementation and test-code executor. | |
| 469 | + | - CodeRabbit is mandatory for task and final reviews. | |
| 470 | + | - Execution is sequential with one active task. | |
| 471 | + | - User approval is mandatory at phase, task, deferral, and commit boundaries. | |
| 472 | + | - All changes are committed once after complete verification. | |
| 473 | + | - The final commit is never pushed automatically. | |
| 474 | + | - Existing documentation is reconciled rather than overwritten. | |
| 475 | + | - Complete client handover documentation is mandatory without exception. | |
| 476 | + | ||
| 477 | + | ## 10. Out of Scope | |
| 478 | + | ||
| 479 | + | - Repairing, replacing, or migrating the unavailable standalone v2 script or remote endpoint; only the built-in integration and references are removed. | |
| 480 | + | - Parallel task execution. | |
| 481 | + | - Frontend/backend distribution to different executors. | |
| 482 | + | - Autonomous approval decisions. | |
| 483 | + | - Multiple task commits. | |
| 484 | + | - Automatic pushes, releases, or deployments. | |
| 485 | + | - Replacement of project issue trackers or external documentation systems. | |
| 486 | + | - Generating implementation code during specification work. | |
| 487 | + | ||
| 488 | + | ## 11. Definition of Done | |
| 489 | + | ||
| 490 | + | Architect mode is complete when: | |
| 491 | + | ||
| 492 | + | 1. The built-in command exposes the approved CLI contract. | |
| 493 | + | 2. No built-in v2 downloader, flag parser, usage text, or documentation reference remains. | |
| 494 | + | 3. The canonical architect skill is distributed by every supported installer. | |
| 495 | + | 4. The current machine can refresh the active function and skill from the published source. | |
| 496 | + | 5. Command-level tests cover architect behavior, v2 rejection, and preservation of existing non-v2 modes. | |
| 497 | + | 6. The workflow enforces role boundaries, phase gates, task states, retries, reviews, and the single-commit policy. | |
| 498 | + | 7. The workflow mandates the complete internal and client documentation package. | |
| 499 | + | 8. Syntax and workflow tests pass. | |
| 500 | + | 9. Published OpenGist content matches the verified local source. | |
TASKS.md(файл создан)
| @@ -0,0 +1,388 @@ | |||
| 1 | + | # Plan Build Architect Mode Execution Plan | |
| 2 | + | ||
| 3 | + | ## Execution Policy | |
| 4 | + | ||
| 5 | + | This plan implements the approved `SPEC.md`. Claude Code is the architect, documentation manager, dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit reviews every task and the final aggregate diff. | |
| 6 | + | ||
| 7 | + | The following rules apply to every task: | |
| 8 | + | ||
| 9 | + | 1. Execute tasks sequentially in ID order. | |
| 10 | + | 2. Only one task may be `In Progress` at a time. | |
| 11 | + | 3. Do not start a task until its dependencies are `Complete` and the user approves dispatch. | |
| 12 | + | 4. Codex may modify only the task's Allowed File Scope. | |
| 13 | + | 5. Codex must stop and report when required work exceeds that scope. | |
| 14 | + | 6. Codex must not commit, stage, push, reset, restore, or discard changes. | |
| 15 | + | 7. Claude independently checks the diff and reruns verification commands. | |
| 16 | + | 8. CodeRabbit reviews each task. Valid critical, high, and medium findings must be fixed before completion. | |
| 17 | + | 9. Codex receives at most two focused correction attempts after its initial execution. | |
| 18 | + | 10. All changes remain uncommitted until every task, final review, full verification, and handover document passes. | |
| 19 | + | 11. Claude updates `SPEC.md`, `ADR.md`, `CHANGELOG.md`, `README.md`, and the mandatory `docs/` handover package. Codex does not edit those documents unless a later approved scope amendment explicitly says otherwise. | |
| 20 | + | ||
| 21 | + | ## Claude Documentation Workstream | |
| 22 | + | ||
| 23 | + | This workstream runs alongside Codex execution and is not delegated: | |
| 24 | + | ||
| 25 | + | - Preserve and reconcile existing documentation rather than replacing it blindly. | |
| 26 | + | - Maintain `SPEC.md` as the approved baseline and record approved amendments. | |
| 27 | + | - Create and maintain append-only `ADR.md` decisions. | |
| 28 | + | - Maintain Keep a Changelog-compatible `CHANGELOG.md` entries referencing task IDs. | |
| 29 | + | - Remove obsolete v2 usage and standalone-install references from `README.md` after `TASK-001` passes. | |
| 30 | + | - Document `plan_build --architect`, `--new`, compatibility rules, prerequisites, and examples after `TASK-002` passes. | |
| 31 | + | - Document installer distribution and local refresh behavior after `TASK-003` passes. | |
| 32 | + | - Create or update `docs/USER_MANUAL.md`, `docs/RUNBOOK.md`, `docs/API.md`, `docs/DEPLOYMENT.md`, `docs/SECURITY.md`, and `docs/HANDOVER.md` before final review. | |
| 33 | + | - Mark non-applicable sections explicitly with a factual rationale rather than omitting files or inventing behavior. | |
| 34 | + | - Add final commit SHA placeholders only until the final commit exists; replace or explain the self-reference limitation during finalization. | |
| 35 | + | ||
| 36 | + | --- | |
| 37 | + | ||
| 38 | + | ## TASK-001: Remove the obsolete v2 integration | |
| 39 | + | ||
| 40 | + | **Status:** Complete | |
| 41 | + | ||
| 42 | + | **Dependencies:** None | |
| 43 | + | ||
| 44 | + | ### Objective | |
| 45 | + | ||
| 46 | + | Remove the broken standalone v2 downloader and all `--v2` parsing and forwarding behavior from the built-in `plan_build` function. Preserve every existing non-v2 mode. Make `--v2` use the normal unknown-argument failure path. | |
| 47 | + | ||
| 48 | + | ### Allowed File Scope | |
| 49 | + | ||
| 50 | + | - `func` | |
| 51 | + | - `test_plan_build.zsh` | |
| 52 | + | ||
| 53 | + | No other file may be created, modified, renamed, or deleted by Codex. | |
| 54 | + | ||
| 55 | + | ### Context / Interfaces | |
| 56 | + | ||
| 57 | + | - `func` currently defines `_plan_build_v2()`, which downloads a now-unavailable standalone script. | |
| 58 | + | - `plan_build()` currently performs a preliminary argument pass to strip `--v2` and forward all remaining arguments. | |
| 59 | + | - The normal parser already rejects unknown arguments with a non-zero status and usage output. | |
| 60 | + | - Existing supported behavior includes `--yolo`, `--prompt`, `--brainstorm`, and `--writing-plan`. | |
| 61 | + | - `test_plan_build.zsh` is the highest command-level test seam. It sources `func`, stubs external commands, invokes `plan_build`, and asserts status and output. | |
| 62 | + | - Do not redesign the existing parser beyond the smallest change required to remove v2. | |
| 63 | + | ||
| 64 | + | ### Acceptance Criteria | |
| 65 | + | ||
| 66 | + | - `_plan_build_v2()` no longer exists. | |
| 67 | + | - The v2 URL, temporary-file logic, Bash forwarding, and v2 status handling no longer exist. | |
| 68 | + | - `plan_build()` no longer performs a v2 pre-parse or maintains v2 passthrough arguments. | |
| 69 | + | - Usage output contains no `--v2`, `--grill`, or `--distribute` text. | |
| 70 | + | - `plan_build --v2` returns non-zero through the standard unknown-argument path and identifies `--v2` as unknown. | |
| 71 | + | - Existing standard, yolo, prompt, brainstorm, and writing-plan behavior remains unchanged. | |
| 72 | + | - Tests cover v2 rejection and continue covering existing modes. | |
| 73 | + | - Zsh syntax validation and the complete existing plan-build test suite pass. | |
| 74 | + | ||
| 75 | + | ### Verification Commands | |
| 76 | + | ||
| 77 | + | ```bash | |
| 78 | + | zsh -n func | |
| 79 | + | zsh -n test_plan_build.zsh | |
| 80 | + | zsh test_plan_build.zsh | |
| 81 | + | git diff --check -- func test_plan_build.zsh | |
| 82 | + | git diff -- func test_plan_build.zsh | |
| 83 | + | ``` | |
| 84 | + | ||
| 85 | + | ### Prompt for Codex | |
| 86 | + | ||
| 87 | + | ```text | |
| 88 | + | Objective: | |
| 89 | + | Remove the obsolete standalone v2 integration from the built-in plan_build Zsh function. Delete the _plan_build_v2 downloader and remove all --v2 pre-parsing, passthrough, forwarding, and usage text. After the change, --v2 must be handled by the existing normal unknown-argument branch. Preserve all non-v2 behavior. | |
| 90 | + | ||
| 91 | + | Allowed File Scope: | |
| 92 | + | - func | |
| 93 | + | - test_plan_build.zsh | |
| 94 | + | Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. | |
| 95 | + | ||
| 96 | + | Context / Interfaces: | |
| 97 | + | - func defines _plan_build_v2() immediately before plan_build(). It downloads a missing remote plan_build.sh and executes it with Bash. | |
| 98 | + | - plan_build() currently strips --v2 in a preliminary argument loop, then either forwards to _plan_build_v2 or enters the normal parser. | |
| 99 | + | - The normal parser already prints "Error: Unknown argument: <argument>", prints usage, and returns 1. | |
| 100 | + | - Supported non-v2 flags are --yolo, --prompt, --brainstorm, and --writing-plan. | |
| 101 | + | - test_plan_build.zsh is a command-level Zsh test that sources func, stubs external CLI checks and Claude, and asserts output/status. | |
| 102 | + | - Make the smallest correct parser change. Do not refactor unrelated shell functions or reformat unrelated content. | |
| 103 | + | ||
| 104 | + | Acceptance Criteria: | |
| 105 | + | 1. _plan_build_v2 and all of its URL/download/temporary-file/forwarding code are removed. | |
| 106 | + | 2. plan_build has no use_v2 or passthrough state and no preliminary v2 argument pass. | |
| 107 | + | 3. Usage text has no v2, grill, or distribute reference. | |
| 108 | + | 4. plan_build --v2 returns status 1 and includes "Unknown argument: --v2". | |
| 109 | + | 5. Standard, --yolo, --prompt, --brainstorm, and --writing-plan behavior remains unchanged. | |
| 110 | + | 6. Add a command-level regression assertion for --v2 rejection. | |
| 111 | + | 7. All existing tests pass. | |
| 112 | + | ||
| 113 | + | Required Verification: | |
| 114 | + | - zsh -n func | |
| 115 | + | - zsh -n test_plan_build.zsh | |
| 116 | + | - zsh test_plan_build.zsh | |
| 117 | + | - git diff --check -- func test_plan_build.zsh | |
| 118 | + | ||
| 119 | + | Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. | |
| 120 | + | ``` | |
| 121 | + | ||
| 122 | + | ### CodeRabbit Outcome | |
| 123 | + | ||
| 124 | + | Passed with zero findings. | |
| 125 | + | ||
| 126 | + | ### Completion Evidence | |
| 127 | + | ||
| 128 | + | - Codex removed the v2 downloader and parser forwarding only within the approved files. | |
| 129 | + | - `plan_build --v2` now returns the normal unknown-argument error. | |
| 130 | + | - `zsh -n func` passed. | |
| 131 | + | - `zsh -n test_plan_build.zsh` passed. | |
| 132 | + | - `zsh test_plan_build.zsh` passed. | |
| 133 | + | - `git diff --check -- func test_plan_build.zsh` passed. | |
| 134 | + | ||
| 135 | + | --- | |
| 136 | + | ||
| 137 | + | ## TASK-002: Add the built-in architect command contract | |
| 138 | + | ||
| 139 | + | **Status:** Complete | |
| 140 | + | ||
| 141 | + | **Dependencies:** TASK-001 | |
| 142 | + | ||
| 143 | + | ### Objective | |
| 144 | + | ||
| 145 | + | Add `--architect` to the built-in `plan_build` function. Support `--new` and `--yolo`, enforce incompatible and duplicate flag rules, run fail-fast architect preflight, collect the initial payload through the existing input contract, and launch Claude with the canonical installed architect skill. Preserve existing non-architect modes. | |
| 146 | + | ||
| 147 | + | ### Allowed File Scope | |
| 148 | + | ||
| 149 | + | - `func` | |
| 150 | + | - `test_plan_build.zsh` | |
| 151 | + | ||
| 152 | + | No other file may be created, modified, renamed, or deleted by Codex. | |
| 153 | + | ||
| 154 | + | ### Context / Interfaces | |
| 155 | + | ||
| 156 | + | - Claude will create the canonical repository workflow document `architect-workflow.md` before this task is dispatched. | |
| 157 | + | - Installers will later distribute it to `~/.claude/skills/plan-build-architect/SKILL.md` in `TASK-003`. | |
| 158 | + | - Architect mode is interactive and requires `claude`, `codex`, `coderabbit`, `git`, a Git worktree, a usable TTY, and a readable non-empty installed skill. | |
| 159 | + | - Preflight must run before payload collection or any project-file modification. | |
| 160 | + | - `--new` is valid only with `--architect`. | |
| 161 | + | - `--architect` may combine only with `--new` and `--yolo`. | |
| 162 | + | - Architect mode must reject `--prompt`, `--brainstorm`, and `--writing-plan` combinations. | |
| 163 | + | - `--yolo` is forwarded to Claude but the architect workflow itself retains mandatory human gates. | |
| 164 | + | - The initial payload continues using the existing `EOF`-terminated stdin behavior. | |
| 165 | + | - Existing command-level tests stub helpers and Claude. Architect tests must not launch real external CLIs or require a real TTY. | |
| 166 | + | ||
| 167 | + | ### Acceptance Criteria | |
| 168 | + | ||
| 169 | + | - Usage documents built-in architect syntax and no v2 syntax. | |
| 170 | + | - Duplicate `--architect` and duplicate `--new` fail with usage guidance. | |
| 171 | + | - `--new` without `--architect` fails. | |
| 172 | + | - Architect combinations with prompt, brainstorm, or writing-plan fail before external tools launch. | |
| 173 | + | - A dedicated architect preflight checks all required tools, Git context, TTY, and installed skill with actionable errors. | |
| 174 | + | - Architect preflight occurs before payload reading. | |
| 175 | + | - Empty payload remains an error. | |
| 176 | + | - The Claude invocation explicitly directs Claude to read `~/.claude/skills/plan-build-architect/SKILL.md`, obey the architect role boundary, and treat the payload as the initial high-level requirement. | |
| 177 | + | - `--new` is represented unambiguously in the Claude instruction. | |
| 178 | + | - `--yolo` is forwarded to Claude. | |
| 179 | + | - Existing non-architect modes retain current observable behavior. | |
| 180 | + | - Command-level tests cover success, compatibility failures, duplicates, new/resume instruction, yolo forwarding, and preflight failure without invoking real tools. | |
| 181 | + | ||
| 182 | + | ### Verification Commands | |
| 183 | + | ||
| 184 | + | ```bash | |
| 185 | + | zsh -n func | |
| 186 | + | zsh -n test_plan_build.zsh | |
| 187 | + | zsh test_plan_build.zsh | |
| 188 | + | git diff --check -- func test_plan_build.zsh | |
| 189 | + | git diff -- func test_plan_build.zsh | |
| 190 | + | ``` | |
| 191 | + | ||
| 192 | + | ### Prompt for Codex | |
| 193 | + | ||
| 194 | + | ```text | |
| 195 | + | Objective: | |
| 196 | + | Implement the built-in plan_build --architect command contract in Zsh. Architect mode launches Claude as a documentation-first architect/orchestrator using ~/.claude/skills/plan-build-architect/SKILL.md. It must support --new and --yolo, reject incompatible or duplicate flags, run a fail-fast preflight, preserve the existing EOF-terminated payload input, and leave every existing non-architect mode unchanged. | |
| 197 | + | ||
| 198 | + | Allowed File Scope: | |
| 199 | + | - func | |
| 200 | + | - test_plan_build.zsh | |
| 201 | + | Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. | |
| 202 | + | ||
| 203 | + | Context / Interfaces: | |
| 204 | + | - TASK-001 has already removed --v2. | |
| 205 | + | - Existing plan_build supports --yolo, --prompt, --brainstorm, and --writing-plan. | |
| 206 | + | - --architect may combine only with --new and --yolo. | |
| 207 | + | - --new without --architect is invalid. | |
| 208 | + | - --architect combined with --prompt, --brainstorm, or --writing-plan is invalid. | |
| 209 | + | - Duplicate --architect and duplicate --new must fail with usage output. | |
| 210 | + | - Architect preflight must verify, before payload reading: an interactive TTY; a Git worktree; claude, codex, coderabbit, and git availability; and a readable non-empty ~/.claude/skills/plan-build-architect/SKILL.md. | |
| 211 | + | - Error output must identify the missing requirement and provide practical remediation. | |
| 212 | + | - The current input contract reads lines until EOF appears on its own line and rejects an empty payload. | |
| 213 | + | - The Claude prompt must explicitly tell Claude to read ~/.claude/skills/plan-build-architect/SKILL.md, follow it strictly, remain within its documentation/orchestration boundary, and use the payload as the initial high-level requirement. | |
| 214 | + | - When --new is present, the prompt must explicitly request the skill's archive-and-start-new behavior. Otherwise it must permit safe resume detection. | |
| 215 | + | - --yolo forwards the existing Claude yolo argument but does not weaken workflow approval gates. | |
| 216 | + | - test_plan_build.zsh uses function stubs. Add or stub a dedicated architect preflight seam so tests never invoke actual CLIs or depend on the test runner's TTY. | |
| 217 | + | - Prefer the existing command-level test seam. Do not add another test framework. | |
| 218 | + | - Make minimal localized changes and do not refactor unrelated functions. | |
| 219 | + | ||
| 220 | + | Acceptance Criteria: | |
| 221 | + | 1. Usage includes plan_build --architect [--new] [--yolo]. | |
| 222 | + | 2. Duplicate architect/new flags and invalid combinations return status 1 with clear errors and usage. | |
| 223 | + | 3. Architect preflight executes before payload collection and checks every stated dependency. | |
| 224 | + | 4. Empty payload returns status 1. | |
| 225 | + | 5. A successful architect invocation directs Claude to the canonical installed skill and includes the initial payload. | |
| 226 | + | 6. --new changes the instruction to start a new archived workflow; default behavior permits resume detection. | |
| 227 | + | 7. --yolo is forwarded to Claude. | |
| 228 | + | 8. Existing standard, prompt, brainstorm, writing-plan, and yolo tests remain green. | |
| 229 | + | 9. Tests cover architect success and every parser/preflight edge without launching real external processes. | |
| 230 | + | ||
| 231 | + | Required Verification: | |
| 232 | + | - zsh -n func | |
| 233 | + | - zsh -n test_plan_build.zsh | |
| 234 | + | - zsh test_plan_build.zsh | |
| 235 | + | - git diff --check -- func test_plan_build.zsh | |
| 236 | + | ||
| 237 | + | Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. | |
| 238 | + | ``` | |
| 239 | + | ||
| 240 | + | ### CodeRabbit Outcome | |
| 241 | + | ||
| 242 | + | CodeRabbit reported one major finding: checking only the exit status of `git rev-parse --is-inside-work-tree` could accept a bare repository. Codex added an exact `true` check and regression fixtures for normal and bare repositories. The follow-up CodeRabbit review passed with zero findings. | |
| 243 | + | ||
| 244 | + | ### Completion Evidence | |
| 245 | + | ||
| 246 | + | - Codex added the built-in architect parser, preflight, launch prompt, and command-level tests only within the approved files. | |
| 247 | + | - Architect tests cover success, new workflow, safe resume, yolo forwarding, invalid combinations, duplicates, empty payload, preflight ordering, normal worktrees, and bare repository rejection. | |
| 248 | + | - `zsh -n func` passed. | |
| 249 | + | - `zsh -n test_plan_build.zsh` passed. | |
| 250 | + | - `zsh test_plan_build.zsh` passed. | |
| 251 | + | - `git diff --check -- func test_plan_build.zsh` passed. | |
| 252 | + | - Final CodeRabbit review passed with zero findings. | |
| 253 | + | ||
| 254 | + | --- | |
| 255 | + | ||
| 256 | + | ## TASK-003: Distribute and verify the canonical architect skill | |
| 257 | + | ||
| 258 | + | **Status:** Pending | |
| 259 | + | ||
| 260 | + | **Dependencies:** TASK-002 | |
| 261 | + | ||
| 262 | + | ### Objective | |
| 263 | + | ||
| 264 | + | Extend the configuration and platform installers to atomically install the canonical `architect-workflow.md` source as `~/.claude/skills/plan-build-architect/SKILL.md`. Add repository-level tests that verify every supported installer uses the same source and destination while preserving the existing plan-build skill installation. | |
| 265 | + | ||
| 266 | + | ### Allowed File Scope | |
| 267 | + | ||
| 268 | + | - `config.sh` | |
| 269 | + | - `zsh_macos.sh` | |
| 270 | + | - `zsh_ubuntu.sh` | |
| 271 | + | - `zsh_wsl.sh` | |
| 272 | + | - `test_plan_build_installers.zsh` (new) | |
| 273 | + | ||
| 274 | + | Codex must not modify `architect-workflow.md`; Claude owns its approved content. No other file may be created, modified, renamed, or deleted by Codex. | |
| 275 | + | ||
| 276 | + | ### Context / Interfaces | |
| 277 | + | ||
| 278 | + | - `config.sh` currently downloads `orchestrate-loop.md` to `~/.claude/skills/plan-build/SKILL.md` through a temporary file and atomic move. | |
| 279 | + | - Each platform installer has equivalent existing plan-build skill installation logic. | |
| 280 | + | - The new canonical repository source is `architect-workflow.md`. | |
| 281 | + | - The new installed destination is `~/.claude/skills/plan-build-architect/SKILL.md`. | |
| 282 | + | - Existing plan-build skill distribution must continue unchanged. | |
| 283 | + | - All four installers must use their existing gist raw base rather than introducing a new remote endpoint. | |
| 284 | + | - Failure to download or install the architect skill must be visible and must not leave a partial destination file. | |
| 285 | + | - The new test should validate repository contracts without network access, elevated privileges, home-directory changes, or execution of full platform installers. | |
| 286 | + | ||
| 287 | + | ### Acceptance Criteria | |
| 288 | + | ||
| 289 | + | - `config.sh` installs both the existing plan-build skill and the architect skill. | |
| 290 | + | - macOS, Ubuntu, and WSL installers install both skills. | |
| 291 | + | - Every installer downloads `architect-workflow.md` from its existing gist raw base. | |
| 292 | + | - Every installer targets `~/.claude/skills/plan-build-architect/SKILL.md`. | |
| 293 | + | - Parent directories are created safely. | |
| 294 | + | - Downloads use temporary files and atomic moves. | |
| 295 | + | - Failed downloads remove temporary files and emit clear errors or warnings consistent with each installer's existing behavior. | |
| 296 | + | - Existing plan-build skill installation remains intact. | |
| 297 | + | - A new Zsh test validates all four installer contracts statically and runs without external services. | |
| 298 | + | - Bash and Zsh syntax checks pass. | |
| 299 | + | ||
| 300 | + | ### Verification Commands | |
| 301 | + | ||
| 302 | + | ```bash | |
| 303 | + | bash -n config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh | |
| 304 | + | zsh -n test_plan_build_installers.zsh | |
| 305 | + | zsh test_plan_build_installers.zsh | |
| 306 | + | zsh test_plan_build.zsh | |
| 307 | + | git diff --check -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh | |
| 308 | + | git diff -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh | |
| 309 | + | ``` | |
| 310 | + | ||
| 311 | + | ### Prompt for Codex | |
| 312 | + | ||
| 313 | + | ```text | |
| 314 | + | Objective: | |
| 315 | + | Distribute the canonical architect workflow through every supported Zsh Setup installer. Install repository file architect-workflow.md from the existing gist raw base as ~/.claude/skills/plan-build-architect/SKILL.md, using the same safe temporary-file and atomic-move pattern as the existing plan-build skill. Add a network-free repository test for the installer contracts. | |
| 316 | + | ||
| 317 | + | Allowed File Scope: | |
| 318 | + | - config.sh | |
| 319 | + | - zsh_macos.sh | |
| 320 | + | - zsh_ubuntu.sh | |
| 321 | + | - zsh_wsl.sh | |
| 322 | + | - test_plan_build_installers.zsh (new) | |
| 323 | + | Do not modify architect-workflow.md. Do not create, modify, rename, or delete any other file. Do not stage, commit, push, reset, restore, or discard changes. | |
| 324 | + | ||
| 325 | + | Context / Interfaces: | |
| 326 | + | - config.sh and all three platform installers already install orchestrate-loop.md at ~/.claude/skills/plan-build/SKILL.md. | |
| 327 | + | - Preserve that existing installation exactly. | |
| 328 | + | - Add architect-workflow.md as a second canonical source. | |
| 329 | + | - Install it at ~/.claude/skills/plan-build-architect/SKILL.md. | |
| 330 | + | - Use each script's existing GIST_RAW_BASE. Do not add or depend on another gist or endpoint. | |
| 331 | + | - Follow each script's current logging and failure conventions. | |
| 332 | + | - Create destination directories safely. | |
| 333 | + | - Download to a temporary sibling file and move only after successful curl completion. | |
| 334 | + | - Remove temporary files on failure so partial skills cannot become active. | |
| 335 | + | - test_plan_build_installers.zsh must inspect repository files and assert the source filename, installed destination, existing-skill preservation, and safe download pattern for config.sh plus macOS, Ubuntu, and WSL scripts. | |
| 336 | + | - The test must not access the network, invoke sudo, execute the installers, or write to the real home directory. | |
| 337 | + | - Keep changes localized to existing skill-install blocks. | |
| 338 | + | ||
| 339 | + | Acceptance Criteria: | |
| 340 | + | 1. All four installers install the existing plan-build skill and new architect skill. | |
| 341 | + | 2. All use architect-workflow.md and ~/.claude/skills/plan-build-architect/SKILL.md. | |
| 342 | + | 3. All use temporary download files and atomic moves, with cleanup on failure. | |
| 343 | + | 4. Existing installation behavior remains intact. | |
| 344 | + | 5. The new static contract test passes without external services. | |
| 345 | + | 6. Existing plan_build tests remain green. | |
| 346 | + | ||
| 347 | + | Required Verification: | |
| 348 | + | - bash -n config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh | |
| 349 | + | - zsh -n test_plan_build_installers.zsh | |
| 350 | + | - zsh test_plan_build_installers.zsh | |
| 351 | + | - zsh test_plan_build.zsh | |
| 352 | + | - git diff --check -- config.sh zsh_macos.sh zsh_ubuntu.sh zsh_wsl.sh test_plan_build_installers.zsh | |
| 353 | + | ||
| 354 | + | Report the files changed, tests run, and results. If any required change falls outside the allowed scope, stop and report the needed scope expansion without touching that file. | |
| 355 | + | ``` | |
| 356 | + | ||
| 357 | + | ### CodeRabbit Outcome | |
| 358 | + | ||
| 359 | + | Pending. | |
| 360 | + | ||
| 361 | + | ### Completion Evidence | |
| 362 | + | ||
| 363 | + | Pending. | |
| 364 | + | ||
| 365 | + | --- | |
| 366 | + | ||
| 367 | + | ## Final Review and Handover Gate | |
| 368 | + | ||
| 369 | + | This gate begins only after `TASK-001`, `TASK-002`, and `TASK-003` are `Complete`. | |
| 370 | + | ||
| 371 | + | Claude must: | |
| 372 | + | ||
| 373 | + | 1. Complete all root engineering records and mandatory `docs/` handover files. | |
| 374 | + | 2. Run CodeRabbit over the complete uncommitted diff. | |
| 375 | + | 3. Delegate valid code or test fixes to Codex under the responsible task's original scope and retry limit. | |
| 376 | + | 4. Run all focused commands plus the complete repository verification suite. | |
| 377 | + | 5. Validate required documents, links, source references, examples, Mermaid syntax where tooling exists, and absence of unresolved placeholders. | |
| 378 | + | 6. Run available secret scanning and block suspected credentials. | |
| 379 | + | 7. Confirm Git contains only approved changes and preserves pre-existing user work. | |
| 380 | + | 8. Present the final diff summary, verification evidence, known limitations, and proposed single commit message. | |
| 381 | + | 9. Wait for explicit user approval before staging and creating one commit. | |
| 382 | + | 10. Never push automatically. | |
| 383 | + | ||
| 384 | + | ## Final Commit | |
| 385 | + | ||
| 386 | + | **Status:** Pending user approval after final gate. | |
| 387 | + | ||
| 388 | + | **Proposed message:** `feat: add plan_build architect workflow` | |
architect-workflow.md(файл создан)
| @@ -0,0 +1,219 @@ | |||
| 1 | + | # Plan Build Architect Workflow | |
| 2 | + | ||
| 3 | + | Use this workflow only when `plan_build --architect` launches Claude Code. Claude is the lead architect, documentation manager, task dispatcher, and verifier. OpenAI Codex is the sole code and test-code executor. CodeRabbit is the required automated reviewer. | |
| 4 | + | ||
| 5 | + | ## Non-Negotiable Role Boundary | |
| 6 | + | ||
| 7 | + | Claude may inspect every project file but may create or modify only: | |
| 8 | + | ||
| 9 | + | - `SPEC.md` | |
| 10 | + | - `TASKS.md` | |
| 11 | + | - `ADR.md` | |
| 12 | + | - `CHANGELOG.md` | |
| 13 | + | - `README.md` | |
| 14 | + | - Markdown files under `docs/` | |
| 15 | + | ||
| 16 | + | Claude must not write application code, test code, migrations, generated source, or executable configuration. Delegate those changes to Codex through an approved task prompt. | |
| 17 | + | ||
| 18 | + | Codex must not commit, stage, push, reset, restore, or discard changes. All approved work remains uncommitted until the complete delivery passes final verification and the user approves one final commit. | |
| 19 | + | ||
| 20 | + | Never push automatically. | |
| 21 | + | ||
| 22 | + | ## Startup Preflight | |
| 23 | + | ||
| 24 | + | Before discovery or project-file modification: | |
| 25 | + | ||
| 26 | + | 1. Confirm the current directory is a Git worktree. | |
| 27 | + | 2. Record `git status --short` and preserve all pre-existing work. | |
| 28 | + | 3. Confirm an interactive terminal is available. | |
| 29 | + | 4. Confirm `codex`, `coderabbit`, and `git` are available. | |
| 30 | + | 5. Inspect project instructions, manifests, existing documentation, tests, CI, and nearby implementation patterns. | |
| 31 | + | 6. Never request or expose credential values. Use approved credential integrations when authentication is required. | |
| 32 | + | ||
| 33 | + | If a requirement is missing, stop with exact remediation guidance. | |
| 34 | + | ||
| 35 | + | ## Existing Workflow Detection | |
| 36 | + | ||
| 37 | + | If `SPEC.md`, `TASKS.md`, `ADR.md`, or `CHANGELOG.md` exists: | |
| 38 | + | ||
| 39 | + | 1. Read all existing workflow records. | |
| 40 | + | 2. Compare their claims with Git and the current worktree. | |
| 41 | + | 3. Identify the first incomplete or inconsistent task. | |
| 42 | + | 4. Present the detected state and ask whether to resume. | |
| 43 | + | ||
| 44 | + | When the launch instruction says `Start mode: archive-and-start-new`, archive existing workflow documents in a timestamped documentation archive before creating replacements. Never overwrite them silently. | |
| 45 | + | ||
| 46 | + | ## Phase 1: Discovery and Architecture | |
| 47 | + | ||
| 48 | + | Interview the user until product, architecture, data, integration, operational, security, and handover requirements are clear. | |
| 49 | + | ||
| 50 | + | Rules: | |
| 51 | + | ||
| 52 | + | - Ask exactly one question at a time. | |
| 53 | + | - Include a recommended default answer with every question. | |
| 54 | + | - Resolve facts from the repository instead of asking the user. | |
| 55 | + | - Ask the user only for decisions, priorities, business rules, and information that cannot be discovered safely. | |
| 56 | + | - Probe user roles, workflows, data structures, API or component contracts, technology constraints, integrations, edge cases, failure modes, migration, rollback, testing, deployment, monitoring, security, compliance, support, and ownership. | |
| 57 | + | - Collect project name, client or owner, purpose, target users, repository scope, supported environments, deployment owner, operational owner, support role, compliance constraints, and intended handover date. | |
| 58 | + | - Do not implement or dispatch Codex during discovery. | |
| 59 | + | ||
| 60 | + | Do not enter Phase 2 until the user explicitly states either: | |
| 61 | + | ||
| 62 | + | - `I am ready to generate the spec` | |
| 63 | + | - `Phase 1 complete` | |
| 64 | + | ||
| 65 | + | ## Phase 2: Specification | |
| 66 | + | ||
| 67 | + | After the explicit Phase 1 completion phrase: | |
| 68 | + | ||
| 69 | + | 1. Ask no more discovery questions. | |
| 70 | + | 2. Create or reconcile `SPEC.md` without discarding valid existing content. | |
| 71 | + | 3. Include executive summary and goals, architecture and technology, data models or durable state schemas, API or component contracts, edge cases, constraints, testing strategy, out-of-scope items, and definition of done. | |
| 72 | + | 4. Use Mermaid for applicable system context, component, deployment, and critical sequence diagrams. | |
| 73 | + | 5. Mark non-applicable sections with a factual rationale instead of inventing behavior. | |
| 74 | + | 6. Treat the approved specification as the requirements baseline. | |
| 75 | + | 7. Present the specification and wait for explicit approval. | |
| 76 | + | ||
| 77 | + | Any later requirement change is a visible amendment. Pause execution, assess affected tasks and documents, record architectural changes in `ADR.md`, and obtain approval before continuing. | |
| 78 | + | ||
| 79 | + | ## Phase 3: Codex Task Plan | |
| 80 | + | ||
| 81 | + | After `SPEC.md` approval, create or reconcile `TASKS.md`. | |
| 82 | + | ||
| 83 | + | Use stable task IDs such as `TASK-001`. Allowed states are: | |
| 84 | + | ||
| 85 | + | - `Pending` | |
| 86 | + | - `In Progress` | |
| 87 | + | - `Blocked` | |
| 88 | + | - `Review` | |
| 89 | + | - `Complete` | |
| 90 | + | ||
| 91 | + | Only one task may be `In Progress`. | |
| 92 | + | ||
| 93 | + | Every task must include: | |
| 94 | + | ||
| 95 | + | - ID, title, status, and dependencies | |
| 96 | + | - Objective | |
| 97 | + | - Exhaustive allowed file scope | |
| 98 | + | - Context and interfaces | |
| 99 | + | - Self-contained prompt for Codex | |
| 100 | + | - Acceptance criteria | |
| 101 | + | - Unit or integration test requirements | |
| 102 | + | - Verification commands | |
| 103 | + | - CodeRabbit outcome | |
| 104 | + | - Completion evidence | |
| 105 | + | ||
| 106 | + | Every Codex prompt must explicitly prohibit commits and out-of-scope edits. Tasks must be atomic, sequential, and small enough for a fresh Codex context. | |
| 107 | + | ||
| 108 | + | Present `TASKS.md` and wait for explicit approval before execution. | |
| 109 | + | ||
| 110 | + | ## Documentation Records | |
| 111 | + | ||
| 112 | + | Maintain these root engineering records throughout execution: | |
| 113 | + | ||
| 114 | + | - `SPEC.md`: approved requirements baseline and amendments | |
| 115 | + | - `TASKS.md`: task state, prompts, reviews, and evidence | |
| 116 | + | - `ADR.md`: append-only architecture decisions | |
| 117 | + | - `CHANGELOG.md`: Keep a Changelog-compatible `Unreleased` entries referencing task IDs | |
| 118 | + | - `README.md`: product overview, prerequisites, quick start, and configuration | |
| 119 | + | ||
| 120 | + | Every ADR uses a stable ID and records status, date, context, decision, alternatives, consequences, and affected components. Keep superseded decisions and link their replacements. | |
| 121 | + | ||
| 122 | + | ## Mandatory Client Handover Package | |
| 123 | + | ||
| 124 | + | The following files are mandatory without exception: | |
| 125 | + | ||
| 126 | + | - `docs/USER_MANUAL.md` | |
| 127 | + | - `docs/RUNBOOK.md` | |
| 128 | + | - `docs/API.md` | |
| 129 | + | - `docs/DEPLOYMENT.md` | |
| 130 | + | - `docs/SECURITY.md` | |
| 131 | + | - `docs/HANDOVER.md` | |
| 132 | + | ||
| 133 | + | Create missing documents and reconcile existing ones. Do not replace valid project-specific content wholesale. | |
| 134 | + | ||
| 135 | + | When a document or section is not applicable, retain it and state `Not Applicable` with a short factual rationale. | |
| 136 | + | ||
| 137 | + | Client-facing documents describe the delivered system, not Claude, Codex, CodeRabbit, prompts, or internal execution mechanics unless disclosure is contractually required. | |
| 138 | + | ||
| 139 | + | Implementation claims must reference relevant source files, configuration, schemas, endpoints, or verified commands. Handover documents include software version or commit SHA, generation date, document owner, and last verification date. | |
| 140 | + | ||
| 141 | + | `docs/HANDOVER.md` must include deliverables, access prerequisites, verified capabilities, limitations, approved deferred risks, support boundaries, warranty assumptions, ownership transfer, and dated acceptance/sign-off placeholders. | |
| 142 | + | ||
| 143 | + | ## Task Execution Loop | |
| 144 | + | ||
| 145 | + | For each approved task, in dependency order: | |
| 146 | + | ||
| 147 | + | 1. Confirm dependencies are `Complete`. | |
| 148 | + | 2. Set exactly that task to `In Progress`. | |
| 149 | + | 3. Record the current Git status and task baseline. | |
| 150 | + | 4. Invoke Codex non-interactively in the current worktree with workspace-write access using the exact approved prompt from `TASKS.md`. | |
| 151 | + | 5. Capture Codex's result. | |
| 152 | + | 6. Inspect the diff for correctness, approved scope, repository conventions, unrelated changes, and secret exposure. | |
| 153 | + | 7. Independently run the task's verification commands. | |
| 154 | + | 8. Set the task to `Review` and run CodeRabbit on the task diff. | |
| 155 | + | 9. Investigate every concrete finding. | |
| 156 | + | 10. Delegate valid fixes back to Codex within the same task scope. | |
| 157 | + | 11. Rerun focused verification and CodeRabbit after substantive fixes. | |
| 158 | + | 12. Record commands, results, findings, and completion evidence. | |
| 159 | + | 13. Report the outcome and wait for user approval before starting the next task. | |
| 160 | + | ||
| 161 | + | Use non-interactive Codex execution in this form, adapting only supported sandbox flags to the installed CLI: | |
| 162 | + | ||
| 163 | + | ```bash | |
| 164 | + | codex exec --sandbox workspace-write "<exact approved task prompt>" | |
| 165 | + | ``` | |
| 166 | + | ||
| 167 | + | Critical, high, and medium CodeRabbit findings block completion. Low-severity findings may be deferred only with user approval and must be recorded in `CHANGELOG.md` and `docs/HANDOVER.md`. | |
| 168 | + | ||
| 169 | + | ## Scope Expansion | |
| 170 | + | ||
| 171 | + | If Codex reports that required work exceeds the allowed file scope: | |
| 172 | + | ||
| 173 | + | 1. Do not permit out-of-scope edits. | |
| 174 | + | 2. Assess requirement, architecture, dependency, and test impact. | |
| 175 | + | 3. Update `SPEC.md`, `TASKS.md`, and `ADR.md` when appropriate. | |
| 176 | + | 4. Ask the user to approve the revised scope. | |
| 177 | + | 5. Redispatch only after approval. | |
| 178 | + | ||
| 179 | + | ## Failure and Retry Policy | |
| 180 | + | ||
| 181 | + | Allow the initial Codex attempt plus at most two focused correction attempts. | |
| 182 | + | ||
| 183 | + | If acceptance still fails: | |
| 184 | + | ||
| 185 | + | 1. Stop the workflow. | |
| 186 | + | 2. Mark the task `Blocked`. | |
| 187 | + | 3. Preserve the partial diff. | |
| 188 | + | 4. Record diagnostics and attempted fixes in task evidence. | |
| 189 | + | 5. Ask whether to revise architecture, scope, or acceptance criteria. | |
| 190 | + | 6. Do not start dependent tasks. | |
| 191 | + | ||
| 192 | + | If no test framework exists, the first applicable task establishes the smallest project-appropriate validation setup. If automated testing is technically impossible, obtain user approval for explicit manual acceptance steps and record the risk in `docs/HANDOVER.md`. | |
| 193 | + | ||
| 194 | + | ## Security Rules | |
| 195 | + | ||
| 196 | + | - Never include credential values, tokens, private keys, personal data, or production secrets in prompts or documentation. | |
| 197 | + | - Document only secret names, required environment variables, approved storage, ownership, and rotation procedures. | |
| 198 | + | - Use native credential helpers and approved credential stores. | |
| 199 | + | - Run available secret scanning before final completion. | |
| 200 | + | - Treat suspected credentials as blocking findings. | |
| 201 | + | ||
| 202 | + | ## Final Review and Single Commit | |
| 203 | + | ||
| 204 | + | After every task is `Complete`: | |
| 205 | + | ||
| 206 | + | 1. Finish all root engineering records and mandatory handover documents. | |
| 207 | + | 2. Run CodeRabbit over the complete uncommitted diff. | |
| 208 | + | 3. Delegate valid code or test fixes to Codex under the responsible task scope. | |
| 209 | + | 4. Run the complete project lint, type-check, build, and test suite. | |
| 210 | + | 5. Confirm the aggregate diff contains only approved changes and preserves pre-existing work. | |
| 211 | + | 6. Validate required documents and sections, Markdown structure, links, source references, commands, examples, and Mermaid syntax where tooling is available. | |
| 212 | + | 7. Ensure no unresolved `TODO`, placeholder, or template text remains. Approved limitations belong in `docs/HANDOVER.md`. | |
| 213 | + | 8. Run available secret scanning. | |
| 214 | + | 9. Present the complete diff summary, verification evidence, known limitations, and proposed commit message. | |
| 215 | + | 10. Wait for explicit user approval. | |
| 216 | + | 11. Stage only approved files and create one commit. | |
| 217 | + | 12. Do not push. | |
| 218 | + | ||
| 219 | + | Never call the delivery complete when required verification has not run. Report environmental or unrelated failures with evidence. | |
func
| @@ -497,52 +497,49 @@ _plan_build_superpowers_preflight() { | |||
| 497 | 497 | return 1 | |
| 498 | 498 | } | |
| 499 | 499 | ||
| 500 | - | _plan_build_v2() { | |
| 501 | - | # v2 is the standalone plan_build script (adds --grill and --distribute), | |
| 502 | - | # fetched on demand from its own gist so this function never goes stale. | |
| 503 | - | local v2_url="https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.sh" | |
| 504 | - | local v2_file | |
| 505 | - | local v2_status | |
| 500 | + | _plan_build_is_worktree() { | |
| 501 | + | local inside_work_tree | |
| 506 | 502 | ||
| 507 | - | require_cli curl "curl" || return 1 | |
| 503 | + | inside_work_tree="$(command git rev-parse --is-inside-work-tree 2>/dev/null)" || return 1 | |
| 504 | + | [ "$inside_work_tree" = "true" ] | |
| 505 | + | } | |
| 506 | + | ||
| 507 | + | _plan_build_architect_preflight() { | |
| 508 | + | local skill_path="$HOME/.claude/skills/plan-build-architect/SKILL.md" | |
| 509 | + | ||
| 510 | + | if ! (: </dev/tty) 2>/dev/null; then | |
| 511 | + | echo "❌ Error: Architect mode requires an interactive terminal." | |
| 512 | + | echo "Run plan_build --architect from an interactive terminal." | |
| 513 | + | return 1 | |
| 514 | + | fi | |
| 508 | 515 | ||
| 509 | - | v2_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-v2.XXXXXX")" || return 1 | |
| 516 | + | require_cli claude "Claude Code CLI" || return 1 | |
| 517 | + | require_cli codex "Codex CLI" || return 1 | |
| 518 | + | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 519 | + | require_cli git "Git CLI" || return 1 | |
| 510 | 520 | ||
| 511 | - | if ! curl -fsSL "$v2_url" -o "$v2_file"; then | |
| 512 | - | rm -f "$v2_file" | |
| 513 | - | echo "❌ Error: Unable to download plan_build v2 from $v2_url" | |
| 521 | + | if ! _plan_build_is_worktree; then | |
| 522 | + | echo "❌ Error: Architect mode must run inside a Git worktree." | |
| 523 | + | echo "Change to a Git worktree, then retry plan_build --architect." | |
| 514 | 524 | return 1 | |
| 515 | 525 | fi | |
| 516 | 526 | ||
| 517 | - | bash "$v2_file" "$@" | |
| 518 | - | v2_status=$? | |
| 519 | - | rm -f "$v2_file" | |
| 520 | - | return $v2_status | |
| 527 | + | if [ ! -r "$skill_path" ] || [ ! -s "$skill_path" ]; then | |
| 528 | + | echo "❌ Error: Architect skill is missing, unreadable, or empty: $skill_path" | |
| 529 | + | echo "Install a readable, non-empty plan-build-architect skill at that path." | |
| 530 | + | return 1 | |
| 531 | + | fi | |
| 521 | 532 | } | |
| 522 | 533 | ||
| 523 | 534 | plan_build() { | |
| 524 | 535 | local claude_args=() | |
| 525 | 536 | local use_yolo=0 | |
| 537 | + | local use_architect=0 | |
| 538 | + | local use_new=0 | |
| 526 | 539 | local enhance_payload=0 | |
| 527 | 540 | local planning_mode="standard" | |
| 528 | - | local usage="Usage: plan_build [--v2] [--yolo] [--prompt] [--brainstorm | --writing-plan] | |
| 529 | - | --v2 forwards all other arguments to the standalone v2 script (adds --grill and --distribute)." | |
| 530 | - | ||
| 531 | - | local use_v2=0 | |
| 532 | - | local arg | |
| 533 | - | local passthrough=() | |
| 534 | - | for arg in "$@"; do | |
| 535 | - | if [ "$arg" = "--v2" ]; then | |
| 536 | - | use_v2=1 | |
| 537 | - | else | |
| 538 | - | passthrough+=("$arg") | |
| 539 | - | fi | |
| 540 | - | done | |
| 541 | - | ||
| 542 | - | if [ "$use_v2" -eq 1 ]; then | |
| 543 | - | _plan_build_v2 "${passthrough[@]}" | |
| 544 | - | return $? | |
| 545 | - | fi | |
| 541 | + | local usage="Usage: plan_build [--yolo] [--prompt] [--brainstorm | --writing-plan] | |
| 542 | + | plan_build --architect [--new] [--yolo]" | |
| 546 | 543 | ||
| 547 | 544 | while [ $# -gt 0 ]; do | |
| 548 | 545 | case "$1" in | |
| @@ -555,6 +552,22 @@ plan_build() { | |||
| 555 | 552 | use_yolo=1 | |
| 556 | 553 | claude_args=(--yolo) | |
| 557 | 554 | ;; | |
| 555 | + | --architect) | |
| 556 | + | if [ "$use_architect" -eq 1 ]; then | |
| 557 | + | echo "Error: Duplicate argument: --architect" | |
| 558 | + | echo "$usage" | |
| 559 | + | return 1 | |
| 560 | + | fi | |
| 561 | + | use_architect=1 | |
| 562 | + | ;; | |
| 563 | + | --new) | |
| 564 | + | if [ "$use_new" -eq 1 ]; then | |
| 565 | + | echo "Error: Duplicate argument: --new" | |
| 566 | + | echo "$usage" | |
| 567 | + | return 1 | |
| 568 | + | fi | |
| 569 | + | use_new=1 | |
| 570 | + | ;; | |
| 558 | 571 | --prompt) | |
| 559 | 572 | if [ "$enhance_payload" -eq 1 ]; then | |
| 560 | 573 | echo "Error: Duplicate argument: --prompt" | |
| @@ -598,15 +611,32 @@ plan_build() { | |||
| 598 | 611 | shift | |
| 599 | 612 | done | |
| 600 | 613 | ||
| 601 | - | require_cli claude "Claude Code CLI" || return 1 | |
| 602 | - | if [ "$planning_mode" != "standard" ]; then | |
| 603 | - | _plan_build_superpowers_preflight || return 1 | |
| 614 | + | if [ "$use_new" -eq 1 ] && [ "$use_architect" -ne 1 ]; then | |
| 615 | + | echo "Error: --new requires --architect." | |
| 616 | + | echo "$usage" | |
| 617 | + | return 1 | |
| 604 | 618 | fi | |
| 605 | - | require_cli codex "Codex CLI" || return 1 | |
| 606 | - | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 607 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 608 | - | require_cli auggie "Auggie CLI" || return 1 | |
| 609 | - | require_cli script "script utility" || return 1 | |
| 619 | + | ||
| 620 | + | if [ "$use_architect" -eq 1 ] && | |
| 621 | + | { [ "$enhance_payload" -eq 1 ] || [ "$planning_mode" != "standard" ]; }; then | |
| 622 | + | echo "Error: --architect may combine only with --new and --yolo." | |
| 623 | + | echo "$usage" | |
| 624 | + | return 1 | |
| 625 | + | fi | |
| 626 | + | ||
| 627 | + | if [ "$use_architect" -eq 1 ]; then | |
| 628 | + | _plan_build_architect_preflight || return 1 | |
| 629 | + | else | |
| 630 | + | require_cli claude "Claude Code CLI" || return 1 | |
| 631 | + | if [ "$planning_mode" != "standard" ]; then | |
| 632 | + | _plan_build_superpowers_preflight || return 1 | |
| 633 | + | fi | |
| 634 | + | require_cli codex "Codex CLI" || return 1 | |
| 635 | + | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 636 | + | if [ "$enhance_payload" -eq 1 ]; then | |
| 637 | + | require_cli auggie "Auggie CLI" || return 1 | |
| 638 | + | require_cli script "script utility" || return 1 | |
| 639 | + | fi | |
| 610 | 640 | fi | |
| 611 | 641 | ||
| 612 | 642 | echo "📥 Reading payload... Type 'EOF' on a new line and press Enter when finished." | |
| @@ -676,6 +706,26 @@ plan_build() { | |||
| 676 | 706 | esac | |
| 677 | 707 | fi | |
| 678 | 708 | ||
| 709 | + | if [ "$use_architect" -eq 1 ]; then | |
| 710 | + | local architect_start_mode | |
| 711 | + | if [ "$use_new" -eq 1 ]; then | |
| 712 | + | 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." | |
| 713 | + | else | |
| 714 | + | 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." | |
| 715 | + | fi | |
| 716 | + | ||
| 717 | + | echo "🚀 Launching Claude Code in architect mode..." | |
| 718 | + | ||
| 719 | + | claude "${claude_args[@]}" "Read \`~/.claude/skills/plan-build-architect/SKILL.md\` and follow it strictly, including every gate even when --yolo is active. Stay in the documentation-first architect/orchestrator role: produce and coordinate documentation and planning only, and do not implement the requirement. | |
| 720 | + | ||
| 721 | + | $architect_start_mode | |
| 722 | + | ||
| 723 | + | Use the following payload as the initial requirement: | |
| 724 | + | ||
| 725 | + | $payload" | |
| 726 | + | return $? | |
| 727 | + | fi | |
| 728 | + | ||
| 679 | 729 | local planning_instruction | |
| 680 | 730 | case "$planning_mode" in | |
| 681 | 731 | brainstorm) | |
test_plan_build.zsh
| @@ -29,6 +29,28 @@ assert_contains() { | |||
| 29 | 29 | fi | |
| 30 | 30 | } | |
| 31 | 31 | ||
| 32 | + | assert_not_contains() { | |
| 33 | + | local output="$1" | |
| 34 | + | local unexpected="$2" | |
| 35 | + | local label="$3" | |
| 36 | + | ||
| 37 | + | if [[ "$output" == *"$unexpected"* ]]; then | |
| 38 | + | print -u2 -- "FAIL: $label (unexpected '$unexpected')" | |
| 39 | + | failures=$((failures + 1)) | |
| 40 | + | fi | |
| 41 | + | } | |
| 42 | + | ||
| 43 | + | preflight_fixture_dir="$(mktemp -d "${TMPDIR:-/tmp}/plan-build-preflight.XXXXXX")" | |
| 44 | + | trap 'rm -rf -- "$preflight_fixture_dir"' EXIT | |
| 45 | + | command git init -q "$preflight_fixture_dir/worktree" | |
| 46 | + | command git init -q --bare "$preflight_fixture_dir/bare.git" | |
| 47 | + | ||
| 48 | + | (cd "$preflight_fixture_dir/worktree" && _plan_build_is_worktree) && rc=0 || rc=$? | |
| 49 | + | assert_equal "0" "$rc" "architect preflight accepts normal worktree" | |
| 50 | + | ||
| 51 | + | (cd "$preflight_fixture_dir/bare.git" && _plan_build_is_worktree) && rc=0 || rc=$? | |
| 52 | + | assert_equal "1" "$rc" "architect preflight rejects bare repository" | |
| 53 | + | ||
| 32 | 54 | plugin_state() { | |
| 33 | 55 | printf '%s\n' "$1" | _plan_build_superpowers_state | |
| 34 | 56 | } | |
| @@ -51,6 +73,32 @@ output="$(plan_build --writing-plan --writing-plan 2>&1)" && rc=0 || rc=$? | |||
| 51 | 73 | assert_equal "1" "$rc" "duplicate writing-plan status" | |
| 52 | 74 | assert_contains "$output" "Duplicate argument: --writing-plan" "duplicate writing-plan message" | |
| 53 | 75 | ||
| 76 | + | output="$(plan_build --v2 2>&1)" && rc=0 || rc=$? | |
| 77 | + | assert_equal "1" "$rc" "v2 unknown argument status" | |
| 78 | + | assert_contains "$output" "Unknown argument: --v2" "v2 unknown argument message" | |
| 79 | + | ||
| 80 | + | for args expected label in \ | |
| 81 | + | "--architect --architect" "--architect" "duplicate architect" \ | |
| 82 | + | "--architect --new --new" "--new" "duplicate new"; do | |
| 83 | + | output="$(plan_build ${(z)args} 2>&1)" && rc=0 || rc=$? | |
| 84 | + | assert_equal "1" "$rc" "$label status" | |
| 85 | + | assert_contains "$output" "Duplicate argument: $expected" "$label message" | |
| 86 | + | assert_contains "$output" "plan_build --architect [--new] [--yolo]" "$label usage" | |
| 87 | + | done | |
| 88 | + | ||
| 89 | + | for args in \ | |
| 90 | + | "--architect --prompt" \ | |
| 91 | + | "--architect --brainstorm" \ | |
| 92 | + | "--architect --writing-plan"; do | |
| 93 | + | output="$(plan_build ${(z)args} 2>&1)" && rc=0 || rc=$? | |
| 94 | + | assert_equal "1" "$rc" "$args incompatible status" | |
| 95 | + | assert_contains "$output" "may combine only with --new and --yolo" "$args incompatible message" | |
| 96 | + | done | |
| 97 | + | ||
| 98 | + | output="$(plan_build --new 2>&1)" && rc=0 || rc=$? | |
| 99 | + | assert_equal "1" "$rc" "orphan new status" | |
| 100 | + | assert_contains "$output" "--new requires --architect" "orphan new message" | |
| 101 | + | ||
| 54 | 102 | export CLAUDE_CODE_SAFE_MODE=1 | |
| 55 | 103 | output="$(_plan_build_superpowers_preflight 2>&1)" && rc=0 || rc=$? | |
| 56 | 104 | unset CLAUDE_CODE_SAFE_MODE | |
| @@ -59,6 +107,11 @@ assert_contains "$output" "safe mode disables Superpowers" "safe mode message" | |||
| 59 | 107 | ||
| 60 | 108 | require_cli() { return 0; } | |
| 61 | 109 | _plan_build_superpowers_preflight() { return 0; } | |
| 110 | + | architect_preflight_calls=0 | |
| 111 | + | _plan_build_architect_preflight() { | |
| 112 | + | architect_preflight_calls=$((architect_preflight_calls + 1)) | |
| 113 | + | return 0 | |
| 114 | + | } | |
| 62 | 115 | claude() { | |
| 63 | 116 | printf 'CLAUDE_ARGS:' | |
| 64 | 117 | printf ' <%s>' "$@" | |
| @@ -78,6 +131,37 @@ output="$(printf 'build feature\nEOF\n' | plan_build 2>&1)" && rc=0 || rc=$? | |||
| 78 | 131 | assert_equal "0" "$rc" "standard launch status" | |
| 79 | 132 | assert_contains "$output" "Planning mode: standard" "standard prompt" | |
| 80 | 133 | ||
| 134 | + | output="$(printf 'design feature\nEOF\n' | plan_build --architect 2>&1)" && rc=0 || rc=$? | |
| 135 | + | assert_equal "0" "$rc" "architect launch status" | |
| 136 | + | assert_contains "$output" "~/.claude/skills/plan-build-architect/SKILL.md" "architect skill path" | |
| 137 | + | assert_contains "$output" "documentation-first architect/orchestrator role" "architect role boundary" | |
| 138 | + | assert_contains "$output" "design feature" "architect payload" | |
| 139 | + | assert_contains "$output" "Start mode: safe-resume-detection" "architect resume mode" | |
| 140 | + | ||
| 141 | + | output="$(printf 'fresh design\nEOF\n' | plan_build --architect --new 2>&1)" && rc=0 || rc=$? | |
| 142 | + | assert_equal "0" "$rc" "architect new launch status" | |
| 143 | + | assert_contains "$output" "Start mode: archive-and-start-new" "architect new mode" | |
| 144 | + | assert_contains "$output" "fresh design" "architect new payload" | |
| 145 | + | ||
| 146 | + | output="$(printf 'fast design\nEOF\n' | plan_build --architect --yolo 2>&1)" && rc=0 || rc=$? | |
| 147 | + | assert_equal "0" "$rc" "architect yolo launch status" | |
| 148 | + | assert_contains "$output" "<--yolo>" "architect yolo forwarding" | |
| 149 | + | assert_contains "$output" "every gate even when --yolo is active" "architect yolo gates" | |
| 150 | + | ||
| 151 | + | output="$(printf 'EOF\n' | plan_build --architect 2>&1)" && rc=0 || rc=$? | |
| 152 | + | assert_equal "1" "$rc" "architect empty payload status" | |
| 153 | + | assert_contains "$output" "Payload was empty" "architect empty payload message" | |
| 154 | + | ||
| 155 | + | _plan_build_architect_preflight() { | |
| 156 | + | echo "architect preflight failed" | |
| 157 | + | return 1 | |
| 158 | + | } | |
| 159 | + | output="$(printf 'must not be read\nEOF\n' | plan_build --architect 2>&1)" && rc=0 || rc=$? | |
| 160 | + | assert_equal "1" "$rc" "architect preflight failure status" | |
| 161 | + | assert_contains "$output" "architect preflight failed" "architect preflight failure message" | |
| 162 | + | assert_not_contains "$output" "Reading payload" "architect preflight before payload" | |
| 163 | + | assert_not_contains "$output" "CLAUDE_ARGS" "architect preflight prevents launch" | |
| 164 | + | ||
| 81 | 165 | if [ "$failures" -ne 0 ]; then | |
| 82 | 166 | exit 1 | |
| 83 | 167 | fi | |
Vernon Wee Hong KOH ревизий этого фрагмента 3 weeks ago. К ревизии
8 files changed, 616 insertions
README.md
| @@ -30,3 +30,27 @@ eval "$(starship init zsh)" | |||
| 30 | 30 | ``` | |
| 31 | 31 | ||
| 32 | 32 | Starship owns the prompt and loads after Oh My Zsh. The managed Starship config is installed at `~/.config/starship.toml`. A Nerd Font is required for the Powerline symbols. | |
| 33 | + | ||
| 34 | + | ## Plan-build workflow | |
| 35 | + | ||
| 36 | + | `plan_build` launches Claude Code as the implementation orchestrator, with Codex and CodeRabbit as independent reviewers. The configuration installer also installs its workflow at `~/.claude/skills/plan-build/SKILL.md`. | |
| 37 | + | ||
| 38 | + | ```zsh | |
| 39 | + | plan_build # Standard plan and build | |
| 40 | + | plan_build --prompt # Enhance the payload with Auggie first | |
| 41 | + | plan_build --writing-plan # Superpowers implementation plan, Codex review, then build | |
| 42 | + | plan_build --prompt --brainstorm # Auggie, Superpowers design and plan, Codex review, then build | |
| 43 | + | plan_build --yolo --writing-plan # Pass --yolo through to Claude Code | |
| 44 | + | plan_build --v2 --grill # Run the standalone v2 script (adds --grill and --distribute) | |
| 45 | + | plan_build --v2 --distribute # v2 distributed mode: Codex implements BE, Kimi Code implements FE | |
| 46 | + | ``` | |
| 47 | + | ||
| 48 | + | `--brainstorm` and `--writing-plan` are mutually exclusive. They require the enabled `superpowers@claude-plugins-official` Claude Code plugin; `plan_build` reports the install or enable command and exits before Auggie when the requirement is not met. | |
| 49 | + | ||
| 50 | + | `--v2` downloads and runs the standalone [plan_build v2 script](https://opengist.resetrix.work/weehong/plan-build) on demand, forwarding every other argument to it. v2 adds the `--grill` planning mode (`mattpocock-skills:grilling`) and `--distribute` (backend items implemented by Codex, frontend items by Kimi Code, sequentially, after the FE/BE split is confirmed). `--distribute` additionally requires the `kimi` CLI. Without `--v2`, `plan_build` runs the built-in v1 function unchanged. | |
| 51 | + | ||
| 52 | + | On a machine without this full setup (`config.sh` normally installs the skill), install just the plan-build skill with: | |
| 53 | + | ||
| 54 | + | ```zsh | |
| 55 | + | mkdir -p ~/.claude/skills/plan-build && curl -fsSL https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md -o ~/.claude/skills/plan-build/SKILL.md | |
| 56 | + | ``` | |
config.sh
| @@ -12,6 +12,8 @@ CONFIG_FILES=( | |||
| 12 | 12 | ".zshrc" | |
| 13 | 13 | ".config/starship.toml" | |
| 14 | 14 | ) | |
| 15 | + | PLAN_BUILD_SKILL_TARGET="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 16 | + | ||
| 15 | 17 | echo "Starting configuration download..." | |
| 16 | 18 | download_failed=0 | |
| 17 | 19 | ||
| @@ -36,6 +38,17 @@ for f in "${CONFIG_FILES[@]}"; do | |||
| 36 | 38 | fi | |
| 37 | 39 | done | |
| 38 | 40 | ||
| 41 | + | echo "Downloading Claude Code plan-build workflow..." | |
| 42 | + | mkdir -p "$(dirname "$PLAN_BUILD_SKILL_TARGET")" | |
| 43 | + | skill_tmp="${PLAN_BUILD_SKILL_TARGET}.tmp.$$" | |
| 44 | + | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp" && mv "$skill_tmp" "$PLAN_BUILD_SKILL_TARGET"; then | |
| 45 | + | echo "Successfully updated $PLAN_BUILD_SKILL_TARGET" | |
| 46 | + | else | |
| 47 | + | rm -f "$skill_tmp" | |
| 48 | + | echo "Error: Failed to download the plan-build workflow" >&2 | |
| 49 | + | download_failed=1 | |
| 50 | + | fi | |
| 51 | + | ||
| 39 | 52 | if [ "$download_failed" -ne 0 ]; then | |
| 40 | 53 | echo "Configuration download completed with errors." >&2 | |
| 41 | 54 | exit 1 | |
func
| @@ -427,6 +427,277 @@ prompt() { | |||
| 427 | 427 | command auggie account status | |
| 428 | 428 | } | |
| 429 | 429 | ||
| 430 | + | # ----------------------------------------------------------------------------- | |
| 431 | + | # Function: plan_build (Claude Code multi-agent workflow orchestrator) | |
| 432 | + | # ----------------------------------------------------------------------------- | |
| 433 | + | _plan_build_superpowers_state() { | |
| 434 | + | awk ' | |
| 435 | + | BEGIN { | |
| 436 | + | RS = "}" | |
| 437 | + | state = "missing" | |
| 438 | + | printed = 0 | |
| 439 | + | } | |
| 440 | + | /"id"[[:space:]]*:[[:space:]]*"superpowers@claude-plugins-official"/ { | |
| 441 | + | state = "installed" | |
| 442 | + | if ($0 ~ /"enabled"[[:space:]]*:[[:space:]]*true/) { | |
| 443 | + | state = "enabled" | |
| 444 | + | } else if ($0 ~ /"enabled"[[:space:]]*:[[:space:]]*false/) { | |
| 445 | + | state = "disabled" | |
| 446 | + | } | |
| 447 | + | print state | |
| 448 | + | printed = 1 | |
| 449 | + | exit | |
| 450 | + | } | |
| 451 | + | END { | |
| 452 | + | if (!printed) { | |
| 453 | + | print state | |
| 454 | + | } | |
| 455 | + | } | |
| 456 | + | ' | |
| 457 | + | } | |
| 458 | + | ||
| 459 | + | _plan_build_superpowers_preflight() { | |
| 460 | + | local plugin_json | |
| 461 | + | local plugin_state | |
| 462 | + | ||
| 463 | + | case "${CLAUDE_CODE_SAFE_MODE:-}" in | |
| 464 | + | 1|true|TRUE|yes|YES|on|ON) | |
| 465 | + | echo "❌ Error: Claude Code safe mode disables Superpowers." | |
| 466 | + | echo "Unset CLAUDE_CODE_SAFE_MODE before using --brainstorm or --writing-plan." | |
| 467 | + | return 1 | |
| 468 | + | ;; | |
| 469 | + | esac | |
| 470 | + | ||
| 471 | + | if ! plugin_json="$(command claude plugin list --json 2>/dev/null)"; then | |
| 472 | + | echo "❌ Error: Unable to inspect Claude Code plugins." | |
| 473 | + | echo "Run 'claude plugin list' to diagnose the problem." | |
| 474 | + | return 1 | |
| 475 | + | fi | |
| 476 | + | ||
| 477 | + | plugin_state="$(printf '%s\n' "$plugin_json" | _plan_build_superpowers_state)" | |
| 478 | + | ||
| 479 | + | case "$plugin_state" in | |
| 480 | + | enabled) | |
| 481 | + | return 0 | |
| 482 | + | ;; | |
| 483 | + | disabled) | |
| 484 | + | echo "❌ Error: Claude Code Superpowers is installed but disabled." | |
| 485 | + | echo "Enable it with: claude plugin enable superpowers@claude-plugins-official" | |
| 486 | + | ;; | |
| 487 | + | missing) | |
| 488 | + | echo "❌ Error: Claude Code Superpowers is required for --brainstorm and --writing-plan." | |
| 489 | + | echo "Install it in Claude Code with: /plugin install superpowers@claude-plugins-official" | |
| 490 | + | ;; | |
| 491 | + | *) | |
| 492 | + | echo "❌ Error: Unable to determine Claude Code Superpowers status." | |
| 493 | + | echo "Run 'claude plugin list' to diagnose the problem." | |
| 494 | + | ;; | |
| 495 | + | esac | |
| 496 | + | ||
| 497 | + | return 1 | |
| 498 | + | } | |
| 499 | + | ||
| 500 | + | _plan_build_v2() { | |
| 501 | + | # v2 is the standalone plan_build script (adds --grill and --distribute), | |
| 502 | + | # fetched on demand from its own gist so this function never goes stale. | |
| 503 | + | local v2_url="https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.sh" | |
| 504 | + | local v2_file | |
| 505 | + | local v2_status | |
| 506 | + | ||
| 507 | + | require_cli curl "curl" || return 1 | |
| 508 | + | ||
| 509 | + | v2_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-v2.XXXXXX")" || return 1 | |
| 510 | + | ||
| 511 | + | if ! curl -fsSL "$v2_url" -o "$v2_file"; then | |
| 512 | + | rm -f "$v2_file" | |
| 513 | + | echo "❌ Error: Unable to download plan_build v2 from $v2_url" | |
| 514 | + | return 1 | |
| 515 | + | fi | |
| 516 | + | ||
| 517 | + | bash "$v2_file" "$@" | |
| 518 | + | v2_status=$? | |
| 519 | + | rm -f "$v2_file" | |
| 520 | + | return $v2_status | |
| 521 | + | } | |
| 522 | + | ||
| 523 | + | plan_build() { | |
| 524 | + | local claude_args=() | |
| 525 | + | local use_yolo=0 | |
| 526 | + | local enhance_payload=0 | |
| 527 | + | local planning_mode="standard" | |
| 528 | + | local usage="Usage: plan_build [--v2] [--yolo] [--prompt] [--brainstorm | --writing-plan] | |
| 529 | + | --v2 forwards all other arguments to the standalone v2 script (adds --grill and --distribute)." | |
| 530 | + | ||
| 531 | + | local use_v2=0 | |
| 532 | + | local arg | |
| 533 | + | local passthrough=() | |
| 534 | + | for arg in "$@"; do | |
| 535 | + | if [ "$arg" = "--v2" ]; then | |
| 536 | + | use_v2=1 | |
| 537 | + | else | |
| 538 | + | passthrough+=("$arg") | |
| 539 | + | fi | |
| 540 | + | done | |
| 541 | + | ||
| 542 | + | if [ "$use_v2" -eq 1 ]; then | |
| 543 | + | _plan_build_v2 "${passthrough[@]}" | |
| 544 | + | return $? | |
| 545 | + | fi | |
| 546 | + | ||
| 547 | + | while [ $# -gt 0 ]; do | |
| 548 | + | case "$1" in | |
| 549 | + | --yolo) | |
| 550 | + | if [ "$use_yolo" -eq 1 ]; then | |
| 551 | + | echo "Error: Duplicate argument: --yolo" | |
| 552 | + | echo "$usage" | |
| 553 | + | return 1 | |
| 554 | + | fi | |
| 555 | + | use_yolo=1 | |
| 556 | + | claude_args=(--yolo) | |
| 557 | + | ;; | |
| 558 | + | --prompt) | |
| 559 | + | if [ "$enhance_payload" -eq 1 ]; then | |
| 560 | + | echo "Error: Duplicate argument: --prompt" | |
| 561 | + | echo "$usage" | |
| 562 | + | return 1 | |
| 563 | + | fi | |
| 564 | + | enhance_payload=1 | |
| 565 | + | ;; | |
| 566 | + | --brainstorm) | |
| 567 | + | if [ "$planning_mode" = "brainstorm" ]; then | |
| 568 | + | echo "Error: Duplicate argument: --brainstorm" | |
| 569 | + | echo "$usage" | |
| 570 | + | return 1 | |
| 571 | + | fi | |
| 572 | + | if [ "$planning_mode" != "standard" ]; then | |
| 573 | + | echo "Error: --brainstorm and --writing-plan are mutually exclusive." | |
| 574 | + | echo "$usage" | |
| 575 | + | return 1 | |
| 576 | + | fi | |
| 577 | + | planning_mode="brainstorm" | |
| 578 | + | ;; | |
| 579 | + | --writing-plan) | |
| 580 | + | if [ "$planning_mode" = "writing-plan" ]; then | |
| 581 | + | echo "Error: Duplicate argument: --writing-plan" | |
| 582 | + | echo "$usage" | |
| 583 | + | return 1 | |
| 584 | + | fi | |
| 585 | + | if [ "$planning_mode" != "standard" ]; then | |
| 586 | + | echo "Error: --brainstorm and --writing-plan are mutually exclusive." | |
| 587 | + | echo "$usage" | |
| 588 | + | return 1 | |
| 589 | + | fi | |
| 590 | + | planning_mode="writing-plan" | |
| 591 | + | ;; | |
| 592 | + | *) | |
| 593 | + | echo "Error: Unknown argument: $1" | |
| 594 | + | echo "$usage" | |
| 595 | + | return 1 | |
| 596 | + | ;; | |
| 597 | + | esac | |
| 598 | + | shift | |
| 599 | + | done | |
| 600 | + | ||
| 601 | + | require_cli claude "Claude Code CLI" || return 1 | |
| 602 | + | if [ "$planning_mode" != "standard" ]; then | |
| 603 | + | _plan_build_superpowers_preflight || return 1 | |
| 604 | + | fi | |
| 605 | + | require_cli codex "Codex CLI" || return 1 | |
| 606 | + | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 607 | + | if [ "$enhance_payload" -eq 1 ]; then | |
| 608 | + | require_cli auggie "Auggie CLI" || return 1 | |
| 609 | + | require_cli script "script utility" || return 1 | |
| 610 | + | fi | |
| 611 | + | ||
| 612 | + | echo "📥 Reading payload... Type 'EOF' on a new line and press Enter when finished." | |
| 613 | + | ||
| 614 | + | local payload | |
| 615 | + | local line | |
| 616 | + | payload="" | |
| 617 | + | ||
| 618 | + | while IFS= read -r line; do | |
| 619 | + | [ "$line" = "EOF" ] && break | |
| 620 | + | if [ -z "$payload" ]; then | |
| 621 | + | payload="$line" | |
| 622 | + | else | |
| 623 | + | payload="${payload}"$'\n'"${line}" | |
| 624 | + | fi | |
| 625 | + | done | |
| 626 | + | ||
| 627 | + | if [ -z "$payload" ]; then | |
| 628 | + | echo "❌ Error: Payload was empty." | |
| 629 | + | return 1 | |
| 630 | + | fi | |
| 631 | + | ||
| 632 | + | if [ "$enhance_payload" -eq 1 ]; then | |
| 633 | + | local enhanced_file | |
| 634 | + | local review_reply | |
| 635 | + | enhanced_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-enhanced.XXXXXX")" || return 1 | |
| 636 | + | ||
| 637 | + | echo "✨ Enhancing payload with Auggie..." | |
| 638 | + | if ! _enhance_prompt "$payload" "$enhanced_file"; then | |
| 639 | + | rm -f "$enhanced_file" | |
| 640 | + | echo "❌ Error: Prompt enhancement failed; Claude was not launched." | |
| 641 | + | return 1 | |
| 642 | + | fi | |
| 643 | + | ||
| 644 | + | payload="$(cat "$enhanced_file")" | |
| 645 | + | rm -f "$enhanced_file" | |
| 646 | + | ||
| 647 | + | if [ -z "$payload" ]; then | |
| 648 | + | echo "❌ Error: Enhanced payload was empty; Claude was not launched." | |
| 649 | + | return 1 | |
| 650 | + | fi | |
| 651 | + | ||
| 652 | + | printf '\n%s\n' "━━━━━━━━━━━━━━━━ Auggie enhanced prompt ━━━━━━━━━━━━━━━━" | |
| 653 | + | printf '%s\n' "$payload" | |
| 654 | + | printf '%s\n\n' "━━━━━━━━━━━━━━━━ End enhanced prompt ━━━━━━━━━━━━━━━━━" | |
| 655 | + | ||
| 656 | + | if ! (: </dev/tty) 2>/dev/null; then | |
| 657 | + | echo "❌ Error: Cannot review the enhanced prompt without an interactive terminal; Claude was not launched." | |
| 658 | + | return 1 | |
| 659 | + | fi | |
| 660 | + | ||
| 661 | + | printf "Proceed with this enhanced prompt? (y/N) " >/dev/tty | |
| 662 | + | if ! IFS= read -r review_reply </dev/tty; then | |
| 663 | + | printf '\n' >/dev/tty | |
| 664 | + | echo "🛑 Review cancelled; Claude was not launched." | |
| 665 | + | return 1 | |
| 666 | + | fi | |
| 667 | + | ||
| 668 | + | case "$review_reply" in | |
| 669 | + | y|Y|yes|YES|Yes) | |
| 670 | + | echo "✅ Enhanced prompt approved." | |
| 671 | + | ;; | |
| 672 | + | *) | |
| 673 | + | echo "🛑 Enhanced prompt not approved; Claude was not launched." | |
| 674 | + | return 0 | |
| 675 | + | ;; | |
| 676 | + | esac | |
| 677 | + | fi | |
| 678 | + | ||
| 679 | + | local planning_instruction | |
| 680 | + | case "$planning_mode" in | |
| 681 | + | brainstorm) | |
| 682 | + | 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." | |
| 683 | + | ;; | |
| 684 | + | writing-plan) | |
| 685 | + | 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." | |
| 686 | + | ;; | |
| 687 | + | *) | |
| 688 | + | planning_instruction="Planning mode: standard. Create the workflow's normal short implementation plan." | |
| 689 | + | ;; | |
| 690 | + | esac | |
| 691 | + | ||
| 692 | + | echo "🚀 Launching Claude Code with your multi-agent workflow ($planning_mode planning)..." | |
| 693 | + | ||
| 694 | + | claude "${claude_args[@]}" "Please read \`~/.claude/skills/plan-build/SKILL.md\` and strictly follow the 8-step multi-agent workflow to implement the following task. | |
| 695 | + | ||
| 696 | + | $planning_instruction | |
| 697 | + | ||
| 698 | + | $payload" | |
| 699 | + | } | |
| 700 | + | ||
| 430 | 701 | # ----------------------------------------------------------------------------- | |
| 431 | 702 | # Function: aicommit (Automated Conventional Commit Engine Wrapper) | |
| 432 | 703 | # ----------------------------------------------------------------------------- | |
orchestrate-loop.md(файл создан)
| @@ -0,0 +1,190 @@ | |||
| 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. When `plan_build` supplies "Distribution mode: on", Codex and Kimi Code also become the implementers (backend and frontend respectively) via the Distributed Implementation variant of step 5. | |
| 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 | + | - `grill`: Invoke `mattpocock-skills:grilling` to relentlessly stress-test the payload and your intended approach with the user. After grilling concludes, write the workflow's normal short implementation plan incorporating what survived. | |
| 46 | + | ||
| 47 | + | For either Superpowers mode, save the artifacts at the paths selected by the skills. In `grill` mode, the short implementation plan is the planning artifact. 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. | |
| 48 | + | ||
| 49 | + | If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note. | |
| 50 | + | ||
| 51 | + | ### 4. Codex Plan Review | |
| 52 | + | ||
| 53 | + | Run this step only for `brainstorm`, `writing-plan`, and `grill` 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. | |
| 54 | + | ||
| 55 | + | Recommended prompt shape: | |
| 56 | + | ||
| 57 | + | ```text | |
| 58 | + | 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. | |
| 59 | + | ||
| 60 | + | Task: | |
| 61 | + | <payload> | |
| 62 | + | ||
| 63 | + | Spec: | |
| 64 | + | <spec path, if present> | |
| 65 | + | ||
| 66 | + | Implementation plan: | |
| 67 | + | <plan path> | |
| 68 | + | ``` | |
| 69 | + | ||
| 70 | + | 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. | |
| 71 | + | ||
| 72 | + | In `standard` mode, skip this step and continue directly to implementation. | |
| 73 | + | ||
| 74 | + | ### 5. Implement | |
| 75 | + | ||
| 76 | + | If `plan_build` supplied "Distribution mode: on", skip this step and step 6 | |
| 77 | + | and follow the Distributed Implementation variant (steps 5a–5c) below | |
| 78 | + | instead, then continue at step 7. | |
| 79 | + | ||
| 80 | + | Make the change in small, reviewable edits: | |
| 81 | + | ||
| 82 | + | - Follow existing style and abstractions. | |
| 83 | + | - Add or update tests when behavior changes. | |
| 84 | + | - Update docs only when user-facing usage changes. | |
| 85 | + | - Avoid unrelated refactors and formatting churn. | |
| 86 | + | ||
| 87 | + | After each meaningful edit group, re-check the diff for accidental changes. | |
| 88 | + | ||
| 89 | + | ### Distributed Implementation (distribution mode: on) | |
| 90 | + | ||
| 91 | + | In this variant you orchestrate and review only — you never implement, | |
| 92 | + | not even leftovers. Codex implements backend items; Kimi Code implements | |
| 93 | + | frontend items. | |
| 94 | + | ||
| 95 | + | #### 5a. Split And Confirm | |
| 96 | + | ||
| 97 | + | Tag every work item in the plan as `BE`, `FE`, or `unclear`. Present the | |
| 98 | + | full table to the user (AskUserQuestion) and have them confirm or | |
| 99 | + | reassign each item; `unclear` items must be assigned by the user to `BE` | |
| 100 | + | or `FE`. Dispatch nothing until every item is confirmed. | |
| 101 | + | ||
| 102 | + | #### 5b. Backend Phase (Codex) | |
| 103 | + | ||
| 104 | + | Check `git status` first so pre-existing work is never mixed in or | |
| 105 | + | reverted. Compose a self-contained brief: the task, constraints, the | |
| 106 | + | exact confirmed BE item list with file paths, project conventions, and | |
| 107 | + | validation commands. Dispatch: | |
| 108 | + | ||
| 109 | + | ```bash | |
| 110 | + | codex exec --full-auto "<brief>" | |
| 111 | + | ``` | |
| 112 | + | ||
| 113 | + | Then review the phase diff (`git diff`) yourself for correctness, scope, | |
| 114 | + | and convention fit. Send findings back to Codex as a new brief (findings | |
| 115 | + | plus the original context) — do not fix them yourself. Maximum 2 retry | |
| 116 | + | rounds; if valid findings remain after that, stop and report with the | |
| 117 | + | partial diff intact. | |
| 118 | + | ||
| 119 | + | An empty diff from a delegate counts as a failure: retry once with a | |
| 120 | + | sharpened brief, within the same 2-round bound. If the delegate CLI | |
| 121 | + | crashes or hangs, stop and report, preserving the partial diff. | |
| 122 | + | ||
| 123 | + | #### 5c. Frontend Phase (Kimi Code) | |
| 124 | + | ||
| 125 | + | Check `git status` again, then compose the FE brief the same way, and | |
| 126 | + | additionally include the now-implemented backend API surface (routes, | |
| 127 | + | types, request/response contracts) so the frontend builds against the | |
| 128 | + | real backend. Dispatch: | |
| 129 | + | ||
| 130 | + | ```bash | |
| 131 | + | kimi -p "<brief>" | |
| 132 | + | ``` | |
| 133 | + | ||
| 134 | + | (`-p` runs one prompt non-interactively and manages permissions itself; | |
| 135 | + | it cannot be combined with `--auto` or `--yolo`.) | |
| 136 | + | ||
| 137 | + | Review the phase diff and route findings back to Kimi under the same | |
| 138 | + | 2-round retry bound and failure rules as the backend phase. | |
| 139 | + | ||
| 140 | + | After both phases pass review, skip step 6 (the per-phase reviews above | |
| 141 | + | replace it — Codex cannot impartially review the half it wrote) and | |
| 142 | + | continue at step 7 with the combined diff. | |
| 143 | + | ||
| 144 | + | ### 6. Codex Code Review Pass | |
| 145 | + | ||
| 146 | + | Skip this step in distribution mode; the per-phase reviews in steps | |
| 147 | + | 5b–5c replace it. | |
| 148 | + | ||
| 149 | + | 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. | |
| 150 | + | ||
| 151 | + | Recommended prompt shape: | |
| 152 | + | ||
| 153 | + | ```text | |
| 154 | + | 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. | |
| 155 | + | ||
| 156 | + | Task: | |
| 157 | + | <payload> | |
| 158 | + | ||
| 159 | + | Diff: | |
| 160 | + | <git diff> | |
| 161 | + | ``` | |
| 162 | + | ||
| 163 | + | Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial. | |
| 164 | + | ||
| 165 | + | ### 7. CodeRabbit Review Pass | |
| 166 | + | ||
| 167 | + | Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding. | |
| 168 | + | ||
| 169 | + | If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely. | |
| 170 | + | ||
| 171 | + | ### 8. Validate And Close | |
| 172 | + | ||
| 173 | + | Run the planned validation commands, such as: | |
| 174 | + | ||
| 175 | + | ```bash | |
| 176 | + | npm test | |
| 177 | + | npm run lint | |
| 178 | + | pytest | |
| 179 | + | cargo test | |
| 180 | + | go test ./... | |
| 181 | + | ``` | |
| 182 | + | ||
| 183 | + | 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. | |
| 184 | + | ||
| 185 | + | Before final response: | |
| 186 | + | ||
| 187 | + | - Confirm `git diff` contains only intended changes. | |
| 188 | + | - Summarize what changed. | |
| 189 | + | - Report validation run and result. | |
| 190 | + | - Note any remaining risks or commands that could not run. | |
test_plan_build.zsh(файл создан)
| @@ -0,0 +1,85 @@ | |||
| 1 | + | #!/usr/bin/env zsh | |
| 2 | + | ||
| 3 | + | set -eu | |
| 4 | + | ||
| 5 | + | repo_dir="${0:A:h}" | |
| 6 | + | source "$repo_dir/func" | |
| 7 | + | ||
| 8 | + | failures=0 | |
| 9 | + | ||
| 10 | + | assert_equal() { | |
| 11 | + | local expected="$1" | |
| 12 | + | local actual="$2" | |
| 13 | + | local label="$3" | |
| 14 | + | ||
| 15 | + | if [ "$actual" != "$expected" ]; then | |
| 16 | + | print -u2 -- "FAIL: $label (expected '$expected', got '$actual')" | |
| 17 | + | failures=$((failures + 1)) | |
| 18 | + | fi | |
| 19 | + | } | |
| 20 | + | ||
| 21 | + | assert_contains() { | |
| 22 | + | local output="$1" | |
| 23 | + | local expected="$2" | |
| 24 | + | local label="$3" | |
| 25 | + | ||
| 26 | + | if [[ "$output" != *"$expected"* ]]; then | |
| 27 | + | print -u2 -- "FAIL: $label (missing '$expected')" | |
| 28 | + | failures=$((failures + 1)) | |
| 29 | + | fi | |
| 30 | + | } | |
| 31 | + | ||
| 32 | + | plugin_state() { | |
| 33 | + | printf '%s\n' "$1" | _plan_build_superpowers_state | |
| 34 | + | } | |
| 35 | + | ||
| 36 | + | assert_equal "enabled" "$(plugin_state '[{"id":"superpowers@claude-plugins-official","enabled":true}]')" "compact enabled JSON" | |
| 37 | + | assert_equal "disabled" "$(plugin_state $'[\n {\n "enabled": false,\n "id": "superpowers@claude-plugins-official"\n }\n]')" "reordered disabled JSON" | |
| 38 | + | assert_equal "enabled" "$(plugin_state $'[\n {"enabled": false, "id": "other@market"},\n {"enabled": true, "id": "superpowers@claude-plugins-official"}\n]')" "multiple plugin JSON" | |
| 39 | + | assert_equal "missing" "$(plugin_state '[{"id":"coderabbit@claude-plugins-official","enabled":true}]')" "missing plugin JSON" | |
| 40 | + | assert_equal "installed" "$(plugin_state '[{"id":"superpowers@claude-plugins-official"}]')" "malformed plugin JSON" | |
| 41 | + | ||
| 42 | + | output="$(plan_build --brainstorm --writing-plan 2>&1)" && rc=0 || rc=$? | |
| 43 | + | assert_equal "1" "$rc" "mutually exclusive flags status" | |
| 44 | + | assert_contains "$output" "mutually exclusive" "mutually exclusive flags message" | |
| 45 | + | ||
| 46 | + | output="$(plan_build --brainstorm --brainstorm 2>&1)" && rc=0 || rc=$? | |
| 47 | + | assert_equal "1" "$rc" "duplicate brainstorm status" | |
| 48 | + | assert_contains "$output" "Duplicate argument: --brainstorm" "duplicate brainstorm message" | |
| 49 | + | ||
| 50 | + | output="$(plan_build --writing-plan --writing-plan 2>&1)" && rc=0 || rc=$? | |
| 51 | + | assert_equal "1" "$rc" "duplicate writing-plan status" | |
| 52 | + | assert_contains "$output" "Duplicate argument: --writing-plan" "duplicate writing-plan message" | |
| 53 | + | ||
| 54 | + | export CLAUDE_CODE_SAFE_MODE=1 | |
| 55 | + | output="$(_plan_build_superpowers_preflight 2>&1)" && rc=0 || rc=$? | |
| 56 | + | unset CLAUDE_CODE_SAFE_MODE | |
| 57 | + | assert_equal "1" "$rc" "safe mode status" | |
| 58 | + | assert_contains "$output" "safe mode disables Superpowers" "safe mode message" | |
| 59 | + | ||
| 60 | + | require_cli() { return 0; } | |
| 61 | + | _plan_build_superpowers_preflight() { return 0; } | |
| 62 | + | claude() { | |
| 63 | + | printf 'CLAUDE_ARGS:' | |
| 64 | + | printf ' <%s>' "$@" | |
| 65 | + | printf '\n' | |
| 66 | + | } | |
| 67 | + | ||
| 68 | + | output="$(printf 'build feature\nEOF\n' | plan_build --writing-plan --yolo 2>&1)" && rc=0 || rc=$? | |
| 69 | + | assert_equal "0" "$rc" "writing-plan launch status" | |
| 70 | + | assert_contains "$output" "Planning mode: writing-plan" "writing-plan prompt" | |
| 71 | + | assert_contains "$output" "<--yolo>" "yolo forwarding" | |
| 72 | + | ||
| 73 | + | output="$(printf 'build feature\nEOF\n' | plan_build --brainstorm 2>&1)" && rc=0 || rc=$? | |
| 74 | + | assert_equal "0" "$rc" "brainstorm launch status" | |
| 75 | + | assert_contains "$output" "Planning mode: brainstorm" "brainstorm prompt" | |
| 76 | + | ||
| 77 | + | output="$(printf 'build feature\nEOF\n' | plan_build 2>&1)" && rc=0 || rc=$? | |
| 78 | + | assert_equal "0" "$rc" "standard launch status" | |
| 79 | + | assert_contains "$output" "Planning mode: standard" "standard prompt" | |
| 80 | + | ||
| 81 | + | if [ "$failures" -ne 0 ]; then | |
| 82 | + | exit 1 | |
| 83 | + | fi | |
| 84 | + | ||
| 85 | + | print -- "PASS: plan_build tests" | |
zsh_macos.sh
| @@ -111,6 +111,17 @@ download_configs() { | |||
| 111 | 111 | fi | |
| 112 | 112 | done | |
| 113 | 113 | ||
| 114 | + | local skill_target="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 115 | + | local skill_tmp="${skill_target}.tmp.$$" | |
| 116 | + | mkdir -p "$(dirname "$skill_target")" | |
| 117 | + | log "Fetching orchestrate-loop.md -> .claude/skills/plan-build/SKILL.md ..." | |
| 118 | + | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp"; then | |
| 119 | + | mv "$skill_tmp" "$skill_target" | |
| 120 | + | else | |
| 121 | + | rm -f "$skill_tmp" | |
| 122 | + | warn "Failed to download orchestrate-loop.md" | |
| 123 | + | fi | |
| 124 | + | ||
| 114 | 125 | ok "Configs downloaded (Backup at $backup)" | |
| 115 | 126 | } | |
| 116 | 127 | ||
zsh_ubuntu.sh
| @@ -202,6 +202,17 @@ download_configs() { | |||
| 202 | 202 | fi | |
| 203 | 203 | done | |
| 204 | 204 | ||
| 205 | + | local skill_target="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 206 | + | local skill_tmp="${skill_target}.tmp.$$" | |
| 207 | + | mkdir -p "$(dirname "$skill_target")" | |
| 208 | + | log "Fetching orchestrate-loop.md -> .claude/skills/plan-build/SKILL.md ..." | |
| 209 | + | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp"; then | |
| 210 | + | mv "$skill_tmp" "$skill_target" | |
| 211 | + | else | |
| 212 | + | rm -f "$skill_tmp" | |
| 213 | + | warn "Failed to download orchestrate-loop.md" | |
| 214 | + | fi | |
| 215 | + | ||
| 205 | 216 | ok "Configs downloaded (Backup at $backup)" | |
| 206 | 217 | } | |
| 207 | 218 | ||
zsh_wsl.sh
| @@ -204,6 +204,17 @@ download_configs() { | |||
| 204 | 204 | fi | |
| 205 | 205 | done | |
| 206 | 206 | ||
| 207 | + | local skill_target="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 208 | + | local skill_tmp="${skill_target}.tmp.$$" | |
| 209 | + | mkdir -p "$(dirname "$skill_target")" | |
| 210 | + | log "Fetching orchestrate-loop.md -> .claude/skills/plan-build/SKILL.md ..." | |
| 211 | + | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp"; then | |
| 212 | + | mv "$skill_tmp" "$skill_target" | |
| 213 | + | else | |
| 214 | + | rm -f "$skill_tmp" | |
| 215 | + | warn "Failed to download orchestrate-loop.md" | |
| 216 | + | fi | |
| 217 | + | ||
| 207 | 218 | ok "Configs downloaded (Backup at $backup)" | |
| 208 | 219 | } | |
| 209 | 220 | ||
Vernon Wee Hong KOH ревизий этого фрагмента 3 weeks ago. К ревизии
8 files changed, 616 deletions
README.md
| @@ -30,27 +30,3 @@ eval "$(starship init zsh)" | |||
| 30 | 30 | ``` | |
| 31 | 31 | ||
| 32 | 32 | Starship owns the prompt and loads after Oh My Zsh. The managed Starship config is installed at `~/.config/starship.toml`. A Nerd Font is required for the Powerline symbols. | |
| 33 | - | ||
| 34 | - | ## Plan-build workflow | |
| 35 | - | ||
| 36 | - | `plan_build` launches Claude Code as the implementation orchestrator, with Codex and CodeRabbit as independent reviewers. The configuration installer also installs its workflow at `~/.claude/skills/plan-build/SKILL.md`. | |
| 37 | - | ||
| 38 | - | ```zsh | |
| 39 | - | plan_build # Standard plan and build | |
| 40 | - | plan_build --prompt # Enhance the payload with Auggie first | |
| 41 | - | plan_build --writing-plan # Superpowers implementation plan, Codex review, then build | |
| 42 | - | plan_build --prompt --brainstorm # Auggie, Superpowers design and plan, Codex review, then build | |
| 43 | - | plan_build --yolo --writing-plan # Pass --yolo through to Claude Code | |
| 44 | - | plan_build --v2 --grill # Run the standalone v2 script (adds --grill and --distribute) | |
| 45 | - | plan_build --v2 --distribute # v2 distributed mode: Codex implements BE, Kimi Code implements FE | |
| 46 | - | ``` | |
| 47 | - | ||
| 48 | - | `--brainstorm` and `--writing-plan` are mutually exclusive. They require the enabled `superpowers@claude-plugins-official` Claude Code plugin; `plan_build` reports the install or enable command and exits before Auggie when the requirement is not met. | |
| 49 | - | ||
| 50 | - | `--v2` downloads and runs the standalone [plan_build v2 script](https://opengist.resetrix.work/weehong/plan-build) on demand, forwarding every other argument to it. v2 adds the `--grill` planning mode (`mattpocock-skills:grilling`) and `--distribute` (backend items implemented by Codex, frontend items by Kimi Code, sequentially, after the FE/BE split is confirmed). `--distribute` additionally requires the `kimi` CLI. Without `--v2`, `plan_build` runs the built-in v1 function unchanged. | |
| 51 | - | ||
| 52 | - | On a machine without this full setup (`config.sh` normally installs the skill), install just the plan-build skill with: | |
| 53 | - | ||
| 54 | - | ```zsh | |
| 55 | - | mkdir -p ~/.claude/skills/plan-build && curl -fsSL https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/SKILL.md -o ~/.claude/skills/plan-build/SKILL.md | |
| 56 | - | ``` | |
config.sh
| @@ -12,8 +12,6 @@ CONFIG_FILES=( | |||
| 12 | 12 | ".zshrc" | |
| 13 | 13 | ".config/starship.toml" | |
| 14 | 14 | ) | |
| 15 | - | PLAN_BUILD_SKILL_TARGET="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 16 | - | ||
| 17 | 15 | echo "Starting configuration download..." | |
| 18 | 16 | download_failed=0 | |
| 19 | 17 | ||
| @@ -38,17 +36,6 @@ for f in "${CONFIG_FILES[@]}"; do | |||
| 38 | 36 | fi | |
| 39 | 37 | done | |
| 40 | 38 | ||
| 41 | - | echo "Downloading Claude Code plan-build workflow..." | |
| 42 | - | mkdir -p "$(dirname "$PLAN_BUILD_SKILL_TARGET")" | |
| 43 | - | skill_tmp="${PLAN_BUILD_SKILL_TARGET}.tmp.$$" | |
| 44 | - | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp" && mv "$skill_tmp" "$PLAN_BUILD_SKILL_TARGET"; then | |
| 45 | - | echo "Successfully updated $PLAN_BUILD_SKILL_TARGET" | |
| 46 | - | else | |
| 47 | - | rm -f "$skill_tmp" | |
| 48 | - | echo "Error: Failed to download the plan-build workflow" >&2 | |
| 49 | - | download_failed=1 | |
| 50 | - | fi | |
| 51 | - | ||
| 52 | 39 | if [ "$download_failed" -ne 0 ]; then | |
| 53 | 40 | echo "Configuration download completed with errors." >&2 | |
| 54 | 41 | exit 1 | |
func
| @@ -427,277 +427,6 @@ prompt() { | |||
| 427 | 427 | command auggie account status | |
| 428 | 428 | } | |
| 429 | 429 | ||
| 430 | - | # ----------------------------------------------------------------------------- | |
| 431 | - | # Function: plan_build (Claude Code multi-agent workflow orchestrator) | |
| 432 | - | # ----------------------------------------------------------------------------- | |
| 433 | - | _plan_build_superpowers_state() { | |
| 434 | - | awk ' | |
| 435 | - | BEGIN { | |
| 436 | - | RS = "}" | |
| 437 | - | state = "missing" | |
| 438 | - | printed = 0 | |
| 439 | - | } | |
| 440 | - | /"id"[[:space:]]*:[[:space:]]*"superpowers@claude-plugins-official"/ { | |
| 441 | - | state = "installed" | |
| 442 | - | if ($0 ~ /"enabled"[[:space:]]*:[[:space:]]*true/) { | |
| 443 | - | state = "enabled" | |
| 444 | - | } else if ($0 ~ /"enabled"[[:space:]]*:[[:space:]]*false/) { | |
| 445 | - | state = "disabled" | |
| 446 | - | } | |
| 447 | - | print state | |
| 448 | - | printed = 1 | |
| 449 | - | exit | |
| 450 | - | } | |
| 451 | - | END { | |
| 452 | - | if (!printed) { | |
| 453 | - | print state | |
| 454 | - | } | |
| 455 | - | } | |
| 456 | - | ' | |
| 457 | - | } | |
| 458 | - | ||
| 459 | - | _plan_build_superpowers_preflight() { | |
| 460 | - | local plugin_json | |
| 461 | - | local plugin_state | |
| 462 | - | ||
| 463 | - | case "${CLAUDE_CODE_SAFE_MODE:-}" in | |
| 464 | - | 1|true|TRUE|yes|YES|on|ON) | |
| 465 | - | echo "❌ Error: Claude Code safe mode disables Superpowers." | |
| 466 | - | echo "Unset CLAUDE_CODE_SAFE_MODE before using --brainstorm or --writing-plan." | |
| 467 | - | return 1 | |
| 468 | - | ;; | |
| 469 | - | esac | |
| 470 | - | ||
| 471 | - | if ! plugin_json="$(command claude plugin list --json 2>/dev/null)"; then | |
| 472 | - | echo "❌ Error: Unable to inspect Claude Code plugins." | |
| 473 | - | echo "Run 'claude plugin list' to diagnose the problem." | |
| 474 | - | return 1 | |
| 475 | - | fi | |
| 476 | - | ||
| 477 | - | plugin_state="$(printf '%s\n' "$plugin_json" | _plan_build_superpowers_state)" | |
| 478 | - | ||
| 479 | - | case "$plugin_state" in | |
| 480 | - | enabled) | |
| 481 | - | return 0 | |
| 482 | - | ;; | |
| 483 | - | disabled) | |
| 484 | - | echo "❌ Error: Claude Code Superpowers is installed but disabled." | |
| 485 | - | echo "Enable it with: claude plugin enable superpowers@claude-plugins-official" | |
| 486 | - | ;; | |
| 487 | - | missing) | |
| 488 | - | echo "❌ Error: Claude Code Superpowers is required for --brainstorm and --writing-plan." | |
| 489 | - | echo "Install it in Claude Code with: /plugin install superpowers@claude-plugins-official" | |
| 490 | - | ;; | |
| 491 | - | *) | |
| 492 | - | echo "❌ Error: Unable to determine Claude Code Superpowers status." | |
| 493 | - | echo "Run 'claude plugin list' to diagnose the problem." | |
| 494 | - | ;; | |
| 495 | - | esac | |
| 496 | - | ||
| 497 | - | return 1 | |
| 498 | - | } | |
| 499 | - | ||
| 500 | - | _plan_build_v2() { | |
| 501 | - | # v2 is the standalone plan_build script (adds --grill and --distribute), | |
| 502 | - | # fetched on demand from its own gist so this function never goes stale. | |
| 503 | - | local v2_url="https://opengist.resetrix.work/weehong/plan-build/raw/HEAD/plan_build.sh" | |
| 504 | - | local v2_file | |
| 505 | - | local v2_status | |
| 506 | - | ||
| 507 | - | require_cli curl "curl" || return 1 | |
| 508 | - | ||
| 509 | - | v2_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-v2.XXXXXX")" || return 1 | |
| 510 | - | ||
| 511 | - | if ! curl -fsSL "$v2_url" -o "$v2_file"; then | |
| 512 | - | rm -f "$v2_file" | |
| 513 | - | echo "❌ Error: Unable to download plan_build v2 from $v2_url" | |
| 514 | - | return 1 | |
| 515 | - | fi | |
| 516 | - | ||
| 517 | - | bash "$v2_file" "$@" | |
| 518 | - | v2_status=$? | |
| 519 | - | rm -f "$v2_file" | |
| 520 | - | return $v2_status | |
| 521 | - | } | |
| 522 | - | ||
| 523 | - | plan_build() { | |
| 524 | - | local claude_args=() | |
| 525 | - | local use_yolo=0 | |
| 526 | - | local enhance_payload=0 | |
| 527 | - | local planning_mode="standard" | |
| 528 | - | local usage="Usage: plan_build [--v2] [--yolo] [--prompt] [--brainstorm | --writing-plan] | |
| 529 | - | --v2 forwards all other arguments to the standalone v2 script (adds --grill and --distribute)." | |
| 530 | - | ||
| 531 | - | local use_v2=0 | |
| 532 | - | local arg | |
| 533 | - | local passthrough=() | |
| 534 | - | for arg in "$@"; do | |
| 535 | - | if [ "$arg" = "--v2" ]; then | |
| 536 | - | use_v2=1 | |
| 537 | - | else | |
| 538 | - | passthrough+=("$arg") | |
| 539 | - | fi | |
| 540 | - | done | |
| 541 | - | ||
| 542 | - | if [ "$use_v2" -eq 1 ]; then | |
| 543 | - | _plan_build_v2 "${passthrough[@]}" | |
| 544 | - | return $? | |
| 545 | - | fi | |
| 546 | - | ||
| 547 | - | while [ $# -gt 0 ]; do | |
| 548 | - | case "$1" in | |
| 549 | - | --yolo) | |
| 550 | - | if [ "$use_yolo" -eq 1 ]; then | |
| 551 | - | echo "Error: Duplicate argument: --yolo" | |
| 552 | - | echo "$usage" | |
| 553 | - | return 1 | |
| 554 | - | fi | |
| 555 | - | use_yolo=1 | |
| 556 | - | claude_args=(--yolo) | |
| 557 | - | ;; | |
| 558 | - | --prompt) | |
| 559 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 560 | - | echo "Error: Duplicate argument: --prompt" | |
| 561 | - | echo "$usage" | |
| 562 | - | return 1 | |
| 563 | - | fi | |
| 564 | - | enhance_payload=1 | |
| 565 | - | ;; | |
| 566 | - | --brainstorm) | |
| 567 | - | if [ "$planning_mode" = "brainstorm" ]; then | |
| 568 | - | echo "Error: Duplicate argument: --brainstorm" | |
| 569 | - | echo "$usage" | |
| 570 | - | return 1 | |
| 571 | - | fi | |
| 572 | - | if [ "$planning_mode" != "standard" ]; then | |
| 573 | - | echo "Error: --brainstorm and --writing-plan are mutually exclusive." | |
| 574 | - | echo "$usage" | |
| 575 | - | return 1 | |
| 576 | - | fi | |
| 577 | - | planning_mode="brainstorm" | |
| 578 | - | ;; | |
| 579 | - | --writing-plan) | |
| 580 | - | if [ "$planning_mode" = "writing-plan" ]; then | |
| 581 | - | echo "Error: Duplicate argument: --writing-plan" | |
| 582 | - | echo "$usage" | |
| 583 | - | return 1 | |
| 584 | - | fi | |
| 585 | - | if [ "$planning_mode" != "standard" ]; then | |
| 586 | - | echo "Error: --brainstorm and --writing-plan are mutually exclusive." | |
| 587 | - | echo "$usage" | |
| 588 | - | return 1 | |
| 589 | - | fi | |
| 590 | - | planning_mode="writing-plan" | |
| 591 | - | ;; | |
| 592 | - | *) | |
| 593 | - | echo "Error: Unknown argument: $1" | |
| 594 | - | echo "$usage" | |
| 595 | - | return 1 | |
| 596 | - | ;; | |
| 597 | - | esac | |
| 598 | - | shift | |
| 599 | - | done | |
| 600 | - | ||
| 601 | - | require_cli claude "Claude Code CLI" || return 1 | |
| 602 | - | if [ "$planning_mode" != "standard" ]; then | |
| 603 | - | _plan_build_superpowers_preflight || return 1 | |
| 604 | - | fi | |
| 605 | - | require_cli codex "Codex CLI" || return 1 | |
| 606 | - | require_cli coderabbit "CodeRabbit CLI" || return 1 | |
| 607 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 608 | - | require_cli auggie "Auggie CLI" || return 1 | |
| 609 | - | require_cli script "script utility" || return 1 | |
| 610 | - | fi | |
| 611 | - | ||
| 612 | - | echo "📥 Reading payload... Type 'EOF' on a new line and press Enter when finished." | |
| 613 | - | ||
| 614 | - | local payload | |
| 615 | - | local line | |
| 616 | - | payload="" | |
| 617 | - | ||
| 618 | - | while IFS= read -r line; do | |
| 619 | - | [ "$line" = "EOF" ] && break | |
| 620 | - | if [ -z "$payload" ]; then | |
| 621 | - | payload="$line" | |
| 622 | - | else | |
| 623 | - | payload="${payload}"$'\n'"${line}" | |
| 624 | - | fi | |
| 625 | - | done | |
| 626 | - | ||
| 627 | - | if [ -z "$payload" ]; then | |
| 628 | - | echo "❌ Error: Payload was empty." | |
| 629 | - | return 1 | |
| 630 | - | fi | |
| 631 | - | ||
| 632 | - | if [ "$enhance_payload" -eq 1 ]; then | |
| 633 | - | local enhanced_file | |
| 634 | - | local review_reply | |
| 635 | - | enhanced_file="$(mktemp "${TMPDIR:-/tmp}/plan-build-enhanced.XXXXXX")" || return 1 | |
| 636 | - | ||
| 637 | - | echo "✨ Enhancing payload with Auggie..." | |
| 638 | - | if ! _enhance_prompt "$payload" "$enhanced_file"; then | |
| 639 | - | rm -f "$enhanced_file" | |
| 640 | - | echo "❌ Error: Prompt enhancement failed; Claude was not launched." | |
| 641 | - | return 1 | |
| 642 | - | fi | |
| 643 | - | ||
| 644 | - | payload="$(cat "$enhanced_file")" | |
| 645 | - | rm -f "$enhanced_file" | |
| 646 | - | ||
| 647 | - | if [ -z "$payload" ]; then | |
| 648 | - | echo "❌ Error: Enhanced payload was empty; Claude was not launched." | |
| 649 | - | return 1 | |
| 650 | - | fi | |
| 651 | - | ||
| 652 | - | printf '\n%s\n' "━━━━━━━━━━━━━━━━ Auggie enhanced prompt ━━━━━━━━━━━━━━━━" | |
| 653 | - | printf '%s\n' "$payload" | |
| 654 | - | printf '%s\n\n' "━━━━━━━━━━━━━━━━ End enhanced prompt ━━━━━━━━━━━━━━━━━" | |
| 655 | - | ||
| 656 | - | if ! (: </dev/tty) 2>/dev/null; then | |
| 657 | - | echo "❌ Error: Cannot review the enhanced prompt without an interactive terminal; Claude was not launched." | |
| 658 | - | return 1 | |
| 659 | - | fi | |
| 660 | - | ||
| 661 | - | printf "Proceed with this enhanced prompt? (y/N) " >/dev/tty | |
| 662 | - | if ! IFS= read -r review_reply </dev/tty; then | |
| 663 | - | printf '\n' >/dev/tty | |
| 664 | - | echo "🛑 Review cancelled; Claude was not launched." | |
| 665 | - | return 1 | |
| 666 | - | fi | |
| 667 | - | ||
| 668 | - | case "$review_reply" in | |
| 669 | - | y|Y|yes|YES|Yes) | |
| 670 | - | echo "✅ Enhanced prompt approved." | |
| 671 | - | ;; | |
| 672 | - | *) | |
| 673 | - | echo "🛑 Enhanced prompt not approved; Claude was not launched." | |
| 674 | - | return 0 | |
| 675 | - | ;; | |
| 676 | - | esac | |
| 677 | - | fi | |
| 678 | - | ||
| 679 | - | local planning_instruction | |
| 680 | - | case "$planning_mode" in | |
| 681 | - | brainstorm) | |
| 682 | - | 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." | |
| 683 | - | ;; | |
| 684 | - | writing-plan) | |
| 685 | - | 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." | |
| 686 | - | ;; | |
| 687 | - | *) | |
| 688 | - | planning_instruction="Planning mode: standard. Create the workflow's normal short implementation plan." | |
| 689 | - | ;; | |
| 690 | - | esac | |
| 691 | - | ||
| 692 | - | echo "🚀 Launching Claude Code with your multi-agent workflow ($planning_mode planning)..." | |
| 693 | - | ||
| 694 | - | claude "${claude_args[@]}" "Please read \`~/.claude/skills/plan-build/SKILL.md\` and strictly follow the 8-step multi-agent workflow to implement the following task. | |
| 695 | - | ||
| 696 | - | $planning_instruction | |
| 697 | - | ||
| 698 | - | $payload" | |
| 699 | - | } | |
| 700 | - | ||
| 701 | 430 | # ----------------------------------------------------------------------------- | |
| 702 | 431 | # Function: aicommit (Automated Conventional Commit Engine Wrapper) | |
| 703 | 432 | # ----------------------------------------------------------------------------- | |
orchestrate-loop.md (файл удалён)
| @@ -1,190 +0,0 @@ | |||
| 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. When `plan_build` supplies "Distribution mode: on", Codex and Kimi Code also become the implementers (backend and frontend respectively) via the Distributed Implementation variant of step 5. | |
| 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 | - | - `grill`: Invoke `mattpocock-skills:grilling` to relentlessly stress-test the payload and your intended approach with the user. After grilling concludes, write the workflow's normal short implementation plan incorporating what survived. | |
| 46 | - | ||
| 47 | - | For either Superpowers mode, save the artifacts at the paths selected by the skills. In `grill` mode, the short implementation plan is the planning artifact. 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. | |
| 48 | - | ||
| 49 | - | If the task touches behavior, data, auth, payments, destructive actions, or shared infrastructure, include a rollback or compatibility note. | |
| 50 | - | ||
| 51 | - | ### 4. Codex Plan Review | |
| 52 | - | ||
| 53 | - | Run this step only for `brainstorm`, `writing-plan`, and `grill` 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. | |
| 54 | - | ||
| 55 | - | Recommended prompt shape: | |
| 56 | - | ||
| 57 | - | ```text | |
| 58 | - | 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. | |
| 59 | - | ||
| 60 | - | Task: | |
| 61 | - | <payload> | |
| 62 | - | ||
| 63 | - | Spec: | |
| 64 | - | <spec path, if present> | |
| 65 | - | ||
| 66 | - | Implementation plan: | |
| 67 | - | <plan path> | |
| 68 | - | ``` | |
| 69 | - | ||
| 70 | - | 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. | |
| 71 | - | ||
| 72 | - | In `standard` mode, skip this step and continue directly to implementation. | |
| 73 | - | ||
| 74 | - | ### 5. Implement | |
| 75 | - | ||
| 76 | - | If `plan_build` supplied "Distribution mode: on", skip this step and step 6 | |
| 77 | - | and follow the Distributed Implementation variant (steps 5a–5c) below | |
| 78 | - | instead, then continue at step 7. | |
| 79 | - | ||
| 80 | - | Make the change in small, reviewable edits: | |
| 81 | - | ||
| 82 | - | - Follow existing style and abstractions. | |
| 83 | - | - Add or update tests when behavior changes. | |
| 84 | - | - Update docs only when user-facing usage changes. | |
| 85 | - | - Avoid unrelated refactors and formatting churn. | |
| 86 | - | ||
| 87 | - | After each meaningful edit group, re-check the diff for accidental changes. | |
| 88 | - | ||
| 89 | - | ### Distributed Implementation (distribution mode: on) | |
| 90 | - | ||
| 91 | - | In this variant you orchestrate and review only — you never implement, | |
| 92 | - | not even leftovers. Codex implements backend items; Kimi Code implements | |
| 93 | - | frontend items. | |
| 94 | - | ||
| 95 | - | #### 5a. Split And Confirm | |
| 96 | - | ||
| 97 | - | Tag every work item in the plan as `BE`, `FE`, or `unclear`. Present the | |
| 98 | - | full table to the user (AskUserQuestion) and have them confirm or | |
| 99 | - | reassign each item; `unclear` items must be assigned by the user to `BE` | |
| 100 | - | or `FE`. Dispatch nothing until every item is confirmed. | |
| 101 | - | ||
| 102 | - | #### 5b. Backend Phase (Codex) | |
| 103 | - | ||
| 104 | - | Check `git status` first so pre-existing work is never mixed in or | |
| 105 | - | reverted. Compose a self-contained brief: the task, constraints, the | |
| 106 | - | exact confirmed BE item list with file paths, project conventions, and | |
| 107 | - | validation commands. Dispatch: | |
| 108 | - | ||
| 109 | - | ```bash | |
| 110 | - | codex exec --full-auto "<brief>" | |
| 111 | - | ``` | |
| 112 | - | ||
| 113 | - | Then review the phase diff (`git diff`) yourself for correctness, scope, | |
| 114 | - | and convention fit. Send findings back to Codex as a new brief (findings | |
| 115 | - | plus the original context) — do not fix them yourself. Maximum 2 retry | |
| 116 | - | rounds; if valid findings remain after that, stop and report with the | |
| 117 | - | partial diff intact. | |
| 118 | - | ||
| 119 | - | An empty diff from a delegate counts as a failure: retry once with a | |
| 120 | - | sharpened brief, within the same 2-round bound. If the delegate CLI | |
| 121 | - | crashes or hangs, stop and report, preserving the partial diff. | |
| 122 | - | ||
| 123 | - | #### 5c. Frontend Phase (Kimi Code) | |
| 124 | - | ||
| 125 | - | Check `git status` again, then compose the FE brief the same way, and | |
| 126 | - | additionally include the now-implemented backend API surface (routes, | |
| 127 | - | types, request/response contracts) so the frontend builds against the | |
| 128 | - | real backend. Dispatch: | |
| 129 | - | ||
| 130 | - | ```bash | |
| 131 | - | kimi -p "<brief>" | |
| 132 | - | ``` | |
| 133 | - | ||
| 134 | - | (`-p` runs one prompt non-interactively and manages permissions itself; | |
| 135 | - | it cannot be combined with `--auto` or `--yolo`.) | |
| 136 | - | ||
| 137 | - | Review the phase diff and route findings back to Kimi under the same | |
| 138 | - | 2-round retry bound and failure rules as the backend phase. | |
| 139 | - | ||
| 140 | - | After both phases pass review, skip step 6 (the per-phase reviews above | |
| 141 | - | replace it — Codex cannot impartially review the half it wrote) and | |
| 142 | - | continue at step 7 with the combined diff. | |
| 143 | - | ||
| 144 | - | ### 6. Codex Code Review Pass | |
| 145 | - | ||
| 146 | - | Skip this step in distribution mode; the per-phase reviews in steps | |
| 147 | - | 5b–5c replace it. | |
| 148 | - | ||
| 149 | - | 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. | |
| 150 | - | ||
| 151 | - | Recommended prompt shape: | |
| 152 | - | ||
| 153 | - | ```text | |
| 154 | - | 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. | |
| 155 | - | ||
| 156 | - | Task: | |
| 157 | - | <payload> | |
| 158 | - | ||
| 159 | - | Diff: | |
| 160 | - | <git diff> | |
| 161 | - | ``` | |
| 162 | - | ||
| 163 | - | Apply fixes for valid findings, then repeat this review pass if the fixes are non-trivial. | |
| 164 | - | ||
| 165 | - | ### 7. CodeRabbit Review Pass | |
| 166 | - | ||
| 167 | - | Run CodeRabbit on the branch or diff when available. Treat its output as advisory but investigate every concrete finding. | |
| 168 | - | ||
| 169 | - | If CodeRabbit cannot run locally, record the command attempted and the failure. Continue with manual validation rather than blocking indefinitely. | |
| 170 | - | ||
| 171 | - | ### 8. Validate And Close | |
| 172 | - | ||
| 173 | - | Run the planned validation commands, such as: | |
| 174 | - | ||
| 175 | - | ```bash | |
| 176 | - | npm test | |
| 177 | - | npm run lint | |
| 178 | - | pytest | |
| 179 | - | cargo test | |
| 180 | - | go test ./... | |
| 181 | - | ``` | |
| 182 | - | ||
| 183 | - | 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. | |
| 184 | - | ||
| 185 | - | Before final response: | |
| 186 | - | ||
| 187 | - | - Confirm `git diff` contains only intended changes. | |
| 188 | - | - Summarize what changed. | |
| 189 | - | - Report validation run and result. | |
| 190 | - | - Note any remaining risks or commands that could not run. | |
test_plan_build.zsh (файл удалён)
| @@ -1,85 +0,0 @@ | |||
| 1 | - | #!/usr/bin/env zsh | |
| 2 | - | ||
| 3 | - | set -eu | |
| 4 | - | ||
| 5 | - | repo_dir="${0:A:h}" | |
| 6 | - | source "$repo_dir/func" | |
| 7 | - | ||
| 8 | - | failures=0 | |
| 9 | - | ||
| 10 | - | assert_equal() { | |
| 11 | - | local expected="$1" | |
| 12 | - | local actual="$2" | |
| 13 | - | local label="$3" | |
| 14 | - | ||
| 15 | - | if [ "$actual" != "$expected" ]; then | |
| 16 | - | print -u2 -- "FAIL: $label (expected '$expected', got '$actual')" | |
| 17 | - | failures=$((failures + 1)) | |
| 18 | - | fi | |
| 19 | - | } | |
| 20 | - | ||
| 21 | - | assert_contains() { | |
| 22 | - | local output="$1" | |
| 23 | - | local expected="$2" | |
| 24 | - | local label="$3" | |
| 25 | - | ||
| 26 | - | if [[ "$output" != *"$expected"* ]]; then | |
| 27 | - | print -u2 -- "FAIL: $label (missing '$expected')" | |
| 28 | - | failures=$((failures + 1)) | |
| 29 | - | fi | |
| 30 | - | } | |
| 31 | - | ||
| 32 | - | plugin_state() { | |
| 33 | - | printf '%s\n' "$1" | _plan_build_superpowers_state | |
| 34 | - | } | |
| 35 | - | ||
| 36 | - | assert_equal "enabled" "$(plugin_state '[{"id":"superpowers@claude-plugins-official","enabled":true}]')" "compact enabled JSON" | |
| 37 | - | assert_equal "disabled" "$(plugin_state $'[\n {\n "enabled": false,\n "id": "superpowers@claude-plugins-official"\n }\n]')" "reordered disabled JSON" | |
| 38 | - | assert_equal "enabled" "$(plugin_state $'[\n {"enabled": false, "id": "other@market"},\n {"enabled": true, "id": "superpowers@claude-plugins-official"}\n]')" "multiple plugin JSON" | |
| 39 | - | assert_equal "missing" "$(plugin_state '[{"id":"coderabbit@claude-plugins-official","enabled":true}]')" "missing plugin JSON" | |
| 40 | - | assert_equal "installed" "$(plugin_state '[{"id":"superpowers@claude-plugins-official"}]')" "malformed plugin JSON" | |
| 41 | - | ||
| 42 | - | output="$(plan_build --brainstorm --writing-plan 2>&1)" && rc=0 || rc=$? | |
| 43 | - | assert_equal "1" "$rc" "mutually exclusive flags status" | |
| 44 | - | assert_contains "$output" "mutually exclusive" "mutually exclusive flags message" | |
| 45 | - | ||
| 46 | - | output="$(plan_build --brainstorm --brainstorm 2>&1)" && rc=0 || rc=$? | |
| 47 | - | assert_equal "1" "$rc" "duplicate brainstorm status" | |
| 48 | - | assert_contains "$output" "Duplicate argument: --brainstorm" "duplicate brainstorm message" | |
| 49 | - | ||
| 50 | - | output="$(plan_build --writing-plan --writing-plan 2>&1)" && rc=0 || rc=$? | |
| 51 | - | assert_equal "1" "$rc" "duplicate writing-plan status" | |
| 52 | - | assert_contains "$output" "Duplicate argument: --writing-plan" "duplicate writing-plan message" | |
| 53 | - | ||
| 54 | - | export CLAUDE_CODE_SAFE_MODE=1 | |
| 55 | - | output="$(_plan_build_superpowers_preflight 2>&1)" && rc=0 || rc=$? | |
| 56 | - | unset CLAUDE_CODE_SAFE_MODE | |
| 57 | - | assert_equal "1" "$rc" "safe mode status" | |
| 58 | - | assert_contains "$output" "safe mode disables Superpowers" "safe mode message" | |
| 59 | - | ||
| 60 | - | require_cli() { return 0; } | |
| 61 | - | _plan_build_superpowers_preflight() { return 0; } | |
| 62 | - | claude() { | |
| 63 | - | printf 'CLAUDE_ARGS:' | |
| 64 | - | printf ' <%s>' "$@" | |
| 65 | - | printf '\n' | |
| 66 | - | } | |
| 67 | - | ||
| 68 | - | output="$(printf 'build feature\nEOF\n' | plan_build --writing-plan --yolo 2>&1)" && rc=0 || rc=$? | |
| 69 | - | assert_equal "0" "$rc" "writing-plan launch status" | |
| 70 | - | assert_contains "$output" "Planning mode: writing-plan" "writing-plan prompt" | |
| 71 | - | assert_contains "$output" "<--yolo>" "yolo forwarding" | |
| 72 | - | ||
| 73 | - | output="$(printf 'build feature\nEOF\n' | plan_build --brainstorm 2>&1)" && rc=0 || rc=$? | |
| 74 | - | assert_equal "0" "$rc" "brainstorm launch status" | |
| 75 | - | assert_contains "$output" "Planning mode: brainstorm" "brainstorm prompt" | |
| 76 | - | ||
| 77 | - | output="$(printf 'build feature\nEOF\n' | plan_build 2>&1)" && rc=0 || rc=$? | |
| 78 | - | assert_equal "0" "$rc" "standard launch status" | |
| 79 | - | assert_contains "$output" "Planning mode: standard" "standard prompt" | |
| 80 | - | ||
| 81 | - | if [ "$failures" -ne 0 ]; then | |
| 82 | - | exit 1 | |
| 83 | - | fi | |
| 84 | - | ||
| 85 | - | print -- "PASS: plan_build tests" | |
zsh_macos.sh
| @@ -111,17 +111,6 @@ download_configs() { | |||
| 111 | 111 | fi | |
| 112 | 112 | done | |
| 113 | 113 | ||
| 114 | - | local skill_target="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 115 | - | local skill_tmp="${skill_target}.tmp.$$" | |
| 116 | - | mkdir -p "$(dirname "$skill_target")" | |
| 117 | - | log "Fetching orchestrate-loop.md -> .claude/skills/plan-build/SKILL.md ..." | |
| 118 | - | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp"; then | |
| 119 | - | mv "$skill_tmp" "$skill_target" | |
| 120 | - | else | |
| 121 | - | rm -f "$skill_tmp" | |
| 122 | - | warn "Failed to download orchestrate-loop.md" | |
| 123 | - | fi | |
| 124 | - | ||
| 125 | 114 | ok "Configs downloaded (Backup at $backup)" | |
| 126 | 115 | } | |
| 127 | 116 | ||
zsh_ubuntu.sh
| @@ -202,17 +202,6 @@ download_configs() { | |||
| 202 | 202 | fi | |
| 203 | 203 | done | |
| 204 | 204 | ||
| 205 | - | local skill_target="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 206 | - | local skill_tmp="${skill_target}.tmp.$$" | |
| 207 | - | mkdir -p "$(dirname "$skill_target")" | |
| 208 | - | log "Fetching orchestrate-loop.md -> .claude/skills/plan-build/SKILL.md ..." | |
| 209 | - | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp"; then | |
| 210 | - | mv "$skill_tmp" "$skill_target" | |
| 211 | - | else | |
| 212 | - | rm -f "$skill_tmp" | |
| 213 | - | warn "Failed to download orchestrate-loop.md" | |
| 214 | - | fi | |
| 215 | - | ||
| 216 | 205 | ok "Configs downloaded (Backup at $backup)" | |
| 217 | 206 | } | |
| 218 | 207 | ||
zsh_wsl.sh
| @@ -204,17 +204,6 @@ download_configs() { | |||
| 204 | 204 | fi | |
| 205 | 205 | done | |
| 206 | 206 | ||
| 207 | - | local skill_target="$HOME/.claude/skills/plan-build/SKILL.md" | |
| 208 | - | local skill_tmp="${skill_target}.tmp.$$" | |
| 209 | - | mkdir -p "$(dirname "$skill_target")" | |
| 210 | - | log "Fetching orchestrate-loop.md -> .claude/skills/plan-build/SKILL.md ..." | |
| 211 | - | if curl -fsSL "$GIST_RAW_BASE/orchestrate-loop.md" -o "$skill_tmp"; then | |
| 212 | - | mv "$skill_tmp" "$skill_target" | |
| 213 | - | else | |
| 214 | - | rm -f "$skill_tmp" | |
| 215 | - | warn "Failed to download orchestrate-loop.md" | |
| 216 | - | fi | |
| 217 | - | ||
| 218 | 207 | ok "Configs downloaded (Backup at $backup)" | |
| 219 | 208 | } | |
| 220 | 209 | ||
Vernon Wee Hong KOH ревизий этого фрагмента 3 weeks ago. К ревизии
1 file changed, 28 insertions, 2 deletions
vimrc
| @@ -34,7 +34,33 @@ set wrap | |||
| 34 | 34 | " Enable mouse support | |
| 35 | 35 | set mouse=a | |
| 36 | 36 | ||
| 37 | - | " Enable clipboard access | |
| 37 | + | " Use Wayland's clipboard tools when this Vim lacks native clipboard support | |
| 38 | + | if !has('clipboard') && exists('v:clipproviders') | |
| 39 | + | \ && executable('wl-copy') && executable('wl-paste') | |
| 40 | + | function! s:WaylandCopy(register, type, lines) abort | |
| 41 | + | let l:text = join(a:lines, "\n") | |
| 42 | + | if a:type ==# 'V' | |
| 43 | + | let l:text ..= "\n" | |
| 44 | + | endif | |
| 45 | + | call system('wl-copy', l:text) | |
| 46 | + | endfunction | |
| 47 | + | ||
| 48 | + | function! s:WaylandPaste(register) abort | |
| 49 | + | return ['', systemlist('wl-paste --no-newline')] | |
| 50 | + | endfunction | |
| 51 | + | ||
| 52 | + | let v:clipproviders['wltools'] = { | |
| 53 | + | \ 'copy': { | |
| 54 | + | \ '+': function('s:WaylandCopy'), | |
| 55 | + | \ '*': function('s:WaylandCopy') | |
| 56 | + | \ }, | |
| 57 | + | \ 'paste': { | |
| 58 | + | \ '+': function('s:WaylandPaste'), | |
| 59 | + | \ '*': function('s:WaylandPaste') | |
| 60 | + | \ } | |
| 61 | + | \ } | |
| 62 | + | set clipmethod^=wltools | |
| 63 | + | endif | |
| 38 | 64 | set clipboard=unnamedplus | |
| 39 | 65 | ||
| 40 | 66 | " Disable swap file | |
| @@ -143,4 +169,4 @@ set formatoptions+=l " Don't break lines that were already long | |||
| 143 | 169 | syntax on | |
| 144 | 170 | ||
| 145 | 171 | " Increase memory limit for complex syntax parsing (Prevents E363) | |
| 146 | - | set maxmempattern=20000 | |
| 172 | + | set maxmempattern=20000 | |
Новее
Позже