Harness Sync

Reconciles Plans.md against implementation status and detects/updates drift. Standalone version of legacy sync-status and the harness-plan sync subcommand.

Quick Reference

Options

Step 0: Plans.md validation

Verify Plans.md exists and is properly formatted. If issues are found, guide and stop immediately. In repos with multiple Plans.md files, confirm the target plan with scripts/plan-registry.sh list or --plan NAME before reading.

Step 1: Collect current state (parallel)

# Plans.md state
cat Plans.md

# Git change state
git status
git diff --stat HEAD~3

# Recent commit history
git log --oneline -10

# Agent trace (recently edited files)
tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | jq -r '.files[].path' | sort -u

Step 1.5: Agent trace analysis

Retrieve recent edit history from Agent Trace and reconcile with Plans.md tasks:

# List of recently edited files
RECENT_FILES=$(tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.files[].path' | sort -u)

# Project information
PROJECT=$(tail -1 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.metadata.project')

Reconciliation points:

Step 2: Drift detection

Step 3: Plans.md update proposal

When drift is detected, propose and execute:

Plans.md update needed

| Task | Current | Change to | Reason |
|------|---------|-----------|--------|
| XX   | cc:WIP | cc:done | Already committed |
| YY   | cc:TODO | cc:WIP | File already edited |

Update? (yes / no)

Step 4: Progress summary output

## Progress Summary

**Project**: {{project_name}}

| Status | Count |
|--------|-------|
| Not started (cc:TODO) | {{count}} |
| In progress (cc:WIP) | {{count}} |
| Done (cc:done) | {{count}} |
| PM confirmed (pm:approved) | {{count}} |

**Progress rate**: {{percent}}%

### Recently edited files (Agent Trace)
- {{file1}}
- {{file2}}

Step 4.5: Save snapshot (when --snapshot is specified)

When --snapshot is specified, save the current progress state as a timestamped snapshot.

Save location

Save in JSON format to the .claude/state/snapshots/ directory:

SNAPSHOT_DIR="${PROJECT_ROOT}/.claude/state/snapshots"
mkdir -p "${SNAPSHOT_DIR}"
SNAPSHOT_FILE="${SNAPSHOT_DIR}/progress-$(date -u +%Y%m%dT%H%M%SZ).json"

Snapshot contents

{
  "timestamp": "2026-03-08T10:30:00Z",
  "phase": "Phase 26",
  "progress": {
    "total": 16,
    "todo": 5,
    "wip": 3,
    "done": 6,
    "confirmed": 2
  },
  "progress_rate": 50,
  "recent_commits": ["abc1234 feat: ...", "def5678 fix: ..."],
  "recent_files": ["skills/harness-work/SKILL.md", "..."],
  "notes": ""
}

Diff comparison

When a previous snapshot exists, show the diff:

## Snapshot diff

| Metric | Previous ({{prev_time}}) | Current | Change |
|--------|-------------------------|---------|--------|
| Progress rate | {{prev}}% | {{current}}% | +{{diff}}%pt |
| Done tasks | {{prev_done}} | {{current_done}} | +{{diff_done}} |
| WIP tasks | {{prev_wip}} | {{current_wip}} | {{diff_wip}} |

Design intent: Snapshots are for manual use when users want to "record the current state." This is a different feature from the automatic progress feed during breezing (26.2.3).

Step 5: Next action suggestions

Next steps

**Priority 1**: {{task}}
- Reason: {{requested / waiting for unblock}}

**Recommended**: harness-work, harness-review

Anomaly detection

Step 6: Retrospective (default ON)

If there is at least 1 cc:done task, automatically run a retrospective. Can be explicitly skipped with --no-retro.

Step R1: Collect completed tasks

# Extract cc:done / pm:approved tasks from Plans.md
grep -E 'cc:done|pm:approved' Plans.md

# Recent completion commit history
git log --oneline --since="7 days ago"

# Change scale
git diff --stat HEAD~10

Step R2: Retrospective 4 items

Step R3: Retrospective summary output

## Retrospective Summary

**Period**: {{start_date}} – {{end_date}}

| Metric | Value |
|--------|-------|
| Completed tasks | {{count}} |
| Blocks occurred | {{blocked_count}} |
| Scope variation | +{{added}} / -{{removed}} |
| Estimation accuracy | Expected {{est}} files → Actual {{actual}} files |

### Learnings
- {{1-2 lines of learning}}

### Actions for next time
- {{1-2 lines of improvement actions}}

Step R4: Record to harness-mem

Record retrospective results in harness-mem for reference during the next create. Record location: Relevant agent memory under .claude/agent-memory/.

Related skills

• harness-plan — Plan creation and task management
• harness-work — Task implementation
• harness-review — Code review