forge-orkes 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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/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/.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: