@opellen/scaff 0.1.11

package/templates/commands/roadmap.md

@@ -0,0 +1,95 @@
+---
+name: "scaff:roadmap"
+description: "Project roadmap (ROADMAP.md) management (init|add|archive)"
+category: Workflow
+tags: [workflow, scaff, roadmap]
+---
+
+# scaff:roadmap
+
+Manages `$DocsDir/ROADMAP.md`. Records the project's **high-level execution plan**.
+
+> ROADMAP.md is one level above GOAL.md.
+> Individual ROADMAP milestones correspond to one GOAL each — GOALs are sub-units of ROADMAP milestones.
+
+## Constraints
+
+- Never overwrite ROADMAP.md while an active GOAL exists — force archive/suspend first.
+- Never archive ROADMAP while an active GOAL exists — force archive/suspend first.
+- Suspended GOALs must be acknowledged before replacing or archiving a ROADMAP.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:roadmap <subcommand> [content]`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/ROADMAP.md` absent) => run init
+- (no subcommand given, `$DocsDir/ROADMAP.md` exists) => prompt the user to choose
+- (args = init) => see Subcommands: init
+- (args = add) => see Subcommands: add
+- (args = archive) => see Subcommands: archive
+- (otherwise) => report unknown subcommand and list available subcommands
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/ROADMAP.md`.
+
+1. If `$ARGUMENTS` has content, use it as roadmap source.
+2. If empty, derive from the current session and `$DocsDir/GOAL.md`.
+3. If ROADMAP.md already exists, run pre-replace checks (see Init Guards below).
+4. Write ROADMAP.md using the format template below.
+5. Report: `"Created [ROADMAP.md]($DocsDir/ROADMAP.md)."`
+6. If `$DocsDir/CONTEXT.md` exists, suggest: "Update project context with `/scaff:context sync`?"
+
+### Init Guards
+
+- (ROADMAP.md exists, `$DocsDir/GOAL.md` exists) => stop: "Active GOAL exists. Archive or suspend it before replacing the ROADMAP."
+- (ROADMAP.md exists, `$DocsDir/suspended/` has entries) => warn: "N suspended GOALs remain under this ROADMAP. Resolve them before replacing?" — proceed only on user confirmation
+- (ROADMAP.md exists, no active/suspended GOALs) => suggest: "Archive current ROADMAP first with `/scaff:roadmap archive`? Or overwrite?"
+
+### ROADMAP.md Format Template
+
+```markdown
+---
+id: <roadmap-slug>
+title: <one-line summary>
+status: active
+started: YYYY-MM-DD
+---
+
+- [ ] **M1: <title>**
+  - <details>
+
+- [ ] **M2: <title>**
+  - <details>
+```
+
+## add
+
+Adds a milestone entry to `$DocsDir/ROADMAP.md`.
+
+1. Add `$ARGUMENTS` content as a new milestone entry.
+2. Number sequentially after existing milestones.
+3. Report: `"Updated [ROADMAP.md]($DocsDir/ROADMAP.md) — added milestone M<N>."`
+
+## archive
+
+Archives the entire ROADMAP.md. Use when all milestones are complete or the roadmap is being replaced.
+
+1. Run archive guards (see Archive Guards below).
+2. Read `$DocsDir/ROADMAP.md` and parse front-matter `id`.
+3. Set front-matter `status` to `done` and add `completed: YYYY-MM-DD`.
+4. Move to `$DocsDir/archive/roadmaps/YYYY-MM-DD-<id>.md`.
+5. Report: `"Archived to [$DocsDir/archive/roadmaps/YYYY-MM-DD-<id>.md]($DocsDir/archive/roadmaps/YYYY-MM-DD-<id>.md). Create a new roadmap with /scaff:roadmap init."`
+
+### Archive Guards
+
+- (`$DocsDir/GOAL.md` exists) => stop: "Active GOAL exists. Archive or suspend it before archiving the ROADMAP."
+- (`$DocsDir/suspended/` has entries) => warn: "N suspended GOALs remain under this ROADMAP. Resolve them before archiving?" — proceed only on user confirmation
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/scout.md

@@ -0,0 +1,68 @@
+---
+name: "scaff:scout"
+description: "Project scout (project-name)"
+category: Workflow
+tags: [workflow, scaff, scout]
+---
+
+## Constraints
+
+<!-- @if subagent -->
+- **Delegate** analysis and implementation tasks to **subagents** — direct work is limited to one-line fixes.
+- Report subagent results to the user.
+<!-- @else -->
+- Perform analysis and implementation tasks directly.
+- Report results to the user.
+<!-- @endif -->
+- Report status based solely on docs files read during initialization — do not read other files proactively.
+- Keep suggestions to 1-2 lines — follow the user's direction if they want something different.
+- Skip suggestions if the user starts with a specific task instruction.
+- GOAL.md tasks are always the unit of progress — DESIGN.md is a reference document, not a progress tracker.
+- In Discovery Mode: don't rush to formalize — sometimes thinking IS the value.
+- (creating CONTEXT.md) => suggest `/scaff:context init` — do not write CONTEXT.md directly.
+- (creating GOAL.md) => suggest `/scaff:goal init` — do not write GOAL.md directly.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+# Session Initialization
+
+1. Read all of these files at once (parallel if supported, sequential otherwise):
+   - `$DocsDir/CONTEXT.md`, `$DocsDir/GOAL.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, `$DocsDir/ROADMAP.md`, `$DocsDir/CHECKPOINT.md`
+   - A file read error means the file does not exist — mark it as "not present" and move on. **Do NOT retry failed reads.**
+2. If no GOAL.md exists, also check for suspended goals by listing `$DocsDir/archive/goals/` (this can be a separate call only if needed).
+3. Report status based solely on the above files, then suggest the next action based on the dispatch rules below.
+
+## State Dispatch
+
+- (no CONTEXT.md, no/minimal code) => enter **Discovery Mode**
+- (no CONTEXT.md, existing codebase) => suggest `/scaff:context init`
+- (CONTEXT.md only, no GOAL, no ROADMAP) => suggest `/scaff:goal init` or `/scaff:roadmap init`
+- (CONTEXT.md + ROADMAP.md, no GOAL) => suggest picking a milestone from ROADMAP.md and starting with `/scaff:goal init`
+- (no GOAL.md, suspended goals exist) => list suspended goals, suggest `/scaff:goal resume`
+- (GOAL.md + CHECKPOINT.md) => show checkpoint summary, suggest `/scaff:go`
+- (GOAL.md, no DESIGN.md, implementation task) => suggest `/scaff:design init`
+- (GOAL.md, no DESIGN.md, analysis task) => suggest `/scaff:go`
+- (GOAL.md + DESIGN.md) => suggest `/scaff:go`
+- (GOAL.md completed) => suggest `/scaff:goal archive`
+
+**Implementation vs Analysis criteria**: If GOAL.md sub-tasks contain keywords like "analyze", "investigate", "audit", "research", "document", or the deliverable is an `.md` analysis doc, it's an analysis task. If the goal is coding, porting, or implementation, it's an implementation task.
+
+# Discovery Mode
+
+When the user's intent is unclear or exploratory (`/scaff:scout` with no specific task, or a vague topic):
+
+- Be curious, not prescriptive — ask questions, don't follow a script
+- Explore multiple directions and let the user follow what resonates
+- Visualize with ASCII diagrams when they'd help clarify thinking
+- Ground discussions in actual codebase, don't just theorize
+- When insights crystallize, use the corresponding commands to capture them:
+  - Project context => run `/scaff:context init`
+  - First objective => suggest `/scaff:goal init`
+
+# 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/verify.md

@@ -0,0 +1,112 @@
+---
+name: "scaff:verify"
+description: "Verify implementation against goal, design, and code"
+category: Workflow
+tags: [workflow, scaff, verify]
+---
+
+# scaff:verify
+
+Cross-checks the current implementation state against GOAL.md and DESIGN.md to surface gaps before archiving.
+
+## Constraints
+
+<!-- @if subagent -->
+- **Delegate** analysis and verification tasks to **subagents** — direct work is limited to one-line fixes.
+- Report subagent results to the user.
+<!-- @else -->
+- Perform analysis and verification tasks directly.
+- Report results to the user.
+<!-- @endif -->
+- Design Alignment focuses on structural decisions, not style preferences — ignore cosmetic differences.
+- Task Coverage is mechanical — checkbox state vs code presence, low ambiguity.
+- Assign severity based on the strongest evidence available — no concrete signal means don't flag.
+- Omit issues without a `file:line` pointer and a concrete action.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/scaff:verify [focus area]`
+
+- If `$ARGUMENTS` has content, use it as the focus area for verification.
+- If empty, infer the verification scope from the current session context (recent work, active goal, design).
+- If unable to determine what to verify, prompt the user to specify.
+
+# Workflow
+
+## Phase 1 — Read Context
+
+Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip if already in session context. A file read error means the file does not exist — **do NOT retry failed reads.**
+- If GOAL.md has front-matter `id`, glob `$DocsDir/logs/*-<goal-id>-*.md` and read the latest 1-2 for session history.
+
+### Check Dispatch
+
+- (GOAL + DESIGN) => run full verification (Phases 2–4)
+- (GOAL only) => skip Phase 2, run Phases 3–4
+- (neither, $ARGUMENTS given) => freeform check against `$ARGUMENTS`
+- (neither, no $ARGUMENTS) => ask the user what to verify
+
+## Phase 2 — Design Alignment
+
+> Requires: DESIGN.md. Skip if absent.
+
+Check whether the implementation follows the planned architecture.
+
+1. Scan DESIGN.md for structural decisions (file layout, module boundaries, execution flow).
+2. Compare each against the actual codebase.
+3. Flag contradictions as **CONFLICT** — "Deviates from design: \<decision\>"
+4. Spot new/modified files that break project conventions.
+5. Flag convention breaks as **STYLE** — "Breaks project pattern: \<details\>"
+
+## Phase 3 — Task Coverage
+
+> Requires: GOAL.md.
+
+Walk every checkbox in GOAL.md (including nested sub-tasks) and classify each:
+
+- (checked `[x]`) => counted as done
+- (unchecked `[ ]`, codebase evidence found) => **REVIEW** — likely done but unmarked
+- (unchecked `[ ]`, no codebase evidence) => **BLOCKED** — work remains
+
+Output: `done / total` with list of unmarked and blocked items.
+
+## Phase 4 — Intent Match
+
+> Requires: GOAL.md with at least one completed task.
+
+For each completed task, check whether the implementation matches what the task describes:
+
+1. Locate relevant code paths via function names, types, or module structure.
+2. Evaluate whether the code behavior matches the stated goal.
+3. Flag mismatches as **DRIFT** — "Implementation differs from stated intent: \<details\>"
+
+If `$ARGUMENTS` narrows the scope, focus on that area first.
+
+## Phase 5 — Report
+
+```
+## Verify Summary
+
+| Check            | Result                |
+|------------------|-----------------------|
+| Design Alignment | clean / N conflicts   |
+| Task Coverage    | done/total (N issues) |
+| Intent Match     | N drifts found        |
+```
+
+**Issues (ordered by severity):**
+
+- **BLOCKED**: Incomplete work that must be finished
+- **CONFLICT**: Implementation contradicts design decisions
+- **DRIFT**: Completed work that doesn't match stated intent
+- **REVIEW**: Ambiguous situations needing user judgment
+- **STYLE**: Convention deviations worth considering
+
+### Archive Readiness
+
+- (highest = BLOCKED or CONFLICT) => do not archive — resolve first
+- (highest = DRIFT or REVIEW) => archive at your discretion
+- (no issues) => clear to archive
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/skills/scaff-flow/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: scaff-flow
+description: Main-agent flow principles for scaff workflows — documentation timing, CONTEXT.md self-sync, checkpoint triggers, OVERVIEW.md reactive read, self-verification, and decision support. Use whenever the main agent is driving a scaff session, regardless of subagent availability.
+license: MIT
+metadata:
+  version: "1.0"
+  generatedBy: $ScaffVersion
+---
+
+# scaff-flow
+
+## Constraints
+
+- Never execute documentation commands automatically — suggest only.
+- Never auto-read OVERVIEW.md. Only read after a reactive trigger fires AND the user approves.
+- Self-verification is mandatory before marking any GOAL.md task or ROADMAP.md milestone as done.
+- Handoff recommendations (after any scaff command completes) are single-path and decisive — do not enumerate alternatives. Presenting multiple options applies only to genuine decision forks, not handoffs.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Documentation Timing
+
+- (implementation plan crystallizes — files, design decisions, execution order) => suggest `/scaff:design init`
+- (design changes during implementation) => suggest `/scaff:design sync`
+- (project context changes — principles, resources, processes) => suggest `/scaff:context sync`
+- (multiple GOALs need a higher-level plan) => suggest `/scaff:roadmap init`
+- (new milestone identified) => suggest `/scaff:roadmap add`
+- (DESIGN.md step completed) => suggest `/scaff:design sync`
+- (multiple design decisions or context changes accumulated but not yet documented) => suggest `/scaff:recap`
+
+Keep suggestions brief: "Implementation plan ready — document with `/scaff:design init`?"
+
+## CONTEXT.md Self-Sync
+
+CONTEXT.md is the main agent's working memory — it should grow as the session reveals new project facts. Suggest `/scaff:context sync` proactively when any of these signals fire:
+
+- (new resource discovered — file, directory, external system worth referencing) => suggest sync
+- (workflow step refined — a procedure the AI repeats and should remember) => suggest sync
+- (new project principle articulated by user — e.g. "always do X", "never do Y") => suggest sync
+- (new analysis topic / index entry — for projects that maintain analysis tables) => suggest sync
+- (session about to end AND uncommitted context changes accumulated) => suggest sync as part of wrap-up
+
+Cap: at most one CONTEXT.md sync suggestion per session unless the user explicitly accepts an earlier one.
+
+## OVERVIEW.md Reactive Read
+
+OVERVIEW.md is a project-level architectural reference. It is **never auto-loaded**. Read it only when a reactive event explicitly signals that big-picture context is missing:
+
+- (GOAL intent appears to conflict with the actual code structure) => check for OVERVIEW.md, ask user before reading
+- (a subagent reports "project-wide context needed" or paraphrases architecture inaccurately) => same
+- (user prompt literally asks "why was X designed this way?", "what's the overall structure?", "big picture", or types `$DocsDir/OVERVIEW.md`) => same
+- (otherwise) => do NOT read OVERVIEW.md, do NOT suggest reading
+
+When the trigger fires:
+1. Confirm `$DocsDir/OVERVIEW.md` exists (existence check only).
+2. If absent, inform the user and proceed without it.
+3. If present, surface the affordance to the user — *do not auto-read*. Example: "Architectural ambiguity detected. `$DocsDir/OVERVIEW.md` is available — load it?"
+4. Read only after explicit user approval, then keep the result in session (skip-if-loaded for subsequent triggers).
+
+> Bias control: when the trigger condition is uncertain, **default to NOT reading**. The cost of missing one read is small; the cost of always-loading is structural.
+
+## Checkpoint Triggers
+
+- (analysis/exploration session getting long, compact approaching) => suggest `/scaff:goal checkpoint`
+- (context window approaching 80% capacity, if platform supports detection) => suggest `/scaff:goal checkpoint`
+- (sequential analysis of multiple functions/modules, intermediate results accumulating) => suggest `/scaff:goal checkpoint`
+- (before ending a session) => suggest `/scaff:goal checkpoint`
+
+## Blocker Handling
+
+When the current goal cannot proceed (discovered bug, missing dependency, blocking issue):
+
+- (blocker identified, current GOAL cannot progress) => suggest `/scaff:goal suspend` followed by `/scaff:goal "<blocker description>"` to address the blocker as its own goal
+- (blocker goal archived, suspended goals remain) => suggest `/scaff:goal resume` to continue a suspended goal
+- (nested blockers) => same pattern recursively; `suspended/<goal-id>/` stacks naturally, `resume` presents a list when multiple
+
+This preserves "one active GOAL.md at a time" — simpler than in-place stacking schemes.
+
+## Self-Verification
+
+Before checking off a GOAL.md task or ROADMAP.md milestone as "done", verify:
+
+> **"Is this output ready to be used directly in the next step?"**
+
+1. **Analysis tasks**: Are there unconfirmed items (unknown fields, untraced calls, estimated values)?
+2. **Implementation tasks**: Do tests pass? Were edge cases considered?
+3. **Documentation tasks**: Are there missing sections or placeholders?
+
+- (anything lacking) => do not check off, report gaps to user, verify again after remediation
+
+## Execution Handoff
+
+- (goal breakdown completed) => suggest `/scaff:go`
+- (design init completed) => suggest `/scaff:go`
+- (goal resumed from suspension) => suggest `/scaff:go`
+- (goal checkpoint saved, tasks remain) => suggest `/scaff:go`
+- (session start, active GOAL.md with uncompleted tasks) => suggest `/scaff:go`
+
+## User Decision Support
+
+When responding to the user with multiple options — implementation choices, next scaff step, design alternatives, or any decision branching — include:
+
+1. **Recommendation** — Highlight one option with rationale.
+2. **Basis** — 1-line expected outcome (and tradeoff if any).
+3. **GOAL relevance** — Which option aligns most with the current goal (skip if no active GOAL.md).
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/skills/scaff-subagent/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: scaff-subagent
+description: Subagent delegation principles, prompt rules, and scout-split-execute workflow. Use when the main agent dispatches work to subagents.
+license: MIT
+metadata:
+  version: "1.0"
+  generatedBy: $ScaffVersion
+---
+
+# scaff-subagent
+
+## Constraints
+
+- Main agent analyzes and coordinates — delegate implementation and exploration to subagents.
+- (subagent prompt missing any required element) => do not dispatch until complete (see Prompt Requirements)
+- (5+ consecutive Read/Grep without Edit/Write) => stop and report to user
+- A subagent's "done" is a claim, not a fact — main verifies before accepting.
+
+> Main-agent flow concerns (documentation timing, checkpoints, self-verification, decision support) live in the **`scaff-flow`** skill.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Platform Dispatch
+
+- (subagents available, e.g. Claude Code, Codex) => delegate tasks to subagents per workflow below
+- (subagents not available) => execute tasks inline directly — apply Task Complexity Dispatch for work breakdown and Post-Verify after each task; prompt/status/model sections do not apply
+
+## Task Complexity Dispatch
+
+- (1-line fix, typo) => main agent fixes directly
+- (single file, clear change, < 30 lines) => one subagent, skip post-verify
+- (multi-file or design judgment needed) => full workflow (Scout → Split → Execute)
+- (otherwise) => ask user for scope guidance
+
+## Subagent Prompt Requirements
+
+Each subagent prompt must include all seven elements:
+
+1. **Scope** — Explicitly bound files/modules.
+2. **Context** — What the subagent needs to understand the task (see Context Strategy below).
+3. **Goal** — Specific completion criteria (e.g., "tests pass", "parser implemented with output").
+4. **Constraints** — What must not be modified.
+5. **Output** — Expected format (e.g., "change summary + findings").
+6. **Depth** — Analysis depth (e.g., "call chain 2 levels deep", "direct dependencies only").
+7. **Ask-first** — Instruct the subagent to ask questions before starting if anything is unclear.
+
+### Context Strategy
+
+Main reads and selects — the subagent focuses on execution.
+
+- (implementation) => include source of files to be modified; reference-only files as paths
+- (exploration/analysis) => specify target paths and search scope (no source embedding)
+
+### Prompt Example
+
+```
+Scope: src/auth/session.ts only. Do not modify other files.
+
+Context:
+Current implementation of src/auth/session.ts:
+[paste full source here]
+
+Goal: Replace JWT verification with session-based auth. Existing tests must pass.
+Constraints: Use express-session API only. No custom middleware.
+Output: Change summary + test results.
+Depth: session.ts internals only. No call chain tracing needed.
+Ask-first: If anything is unclear, ask before starting.
+```
+
+## Model Selection
+
+- (single file, clear spec) => fast model (e.g. haiku)
+- (multi-file, integration/judgment) => standard model (e.g. sonnet)
+- (architecture, design, review) => capable model (e.g. opus)
+- (otherwise) => standard model
+
+## Workflow: Scout → Split → Execute
+
+### Phase 1 — Scout
+
+Before dispatching any subagent, main must complete scoping:
+
+1. Identify candidate files related to the task (search by keyword, trace from entry point).
+2. Read candidate files in parallel (batch all reads at once, do NOT read one-by-one). Extract relevant sections.
+3. Define the investigation scope (files, modules, boundaries).
+
+Only then:
+4. Construct subagent prompt with all seven required elements, including source from step 2 as Context.
+5. Dispatch one exploratory subagent.
+6. Receive findings and assess scope for splitting.
+
+### Phase 2 — Split
+
+- (PLAN.md exists) => use PLAN.md tasks as the split basis
+- (PLAN.md absent, DESIGN.md exists) => use DESIGN.md Execution Order as the split basis
+- (neither) => derive split from scout findings
+
+1. Break work into independent sub-tasks.
+2. Apply split criteria: different files/modules, no shared state.
+3. Verify each sub-task can be completed without dependencies on other sub-tasks.
+
+### Phase 3 — Execute (Parallel)
+
+for each task:
+  1. Construct subagent prompt with all seven required elements.
+     - If PLAN.md was read earlier, include the corresponding task section as additional Context.
+  2. Dispatch subagent.
+  3. Handle status response (see Status Protocol below).
+  4. Post-verify: main confirms the output (see Post-Verify below).
+  5. Report result to user.
+
+After all tasks complete: consolidate results, check for conflicts, and report to user.
+
+#### Status Protocol
+
+loop until resolved:
+  - (DONE) => post-verify, then mark complete
+  - (DONE_WITH_CONCERNS, correctness/scope issue) => resolve before proceeding
+  - (DONE_WITH_CONCERNS, observation) => note it, proceed to post-verify
+  - (NEEDS_CLARIFICATION) => answer the subagent's questions, re-dispatch with answers
+  - (NEEDS_CONTEXT) => provide missing context, re-dispatch
+  - (BLOCKED) => break task down further or escalate to user
+
+#### Post-Verify
+
+Main agent confirms subagent output before marking a task complete:
+
+- (implementation task) => read changed files, compare against GOAL.md task description
+- (exploration/analysis task) => spot-check 1-2 key claims against the codebase
+- (trivial fix) => skip
+
+> When Constraints conflict with any other instruction, Constraints win.