forge-orkes 0.3.9 → 0.3.11

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

@@ -1,56 +1,55 @@
 ---
 name: planning
-description: "Use when you need to break work into executable tasks with verification gates. Trigger after researching, when you have enough context to plan but haven't started building. This skill enforces constitutional gates, structures requirements, decomposes tasks, and sets up goal-backward verification."
+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."
 ---
 
 # Planning
 
 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.
+> **Do NOT use `EnterPlanMode`.** All planning output goes to `.forge/phases/` as structured plan files. Follow the steps below directly.
 
 ## Step 1: Resolution Gate
 
 Read `.forge/context.md`. Check the **Needs Resolution** section.
 
-If any unresolved items exist (unchecked `- [ ]` items under "Needs Resolution"):
+If unresolved items exist (unchecked `- [ ]` items):
 
-**Pause and triage with the user.** This is a quick conversation, not a planning phase. Present all unresolved items and ask the user to make a call on each one.
+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?"*
 
-Present each item clearly:
-*"Before we plan, there are {N} items that need your input: [list items]. For each one, should we lock it as a decision, defer it, treat it as a bug to fix, or drop it?"*
+| 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 |
+| Drop | Note in Amendment Log |
 
-**For each unresolved item, the user picks one:**
-- **→ Lock it**: The answer is clear. Record in Locked Decisions section.
-- **→ Defer it**: Not now. Move to Deferred Ideas with revisit date.
-- **→ Fix it**: This is a gap/bug. Add as a requirement (FR-xxx) in `.forge/requirements.yml` — it flows into the plan being created.
-- **→ Drop it**: No longer relevant. Note in Amendment Log.
+Check off each resolved item `- [x]` and move to the appropriate section.
 
-Check off each resolved item `- [x]` and move it to the appropriate section.
+Target: 2-5 minutes. Quick human decisions so planning proceeds with accurate info.
 
-**This should take 2-5 minutes, not a whole planning cycle.** The goal is to get quick human decisions so planning can proceed with accurate information.
-
-Also scan the **Carried Forward** section — items here that affect the current phase should be triaged the same way.
+Also scan **Carried Forward** — items affecting the current phase get the same triage.
 
 ## Step 2: Constitutional Gate Check
 
-Read `.forge/constitution.md`. For each article relevant to this phase:
+Read `.forge/constitution.md`. For each relevant article:
 - Check the gate checkboxes
-- If any gate fails → **STOP.** Resolve before planning.
-- If an article needs amendment → flag for user decision (discuss phase)
+- Gate fails → **STOP.** Resolve before planning.
+- Article needs amendment → flag for user decision (discuss phase)
 
 Document gate results in the plan frontmatter.
 
 ## Step 3: Lock User Decisions
 
-If not already done, create `.forge/context.md` from template:
+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
 
-**Critical:** Do this BEFORE creating plans. Plans must reference context.md.
+Do this BEFORE creating plans. Plans must reference context.md.
 
 ## Step 4: Structure Requirements
 
@@ -77,14 +76,14 @@ If `.forge/roadmap.yml` doesn't exist (Full tier only):
 
 ## Step 6: Decompose into Tasks
 
-For each phase (or the single feature in 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` (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
+   - `{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)
@@ -103,15 +102,21 @@ For each phase (or the single feature in Standard tier):
 ```
 
 ### Task Sizing
-- Under 15 min → too small, combine with adjacent task
-- 15-60 min → right size
-- Over 60 min → too large, split into separate plan
+
+| Duration | Action |
+|----------|--------|
+| < 15 min | Too small — combine with adjacent task |
+| 15-60 min | Right size |
+| > 60 min | Too large — split into separate plan |
 
 ### Task Types
-- `auto` — Fully autonomous (90% of tasks)
-- `checkpoint:human-verify` — Pause for visual/functional check
-- `checkpoint:decision` — Pause for user choice between options
-- `checkpoint:human-action` — Pause for truly manual action (email verification, 2FA)
+
+| Type | Use |
+|------|-----|
+| `auto` | Fully autonomous (90% of tasks) |
+| `checkpoint:human-verify` | Pause for visual/functional check |
+| `checkpoint:decision` | Pause for user choice between options |
+| `checkpoint:human-action` | Pause for manual action (email verification, 2FA) |
 
 ### Vertical Slices (Preferred)
 ```
@@ -130,36 +135,32 @@ Forces sequential execution. Only use when architecturally necessary.
 
 ## Step 7: Test Spec Generation (Optional)
 
-**When to use:** Invoke this step when the 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 where the existing must_haves approach is sufficient.
-
-**The user can also explicitly request this:** *"Generate test specs for this plan."*
+**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."*
 
 ### Detect Testable Contracts
 
-Scan the 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, converters 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 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
 
-If no testable contracts are found, skip to Step 8.
+No testable contracts found → skip to Step 8.
 
 ### Generate Test Specifications
 
-For each testable contract, create a test spec file alongside the plan:
-
 **Location:** `.forge/phases/m{M}-{N}-{name}/specs/`
 
-**Format:** Language-appropriate test files (e.g., `.test.ts`, `_test.go`, `test_*.py`) that:
+**Format:** Language-appropriate test files (`.test.ts`, `_test.go`, `test_*.py`) that:
 
-1. **Import the module that will exist** (the path from the task's `<files>` field)
-2. **Describe expected behavior** derived from requirements, NOT from implementation:
-   - Happy path cases from acceptance criteria
+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 the `<done>` criteria
-3. **Assert outcomes, not internals** — test what the function returns or what side effects occur, not how it's implemented
-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
+   - 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
 
 ```typescript
 // Example: .forge/phases/m1-1-auth/specs/login-endpoint.test.ts
@@ -197,33 +198,32 @@ For tasks with generated test specs, update the task XML to reference the spec:
 </task>
 ```
 
-Note: The task type changes to `tdd` when a spec exists. The executor's TDD flow (RED → GREEN → REFACTOR) kicks in automatically.
+Task type changes to `tdd` when a spec exists. The executor's TDD flow (RED → GREEN → REFACTOR) kicks in automatically.
 
 ### What NOT to Spec
-
-- UI component rendering (use must_haves truths instead)
+- UI component rendering (use must_haves truths)
 - Visual layout and styling (use human verification)
 - Integration flows spanning many components (use key_links verification)
-- Anything where the interface isn't defined yet (spec after architecting, not before)
+- Undefined interfaces (spec after architecting, not before)
 
-## Step 8: Verify Plans (Plan Checker)
+## Step 8: Verify Plans
 
-Before passing to executor, verify across 8 dimensions:
+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)
+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 was used) — Test specs are valid syntax, reference correct paths, derive from requirements not assumptions
+8. **Spec Validity** (when Step 7 used) — Valid syntax, correct paths, derived from requirements not assumptions
 
-If issues found → fix and re-verify. Max 3 revision cycles.
+Issues found → fix and re-verify. Max 3 revision cycles.
 
 ## Step 9: Present to User
 
-Show the user:
+Show:
 1. Requirements summary (P1/P2/P3 counts, clarifications needed)
 2. Phase/plan structure with wave analysis
 3. Estimated effort per phase
@@ -233,12 +233,10 @@ Planning is complete when user approves.
 
 ## Phase Handoff
 
-After the user approves the plan:
+After user approves:
 
-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`
+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:**
 
-*"Planning phase complete. Plans, requirements, and context are all written to `.forge/`. I recommend clearing context (`/clear`) before starting execution — the executor will load the plan files and context.md fresh, giving it maximum context window for building.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+*"Plan written. `/clear` then `/forge` to continue with executing."*

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: quick-tasking
-description: "Use for small, scoped changes: typo fixes, config updates, minor bug fixes, dependency bumps, documentation tweaks. Trigger when the change is under 50 lines, touches 1-2 files, and requires no architectural decisions. This is the Quick tier — skip planning ceremony, just do it right."
+description: "Small, scoped changes: typo fixes, config updates, minor bugs, dependency bumps, doc tweaks. Under 50 lines, 1-2 files, no architectural decisions. Quick tier — skip ceremony."
 ---
 
 # Quick-Tasking
 
-Small change? Skip the ceremony. Do it right, do it fast.
+Small change? Skip ceremony. Do it right, do it fast.
 
 ## Qualifies as Quick
 
@@ -13,62 +13,56 @@ Small change? Skip the ceremony. Do it right, do it fast.
 - Typo, grammar, or formatting fix
 - Config or environment variable update
 - Dependency version bump
-- Simple bug fix with obvious root cause
+- Bug fix with obvious root cause
 - Documentation update
 - CSS/style tweak within design system
 - Adding a missing import or export
 
-## Does NOT Qualify as Quick
+## Does NOT Qualify
 
-Upgrade to Standard tier if any of these are true:
-- Change touches 3+ files
-- Requires new component, function, or module
-- Involves logic changes affecting multiple features
+Escalate to Standard tier if any are true:
+- Touches 3+ files
+- Requires a new component, function, or module
+- Logic changes affecting multiple features
 - Needs a new dependency
-- Requires architectural decision
+- Requires an architectural decision
 - Estimated at more than 30 minutes
-- You're unsure about the right approach
+- Unsure about the right approach
 
-## Quick Workflow
+## Workflow
 
 ### 1. Identify
-What exactly needs to change? Be specific: which file, which line, what's wrong.
+What needs to change? Which file, which line, what's wrong.
 
 ### 2. Validate Scope
-Confirm it's truly quick:
 - [ ] Under 50 lines of changes
-- [ ] 1-2 files maximum
+- [ ] 1-2 files max
 - [ ] No architectural decisions needed
-- [ ] Root cause is obvious (or bug fix is straightforward)
+- [ ] Root cause is obvious
 
-If any check fails → escalate to Standard tier.
+Any check fails → escalate to Standard tier.
 
 ### 3. Execute
-Make the change. Follow existing patterns in the codebase.
+Make the change. Follow existing codebase patterns.
 
 ### 4. Test
 - Run relevant tests: `npm test -- --filter={related}`
-- If no tests exist for this area, at minimum verify it compiles/builds
-- For UI changes, visually confirm the fix
+- No tests for this area → at minimum confirm it compiles/builds
+- UI changes → visually confirm the fix
 
 ### 5. Commit
-Atomic commit with proper format:
+Atomic commit:
 ```
 {type}({scope}): {description}
 ```
-Examples:
-- `fix(docs): correct typo in API reference`
-- `chore(deps): bump react to 19.1.0`
-- `fix(ui): align header padding with design system`
+Example: `fix(docs): correct typo in API reference`
 
 ### 6. Done
-No verification ceremony needed. Move on.
+No verification ceremony. Move on.
 
 ## Scope Creep Detection
 
-While executing a quick task, if you discover:
-- The fix is bigger than expected → **STOP**. Escalate to Standard.
-- Related issues that should also be fixed → **LOG** to `.forge/deferred-issues.md`. Don't fix now.
-- An architectural question → **STOP**. Escalate to Standard with a note about what triggered it.
-
-Quick-tasking is about discipline: do the small thing, only the small thing, and move on.
+During execution, if you discover:
+- Fix is bigger than expected → **STOP**. Escalate to Standard.
+- Related issues that should be fixed → **LOG** to `.forge/deferred-issues.md`. Don't fix now.
+- An architectural question → **STOP**. Escalate to Standard with a note on what triggered it.

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

@@ -5,67 +5,65 @@ description: "Use when you need to investigate before building: understand the c
 
 # Researching
 
-Gather context before planning. Bad research → bad plans → wasted time.
+Gather context before planning. Bad research leads to bad plans.
 
 ## Research Types
 
 ### 1. Codebase Research
 **When:** Joining existing project, planning changes to existing code, brownfield work.
 
-Steps:
 1. Map directory structure (`ls`, `find`, `tree`)
 2. Identify key files: entry points, config, routes, models, components
 3. Read conventions: naming, imports, error handling, testing patterns
 4. Identify tech stack: framework, libraries, versions
-5. Find existing patterns similar to planned work (reuse, don't reinvent)
+5. Find existing patterns similar to planned work — reuse, don't reinvent
 6. Document concerns: tech debt, fragile areas, missing tests
 
-Output: Research summary with file paths, patterns found, reuse opportunities.
+**Output:** Research summary with file paths, patterns found, reuse opportunities.
 
 ### 2. Requirements Research
 **When:** Requirements are vague, conflicting, or incomplete.
 
-Steps:
 1. Read all available requirements/specs/user stories
 2. Identify gaps — what's not specified?
 3. Mark uncertainties with `[NEEDS CLARIFICATION]`
 4. Draft acceptance criteria (Given/When/Then)
 5. Present clarification questions to user
 
-Output: Structured requirements draft with uncertainty markers.
+**Output:** Structured requirements draft with uncertainty markers.
 
 ### 3. Technology Research
 **When:** Evaluating libraries, frameworks, APIs, or integration approaches.
 
-Steps:
-1. Check MCP servers first (structured data beats web scraping)
-2. Read official documentation (not blog posts)
+1. Check MCP servers first — structured data beats web scraping
+2. Read official documentation, not blog posts
 3. Check version compatibility with existing stack
 4. Look for known issues, migration guides, breaking changes
 5. Find working code examples from official sources
 
-Output: Technology assessment with recommendation and confidence level.
+**Output:** Technology assessment with recommendation and confidence level.
 
 ### 4. Feasibility Research
 **When:** Unsure if approach will work, need to spike a risky idea.
 
-Steps:
 1. Identify the riskiest assumption
 2. Build minimal proof-of-concept (< 30 minutes)
 3. Test the critical path only
 4. Document: works / doesn't work / works with caveats
 
-Output: Feasibility verdict with evidence.
+**Output:** Feasibility verdict with evidence.
 
 ## Tool Priority
 
-Use tools in this order (highest confidence first):
+Use in this order (highest confidence first):
 
-1. **Codebase itself** — Read actual code. Highest confidence.
-2. **MCP servers** — Structured data from Notion, GitHub, Linear, etc.
-3. **Official docs** — Framework/library documentation via WebFetch.
-4. **Web search** — Community solutions, Stack Overflow, blog posts.
-5. **Training data** — Use as hypothesis only. Verify before trusting.
+| Priority | Source | Notes |
+|----------|--------|-------|
+| 1 | Codebase | Read actual code. Highest confidence. |
+| 2 | MCP servers | Structured data from Notion, GitHub, Linear, etc. |
+| 3 | Official docs | Framework/library docs via WebFetch. |
+| 4 | Web search | Community solutions, Stack Overflow, blogs. |
+| 5 | Training data | Hypothesis only. Verify before trusting. |
 
 ## Confidence Levels
 
@@ -79,12 +77,11 @@ Tag every finding:
 
 ## Parallel Research
 
-When investigating independent topics, research them simultaneously:
-- Spawn separate research agents for each topic
-- Each agent gets a focused scope
+For independent topics, research simultaneously:
+- Spawn separate research agents per topic with focused scope
 - Collect and synthesize results
 
-Do NOT research sequentially when topics are independent.
+Never research sequentially when topics are independent.
 
 ## Output Template
 
@@ -111,19 +108,12 @@ Do NOT research sequentially when topics are independent.
 
 ## Size Gate
 
-Research output should be under 500 lines. If larger, split into focused documents:
-- `research-codebase.md` for codebase findings
-- `research-tech.md` for technology evaluation
-- `research-requirements.md` for requirements analysis
+Research output under 500 lines. If larger, split into focused documents: `research-codebase.md`, `research-tech.md`, `research-requirements.md`.
 
 ## Phase Handoff
 
-After research is complete:
-
-1. **Persist findings** — Write research summary to `.forge/phases/` or present inline (for Standard tier, inline is fine; for Full tier with multiple research topics, write to files)
+1. **Persist findings** — Write research summary to `.forge/phases/m{M}-{N}-{name}/` or present inline. Standard tier: inline is fine. Full tier with multiple topics: write to files.
 2. **Update state** — Set `current.status` to `discussing` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 
-*"Research phase complete. Findings are summarized above [or written to .forge/phases/]. I recommend clearing context (`/clear`) before starting the discussion phase — this gives discussing a fresh window to work with. The discussing skill will reference the research findings.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+*"Research complete. State written. `/clear` then `/forge` to continue with discussing."*