forge-orkes 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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`
@@ -42,22 +42,63 @@ After 3 auto-fix attempts on a single task → STOP fixing. Document remaining i
 ### Scope Boundary
 Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log to `.forge/deferred-issues.md`, don't fix.
 
+## Native Task Tracking (Hybrid Approach)
+
+Use Claude Code's native task tools (`TaskCreate`, `TaskUpdate`, `TaskList`) for **in-session visibility** during execution. The `.forge/state/milestone-{id}.yml` remains the **cross-session source of truth** — native tasks are a UI layer on top.
+
+### On Plan Start
+
+After loading the plan file, create native tasks from the XML task blocks:
+
+1. Parse all `<task>` XML blocks from the plan
+2. For each task, call `TaskCreate`:
+   - `subject`: The task's `<name>` value
+   - `description`: Combine `<action>`, `<verify>`, and `<done>` fields
+   - `activeForm`: Present-continuous form of the task name (e.g., "Implementing login form")
+3. If the plan has ordered tasks (task 2 depends on task 1), set dependencies via `TaskUpdate` with `addBlockedBy`
+4. Store the mapping: native task ID → plan task number (track mentally or in first task's metadata)
+
+### On Task Start
+
+Before implementing each task:
+1. Call `TaskUpdate` with `status: "in_progress"` on the current native task
+2. This gives the user a visible spinner with the `activeForm` text
+
+### On Task Complete
+
+After each task's commit:
+1. Call `TaskUpdate` with `status: "completed"` on the finished native task
+2. The next task automatically becomes unblocked (if dependencies were set)
+
+### On Plan Complete
+
+Native tasks are session-scoped — they disappear on `/clear` or session end. No cleanup needed. The authoritative state has already been written to `.forge/state/milestone-{id}.yml`.
+
+### When NOT to Create Native Tasks
+
+- **Spawned fresh agents**: Subagents don't share the parent's task list. The parent agent creates the native tasks; the subagent just does the work.
+- **Single-task plans**: If the plan has only 1 task, skip native task creation — the overhead isn't worth it.
+
+---
+
 ## Task Execution Flow
 
 For each task in the plan:
 
 1. **Read** the task XML (name, files, action, verify, done)
-2. **Check** context.md — does this task touch a locked decision? Honor it exactly.
-3. **Implement** following the action instructions
-4. **Verify** using the verify step (run tests, inspect output)
-5. **Confirm** done criteria are met
-6. **Commit** atomically
+2. **Mark in-progress** — `TaskUpdate` the native task to `in_progress`
+3. **Check** context.md — does this task touch a locked decision? Honor it exactly.
+4. **Implement** following the action instructions
+5. **Verify** using the verify step (run tests, inspect output)
+6. **Confirm** done criteria are met
+7. **Commit** atomically
+8. **Mark complete** — `TaskUpdate` the native task to `completed`
 
 ## TDD Flow (When task type="tdd")
 
 ### With Test Spec (from planning Step 7)
 When the task has a `<spec>` field, test specs already exist:
-1. **Copy spec to test location:** Move from `.forge/phases/` to the project's test directory
+1. **Copy spec to test location:** Move from `.forge/phases/m{M}-{N}-{name}/specs/` to the project's test directory
 2. **RED:** Remove `skip` markers from the first test. Confirm it fails. Commit: `test({scope}): activate spec tests for {feature}`
 3. **GREEN:** Write minimal code to make it pass. Repeat for each test in the spec.
 4. **REFACTOR:** Clean up. Commit: `feat({scope}): implement {feature}`
@@ -112,7 +153,7 @@ After each task, mentally assess context usage:
 After completing all tasks in a plan, create a summary:
 
 ```markdown
-# Execution Summary: Phase {N}, Plan {NN}
+# Execution Summary: m{M}-{N}-{name}, Plan {NN}
 
 ## Completed Tasks
 1. [Task name] — [one-line result]

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

@@ -498,22 +498,24 @@ If user explicitly says "Use Quick/Standard/Full tier" — honor it. No argument
 
 ## Step 3: Route to Next Skill
 
-Based on detected tier and current state, tell the user which skill comes next and invoke it.
+Based on detected tier and current state, tell the user which skill comes next and **invoke it using the `Skill` tool**.
+
+**CRITICAL: NEVER use `EnterPlanMode` or Claude Code's native plan mode.** All Forge phases are handled by Forge skills invoked via the `Skill` tool. When the workflow says "planning", that means invoke `Skill(planning)` — not enter native plan mode. Native plan mode writes to a different file format and bypasses Forge's constitutional gates, state management, and structured plan output.
 
 If resuming mid-workflow:
 - Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
 - **Use `current.status` to determine the next skill** — this is the authoritative workflow position:
 
-| `current.status` | Next Action |
+| `current.status` | Next Action (invoke via `Skill` tool) |
 |-------------------|-------------|
 | `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` |
+| `researching` | Invoke `Skill(researching)`, then → `discussing` |
+| `discussing` | Invoke `Skill(discussing)`, then → `planning` (or `architecting` for Full) |
+| `planning` | Invoke `Skill(planning)`, then → `executing` |
+| `executing` | Invoke `Skill(executing)`, then → `verifying` |
+| `verifying` | Invoke `Skill(verifying)`, then → `auditing` |
+| `auditing` | Invoke `Skill(auditing)`, then → `refactoring` |
+| `refactoring` | Invoke `Skill(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.
@@ -581,7 +583,7 @@ Each skill ends with a standard handoff message. The pattern is:
 | researching | Research summary (markdown in conversation or `.forge/` files) | discussing reads research findings |
 | discussing | Decision summary → carried into planning via context.md | planning reads context.md |
 | architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
-| planning | Plans in `.forge/phases/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
+| planning | Plans in `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml, context.md | executing reads plans |
 | executing | Committed code, execution summary, milestone state updated | verifying reads must_haves from plans |
 | verifying | Verification report, desire paths updated | auditing reads project.yml + source files |
 | auditing | Health report in `.forge/audits/` | refactoring reads health report + git diff |

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

@@ -7,6 +7,8 @@ description: "Use when you need to break work into executable tasks with verific
 
 Turn research and requirements into executable, verifiable plans.
 
+> **IMPORTANT:** This skill replaces Claude Code's native plan mode. Do NOT use `EnterPlanMode` — all planning output goes to `.forge/phases/` as structured plan files, not to the native plan file. Follow the steps below directly in the conversation.
+
 ## Step 1: Resolution Gate
 
 Read `.forge/context.md`. Check the **Needs Resolution** section.
@@ -77,7 +79,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 +149,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 +162,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 +190,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 +235,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/CLAUDE.md

@@ -2,10 +2,16 @@
 
 A lean meta-prompting framework for Claude Code. Synthesizes context engineering (GSD) and constitutional governance (Spec-Kit) on Claude Code's native primitives.
 
+## Critical: No Native Plan Mode
+
+**NEVER use the `EnterPlanMode` tool when the Forge framework is active** (i.e., when `.forge/` exists or a Forge skill is running). Forge has its own `planning` skill that writes structured plans to `.forge/phases/`. Claude Code's native plan mode writes to a separate plan file with a different format — this conflicts with Forge's workflow and state management.
+
+When the workflow reaches the planning phase, **invoke the `planning` skill using the `Skill` tool** — do not enter native plan mode. This applies to all tiers (Standard and Full). The same rule applies to all other Forge phases: always invoke the corresponding Forge skill, never substitute a native Claude Code behavior.
+
 ## Core Principles
 
 1. **Lean by default, powerful when needed.** Quick fixes skip ceremony. Complex features get full governance. The framework adapts — you don't.
-2. **Native-first.** Skills, agents, hooks, plugins — use Claude Code's built-in systems. No custom JavaScript, no reinvented orchestration.
+2. **Native-first.** Skills, agents, hooks, plugins — use Claude Code's built-in systems. No custom JavaScript, no reinvented orchestration. Periodically audit Forge features against Claude Code's current native capabilities — if a native tool now handles what a Forge feature does, deprecate the Forge version. Use native tools for session-scoped concerns (task UI, exploration) and Forge state for cross-session persistence. When in doubt, prefer native.
 3. **Context is sacred.** Every token earns its place. Size-gate all artifacts, lazy-load skills, spawn fresh agents for isolated work.
 4. **Decisions are contracts.** User decisions lock before building begins. Downstream agents honor contracts or flag violations — never silently override.
 5. **Verify against goals, not tasks.** "Does it work?" beats "Did we complete the checklist?" Goal-backward verification at every tier.