diff --git a/codex/skills/brainstorming/SKILL.md b/codex/skills/brainstorming/SKILL.md index 724dc79..edbc2b5 100644 --- a/codex/skills/brainstorming/SKILL.md +++ b/codex/skills/brainstorming/SKILL.md @@ -27,7 +27,7 @@ You MUST create a task for each of these items and complete them in order: 4. **Propose 2-3 approaches** — with trade-offs and your recommendation 5. **Present design** — in sections scaled to their complexity, get user approval after each section 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit -7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 5 iterations, then surface to human) +7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 3 iterations, then surface to human) 8. **User reviews written spec** — ask user to review the spec file before proceeding 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan @@ -121,7 +121,7 @@ After writing the spec document: 1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md) 2. If Issues Found: fix, re-dispatch, repeat until Approved -3. If loop exceeds 5 iterations, surface to human for guidance +3. If loop exceeds 3 iterations, surface to human for guidance **User Review Gate:** After the spec review loop passes, ask the user to review the written spec before proceeding: diff --git a/codex/skills/brainstorming/scripts/server.js b/codex/skills/brainstorming/scripts/server.js index dec2f7a..86c3080 100644 --- a/codex/skills/brainstorming/scripts/server.js +++ b/codex/skills/brainstorming/scripts/server.js @@ -94,7 +94,7 @@ const WAITING_PAGE = ` h1 { color: #333; } p { color: #666; }

Brainstorm Companion

-

Waiting for Claude to push a screen...

`; +

Waiting for the agent to push a screen...

`; const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8'); const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8'); diff --git a/codex/skills/brainstorming/scripts/start-server.sh b/codex/skills/brainstorming/scripts/start-server.sh index b5f5a75..a60025c 100755 --- a/codex/skills/brainstorming/scripts/start-server.sh +++ b/codex/skills/brainstorming/scripts/start-server.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Start the brainstorm server and output connection info # Usage: start-server.sh [--project-dir ] [--host ] [--url-host ] [--foreground] [--background] # @@ -64,6 +64,16 @@ if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "t FOREGROUND="true" fi +# Windows/Git Bash reaps nohup background processes. Auto-foreground when detected. +if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then + case "${OSTYPE:-}" in + msys*|cygwin*|mingw*) FOREGROUND="true" ;; + esac + if [[ -n "${MSYSTEM:-}" ]]; then + FOREGROUND="true" + fi +fi + # Generate unique session directory SESSION_ID="$$-$(date +%s)" diff --git a/codex/skills/brainstorming/scripts/stop-server.sh b/codex/skills/brainstorming/scripts/stop-server.sh index c3724de..2e5973d 100755 --- a/codex/skills/brainstorming/scripts/stop-server.sh +++ b/codex/skills/brainstorming/scripts/stop-server.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Stop the brainstorm server and clean up # Usage: stop-server.sh # @@ -17,7 +17,31 @@ PID_FILE="${SCREEN_DIR}/.server.pid" if [[ -f "$PID_FILE" ]]; then pid=$(cat "$PID_FILE") - kill "$pid" 2>/dev/null + + # Try to stop gracefully, fallback to force if still alive + kill "$pid" 2>/dev/null || true + + # Wait for graceful shutdown (up to ~2s) + for i in {1..20}; do + if ! kill -0 "$pid" 2>/dev/null; then + break + fi + sleep 0.1 + done + + # If still running, escalate to SIGKILL + if kill -0 "$pid" 2>/dev/null; then + kill -9 "$pid" 2>/dev/null || true + + # Give SIGKILL a moment to take effect + sleep 0.1 + fi + + if kill -0 "$pid" 2>/dev/null; then + echo '{"status": "failed", "error": "process still running"}' + exit 1 + fi + rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log" # Only delete ephemeral /tmp directories diff --git a/codex/skills/brainstorming/spec-document-reviewer-prompt.md b/codex/skills/brainstorming/spec-document-reviewer-prompt.md index 212b36c..35acbb6 100644 --- a/codex/skills/brainstorming/spec-document-reviewer-prompt.md +++ b/codex/skills/brainstorming/spec-document-reviewer-prompt.md @@ -19,32 +19,31 @@ Task tool (general-purpose): | Category | What to Look For | |----------|------------------| | Completeness | TODOs, placeholders, "TBD", incomplete sections | - | Coverage | Missing error handling, edge cases, integration points | | Consistency | Internal contradictions, conflicting requirements | - | Clarity | Ambiguous requirements | - | YAGNI | Unrequested features, over-engineering | + | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing | | Scope | Focused enough for a single plan — not covering multiple independent subsystems | - | Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable | + | YAGNI | Unrequested features, over-engineering | - ## CRITICAL + ## Calibration - Look especially hard for: - - Any TODO markers or placeholder text - - Sections saying "to be defined later" or "will spec when X is done" - - Sections noticeably less detailed than others - - Units that lack clear boundaries or interfaces — can you understand what each unit does without reading its internals? + **Only flag issues that would cause real problems during implementation planning.** + A missing section, a contradiction, or a requirement so ambiguous it could be + interpreted two different ways — those are issues. Minor wording improvements, + stylistic preferences, and "sections less detailed than others" are not. + + Approve unless there are serious gaps that would lead to a flawed plan. ## Output Format ## Spec Review - **Status:** ✅ Approved | ❌ Issues Found + **Status:** Approved | Issues Found **Issues (if any):** - - [Section X]: [specific issue] - [why it matters] + - [Section X]: [specific issue] - [why it matters for planning] - **Recommendations (advisory):** - - [suggestions that don't block approval] + **Recommendations (advisory, do not block approval):** + - [suggestions for improvement] ``` **Reviewer returns:** Status, Issues (if any), Recommendations diff --git a/codex/skills/brainstorming/visual-companion.md b/codex/skills/brainstorming/visual-companion.md index a25e85a..2c35d5d 100644 --- a/codex/skills/brainstorming/visual-companion.md +++ b/codex/skills/brainstorming/visual-companion.md @@ -61,6 +61,14 @@ scripts/start-server.sh --project-dir /path/to/project scripts/start-server.sh --project-dir /path/to/project ``` +**Windows (Git Bash / CMD / PowerShell):** +```bash +# Windows/Git Bash reaps nohup background processes. The script auto-detects +# this via OSTYPE/MSYSTEM and switches to foreground mode automatically. +# No extra flags needed — all Windows shells route through Git Bash. +scripts/start-server.sh --project-dir /path/to/project +``` + **Gemini CLI:** ```bash # Use --foreground and set is_background: true on your shell tool call diff --git a/codex/skills/using-superpowers/references/codex-tools.md b/codex/skills/using-superpowers/references/codex-tools.md index eb23075..86f58fa 100644 --- a/codex/skills/using-superpowers/references/codex-tools.md +++ b/codex/skills/using-superpowers/references/codex-tools.md @@ -13,13 +13,13 @@ Skills use Claude Code tool names. When you encounter these in a skill, use your | `Read`, `Write`, `Edit` (files) | Use your native file tools | | `Bash` (run commands) | Use your native shell tools | -## Subagent dispatch requires collab +## Subagent dispatch requires multi-agent support Add to your Codex config (`~/.codex/config.toml`): ```toml [features] -collab = true +multi_agent = true ``` This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. diff --git a/codex/skills/writing-plans/SKILL.md b/codex/skills/writing-plans/SKILL.md index ed67c5e..26bae9a 100644 --- a/codex/skills/writing-plans/SKILL.md +++ b/codex/skills/writing-plans/SKILL.md @@ -112,22 +112,17 @@ git commit -m "feat: add specific feature" ## Plan Review Loop -After completing each chunk of the plan: +After writing the complete plan: -1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process. - - Provide: chunk content, path to spec document -2. If ❌ Issues Found: - - Fix the issues in the chunk - - Re-dispatch reviewer for that chunk - - Repeat until ✅ Approved -3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk) - -**Chunk boundaries:** Use `## Chunk N: ` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained. +1. Dispatch a single plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process. + - Provide: path to the plan document, path to spec document +2. If ❌ Issues Found: fix the issues, re-dispatch reviewer for the whole plan +3. If ✅ Approved: proceed to execution handoff **Review loop guidance:** - Same agent that wrote the plan fixes it (preserves context) -- If loop exceeds 5 iterations, surface to human for guidance -- Reviewers are advisory - explain disagreements if you believe feedback is incorrect +- If loop exceeds 3 iterations, surface to human for guidance +- Reviewers are advisory — explain disagreements if you believe feedback is incorrect ## Execution Handoff diff --git a/codex/skills/writing-plans/plan-document-reviewer-prompt.md b/codex/skills/writing-plans/plan-document-reviewer-prompt.md index ce36cba..2db2806 100644 --- a/codex/skills/writing-plans/plan-document-reviewer-prompt.md +++ b/codex/skills/writing-plans/plan-document-reviewer-prompt.md @@ -2,17 +2,17 @@ Use this template when dispatching a plan document reviewer subagent. -**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition. +**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition. -**Dispatch after:** Each plan chunk is written +**Dispatch after:** The complete plan is written. ``` Task tool (general-purpose): - description: "Review plan chunk N" + description: "Review plan document" prompt: | - You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation. + You are a plan document reviewer. Verify this plan is complete and ready for implementation. - **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only + **Plan to review:** [PLAN_FILE_PATH] **Spec for reference:** [SPEC_FILE_PATH] ## What to Check @@ -20,33 +20,30 @@ Task tool (general-purpose): | Category | What to Look For | |----------|------------------| | Completeness | TODOs, placeholders, incomplete tasks, missing steps | - | Spec Alignment | Chunk covers relevant spec requirements, no scope creep | - | Task Decomposition | Tasks atomic, clear boundaries, steps actionable | - | File Structure | Files have clear single responsibilities, split by responsibility not layer | - | File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? | - | Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking | - | Chunk Size | Each chunk under 1000 lines | + | Spec Alignment | Plan covers spec requirements, no major scope creep | + | Task Decomposition | Tasks have clear boundaries, steps are actionable | + | Buildability | Could an engineer follow this plan without getting stuck? | - ## CRITICAL + ## Calibration - Look especially hard for: - - Any TODO markers or placeholder text - - Steps that say "similar to X" without actual content - - Incomplete task definitions - - Missing verification steps or expected outputs - - Files planned to hold multiple responsibilities or likely to grow unwieldy + **Only flag issues that would cause real problems during implementation.** + An implementer building the wrong thing or getting stuck is an issue. + Minor wording, stylistic preferences, and "nice to have" suggestions are not. + + Approve unless there are serious gaps — missing requirements from the spec, + contradictory steps, placeholder content, or tasks so vague they can't be acted on. ## Output Format - ## Plan Review - Chunk N + ## Plan Review **Status:** Approved | Issues Found **Issues (if any):** - - [Task X, Step Y]: [specific issue] - [why it matters] + - [Task X, Step Y]: [specific issue] - [why it matters for implementation] - **Recommendations (advisory):** - - [suggestions that don't block approval] + **Recommendations (advisory, do not block approval):** + - [suggestions for improvement] ``` **Reviewer returns:** Status, Issues (if any), Recommendations