spec — research and write spec

Caution

Skipping spec means rewriting later. Without a specification, parallel agents in /brewcode:plan and /brewcode:start have no shared ground truth — they duplicate work, contradict each other, and miss edge cases. The fix costs more than the spec would have.

Tip

-n / --noask for CI and scripts. Pass the flag to suppress all AskUserQuestion calls — spec is generated and reviewed automatically, no human in the loop. Useful when piping requirements from a file or external tool.

Quick reference

FieldValue
Command/brewcode:spec
Arguments[-n] <description> | <path-to-requirements>
Flag-n, --noask — skip all clarifying questions
Modelopus
Contextsession
ToolsRead, Write, Glob, Grep, Bash, Task, AskUserQuestion

When to use

  • New feature or task — turn a description or requirements file into a structured SPEC.md
  • Ambiguous requirements — clarifying questions surface scope, constraints, and edge cases before research begins
  • Large scope — the skill detects when requirements span more than 3 independent areas and suggests splitting
  • Automated pipelines — --noask skips interaction; pipe a requirements doc path as the argument

Examples

# From a plain description
/brewcode:spec "add JWT refresh token rotation to auth service"

# From an existing requirements file
/brewcode:spec path/to/requirements.md

# No interaction — auto-approve all defaults
/brewcode:spec -n "migrate database layer to async repositories"

Expected output after a successful run:

# Spec Created

Files Created:
  SPEC: .claude/tasks/20260417_143052_auth_feature_task/SPEC.md
  Task Dir: .claude/tasks/20260417_143052_auth_feature_task/

Next Step:
  /brewcode:plan .claude/tasks/20260417_143052_auth_feature_task/

Flow

  1. Check adapted templates

    Verifies .claude/tasks/templates/SPEC.md.template exists. Missing template means /brewcode:setup has not run — the skill stops here rather than writing a spec into the wrong structure.

  2. Parse input and ask clarifying questions

    Reads $ARGUMENTS: plain text becomes the task description; a path is read as requirements; empty args fall back to .claude/TASK.md. Then (unless —noask) fires up to 3 batches of questions — scope, constraints, edge cases. If requirements span more than 3 independent areas, proposes splitting into separate tasks.

  3. Partition research areas

    Divides the codebase into 5–10 logical zones: controllers, services, repositories, tests, config, docs, domain-specific paths. Each zone gets an assigned agent type. Team agents from .claude/teams/ take priority over plugin agents.

  4. Parallel codebase research

    Spawns 5–10 subagents in a single message — Plan, developer, tester, reviewer, Explore — each scoped to one research zone. Agents return findings as bullet lists and file:line references, never large code blocks.

  5. Consolidate into SPEC.md

    Creates the task directory (.claude/tasks/{TIMESTAMP}_{NAME}_task/), merges and deduplicates agent findings, fills all SPEC sections per the project-adapted template, and writes the file. A research table records which agent covered which area.

  6. Validate findings with user

    Unless —noask, presents key architectural decisions, risk assessment, and assumptions via AskUserQuestion. User feedback is incorporated into SPEC before the review pass.

  7. Reviewer loop

    A reviewer agent checks the SPEC for completeness, consistency, feasibility, and risks. All critical and major remarks are fixed and re-reviewed — up to 3 iterations. Remaining remarks after 3 rounds are surfaced to the user.

Phase details — input handling, agent prompt template, output format

Input detection (after flag stripping)

$ARGUMENTSAction
EmptyRead .claude/TASK.md — first line = path — derive task dir
Plain textUse as task description
File pathRead file contents as task description

Naming convention

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

Agent prompt template (research phase)

Each parallel subagent receives a prompt in this shape:

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

Dynamic agent resolution order

  1. Team agent from .claude/teams/team.md matching the domain
  2. Project agent from .claude/agents/
  3. Plugin agent (developer, tester, reviewer, Explore, Plan)

Reviewer iteration loop

WHILE remarks.critical > 0 OR remarks.major > 0:
  Fix all critical/major remarks in SPEC.md
  Re-run reviewer agent
MAX 3 iterations — then surface remaining remarks via AskUserQuestion

Template source: always from .claude/tasks/templates/ (project-adapted), never from plugin base templates directly.

📄

Plan

Next step — turn the SPEC into a phased execution plan with task breakdown.

▶️

Start

Execute the plan with infinite handoff and automatic session continuity.

🔗

GitHub source

SKILL.md, references, and SPEC-creation.md consolidation rules.

🚀

Brewcode overview

Full brewcode pipeline — setup, spec, plan, start, review, and more.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.