forge-orkes 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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/discussing/SKILL.md

@@ -18,9 +18,28 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 ## Boundaries
 
 - No plans or code
-- Writes only `context.md` (at convergence, before handoff)
+- Writes `context.md` progressively (after each confirmed decision, not just at handoff)
 - No phase/plan required
 
+## Progressive Persistence
+
+**Decisions persist immediately.** After each user response that confirms a decision, write it to `.forge/context.md` right away. Don't accumulate in working memory.
+
+### Rules
+
+1. **Create `context.md` on first decision** if it doesn't exist (from template `.forge/templates/context.md`)
+2. **Scope by milestone.** Add decisions under `### M{id} — {name} (drafting)` inside `## Locked Decisions`
+3. **Append, don't rewrite.** Each confirmed decision → append one `- **[Topic]**: [Decision]. Reason: [Why]` line
+4. **Deferred ideas too.** User says "not now" / "later" / "skip" → append to `## Deferred Ideas` immediately
+5. **Discretion areas too.** Left to agent judgment → append to `## Discretion Areas` immediately
+6. **Phase Handoff promotes.** Rename `(drafting)` → `(locked {date})` at convergence. No content change needed — decisions are already written
+
+### Why
+
+Sessions `/clear` or die mid-discussion. Previous behavior: decisions lived only in conversation memory until Step 5 convergence. If session ended before convergence, all Q&A answers vanished. Planning would start from scratch.
+
+Now: any `/clear` preserves everything decided so far. Worst case on interruption = last answer lost, not all answers.
+
 ## Pre-Planning Discussion
 
 ### Step 0: Load Context
@@ -60,6 +79,8 @@ Brief context paragraph from research.
 
 Surface 3-5 decisions that matter.
 
+**After each user response:** write confirmed decisions to `context.md` immediately (see Progressive Persistence).
+
 ### Step 2: Facilitate, Don't Dictate
 
 Help user think deeper, don't push preference. `AskUserQuestion` for decisions; prose for open-ended.
@@ -89,6 +110,8 @@ AskUserQuestion:
 
 Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a time.
 
+**After each user response:** write confirmed decisions/constraints to `context.md` immediately.
+
 ### Step 4: Functionality Distillation
 
 Per feature, force behavioral clarity. Surface assumptions + edge cases.
@@ -103,6 +126,8 @@ Per feature, force behavioral clarity. Surface assumptions + edge cases.
 
 Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
 
+**After each user response:** write confirmed behavioral decisions to `context.md` immediately.
+
 Example -- L3:
 ```
 question: "When the enrichment API is down, what should the system do?"
@@ -223,11 +248,11 @@ Re-plan? Route to `planning` with summary.
 
 After convergence:
 
-1. **Write `context.md`** -- Create/update `.forge/context.md` from template (`.forge/templates/context.md`). Populate:
-   - **Locked Decisions**: all confirmed decisions from Steps 1-5
-   - **Deferred Ideas**: anything explicitly deferred
-   - **Discretion Areas**: topics left to agent judgment
-   - **Needs Resolution**: unresolved items (if any)
+1. **Promote decisions in `context.md`** -- Rename milestone heading from `(drafting)` → `(locked {date})`. Decisions already written progressively — just finalize:
+   - Verify all confirmed decisions present under `## Locked Decisions`
+   - Verify deferred items under `## Deferred Ideas`
+   - Verify discretion areas under `## Discretion Areas`
+   - Add any unresolved items to `## Needs Resolution`
    - If `context.md` already exists (post-planning discussion), update relevant sections + log amendments
 2. **Update state** -- `current.status` = `planning` (`architecting` for Full) in milestone yml
 3. **Recommend clear:**

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