forge-orkes 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.8.0",
+  "version": "0.9.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

@@ -23,16 +23,33 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 
 ## 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.
+**Decisions persist immediately. This is a hard gate — not a guideline.**
 
-### Rules
+After each user response that confirms a decision:
 
-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
+1. **STOP** — do not continue the discussion
+2. **Write to disk** — append to `.forge/context.md` (create from template if missing)
+3. **THEN** continue to the next question
+
+Never accumulate decisions in working memory. Never batch writes to convergence.
+
+### Write Protocol
+
+**On first decision of the session:**
+- Check if `.forge/context.md` exists. If not → create it from `.forge/templates/context.md`
+- Add a milestone heading inside `## Locked Decisions`: `### M{id} — {name} (drafting)` (use "M?" if no milestone yet)
+
+**On each confirmed decision:**
+- Append under the milestone heading: `- **[Topic]**: [Decision]. Reason: [Why]`
+
+**On deferred ideas** (user says "not now" / "later" / "skip"):
+- Append to `## Deferred Ideas` immediately: `- [Idea] — Deferred because: [reason]`
+
+**On discretion areas** (left to agent judgment):
+- Append to `## Discretion Areas` immediately
+
+**At Phase Handoff:**
+- Rename `(drafting)` → `(locked {date})` — decisions are already written, just finalize the heading
 
 ### Why
 
@@ -145,7 +162,13 @@ Apply Functionality Distillation (above), grounded in research findings.
 
 **After each user response:** write confirmed behavioral decisions to `context.md` immediately.
 
-### Step 5: Converge
+### Step 5: Pre-Convergence Audit
+
+**Before summarizing, read `.forge/context.md` and verify all confirmed decisions are present.**
+
+If any decision from the conversation is missing from the file → write it now. Do not proceed to the summary until the file matches the conversation. This is a hard gate.
+
+### Step 6: Converge
 
 Summarize decided items, then confirm:
 

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

@@ -136,7 +136,7 @@ Can't know upfront if "review X" → "it's fine" or "restructure 6 files." Discu
 
 ## Step 3: Route to Next Skill
 
-Tier + state → invoke via `Skill` tool or `Agent` tool (agent-dispatched phases).
+Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
@@ -163,9 +163,7 @@ Resolve `{model}` for `{next}` skill using precedence above. **Always display**
 
 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.
+**Model routing is advisory.** All phases use `Skill()`. Display expected model at each transition. Mismatch → suggest `/model {expected}`. Review gate logs model used.
 
 | Skill | Model | Why |
 |-------|-------|-----|
@@ -179,96 +177,19 @@ Subagents via `Agent` tool → same precedence, enforced via `model` param.
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing |
 
-*Model enforced only for Agent-dispatched skills (verifying, quick-tasking). Skill-routed phases are advisory — use `/model` to switch.*
-
-| `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. | — |
-| `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* | — |
-| `quick-tasking` | Agent-dispatched (Quick tier / refactor-backlog) | **Agent** |
-
-**Phases marked Agent MUST use `Agent()` with `model` param. Never `Skill()` — model enforcement only works through `Agent()`.**
-
-### Agent-Dispatched Phases
-
-Phases marked **Agent** run as spawned agents to enforce model routing. `Agent` tool's `model` param = only enforcement point.
-
-**Skill contract:** Each dispatched skill carries a guard header — if parent loads via Skill(), guard says STOP.
-
-**Parent protocol:**
-1. Resolve model: `models.skills.{skill}` → `models.default` → parent
-2. On return: read updated state, display *"Result: {outcome}. Model: {model} (enforced)."*, route next
-
-**Agent prompt requirements:** `touch .forge/.active-skill` (pre-commit guard) + "Report resolved model in summary."
-
-#### Verifying
-
-When `current.status == verifying`:
-
-1. Read milestone state → identify plan path
-2. Spawn:
-
-```
-Agent(
-  model: "{model}",
-  description: "Verify milestone {id}: {name}",
-  prompt: "You are a verifier agent. Prove completed work delivers what was promised.
-
-FIRST: Run `touch .forge/.active-skill`
-
-Read:
-- .claude/skills/verifying/SKILL.md — process instructions
-- .claude/agents/verifier.md — role, tools, output format
-- .forge/state/milestone-{id}.yml — current state
-- .forge/phases/{phase_path}/plan-{NN}.md — must_haves
-- .forge/project.yml — stack, verification commands
-- .forge/context.md — locked decisions
-- .forge/requirements.yml — requirement coverage
-
-Follow verifying/SKILL.md 3-level process exactly.
-Write results to plan directory.
-Update state: 'reviewing' if PASSED, keep 'verifying' if GAPS.
-Report resolved model in summary."
-)
-```
-
-3. On return: PASSED → reviewing. GAPS → planning (gap-closure).
-
-#### Quick-Tasking
-
-Quick-tasking runs as Agent from Quick tier or refactor-backlog. Parent constructs prompt based on milestone context:
-
-```
-Agent(
-  model: "{model}",
-  description: "Quick fix: {description}",
-  prompt: "You are a quick-tasking agent. Small, scoped fix.
-
-FIRST: Run `touch .forge/.active-skill`
-
-Read:
-- .claude/skills/quick-tasking/SKILL.md — workflow
-- .forge/project.yml — stack, verification commands
-[with milestone: + .forge/state/milestone-{id}.yml, .forge/context.md]
-
-Task: {description}
-
-Follow quick-tasking/SKILL.md workflow.
-[with milestone: After commit, update milestone-{id}.yml (increment progress, log deviations).]
-[without milestone: No state management.]
-Report resolved model in summary."
-)
-```
-
-On return: display result + model. With milestone → read updated state.
+| `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. |
+| `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* |
+| `quick-tasking` | `Skill(quick-tasking)` |
 
 ### Status Advancement Check
 

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -3,8 +3,6 @@ name: quick-tasking
 description: "Small, scoped changes: typo fixes, config updates, minor bugs, dependency bumps, doc tweaks. Under 50 lines, 1-2 files, no architectural decisions. Quick tier — skip ceremony."
 ---
 
-> **AGENT-DISPATCHED:** If reading in parent session, STOP — use Agent() via forge/SKILL.md § Agent-Dispatched Phases.
-
 # Quick-Tasking
 
 Small change? Skip ceremony. Do it right, do it fast.

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

@@ -3,8 +3,6 @@ name: verifying
 description: "Prove completed work delivers what was promised. Goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links. Task completion ≠ goal achievement."
 ---
 
-> **AGENT-DISPATCHED:** If reading in parent session, STOP — use Agent() via forge/SKILL.md § Agent-Dispatched Phases.
-
 # Verifying
 
 Prove completed work delivers what was promised. Task completion ≠ goal achievement.

package/template/CLAUDE.md

@@ -96,8 +96,7 @@ models:
 ```
 
 **Precedence:** `skills.X` → `default` → parent model.
-**Parent session advisory** — warns if mismatch, cannot auto-switch. Enforced at review gate.
-**Agents model-agnostic** — skills set model at spawn. One routing table.
+**All advisory** — forge displays expected model at each transition, suggests `/model` on mismatch. Review gate logs model used. Cannot auto-switch.
 
 ## Agents