/spec Skill

Produces a plan.md inside a work item's _work/<slug>/ directory.

Two modes:

•/spec short [input] — Single agent reads key files and drafts the plan directly. For well-understood, small-scope work.
•/spec [input] — Team of researcher agents investigate in parallel, then synthesize. For complex or uncertain-scope work.

Input can be an existing work item name (/spec auth-refactor) or a freeform description (/spec add rate limiting to the API). Freeform descriptions trigger goal refinement before investigation.

Resolve Work Path

bash

lore resolve

Set KNOWLEDGE_DIR to the result and WORK_DIR to $KNOWLEDGE_DIR/_work.

Step 1: Parse and resolve (both modes)

•Parse arguments: if first arg after /spec is short, use Short Flow; otherwise Full Flow. The remaining text is the input.
•Try to resolve input as an existing work item (fuzzy match or branch inference, same algorithm as /work)
•
If resolved → load the work item:
- •If plan.md exists with ## Investigations and completed findings, skip to synthesis (Step 5)
- •If it has investigations but ## Open Questions needing follow-up, dispatch targeted follow-ups
- •If plan.md exists but is incomplete, present for discussion/editing
- •If no plan.md, continue to Step 2 (the appropriate flow)
•If NOT resolved → treat input as a freeform description, go to Goal Refinement
•If no input at all → try branch inference; if no match, ask what they want to spec

Step 1b: Goal Refinement (new work only)

When the input is a freeform description rather than an existing work item:

•Restate your understanding of the goal in 1-2 sentences. Be specific about what you think they want.
•
Ask 2-4 clarifying questions using AskUserQuestion. Target the gaps that would most affect the spec:
- •Scope boundaries ("Should this cover X, or just Y?")
- •Key constraints ("Any existing patterns to follow? Performance requirements?")
- •Approach preferences ("Do you have a preferred approach, or should I evaluate options?")
- •Do NOT ask questions answerable by reading the codebase — save those for investigations
•Incorporate answers into a refined goal statement
•Create the work item: derive a slug from the description, run the /work create flow
•Continue to Step 2 (Short Flow or Full Flow)

If the user's description is already specific enough (clear scope, stated constraints, obvious approach), skip to step 4 — don't ask questions for the sake of asking. Use judgment.

Short Flow (`/spec short`)

For single-pass plans where the scope is clear and the agent can identify key files without parallel research.

Step 2s: Read key context

•From conversation context and the work item, identify 3-8 key files to read 1b. Search the knowledge store: lore search "<topic>" --type knowledge --json --limit 5. Read any relevant entries to avoid re-discovering known patterns.
•Check the knowledge store (lore index, _manifest.json) for relevant domain files
•Read the files yourself — do NOT spawn subagents
•Note key findings as you go

Step 3s: Draft plan

•
Write plan.md using the plan template below
•
Use ## Context instead of ## Investigations: 3-6 bullet points summarizing key files read, constraints found, and relevant patterns
•
Fill in Goal, Design Decisions (with **Applies to:** fields mapping each decision to affected phases), Phases, Open Questions

Apply the task consolidation rule: each checkbox = one meaningful unit of work. Consolidate sequential same-file edits.
•
Annotate phases with knowledge context — after drafting phases with objectives and tasks, run a concordance query per phase to surface relevant knowledge entries beyond what you encountered in Step 2s:
bash
```
lore prefetch "<phase objective> <key file paths>" --type knowledge --limit 5
```
Review the suggestions for each phase. Add relevant entries as [[knowledge:file#heading]] — why relevant lines in the phase's **Knowledge context:** block. Your direct findings from Step 2s are the primary source — concordance is a widener, not a replacement. Skip entries that don't add actionable context for a worker implementing that phase.
•
Present to user for review

Step 4s: Finalize

•Incorporate user feedback
•
Generate tasks.json — after plan.md is finalized, run:
bash
```
lore work regen-tasks <slug>
```
This pre-computes TaskCreate payloads so /work tasks and /implement can load them directly without re-parsing plan.md.
•Run lore work heal
•Suggest retrospective: Consider /retro <slug> to evaluate knowledge system effectiveness for this spec.

Full Flow (`/spec`)

Team-based divide-and-conquer for complex or uncertain-scope work.

Step 2: Decompose into investigations

•
From the feature description, identify 3-7 focused investigation questions. Each should:
- •Target a specific part of the codebase or concern
- •Be answerable by exploring files (not by asking the user)
- •Be independent enough to run in parallel
•Check the knowledge store index for file hints to include with each investigation

•Present the investigation plan to the user:

code

I'll investigate these areas in parallel:
1. <Question 1> — will look at <file hints>
2. <Question 2> — will look at <file hints>
...
Proceed, or adjust?

•Wait for user confirmation before dispatching

Step 3: Create investigation team

All investigations are executed by fresh researcher agents. The lead decomposes questions and pre-fetches knowledge; researchers investigate. Exception: /spec short is explicitly single-agent for small-scope work.

•

Create team:

code

TeamCreate: team_name="spec-<slug>", description="Investigating <work item title>"

•
Read your team lead name from ~/.claude/teams/spec-<slug>/config.json — you'll embed this in researcher prompts so they know who to message.
•
Create investigation tasks — one TaskCreate per question:
- •subject: "Investigate: <question summary>"
- •description: The full question, context, file hints, and expected report format (see below)
- •activeForm: "Investigating <short topic>"
•
Pre-fetch knowledge for each investigation — before constructing prompts, run:
bash
```
PRIOR_KNOWLEDGE=$(lore prefetch "<investigation topic>" --format prompt --limit 5)
```
This produces a "## Prior Knowledge" block with pre-resolved content from the knowledge store.

•

Spawn researcher agents — launch min(investigation_count, 4) in a single message for parallelism:

code

Task:
  subagent_type: "Explore"
  model: "sonnet"
  team_name: "spec-<slug>"
  name: "researcher-N"
  prompt: |
    You are a researcher on the spec-<slug> team.

    <embed $PRIOR_KNOWLEDGE here — the pre-fetched knowledge block>

    If the pre-loaded knowledge doesn't cover your specific area, also search:
    lore search "<query>" --type knowledge --json --limit 5

    1. Call TaskList to see available investigation tasks
    2. Claim one: TaskUpdate with owner=your name, status=in_progress
    3. Read the full task with TaskGet
    4. Investigate using Glob, Grep, Read, LSP
    5. Send findings to "<team-lead-name>" via SendMessage:
       summary: "Findings: <topic>"
       content: |
         **Question:** <the question>
         **Findings:**
         - <finding 1>
         - <finding 2>
         **Key files:** <paths>
         **Implications:** <1-2 sentences>
         **Observations:** <anything surprising, non-obvious, or that
           contradicts expectations — include codebase conventions, type
           mappings, or patterns you noticed. Optional: omit or write
           "None" if nothing stood out.>
         **Unknowns:** <anything unresolved>
    6. **Update task description** with your full findings report:
       TaskUpdate with description set to the same content from step 5
       (including the **Observations:** section). This is required
       for the TaskCompleted hook to verify your report.
    7. Mark task completed: TaskUpdate with status=completed
    8. Call TaskList — claim next unclaimed task if available
    9. When no tasks remain, you're done

    Keep findings to 500-1000 characters. Facts over opinions.

If more questions than researchers, agents pick up additional tasks after completing their first.

Step 4: Collect and document findings

As researcher messages arrive (delivered automatically):

•Write each finding to the ## Investigations section of plan.md
•Use the investigation entry format from the template below

When all investigation tasks are complete:

•Send shutdown requests to all researchers via SendMessage (type: shutdown_request)
•Run TeamDelete to clean up the team

This is the critical persistence step — findings survive compaction, session boundaries, and context limits.

Step 5: Synthesize

From the documented findings, draft the remaining plan sections:

•
Goal — what we're building/changing and why (1 paragraph)
•
Design Decisions — architectural choices with rationale from findings. Include an **Applies to:** field in each decision mapping it to affected phases (e.g., "Phase 1 (template update), Phase 3 (migration)")
•
Phases — concrete implementation phases with tasks, file paths, objectives. For each phase, include a **Knowledge context:** block listing knowledge entries relevant to that phase — these flow directly to worker agents via task generation

Task consolidation rule: Each - [ ] checkbox should be a meaningful unit of work, not a micro-edit. Multiple sequential edits to the same file should be one task (e.g., "Update worker prompt to add capture step and renumber" not three separate tasks for delete/insert/renumber). Aim for 2-5 tasks per phase. If a phase has >5 tasks, look for consolidation opportunities.
•
Concordance-assisted annotation — after drafting phases, widen each phase's **Knowledge context:** block beyond what investigations explicitly mentioned. For each phase, run:
bash
```
lore prefetch "<phase objective> <key file paths>" --type knowledge --limit 5
```
Review the suggestions against what is already listed. Add relevant entries as [[knowledge:...]] backlinks with a brief "— why relevant" annotation. Skip entries that duplicate what investigations already covered. Investigation findings are the primary source of knowledge references — concordance is a widener, not a replacement.
•
Open Questions — anything investigations couldn't resolve

Present the synthesized plan to the user for review.

Step 5a: Post-research extraction

Invoke /remember scoped to the spec investigation:

code

/remember Research findings from <work item title> — Evaluate researcher-reported **Observations:** from investigation reports against the capture gate (reusable, non-obvious, stable, high-confidence). Capture architectural insights and gotchas discovered during research. Skip: findings already documented in plan.md (they're persisted there).

Step 5b: Generate tasks.json

After the user approves the plan (or after incorporating feedback), generate tasks.json:

bash

lore work regen-tasks <slug>

This pre-computes TaskCreate payloads so /work tasks and /implement can load them directly without re-parsing plan.md.

Step 6: Iterate (if needed)

If gaps are identified:

•Create a new investigation team (same pattern) for targeted follow-ups
•Append new findings to the Investigations section
•Update the synthesis

Run lore work heal after any changes.

After finalization or iteration is complete, suggest:

code

Consider `/retro <slug>` to evaluate knowledge system effectiveness for this spec.

Plan.md Template

markdown

# <Work Item Title>

## Goal
<!-- One paragraph: what we're building/changing and why -->

## Context
<!-- SHORT FLOW ONLY: 3-6 bullets summarizing key files, constraints, and patterns found -->
<!-- FULL FLOW: delete this section and use ## Investigations instead -->

## Investigations
<!-- FULL FLOW ONLY: findings from team-based exploration -->
<!-- SHORT FLOW: delete this section and use ## Context instead -->

### <Topic 1>
**Question:** <what was investigated>
**Findings:**
- Finding 1
- Finding 2
**Key files:** `path/to/file.ts`, `path/to/other.ts`
**Implications:** How this affects the design

## Design Decisions
<!-- Key architectural choices with rationale. Each decision should include an **Applies to:** field mapping it to the affected phases/tasks. -->

## Phases

### Phase 1: <Name>
**Objective:** What this phase accomplishes
**Files:** relevant file paths
**Knowledge context:**
<!-- Each entry MUST include a "— why relevant" annotation after the backlink. Workers see these annotations as their primary context — a bare link with no explanation is not actionable. -->
- [[knowledge:file#heading]] — why this is relevant to this phase
- [ ] Task 1
- [ ] Task 2

## Open Questions
- Unresolved decisions or items needing follow-up

## Related
<!-- Cross-cutting references that apply to the whole plan, not a specific phase. Phase-specific references belong in **Knowledge context:** blocks within each phase. -->
- [[knowledge:file#heading]] — cross-references to knowledge store

Resuming a spec across sessions

When /spec is called on a work item that already has a plan:

•Read existing investigations/context — they are your memory (no need to re-explore)
•Check if synthesis (Design/Phases) is complete; if not, synthesize from existing findings
•Check Open Questions — dispatch follow-up investigations for unresolved items
•Present current state and ask what needs refinement

/spec Skill

Resolve Work Path

Step 1: Parse and resolve (both modes)

Step 1b: Goal Refinement (new work only)

Short Flow (/spec short)

Step 2s: Read key context

Step 3s: Draft plan

Step 4s: Finalize

Full Flow (/spec)

Step 2: Decompose into investigations

Step 3: Create investigation team

Step 4: Collect and document findings

Step 5: Synthesize

Step 5a: Post-research extraction

Step 5b: Generate tasks.json

Step 6: Iterate (if needed)

Plan.md Template

Resuming a spec across sessions

Short Flow (`/spec short`)

Full Flow (`/spec`)