brainstorming

name	brainstorming
description	Run an interactive brainstorming and planning session for a new feature. Guides the user through clarifying questions, solution proposals, and verification design. On approval, creates all project artifacts (feature branch, plan doc, prd.json, verification scripts) and commits everything. GitHub issues are created by chappie execute.

You are running a structured brainstorming session for a new feature. Follow each phase in order. Do not skip phases. Do not rush to solutions.

Rules

Always as one question at a time!

Phase 1: Explore

Before asking anything, think out loud about the feature. Consider:

• What problem does it solve and for whom?
• What are the edges, exceptions, and failure modes?
• What existing code or systems does it touch?
• What could go wrong technically and from a user perspective?
• What might the user not have considered?

Write this exploration out — 3 to 5 paragraphs. Be lateral. Surface non-obvious concerns.

---

Phase 2: Clarify (3 rounds, one at a time)

Ask clarifying questions to extract detail about both the feature intent and the implementation.

Rules — do not break these:

• Ask exactly one question. Not two. Not a question with sub-bullets. One.
• Stop. Wait for the answer. Do not continue until the user replies.
• Then ask the next single question. Repeat for 3 rounds total.

After all 3 rounds, summarize what you now understand.

---

Phase 3: Propose (3 rounds, one at a time)

Offer a distinct solution approach. Include:

• The core idea in 2-3 sentences
• Key tradeoffs (what it's good at, what it sacrifices)
• Any notable implementation risks

After presenting, ask: "Want to explore this further, see the next option, or change direction?"

Wait for the user's response before the next round. The user may steer, combine approaches, or call it early.

---

Phase 4: Verification Design

For the agreed approach, propose specific, deterministic verification steps — one per task that will be in the plan.

Each verification must be:

• A shell command or script that exits 0 on success, non-zero on failure
• Runnable without Claude's involvement
• Specific enough to actually catch regressions

Examples by context:

• Web app: npm run build exits 0; agent-browser snapshot confirms a key element is present
• API: curl returns expected status and response shape
• Data processing: row count matches expected value, column sum within tolerance
• CLI tool: command runs without error and output matches a fixture

Present the list and ask the user to confirm, adjust, or add steps.

---

Phase 5: Final Approval

Present a complete summary:

1. Feature name (slug format, e.g., user-auth)
2. What it does (2-3 sentences)
3. Approach chosen
4. Tasks — numbered list, each with a short title and description
5. Verification steps — which task each belongs to
6. Open questions or risks to watch during execution

Ask: "Ready to generate the plan and kick off the build?"

Do not proceed until the user confirms.

---

Phase 6: Generate Artifacts

On confirmation, first run preflight checks. For each item that is missing or wrong, tell the user and offer to fix it. Do not proceed until all pass.

Preflight: git repo

git rev-parse --is-inside-work-tree

If this fails, no git repo exists. Offer to run git init.

Preflight: not on main/master

git branch --show-current

If the current branch is main or master, stop. Offer to create the feature branch now (you know the feature name at this point).

Preflight: remote configured

git remote -v

If no remote is set, offer two options:

Option A — Create a new GitHub repo:

gh repo create <repo-name> --public --source=. --remote=origin
# or use --private if preferred

Option B — Link to an existing repo:

git remote add origin <url>

Ask which they prefer, run it, and confirm the remote is now configured. A remote must exist before proceeding — chappie execute will create GitHub issues there.

If the remote exists but the branch has never been pushed, that's fine — execute handles the push.

---

Once preflight passes, execute the following steps in order:

1. Feature branch

git checkout -b feature/<feature-name>

2. Plan document

Create /docs/plans/<feature-name>.md using this exact template:

# <Feature Name>

## Summary

<2-3 sentences describing what this feature does and the problem it solves.>

## Approach

<Chosen approach and rationale — 2-3 sentences covering the core idea and why it was selected over alternatives.>

## Tasks

1. **<Task Title>** — <Short description of what this task accomplishes and how.>
2. **<Task Title>** — <Short description of what this task accomplishes and how.>
3. **<Task Title>** — <Short description of what this task accomplishes and how.>

## Verification

| Task | Step | Command |
|------|------|---------|
| task-001 | <what it checks> | `<shell command that exits 0 on success>` |
| task-002 | <what it checks> | `<shell command that exits 0 on success>` |
| task-003 | <what it checks> | `<shell command that exits 0 on success>` |

## Risks & Open Questions

- <Risk or open question surfaced during brainstorming>
- <Risk or open question surfaced during brainstorming>

3. Verification scripts

For each task that has a verification step, create tests/verification/<feature-name>/<task-id>.sh.

Scripts are scoped to the feature so multiple features can coexist without collision. Task IDs follow the format task-001, task-002, etc. in the order tasks appear in the plan.

Each script must:

• Be executable (chmod +x)
• Exit 0 on success, non-zero on failure
• Include a comment at the top explaining what it verifies

Example (for feature user-auth, task task-002):

#!/bin/bash
# Verifies that the app builds without errors
# tests/verification/user-auth/task-002.sh
npm run build

Tests written by the tester agent live in tests/<feature-name>/, e.g. tests/user-auth/test-task-002.sh.

4. prd.json

Create prd.json at the project root. This is the single manifest that chappie execute reads to drive everything — task descriptions, GitHub issue creation, branch name, and runtime state.

{
  "sprint": "<Feature Name (human-readable)>",
  "name": "<feature-name>",
  "branch": "feature/<feature-name>",
  "description": "<2-3 sentence description of what this feature does>",
  "createdAt": "<YYYY-MM-DD>",
  "github": {
    "epic": null,
    "tasks": {
      "task-001": null,
      "task-002": null
    }
  },
  "tasks": [
    {
      "id": "task-001",
      "title": "<short title>",
      "type": "backend",
      "description": "<see formatting rules below>",
      "acceptanceCriteria": [
        "<specific, testable criterion>",
        "<specific, testable criterion>"
      ]
    }
  ]
}

type is one of "backend", "frontend", or "both". The acceptanceCriteria are what the test-writer agent uses to write tests — be precise and measurable.

Description formatting rules — follow these exactly:

Each task description must be written as structured markdown, not a wall of text. Use \n for newlines inside the JSON string. Format it like this:

<One sentence overview of what this task does.>\n\n**Files to create/modify:**\n- `path/to/file.ts` — what it exports or does\n- `path/to/other.ts` — what it exports or does\n\n**Key details:**\n- Specific behavior, constraint, or requirement\n- Another specific detail\n\n```typescript\n// Example type or schema if helpful\n```\n\n<Any important notes about edge cases or gotchas.>

Use bullet lists for files and requirements. Use fenced code blocks for schemas, types, SQL, or config snippets. Never write the description as a single paragraph — it is rendered as GitHub markdown and must be readable at a glance.

github.epic and github.tasks.* start as null — chappie execute creates the GitHub issues on first run and writes the issue numbers back into this file. Do not fill them in manually.

5. Initial commit

Stage and commit all artifacts:

git add docs/plans/<feature-name>.md tests/verification/ prd.json
git commit -m "plan(<feature-name>): brainstorm complete, artifacts committed"

---

Done

Summarize what was created: files committed, branch name.

Note: GitHub issues will be created automatically when chappie execute runs — no action needed.

Then tell the user exactly how to kick off the build:

npx chappie execute
# or, if running locally:
chappie execute