forge-orkes 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

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

@@ -168,7 +168,7 @@ Run all non-advisory verification commands once after commit. 1 retry max.
 | Context under 40% | Continue normally |
 | Switching unrelated subsystems | Spawn fresh agent |
 
-**Spawn via Task tool** with: relevant plan details, specific files, locked decisions from context.md, clear success criteria.
+**Spawn via Agent tool** with: relevant plan details, specific files, locked decisions from context.md, clear success criteria. **Pass `model` param** from `project.yml` model routing (`models.skills.executing` → `models.default` → parent). Display: *"Spawning executor with model: {model} (from {source})"*
 
 ## Execution Summary
 

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

@@ -45,7 +45,8 @@ No `project.yml` + Standard/Full → **Step 2A**. State exists → **Step 2B**.
 
 ### Parent Session Model Advisory
 
-Check `models.parent_session` from `project.yml`. Mismatch → *"Recommends {parent_session}, running {current}. `/model` to switch."*
+Check `models.parent_session` from `project.yml`. **Always display:** *"Session model: {current}. Project recommends: {parent_session}."*
+Mismatch → append: *"Use `/model` to switch."*
 - Advisory only -- no block. Reviewer enforces at review gate.
 
 ## Step 2A: Project Init
@@ -75,7 +76,7 @@ ANY: new project, major arch change, multi-phase, multi-subsystem, days of work,
 
 ## Step 3: Route to Next Skill
 
-Tier + state → invoke via `Skill` tool.
+Tier + state → invoke via `Skill` tool or `Agent` tool (agent-dispatched phases).
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
@@ -85,7 +86,7 @@ Tier + state → invoke via `Skill` tool.
 
 1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
 
-*"Milestone {id}: {name} | {current.status} → {next} | {overall_percent}% | Routing..."*
+*"Milestone {id}: {name} | {current.status} → {next} ({model}) | {overall_percent}% | Routing..."*
 
 Briefing, not prompt -- default = forward.
 
@@ -96,7 +97,15 @@ Read `models` from `project.yml`:
 2. `models.default` → fallback
 3. Inherit parent session
 
-Subagents via `Task` → same precedence.
+Resolve `{model}` for `{next}` skill using precedence above. **Always display** the resolved model in the routing briefing and its source:
+
+*"Skill {next} expects {model} (from {source}). Running {current_model}."*
+
+Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Show on every transition, not just mismatch. If mismatch, append: *"Use `/model` to switch."*
+
+**Agent spawns MUST include `model` param.** Resolve model for the skill context, pass to `Agent(model: "{model}")`. This is the only enforcement point — `Skill` tool has no model param.
+
+Subagents via `Agent` tool → same precedence, enforced via `model` param.
 
 | Skill | Model | Why |
 |-------|-------|-----|
@@ -110,17 +119,60 @@ Subagents via `Task` → same precedence.
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing |
 
-| `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. |
+| `current.status` | Route To | Method |
+|-------------------|----------|--------|
+| `not_started` | Detect tier, start | — |
+| `researching` | `Skill(researching)` → discussing | Skill |
+| `discussing` | `Skill(discussing)` → planning (or architecting if Full) | Skill |
+| `architecting` | `Skill(architecting)` → planning | Skill |
+| `planning` | `Skill(planning)` → executing | Skill |
+| `executing` | `Skill(executing)` → verifying | Skill |
+| `verifying` | Agent-dispatched → reviewing | **Agent** |
+| `reviewing` | `Skill(reviewing)` → complete | Skill |
+| `complete` | Done. Ask what's next. | — |
+
+### Agent-Dispatched Phases
+
+Some phases run as spawned agents instead of in-session skills. This **enforces model routing** — the `Agent` tool's `model` param guarantees the correct model runs.
+
+#### Verifying (Agent-Dispatched)
+
+When `current.status == verifying`, do NOT call `Skill(verifying)`. Instead:
+
+1. Read milestone state: `.forge/state/milestone-{id}.yml`
+2. Identify the plan path from state: `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
+3. Resolve model: `models.skills.verifying` → `models.default` → parent
+4. Spawn agent:
+
+```
+Agent(
+  model: "{resolved_model}",
+  description: "Verify milestone {id}: {name}",
+  prompt: "You are a verifier agent. Your job: prove completed work delivers what was promised.
+
+FIRST: Run `touch .forge/.active-skill` to satisfy the pre-commit hook guard. Without this, all Write/Edit operations will be blocked.
+
+Read these files for context:
+- .claude/skills/verifying/SKILL.md — your full process instructions
+- .claude/agents/verifier.md — your role, tools, output format
+- .forge/state/milestone-{id}.yml — current state
+- .forge/phases/{phase_path}/plan-{NN}.md — must_haves to verify
+- .forge/project.yml — tech stack, verification commands
+- .forge/context.md — locked decisions
+- .forge/requirements.yml — requirement IDs for coverage
+
+Follow the 3-level verification process in verifying/SKILL.md exactly.
+Write verification results to the plan directory.
+Update milestone state: set current.status to 'reviewing' if PASSED, keep 'verifying' if GAPS FOUND.
+End with a verification summary for the parent session."
+)
+```
+
+5. On agent return:
+   - Read updated `milestone-{id}.yml`
+   - Display result: *"Verification {PASSED|GAPS FOUND}. Model: {model} (enforced)."*
+   - PASSED → route to reviewing
+   - GAPS FOUND → route back to planning (gap-closure mode)
 
 - Skip before `current.status`; resume current.
 

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

@@ -54,7 +54,7 @@ File lists per subagent (paths, not globs).
 
 ## Step 3: Parallel Scans
 
-Fresh-context subagents with file list + tech stack.
+Fresh-context subagents with file list + tech stack. **Pass `model` param** from `project.yml` model routing (`models.skills.reviewing` → `models.default` → parent). Display: *"Spawning reviewers with model: {model} (from {source})"*
 
 ### Part 1: Security Audit
 
@@ -315,5 +315,5 @@ pending → dismissed (during triage or later)
 ## Phase Handoff
 
 1. Confirm report + backlog
-2. Set `current.status: complete`
+2. Set `current.status: complete` and `current.completed_at: "<ISO 8601 timestamp>"`
 3. *"Milestone [{name}] complete. Report: `.forge/audits/milestone-{id}-health-report.md`. {N} backlog items. `/forge` or backlog."*

package/template/.forge/templates/state/milestone.yml

@@ -13,7 +13,8 @@ current:
   phase_name: ""                       # Human-readable phase name
   plan: null                           # Current plan number within phase
   task: null                           # Current task number within plan
-  status: not_started                  # not_started | researching | discussing | planning | executing | verifying | auditing | refactoring | complete
+  status: not_started                  # not_started | researching | discussing | planning | executing | verifying | reviewing | complete
+  completed_at: null                    # ISO 8601 timestamp — set when status transitions to complete
 
 progress:
   phases_complete: 0                   # Number of roadmap phases with all tasks done