forge-orkes 0.6.1 → 0.9.0

package/package.json

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

@@ -250,6 +250,34 @@ Re-plan? Route to `planning` with summary.
 
 After convergence:
 
+### Step A: Milestone Gate (Advisory → Tier Escalation)
+
+If no milestone exists (advisory discussion — forge routed here without tier/milestone):
+
+1. **Assess decisions.** Do locked decisions require code changes?
+   - Schema changes, field renames, new files, API changes, multi-file edits, refactoring → **yes, changes needed**
+   - Documentation only, config tweaks, "no changes needed" → **no** → end. *"No code changes needed. Discussion complete."*
+2. **Detect tier from decisions scope.**
+   - Single file, <50 lines, trivial → **Quick**
+   - Multi-file, refactor, feature, service changes → **Standard**
+   - Major architectural, multi-subsystem, multi-phase → **Full**
+3. **Create milestone.**
+   - Read `.forge/state/index.yml` (create from `.forge/templates/state/index.yml` if missing)
+   - Next ID = max existing ID + 1 (or 1 if none)
+   - Create `milestone-{id}.yml` from `.forge/templates/state/milestone.yml`:
+     - `milestone.id` = {id}, `milestone.name` = brief summary of discussion topic
+     - `current.tier` = detected tier
+     - `current.status` = `planning` (Standard) / `architecting` (Full) / `not_started` (Quick)
+     - `decisions[]` = locked decisions from `context.md`
+   - Add entry to `index.yml`: `id`, `name`, `status: active`, `last_updated: now`
+4. **Update `context.md`** — scope decisions under `### M{id} — {name} (locked {date})`
+5. **Quick tier?** → *"Scope is Quick. `/clear` then `/forge {id}` for quick-tasking."* End.
+6. Proceed to Step B with new milestone.
+
+If milestone exists → skip to Step B.
+
+### Step B: Standard Handoff
+
 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`

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

@@ -22,9 +22,9 @@ Check state files:
    - 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?"*
+3. **Multiple (no arg):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{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.
+5. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → 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.
@@ -43,6 +43,60 @@ Check `desire_paths` 3+ occurrences:
 
 No `project.yml` + Standard/Full → **Step 2A**. State exists → **Step 2B**.
 
+## Step 1.5: Lifecycle Operations
+
+Before tier detection, check if user request matches lifecycle patterns:
+- "defer milestone {id}" / "defer {id}" / "pause milestone {id}" → **Defer**
+- "resume milestone {id}" / "undefer {id}" / "reactivate milestone {id}" → **Resume**
+- "delete milestone {id}" / "archive milestone {id}" / "remove milestone {id}" → **Delete** (see below)
+
+No match → fall through to Step 2B (tier detection).
+
+### Defer Operation
+
+1. Validate: milestone in `index.yml`, status not `deferred`
+2. Extract reason (text after "—"/"-" or second sentence). None → ask: *"Reason for deferring?"*
+3. Update `index.yml`: `status: deferred`, `last_updated`
+4. Update `milestone-{id}.yml`:
+   - `lifecycle.deferred_at` = ISO 8601 now
+   - `lifecycle.deferred_reason` = reason
+   - `lifecycle.status_before_defer` = copy of `current.status`
+5. Update `roadmap.yml`: all phases belonging to this milestone → `status: deferred`
+6. Confirm: *"Deferred milestone {id}: {name}. Was {status}, frozen at {current.status}. Reason: {reason}."*
+
+### Resume Operation
+
+1. Validate: milestone in `index.yml`, status is `deferred`
+2. Update `index.yml`: `status: active`, `last_updated`
+3. Update `milestone-{id}.yml`: `lifecycle.resumed_at` = ISO 8601 now
+4. Confirm + route: *"Resumed milestone {id}: {name}. Picking up at {current.status}."*
+5. Fall through to normal routing (Step 3) — `current.status` already frozen at correct position
+
+### Delete (Archive) Operation
+
+1. Validate: milestone in `index.yml` (any status — active, deferred, complete, not_started)
+2. Build manifest — scan for associated files:
+   - `.forge/state/milestone-{id}.yml`
+   - `.forge/phases/m{id}-*/` (glob all phase dirs)
+   - `.forge/research/milestone-{id}.md` (if exists)
+   - `.forge/audits/milestone-{id}-*` (if exists)
+   - Note: `.forge/context.md` is shared — do NOT archive or modify. M{id} decisions stay as history.
+3. Show manifest + confirm:
+   *"Archiving milestone {id}: {name}\n  - {list files}\n  → .forge/archive/milestone-{id}/\n\nProceed?"*
+4. On confirm:
+   a. Create `.forge/archive/milestone-{id}/`
+   b. Copy `milestone-{id}.yml` → archive as `state.yml`
+   c. Copy phase dirs → archive `phases/`
+   d. Copy research file → archive `research.md` (if exists)
+   e. Copy audit files → archive `audits/` (if exists)
+   f. Remove originals after successful copy
+   g. Remove milestone entry from `index.yml`
+   h. Remove milestone + its phases from `roadmap.yml`
+   i. Update `index.yml` `last_updated`
+5. Confirm: *"Archived milestone {id}: {name} → .forge/archive/milestone-{id}/. Removed from active state."*
+
+**Safety:** Copy-then-delete, not move. If copy fails, originals intact.
+
 ### Parent Session Model Advisory
 
 Check `models.parent_session` from `project.yml`. **Always display:** *"Session model: {current}. Project recommends: {parent_session}."*
@@ -71,12 +125,18 @@ ANY: new project, major arch change, multi-phase, multi-subsystem, days of work,
 ### Direct Utility
 "upgrade"/"update forge"/"sync forge" → `upgrading` (bypasses tiers)
 
+### Advisory (Tier Deferred)
+ANY: "review"/"advise"/"assess"/"evaluate" + specific system/component/feature, scope unclear, "what do you think about"
+→ No `project.yml` → init first. Then `discussing` (no milestone — tier detected post-discussion).
+
+Can't know upfront if "review X" → "it's fine" or "restructure 6 files." Discussion determines scope. Discussing skill detects tier at convergence, creates milestone if code changes needed.
+
 ### User Override
 "Use Quick/Standard/Full tier" → honor.
 
 ## 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.
 
@@ -103,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 |
 |-------|-------|-----|
@@ -119,95 +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. | — |
-| `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
 
@@ -266,8 +248,9 @@ After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist".
 ## State Transitions
 
 ```
-Standard: not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
-Full:     not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+Standard:  not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
+Full:      not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+Advisory:  [init?] → discussing → [tier gate] → planning → executing → verifying → reviewing → complete
 
 Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing (auth/data/API) · testing (e2e/integration/flake)
 Phase boundaries: `[clear]` recommended between phases to reset context.

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

@@ -312,7 +312,7 @@ User selects per stack.
      milestones:
        - id: 1
          name: "{project name}"
-         status: active
+         status: active                # not_started | active | deferred | complete
          last_updated: "{date}"
      ```
    - `.forge/state/milestone-1.yml`:

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/.forge/templates/roadmap.yml

@@ -4,13 +4,16 @@
 
 roadmap:
   # Milestones group phases into concurrent work streams.
-  # Phases keep global IDs. Milestones reference them.
+  # Each milestone contains its own phases numbered sequentially (1, 2, 3...).
   # Different milestones can be worked on in parallel across sessions.
   milestones:
     - id: 1
       name: ""                         # e.g., "MVP", "Admin Dashboard"
-      phases: []                       # List of phase IDs belonging to this milestone
+      phases: []                       # List of phase numbers belonging to this milestone
 
+  # Phases are scoped within milestones. Each phase has a local number (1, 2, 3...)
+  # within its milestone. Directory naming: .forge/phases/m{milestone_id}-{phase_num}-{name}/
+  # Example: m1-1-foundation/, m1-2-auth/, m2-1-dashboard/
   phases:
     - id: 1
       name: ""                       # e.g., "Foundation & Architecture"
@@ -21,7 +24,7 @@ roadmap:
         - ""                         # e.g., "User can see the landing page"
         - ""                         # e.g., "API returns valid JSON for /users"
       estimated_hours: null
-      status: pending                # pending | researching | planning | executing | verifying | complete
+      status: pending                # pending | researching | planning | executing | verifying | deferred | complete
 
     - id: 2
       name: ""

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

@@ -5,7 +5,7 @@
 milestones:                            # Active milestones and their high-level status
   - id: 1
     name: ""                           # Human-readable milestone name from roadmap
-    status: not_started                # not_started | active | complete
+    status: not_started                # not_started | active | deferred | complete
     last_updated: null                 # ISO 8601 timestamp — used for resume default selection
 
 metrics:

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

@@ -46,3 +46,11 @@ deviations:                            # Tracked deviations during execution
     plan: null
     task: null
     resolution: ""
+
+# Lifecycle — events separate from workflow position (current:).
+# current.status stays frozen when deferred — it IS the resume point.
+lifecycle:
+  deferred_at: null                    # ISO 8601 — when milestone was deferred
+  deferred_reason: ""                  # User-provided reason for deferring
+  status_before_defer: null            # Workflow status when deferred (mirrors frozen current.status)
+  resumed_at: null                     # ISO 8601 — when milestone was resumed

package/template/CLAUDE.md

@@ -36,6 +36,10 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 **Flow:** `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing` → done
 **Optional:** `designing` (UI), `securing` (auth/data/API), `debugging` (stuck), `testing` (e2e/integration/flake)
 
+### Advisory (tier deferred)
+**Triggers:** "review"/"advise"/"assess"/"evaluate" + specific system/component, scope unclear upfront
+**Flow:** `discussing` → [tier gate detects scope] → `planning` → `executing` → `verifying` → `reviewing` → done
+
 ## Skill Routing
 
 | Need to... | Skill | Tier |
@@ -92,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
 
@@ -130,8 +133,10 @@ State lives in `.forge/`:
 - `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
 - `phases/m{M}-{N}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter
 - `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
+- `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
-**Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions.
+**Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
+`index.yml status` gates routing: `not_started | active | deferred | complete`.
 **Format**: YAML for machine state, Markdown for human content.
 **`current.status` is authoritative.** Complete only at `current.status == complete`. 100% tasks ≠ done — still needs verifying + reviewing.