implement

Do NOT re-invoke this skill via the Skill tool. Do NOT re-read these instructions or any other document in a loop. If you encounter any error or are unsure how to proceed, STOP and tell the user. Execute the workflow below once, then stop.

Task

You are implementing an existing specification. Your $ARGUMENTS contain the spec file path (if provided by the user).

Implement according to the spec. Do not write new specs in this session.

Setup

1. Check if $ARGUMENTS contains --workspace <dir>. If so, use that directory and skip config lookup.
2. Check for config files (first match wins):
   • .claude/skill-configs/spex/config.local.yaml (local scope, gitignored)
   • .claude/skill-configs/spex/config.yaml (project scope, committed to repo)
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. All paths below use this variable.

Workflow

Step 1: Read the spec

If a spec file path was provided in $ARGUMENTS, 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

Content Guidelines

Content principles:

• 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 = () => { /* ... */ };

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

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

Quick Reference

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

Implementing a phased spec (directory):

1. Read README.md for overview, then read each PN-*.md for phase details
2. Create TodoWrite with current phase + wrap-up steps
3. Update status in README.md to "In Progress"
4. Implement current phase following its PN-*.md file exactly
5. Update checklist items to [x] in the phase file as completed
6. Run tests and example workflow
7. Commit implementation with phase reference
8. If more phases remain, repeat from step 2
9. When all phases done: update README.md status, git mv entire directory to archive, final commit

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