@opellen/scaff 0.1.11

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@opellen/scaff",
+  "version": "0.1.11",
+  "description": "Agile, goal-centric AI harness. Just markdown.",
+  "type": "module",
+  "license": "MIT",
+  "author": "San",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opellen/scaff.git"
+  },
+  "homepage": "https://github.com/opellen/scaff#readme",
+  "bugs": {
+    "url": "https://github.com/opellen/scaff/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "ai",
+    "project-management",
+    "markdown",
+    "context-management"
+  ],
+  "bin": {
+    "scaff": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./marker": "./dist/marker.js"
+  },
+  "files": [
+    "dist",
+    "templates/commands",
+    "templates/skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@inquirer/core": "^11.1.7",
+    "@inquirer/prompts": "^8.3.2",
+    "chalk": "^5.6.2",
+    "yaml": "^2.8.3"
+  }
+}

package/templates/commands/context.md

@@ -0,0 +1,93 @@
+---
+name: "scaff:context"
+description: "Project context (CONTEXT.md) management (init|sync)"
+category: Workflow
+tags: [workflow, scaff, context]
+---
+
+# scaff:context
+
+Manages `$DocsDir/CONTEXT.md`. Records the **current working context** of the project.
+
+> CONTEXT.md is not a project overview or summary.
+> It captures what is being worked on now, which resources are referenced, and what principles/workflows apply — **context the AI needs immediately at session start**.
+
+## Constraints
+
+- Never overwrite CONTEXT.md without user confirmation.
+- Target ~100 lines or less — this file is read at every session start.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:context <subcommand> [content]`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/CONTEXT.md` absent) => run init
+- (no subcommand given, `$DocsDir/CONTEXT.md` exists) => prompt the user to choose
+- (args = init) => see Subcommands: init
+- (args = sync) => see Subcommands: sync
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/CONTEXT.md`.
+
+1. If CONTEXT.md already exists, notify and confirm overwrite.
+2. If `$ARGUMENTS` has content, incorporate it.
+3. Write project-specific context based on the current session discussion.
+4. Use the skeleton below as a baseline, extending with project-specific sections.
+5. Report: `"Created [CONTEXT.md]($DocsDir/CONTEXT.md)."`
+
+**Skeleton:**
+
+```markdown
+# Project Brief
+- <1-2 lines: what this project is and who it's for>
+- <1-2 lines: core architecture or stack>
+- For deeper architecture/decisions, see `$DocsDir/OVERVIEW.md` (if present).
+
+# Goal Hierarchy
+- If `$DocsDir/ROADMAP.md` exists, it contains the milestone plan.
+  - Mark ROADMAP.md milestones as `done` when completed.
+  - GOAL.md objectives are sub-units of ROADMAP.md milestones.
+
+# Current Objective
+- If `$DocsDir/GOAL.md` exists, treat it as the top priority.
+
+# Principles
+
+# Workflow
+1. Add tasks to GOAL.md `## Tasks`
+2. Implement code in `$CodebaseDir`
+3. On completion, mark status as `done` and check off GOAL.md checklist
+4. GOAL.md YAML front-matter must include an `id` field (slug format)
+5. Save session progress with `/scaff:goal checkpoint` → `$DocsDir/CHECKPOINT.md`
+   - Single file, overwritten each session — captures latest state for session handoff
+```
+
+**Project-specific sections** — extend the skeleton with sections appropriate to the project:
+
+- **Resources**: Key file/directory paths and their descriptions
+- **Process**: Project-specific procedures (e.g., porting rules, analysis doc management)
+- **Index/Tables**: Frequently referenced item lists (e.g., analysis topics, API endpoints)
+- **Extended Principles**: Project-specific principles (e.g., 1:1 logic preservation, no magic numbers)
+
+## sync
+
+Reviews current CONTEXT.md and **proposes updates**.
+
+1. Read `$DocsDir/CONTEXT.md`. If absent, suggest init.
+2. If `$ARGUMENTS` has content, use it as update direction.
+3. Identify changes from the current session discussion that should be reflected.
+4. Present changes in **diff format**:
+   - Content to add
+   - Content to modify
+   - Outdated content to remove/update
+5. Apply the changes.
+6. Report: `"Updated [CONTEXT.md]($DocsDir/CONTEXT.md)."`
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/design.md

@@ -0,0 +1,108 @@
+---
+name: "scaff:design"
+description: "Implementation design (DESIGN.md) management (init|sync|archive)"
+category: Workflow
+tags: [workflow, scaff, design]
+---
+
+# scaff:design
+
+Manages `$DocsDir/DESIGN.md`. Records the **implementation design** for the current GOAL.
+
+> If GOAL.md is "what/why", DESIGN.md is "how".
+> Documents implementation plans, file change lists, key design decisions — implementation details that would be lost if only in chat.
+
+## Lifecycle
+
+DESIGN.md is paired 1:1 with GOAL.md:
+- Created after GOAL.md when an implementation plan emerges
+- Archived together with GOAL.md
+
+## Constraints
+
+- Never overwrite DESIGN.md without user confirmation.
+- DESIGN.md requires a corresponding GOAL.md — do not create without one.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:design <subcommand> [content]`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/DESIGN.md` absent) => run init
+- (no subcommand given, `$DocsDir/DESIGN.md` exists) => prompt the user to choose
+- (args = init) => see Subcommands: init
+- (args = sync) => see Subcommands: sync
+- (args = archive) => see Subcommands: archive
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/DESIGN.md`.
+
+1. Read `$DocsDir/GOAL.md`. A file read error means the file does not exist — **do NOT retry failed reads.** If absent, suggest setting a goal first.
+2. Parse GOAL.md `id` and `goal` for context.
+   - If GOAL.md has sub-tasks (from breakdown), note them as context for structuring the Execution Order.
+3. If `$ARGUMENTS` has content, incorporate it.
+4. Write based on the implementation plan discussed in the current session.
+5. If DESIGN.md already exists, notify and confirm overwrite.
+6. Report: `"Created [DESIGN.md]($DocsDir/DESIGN.md)."`
+   - (GOAL.md has breakdown sub-tasks AND Execution Order structure differs significantly) => also notify: `"Execution Order differs from GOAL.md sub-task structure. Run /scaff:goal breakdown to adjust if needed."`
+
+**Structure:**
+
+```markdown
+---
+goal-id: <GOAL.md id>
+created: YYYY-MM-DD
+---
+
+# Implementation Plan
+
+## Files to Change
+
+| File | Change | Description |
+|------|--------|-------------|
+| ... | new/modify | ... |
+
+## Key Design Decisions
+
+### 1. <Component/Module>
+- Design decision and rationale
+
+## Execution Order
+1. ...
+2. ...
+```
+
+Extend with project-appropriate sections.
+
+## sync
+
+Reviews current DESIGN.md and **proposes updates**.
+
+1. Read `$DocsDir/DESIGN.md`. If absent, suggest init.
+2. If `$ARGUMENTS` has content, use it as update direction.
+3. Identify changes from the current session:
+   - New design decisions
+   - Updated file change list
+   - Modified execution order
+   - Design changes from trial-and-error
+4. Present changes in **diff format**.
+5. Apply the changes.
+6. Report: `"Updated [DESIGN.md]($DocsDir/DESIGN.md)."`
+
+## archive
+
+Archives DESIGN.md.
+
+1. Parse `goal-id` from `$DocsDir/DESIGN.md` front-matter.
+2. Move to `$DocsDir/archive/goals/YYYY-MM-DD-<goal-id>/DESIGN.md`.
+3. Report: `"Archived to [$DocsDir/archive/goals/YYYY-MM-DD-<goal-id>/DESIGN.md]($DocsDir/archive/goals/YYYY-MM-DD-<goal-id>/DESIGN.md)."`
+
+> **Note**: `/scaff:goal archive` automatically archives DESIGN.md together with GOAL.md.
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/go.md

@@ -0,0 +1,56 @@
+---
+name: "scaff:go"
+description: "Execute the next task in GOAL.md"
+category: Workflow
+tags: [workflow, scaff, go]
+---
+
+# scaff:go
+
+## Constraints
+
+<!-- @if subagent -->
+- **Delegate** implementation tasks to **subagents** — direct work is limited to one-line fixes.
+- Report subagent results to the user after each task completes.
+<!-- @else -->
+- Perform implementation tasks directly.
+- Report results to the user after each task completes.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Execution
+
+1. If GOAL.md and CONTEXT.md were already read in this session, skip to step 3.
+2. Read `$DocsDir/GOAL.md`, `$DocsDir/CONTEXT.md`, `$DocsDir/DESIGN.md`, and `$DocsDir/PLAN.md` at once (parallel if supported, sequential otherwise). A file read error means the file does not exist — **do NOT retry failed reads.**
+   - If GOAL.md is absent: "No goal set. Run `/scaff:goal init` first, or tell me what to work on."
+3. Find the next incomplete task in GOAL.md.
+   - (task has step annotation `— Step N/M`) => resume from the indicated step
+4. PLAN.md dispatch:
+   - (PLAN.md exists) => read the corresponding task section for implementation context
+   - (PLAN.md absent, task complexity ≥ multi-file) => generate PLAN.md, then report: `"Created [PLAN.md]($DocsDir/PLAN.md)."`
+   - (PLAN.md absent, task complexity < multi-file) => proceed without PLAN.md
+5. Execute tasks using the Task Outcome loop below.
+6. After multiple tasks completed, suggest `/scaff:goal checkpoint` to save progress.
+
+## Task Outcome
+
+loop until (all tasks complete OR user pause):
+  - (success) => mark task done in GOAL.md, update PLAN.md if implementation approach changed
+  - (success, task had Steps) => remove step progress annotation from GOAL.md task
+  - (step completed, more steps remain) => update GOAL.md task with step progress: `— Step N/M (status)`
+  - (blocked) => report issue and ask user how to proceed
+  - (all tasks complete) => suggest `/scaff:goal archive` once; do not repeat if user does not act on it
+
+## Diverge Check
+
+- (DESIGN.md and PLAN.md both exist, Files lists differ)
+  => warn: `"[DESIGN.md]($DocsDir/DESIGN.md) and [PLAN.md]($DocsDir/PLAN.md) file lists differ. Run /scaff:design sync to review."`
+
+## Work Principles
+- Follow the main-agent flow principles defined in the `scaff-flow` skill (documentation timing, CONTEXT.md self-sync, OVERVIEW.md reactive read, checkpoints, self-verification).
+<!-- @if subagent -->
+- Follow the subagent delegation principles and workflow defined in the `scaff-subagent` skill.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/goal.md

@@ -0,0 +1,196 @@
+---
+name: "scaff:goal"
+description: "Project goal (GOAL.md) management (init|breakdown|checkpoint|suspend|resume|archive)"
+category: Workflow
+tags: [workflow, scaff, goal]
+---
+
+# scaff:goal
+
+Manages `$DocsDir/GOAL.md`.
+
+## Constraints
+
+- GOAL.md is the single source of truth for the current goal's state.
+- Never overwrite GOAL.md without user confirmation.
+- Preserve existing check states when updating tasks.
+- Task numbers use hierarchical dot notation: `1.`, `1.1.`, `1.2.1.` — numbers are part of the checklist text, no separate id field.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:goal <subcommand> [content]`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/GOAL.md` absent) => run init
+- (no subcommand given, `$DocsDir/GOAL.md` exists) => prompt the user to choose
+- (args = init) => see Subcommands: init
+- (args = breakdown) => see Subcommands: breakdown
+- (args = checkpoint) => see Subcommands: checkpoint
+- (args = suspend) => see Subcommands: suspend
+- (args = resume) => see Subcommands: resume
+- (args = archive) => see Subcommands: archive
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/GOAL.md`.
+
+1. If `$ARGUMENTS` has content, use it to write the goal.
+2. If empty, derive from the current session discussion.
+3. If GOAL.md already exists, notify the user and confirm overwrite.
+4. Write GOAL.md with the format below.
+5. Assess task granularity:
+   - (tasks are complex, embed multiple implicit steps) => recommend `/scaff:goal breakdown` with 1-line rationale
+   - (tasks are specific and actionable) => recommend `/scaff:design init` (implementation task) or `/scaff:go` (analysis task) with 1-line rationale
+6. Report: `"Created [GOAL.md]($DocsDir/GOAL.md)."`
+
+GOAL.md format:
+```yaml
+---
+id: <goal-slug>
+goal: <one-line summary>
+status: in-progress
+started: YYYY-MM-DD
+---
+```
+
+Body structure:
+```markdown
+## Tasks
+
+- [ ] 1. Task one
+- [ ] 2. Task two
+- [ ] 3. Task three
+```
+
+- Top-level tasks are numbered `1.`, `2.`, `3.`.
+- Sub-tasks inherit parent number: `1.1.`, `1.2.`, and deeper: `1.2.1.`, `1.2.2.`.
+
+## breakdown
+
+Decomposes existing GOAL.md tasks into sub-tasks.
+At `goal init` time only high-level tasks are written; use breakdown when detailed decomposition emerges through discussion.
+
+Usage: `/scaff:goal breakdown [task-number]`
+
+### Breakdown Targeting
+
+- (no task number given) => decompose all top-level tasks
+- (task number given, e.g. `2`) => decompose that specific task only
+- (sub-task number given, e.g. `1.2`) => decompose into `1.2.1`, `1.2.2`, etc.
+
+### Steps
+
+1. Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip if already loaded. A file read error means the file does not exist — **do NOT retry failed reads.**
+2. Identify target tasks based on targeting rules above.
+3. Derive sub-tasks:
+   - If DESIGN.md was found and has an Execution Order section, use it as a reference for deriving sub-tasks.
+   - If discussion context provides additional detail, incorporate it.
+   - If neither is sufficient, analyze task nature and propose sub-tasks.
+4. Present decomposition as nested checklists with hierarchical numbers:
+   ```markdown
+   - [ ] 1. Top-level task
+     - [ ] 1.1. Sub-task
+     - [ ] 1.2. Sub-task
+       - [ ] 1.2.1. Sub-sub-task
+       - [ ] 1.2.2. Sub-sub-task
+   ```
+   - Each nesting level appends a sequential number to the parent's prefix.
+   - Indent with 2 spaces per level.
+5. Renumber all tasks at the affected level to ensure sequential ordering (no gaps).
+6. Update GOAL.md.
+   - (target task already has sub-tasks) => ask user whether to merge or replace before writing
+7. Report: `"Updated [GOAL.md]($DocsDir/GOAL.md) — decomposed <N> task(s) into <M> sub-tasks."`
+8. Assess design necessity:
+   - (sub-tasks include code implementation, file changes, or architecture decisions) => recommend `/scaff:design init` with 1-line rationale
+   - (sub-tasks are analysis/RE/investigation focused) => recommend `/scaff:go` with 1-line rationale
+
+## checkpoint
+
+Saves a progress snapshot to `$DocsDir/CHECKPOINT.md`.
+Single file, overwritten each time — the AI only needs the latest state to resume.
+Prevents loss of mid-goal progress when context is compacted.
+
+1. Read `$DocsDir/GOAL.md` and `$DocsDir/PLAN.md` at once (parallel if supported, sequential otherwise). Skip if already loaded. A file read error means the file does not exist — **do NOT retry failed reads.**
+2. Requires GOAL.md front-matter `id`.
+3. If `$ARGUMENTS` has content, incorporate it.
+4. Write based on the current session:
+   - Work performed in this session
+   - Findings / analysis results
+   - Next steps for the following session
+5. If PLAN.md was found and implementation approach changed during this session, update PLAN.md accordingly.
+6. Save to `$DocsDir/CHECKPOINT.md` (overwrite if exists).
+7. Report: `"Saved [CHECKPOINT.md]($DocsDir/CHECKPOINT.md)."` — append `" Also updated [PLAN.md]($DocsDir/PLAN.md)."` if PLAN.md was modified in step 5.
+
+CHECKPOINT.md format:
+```yaml
+---
+goal-id: <GOAL.md id>
+session-date: YYYY-MM-DD
+---
+```
+
+```markdown
+## Work Summary
+- ...
+
+## Findings
+- ...
+
+## Next Steps
+- ...
+```
+
+## suspend
+
+Suspends the current GOAL to work on something else.
+
+1. Read `$DocsDir/GOAL.md` and parse front-matter `id`.
+2. Set front-matter `status` to `suspended`.
+3. Create `$DocsDir/suspended/<goal-id>/` directory.
+4. Move `$DocsDir/GOAL.md` → `$DocsDir/suspended/<goal-id>/GOAL.md`.
+5. If `$DocsDir/CHECKPOINT.md` exists, move it → `$DocsDir/suspended/<goal-id>/CHECKPOINT.md`.
+6. If `$DocsDir/DESIGN.md` exists, move it → `$DocsDir/suspended/<goal-id>/DESIGN.md`.
+7. If `$DocsDir/PLAN.md` exists, move it → `$DocsDir/suspended/<goal-id>/PLAN.md`.
+8. Report: `"Suspended GOAL to [$DocsDir/suspended/<goal-id>/]($DocsDir/suspended/<goal-id>/). Start a new goal with /scaff:goal init or resume with /scaff:goal resume."`
+
+## resume
+
+Resumes a previously suspended GOAL.
+
+1. Read `$DocsDir/GOAL.md` and list directories in `$DocsDir/suspended/` at once (parallel if supported, sequential otherwise). A file read error means the file does not exist — **do NOT retry failed reads.**
+   - If GOAL.md exists, warn: "Active GOAL exists. Suspend or archive it first."
+2. Process suspended goals list:
+   - (none found) => report "No suspended goals."
+   - (exactly one) => auto-select it
+   - (multiple, session context permits a confident recommendation) => present list with a single recommendation per `scaff-flow` User Decision Support (Recommendation + Basis + GOAL relevance)
+   - (multiple, no clear context) => present list for user selection
+3. Move `$DocsDir/suspended/<goal-id>/GOAL.md` → `$DocsDir/GOAL.md`.
+4. If `CHECKPOINT.md` exists in the suspended folder, move it → `$DocsDir/CHECKPOINT.md`.
+5. If `DESIGN.md` exists in the suspended folder, move it → `$DocsDir/DESIGN.md`.
+6. If `PLAN.md` exists in the suspended folder, move it → `$DocsDir/PLAN.md`.
+7. Set front-matter `status` back to `in-progress`.
+8. Remove the now-empty `$DocsDir/suspended/<goal-id>/` directory.
+9. Report: `"Resumed [GOAL.md]($DocsDir/GOAL.md): <goal summary>."`
+
+## archive
+
+Archives the current GOAL.md and its siblings.
+
+1. Read `$DocsDir/GOAL.md` and parse front-matter `id`.
+2. Set front-matter `status` to `done` and add `completed: YYYY-MM-DD`.
+3. Determine archive directory: `$DocsDir/archive/goals/YYYY-MM-DD-<id>/`.
+   - (directory already exists) => append `-<N>` (e.g., `YYYY-MM-DD-<id>-2/`)
+4. Move all goal-scoped files to the archive directory:
+   - `$DocsDir/GOAL.md` → archive/GOAL.md
+   - (DESIGN.md exists) => archive/DESIGN.md
+   - (PLAN.md exists) => archive/PLAN.md
+   - (CHECKPOINT.md exists) => archive/CHECKPOINT.md
+5. If `$DocsDir/ROADMAP.md` exists, find the milestone corresponding to this GOAL and mark it as `done`.
+6. Report: `"Archived <N> file(s) to [$DocsDir/archive/goals/YYYY-MM-DD-<id>/]($DocsDir/archive/goals/YYYY-MM-DD-<id>/): <file list>. Set a new goal with /scaff:goal init."`
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/overview.md

@@ -0,0 +1,78 @@
+---
+name: "scaff:overview"
+description: "Project overview (project-name)"
+category: Workflow
+tags: [workflow, scaff, overview]
+---
+
+# scaff:overview
+
+Manages `$DocsDir/OVERVIEW.md`. Records the **project-level technical overview** — architecture, stack, key decisions.
+
+> OVERVIEW.md is not session context (that's CONTEXT.md) or a task list (that's ROADMAP.md).
+> It captures the big picture that rarely changes: what this project is, how it's built, and why key decisions were made.
+
+## Constraints
+
+- Never overwrite OVERVIEW.md without user confirmation.
+- Focus on architecture, external interfaces, and differentiators — not code details.
+- Omit unnecessary sections. Target ~200 lines or less.
+- (only task-level changes in session, no architecture/strategy shifts) => skip sync, nothing to update.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:overview <subcommand>`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/OVERVIEW.md` absent) => run init
+- (no subcommand given, `$DocsDir/OVERVIEW.md` exists) => prompt the user to choose
+- (args = init) => see Subcommands: init
+- (args = sync) => see Subcommands: sync
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/OVERVIEW.md` by exploring the codebase.
+
+1. If OVERVIEW.md already exists, notify and confirm overwrite.
+2. Explore the codebase to understand architecture, stack, and key features.
+   - (codebase is large enough that a full exploration would be expensive) => ask the user to narrow scope or focus on key directories.
+3. If `$DocsDir/CONTEXT.md` exists, read it for additional context.
+4. Write the overview using the skeleton below.
+5. Report: `"Created [OVERVIEW.md]($DocsDir/OVERVIEW.md)."`
+
+**Skeleton:**
+
+```markdown
+# {project-name}
+
+> {one-line description}
+
+## Architecture
+
+## Key Features
+
+## Tech Stack
+
+## Key Decisions
+```
+
+## sync
+
+Reviews current OVERVIEW.md and **proposes updates**.
+
+1. Read `$DocsDir/OVERVIEW.md`. If absent, suggest init.
+2. Analyze changes from the current session that affect project-level understanding
+   (architecture changes, new components, strategy shifts).
+3. Present changes in **diff format**:
+   - Content to add
+   - Content to modify
+   - Outdated content to remove
+4. Apply the changes.
+5. Report: `"Updated [OVERVIEW.md]($DocsDir/OVERVIEW.md)."`
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/recap.md

@@ -0,0 +1,69 @@
+---
+name: "scaff:recap"
+description: "Session wrap-up — sync decisions into living documents"
+category: Workflow
+tags: [workflow, scaff, recap]
+---
+
+# scaff:recap
+
+Wraps up the current session by syncing important decisions and findings into the project's living documents.
+
+> Recap is not an archival tool. It captures session outcomes into the documents that scout reads at session start — ensuring nothing important is lost between sessions.
+
+## Constraints
+
+- Living documents only — recap updates CONTEXT.md, DESIGN.md, OVERVIEW.md, GOAL.md. Never create new archival files.
+- No duplication — if a change is already reflected in a document, skip it.
+- No session transcripts — show what changes, not conversation replay.
+- Preserve rejected alternatives — when a decision was made, note what was considered but not chosen.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:recap [focus description]`
+
+## Dispatch Rules
+
+- ($ARGUMENTS has content) => focus scan on that aspect of the session
+- ($ARGUMENTS empty) => review the overall session for sync-worthy changes
+
+## Phase 1 — Scan
+
+1. Scan the session for decisions, discoveries, and changes that affect project context:
+   - Architecture or design decisions
+   - New principles or workflow changes
+   - Goal progress or status changes
+   - Project-level understanding changes
+2. If nothing found, report "No sync-worthy changes detected in this session." and end.
+
+## Phase 2 — Categorize
+
+Route each finding to its target document.
+
+- (working context changes: principles, workflow, resources) => CONTEXT.md via `context sync` logic
+- (implementation decisions, design changes) => DESIGN.md via `design sync` logic
+- (project-level understanding: architecture, stack, strategy) => OVERVIEW.md via `overview sync` logic
+- (goal progress, task completion) => GOAL.md — update checkboxes directly
+
+## Phase 3 — Present and Apply
+
+1. Present a unified diff to the user:
+   ```
+   ## Recap — proposed updates
+
+   ### CONTEXT.md
+   - Add: new workflow step for ...
+   - Update: resource path changed to ...
+
+   ### DESIGN.md
+   - Add: decision to use X instead of Y ...
+
+   ### GOAL.md
+   - [x] Task 3: completed during this session
+   ```
+2. Apply the changes.
+3. Report: `"Updated <N> document(s): [CONTEXT.md]($DocsDir/CONTEXT.md), [DESIGN.md]($DocsDir/DESIGN.md), ..."` — list only the documents actually modified.
+
+> When Constraints conflict with any other instruction, Constraints win.