Brewcode:Spec

<instructions>

Input Handling

Flag Parsing

Parse $ARGUMENTS for flags BEFORE input detection:

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. Check Adapted Templates (REQUIRED FIRST)

EXECUTE using Bash tool:

   test -f .claude/tasks/templates/SPEC.md.template && echo "SPEC.md.template" || echo "SPEC.md.template MISSING"

STOP if MISSING — Run /brewcode:setup first.

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:

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/
• Read .claude/tasks/templates/SPEC.md.template (project-adapted)
• 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: Always from .claude/tasks/templates/ (project), never from plugin base templates directly.

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

> Copy the command below first, then clear context and paste it.

1. Clear context: type `/clear` and press Enter
2. Run (paste copied command):
\`\`\`
/brewcode:plan .claude/tasks/{TIMESTAMP}_{NAME}_task/
\`\`\`

</instructions>

Spec

Creates a detailed task specification (SPEC.md) by researching your codebase in parallel, asking clarifying questions, and running a reviewer quality gate. The output is a self-contained document ready for /brewcode:plan.

Quick Start

/brewcode:spec "Add role-based access control to REST API"

Modes

The -n / --noask flag can be combined with any input mode. It is parsed and stripped before input detection.

Examples

Good Usage

# Concrete, scoped feature request
/brewcode:spec "Add WebSocket support for real-time order notifications in the checkout module"

# Point to an existing requirements document
/brewcode:spec docs/rfcs/0042-caching-layer.md

# Fully automated run in CI — no interactive prompts
/brewcode:spec -n "Migrate user service from REST to gRPC"

# Short flag works the same way
/brewcode:spec --noask "Replace Lombok with Java records in the domain module"

# No arguments — picks up scope from .claude/TASK.md
/brewcode:spec

Common Mistakes

# BAD: Vague description — agents cannot research anything specific
/brewcode:spec "Improve the backend"
# FIX: Be concrete about what to improve and where
/brewcode:spec "Add pagination and sorting to the /api/products endpoint"

# BAD: Running spec before setup — templates are missing
/brewcode:spec "Add caching layer"
# FIX: Run setup first, then spec
/brewcode:setup
/brewcode:spec "Add Redis caching for product catalog queries"

# BAD: Writing a spec for code that is already implemented — spec is for new/changed work
/brewcode:spec "The login page that we shipped last sprint"
# FIX: Use spec only for upcoming changes; use /brewcode:review for existing code
/brewcode:spec "Add MFA to the existing login flow"

Output

The skill creates a task directory and writes the specification into it:

.claude/tasks/{TIMESTAMP}_{NAME}_task/
  SPEC.md

SPEC.md contains:

• Task description and scope boundaries
• User Q&A from the clarifying step (or "Skipped" in --noask mode)
• Research findings from 5-10 parallel agents (architecture, services, tests, config, docs)
• Risks, constraints, and architectural decisions
• Reviewer remarks (all critical/major resolved)

Tips

• Run /brewcode:setup once per project before your first spec. It generates adapted templates that the spec skill depends on.
• Use -n when you already have a well-defined requirements document and do not need interactive clarification.
• If the skill detects that your request spans more than 3 independent areas or 12+ plan phases, it will suggest splitting into smaller tasks. Accept the split to keep specs focused.
• After the spec is ready, clear context with /clear and then run /brewcode:plan .claude/tasks/{TIMESTAMP}_{NAME}_task/ to generate the execution plan.

Documentation

Full docs: spec

SPEC Creation Instructions

Overview

Создание спецификации через параллельный анализ 5-10 логических областей проекта.

Step 1: Partition Research Areas

Разделить исследуемый материал на 5-10 логических частей:

Target: 5-10 areas based on project size and task complexity.

Step 2: Assign Agents to Areas

Выбор агента для каждой области на основе доступных в проекте:

Rule: If team exists in .claude/teams/, prefer team agents for matching domains. Otherwise use project-specific agents from .claude/agents/ when available.

Step 3: Parallel Agent Execution

┌─────────────────────────────────────────────────────────────┐
│  ONE message with 5-10 Task tool calls in PARALLEL          │
│                                                             │
│  Task(subagent_type="Plan", prompt="Analyze architecture in {area}")│
│  Task(subagent_type="developer", prompt="Analyze DB layer...")      │
│  Task(subagent_type="developer", prompt="Analyze services...")      │
│  Task(subagent_type="tester", prompt="Analyze test patterns...")    │
│  Task(subagent_type="reviewer", prompt="Analyze quality...")        │
│  ...                                                        │
└─────────────────────────────────────────────────────────────┘

Agent Prompt Template

Analyze {AREA_NAME} for task: "{TASK_DESCRIPTION}"

Focus:
- Existing patterns and conventions
- Reusable components/code
- Potential impact areas
- Risks and constraints
- Best practices observed

Context files: {LIST_OF_FILES_IN_AREA}

Output format:
1. Key findings (bullet points)
2. Reusable assets (table: path | purpose)
3. Risks/constraints (bullet points)
4. Recommendations (bullet points)

DO NOT include large code blocks - reference file:line instead.

Step 4: Consolidate Results

После завершения всех агентов:

1. Merge findings — объединить key findings 2. Deduplicate — убрать повторяющуюся информацию 3. Prioritize — ранжировать по важности для задачи 4. Structure — заполнить секции SPEC.md.template

Consolidation Rules

Step 5: Output

Create SPEC file: .claude/tasks/{TIMESTAMP}_{NAME}_task/SPEC.md

Important:

• NO large code blocks in SPEC — use file:line references
• Code snippets from research are for understanding, NOT for spec
• SPEC is a plan document, not a code dump

Example Partition

For a Spring Boot project with auth feature:

Timing

Total: 5-8 turns depending on review iterations and user interactions.