forge-orkes 0.3.11 → 0.3.13

package/template/.claude/skills/forge/SKILL.md

@@ -5,193 +5,193 @@ description: "START HERE for any task. Forge orchestrates Quick fixes, Standard
 
 # Forging: Workflow Orchestration
 
-Entry point. Detect tier, route to skills, manage state transitions. For new projects, run init before work begins.
+Entry point. Detect tier, route skills, manage transitions. New projects → init first.
 
 ## Step 1: Read State
 
 ### Milestone Selection
 
-Check state files in order:
-1. `.forge/state/index.yml` exists → milestone-aware format
-2. `.forge/state.yml` exists (legacy) → suggest migration: *"I found a legacy state.yml. Migrate to milestone-aware format?"* If yes, create `.forge/state/`, split into `index.yml` + `milestone-1.yml`, delete old file.
-3. Neither exists → no state yet, proceed to init or tier detection.
-
-**When milestone-aware state exists (`state/index.yml`):**
-1. Read `.forge/state/index.yml` for active milestones
-2. **Check for milestone argument first.** If the user invoked `/forge` with an argument (e.g., `/forge 2`, `/forge "Auth system"`):
-   - Match against milestone IDs (exact number) or names (case-insensitive substring)
-   - Match found → auto-select, skip prompt: *"Resuming milestone {id}: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
-   - No match → warn and show interactive prompt: *"No milestone matching '{arg}'. Active milestones:"*
-3. **Multiple active milestones (no argument):** Present all with status and `last_updated`. Default to most recent. *"You have {N} active milestones. Most recent: [{name}] (status: {current.status}, last touched {date}). Work on this one, or switch?"*
-4. **One milestone:** Auto-select. *"Resuming milestone: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
-5. **No active milestones:** Proceed to init or ask user to create one.
-6. Load `.forge/state/milestone-{id}.yml`
-7. **Route on `current.status`, NOT `overall_percent`.** Status is the authoritative workflow position. A milestone is complete only when `current.status == complete`. Even at 100% `overall_percent`, remaining workflow steps (verifying, reviewing) must run.
-8. Report position, then **immediately route** (see Step 3):
-   - Workflow status (`current.status`) — primary position indicator
-   - Phase progress: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for unverified phases**
-   - Task progress (`overall_percent`) — measures task completion, not workflow completion
-   - **No menus.** State position, state next action, invoke skill.
-
-If Beads is installed and enabled (`settings.json → forge.beads_integration: true`), run `bd prime` for cross-session context. See `beads-integration` skill. Optional — Forge works without it.
-
-Read `.forge/context.md` if it exists. If **Needs Resolution** has unchecked items:
-- Warn immediately: *"There are {N} unresolved discrepancies from init: [list items]."*
-- Quick tier proceeds despite unresolved items
-- Standard/Full blocked at planning gate until resolved
-
-Check `.forge/refactor-backlog.yml` for pending items:
-- Count by effort level
-- *"You have {N} pending refactoring items ({Q} quick, {S} standard). Tackle any before new work?"*
-- User picks one → route to `quick-tasking` (quick) or Standard tier (standard). Set `status: in_progress`.
-- User declines → proceed normally.
-
-Check `.forge/state/index.yml → desire_paths` for patterns with 3+ occurrences not yet acted on:
-- *"Recurring pattern: [{description}] ({N} times). Address this by [suggested change]?"*
-- User agrees → apply change, reset counter
-- User declines → note it, move on. Don't nag every session.
-
-No `.forge/project.yml` AND Standard/Full tier → **Step 2A: Project Init**.
-State exists → **Step 2B: Detect Tier**.
+Check state files:
+1. `.forge/state/index.yml` → milestone-aware
+2. `.forge/state.yml` (legacy) → *"Migrate?"* Yes → split into `state/index.yml` + `milestone-1.yml`, delete old.
+3. Neither → init/tier detection.
 
-## Step 2A: Project Init
+**With `state/index.yml`:**
+1. Read for active milestones
+2. **Check arg first.** `/forge 2` or `/forge "Auth system"`:
+   - Match IDs (exact) or names (case-insensitive substring)
+   - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {overall_percent}%"*
+   - No match → *"No match for '{arg}'. Active:"*
+3. **Multiple (no arg):** Show all + status + `last_updated`. Default recent. *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
+4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {overall_percent}%"*
+5. **None:** Init or create.
+6. Load `milestone-{id}.yml`
+7. **Route on `current.status`, NOT `overall_percent`.** Complete only at `complete`. 100% tasks ≠ done -- verifying + reviewing must run.
+8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `overall_percent`. **No menus.** Position → action → invoke.
 
-No `.forge/project.yml` → invoke `Skill(initializing)`. It handles brownfield/greenfield detection, framework absorption, tech stack scanning, design system setup, and constitution config. After init, return here for tier detection.
+Beads enabled (`forge.beads_integration: true`) → `bd prime`. Optional.
 
-## Step 2B: Detect Tier
+Read `.forge/context.md`. **Needs Resolution** unchecked → warn: *"{N} unresolved discrepancies."* Quick proceeds; Standard/Full blocked at planning.
 
-### Quick Tier
-Match ANY: single file change, typo/grammar/formatting fix, config/env update, dependency bump, <50 lines estimated, user says "quick"/"small"/"minor"
+Check `.forge/refactor-backlog.yml`:
+- *"{N} refactors ({Q} quick, {S} standard). Tackle first?"*
+- Pick → `quick-tasking`/Standard, set `in_progress`. Decline → proceed.
 
-→ Route to `quick-tasking`
+Check `desire_paths` 3+ occurrences:
+- *"Recurring: [{description}] ({N}x). Fix via [suggestion]?"*
+- Agree → apply, reset. Decline → note, don't nag.
 
-### Standard Tier
-Match ANY: new feature/component, bug fix requiring investigation, multi-file refactor, external service integration, 1-8 hours estimated
+No `project.yml` + Standard/Full → **Step 2A**. State exists → **Step 2B**.
 
-→ `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing`
+### Parent Session Model Advisory
+
+Check `models.parent_session` from `project.yml`. Mismatch → *"Recommends {parent_session}, running {current}. `/model` to switch."*
+- Advisory only -- no block. Reviewer enforces at review gate.
+
+## Step 2A: Project Init
 
-### Full Tier
-Match ANY: new project, major architectural change, multi-phase milestone, complex multi-subsystem work, days of work estimated, user says "full"/"complex"/"project"/"milestone"
+No `project.yml` → `Skill(initializing)`. Brownfield/greenfield, absorption, stack scan, design system, constitution. Return after.
+
+## Step 2B: Detect Tier
+
+### Quick
+ANY: single file, typo/formatting, config/env, dep bump, <50 lines, "quick"/"small"/"minor"
+→ `quick-tasking`
+
+### Standard
+ANY: new feature/component, bug needing investigation, multi-file refactor, service integration, 1-8h
+→ `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing`
 
+### Full
+ANY: new project, major arch change, multi-phase, multi-subsystem, days of work, "full"/"complex"/"project"/"milestone"
 → `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing`
-→ Add `designing` if UI work involved
-→ Add `securing` if auth/data/API touched
+→ +`designing` if UI; +`securing` if auth/data/API
 
-### Direct Utility Skills
-User says "upgrade"/"update forge"/"sync forge" → route to `upgrading` (bypasses tier detection)
+### Direct Utility
+"upgrade"/"update forge"/"sync forge" → `upgrading` (bypasses tiers)
 
 ### User Override
-User says "Use Quick/Standard/Full tier" → honor it.
+"Use Quick/Standard/Full tier" → honor.
 
 ## Step 3: Route to Next Skill
 
-Based on tier and state, invoke the next skill via the `Skill` tool.
+Tier + state → invoke via `Skill` tool.
 
-**CRITICAL: NEVER use `EnterPlanMode` or native plan mode.** All Forge phases use Forge skills via `Skill` tool. "Planning" means `Skill(planning)` — not native plan mode. Native plan mode writes a different format and bypasses Forge's constitutional gates and state management.
+**CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
 ### Mandatory Auto-Routing on Resume
 
-**Never present menus or ask "What would you like to do?" on resume.** Routing is deterministic. Brief status, then route. Ask for choices only when `current.status == complete` or state is ambiguous/corrupted.
-
-Resume steps:
-1. Read `.forge/state/milestone-{id}.yml` for current position
-2. Check for status advancement (see below)
-3. Use `current.status` to determine next skill
-4. Brief the user, then route:
-
-*"Resuming Milestone {id}: {name}*
-*Workflow: {current.status} — next: {next skill}*
-*Phases: {compact list with Executed/Verified/Pending/In progress}*
-*Progress: {overall_percent}% of tasks executed*
-*Routing to {skill}..."*
-
-This is a **briefing, not a prompt** — the user can interrupt, but the default is forward motion.
-
-| `current.status` | Next Action (invoke via `Skill` tool) |
-|-------------------|-------------|
-| `not_started` | Detect tier, start workflow |
-| `researching` | `Skill(researching)` → `discussing` |
-| `discussing` | `Skill(discussing)` → `planning` (or `architecting` for Full) |
-| `planning` | `Skill(planning)` → `executing` |
-| `executing` | `Skill(executing)` → `verifying` |
-| `verifying` | `Skill(verifying)` → `reviewing` |
-| `reviewing` | `Skill(reviewing)` → `complete` |
-| `complete` | Done. Ask user what's next. |
-
-- **Never treat a milestone as complete at 100% `overall_percent`.** Task completion != workflow completion. 100% means execution is done — verification and reviewing still must run.
-- Skip completed phases (before `current.status`)
-- Resume from current phase
+**No menus.** Deterministic. Brief → route. Choices only at `complete` or corrupted.
 
-### Status Advancement Check
+1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
+
+*"Milestone {id}: {name} | {current.status} → {next} | {overall_percent}% | Routing..."*
+
+Briefing, not prompt -- default = forward.
+
+### Model Routing
+
+Read `models` from `project.yml`:
+1. `models.skills.{skill_name}` → use if set
+2. `models.default` → fallback
+3. Inherit parent session
+
+Subagents via `Task` → same precedence.
 
-Sessions can end before status advances. On resume, detect and fix:
+| Skill | Model | Why |
+|-------|-------|-----|
+| architecting | opus | Structural reasoning |
+| planning | opus | Task decomposition |
+| researching | sonnet | Analysis |
+| executing | sonnet | Code gen |
+| verifying | haiku | Mechanical checks |
+| reviewing | sonnet | Audit judgment |
+| quick-tasking | haiku | Speed |
+| discussing | sonnet | Conversation |
 
-- **`executing`**: All plans completed and committed? YES → advance to `verifying`, route there. NO → route to executing.
-- **`verifying`**: Verification report exists and passed? YES → advance to `reviewing`. NO → route to verifying.
-- **General**: If work for current status is done but status wasn't advanced (session ended mid-handoff), advance now and route forward.
+| `current.status` | Route To |
+|-------------------|----------|
+| `not_started` | Detect tier, start |
+| `researching` | `Skill(researching)` → discussing |
+| `discussing` | `Skill(discussing)` → planning (or architecting if Full) |
+| `architecting` | `Skill(architecting)` → planning |
+| `planning` | `Skill(planning)` → executing |
+| `executing` | `Skill(executing)` → verifying |
+| `verifying` | `Skill(verifying)` → reviewing |
+| `reviewing` | `Skill(reviewing)` → complete |
+| `complete` | Done. Ask what's next. |
+
+- 100% tasks != complete -- verification + reviewing must run.
+- Skip before `current.status`; resume current.
+
+### Status Advancement Check
+
+Sessions end before advancement. On resume detect + fix:
+- `executing`: all committed? → `verifying`. Else → executing.
+- `verifying`: report passed? → `reviewing`. Else → verifying.
+- General: work done, status stale → advance + route.
 
 ### Phase Status Wording
 
-| Phase State | Display As | Meaning |
-|------------|-----------|---------|
-| Tasks executed, commits made | **"Executed"** | Code written and committed, NOT verified |
-| Passed verifying skill | **"Verified"** | Passed goal-backward verification |
-| Not started | **"Pending"** | No work done |
-| Partially done | **"In progress"** | Partially executed |
+| State | Display | Meaning |
+|-------|---------|---------|
+| Committed, not verified | **"Executed"** | Code done, NOT verified |
+| Passed verifying | **"Verified"** | Goal-backward verified |
+| Not started | **"Pending"** | No work |
+| Partial | **"In progress"** | Partial execution |
 
-**Never say "Complete" unless a phase passed the full workflow** (executed + verified + reviewed).
+**Never "Complete" unless passed full workflow** (executed + verified + reviewed).
 
 ### On-Demand Discussion
 
-`discussing` can be invoked anytime. If the user says "discuss Phase 2", "let's talk through the plan", "I want to rethink this" — route to `discussing` immediately. After, return to the active skill or re-plan if direction changed.
+`discussing` anytime. "discuss Phase 2"/"talk through plan"/"rethink this" → route immediately. After, return or re-plan if direction changed.
 
 ## Deviation Rules (All Tiers)
 
 | Situation | Action | Rule |
 |-----------|--------|------|
-| Bug blocking current task | Auto-fix, document | Rule 1 |
-| Missing validation/error handling/null checks | Auto-add, document | Rule 2 |
-| Broken import/dep/config blocking progress | Auto-fix, document | Rule 3 |
-| Need new DB table, service layer, library swap | **STOP. Ask user.** | Rule 4 |
-| After verifying passes | Run health audit + refactoring review | `reviewing` |
+| Bug blocking task | Auto-fix, document | 1 |
+| Missing validation/error handling/null checks | Auto-add, document | 2 |
+| Broken import/dep/config | Auto-fix, document | 3 |
+| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
+| After verifying passes | Health + refactoring audit | `reviewing` |
+| Model routing mismatch | Flag expensive models for mechanical tasks | `reviewing` |
 
-Uncertain → Rule 4 (ask). Never silently make architectural decisions.
+Uncertain → 4. Never silently make arch decisions.
 
 ## Context Handoff Protocol
 
-Phase transitions are context-clearing boundaries. After each phase writes state to disk, **recommend clearing context** before the next phase. This prevents context rot in long sessions.
-
-Each phase produces persistent artifacts the next phase reads from disk. The next phase needs the artifacts, not the working memory. Stale context wastes tokens and degrades quality.
+Phase transitions = clear boundaries. **Recommend `/clear`** after writing state. Next phase reads disk artifacts, not working memory.
 
-Recommend at every Standard/Full phase boundary:
+Standard/Full:
 
 ```
 researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
 ```
 
-**Skip when:** Quick tier, phase was very short and context under 40%, or user opted out of clearing prompts.
+**Skip:** Quick, short phase + context <40%, user opted out.
 
 ### Handoff Pattern
 
-1. Confirm state is written to `.forge/`
-2. Summarize artifacts the next phase needs
-3. *"State written. `/clear` then `/forge` to continue with {next phase}."*
-4. User declines → proceed. Advisory, not blocking.
+1. Confirm state written
+2. List artifacts for next phase
+3. *"State written. `/clear` then `/forge` for {next phase}."*
+4. Decline → proceed. Advisory.
 
 ### Handoff Artifacts
 
-| Phase | Writes | Next Phase Reads |
-|-------|--------|------------------|
-| researching | Research summary | discussing reads findings |
-| discussing | Decision summary → context.md | planning reads context.md |
-| architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
-| planning | Plans in `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
-| executing | Committed code, execution summary, milestone state | verifying reads must_haves from plans |
-| verifying | Verification report, desire paths | reviewing reads project.yml + source + git diff |
+| Phase | Writes | Read By |
+|-------|--------|---------|
+| researching | Research summary | discussing |
+| discussing | Decisions → context.md | planning |
+| architecting | ADRs, data models, API contracts | planning |
+| planning | `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml | executing |
+| executing | Committed code, execution summary, state | verifying |
+| verifying | Verification report, desire paths | reviewing |
 
 ### Context Loading on Resume
 
-After a context clear, each skill loads required state from disk via its "Read Context" or "Pre-Execution Checklist" step. The `forge` orchestrator reads `milestone-{id}.yml` for routing; the target skill loads its own dependencies.
+After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist". Orchestrator reads `milestone-{id}.yml`; skills load own deps.
 
 ## State Transitions
 
@@ -202,4 +202,4 @@ not_started → [init if new] → researching → [clear] → discussing → [cl
                                                                                           ↗ securing (if auth/data)
 ```
 
-Update `.forge/state/milestone-{id}.yml` at each transition. Update `.forge/state/index.yml` milestone `last_updated` timestamp.
+Update `milestone-{id}.yml` + `index.yml` `last_updated` at each transition.