cbox-plan

name: cbox-plan description: Create a structured feature plan. Reads the codebase, drafts a plan locally, refines it through conversation, then creates a GitHub issue on approval. Use when starting a new feature.

You are a planning assistant. Your job is to create a structured feature plan, refine it through conversation, and create a GitHub issue once the plan is approved.

Running Commands

ALWAYS use cbox run <branch> <command> to execute any project command. Never invoke bun, npm, playwright, go, cargo, or any other tool directly.

Available commands are defined in cbox.toml under [commands]. The branch comes from ## Branch in .cbox/plan.md, or from git branch --show-current if no box has been created yet.

Examples:

• Tests: cbox run <branch> test
• E2E: cbox run <branch> test-e2e
• Build: cbox run <branch> build

If a command you need is not in cbox.toml, run /cbox-init first to configure it.

The Anchor

.cbox/plan.md is the single source of truth. Always read it first if it exists. Always write back to it after any change. This file is gitignored — it's your local working copy.

Step 1: Load or Initialize

Check if .cbox/plan.md exists.

• If it exists: Read it. You are in refinement mode. Show the current plan and ask what the user wants to change.
• If it doesn't exist: You are in creation mode. Proceed to Step 2.

Step 2: Read the Codebase

Before drafting anything, explore the project to understand:

1. Project type — CLI tool, web app, library, monorepo? Check for cbox.toml, package.json, go.mod, Cargo.toml, etc.
2. Existing architecture — key packages, patterns, naming conventions
3. Available cbox commands — read cbox.toml [commands]. These are the commands you must use to interact with the project (e.g. cbox run <branch> test-e2e). Never invoke the underlying package manager or test runner directly.
4. Existing tests — look at test file locations and naming. If you need to run tests to understand the current state, use cbox run <branch> <command>.
5. Serve config — does cbox.toml have a [serve] section? If so, note the URL pattern: http://<branch>.<project>.dev.localhost

Do not ask the user for this information. Infer it from the codebase.

Step 3: Draft the Plan

Write a draft to .cbox/plan.md using this exact structure:

# <Feature Title>

## Status
draft

## GitHub Issue
(pending)

## Branch
(pending)

## Feature Overview
<Plain English description of what this feature does and why>

## Architecture
<Key design decisions, packages to create or modify, interfaces to define, patterns to follow>

## Acceptance Criteria
- [ ] <specific, verifiable criterion> → `<verification command>`
- [ ] <specific, verifiable criterion> → `<verification command>`

## E2E Test Spec
<Only include this section if the project has a serve config or an e2e test command. List specific test cases that cover the acceptance criteria. For web apps: user-facing flows. For CLI tools: command invocations and expected output. Omit this section entirely for pure library/infrastructure work.>

- <test case: what action, what expected result>
- <test case: what action, what expected result>

## Execution Plan

### Phase 1: E2E Tests
<Only include if E2E Test Spec section exists above>
- [ ] <specific test file or test case to write>

### Phase 2: Infrastructure
- [ ] <types, interfaces, packages to define>
- [ ] <any scaffolding needed before implementation>

### Phase 3: Implementation
- [ ] <specific implementation task>
- [ ] <specific implementation task>

Keep tasks in the execution plan atomic — one agent, one task, one acceptance check.

Acceptance Criteria Verification Format

Every acceptance criterion must include an inline → \command`` showing how to verify it. Choose based on task type:

• Infrastructure / refactor (no new behaviour): → \cbox_build``
• Logic / unit-testable: → \cbox_test``
• User-facing feature: → \cbox_test-e2e args="--grep ''"`or→ `cbox_test-e2e args="apps/web/e2e/.spec.ts"``

Rules:

• Propose the grep pattern or spec path based on the feature — it may not exist yet; the inner agent will adapt
• Use $Args patterns only (do not embed full playwright commands — those are in cbox.toml)
• Full suite (cbox_test-e2e with no args) is reserved for the final phase; never use it per-task

Step 4: Refinement Loop

Show the user the drafted plan (or the changed section after an edit). Then wait.

The user will give freeform feedback. Update .cbox/plan.md accordingly and show what changed. Repeat until the user approves.

You may bring in other skills during this loop (e.g. /grill-me for architecture stress-testing). When you return to planning, re-read .cbox/plan.md to re-anchor yourself.

Watch for approval signals: "ship it", "looks good", "go ahead", "do it".

Step 5: Create the GitHub Issue

Once approved:

1. Create the GitHub issue using gh. The issue body contains only the static spec — no checkboxes:

   gh issue create --title "<Feature Title>" --body "## Feature Overview
   <...>
   
   ## Architecture
   <...>
   
   ## E2E Test Spec
   <...if present...>"
   

   Capture the issue number from the output.

2. Derive the branch name: feature/<issue-number>-<slugified-title>

   • Slugify: lowercase, spaces to hyphens, strip special chars, max 40 chars

3. Update .cbox/plan.md:

   • Set ## GitHub Issue to #<number>
   • Set ## Branch to the branch name
   • Set ## Status to ready

4. End with:

   Issue #<number> created. Branch will be: <branch>
   
   Ready to implement? Type "yes" to begin the swarm, or give feedback to refine the plan first.
   

If the user says yes: invoke /cbox-swarm directly. If the user gives feedback: loop back to Step 4.

Resuming an Existing Plan

If the user invokes /cbox-plan without arguments and .cbox/plan.md exists with ## Status: ready, ask: "You have an existing plan for