forge-orkes 0.3.8 → 0.3.10

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

@@ -1,83 +1,51 @@
 ---
 name: executing
-description: "Use when building: writing code, creating files, running tests. Trigger when you have an approved plan and need to implement it. This skill enforces atomic commits, deviation rules, context engineering, and TDD when applicable."
+description: "Build to plan with atomic commits, deviation rules, and context engineering. Trigger when an approved plan exists."
 ---
 
 # Executing
 
-Build to plan with atomic commits, smart deviation handling, and context engineering.
-
 ## Pre-Execution Checklist
-
-Before writing any code:
 - [ ] 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`
+- [ ] Context.md locked decisions noted
+- [ ] Constitution.md gates satisfied
+- [ ] Milestone state updated to `status: executing`
 
 ## Deviation Rules
 
-When you encounter issues while building, follow this decision tree:
-
 ### Rule 4 Check First (Architectural)
-Does the issue require a new database table, service layer, major schema change, library swap, or infrastructure change?
-- **YES** → **STOP.** Create checkpoint. Document: what you found, proposed change, why needed, impact, alternatives. Wait for user decision.
+New DB table, service layer, schema change, library swap, or infra change?
+- **YES** → **STOP.** Checkpoint: what, proposed change, why, impact, alternatives. Wait for user.
 - **NO** → Continue to Rules 1-3.
 
 ### Rule 1: Auto-Fix Bugs
-Issue is a simple bug blocking the current task (broken behavior, wrong output, error).
-→ Fix inline. Add test if applicable. Document in summary: "Rule 1: Fixed [bug] because [reason]."
+Bug blocking current task → Fix inline. Add test if applicable. Document: "Rule 1: Fixed [bug] because [reason]."
 
 ### Rule 2: Auto-Add Critical Functionality
-Missing error handling, input validation, null checks, auth checks, CSRF protection, rate limiting, logging.
-→ Add it. Document in summary: "Rule 2: Added [functionality] because [reason]."
+Missing error handling, validation, null checks, auth, CSRF, rate limiting, logging → Add it. Document: "Rule 2: Added [what] because [reason]."
 
 ### Rule 3: Auto-Fix Blocking Infrastructure
-Missing dependency, wrong types, broken imports, env var misconfiguration, build config issue.
-→ Fix it. Document in summary: "Rule 3: Fixed [issue] because [reason]."
+Missing dep, wrong types, broken imports, env var, build config → Fix it. Document: "Rule 3: Fixed [issue] because [reason]."
 
 ### 3-Strike Limit
-After 3 auto-fix attempts on a single task → STOP fixing. Document remaining issues in summary. Move to next task.
+3 auto-fix attempts on a single task → STOP. Document remaining issues. Move to next task.
 
 ### 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:
+Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log to `.forge/deferred-issues.md`.
 
-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)
+## Native Task Tracking
 
-### On Task Start
+Use `TaskCreate`/`TaskUpdate`/`TaskList` for in-session visibility. `.forge/state/milestone-{id}.yml` remains the cross-session source of truth.
 
-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 Plan Start:** Parse `<task>` XML blocks. `TaskCreate` each: `subject` = name, `description` = action + verify + done, `activeForm` = present-continuous form. Set dependencies via `addBlockedBy`. Track native task ID → plan task number.
 
-### On Task Complete
+**On Task Start:** `TaskUpdate` → `status: "in_progress"`.
 
-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 Task Complete:** `TaskUpdate` → `status: "completed"`.
 
-### On Plan Complete
+**On Plan Complete:** Native tasks are session-scoped — disappear on `/clear`. No cleanup needed.
 
-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.
+**Skip native tasks when:** spawned fresh agents (subagents don't share parent task list) or single-task plans.
 
 ---
 
@@ -85,39 +53,36 @@ Native tasks are session-scoped — they disappear on `/clear` or session end. N
 
 For each task in the plan:
 
-1. **Read** the task XML (name, files, action, verify, done)
-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
+1. **Read** task XML (name, files, action, verify, done)
+2. **Mark in-progress** — `TaskUpdate` to `in_progress`
+3. **Check** context.md — honor locked decisions exactly
+4. **Implement** per action instructions
+5. **Verify** using the verify step
+6. **Confirm** done criteria met
 7. **Commit** atomically
-8. **Run verification gate** — execute configured verification commands (see Verification Gate below)
-9. **Mark complete** — `TaskUpdate` the native task to `completed`
+8. **Run verification gate** (see below)
+9. **Mark complete** — `TaskUpdate` to `completed`
 
-## TDD Flow (When task type="tdd")
+## TDD Flow (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/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.
+**With Test Spec:**
+1. Copy spec from `.forge/phases/m{M}-{N}-{name}/specs/` to test directory
+2. **RED:** Remove `skip` markers. Confirm failure. Commit: `test({scope}): activate spec tests for {feature}`
+3. **GREEN:** Minimal code to pass. Repeat per test.
 4. **REFACTOR:** Clean up. Commit: `feat({scope}): implement {feature}`
 
-### Without Test Spec (standard TDD)
-1. **RED:** Write failing tests first. Commit: `test({scope}): add failing tests for {feature}`
-2. **GREEN:** Write minimal code to pass tests. Commit: `feat({scope}): implement {feature}`
-3. **REFACTOR:** Clean up if needed. Commit: `refactor({scope}): clean up {feature}`
+**Without Test Spec:**
+1. **RED:** Write failing tests. Commit: `test({scope}): add failing tests for {feature}`
+2. **GREEN:** Minimal code to pass. Commit: `feat({scope}): implement {feature}`
+3. **REFACTOR:** Clean up. Commit: `refactor({scope}): clean up {feature}`
 
 ## Atomic Commit Protocol
 
-After each task completes:
-
-1. Stage only task-related files individually: `git add src/specific/file.ts`
+1. Stage files individually: `git add src/specific/file.ts`
 2. **NEVER** use `git add .` or `git add -A`
-3. Commit with format: `{type}({phase}-{plan}): {description}`
+3. Format: `{type}({phase}-{plan}): {description}`
 4. Include bullet-point body listing key changes
-5. Verify commit was created: `git log -1`
+5. Verify: `git log -1`
 
 ```
 feat(auth-01): implement JWT-based login
@@ -130,14 +95,12 @@ feat(auth-01): implement JWT-based login
 
 ## Verification Gate
 
-After each task commit, run the project's configured verification commands to catch regressions immediately. This is mechanical enforcement — not optional, not agent-directed.
+After each task commit, run configured verification commands. Mechanical — not optional.
 
 ### Load Config
-
-Read `.forge/project.yml → verification`. If `verification.commands` is empty or missing, skip this section entirely.
+Read `.forge/project.yml → verification`. Empty or missing `commands` → skip entirely.
 
 ```yaml
-# Example from project.yml:
 verification:
   commands:
     - cmd: "npm run lint"
@@ -151,127 +114,92 @@ verification:
 ```
 
 ### Execution Flow
-
-For each verification command, in order:
-
-1. **Run the command** via Bash
-2. **If it passes** → move to next command
-3. **If it fails:**
-   - **Advisory command?** → Log warning: *"Advisory: `{cmd}` failed (pre-existing issue, not blocking)."* Move to next command.
-   - **Non-advisory + `auto_fix: false`?** → Log failure and continue to next task. Don't block.
-   - **Non-advisory + `auto_fix: true`?** → Enter auto-fix loop (below)
+For each command, in order:
+1. **Run** via Bash
+2. **Pass** → next command
+3. **Fail:**
+   - **Advisory?** → Log warning, move on
+   - **Non-advisory + `auto_fix: false`?** → Log failure, next task
+   - **Non-advisory + `auto_fix: true`?** → Auto-fix loop
 
 ### Auto-Fix Loop
-
-When a non-advisory verification command fails with `auto_fix: true`:
-
 ```
 Attempt 1:
-  1. Read the command output (error messages, failing tests, lint errors)
-  2. Identify the issue — is it caused by the current task's changes?
-     - YES → fix the code, stage fixes, amend the commit
-     - NO (pre-existing) → mark this command as advisory for this session, log warning, continue
-  3. Re-run the verification command
-  4. If passes → continue to next command
-  5. If fails → attempt 2 (up to max_retries)
+  1. Read error output
+  2. Caused by current task?
+     - YES → fix code, stage fixes, amend commit
+     - NO → mark advisory for this session, log warning, continue
+  3. Re-run command
+  4. Pass → next command
+  5. Fail → next attempt (up to max_retries)
 
 After max_retries exhausted:
-  → Log the failure in the execution summary
-  → Continue to next task (don't block the whole plan)
-  → The verifying skill will catch persistent failures later
+  → Log failure in execution summary
+  → Continue to next task
+  → Verifying skill catches persistent failures later
 ```
 
-### Integration with 3-Strike Rule
-
-Verification auto-fix attempts count toward the task's 3-strike limit. If a task has already used 2 strikes on implementation issues, it gets 1 verification retry max.
+### 3-Strike Integration
+Verification retries count toward the task's 3-strike limit. 2 strikes used = 1 verification retry max.
 
-### What NOT to Fix in Verification
-
-- **Pre-existing failures** not caused by the current task → mark advisory
-- **Flaky tests** that pass on re-run without code changes → note in summary, don't count as a strike
-- **Unrelated warnings** (deprecation notices, non-blocking lint info) → ignore
+### Do NOT Fix
+- **Pre-existing failures** not from current task → mark advisory
+- **Flaky tests** passing on re-run without changes → note in summary, no strike
+- **Unrelated warnings** (deprecation, non-blocking lint) → ignore
 
 ### Quick Tier
-
-Verification gates also run for Quick tier tasks (`quick-tasking` skill). After the commit, run all non-advisory verification commands once. If they fail, show the output and let the agent fix — but limit to 1 retry (Quick tier shouldn't spend time in fix loops).
+Run all non-advisory verification commands once after commit. 1 retry max.
 
 ## Context Engineering
 
-### When to Spawn Fresh Agent
-- Task touches 20+ files
-- Task involves complex subsystem with deep dependency tree
-- Current context exceeds ~60% utilization
-- Switching between unrelated subsystems
-
-### How to Spawn
-Use the Task tool with a focused prompt:
-- Include only relevant plan details
-- Reference specific files to modify
-- Pass locked decisions from context.md
-- Set clear success criteria
-
-### Size Monitoring
-After each task, mentally assess context usage:
-- Under 40%: continue normally
-- 40-60%: consider fresh agent for next task
-- Over 60%: spawn fresh agent
+| Trigger | Action |
+|---------|--------|
+| Task touches 20+ files | Spawn fresh agent |
+| Deep dependency tree subsystem | Spawn fresh agent |
+| Context over 60% | Spawn fresh agent |
+| Context 40-60% | Consider fresh agent |
+| Context under 40% | Continue normally |
+| Switching unrelated subsystems | Spawn fresh agent |
+
+**Spawn via Task tool** with: relevant plan details, specific files, locked decisions from context.md, clear success criteria.
 
 ## Execution Summary
 
-After completing all tasks in a plan, create a summary:
+After completing all tasks in a plan:
 
 ```markdown
 # Execution Summary: m{M}-{N}-{name}, Plan {NN}
 
 ## Completed Tasks
 1. [Task name] — [one-line result]
-2. [Task name] — [one-line result]
 
 ## Deviations
 - Rule 1: Fixed [bug] in [file] because [reason]
-- Rule 2: Added [functionality] to [file] because [reason]
 
 ## Commits
 - abc1234: feat(auth-01): implement login form
-- def5678: test(auth-01): add login integration tests
 
 ## Files Modified
 - src/components/Login.tsx (created)
-- src/hooks/useAuth.ts (created)
-- src/api/auth/login.ts (created)
 
 ## Notes
 [Anything the verifier should know]
 ```
 
 ## State Updates
-
-After plan execution:
 1. Update `.forge/state/milestone-{id}.yml` — advance plan counter, update progress
-2. Record deviations in the milestone state file
-3. Update `.forge/state/index.yml` — set milestone `last_updated` timestamp
-4. If all plans in phase complete → transition to `verifying`
+2. Record deviations in milestone state
+3. Update `.forge/state/index.yml` — set `last_updated` timestamp
+4. All plans in phase complete → transition to `verifying`
 
 ## Desire Path Signals
 
-While executing, watch for and log these patterns in `.forge/state/index.yml → desire_paths` (desire paths are global, not per-milestone):
-
-- **Repeated deviations**: If you apply the same deviation rule for the same reason more than once (e.g., adding null checks in every API handler), log it as a `deviation_pattern`. Don't just record each deviation individually — notice when they form a pattern.
-- **User corrections**: If the user corrects your output and the correction matches something they've corrected before (e.g., "use the Card component, not a div"), log it as a `user_correction` and increment the count.
-- **Agent struggles**: If you need multiple attempts to get something right, or the user has to guide you through it, log the task type as an `agent_struggle`.
-
-This takes seconds per signal. Don't skip it — this data drives framework evolution.
+Log to `.forge/state/index.yml → desire_paths` (global, not per-milestone):
+- **Repeated deviations**: Same rule, same reason, more than once → `deviation_pattern`
+- **User corrections**: Repeated correction matching a prior one → `user_correction`, increment count
+- **Agent struggles**: Multiple attempts or user guidance needed → `agent_struggle`
 
 ## Phase Handoff
-
-After all plans in the phase are executed:
-
-1. **Verify persistence** — Confirm execution summary is documented, all commits are made, milestone state is updated with progress and deviations, and desire path signals are logged
-2. **Update state** — Set `current.status` to `verifying` in `.forge/state/milestone-{id}.yml`
-3. **Recommend context clear:**
-
-*"Execution phase complete. All tasks committed, state updated, deviations logged. I recommend clearing context (`/clear`) before starting verification — the verifier needs a fresh window to objectively assess the work against must_haves, without carrying the executor's assumptions.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
-
-This handoff is especially important after execution — the verifier should approach the code with fresh eyes, not the executor's memory of what it intended to build.
+1. Confirm persistence — summary documented, commits made, state updated, desire paths logged
+2. Set `current.status` to `verifying`
+3. Recommend: *"Tasks committed, state updated. `/clear` then `/forge` to continue with verifying."*