# Harness Sync

HAR: Sync Plans.md with implementation.

- Repository: https://github.com/Chachamaru127/claude-code-harness (3190 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Chachamaru127/claude-code-harness --skill harness-sync -g -a claude-code -y`
Codex: `npx skills add Chachamaru127/claude-code-harness --skill harness-sync -g -a codex -y`
Cursor: `npx skills add Chachamaru127/claude-code-harness --skill harness-sync -g -a cursor -y`
Gemini CLI: `npx skills add Chachamaru127/claude-code-harness --skill harness-sync -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Chachamaru127/claude-code-harness`

## Description

HAR: Sync Plans.md with implementation. Drift detect, marker update, retrospective. Trigger: sync-status, where am I, check progress. --snapshot for snapshots. Do NOT load for: planning, implementation, review, release.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Harness Sync

Plans.md と実装状況を照合し、差分を検出・更新する。
旧 `sync-status` および `harness-plan sync` サブコマンドの独立版。

## Quick Reference

| ユーザー入力 | 動作 |
|------------|------|
| `harness-sync` | 進捗同期 + レトロスペクティブ（デフォルト ON） |
| `harness-sync --no-retro` | 進捗同期のみ（レトロスキップ） |
| `harness-sync --snapshot` | スナップショット保存（進捗の時点記録） |
| `harness-sync --plan roadmap` | named Plans の `roadmap` を同期 |
| "今どこ？" / "進捗確認" | 同上 |

## オプション

| オプション | 説明 | デフォルト |
|----------|------|----------|
| `--snapshot` | 現在の進捗をスナップショットとして保存 | false |
| `--no-retro` | レトロスペクティブをスキップ | false（デフォルトで実行） |
| `--plan NAME` | `plans/manifest.json` の named plan を使う | active/default |

## Step 0: Plans.md 検証

Plans.md の存在とフォーマットを確認する。問題がある場合は即座に案内して停止する。
複数 Plans.md がある repo では、対象 plan を `scripts/plan-registry.sh list` または `--plan NAME` で確認してから読む。

| 状態 | 案内 |
|------|------|
| Plans.md が存在しない | `Plans.md が見つかりません。harness-plan create で作成してください。` → **停止** |
| ヘッダーに DoD / Depends カラムがない（v1 形式） | `Plans.md が旧フォーマット（3カラム）です。harness-plan create で v2（5カラム）に再生成してください。既存タスクは自動的に引き継がれます。` → **停止** |
| v2 形式（5カラム） | そのまま Step 1 に進む |

## Step 1: 現状収集（並列）

```bash
# 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 分析

Agent Trace から直近の編集履歴を取得し、Plans.md のタスクと照合する:

```bash
# 直近の編集ファイル一覧
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')
```

**照合ポイント**:

| チェック項目 | 検出方法 |
|------------|----------|
| Plans.md にないファイル編集 | Agent Trace vs タスク記述 |
| タスク記述と異なるファイル | 想定ファイル vs 実際の編集 |
| 長時間編集がないタスク | Agent Trace 時系列 vs WIP 期間 |

## Step 2: 差分検出

The rest: https://github.com/Chachamaru127/claude-code-harness/blob/HEAD/codex/.codex/skills/harness-sync/SKILL.md