forge-orkes 0.3.9 → 0.3.11

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

@@ -5,178 +5,148 @@ description: "START HERE for any task. Forge orchestrates Quick fixes, Standard
 
 # Forging: Workflow Orchestration
 
-You are the entry point. Detect the right tier, route to the right skills, manage state transitions. For new projects, run the interactive init before any work begins.
+Entry point. Detect tier, route to skills, manage state transitions. For new projects, run init before work begins.
 
 ## Step 1: Read State
 
 ### Milestone Selection
 
-Check for state files in this order:
-1. If `.forge/state/index.yml` exists → **new milestone-aware format**
-2. If `.forge/state.yml` exists (legacy) → suggest migration: *"I found a legacy state.yml. Would you like me to migrate it to the new milestone-aware format?"* If yes, create `.forge/state/` directory, split into `index.yml` + `milestone-1.yml`, delete old file.
-3. If neither exists → no state yet, proceed to init or tier detection.
+Check state files in order:
+1. `.forge/state/index.yml` exists → milestone-aware format
+2. `.forge/state.yml` exists (legacy) → suggest migration: *"I found a legacy state.yml. Migrate to milestone-aware format?"* If yes, create `.forge/state/`, split into `index.yml` + `milestone-1.yml`, delete old file.
+3. Neither exists → no state yet, proceed to init or tier detection.
 
 **When milestone-aware state exists (`state/index.yml`):**
-1. Read `.forge/state/index.yml` to get the list of active milestones
+1. Read `.forge/state/index.yml` for active milestones
 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}] (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 remaining workflow steps (verifying, reviewing) before it is truly done.
-8. Report position briefly, then **immediately route to the next skill** (see Step 3: Mandatory Auto-Routing):
-   - **Workflow status** (`current.status`) — this is the primary indicator of where you are
-   - Phase progress using precise terminology: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for a phase that hasn't been verified**
-   - Task progress percentage (`overall_percent`) — this measures task completion, not workflow completion
-   - **Do NOT present a menu of options.** State the position, state the next action, invoke the skill.
-
-If Beads is installed and enabled (`settings.json → forge.beads_integration: true`), also run `bd prime` for cross-session context. See `beads-integration` skill for details. This is optional — Forge works fully without it.
-
-Also read `.forge/context.md` if it exists. If the **Needs Resolution** section has unchecked items:
-- **Warn the user immediately**: *"There are {N} unresolved discrepancies from project init that need your input before planning can proceed: [list items briefly]."*
-- Quick tier tasks can proceed despite unresolved items (they don't go through planning)
-- Standard/Full tier tasks will be blocked at the planning gate until resolved
-
-Check `.forge/refactor-backlog.yml` for pending items. If found:
-- Count pending items by effort level
-- **Surface them early**: *"You have {N} pending refactoring items ({Q} quick, {S} standard). Want to tackle any before starting new work?"*
-- If the user picks one → route to `quick-tasking` (for quick items) or Standard tier (for standard items). Update the item's `status` to `in_progress`.
-- If the user says not now → proceed with normal workflow.
-
-Check `.forge/state/index.yml → desire_paths` for any patterns with 3+ occurrences that haven't been acted on:
-- **Surface them early**: *"I've noticed a recurring pattern: [{description}] ({N} times). Before we start, would you like to address this by [suggested framework change]?"*
-- If the user agrees → apply the change (update skill, constitution, or template), reset the counter
-- If the user says not now → note it and move on. Don't nag every session.
-
-If no `.forge/project.yml` exists AND the task is Standard or Full tier → go to **Step 2A: Project Init** before anything else.
-
-If state exists → go to **Step 2B: Detect Tier**.
+   - Match against milestone IDs (exact number) or names (case-insensitive substring)
+   - Match found → auto-select, skip prompt: *"Resuming milestone {id}: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
+   - No match → warn and show interactive prompt: *"No milestone matching '{arg}'. Active milestones:"*
+3. **Multiple active milestones (no argument):** Present all with status and `last_updated`. Default to most recent. *"You have {N} active milestones. Most recent: [{name}] (status: {current.status}, last touched {date}). Work on this one, or switch?"*
+4. **One milestone:** Auto-select. *"Resuming milestone: [{name}] — status: {current.status}, tasks: {overall_percent}%"*
+5. **No active milestones:** Proceed to init or ask user to create one.
+6. Load `.forge/state/milestone-{id}.yml`
+7. **Route on `current.status`, NOT `overall_percent`.** Status is the authoritative workflow position. A milestone is complete only when `current.status == complete`. Even at 100% `overall_percent`, remaining workflow steps (verifying, reviewing) must run.
+8. Report position, then **immediately route** (see Step 3):
+   - Workflow status (`current.status`) — primary position indicator
+   - Phase progress: "Executed" (code done, not verified), "Verified", "Pending", "In progress" — **never say "Complete" for unverified phases**
+   - Task progress (`overall_percent`) — measures task completion, not workflow completion
+   - **No menus.** State position, state next action, invoke skill.
+
+If Beads is installed and enabled (`settings.json → forge.beads_integration: true`), run `bd prime` for cross-session context. See `beads-integration` skill. Optional — Forge works without it.
+
+Read `.forge/context.md` if it exists. If **Needs Resolution** has unchecked items:
+- Warn immediately: *"There are {N} unresolved discrepancies from init: [list items]."*
+- Quick tier proceeds despite unresolved items
+- Standard/Full blocked at planning gate until resolved
+
+Check `.forge/refactor-backlog.yml` for pending items:
+- Count by effort level
+- *"You have {N} pending refactoring items ({Q} quick, {S} standard). Tackle any before new work?"*
+- User picks one → route to `quick-tasking` (quick) or Standard tier (standard). Set `status: in_progress`.
+- User declines → proceed normally.
+
+Check `.forge/state/index.yml → desire_paths` for patterns with 3+ occurrences not yet acted on:
+- *"Recurring pattern: [{description}] ({N} times). Address this by [suggested change]?"*
+- User agrees → apply change, reset counter
+- User declines → note it, move on. Don't nag every session.
+
+No `.forge/project.yml` AND Standard/Full tier → **Step 2A: Project Init**.
+State exists → **Step 2B: Detect Tier**.
 
 ## Step 2A: Project Init
 
-If no `.forge/project.yml` exists, invoke the `initializing` skill via `Skill(initializing)`. It handles brownfield/greenfield detection, framework absorption, tech stack scanning, design system setup, and constitutional configuration. After init completes, return here for tier detection.
+No `.forge/project.yml` → invoke `Skill(initializing)`. It handles brownfield/greenfield detection, framework absorption, tech stack scanning, design system setup, and constitution config. After init, return here for tier detection.
 
 ## Step 2B: Detect Tier
 
-Analyze the user's request against these patterns:
-
 ### Quick Tier
-Match ANY:
-- Single file change
-- Typo, grammar, formatting fix
-- Config/environment update
-- Dependency version bump
-- Under 50 lines of changes estimated
-- User says "quick", "small", "minor", "just"
+Match ANY: single file change, typo/grammar/formatting fix, config/env update, dependency bump, <50 lines estimated, user says "quick"/"small"/"minor"
 
-→ Route to `quick-tasking` skill
+→ Route to `quick-tasking`
 
 ### Standard Tier
-Match ANY:
-- New feature or component
-- Bug fix requiring investigation
-- Refactor touching multiple files
-- Integration with external service
-- Estimated 1-8 hours of work
+Match ANY: new feature/component, bug fix requiring investigation, multi-file refactor, external service integration, 1-8 hours estimated
 
-→ Route through: `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing`
+→ `researching` → `discussing` → `planning` → `executing` → `verifying` → `reviewing`
 
 ### Full Tier
-Match ANY:
-- New project from scratch
-- Major architectural change
-- Multi-phase milestone
-- Complex system with multiple subsystems
-- Estimated days of work
-- User says "full", "complex", "project", "milestone"
-
-→ Route through: `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing`
+Match ANY: new project, major architectural change, multi-phase milestone, complex multi-subsystem work, days of work estimated, user says "full"/"complex"/"project"/"milestone"
+
+→ `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `reviewing`
 → Add `designing` if UI work involved
 → Add `securing` if auth/data/API touched
 
 ### Direct Utility Skills
-Match ANY:
-- User says "upgrade", "update forge", "sync forge"
-
-→ Route to `upgrading` skill (bypasses tier detection)
+User says "upgrade"/"update forge"/"sync forge" → route to `upgrading` (bypasses tier detection)
 
 ### User Override
-If user explicitly says "Use Quick/Standard/Full tier" — honor it. No arguments.
+User says "Use Quick/Standard/Full tier" → honor it.
 
 ## Step 3: Route to Next Skill
 
-Based on detected tier and current state, tell the user which skill comes next and **invoke it using the `Skill` tool**.
+Based on tier and state, invoke the next skill via 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.
+**CRITICAL: NEVER use `EnterPlanMode` or native plan mode.** All Forge phases use Forge skills via `Skill` tool. "Planning" means `Skill(planning)` — not native plan mode. Native plan mode writes a different format and bypasses Forge's constitutional gates and state management.
 
 ### Mandatory Auto-Routing on Resume
 
-**When resuming mid-workflow, DO NOT present a menu of options or ask "What would you like to do?".** Routing is deterministic. Give a brief status briefing, then route automatically. The only time to ask the user for a choice is when `current.status == complete` (milestone done) or when state is ambiguous/corrupted.
+**Never present menus or ask "What would you like to do?" on resume.** Routing is deterministic. Brief status, then route. Ask for choices only when `current.status == complete` or state is ambiguous/corrupted.
 
 Resume steps:
-1. Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
-2. **Check for status advancement** (see below)
-3. **Use `current.status` to determine the next skill** — this is the authoritative workflow position
-4. **Brief the user, then route.** Show a compact status summary so the user can orient, then immediately invoke the next skill. Format:
+1. Read `.forge/state/milestone-{id}.yml` for current position
+2. Check for status advancement (see below)
+3. Use `current.status` to determine next skill
+4. Brief the user, then route:
 
 *"Resuming Milestone {id}: {name}*
-*Workflow: {current.status} — next step: {next skill name}*
-*Phases: {compact phase list with statuses using correct wording — Executed/Verified/Pending/In progress}*
+*Workflow: {current.status} — next: {next skill}*
+*Phases: {compact list with Executed/Verified/Pending/In progress}*
 *Progress: {overall_percent}% of tasks executed*
 *Routing to {skill}..."*
 
-This is a **briefing, not a prompt** — the user sees where they are and what's happening next. They can interrupt if they want to do something different, but the default is forward motion.
+This is a **briefing, not a prompt** — the user can interrupt, but the default is forward motion.
 
 | `current.status` | Next Action (invoke via `Skill` tool) |
 |-------------------|-------------|
 | `not_started` | Detect tier, start workflow |
-| `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 → `reviewing` |
-| `reviewing` | Invoke `Skill(reviewing)`, 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 and reviewing still need to run.
-- Skip completed phases (phases before `current.status`)
+| `researching` | `Skill(researching)` → `discussing` |
+| `discussing` | `Skill(discussing)` → `planning` (or `architecting` for Full) |
+| `planning` | `Skill(planning)` → `executing` |
+| `executing` | `Skill(executing)` → `verifying` |
+| `verifying` | `Skill(verifying)` → `reviewing` |
+| `reviewing` | `Skill(reviewing)` → `complete` |
+| `complete` | Done. Ask user what's next. |
+
+- **Never treat a milestone as complete at 100% `overall_percent`.** Task completion != workflow completion. 100% means execution is done — verification and reviewing still must run.
+- Skip completed phases (before `current.status`)
 - Resume from current phase
 
 ### Status Advancement Check
 
-Sometimes a session ends before the executing skill advances `current.status`. On resume, detect and fix this:
+Sessions can end before status advances. On resume, detect and fix:
 
-- **If `current.status == executing`**: Check if all phases in the roadmap have been executed (all plans completed, commits made). If YES → advance `current.status` to `verifying` in the state file, then route to verifying. If NO → route to executing for the next unexecuted phase.
-- **If `current.status == verifying`**: Check if verification report exists. If YES and it passed → advance to `reviewing`. If NO → route to verifying.
-- **General rule**: If the work for the current status is done but the status wasn't advanced (session ended mid-handoff), advance it now and route to the next skill.
+- **`executing`**: All plans completed and committed? YES → advance to `verifying`, route there. NO → route to executing.
+- **`verifying`**: Verification report exists and passed? YES → advance to `reviewing`. NO → route to verifying.
+- **General**: If work for current status is done but status wasn't advanced (session ended mid-handoff), advance now and route forward.
 
 ### Phase Status Wording
 
-When reporting phase progress on resume, use precise terminology to avoid confusion:
-
 | Phase State | Display As | Meaning |
 |------------|-----------|---------|
-| All tasks executed, commits made | **"Executed"** | Code is written and committed, but NOT yet verified |
-| Verified by verifying skill | **"Verified"** | Passed goal-backward verification |
-| Not yet started | **"Pending"** | No work done yet |
-| Currently in progress | **"In progress"** | Partially executed |
+| Tasks executed, commits made | **"Executed"** | Code written and committed, NOT verified |
+| Passed verifying skill | **"Verified"** | Passed goal-backward verification |
+| Not started | **"Pending"** | No work done |
+| Partially done | **"In progress"** | Partially executed |
 
-**Never say a phase is "Complete" unless it has passed through the full workflow** (executed + verified + reviewed). Use "Executed" for phases where code is done but verification hasn't run. This prevents users from thinking a phase is fully done when it still needs verification.
+**Never say "Complete" unless a phase passed the full workflow** (executed + verified + reviewed).
 
 ### On-Demand Discussion
 
-The `discussing` skill can be invoked at any time, regardless of current workflow position. If the user says "discuss Phase 2", "let's talk through the plan", "I want to rethink this", or similar — route to `discussing` immediately. After the discussion concludes, return to whatever skill was active (or re-plan if the discussion changed direction).
+`discussing` can be invoked anytime. If the user says "discuss Phase 2", "let's talk through the plan", "I want to rethink this" — route to `discussing` immediately. After, return to the active skill or re-plan if direction changed.
 
 ## Deviation Rules (All Tiers)
 
-While working at any tier, if you encounter:
-
 | Situation | Action | Rule |
 |-----------|--------|------|
 | Bug blocking current task | Auto-fix, document | Rule 1 |
@@ -185,57 +155,43 @@ While working at any tier, if you encounter:
 | Need new DB table, service layer, library swap | **STOP. Ask user.** | Rule 4 |
 | After verifying passes | Run health audit + refactoring review | `reviewing` |
 
-When uncertain → Rule 4 (ask). Never silently make architectural decisions.
+Uncertain → Rule 4 (ask). Never silently make architectural decisions.
 
 ## Context Handoff Protocol
 
-Phase transitions are natural context-clearing boundaries. After each phase completes and writes its state to disk, **recommend the user clear context** before the next phase begins. This prevents context rot — the #1 cause of quality degradation in long sessions.
-
-### Why Clear Between Phases
+Phase transitions are context-clearing boundaries. After each phase writes state to disk, **recommend clearing context** before the next phase. This prevents context rot in long sessions.
 
-Each phase produces persistent artifacts (state files, plans, reports, backlogs) that the next phase reads from disk. The next phase does NOT need the previous phase's working memory — it needs the artifacts. Carrying forward stale context wastes tokens and degrades output quality.
+Each phase produces persistent artifacts the next phase reads from disk. The next phase needs the artifacts, not the working memory. Stale context wastes tokens and degrades quality.
 
-### When to Recommend
-
-Recommend clearing context at every phase boundary in Standard and Full tiers:
+Recommend at every Standard/Full phase boundary:
 
 ```
 researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
 ```
 
-**Skip the recommendation when:**
-- Quick tier (single phase, no boundary to clear)
-- The phase was very short (under 5 minutes of work) and context is well under 40%
-- The user has explicitly said they don't want context-clearing prompts
-
-### The Handoff Prompt
-
-Each skill ends with a standard handoff message. The pattern is:
-
-1. **Confirm state is written** — skill verifies its outputs are persisted to `.forge/`
-2. **Summarize what was produced** — brief list of artifacts the next phase will need
-3. **Recommend clearing context** — present the prompt to the user:
-
-*"Phase complete. All state has been written to disk. I recommend clearing context (`/clear`) before starting {next phase} — this gives the next phase a fresh context window to work with. The {next phase} skill will load everything it needs from `.forge/` state files.*
+**Skip when:** Quick tier, phase was very short and context under 40%, or user opted out of clearing prompts.
 
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+### Handoff Pattern
 
-4. **If user declines** — proceed normally. The recommendation is advisory, not blocking.
+1. Confirm state is written to `.forge/`
+2. Summarize artifacts the next phase needs
+3. *"State written. `/clear` then `/forge` to continue with {next phase}."*
+4. User declines → proceed. Advisory, not blocking.
 
-### What Each Phase Writes (Handoff Artifacts)
+### Handoff Artifacts
 
-| Phase | Writes to Disk | Next Phase Reads |
-|-------|---------------|------------------|
-| 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 |
+| Phase | Writes | Next Phase Reads |
+|-------|--------|------------------|
+| researching | Research summary | discussing reads findings |
+| discussing | Decision summary → context.md | planning reads context.md |
 | architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
 | 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 | reviewing reads project.yml + source files + git diff |
+| executing | Committed code, execution summary, milestone state | verifying reads must_haves from plans |
+| verifying | Verification report, desire paths | reviewing reads project.yml + source + git diff |
 
 ### Context Loading on Resume
 
-When a skill starts after a context clear, it must load its required state from disk. Each skill's "Read Context" or "Pre-Execution Checklist" step handles this. The `forge` orchestrator reads `milestone-{id}.yml` to determine which skill to route to, then that skill loads its own dependencies.
+After a context clear, each skill loads required state from disk via its "Read Context" or "Pre-Execution Checklist" step. The `forge` orchestrator reads `milestone-{id}.yml` for routing; the target skill loads its own dependencies.
 
 ## State Transitions