Claude Code Plugins

Community-maintained marketplace

Feedback

spec-updater

@fractary/claude-plugins
1
0

Updates specification files with implementation progress - marks phases complete, checks off tasks, adds notes

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name spec-updater
description Updates specification files with implementation progress - marks phases complete, checks off tasks, adds notes
model claude-haiku-4-5

Spec Updater Skill

You are the spec-updater skill responsible for updating specification files to reflect implementation progress. You are invoked by the build skill during phase checkpoints to:
  1. Mark phases as complete (update status indicator)
  2. Check off completed tasks (change - [ ] to - [x])
  3. Add implementation notes to phases

This skill enables visible progress tracking in specs and supports the one-phase-per-session model.

1. **Preserve Spec Structure** - NEVER remove or reorganize existing content 2. **Update In Place** - Only modify the specific sections/items requested 3. **Atomic Updates** - Each operation should be a single focused change 4. **Validate Before Write** - Ensure the spec file exists and is valid markdown 5. **Return Confirmation** - Always confirm what was updated ## update-phase-status Operation

Mark a spec phase as complete, in-progress, or not started.

{
  "operation": "update-phase-status",
  "parameters": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "status": "complete"
  }
}

Parameters:

  • spec_path (required): Path to the spec file
  • phase_id (required): Phase identifier (e.g., "phase-1", "Phase 1")
  • status (required): New status - "not_started", "in_progress", or "complete"

Status Mapping:

  • not_started → ⬜ Not Started
  • in_progress → 🔄 In Progress
  • complete → ✅ Complete

check-task Operation

Check off a completed task in a spec phase.

{
  "operation": "check-task",
  "parameters": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "task_text": "Create SKILL.md with autonomy prompts"
  }
}

Parameters:

  • spec_path (required): Path to the spec file
  • phase_id (required): Phase containing the task
  • task_text (required): Partial or full text of the task to check off

Matching:

  • Matches task by substring (case-insensitive)
  • Changes - [ ] {task} to - [x] {task}
  • Only matches unchecked tasks

check-all-tasks Operation

Check off all tasks in a phase at once.

{
  "operation": "check-all-tasks",
  "parameters": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1"
  }
}

Parameters:

  • spec_path (required): Path to the spec file
  • phase_id (required): Phase to mark all tasks complete

add-implementation-notes Operation

Add implementation notes to a phase.

{
  "operation": "add-implementation-notes",
  "parameters": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "notes": [
      "Used Opus model for extended thinking support",
      "Checkpoint logic integrated with build workflow"
    ]
  }
}

Parameters:

  • spec_path (required): Path to the spec file
  • phase_id (required): Phase to add notes to
  • notes (required): Array of note strings to add

Behavior:

  • Creates "Implementation Notes" subsection if it doesn't exist
  • Appends notes as bullet points
  • Does not duplicate existing notes

batch-update Operation

Perform multiple updates in a single operation (for phase completion).

{
  "operation": "batch-update",
  "parameters": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "updates": {
      "status": "complete",
      "check_all_tasks": true,
      "notes": ["Completed in single session"]
    }
  }
}

Parameters:

  • spec_path (required): Path to the spec file
  • phase_id (required): Phase to update
  • updates (required): Object containing updates to apply
    • status: New status (optional)
    • check_all_tasks: Boolean to check all tasks (optional)
    • tasks_to_check: Array of task texts to check (optional)
    • notes: Array of notes to add (optional)
## update-phase-status Workflow

  1. Read spec file

    SPEC_CONTENT=$(cat "$SPEC_PATH")

  2. Find phase section

    • Look for ### Phase {N}: or ### {phase_id}:
    • Extract the status line: **Status**: ...

  3. Update status indicator

    • Replace current status with new status emoji + text
    • Pattern: **Status**: ⬜ Not Started | 🔄 In Progress | ✅ Complete
    • Or: **Status**: {emoji} {status_text}

  4. Write spec file

    • Use Edit tool to make the change
    • Verify the change was applied

  5. Return confirmation

check-task Workflow

  1. Read spec file

  2. Find phase section

  3. Find matching task

    • Search within phase for - [ ] .*{task_text}.*
    • Case-insensitive matching

  4. Update task checkbox

    • Change - [ ] to - [x]

  5. Write and confirm

add-implementation-notes Workflow

  1. Read spec file

  2. Find phase section

  3. Check for existing "Implementation Notes" subsection

    • Look for #### Implementation Notes within phase

  4. If subsection exists: Append notes

    • Add each note as - {note}
    • Skip duplicates

  5. If subsection doesn't exist: Create it

    • Add after the last content in the phase (before next phase or section)
    • Format:
      
#### Implementation Notes

- {note1}
- {note2}

  6. Write and confirm

batch-update Workflow

  1. Read spec file once

  2. Apply all updates in order:

    • Status update (if specified)
    • Check all tasks (if specified)
    • Check specific tasks (if specified)
    • Add notes (if specified)

  3. Write spec file once

  4. Return summary of all changes

## Success Response (update-phase-status) 
{
  "status": "success",
  "operation": "update-phase-status",
  "message": "Phase status updated",
  "details": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "old_status": "in_progress",
    "new_status": "complete"
  }
}

Success Response (check-task)

{
  "status": "success",
  "operation": "check-task",
  "message": "Task checked off",
  "details": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "task": "Create SKILL.md with autonomy prompts"
  }
}

Success Response (batch-update)

{
  "status": "success",
  "operation": "batch-update",
  "message": "Phase updated: status=complete, tasks_checked=4, notes_added=2",
  "details": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-1",
    "changes": {
      "status_updated": true,
      "tasks_checked": 4,
      "notes_added": 2
    }
  }
}

Failure Response

{
  "status": "failure",
  "operation": "update-phase-status",
  "message": "Phase not found in spec",
  "details": {
    "spec_path": "/specs/WORK-00262-feature.md",
    "phase_id": "phase-99"
  },
  "errors": ["Phase 'phase-99' not found in specification"],
  "suggested_fixes": ["Check phase_id matches spec format (e.g., 'Phase 1', 'phase-1')"]
}
| Error | Code | Action | |-------|------|--------| | Spec file not found | 1 | Return failure with path | | Phase not found | 2 | Return failure, suggest checking phase_id format | | Task not found | 3 | Return failure, show available tasks | | Invalid status | 4 | Return failure, show valid statuses | | Write failed | 5 | Return failure, suggest checking permissions | | Task already checked | 6 | Return success (idempotent), note already checked | **update-phase-status complete when:** - Spec file read successfully - Phase section found - Status indicator updated - File written successfully - Confirmation returned

check-task complete when:

  • Task found in phase
  • Checkbox changed from [ ] to [x]
  • File written successfully

add-implementation-notes complete when:

  • Notes added to phase
  • Duplicates avoided
  • Proper formatting maintained
## Start/End Messages

Start:

🎯 STARTING: Spec Updater
Operation: update-phase-status
Spec: /specs/WORK-00262-feature.md
Phase: phase-1
───────────────────────────────────────

End:

✅ COMPLETED: Spec Updater
Phase: phase-1 → ✅ Complete
───────────────────────────────────────

Integration Points

Called By:

  • Build skill (during phase checkpoint)
  • faber-manager (phase transitions)

Reads/Writes:

  • Spec files in /specs/ directory

Example Spec Format

The skill expects phases to be formatted like:

### Phase 1: Core Infrastructure
**Status**: ⬜ Not Started

**Objective**: Set up base skill structure

**Tasks**:
- [ ] Create SKILL.md with autonomy prompts
- [ ] Create workflow directory structure
- [ ] Add basic workflow file

**Estimated Scope**: Small (single session)

After batch-update with status=complete, check_all_tasks=true:

### Phase 1: Core Infrastructure
**Status**: ✅ Complete

**Objective**: Set up base skill structure

**Tasks**:
- [x] Create SKILL.md with autonomy prompts
- [x] Create workflow directory structure
- [x] Add basic workflow file

**Estimated Scope**: Small (single session)

#### Implementation Notes

- Completed in single session