forge-orkes 0.3.4 → 0.3.5

package/package.json

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

@@ -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.

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.