brewcode-spec

name	brewcode:spec
description	Creates SPEC.md task spec via research + interaction. Triggers: create SPEC.md, brewcode spec, write spec.
disable-model-invocation	true
argument-hint	[-n] <description> | <path-to-requirements> — -n/--noask: no questions to user
allowed-tools	Read, Write, Glob, Grep, Bash, Task, AskUserQuestion
model	opus

Input Handling

Input	Action
$ARGUMENTS empty	Read .claude/TASK.md → first line = path → derive task dir
$ARGUMENTS has text	Use as task description
$ARGUMENTS has path	Read file as task description

Flag Parsing

Parse $ARGUMENTS for flags BEFORE input detection:

Flag	Effect
-n, --noask	Skip all user questions, auto-approve defaults

Strip flag from $ARGUMENTS. Remaining text = description or path.

Naming

• Timestamp: YYYYMMDD_HHMMSS (e.g., 20260208_143052)
• Name slug: lowercase, underscores, from description (e.g., auth_feature)
• Task dir: .claude/tasks/{TIMESTAMP}_{NAME}_task/

Workflow

0. Detect SPEC Template (OPTIONAL)

   EXECUTE using Bash tool:

   test -f .claude/tasks/templates/SPEC.md.template && echo "PROJECT TEMPLATE" || echo "BUILT-IN STRUCTURE"
   

   If a project template exists, use it. Otherwise use the built-in SPEC structure from the Output section below.

1. Read & Analyze Input

   • Parse $ARGUMENTS per Input Handling table
   • Determine scope: files affected, areas of codebase
   • Identify what needs clarification

2. Clarifying Questions (AskUserQuestion)

   If --noask: Skip. Record in SPEC User Q&A: "Skipped (--noask mode)". Infer scope from description and codebase analysis.

   Otherwise: Use AskUserQuestion tool to ask 3-5 questions, grouped in batches of up to 4 per AskUserQuestion call. Focus on:

   #	Category	Example Questions
   1	Scope	What's in/out? Which modules affected?
   2	Constraints	Required libraries? Backward compatibility? API contracts?
   3	Edge cases / ambiguities	Concurrent access? Empty/null inputs? Error recovery?

   Record all Q&A for the User Q&A section of SPEC.

2.5. Feature Splitting Check

After gathering requirements, evaluate scope:

IF requirements cover >3 independent areas OR estimated complexity >12 plan phases:
  → AskUserQuestion: "I suggest splitting into X tasks: [A], [B], [C]. Agree?"
  → If yes: create SPEC only for first task, record others in Notes section
  → If no: continue with full scope

Dynamic Agent Resolution

Before spawning agents, check for project team agents:

1. If .claude/teams/ exists — read team.md for agent roster with domains
2. If .claude/agents/ has project agents — list available
3. Match agent domain to current task area
4. Priority: team agent > project agent > plugin agent > system agent
5. If agent refuses (Task Acceptance Protocol) — re-delegate to suggested colleague (max 2 retries)

Always fall back to plugin agents when no project agents match the task domain.

3. Partition Research Areas (5-10 areas)

   Analyze project and split into logical parts for parallel research:

   | Area | Pattern | Agent |
   |------|---------|-------|
   | Domain-specific | matching pattern | matching team agent |
   | Controllers | **/controllers/ | developer |
   | Services | **/services/ | developer |
   | DB/Repos | **/repositories/ | developer |
   | Tests | **/test/ | tester |
   | Config | *.yml, docker-* | developer |
   | Docs | *.md, docs/ | Explore |
   

   See references/SPEC-creation.md for detailed parallel research instructions.

4. Parallel Research (ONE message, 5-10 agents)

   ONE message with 5-10 Task calls in PARALLEL
   
   Task(subagent_type="Plan", prompt="Analyze architecture...")
   Task(subagent_type="developer", prompt="Analyze services...")
   Task(subagent_type="tester", prompt="Analyze test patterns...")
   Task(subagent_type="reviewer", prompt="Analyze quality...")
   Task(subagent_type="Explore", prompt="Find library docs...")
   

   Agent prompt template:

   > **Context:** BC_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook).
   
   Analyze {AREA} for task: "{TASK_DESCRIPTION}"
   Focus: patterns, reusable code, risks, constraints
   Context files: {FILES_IN_AREA}
   Output: findings (bullets), assets (table), risks, recommendations
   NO large code blocks - use file:line references
   

5. Consolidate into SPEC

   • Create task directory: .claude/tasks/{TIMESTAMP}_{NAME}_task/
   • Use the project SPEC.md.template if detected in Step 0, otherwise the built-in structure
   • Merge agent findings (deduplicate)
   • Fill SPEC sections per Consolidation Rules in references/SPEC-creation.md
   • Write .claude/tasks/{TIMESTAMP}_{NAME}_task/SPEC.md
   • Include Research table with per-agent findings

6. Present Key Findings (AskUserQuestion)

   If --noask: Skip validation. Auto-approve all findings.

   Otherwise: Use AskUserQuestion to validate with user:

   • Key architectural decisions made
   • Risk assessment and proposed mitigations
   • Any assumptions that need confirmation
   • Completeness check: "Does this cover everything?"

   Incorporate user feedback into SPEC.

7. Review SPEC (reviewer agent + fix loop)

   Task(subagent_type="reviewer", prompt="> **Context:** BC_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook).
   
   Review SPEC at {SPEC_PATH}
   Check: completeness, consistency, feasibility, risks
   Output: list of remarks with severity (critical/major/minor), specific fixes")
   

   Iteration loop:

   WHILE remarks.critical > 0 OR remarks.major > 0:
     1. Fix all critical/major remarks in SPEC.md
     2. Re-run reviewer
   MAX 3 iterations. After 3 rounds, present remaining remarks to user via AskUserQuestion.
   

   Exit criteria: No critical/major remarks remaining OR 3 iterations exhausted

Template source: Prefer a project .claude/tasks/templates/SPEC.md.template when present; otherwise use the built-in SPEC structure below.

Output

# Spec Created

## Detection

| Field | Value |
|-------|-------|
| Arguments | `{received args}` |
| Input Type | `{text description or file path}` |
| Noask | `{yes or no}` |

## Files Created
- SPEC: .claude/tasks/{TIMESTAMP}_{NAME}_task/SPEC.md
- Task Dir: .claude/tasks/{TIMESTAMP}_{NAME}_task/

## Next Step

> Clear context, then hand the SPEC to the developer agent for implementation.

1. Clear context: type `/clear` and press Enter
2. Delegate implementation to the `developer` agent, pointing it at the SPEC:
\`\`\`
Implement the spec at .claude/tasks/{TIMESTAMP}_{NAME}_task/SPEC.md
\`\`\`