plan-write

name	plan-write
description	Write a detailed, self-contained implementation plan to a new Markdown file under plan/. Use when you already have a sketch/requirements and want a plan doc before coding.

Write Plan Doc

Preconditions

• Confirm you are in the intended repo: git rev-parse --show-toplevel
• Do not start implementation in this skill; only write/update the plan document.
• Plan critique is a separate step (use plan-critique-loop); plan-write does not run critique internally.

Expected runtime

Typically runs 15–45 minutes. Callers should allow the full --timeout (default 3600s) before interrupting.

If you use --progress-log, do not tail -f it into the main context unless you must debug; prefer checking progress via log line counts (for example: wc -l <progress-log>) and/or the heartbeat counters.

Workflow — Option A (external script, preferred)

Run the plan-write as a standalone CLI invocation:

resolve_skill_dir() {
  local name="$1"
  local repo_root=""
  repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

  local candidates=(
    "$repo_root/.agents/skills/$name"
    "$repo_root/.claude/skills/$name"
    "$HOME/.agents/skills/$name"
    "$HOME/.codex/skills/$name"
    "$HOME/.claude/skills/$name"
  )

  for d in "${candidates[@]}"; do
    if [[ -d "$d" ]]; then
      echo "$d"
      return 0
    fi
  done

  echo "Error: skill '$name' not found in repo-scoped or user-scoped skill dirs." >&2
  return 1
}

PLAN_WRITE_SKILL_DIR="$(resolve_skill_dir plan-write)"
python3 "$PLAN_WRITE_SKILL_DIR/scripts/run_plan_write.py" sketch/<generated-name>.md

Flags:

• --cli codex|claude — override auto-detected CLI
• --model MODEL — pass a specific model to the CLI
• --reasoning-effort LEVEL — pass explicit reasoning effort (vhigh aliases to xhigh)
• --timeout N — CLI invocation timeout in seconds (default: 3600)
• --progress-log PATH — optional path to append streamed subagent output
• --heartbeat-seconds N — heartbeat cadence in seconds (0 disables)

Default behavior:

• When using Codex and no overrides are provided, the script uses --model gpt-5.2 with high reasoning effort.
• When using Codex, the script always runs with --sandbox danger-full-access, -a never, and --search so it can do bounded official-doc research when “latest” matters.

The first positional argument can be a sketch file path (for example under sketch/) or raw sketch text. The script prints the created plan doc path to stdout on success.

Workflow — Option B (inline, legacy)

1. Open references/prompts/plan-output.md.
2. Provide your sketch/notes/requirements as $ARGUMENTS.
3. Ensure the prompt writes a new file under plan/ (kebab-case; do not overwrite).
4. In your response, clearly state the final path you wrote (for example: plan/<generated-name>.md).