forge-orkes 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.6.1",
+  "version": "0.8.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,6 +125,12 @@ 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.
 
@@ -132,6 +192,7 @@ 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. | — |
+| `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()`.**
@@ -266,8 +327,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/.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 |
@@ -130,8 +134,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.