forge-orkes 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/agents/executor.md

@@ -22,7 +22,7 @@ Execute plan tasks precisely. You have full development tool access but operate
 
 ## Upstream Input
 
-- Plan from Planner agent: `.forge/phases/{N}-{name}/plan.md`
+- Plan from Planner agent: `.forge/phases/m{M}-{N}-{name}/plan.md`
 - Context: `.forge/context.md` (locked decisions, deferred ideas)
 - State: `.forge/state/milestone-{id}.yml` (current position for active milestone)
 
@@ -74,7 +74,7 @@ Need to deviate from plan?
 
 ### 1. Read the Plan
 ```
-Read: .forge/phases/{N}-{name}/plan.md
+Read: .forge/phases/m{M}-{N}-{name}/plan.md
 Read: .forge/context.md
 Read: .forge/state/milestone-{id}.yml
 ```

package/template/.claude/agents/planner.md

@@ -28,9 +28,9 @@ Transform research findings into actionable, verified plans. Ensure every plan p
 ## Downstream Output
 
 Files created/updated in `.forge/`:
-- `phases/{N}-{name}/plan.md` — Task plan with XML tasks
-- `phases/{N}-{name}/specs/` — Test spec files (when Step 7 is invoked)
-- `phases/{N}-{name}/requirements.yml` — Structured requirements
+- `phases/m{M}-{N}-{name}/plan.md` — Task plan with XML tasks
+- `phases/m{M}-{N}-{name}/specs/` — Test spec files (when Step 7 is invoked)
+- `phases/m{M}-{N}-{name}/requirements.yml` — Structured requirements
 - `context.md` — Locked decisions and deferred ideas
 - `state/milestone-{id}.yml` — Updated with current phase/plan
 

package/template/.claude/agents/verifier.md

@@ -20,7 +20,7 @@ Perform goal-backward verification: start from what was promised (must_haves), w
 
 ## Upstream Input
 
-- Plan with must_haves: `.forge/phases/{N}-{name}/plan.md`
+- Plan with must_haves: `.forge/phases/m{M}-{N}-{name}/plan.md`
 - Execution summary from Executor
 - Source code (read-only inspection)
 - Milestone state file (what was completed, any deviations)
@@ -78,7 +78,7 @@ Verification report:
 
 ### 1. Load Verification Criteria
 ```
-Read: .forge/phases/{N}-{name}/plan.md → extract must_haves
+Read: .forge/phases/m{M}-{N}-{name}/plan.md → extract must_haves
 Read: .forge/state/milestone-{id}.yml → check reported progress
 Read: .forge/context.md → know locked decisions
 ```
@@ -161,7 +161,7 @@ Check for common issues the Executor might have left:
 
 ### 7. Requirements Coverage
 
-Cross-reference requirements from `.forge/phases/{N}-{name}/requirements.yml`:
+Cross-reference requirements from `.forge/phases/m{M}-{N}-{name}/requirements.yml`:
 - Every `must-have` requirement should have corresponding implemented code
 - Every acceptance criterion should be testable
 - Flag any requirements with no corresponding implementation

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

@@ -97,7 +97,7 @@ When designing data models:
 4. Consider indexing needs (what will be queried frequently?)
 5. Plan for evolution (what might change? Use nullable fields over rigid schemas)
 
-Document in `.forge/phases/{N}-{name}/data-model.md`.
+Document in `.forge/phases/m{M}-{N}-{name}/data-model.md`.
 
 ## API Contract Design
 
@@ -109,7 +109,7 @@ When designing APIs:
 4. Consider pagination for list endpoints
 5. Plan authentication requirements per endpoint
 
-Document in `.forge/phases/{N}-{name}/contracts/`.
+Document in `.forge/phases/m{M}-{N}-{name}/contracts/`.
 
 ## Output
 
@@ -124,7 +124,7 @@ After completing architectural work:
 
 After architectural decisions are documented:
 
-1. **Verify persistence** — Confirm ADRs are written to `.forge/decisions/`, data models and API contracts to `.forge/phases/{N}-{name}/`
+1. **Verify persistence** — Confirm ADRs are written to `.forge/decisions/`, data models and API contracts to `.forge/phases/m{M}-{N}-{name}/`
 2. **Update state** — Set `current.status` to `planning` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 

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

@@ -224,7 +224,7 @@ When invoked on an existing phase or plan:
 ### Step 1: Load Context
 
 Read the relevant files:
-- The plan being discussed (`.forge/phases/{N}-{name}/plan-{NN}.md`)
+- The plan being discussed (`.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`)
 - Requirements it's based on (`.forge/requirements.yml`)
 - Locked decisions (`.forge/context.md`)
 - Constitution (`.forge/constitution.md`)

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

@@ -10,7 +10,7 @@ Build to plan with atomic commits, smart deviation handling, and context enginee
 ## Pre-Execution Checklist
 
 Before writing any code:
-- [ ] Plan exists (`.forge/phases/{N}-{name}/plan-{NN}.md`)
+- [ ] Plan exists (`.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`)
 - [ ] Context.md reviewed (locked decisions noted)
 - [ ] Constitution.md gates satisfied (from planning phase)
 - [ ] Current milestone state (`.forge/state/milestone-{id}.yml`) updated to `status: executing`

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

@@ -18,16 +18,22 @@ Check for state files in this order:
 
 **When milestone-aware state exists (`state/index.yml`):**
 1. Read `.forge/state/index.yml` to get the list of active milestones
-2. **If multiple active milestones:**
-   - Present all milestones with their progress and `last_updated` timestamp
+2. **Check for milestone argument first.** If the user invoked `/forge` with an argument (e.g., `/forge 2`, `/forge "Auth system"`):
+   - Match the argument against milestone IDs (exact number match) or milestone names (case-insensitive substring match)
+   - If a match is found → auto-select it immediately, skip the confirmation prompt: *"Resuming milestone {id}: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
+   - If no match → warn and fall through to the interactive prompt: *"No milestone matching '{arg}' found. Here are your active milestones:"*
+3. **If multiple active milestones (and no argument provided):**
+   - Present all milestones with their status and `last_updated` timestamp
    - Default to the most recently updated milestone
-   - Ask user to confirm or switch: *"You have {N} active milestones. Most recent: [{name}] ({progress}%, last touched {date}). Work on this one, or switch?"*
-3. **If one milestone:** Auto-select it. Inform user: *"Resuming milestone: [{name}] ({progress}%)"*
-4. **If no active milestones:** Proceed to init or ask user to create one.
-5. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
-6. Report position from the milestone-specific state:
+   - Ask user to confirm or switch: *"You have {N} active milestones. Most recent: [{name}] (status: {current.status}, last touched {date}). Work on this one, or switch?"*
+4. **If one milestone:** Auto-select it. Inform user: *"Resuming milestone: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
+5. **If no active milestones:** Proceed to init or ask user to create one.
+6. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
+7. **Route based on `current.status`, NOT on `overall_percent`.** The `current.status` field is the authoritative workflow position. A milestone is only complete when `current.status` equals `complete`. Even if `overall_percent` is 100%, the milestone still needs to go through any remaining workflow steps (verifying, auditing, refactoring) before it is truly done.
+8. Report position from the milestone-specific state:
+   - **Workflow status** (`current.status`) — this is the primary indicator of where you are
    - Current phase, plan, task
-   - Progress percentage
+   - Task progress percentage (`overall_percent`) — this measures task completion, not workflow completion
    - Active blockers
    - Recent decisions
 
@@ -496,7 +502,22 @@ Based on detected tier and current state, tell the user which skill comes next a
 
 If resuming mid-workflow:
 - Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
-- Skip completed phases
+- **Use `current.status` to determine the next skill** — this is the authoritative workflow position:
+
+| `current.status` | Next Action |
+|-------------------|-------------|
+| `not_started` | Detect tier, start workflow |
+| `researching` | Resume or complete `researching`, then → `discussing` |
+| `discussing` | Resume or complete `discussing`, then → `planning` (or `architecting` for Full) |
+| `planning` | Resume or complete `planning`, then → `executing` |
+| `executing` | Resume or complete `executing`, then → `verifying` |
+| `verifying` | Resume or complete `verifying`, then → `auditing` |
+| `auditing` | Resume or complete `auditing`, then → `refactoring` |
+| `refactoring` | Resume or complete `refactoring`, then → `complete` |
+| `complete` | Milestone is done. Ask user what's next. |
+
+- **Never treat a milestone as complete just because `overall_percent` is 100%.** Task completion and workflow completion are different. All planned tasks being done (100%) means execution is finished — verification, auditing, and refactoring still need to run.
+- Skip completed phases (phases before `current.status`)
 - Resume from current phase
 
 ### On-Demand Discussion

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

@@ -77,7 +77,12 @@ If `.forge/roadmap.yml` doesn't exist (Full tier only):
 
 For each phase (or the single feature in Standard tier):
 
-1. Copy `.forge/templates/plan.md` → `.forge/phases/{N}-{name}/plan-{NN}.md`
+1. Copy `.forge/templates/plan.md` → `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
+   - **`{M}`** = milestone ID from `roadmap.yml` (e.g., `1`, `2`, `24`)
+   - **`{N}`** = phase number within the milestone (sequential: `1`, `2`, `3`...)
+   - **`{name}`** = phase `name` from `roadmap.yml` in kebab-case
+   - **`{NN}`** = plan sequence within the phase (`01`, `02`, etc.)
+   - Example: `.forge/phases/m3-2-providers/plan-01.md` = milestone 3, phase 2, plan 01
 2. Fill in frontmatter (phase, plan number, wave, dependencies)
 3. Create goal-backward must_haves:
    - **Truths:** Observable from user perspective when done (3-7)
@@ -142,7 +147,7 @@ If no testable contracts are found, skip to Step 8.
 
 For each testable contract, create a test spec file alongside the plan:
 
-**Location:** `.forge/phases/{N}-{name}/specs/`
+**Location:** `.forge/phases/m{M}-{N}-{name}/specs/`
 
 **Format:** Language-appropriate test files (e.g., `.test.ts`, `_test.go`, `test_*.py`) that:
 
@@ -155,7 +160,7 @@ For each testable contract, create a test spec file alongside the plan:
 4. **Mark as pending/skipped** — tests should be valid syntax but marked to skip (e.g., `it.skip()`, `@pytest.mark.skip`, `t.Skip()`) so they don't break CI before implementation
 
 ```typescript
-// Example: .forge/phases/1-auth/specs/login-endpoint.test.ts
+// Example: .forge/phases/m1-1-auth/specs/login-endpoint.test.ts
 describe('POST /api/auth/login', () => {
   it.skip('returns 200 with valid token for correct credentials', () => {
     // From FR-001: "User can log in with email and password"
@@ -183,7 +188,7 @@ For tasks with generated test specs, update the task XML to reference the spec:
 <task type="tdd">
   <name>Implement login endpoint</name>
   <files>src/api/auth/login.ts</files>
-  <spec>.forge/phases/1-auth/specs/login-endpoint.test.ts</spec>
+  <spec>.forge/phases/m1-1-auth/specs/login-endpoint.test.ts</spec>
   <action>Make all tests in the spec file pass. Remove skip markers as you implement.</action>
   <verify>All spec tests pass: npm test -- login-endpoint</verify>
   <done>All skip markers removed, all tests green</done>
@@ -228,7 +233,7 @@ Planning is complete when user approves.
 
 After the user approves the plan:
 
-1. **Verify persistence** — Confirm all plans are written to `.forge/phases/{N}-{name}/plan-{NN}.md`, requirements to `.forge/requirements.yml`, roadmap to `.forge/roadmap.yml`, and context to `.forge/context.md`
+1. **Verify persistence** — Confirm all plans are written to `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`, requirements to `.forge/requirements.yml`, roadmap to `.forge/roadmap.yml`, and context to `.forge/context.md`
 2. **Update state** — Set `current.status` to `executing` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 

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

@@ -19,7 +19,7 @@ When entering with a fresh context (after `/clear`):
 ```
 Read: .forge/state/milestone-{id}.yml → current phase, plans completed
 Read: .forge/project.yml → tech stack (for running tests)
-Read: .forge/phases/{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
+Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
 Read: .forge/context.md → locked decisions (to understand intent)
 Read: .forge/requirements.yml → requirement IDs for coverage check
 ```

package/template/.forge/templates/plan.md

@@ -1,6 +1,6 @@
 # Phase Plan Template
 
-Copy to `.forge/phases/{N}-{name}/plan-{NN}.md` for each plan in a phase.
+Copy to `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md` for each plan in a phase.
 
 ---
 

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

@@ -16,11 +16,16 @@ current:
   status: not_started                  # not_started | researching | discussing | planning | executing | verifying | auditing | refactoring | complete
 
 progress:
-  phases_complete: 0
-  phases_total: 0
-  current_phase_percent: 0
-  overall_percent: 0
+  phases_complete: 0                   # Number of roadmap phases with all tasks done
+  phases_total: 0                      # Total roadmap phases in this milestone
+  current_phase_percent: 0             # Task completion % within the current phase (0-100)
+  overall_percent: 0                   # Task completion % across all phases (0-100)
   last_update: null                    # ISO 8601 timestamp
+  # NOTE: overall_percent measures TASK completion, not WORKFLOW completion.
+  # A milestone with 100% tasks done still needs verifying, auditing, and refactoring.
+  # The authoritative workflow position is current.status — not this percentage.
+  # Agents: do NOT set overall_percent above 100 or use it to determine if a milestone is "done".
+  # A milestone is only done when current.status == "complete".
 
 decisions:                             # Locked decisions (synced from context.md)
   - decision: ""

package/template/CLAUDE.md

@@ -124,6 +124,9 @@ Milestones group phases into concurrent work streams. Each milestone has its own
 ### Machine-Readable State
 YAML for anything agents parse programmatically (project, requirements, roadmap, state). Markdown for human-facing content (constitution, context, verification reports). Never free-form prose for machine state.
 
+### Milestone Completion: Status vs. Percentage
+**`current.status` is the authoritative workflow position.** A milestone is only complete when `current.status == complete`. The `progress.overall_percent` field measures task completion — not workflow completion. A milestone at 100% task completion still needs verifying, auditing, and refactoring before it is done. On resume, always check and display `current.status` to determine next steps.
+
 ## Deviation Rules (Executor Decision Tree)
 
 When the executor encounters issues during building: