forge-orkes 0.12.1 → 0.13.0

package/package.json

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

@@ -0,0 +1,85 @@
+---
+name: deferred
+description: Read-only aggregator. Show all deferred work in this project grouped by surface (milestones, refactor backlog, phases/tasks inside active milestones). Trigger:`/forge deferred`, "show deferred", "deferred items", "what's deferred".
+model: haiku
+---
+
+# Deferred
+
+Read-only. Surface all deferred work across three storage surfaces so user need not remember where each kind lives. Never mutates state. No agents, no Skill invocations, no Write/Edit.
+
+Three surfaces:
+
+1. **Milestones** — `.forge/state/index.yml` entries with `status: deferred`. Strategic punts (whole milestone frozen).
+2. **Refactor backlog** — `.forge/refactor-backlog.yml` items with `status: deferred`. Code-quality punts.
+3. **Inside active milestones** — phase/task entries with `status: deferred` or `deferred: true` inside `.forge/state/milestone-*.yml`. Tactical punts within in-flight work.
+
+## Step 1: Read three surfaces
+
+**Surface 1 — Deferred milestones.** Read `.forge/state/index.yml`. Collect every entry under `milestones:` where `status: deferred`. Pull `id`, `name`, `lifecycle.deferred_at` (if present at top level fall back to `last_updated`), `lifecycle.deferred_reason` (may live in the milestone state file — read `.forge/state/milestone-{id}.yml → lifecycle.deferred_at / deferred_reason` for accuracy).
+
+**Surface 2 — Deferred refactor items.** Read `.forge/refactor-backlog.yml`. Collect every item with `status: deferred`. Pull `id` (e.g. R-007), `description` (first line, truncate ≤80 chars), `deferred_at`, `deferred_reason`.
+
+**Surface 3 — Deferred phases/tasks inside active milestones.** Glob `.forge/state/milestone-*.yml`. For each file:
+
+- Look up that milestone's status in `index.yml`.
+- **Only process if `status: active`.** Skip `complete` and `deferred` milestones.
+- *Why:* a deferred milestone's own `lifecycle.deferred_at` block is already counted by Surface 1. Including it here double-counts. Skipping `complete` avoids historical noise.
+- Within the file, find phase or task entries with `status: deferred` or `deferred: true`. Pull milestone id, phase/task name, `deferred_at`, `deferred_reason`.
+
+Missing source files → that section renders `(none)`. Never error.
+
+## Step 2: Normalize
+
+Each entry → tuple `{ surface, id, name, deferred_at, deferred_reason }`. Missing `deferred_at` → null. Missing `deferred_reason` → null.
+
+## Step 3: Sort
+
+Within each section, sort by `deferred_at` ascending (oldest first). Null dates sort last.
+
+## Step 4: Render
+
+Exact format:
+
+```
+Deferred work in this project:
+
+## Milestones ({count})
+- M{id} — {name} (deferred {deferred_at | "date unknown"})
+  Reason: {deferred_reason | "—"}
+
+## Refactor Backlog ({count})
+- {R-id} — {description} (deferred {deferred_at | "unknown"})
+  Reason: {deferred_reason | "—"}
+
+## Inside Active Milestones ({count})
+- M{milestone_id} → {phase or task name} (deferred {deferred_at | "unknown"})
+  Reason: {deferred_reason | "—"}
+```
+
+Section with count 0 → render header + `(none)` line beneath.
+
+## Empty state
+
+All three counts zero → print exactly:
+
+```
+No deferred work in this project.
+```
+
+Then exit.
+
+## Graceful degradation
+
+- Missing `.forge/state/index.yml` → cannot proceed. Print `No forge state found in this project.` exit.
+- Missing `.forge/refactor-backlog.yml` → Surface 2 renders `(none)`. Continue.
+- No `milestone-*.yml` matches → Surface 3 renders `(none)`. Continue.
+- Malformed YAML in any source → skip that source, render `(unreadable)` beneath header, continue others.
+
+## Boundaries
+
+- Read-only. No Write, no Edit, no Bash mutations.
+- No agent dispatch. Mechanical aggregation only.
+- No filter subcommands. Grouped-only view (locked decision).
+- No auto-close, no rot detection, no promotion. Deferred to v2.
+- Do not invoke other skills.

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

@@ -212,6 +212,8 @@ Do NOT list test failures here — pre-existing failures belong in deferred-issu
 3. Update `.forge/state/index.yml` — set `last_updated` timestamp
 4. All plans in phase complete → transition to `verifying`
 
+**When deferring an individual phase or task** (writing `status: deferred` or `deferred: true` to a phase/task entry inside the milestone state file — as opposed to milestone-wide defer which goes through the forge skill's lifecycle flow): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings. Old entries without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
+
 ## Desire Path Signals
 
 Log to `.forge/state/index.yml → desire_paths` (global, not per-milestone):

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

@@ -92,9 +92,15 @@ 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)
+- "deferred" / "show deferred" / "deferred items" / "what's deferred" / "deferred work" → **Show Deferred**
 
 No match → fall through to Step 2B (tier detection).
 
+### Show Deferred
+
+1. Invoke `Skill(deferred)` directly.
+2. Do not enter tier detection. Do not prompt for milestone. The deferred skill is read-only and self-contained.
+
 ### Defer Operation
 
 1. Validate: milestone in `index.yml`, status not `deferred`
@@ -218,6 +224,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | quick-tasking | haiku | Speed |
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing |
+| deferred | haiku | Read + format only |
 
 | `current.status` | Route To |
 |-------------------|----------|
@@ -232,6 +239,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | `complete` | Done. Ask what's next. |
 | `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* |
 | `quick-tasking` | `Skill(quick-tasking)` |
+| (keyword: `deferred` / "show deferred") | `Skill(deferred)` — read-only aggregator |
 
 ### Status Advancement Check
 

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

@@ -285,6 +285,8 @@ items:
 
 Missing? Create from `.forge/templates/refactor-backlog.yml`.
 
+**When deferring an individual refactor item** (status flipped to `deferred`, as opposed to milestone-wide defer which goes through the forge skill): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings to `status: deferred`. Pre-existing items without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
+
 ### Route
 
 **HEALTHY/WARNINGS (accepted):** `current.status: complete` in milestone + index. *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.

package/template/.forge/templates/refactor-backlog.yml

@@ -1,6 +1,12 @@
 # Forge Refactor Backlog
 # Auto-managed by the refactoring skill. Items added after milestone audits.
 # Work items via quick-tasking (effort: quick) or Standard tier (effort: standard).
+#
+# Status vocab: pending | in_progress | done | dismissed | deferred
+# Optional fields (lazy migration — only required on entries set to status: deferred going forward):
+#   deferred_at: ISO date when status flipped to deferred
+#   deferred_reason: one-line why; revisited when status changes
+# Pre-existing items without these fields parse fine.
 
 items:
   - id: R001                             # Sequential ID: R001, R002, ...
@@ -11,6 +17,21 @@ items:
     description: "Brief description of the refactoring opportunity"
     effort: quick                        # quick (< 30 min, < 50 lines) | standard (needs planning)
     suggested_approach: "Concrete suggestion for how to address it"
-    status: pending                      # pending | in_progress | done | dismissed
+    status: pending                      # pending | in_progress | done | dismissed | deferred
     added: "2026-01-01"                  # ISO 8601 date when added
     completed: null                      # ISO 8601 date when done, null otherwise
+
+  # Example of a deferred item — note the two optional sibling fields:
+  - id: R002
+    milestone: 1
+    category: abstraction
+    file: "src/legacy.ts"
+    lines: "1-200"
+    description: "Extract module — blocked on upstream API change"
+    effort: standard
+    suggested_approach: "Wait for v2 API, then extract"
+    status: deferred
+    deferred_at: "2026-05-29"            # ISO date when status flipped to deferred
+    deferred_reason: "Blocked on upstream v2 API; revisit Q3"
+    added: "2026-01-15"
+    completed: null

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

@@ -50,8 +50,23 @@ deviations:                            # Tracked deviations during execution
 
 # Lifecycle — events separate from workflow position (current:).
 # current.status stays frozen when deferred — it IS the resume point.
+# This block handles MILESTONE-LEVEL deferral (whole milestone frozen).
 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
+
+# Phase/task-level deferral (separate scope from milestone-level lifecycle above):
+# When marking an individual phase or task deferred INSIDE an active milestone,
+# add deferred_at + deferred_reason adjacent to that entry's status field.
+# Fields are OPTIONAL (lazy migration — old entries lacking them parse fine).
+# These feed the `deferred` aggregator skill.
+#
+# Example (this template doesn't model concrete phases, but when a skill
+# writes such an entry, follow this shape):
+#   phases:
+#     - id: 3
+#       status: deferred
+#       deferred_at: "2026-05-29"
+#       deferred_reason: "Blocked on upstream API; revisit when X ships"