brainstorm

Brainstorming Ideas Into Designs

Overview

Turn ideas into fully formed designs through collaborative dialogue. Produces ONE artifact:

• GitHub Issue — Design document with overview, architecture, and acceptance criteria

Announce at start: "I'm using envoy:brainstorm to design this feature."

The Process

Phase 1: Understanding the Idea

1. Check the current project state (files, docs, recent commits)
2. Ask questions one at a time to refine the idea
3. Prefer multiple choice questions when possible
4. Focus on: purpose, constraints, success criteria, affected areas

Phase 1.5: Repo Exploration

Before proposing approaches, explore the repo:

1. Read relevant existing files (use acceptance criteria as guide)
2. Check for existing patterns, utilities, or similar features
3. Note file paths that will likely be affected

This produces the implementation task list in the issue. Every referenced file path should be verified to exist (or confirmed as a new file to create).

Phase 2: Exploring Approaches

1. Propose 2-3 different approaches with trade-offs (informed by Phase 1.5 findings)
2. Lead with your recommended option and explain why
3. Get user confirmation before proceeding

Phase 3: Presenting the Design

1. Present design in sections of 200-300 words
2. Ask after each section: "Does this look right so far?"
3. Cover: architecture, components, data flow, error handling, testing
4. Be ready to revise based on feedback

Phase 4: Create GitHub Issue and Task Handoff

Once the design is confirmed, create the GitHub issue AND the schema-backed task handoff consumed by /envoy:pickup:

ISSUE_URL=$(gh issue create --title "<Feature Name>" --body "$(cat <<'EOF'
## Overview

<2-3 sentence description>

## Architecture

<Technical approach, key decisions, components involved>

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Tasks

> Every task in this spec is REQUIRED. Optional or stretch work goes in a separate issue.

### Task 1: <name>
**Files:** Create/Modify: `exact/path/to/file.ext`
**What:** <one sentence describing the change>

### Task 2: <name>
**Files:** Create/Modify: `exact/path/to/file.ext`
**What:** <one sentence describing the change>

---

*Generated by Envoy*
EOF
)" --label "<labels>")
ISSUE_NUMBER=$(basename "$ISSUE_URL")

# Emit the schema-backed task handoff (validated against lib/schemas/tasks.json).
# pickup's preflight will fail fatal if this file is missing or invalid.
cat > /tmp/envoy-tasks-payload.json <<'TASKS_EOF'
{
  "$schemaVersion": "1",
  "strategy": "batch",
  "tasks": [
    {
      "id": "task-1",
      "title": "<name>",
      "description": "<one sentence describing the change>",
      "files": ["exact/path/to/file.ext"],
      "acceptance": ["<criterion>"]
    }
  ]
}
TASKS_EOF

node "$(dirname "$0")/write-tasks.js" "$ISSUE_NUMBER" /tmp/envoy-tasks-payload.json
git add ".envoy-tasks/$ISSUE_NUMBER.json"
git commit -m "chore: task handoff for #$ISSUE_NUMBER"

Phase 5: Final Handoff

"Design complete!

Artifact created:

• Issue: #

To start implementation:

/envoy:pickup <issue-number>

"

Labels Reference

Label	When to Use
backend	Changes to .NET API, services, database
frontend	Changes to React UI, components, styling
infrastructure	Docker, Azure, Bicep, CI/CD
security	Authentication, authorization, security fixes
feature	New functionality
refactor	Code restructuring without behavior change
bugfix	Fixing broken functionality
docs	Documentation only

Key Principles

• One question at a time — Don't overwhelm
• Multiple choice preferred — Easier to answer
• YAGNI ruthlessly — Remove unnecessary features
• The issue IS the design doc — No separate spec files