Spec Workflow (Write & Implement)

Spec Workflow: Writing and Implementation

This document is reference documentation for humans. The skill files are authoritative at runtime. If you are an LLM reading this document during task execution, STOP — you should be following the instructions in your skill's SKILL.md, not this document.

Overview

This skill supports a two-phase workflow where specification writing and implementation are handled by different agents:

1. WRITING PHASE: Create spec, commit it, STOP
2. IMPLEMENTATION PHASE: Follow spec, implement, update status, commit everything

CRITICAL: These are separate tasks. Never write AND implement in the same session.

Configuration

Config is resolved with the following precedence (first match wins):

1. CLI flag (--workspace <dir>) — one-off override
2. Local config (.claude/skill-configs/spex/config.local.yaml) — gitignored, personal overrides
3. Project config (.claude/skill-configs/spex/config.yaml) — committed to repo, shared with team
4. No config found → STOP and ask the user

There are no built-in defaults. See config.example.yaml in the plugin for reference.

# .claude/skill-configs/spex/config.yaml
workspace_dir: .agent-workspace/specs  # where spec files are created and managed

Setup

1. If --workspace flag provided: use it directly, skip config lookup.
2. Check for config files (first match wins):
   • .claude/skill-configs/spex/config.local.yaml (local scope)
   • .claude/skill-configs/spex/config.yaml (project scope)
3. If no config found: STOP and tell the user:

   "No spex config found. I need a workspace directory to store spec files. You can either:

   1. Specify a custom path
   2. Use the default .agent-workspace/specs

   I'll create .claude/skill-configs/spex/config.yaml with your choice. (See config.example.yaml in the spex plugin for reference.)" Wait for the user's response, then create the config file before continuing.

4. Set ${SPECS_DIR} to the resolved workspace_dir value. All paths below use this variable.

---

Phase 1: Writing Specifications

[Reference only — see the write and write-phased skills for runtime instructions]

When to use: User requests a spec to be written, or you need to document a bug/feature/system change.

Your responsibilities:

• ✅ Investigate and write the spec
• ✅ Git add and commit the spec file
• ✅ STOP - Do not implement

You must NOT:

• ❌ Implement the spec
• ❌ Write any code beyond the spec itself
• ❌ Update the spec status to "In Progress" or "Completed"

Writing Workflow

Step 1: Create timestamped spec file (or directory for phased specs)

# Generate timestamp
TIMESTAMP=$(date +"%y%m%d-%H%M%S")

# Single-phase spec: create file
touch ${SPECS_DIR}/${TIMESTAMP}-descriptive-name.md

# Phased spec: create directory
mkdir -p ${SPECS_DIR}/${TIMESTAMP}-descriptive-name

Single-phase naming: {YYMMDD-HHMMSS}-{kebab-case-description}.md Phased naming: {YYMMDD-HHMMSS}-{kebab-case-description}/ (directory with README.md + PN-*.md files) Location: ${SPECS_DIR}/ directory

Step 2: Investigate thoroughly

Before proposing solutions:

1. Trace execution: Use grep/find to follow actual code paths
2. Verify assumptions: Check if functionality already exists elsewhere
3. Confirm the problem: Ensure issue exists where suspected
4. Never assume missing: Always verify before claiming something doesn't exist

Step 3: Write complete spec

Use this template:

# [Component/Feature] - [Brief Issue]

**Date:** YYYY-MM-DD HH:MM:SS
**Issue:** One-line problem description
**Priority:** [High/Medium/Low]
**Status:** Requires Implementation

## Problem Statement

- Current behavior (what's broken)
- Expected behavior (what should happen)
- Impact on users/system

## Root Cause Analysis

- Technical investigation with code examples
- Why the problem exists
- Comparison with working implementations if available

## Technical Approach

- Proposed solution methodology
- High-level implementation strategy
- Rationale for chosen approach

## Implementation Details

- Specific code changes with file paths
- Step-by-step implementation plan
- Testing strategy
- All commands and dependencies needed

Step 4: Git commit and STOP

# Add the spec file only
git add ${SPECS_DIR}/${TIMESTAMP}-descriptive-name.md

# Commit with descriptive message
git commit -m "spec: add specification for [brief description]

Created spec: ${TIMESTAMP}-descriptive-name.md
Status: Requires Implementation"

STOP HERE - Your work is done. Implementation will be handled by a different agent.

Writing Quality Checklist

Before committing, verify:

• Timestamp formatted correctly (YYMMDD-HHMMSS)
• File in ${SPECS_DIR}/ directory
• Status is "Requires Implementation"
• All required sections present
• Investigated existing code before proposing changes
• Problem statement is specific
• Root cause includes technical investigation
• Solution fixes only stated problem
• Implementation details are actionable with full file paths
• Code examples properly formatted with file:line references
• No meta-commentary or self-notes
• Self-contained for fresh agent to implement

Phased Spec Requirements (write-phased mode)

Phased specs use a directory layout — not a single file. See PHASED-IMPLEMENTATION.md for full templates.

${SPECS_DIR}/{timestamp}-{name}/
├── README.md              # Overview, principles, decisions, phase summary, progress
├── P1-{name}.md          # Phase 1 detail
├── P2-{name}.md          # Phase 2 detail
└── ...

README.md must include:

• Design Principles section (5-7 guiding principles)
• Key Design Decisions table (Decision | Choice | Rationale)
• Phase Summary table
• Progress Tracking section

Each PN-{name}.md must follow the strict phase template:

• Goal, Entry/Exit state
• Implementation Checklist with [ ] items
• Complete Code examples (not snippets)
• Required Tests (complete test files)
• Example Workflow (verification commands)

Each phase must be:

• Self-contained — Completable in one session
• Self-consistent — System works after completion (tests pass)
• Backward compatible — Existing functionality preserved
• Independently committable — One commit per phase
• Test-required — Unit tests for new code
• Workflow-verified — Reproducible example to verify

---

Phase 2: Implementing Specifications

[Reference only — see the implement skill for runtime instructions]

When to use: User requests implementation of an existing spec.

Your responsibilities:

• ✅ Read and understand the spec completely
• ✅ Implement according to the spec
• ✅ Follow all usual best practices
• ✅ Update spec status with commits
• ✅ Git add and commit all changes (spec + implementation)

You must NOT:

• ❌ Deviate from the spec without justification
• ❌ Skip updating the spec status
• ❌ Leave uncommitted changes

Implementation Workflow

Step 1: Read the spec

If a spec file path was provided in $ARGUMENTS (after the implement keyword), use that path directly.

Otherwise, find the latest non-future spec automatically:

python3 -c "
import os
import re
import sys
from datetime import datetime

specs_dir = sys.argv[1]
now = datetime.now()
pattern = re.compile(r'^(\d{6})-(\d{6})-(.*)')

valid_specs = []
for entry in os.listdir(specs_dir):
    full_path = os.path.join(specs_dir, entry)
    if not (os.path.isfile(full_path) or os.path.isdir(full_path)):
        continue
    match = pattern.match(entry)
    if match:
        date_part, time_part, _ = match.groups()
        year = int('20' + date_part[0:2])
        month = int(date_part[2:4])
        day = int(date_part[4:6])
        hour = int(time_part[0:2])
        minute = int(time_part[2:4])
        second = int(time_part[4:6])
        try:
            spec_dt = datetime(year, month, day, hour, minute, second)
            if spec_dt <= now:
                valid_specs.append((spec_dt, entry))
        except ValueError:
            continue

if valid_specs:
    latest = sorted(valid_specs, key=lambda x: x[0], reverse=True)[0]
    print(latest[1])
" "${SPECS_DIR}"

The script outputs the name of the latest spec (file or directory). Construct the full path as ${SPECS_DIR}/{name}.

Reading the spec depends on whether it's a file or directory:

• File (single-phase spec): Read the .md file directly.
• Directory (phased spec): Read {dir}/README.md for the overview, then read each PN-*.md file for phase details.

Understand:

• Problem statement
• Root cause
• Technical approach
• All implementation details
• Testing requirements

Step 2: Create implementation todo list

RECOMMENDED: Use TodoWrite to create a todo list with ALL steps, including wrap-up. This prevents forgetting to update/archive the spec after long implementations.

Create todos for:

1. Implementation tasks (from spec's Implementation Details)
2. Testing/verification
3. Update spec status to "Completed"
4. Add commit hash to spec
5. Archive spec to ${SPECS_DIR}/archive/implemented/
6. Git commit all changes

Example:

TodoWrite:
- Implement feature X according to spec
- Run tests to verify requirements
- Update spec status to "Completed" with commit hash
- Archive spec to ${SPECS_DIR}/archive/implemented/
- Git add and commit all changes (code + spec)

Step 3: Update spec status to "In Progress"

Edit the spec's status field (in the .md file for single-phase specs, or in README.md for directory specs):

**Status:** In Progress
**Started:** YYYY-MM-DD

Optional: Move to active directory

# Single-phase spec (file)
git mv ${SPECS_DIR}/{spec}.md ${SPECS_DIR}/active/{spec}.md

# Phased spec (directory)
git mv ${SPECS_DIR}/{spec}/ ${SPECS_DIR}/active/{spec}/

Step 4: Implement according to spec

Follow the implementation details exactly:

• Make all code changes specified
• Install any required dependencies
• Follow the step-by-step plan
• Test as specified in the spec
• Mark todos as completed as you finish each step

Follow all usual best practices:

• Write clean, maintainable code
• Add appropriate error handling
• Include comments where helpful
• Ensure type safety
• Test thoroughly

Step 5: Verify requirements

# Test the implementation
npm run dev  # or appropriate test command

# Verify all spec requirements met
# Check each item in Implementation Details section

Step 6: Update spec status to "Completed"

Edit the spec's status field (the .md file for single-phase specs, or README.md for directory specs):

**Status:** Completed
**Implementation:**
- Commit: {hash} - {message}
- Commit: {hash} - {message}
**Completed:** YYYY-MM-DD

Step 7: Archive the spec

# Move to implemented archive
mkdir -p ${SPECS_DIR}/archive/implemented

# Single-phase spec (file)
git mv ${SPECS_DIR}/{spec}.md ${SPECS_DIR}/archive/implemented/{spec}.md
# OR from active/
git mv ${SPECS_DIR}/active/{spec}.md ${SPECS_DIR}/archive/implemented/{spec}.md

# Phased spec (directory)
git mv ${SPECS_DIR}/{spec}/ ${SPECS_DIR}/archive/implemented/{spec}/
# OR from active/
git mv ${SPECS_DIR}/active/{spec}/ ${SPECS_DIR}/archive/implemented/{spec}/

Step 8: Git add and commit everything

# Add all changes (implementation + updated spec)
git add [files-you-modified]
git add ${SPECS_DIR}/archive/implemented/{spec}.md  # or wherever spec is

# Commit with reference to spec
git commit -m "feat: implement [feature name]

Implements spec: {timestamp}-name.md
- [Brief description of changes]
- [Another change]

Status: Completed"

Implementation Quality Checklist

Before committing, verify:

• All todos marked as completed
• All spec requirements implemented
• Code follows best practices
• Tests pass / manual testing complete
• Spec status updated to "Completed"
• Spec includes commit hashes
• Spec includes completion date
• Spec archived to ${SPECS_DIR}/archive/implemented/
• All files added to git (implementation + spec)
• Commit message references spec file
• No uncommitted changes remain

---

Directory Structure

${SPECS_DIR}/
├── {timestamp}-name.md            # Single-phase specs (flat file)
├── {timestamp}-name/              # Phased specs (directory)
│   ├── README.md                  #   Overview, principles, decisions, progress
│   ├── P1-{name}.md              #   Phase 1 detail
│   ├── P2-{name}.md              #   Phase 2 detail
│   └── ...
├── active/                        # In progress (Status: In Progress)
├── archive/
│   ├── implemented/              # Completed (Status: Completed)
│   └── deprecated/               # Obsolete (Status: Deprecated)
└── drafts/                       # Work-in-progress ideas

---

Content Guidelines

Content principles (apply to both phases):

• Write specs as final truth, not drafts
• No meta-commentary or revision history
• Include all context for fresh agent to start work
• Use code examples with file paths and line numbers
• Fix only the stated problem (no scope creep)

Code examples format:

// src/components/Example.tsx:42
const problematic = () => { /* ... */ };

// Fixed version:
const corrected = () => { /* ... */ };

---

Common Patterns

Reference existing code

## Root Cause Analysis

The issue occurs in `src/components/Button.tsx:87-92`:

\`\`\`typescript
// Current problematic implementation
const handleClick = () => {
  // Missing validation
  processData(data);
};
\`\`\`

Similar functionality in `src/components/Form.tsx:145` handles this correctly.

Provide complete context

## Implementation Details

**Files to modify**:
- `src/components/Button.tsx` - Add validation
- `src/types/index.ts` - Add new type definition

**Dependencies**:
\`\`\`bash
npm install zod
\`\`\`

**Testing**:
\`\`\`bash
npm run dev
# Navigate to http://localhost:5173/test-page
# Click button and verify validation works
\`\`\`

Break down complex changes

## Implementation Details

**Step 1: Add type definitions**
\`\`\`typescript
// src/types/validation.ts
export interface ValidationRule { /* ... */ }
\`\`\`

**Step 2: Implement validation logic**
\`\`\`typescript
// src/utils/validator.ts:1
export const validateInput = (/* ... */) => { /* ... */ }
\`\`\`

**Step 3: Integrate into component**
\`\`\`typescript
// src/components/Form.tsx:42
import { validateInput } from '@/utils/validator';
// Apply validation before submission
\`\`\`

---

Anti-patterns to Avoid

❌ Vague problem statements: "The form doesn't work right"

✅ Specific problem statements: "Form submission in src/components/ContactForm.tsx:87 allows invalid email formats to pass validation, causing 400 errors from the API"

❌ Assumed missing functionality: "We need to add validation because there is none"

✅ Verified gaps: "Searched codebase with grep -r 'emailValidation' src/ - validation exists in auth/ but not in contact/ forms"

❌ Scope creep: "Fix email validation AND redesign the form UI AND add analytics"

✅ Focused solution: "Add email validation to contact form using existing validation utilities from src/auth/validators.ts"

❌ Writing and implementing in same session: Don't create spec and immediately implement it

✅ Separate sessions: Write spec → commit → stop. Later: implement spec → update status → commit

---

Status Field Reference

During Writing Phase

**Status:** Requires Implementation

During Implementation Phase

Starting work:

**Status:** In Progress
**Started:** YYYY-MM-DD

When complete:

**Status:** Completed
**Implementation:**
- Commit: abc123 - feat: implement feature X
- Commit: def456 - fix: handle edge case in feature X
**Completed:** YYYY-MM-DD

If deprecated:

**Status:** Deprecated
**Reason:** [Brief explanation]
**Superseded By:** [Link to replacement]
**Deprecated:** YYYY-MM-DD

---

Quick Reference

I'm WRITING a spec:

1. Create timestamped file in ${SPECS_DIR}/ (or directory for phased specs)
2. Investigate thoroughly
3. Write complete spec with "Status: Requires Implementation"
4. git add ${SPECS_DIR}/{spec}.md (or {spec}/ for phased) && git commit
5. STOP - Don't implement

I'm IMPLEMENTING a spec:

1. Read spec completely
2. Create TodoWrite list with all steps including wrap-up
3. Update status to "In Progress"
4. Implement according to spec + best practices
5. Test thoroughly
6. Update spec status to "Completed" with commits and date
7. Archive spec to ${SPECS_DIR}/archive/implemented/
8. git add [all-files] && git commit
9. Done

---

Notes

• Specs are living documents until archived
• Update specs if requirements change (add timestamped note at top)
• Reference spec filename in commit messages
• Self-contained specs enable any agent to implement independently
• Timestamps ensure chronological ordering and uniqueness
• The two-phase approach ensures specs are reviewed before implementation
• Different agents bring fresh perspectives to implementation