Agent skill

s:spec

Create SPEC.md for the next backlog item. Creates ./.gtd/<task_name>/SPEC.md

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/s-spec

SKILL.md

Core responsibilities:

  • Read BACKLOG.md to determine what to build next
  • Extract requirements from the backlog item definition
  • Interview user only for implementation details (HOW, not WHAT)
  • Write SPEC.md that is traceable to the backlog item
  • Never deviate from the backlog

Flow: Read Backlog → Select Item → Research → Interview (HOW) → Mirror → Confirm → Write

Required:

  • ./.gtd/BACKLOG.md — Must exist. Run /bootstrap first if missing.

Output:

  • ./.gtd/<task_name>/SPEC.md

Agents used:

  • research — For understanding implementation constraints

Backlog is the Authority

The BACKLOG.md defines WHAT to build. The Spec defines HOW to build it. You do not ask the user what they want. You tell them what's next.

No Deviation

If it's not in the Backlog, it doesn't get built. If the user wants something new, they must update the Backlog first.

Sub-Items First

If a parent item has sub-items, execute sub-items in order. If no sub-items exist, prompt user to run /expand-backlog first.

Interview for Implementation Only

The user has already decided WHAT via the architecture docs. Propose HOW, only ask about genuinely unclear items.

Mirror Before Writing

Summarize the implementation plan, not the requirements (those come from Backlog).

1. Backlog Selection Phase

Check for BACKLOG.md:

bash
if [ ! -f "./.gtd/BACKLOG.md" ]; then
    echo "Error: No BACKLOG.md found. Run /bootstrap first."
    exit 1
fi

Check argument:

If backlog_item argument provided:

  • Validate the item exists in ./.gtd/BACKLOG.md
  • Validate the item is incomplete ([ ] or [~])
  • If valid, use that item
  • If invalid, error with available items

If no argument (auto-detect):

Parse ./.gtd/BACKLOG.md:

  1. Find all items marked [~] (in progress / expanded)
  2. Under each, find sub-items marked [ ] (not started)
  3. Select the first incomplete sub-item

Priority:

  • Parents with [~] status first (already being expanded)
  • Within a parent, sub-items in numbered order
  • If no sub-items exist, check if parent needs expansion

If no sub-items found but parent items exist:

text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► NO EXECUTABLE SUB-ITEMS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

No sub-items found. The next parent item needs expansion:

**{next-parent-item}** — {description}

─────────────────────────────────────────────────────
▶ Run: /expand-backlog {next-parent-item}
─────────────────────────────────────────────────────

If sub-item found, display selection:

text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► NEXT BACKLOG ITEM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Based on BACKLOG.md, the next item to implement is:

**{parent}/{sub-item}** — {description}

Parent: {parent-name}
Tech: {tech stack from parent}

─────────────────────────────────────────────────────
Proceeding with this item. Let me research the implementation...

Do NOT ask user to choose. The backlog order is the authority.

3. Spawn Researcher Agent

Trigger: Immediately after confirming the item. Concurrency: As many as needed.

Fill prompt and spawn:

markdown
<objective>
Investigate domain feasibility for backlog item: {item_name}

**Goal:** {description_from_backlog}
**Tech Stack:** {tech_from_backlog}
</objective>

<investigation_checklist>

1. Identify relevant existing code (based on parent service/tech)
2. Note dependencies and integration points
3. Identify technical constraints
4. Check for existing patterns to reuse
   </investigation_checklist>

<output_format>
Feasibility Report with:

- Implementation Plan (Draft)
- Key Files
- Reference Implementation
- Identified Risks
  </output_format>
python
Task(
  prompt=filled_prompt,
  subagent_type="researcher",
  description="Researching backlog item {item_name}"
)

Purpose:

  • Understand what exists
  • Plan what needs to be created
  • Identify risks and blockers

4. Interview Phase (Propose + Ask Unclear)

Propose your implementation plan, only ask about unclear items:

text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► PROPOSED SPECIFICATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For: **{parent}/{sub-item}**

**Goal:**
{what this delivers}

**Must Have:**
- {requirement 1}
- {requirement 2}

**Nice To Have:**
- {nice requirement 1}
- {nice requirement 2}

**Assumptions:**
- {assumption 1}
- {assumption 2}

**Approach:**
- {implementation approach}

**Tech:**
- {from parent backlog item}

**Unclear items (need your input):**
- {unclear item, if any — or "None"}

─────────────────────────────────────────────────────
Please review. (ok / adjust: ...)

Wait for confirmation before writing SPEC.md.

4. Write SPEC.md

Task name comes from backlog item name.

Summarize implementation plan:

text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► CONFIRMING SPECIFICATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Backlog Item:** {item_name}
**Task Name:** {task-name}

**Goal:** (from Backlog)
{description from backlog}

**Must Have:** (from Backlog responsibilities)
- {responsibility 1}
- {responsibility 2}

**Implementation Approach:**
- {approach based on interview}

**Tech Stack:** (from Backlog)
- {tech from backlog}

**Won't Have:** (this version)
- {exclusions based on MVP discussion}

**Constraints:**
- {from research}

─────────────────────────────────────────────────────

Is this correct? (yes/no/clarify)

Wait for explicit confirmation.

5. Write SPEC.md

Bash:

bash
mkdir -p ./.gtd/<task_name>

Write to ./.gtd/<task_name>/SPEC.md:

markdown
# Specification

**Status:** FINALIZED
**Created:** {date}
**Backlog Item:** {item_name}

## Goal

{What we're building — copied from Backlog description}

## Requirements

### Must Have

(Copied from Backlog responsibilities)

- [ ] {Responsibility 1}
- [ ] {Responsibility 2}

### Nice to Have

- [ ] {Optional feature from interview}

### Won't Have (This Version)

- {Exclusion from MVP discussion}

## Tech Stack

(Copied from Backlog)

- {Technology 1}
- {Technology 2}

## Constraints

- {From research/interview}

## Implementation Notes

{Any specific approach decisions from interview}

## Open Questions

- {Any unresolved questions — empty if none}
text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► SPEC COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Specification written to ./.gtd/<task_name>/SPEC.md

Backlog Item: {item_name}
Acceptance Criteria: {N} items defined

─────────────────────────────────────────────────────

▶ Next Up

/roadmap — create phases from this spec

─────────────────────────────────────────────────────

</offer_next>

<forced_stop> STOP. The workflow is complete. Do NOT automatically run the next command. Wait for the user. </forced_stop>

Didn't find tool you were looking for?

Be as detailed as possible for better results