harness-sync

Harness Sync

Cross-check Plans.md against the implementation status, detect and update differences. Old sync-status and harness-plan sync Standalone version of the subcommand.

Quick Reference

User input	Behavior
harness-sync	Progress sync + retrospective (default ON)
harness-sync --no-retro	Progress sync only (skip retrospective)
harness-sync --snapshot	Save snapshot (record point-in-time progress)
harness-sync --plan roadmap	named Plans の roadmap sync
"Where are we now?" / "progress check"	Same as above

Options

Options	Description	Default
--snapshot	Save the current progress as a snapshot	false
--no-retro	Skip retrospective	false (runs by default)
--plan NAME	plans/manifest.json use the named plan of	active/default

Step 0: Plans.md validation

Check the existence and format of Plans.md. If there is a problem, guide the user immediately and stop. In a repo with multiple Plans.md files, confirm the target plan with scripts/plan-registry.sh list or --plan NAME before reading.

State	Guidance
Plans.md does not exist	Plans.md が見つかりません。harness-plan create で作成してください。 → Stop
Header has no DoD / Depends columns (v1 format)	Plans.md が旧フォーマット（3カラム）です。harness-plan create で v2（5カラム）に再生成してください。既存タスクは自動的に引き継がれます。 → Stop
v2 format (5 columns)	Proceed to Step 1 as is

Step 1: Collect current state (parallel)

# Plans.md の状態
cat Plans.md

# Git 変更状態
git status
git diff --stat HEAD~3

# 直近コミット履歴
git log --oneline -10

# エージェントトレース（直近の編集ファイル）
tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | jq -r '.files[].path' | sort -u

Step 1.5: Agent Trace analysis

Obtain the recent edit history from Agent Trace and cross-check it against the tasks in Plans.md:

# 直近の編集ファイル一覧
RECENT_FILES=$(tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.files[].path' | sort -u)

# プロジェクト情報
PROJECT=$(tail -1 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.metadata.project')

Cross-check points:

Check item	Detection method
File edits not in Plans.md	Agent Trace vs task description
Files different from the task description	Expected files vs actual edits
Tasks with no edits for a long time	Agent Trace timeline vs WIP period

Step 2: Difference detection

Check item	Detection method
Already complete but cc:WIP	Commit history vs marker
Already started but cc:TODO	Changed files vs marker
cc:完了 but uncommitted	git status vs marker

Step 3: Plans.md update proposal

If a difference is detected, propose and execute:

Plans.md 更新が必要です

| Task | 現在 | 変更後 | 理由 |
|------|------|--------|------|
| XX   | cc:WIP | cc:完了 | コミット済み |
| YY   | cc:TODO | cc:WIP | ファイル編集済み |

更新しますか？ (yes / no)

Step 4: Progress summary output

## 進捗サマリー

**プロジェクト**: {{project_name}}

| ステータス | 件数 |
|----------|------|
| 未着手 (cc:TODO) | {{count}} |
| 作業中 (cc:WIP) | {{count}} |
| 完了 (cc:完了) | {{count}} |
| PM確認済 (pm:確認済) | {{count}} |

**進捗率**: {{percent}}%

### 直近の編集ファイル (Agent Trace)
- {{file1}}
- {{file2}}

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

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

Save location

.claude/state/snapshots/ directory in JSON format:

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": ""
}

Difference comparison

If a previous snapshot exists, display the differences:

## スナップショット差分

| 指標 | 前回 ({{prev_time}}) | 今回 | 変化 |
|------|---------------------|------|------|
| 進捗率 | {{prev}}% | {{current}}% | +{{diff}}%pt |
| 完了タスク | {{prev_done}} | {{current_done}} | +{{diff_done}} |
| WIP タスク | {{prev_wip}} | {{current_wip}} | {{diff_wip}} |

Design intent: snapshot is used manually when the user wants to "record the current state." It is a separate feature from the automatic progress feed during breezing (26.2.3).

Step 5: Next action proposal

次にやること

**優先 1**: {{タスク}}
- 理由: {{依頼中 / アンブロック待ち}}

**推奨**: harness-work, harness-review

Anomaly detection

Situation	Warning
Multiple cc:WIP	Multiple tasks in progress simultaneously
pm:依頼中 unprocessed	Process PM requests first
Large discrepancy	Task management can't keep up
WIP not updated for 3+ days	Check whether blocked

Step 6: Retrospective (Default ON)

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

Step R1: Collect completed tasks

# Plans.md から cc:完了 / pm:確認済 のタスクを抽出
grep -E 'cc:完了|pm:確認済' Plans.md

# 直近の完了コミット履歴
git log --oneline --since="7 days ago"

# 変更規模
git diff --stat HEAD~10

Step R2: Retrospective 4 items

Item	Analysis method
Estimation accuracy	Infer the expected number of files from the task description in Plans.md → git diff --stat Compare with the actual number of changed files
Blocking cause	blocked Aggregate reason patterns for tasks with the marker (technical/external dependency/unclear specification)
Quality marker hit rate	[feature:security] Whether related problems actually occurred in tasks marked with etc.
Scope change	Number of tasks at the initial commit of Plans.md vs current number of tasks (number added/deleted)

Step R3: Output retrospective summary

## 振り返りサマリー

**期間**: {{start_date}} 〜 {{end_date}}

| 指標 | 値 |
|------|-----|
| 完了タスク | {{count}} 件 |
| ブロック発生 | {{blocked_count}} 件 |
| スコープ変動 | +{{added}} / -{{removed}} 件 |
| 見積もり精度 | 想定 {{est}} ファイル → 実際 {{actual}} ファイル |

### 学び
- {{1-2 行の学び}}

### 次に活かすこと
- {{1-2 行の改善アクション}}

Step R4: Record to harness-mem

Record the retrospective results in harness-mem so they can be referenced at the next create time. Record destination: .claude/agent-memory/ The corresponding agent memory under .

Related skills

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