OpenParable
Skip to content
← Back to skills

Plan Write

Productivity
plan-write

Plan Write is an Agent Skill for productivity published in the besimple-oss/broccoli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/besimple-oss/broccoli/blob/HEAD/prompt-templates/skills/plan-write/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/plan-write, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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).