/specs.sync

description: "Synchronizes specification context (KG, tasks) with implementation reality. Detects spec-to-code drift, proposes and applies spec updates, creates missing tasks. Full sync closes the SDD triangle (Spec <-> Test <-> Code). Use after task implementation or when drift is detected."
argument-hint: "[ --spec=docs/specs/XXX-feature ] [ --kg-only ] [ --code-only ] [ --after-task=TASK-XXX ]"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, AskUserQuestion, TodoWrite
model: inherit

Spec Synchronization

Synchronizes specification context (Knowledge Graph, Tasks) with implementation reality and detects/applies spec-to-code drift. This is the close-the-loop step of the specification workflow.

Overview

This command solves four problems:

1. **Inconsistent Technical Context**: Tasks lose technical context or don't reflect actual patterns used in the codebase 2. **Specs-Tasks Misalignment**: User request, specification, and tasks are not aligned 3. **Obsolete Knowledge Graph**: The knowledge-graph.json is not updated after implementations 4. **Spec-Code Drift**: The functional specification diverges from what was actually implemented, with decisions lost

It closes the SDD triangle by keeping synchronized:

• **Spec** → The functional specification (WHAT)
• **Test** → Tasks and acceptance criteria (verification)
• **Code** → The actual implementation (HOW)

Workflow Position

brainstorm → spec-to-tasks → task-implementation → task-review → sync (this) → done
                                    ↑                     ↓
                                    └── optionally --kg-only after spec-to-tasks ──┘

Usage

# Full sync (recommended after task-implementation or task-review)
/developer-kit-specs:specs.sync docs/specs/001-feature/

# Sync after a specific task
/developer-kit-specs:specs.sync docs/specs/001-feature/ --after-task=TASK-003

# KG-only mode (lighter, used after spec-to-tasks codebase analysis)
/developer-kit-specs:specs.sync docs/specs/001-feature/ --kg-only

# Code drift detection only
/developer-kit-specs:specs.sync docs/specs/001-feature/ --code-only

Modes

| Flag | What it does | Phases executed | When to use | |------|-------------|-----------------|-------------| | (none) | Full sync: KG update + task enrichment + drift detection + spec update | 1-9 | Default after implementation | | `--kg-only` | Update Knowledge Graph + task enrichment | 1, 2, 3, 4, 9 | After spec-to-tasks, when codebase was analyzed | | `--code-only` | Spec-to-code drift detection + spec update | 1, 5, 6, 7, 8, 9 | When you suspect drift |

Arguments

| Argument | Required | Description | |----------|----------|-------------| | `--spec` | No | Path to spec folder (e.g., `docs/specs/XXX-feature`). Auto-detected from git branch if omitted. | | `--kg-only` | No | Update Knowledge Graph and enrich tasks only. Skip drift detection and spec updates. | | `--code-only` | No | Detect spec-to-code drift and apply spec updates only. Skip KG and task enrichment. | | `--after-task` | No | Sync after a specific task (e.g., `TASK-003`). Narrows extraction to task-related files. |

Core Principles

• **Incremental updates**: Only update what has changed, don't rewrite everything
• **Bidirectional sync**: KG → Tasks and Tasks → KG alignment
• **Codebase-first**: Actual implementation is the final authority
• **Non-destructive**: Preserve manual edits and annotations in task files
• **Traceability**: All changes are logged and reported
• **Idempotent**: Running multiple times produces the same result
• **Living specification**: The spec should reflect what the system DOES, not what we planned it would do

---

Phase 1: Discovery

**Goal**: Identify spec folder, load context, determine execution mode

**Always runs** regardless of mode.

**Actions**:

1. Create todo list with all phases:

   [ ] Phase 1: Discovery
   [ ] Phase 2: Codebase Extraction & Gap Analysis
   [ ] Phase 3: Knowledge Graph Update
   [ ] Phase 4: Task Enrichment
   [ ] Phase 5: Spec Drift Detection
   [ ] Phase 6: Spec Update Proposal & Approval
   [ ] Phase 7: Apply Updates & Task Creation
   [ ] Phase 8: Sync Verification
   [ ] Phase 9: Summary

2. Parse `$ARGUMENTS` via script:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/parse_args.py" "$ARGUMENTS"

Read the JSON output and extract:

• `spec` → spec folder path
• `flags` → detect `--kg-only`, `--code-only`
• `task` → extract from `--after-task` if present

3. Determine spec folder:

• If `--spec=` provided: use it
• If no argument: auto-detect from git branch:

     branch=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/current_branch.py")
     spec=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/find_spec_from_branch.py")

• Validate path contains spec files (at least one markdown file matching spec patterns)

4. Resolve the functional specification file with this priority: 1. `YYYY-MM-DD--feature-name.md` 2. Legacy `*-specs.md` 3. The only dated spec-like markdown file in the folder excluding task and metadata files

5. Load current state:

• Read the resolved functional specification file
• Read `decision-log.md` if exists → extract all DEC entries
• Check if `knowledge-graph.json` exists
• List all task files in `tasks/` directory
• Read `user-request.md` if exists
• Identify completed tasks (status: completed in frontmatter)
• Detect language from existing tasks or source files

6. Determine execution mode:

• If `--kg-only`: execute Phases 1, 2, 3, 4, 9
• If `--code-only`: execute Phases 1, 5, 6, 7, 8, 9
• If no flag: execute all phases (1-9)

---

Phase 2: Codebase Extraction & Gap Analysis

**Goal**: Identify discrepancies between KG, tasks, and actual codebase; extract structured information from implemented code

**Runs unless**: `--code-only`

**Actions**:

2.1 Knowledge Graph Gap Analysis

1. **KG vs Codebase**:

• For e