forge-orkes 0.3.11 → 0.3.13

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

@@ -1,95 +1,80 @@
 ---
 name: planning
-description: "Break work into executable tasks with verification gates. Trigger after researching when context is sufficient. Enforces constitutional gates, structures requirements, decomposes tasks, sets up goal-backward verification."
+description: "Break work into executable tasks with verification gates. Enforces constitutional gates, structures requirements, decomposes tasks, goal-backward verification."
 ---
 
 # Planning
 
-Turn research and requirements into executable, verifiable plans.
-
-> **Do NOT use `EnterPlanMode`.** All planning output goes to `.forge/phases/` as structured plan files. Follow the steps below directly.
+> **Do NOT use `EnterPlanMode`.** Output -> `.forge/phases/`.
 
 ## Step 1: Resolution Gate
 
-Read `.forge/context.md`. Check the **Needs Resolution** section.
-
-If unresolved items exist (unchecked `- [ ]` items):
-
-Present all items and ask the user to decide on each:
-*"Before we plan, {N} items need your input: [list]. For each: lock, defer, fix, or drop?"*
+Read `.forge/context.md` **Needs Resolution**. If unchecked `- [ ]` items:
+*"{N} items need input: [list]. For each: lock, defer, fix, or drop?"*
 
 | Choice | Action |
 |--------|--------|
 | Lock | Record in Locked Decisions |
-| Defer | Move to Deferred Ideas with revisit date |
-| Fix | Add as FR-xxx in `.forge/requirements.yml` — flows into the plan |
+| Defer | Move to Deferred Ideas + revisit date |
+| Fix | Add as FR-xxx in `.forge/requirements.yml` |
 | Drop | Note in Amendment Log |
 
-Check off each resolved item `- [x]` and move to the appropriate section.
-
-Target: 2-5 minutes. Quick human decisions so planning proceeds with accurate info.
+Mark resolved `- [x]`. Target: 2-5 min.
+Scan **Carried Forward** -- items affecting current phase get same triage.
 
-Also scan **Carried Forward** — items affecting the current phase get the same triage.
+## Step 2: Constitutional Gate
 
-## Step 2: Constitutional Gate Check
+Read `.forge/constitution.md`. Per article:
+- Check gate checkboxes
+- Fail -> **STOP.** Resolve first.
+- Needs amendment -> flag for user (discuss phase)
 
-Read `.forge/constitution.md`. For each relevant article:
-- Check the gate checkboxes
-- Gate fails → **STOP.** Resolve before planning.
-- Article needs amendment → flag for user decision (discuss phase)
+Record results in plan frontmatter.
 
-Document gate results in the plan frontmatter.
+## Step 3: Lock Decisions
 
-## Step 3: Lock User Decisions
+If missing, create `.forge/context.md` from template:
+1. Ask user key decisions (framework, constraints, preferences)
+2. **Locked Decisions** (contracts)
+3. **Deferred Ideas** (out of scope)
+4. **Discretion Areas** (agent picks)
 
-If not done, create `.forge/context.md` from template:
-
-1. Ask user about key decisions (framework choices, constraints, preferences)
-2. Record as **Locked Decisions** — these are contracts
-3. Record **Deferred Ideas** — explicitly out of scope
-4. Record **Discretion Areas** — agent picks best approach
-
-Do this BEFORE creating plans. Plans must reference context.md.
+Must complete BEFORE plans. Plans reference context.md.
 
 ## Step 4: Structure Requirements
 
-If `.forge/requirements.yml` doesn't exist, create from template:
-
-1. Extract functional requirements from user description + research
-2. Assign IDs: FR-001, FR-002, etc.
-3. Write acceptance criteria in Given/When/Then format
-4. Mark uncertain items: `[NEEDS CLARIFICATION]`
-5. Separate P1 (must-have) from P2 (should-have) and P3 (nice-to-have)
-6. List deferred items explicitly (DEF-001, etc.)
+If `.forge/requirements.yml` missing, create from template:
+1. Extract from user description + research
+2. IDs: FR-001, FR-002...
+3. Acceptance: Given/When/Then
+4. Uncertain: `[NEEDS CLARIFICATION]`
+5. P1 (must) / P2 (should) / P3 (nice)
+6. Deferred: DEF-001...
 
-**Planning blocks until all P1 `[NEEDS CLARIFICATION]` items are resolved.**
+**Blocks until all P1 `[NEEDS CLARIFICATION]` resolved.**
 
 ## Step 5: Create Roadmap
 
-If `.forge/roadmap.yml` doesn't exist (Full tier only):
+If `.forge/roadmap.yml` missing (Full only):
+1. Group by delivery boundaries
+2. Inter-group dependencies
+3. Phases (coherent, verifiable)
+4. Every FR -> one phase, no orphans
+5. Waves: independent=1, dependent=2+
 
-1. Group requirements by natural delivery boundaries
-2. Identify dependencies between groups
-3. Create phases (coherent, verifiable capabilities)
-4. Assign requirements to phases (every FR → exactly one phase, no orphans)
-5. Analyze waves (independent phases = Wave 1, dependencies = Wave 2+)
+## Step 6: Decompose Tasks
 
-## Step 6: Decompose into Tasks
+Per phase (or feature, Standard tier):
 
-For each phase (or single feature in Standard tier):
-
-1. Copy `.forge/templates/plan.md` → `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
-   - `{M}` = milestone ID from `roadmap.yml`
-   - `{N}` = phase number within milestone (sequential)
-   - `{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`
-2. Fill in frontmatter (phase, plan number, wave, dependencies)
-3. Create goal-backward must_haves:
-   - **Truths:** Observable from user perspective when done (3-7)
-   - **Artifacts:** Files that must exist and be substantive, not stubs
-   - **Key Links:** Critical connections between artifacts
-4. Decompose into XML tasks (2-3 per plan, 15-60 min each):
+1. `.forge/templates/plan.md` -> `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`
+   - `{M}`=milestone, `{N}`=phase#, `{name}`=kebab, `{NN}`=seq
+   - Ex: `.forge/phases/m3-2-providers/plan-01.md`
+2. Frontmatter: phase, plan#, wave, deps
+3. must_haves:
+   - **Truths:** User-observable outcomes (3-7)
+   - **Artifacts:** Must exist, substantive not stubs
+   - **Key Links:** Connections between artifacts
+4. XML tasks (2-3/plan, 15-60 min):
 
 ```xml
 <task type="auto">
@@ -123,7 +108,7 @@ For each phase (or single feature in Standard tier):
 Plan 01: User feature (model + API + UI)   → Wave 1
 Plan 02: Product feature (model + API + UI) → Wave 1
 ```
-Independent plans run in parallel.
+Independent plans run parallel.
 
 ### Avoid Horizontal Layers
 ```
@@ -131,36 +116,31 @@ Plan 01: All models    → Wave 1
 Plan 02: All APIs      → Wave 2 (depends on 01)
 Plan 03: All UI        → Wave 3 (depends on 02)
 ```
-Forces sequential execution. Only use when architecturally necessary.
+Sequential. Only when architecturally required.
 
-## Step 7: Test Spec Generation (Optional)
+## Step 7: Test Specs (Optional)
 
-**When to use:** Work involves testable contracts — APIs with defined endpoints, libraries with public interfaces, data transformations with known inputs/outputs, or services with observable behavior. Skip for UI-heavy work. User can request explicitly: *"Generate test specs for this plan."*
+**When:** Testable contracts (APIs, libraries, transforms, services). Skip UI-heavy.
 
-### Detect Testable Contracts
+### Detect Contracts
 
-Scan tasks from Step 6. A task is a testable contract candidate if it involves:
-- API endpoints — defined request/response shapes, status codes, error cases
-- Library/module interfaces — public functions with typed inputs and expected outputs
-- Data transformations — parsers, formatters, validators with known input→output mappings
-- Service integrations — external API calls with expected payloads and error handling
-- Business logic — calculations, rules engines, state machines with deterministic behavior
+Scan tasks. Candidate if:
+- API endpoints -- shapes, codes, errors
+- Library interfaces -- typed functions, outputs
+- Transforms -- parsers, validators, input->output
+- Services -- external calls, payloads, errors
+- Business logic -- calculations, state machines
 
-No testable contracts found → skip to Step 8.
+None -> skip to Step 8.
 
-### Generate Test Specifications
+### Generate Specs
 
 **Location:** `.forge/phases/m{M}-{N}-{name}/specs/`
-
-**Format:** Language-appropriate test files (`.test.ts`, `_test.go`, `test_*.py`) that:
-
-1. Import the module that will exist (path from task's `<files>`)
-2. Describe expected behavior from requirements, not implementation:
-   - Happy path from acceptance criteria
-   - Edge cases from requirements (empty input, max limits, invalid data)
-   - Error cases from `<done>` criteria
-3. Assert outcomes, not internals
-4. Mark as pending/skipped (`it.skip()`, `@pytest.mark.skip`, `t.Skip()`) so CI doesn't break before implementation
+Test files (`.test.ts`, `_test.go`, `test_*.py`):
+1. Import from `<files>` path
+2. Behavior from requirements (happy, edge, error)
+3. Assert outcomes not internals
+4. Mark pending (`it.skip()`, `@pytest.mark.skip`, `t.Skip()`)
 
 ```typescript
 // Example: .forge/phases/m1-1-auth/specs/login-endpoint.test.ts
@@ -183,9 +163,9 @@ describe('POST /api/auth/login', () => {
 });
 ```
 
-### Update Plan Tasks
+### Update Tasks
 
-For tasks with generated test specs, update the task XML to reference the spec:
+Specs -> type becomes `tdd`:
 
 ```xml
 <task type="tdd">
@@ -198,45 +178,39 @@ For tasks with generated test specs, update the task XML to reference the spec:
 </task>
 ```
 
-Task type changes to `tdd` when a spec exists. The executor's TDD flow (RED → GREEN → REFACTOR) kicks in automatically.
+Executor TDD (RED -> GREEN -> REFACTOR) auto-activates.
 
-### What NOT to Spec
-- UI component rendering (use must_haves truths)
-- Visual layout and styling (use human verification)
-- Integration flows spanning many components (use key_links verification)
-- Undefined interfaces (spec after architecting, not before)
+### Do NOT Spec
+- UI rendering (must_haves truths)
+- Layout/styling (human verify)
+- Multi-component integration (key_links)
+- Undefined interfaces (spec after architecting)
 
 ## Step 8: Verify Plans
 
-Before passing to executor, check 8 dimensions:
-
-1. **Requirement Coverage** — Every phase requirement has task(s)
-2. **Task Completeness** — All tasks have files + action + verify + done
-3. **Dependency Correctness** — Valid DAG, no circular deps
-4. **Key Links Planned** — Artifacts will be wired together, not orphaned
-5. **Scope Sanity** — 2-3 tasks per plan, targeting ~50% context
-6. **Verification Derivation** — must_haves trace to phase goal
-7. **Context Compliance** — Plans honor locked decisions, exclude deferred ideas
-8. **Spec Validity** (when Step 7 used) — Valid syntax, correct paths, derived from requirements not assumptions
-
-Issues found → fix and re-verify. Max 3 revision cycles.
-
-## Step 9: Present to User
+8 dimensions:
+1. **Requirement Coverage** -- every req has task(s)
+2. **Task Completeness** -- files + action + verify + done
+3. **Deps** -- valid DAG, no cycles
+4. **Key Links** -- wired, not orphaned
+5. **Scope** -- 2-3 tasks/plan, ~50% context
+6. **Verification** -- must_haves trace to goal
+7. **Context** -- honors locked, excludes deferred
+8. **Spec Validity** -- valid syntax, correct paths
 
-Show:
-1. Requirements summary (P1/P2/P3 counts, clarifications needed)
-2. Phase/plan structure with wave analysis
-3. Estimated effort per phase
-4. Ask: "Does this plan match your expectations? Any changes?"
+Issues -> fix, re-verify. Max 3 cycles.
 
-Planning is complete when user approves.
+## Step 9: Present
 
-## Phase Handoff
+1. Requirements (P1/P2/P3, clarifications)
+2. Phase/plan structure + waves
+3. Effort estimates
+4. "Does this plan match expectations? Changes?"
 
-After user approves:
+Done when approved.
 
-1. **Verify persistence** — Confirm plans written to `.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`, requirements to `.forge/requirements.yml`, roadmap to `.forge/roadmap.yml`, context to `.forge/context.md`
-2. **Update state** — Set `current.status` to `executing` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
+## Handoff
 
-*"Plan written. `/clear` then `/forge` to continue with executing."*
+1. **Persist** -- plans `.forge/phases/`, reqs `.forge/requirements.yml`, roadmap `.forge/roadmap.yml`, context `.forge/context.md`
+2. **State** -- `current.status` = `executing` in `.forge/state/milestone-{id}.yml`
+3. *"Plan written. `/clear` then `/forge` to continue."*