create-spec

Create Feature Spec

Create a new feature spec folder with requirements and implementation plan documents.

Instructions

Based on conversation above:

1. Create Feature Folder

   • Store requirements and implementation plan in /specs
   • Create new subfolder in kebab-case (e.g., add-auth)

2. Create requirements.md

   • Document what the feature does and why it's needed
   • Include acceptance criteria
   • Reference related features or dependencies

3. Create implementation-plan.md

   • Split implementation into phases
   • Create actionable tasks for each phase
   • Include checkbox for each task: [ ] task description
   • Be specific enough for an agent to implement independently
   • Note dependencies between tasks where relevant
   • Mark complex tasks with [complex] suffix (creates separate GitHub issue when published)
   • Add ### Technical Details section after task list for each phase
   • Capture ALL technical details discussed during planning: CLI commands, database schemas, code snippets, file paths, config values
   • This document is the single source of truth - anything not captured here is lost

4. Create action-required.md

   • Extract all steps requiring manual human action
   • Include: account creation, API key setup, environment variables, third-party service setup, DNS configuration, etc.
   • Each item with checkbox and brief explanation (one line on why needed)
   • Keep these tasks in implementation plan too (for full context)
   • If no manual actions, create file with "None required" note

5. Exclude Test Tasks

   • Do not include unit tests or e2e test tasks
   • Only include tests if user explicitly requests them

If no conversation context:

First ask user what the requirements are, then create spec subfolder:

• requirements.md
• implementation-plan.md
• action-required.md

Implementation Plan Format

Use this structure for implementation-plan.md:

# Implementation Plan: {Feature Name}

## Overview

Brief summary of what will be built.

## Phase 1: {Phase Name}

{Brief description of this phase's goal}

### Tasks

- [ ] Task 1 description
- [ ] Task 2 description (depends on Task 1)
- [ ] Task 3 description [complex]
  - [ ] Subtask 3a
  - [ ] Subtask 3b

### Technical Details

{CLI commands, code snippets, schemas, and other implementation details discussed during planning}

## Phase 2: {Phase Name}

{Brief description}

### Tasks

- [ ] Task 4 description (depends on Phase 1)
- [ ] Task 5 description

### Technical Details

{Technical details for Phase 2 tasks}

Note: Tasks marked with [complex] or having nested subtasks will be created as separate GitHub issues when published (linked to parent phase issue).

Capturing Technical Details

IMPORTANT: Implementation plan must capture ALL technical details discussed during planning. The plan is the single source of truth - anything not captured here is lost.

Each phase should include a ### Technical Details section containing:

• CLI commands: Package installation, migrations, code generation
• Database schemas: Table definitions, column types, relationships
• Code snippets: Key implementation patterns, type definitions, configurations
• File paths: Where code should be created or modified
• Environment variables: Required config values and their purposes
• API endpoints: Routes, methods, request/response shapes
• Third-party integrations: SDK usage, webhook formats, auth flows

These details are passed to GitHub issues via /publish-to-github, available to any agent (or human) implementing the tasks.

action-required.md Format

Use this structure for action-required.md:

# Action Required: {Feature Name}

Manual steps that humans must complete. Cannot be automated.

## Before Implementation

- [ ] **{Action}** - {Brief explanation of why needed}

## During Implementation

- [ ] **{Action}** - {Brief explanation}

## After Implementation

- [ ] **{Action}** - {Brief explanation}

---

> **Note:** These actions are also listed in `implementation-plan.md` with full context

If No Manual Actions

If feature has no manual actions, create file like:

# Action Required: {Feature Name}

No manual steps required for this feature.

All tasks can be implemented automatically.

Next Steps

After feature creation, guide user:

Feature spec created at specs/{feature-name}/

Next steps:

1. Review action-required.md for manual tasks to complete
2. Review requirements and implementation plan
3. Run /publish-to-github to create GitHub issues and project
4. Start implementation with /continue-feature

Notes

• Keep tasks atomic - each should be implementable in a single session
• Tasks should produce working, testable code when complete
• Use clear, descriptive task names that explain what will be done
• Mark dependencies explicitly for tasks that must be done in order
• Common manual actions: account creation, API key generation, environment variables, OAuth app setup, DNS/domain configuration, billing setup, third-party service registration
• Never lose planning details: If technical details were discussed during planning (commands, schemas, code patterns), they MUST be included in the relevant phase's ### Technical Details section. Review conversation before finalizing to ensure nothing is missed.

When to use [complex]

Mark tasks as [complex] when:

• Has multiple subtasks requiring individual tracking
• Requires significant architecture decisions or discussion
• Spans multiple files or systems
• Would benefit from its own GitHub issue for comments/review

Most tasks should NOT be marked complex - reserve for truly substantial work items.