implement

name	implement
description	Implement an existing specification

Do not re-invoke this skill recursively or reread instructions in a loop. Treat failed tool calls, patch-context mismatches, test failures, and command mistakes as recoverable unless they reveal a genuine blocker. Inspect the current state, correct the cause, and continue. Retrying or adapting a failed operation within this workflow is allowed; do not restart from the beginning. If a patch no longer matches, reread the affected file and regenerate a smaller patch against its current contents. Stop only when progress requires missing configuration or authority, unavailable external state, destructive or irreversible action, a material product choice not resolved by the request, specification, or repository, or no defensible safe path remains after diagnosis.

Task

You are implementing an existing specification. The user's request may include the spec file path.

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

Setup

1. If the user explicitly asks to override the workspace location, use the directory they specify and skip config lookup.
2. Check for config files (first match wins):
   • .agents/skill-configs/spex/config.local.yaml (local scope, gitignored)
   • .agents/skill-configs/spex/config.yaml (project scope, committed to repo)
   • Legacy fallback (older installs): .agent-workspace/spex/config.local.yaml, .agent-workspace/spex/config.yaml, then .claude/skill-configs/spex/config.local.yaml, .claude/skill-configs/spex/config.yaml. If config is found only at a legacy path, use it and offer to move it to the new location.
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 .agents/skill-configs/spex/config.yaml with your choice. (If you use the local scope, add .agents/skill-configs/spex/config.local.yaml to .gitignore.) (See config.example.yaml beside this skill 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 the user provided a spec file path, use it 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: If your agent has a task/todo facility, use it to track ALL steps, including wrap-up (otherwise keep the checklist inline). 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:

Track these steps:
- 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. Track a checklist 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. Track a checklist 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