forge-orkes 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.5.0",
+  "version": "0.6.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,55 @@ 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.
+
+## Functionality Distillation
+
+Per feature, force behavioral clarity. Surface assumptions + edge cases.
+
+**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
+**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
+**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
+**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
+**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
+
+**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
+
+Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
+
+Example -- L3:
+```
+question: "When the enrichment API is down, what should the system do?"
+header: "Failure mode"
+options:
+  - label: "Retry with backoff (Recommended)"
+    description: "Queue retries at 1m/5m/30m. Adds complexity but self-heals."
+  - label: "Fail and alert"
+    description: "Mark failed, send alert. Simple but requires manual re-trigger."
+  - label: "Skip and continue"
+    description: "Process remaining items, revisit failures in next sweep."
+```
+
 ## Pre-Planning Discussion
 
 ### Step 0: Load Context
@@ -60,6 +106,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,32 +137,13 @@ AskUserQuestion:
 
 Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a time.
 
-### Step 4: Functionality Distillation
-
-Per feature, force behavioral clarity. Surface assumptions + edge cases.
+**After each user response:** write confirmed decisions/constraints to `context.md` immediately.
 
-**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
-**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
-**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
-**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
-**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
-
-**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
+### Step 4: Functionality Distillation
 
-Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
+Apply Functionality Distillation (above), grounded in research findings.
 
-Example -- L3:
-```
-question: "When the enrichment API is down, what should the system do?"
-header: "Failure mode"
-options:
-  - label: "Retry with backoff (Recommended)"
-    description: "Queue retries at 1m/5m/30m. Adds complexity but self-heals."
-  - label: "Fail and alert"
-    description: "Mark failed, send alert. Simple but requires manual re-trigger."
-  - label: "Skip and continue"
-    description: "Process remaining items, revisit failures in next sweep."
-```
+**After each user response:** write confirmed behavioral decisions to `context.md` immediately.
 
 ### Step 5: Converge
 
@@ -132,8 +161,6 @@ options:
     description: "Topics we haven't covered yet."
 ```
 
-Decisions written to `.forge/context.md` at Phase Handoff (below).
-
 ## Post-Planning Discussion
 
 ### Step 1: Load Context
@@ -159,7 +186,7 @@ Translate into meaning, don't recite. Example: *"Phase 2: 3 plans, 8 tasks. Plan
 
 ### Step 4: Drill Functionality
 
-Apply **Functionality Distillation** (Step 4 above), grounded in tasks:
+Apply Functionality Distillation (above), grounded in plan tasks:
 
 - *"Notification service send failure -- retry or log?"*
 - *"Dashboard-to-API -- poll or push?"*
@@ -223,13 +250,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:**
-
-*"Decisions written to `.forge/context.md`. State updated. `/clear` then `/forge` to continue with {planning/architecting}."*
+3. **Recommend clear:** *"State written. `/clear` then `/forge` for {planning/architecting}."*

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

@@ -119,6 +119,8 @@ 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 | — |
@@ -130,51 +132,82 @@ Subagents via `Agent` tool → same precedence, enforced via `model` param.
 | `verifying` | Agent-dispatched → reviewing | **Agent** |
 | `reviewing` | `Skill(reviewing)` → complete | Skill |
 | `complete` | Done. Ask what's next. | — |
+| `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
 
-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.
+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
 
-#### Verifying (Agent-Dispatched)
+**Agent prompt requirements:** `touch .forge/.active-skill` (pre-commit guard) + "Report resolved model in summary."
 
-When `current.status == verifying`, do NOT call `Skill(verifying)`. Instead:
+#### Verifying
 
-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:
+When `current.status == verifying`:
+
+1. Read milestone state → identify plan path
+2. Spawn:
 
 ```
 Agent(
-  model: "{resolved_model}",
+  model: "{model}",
   description: "Verify milestone {id}: {name}",
-  prompt: "You are a verifier agent. Your job: prove completed work delivers what was promised.
+  prompt: "You are a verifier agent. 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.
+FIRST: Run `touch .forge/.active-skill`
 
-Read these files for context:
-- .claude/skills/verifying/SKILL.md — your full process instructions
-- .claude/agents/verifier.md — your role, tools, output format
+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 to verify
-- .forge/project.yml — tech stack, verification commands
+- .forge/phases/{phase_path}/plan-{NN}.md — must_haves
+- .forge/project.yml — stack, verification commands
 - .forge/context.md — locked decisions
-- .forge/requirements.yml — requirement IDs for coverage
+- .forge/requirements.yml — requirement 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."
+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."
 )
 ```
 
-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)
+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."
+)
+```
 
-- Skip before `current.status`; resume current.
+On return: display result + model. With milestone → read updated state.
 
 ### Status Advancement Check
 

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

@@ -3,6 +3,8 @@ 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.
@@ -60,6 +62,27 @@ Example: `fix(docs): correct typo in API reference`
 ### 6. Done
 No verification ceremony. Move on.
 
+## Milestone Context
+
+Quick-tasking handles two contexts. Existing workflow steps (Identify → Validate → Execute → Test → Commit → Done) apply in both — this section adds state management around them.
+
+### With Milestone
+
+Invoked via forge routing (mid-workflow or refactor-backlog item with milestone context):
+
+1. Read `.forge/state/milestone-{id}.yml` for current position
+2. Follow standard workflow (above)
+3. After commit: update milestone state — increment `progress.overall_percent`, log deviations if any Rule 1-3 applied
+4. Report: fix description, files changed, milestone progress update
+
+### Without Milestone
+
+Standalone quick fix (no forge state exists or no milestone context provided):
+
+1. Follow standard workflow (above)
+2. No state reads or writes
+3. Report: fix description, files changed
+
 ## Scope Creep Detection
 
 During execution, if you discover:

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

@@ -3,6 +3,8 @@ 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.
@@ -194,8 +196,6 @@ After PASSED verdict:
 
 1. **Persist** — Confirm verification results documented, desire paths logged to `.forge/state/index.yml`
 2. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
-
-*"Verification passed. State written. `/clear` then `/forge` to continue with reviewing."*
+3. **Recommend clear:** *"State written. `/clear` then `/forge` for reviewing."*
 
 If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.