sync

name	sync
description	End-of-session documentation sync — updates TODO.md and PROGRESS.md only (run /commit after to commit everything)

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Plugin skills are namespaced. Invoke this workflow explicitly as $clade:sync; a bare $name does not select the installed Clade plugin.
• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $clade:skill-name plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

You are the Sync skill. You automate the end-of-session documentation ritual.

This skill only updates documentation files (TODO.md, PROGRESS.md). It does NOT commit. After /sync, the user runs /commit to commit all changes (code + docs) split by module.

---

Step 1: Review recent work

Find what was done in this session:

1. Get the time window: Look for the last sync marker in PROGRESS.md, or default to the last 8 hours.

   git log --since="8 hours ago" --oneline
   

2. Get detailed changes:

   git log --since="8 hours ago" --stat
   

3. Read the commit messages to understand what was accomplished.
4. Also check for uncommitted changes via git status --short.

Build a mental model of: what features were added, what bugs were fixed, what was refactored.

---

Step 2: Update TODO.md

1. Read TODO.md
2. For each unchecked - [ ] item, determine if the recent commits implemented it:
   • Match commit messages against TODO item descriptions
   • Use Grep to verify the implementation exists in code (e.g., if TODO says "add X route", grep for that route)
   • Only check off items you can verify — don't guess
3. Edit TODO.md to check off completed items: - [ ] → - [x]
4. If you discover new sub-tasks during verification, add them under the relevant step
5. Show what was checked off:

   TODO.md updated:
     ✓ Checked off: "Add project_repos table" (verified: schema exists)
     ✓ Checked off: "GitHub API client" (verified: lib/github-client.ts exists)
     ? Skipped: "OAuth integration" (no matching commits found)
   

---

Step 3: Update PROGRESS.md

Append a session summary to PROGRESS.md. Follow this format:

### YYYY-MM-DD — [Brief session description]

**What was done:**
- [Feature/fix 1]: [one-line description of what and why]
- [Feature/fix 2]: [one-line description]

**What worked:**
- [Pattern or approach that was effective]

**What didn't work / lessons:**
- [Issue encountered and how it was resolved, or pitfall to avoid]

**Open items:**
- [Anything left unfinished that the next session should pick up]

Guidelines:

• Be concise — each bullet is one line
• Focus on lessons (what worked, what didn't) — this is the most valuable part
• Don't list every file changed — focus on the "why" and insights
• If nothing notable went wrong, skip "What didn't work"

---

Step 3b: Prune old entries

If PROGRESS.md exceeds 100 lines:

1. Identify entries older than 30 days (by their ### YYYY-MM-DD headers)
2. If the entry is NOT marked with [ACTIVE], move it to docs/progress-archive/YYYY-MM.md (create the file if needed, append to it)
3. Keep PROGRESS.md under 100 lines — the most recent entries stay
4. Show what was archived:

   Archived 3 old entries to docs/progress-archive/2026-01.md
   

---

Step 3c: Generate session scorecard

Run the session scorecard generator to log quality metrics:

bash ~/.clade/scripts/session-scorecard.sh

This appends a JSON entry to ~/.clade/corrections/scorecards.jsonl with correction counts, commits, and a quality score. If the script doesn't exist, skip this step silently.

---

Step 3d: Archive tier files

Check for 3-tier issue handling files from autonomous loop runs:

ls .clade/decisions.md .clade/skipped.md .clade/blockers.md 2>/dev/null

For each file that exists:

1. Append its contents to .clade/{name}-archive.md (create if needed)
2. Delete the original file
3. Report what was archived

If none exist, skip silently.

---

Step 4: Print summary

Always end with a summary:

Sync complete:
  📋 TODO.md: 3 items checked off, 1 new sub-task added
  📝 PROGRESS.md: Session summary appended

  Run /commit to commit all changes (pushes by default; use --no-push to skip).

---

General rules

• Be concise. This is a utility, not a conversation.
• Only check off TODO items you can verify — false positives are worse than false negatives.
• Don't modify TODO.md structure (don't reorder, don't delete items, don't change headers).
• PROGRESS.md entries should be useful to future-you, not a changelog.
• If there's nothing to sync (no recent commits, no changes), say so and exit.

---

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.

Additional skill reference

Sync Skill

End-of-session documentation ritual. Reviews what was done and updates project docs — no commit. Run /commit after to commit everything (docs + code) split by module.

What it does

1. Reviews recent git history to understand what was accomplished
2. Auto-updates TODO.md (checks off completed items)
3. Appends a session summary to PROGRESS.md

Usage

/sync            # Update TODO.md + PROGRESS.md
/commit          # Commit all changes (code + docs) split by module + push
/commit --no-push  # Commit only, skip push

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.