forge-orkes 0.3.9 → 0.3.10

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

@@ -5,30 +5,26 @@ description: "Sync Forge framework files from a local dev repo or NPM. Use when
 
 # Upgrading: Local Dev Sync
 
-Sync framework files from a local Forge source repo into the current project. Use this during Forge development to test changes without publishing to NPM.
+Sync framework files from a local Forge source repo into the current project for testing without publishing to NPM.
 
-For published upgrades, use `npx forge-orkes upgrade` instead.
+For published upgrades, use `npx forge-orkes upgrade`.
 
 ## Step 1: Resolve Source Path
 
 Check if `.forge/dev-source` exists in the project root.
 
-- **If it exists:** read the path from the file (first line, trimmed). Verify the path exists and contains `packages/create-forge/template/`.
-- **If it doesn't exist:** ask the user: *"Where is your local Forge repo? (e.g., ~/Dev/forge)"*
-  - Validate the path has `packages/create-forge/template/`
-  - Save the path to `.forge/dev-source` for next time
+- **Exists:** Read the path (first line, trimmed). Confirm it contains `packages/create-forge/template/`.
+- **Missing:** Ask the user for the local Forge repo path, validate it has `packages/create-forge/template/`, save to `.forge/dev-source`.
 
-The template directory is `{source}/packages/create-forge/template/`.
+Template directory: `{source}/packages/create-forge/template/`.
 
 ## Step 2: File Classification
 
-Files are classified into three categories:
-
 | Category | Paths | Behavior |
 |----------|-------|----------|
-| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite — these are Forge's |
+| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite |
 | **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
-| **Template-only** | `.forge/templates/**` | Overwrite — reference templates |
+| **Template-only** | `.forge/templates/**` | Overwrite |
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements.yml`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
@@ -36,34 +32,30 @@ Files are classified into three categories:
 
 For each framework-owned file in the source template:
 
-1. Read the source file content
-2. Read the local file content (if it exists)
-3. If different → overwrite local with source, report as **updated**
-4. If same → report as **unchanged**
-5. If source has a new file not in local → copy it, report as **added**
-6. If local has a file not in source → report as **removed from template** (don't delete — let user decide)
+1. Read source and local content
+2. Different → overwrite local, report **updated**
+3. Same → report **unchanged**
+4. Source has new file → copy, report **added**
+5. Local has file not in source → report **removed from template** (don't delete -- let user decide)
 
 ## Step 4: Sync Template-Only Files
 
-Same process as Step 3, but for `.forge/templates/**`.
+Same process as Step 3 for `.forge/templates/**`.
 
 ## Step 5: Handle Merge-Owned Files
 
-For `CLAUDE.md`:
+**`CLAUDE.md`:**
 1. Read source and local versions
-2. If different → **do not overwrite**. Instead, summarize what changed in prose (new sections, removed sections, modified text)
-3. Present the summary to the user and let them decide how to merge
+2. If different → summarize changes (new/removed/modified sections) and let the user decide how to merge. Do not overwrite.
 
-For `.claude/settings.json`:
+**`.claude/settings.json`:**
 1. Read source and local versions
-2. Compare the `forge.*` keys only
-3. If forge keys differ → update only `forge.*` keys in local, preserve user's `hooks` and any other custom keys
-4. Update `forge.version` to match the source package version
+2. Compare `forge.*` keys only
+3. If different → update `forge.*` keys in local, preserve user's `hooks` and custom keys
+4. Set `forge.version` to match the source package version
 
 ## Step 6: Report
 
-Present a summary:
-
 ```
 Forge Local Sync Complete
 ─────────────────────────

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

@@ -1,86 +1,69 @@
 ---
 name: verifying
-description: "Use when work is complete and you need to prove it actually works. Trigger after execution: does the code meet original requirements? Not 'did we complete tasks' but 'does it work?' This skill enforces goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links."
+description: "Prove completed work delivers what was promised. Goal-backward verification with 3 levels: Observable Truths, Artifacts, and Key Links. Task completion ≠ goal achievement."
 ---
 
 # Verifying
 
-Prove completed work actually delivers what was promised. Task completion ≠ goal achievement.
+Prove completed work delivers what was promised. Task completion ≠ goal achievement.
 
 ## Core Question
 
-Don't ask: "Did we complete all the tasks?"
-Ask: "Does the user get what they were promised?"
+Not "Did we complete all tasks?" but "Does the user get what they were promised?"
 
 ## Load Context
 
-When entering with a fresh context (after `/clear`):
+After `/clear`, load with fresh eyes — don't carry the executor's assumptions:
 
 ```
 Read: .forge/state/milestone-{id}.yml → current phase, plans completed
 Read: .forge/project.yml → tech stack (for running tests)
 Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
-Read: .forge/context.md → locked decisions (to understand intent)
+Read: .forge/context.md → locked decisions
 Read: .forge/requirements.yml → requirement IDs for coverage check
 ```
 
-This is critical — the verifier should assess the code with fresh eyes, not carry the executor's assumptions. Load must_haves from the plan files and verify against the actual codebase.
-
 ## 3-Level Goal-Backward Verification
 
 ### Level 1: Observable Truths
 
 Read the plan's `must_haves.truths`. For each truth:
 
-1. Design a test (automated or manual) that proves/disproves it
+1. Design a test that proves/disproves it
 2. Run the test
-3. Record result: **VERIFIED** | **FAILED** | **UNCERTAIN**
+3. Record: **VERIFIED** | **FAILED** | **UNCERTAIN**
 
 ```markdown
 | Truth | Test | Result |
 |-------|------|--------|
-| User can see their profile | Navigate to /profile, check render | VERIFIED |
-| User can edit their bio | Click edit, type, save, verify persistence | VERIFIED |
-| Profile photo uploads correctly | Upload image, check display | FAILED — 413 error on large files |
+| User can edit their bio | Click edit, type, save, check persistence | VERIFIED |
+| Profile photo uploads correctly | Upload image, check display | FAILED — 413 on large files |
 ```
 
 ### Level 2: Artifacts (Exists → Substantive → Wired)
 
-Read the plan's `must_haves.artifacts`. For each artifact:
+Read the plan's `must_haves.artifacts`. For each:
 
 | Check | Question | Pass Criteria |
 |-------|----------|---------------|
-| **Exists** | Does the file exist? | File present at specified path |
-| **Substantive** | Is it real code, not a stub? | Exceeds min_lines, no placeholder text, real logic |
-| **Wired** | Is it imported and used by other code? | Has importers, called in production paths |
+| **Exists** | Does the file exist? | Present at specified path |
+| **Substantive** | Real code, not a stub? | Exceeds min_lines, no placeholders, real logic |
+| **Wired** | Imported and used? | Has importers, called in production paths |
 
 ```markdown
 | Artifact | Exists | Substantive | Wired | Status |
 |----------|--------|-------------|-------|--------|
 | src/components/Profile.tsx | ✓ | ✓ (87 lines) | ✓ (imported in routes) | VERIFIED |
-| src/api/users/[id].ts | ✓ | ✓ (43 lines) | ✓ (called by Profile) | VERIFIED |
 | src/hooks/useProfile.ts | ✓ | ✗ (returns {}) | - | STUB |
 ```
 
 ### Stub Detection Red Flags
 
-Watch for these patterns that indicate stubs, not real implementations:
-
-**React components:**
-- `<div>Component</div>` or `<div>Placeholder</div>`
-- `onClick={() => {}}` (empty handler)
-- `onChange={() => console.log()}` (logging-only handler)
-- Hardcoded data instead of API calls
+**React components:** `<div>Placeholder</div>`, `onClick={() => {}}`, `onChange={() => console.log()}`, hardcoded data instead of API calls
 
-**API endpoints:**
-- `return Response.json({ message: "Not implemented" })`
-- Empty arrays without database queries
-- TODO comments in response path
+**API endpoints:** `return Response.json({ message: "Not implemented" })`, empty arrays without DB queries, TODO in response path
 
-**Wiring:**
-- `fetch()` without await/then
-- Query without returning result
-- Form with only `preventDefault`
+**Wiring:** `fetch()` without await/then, query without returning result, form with only `preventDefault`
 
 ### Level 3: Key Links
 
@@ -88,8 +71,8 @@ Read the plan's `must_haves.key_links`. Verify each connection:
 
 | Pattern | How to Verify |
 |---------|---------------|
-| Component → API | Find fetch/axios call in component pointing to API route |
-| API → Database | Find ORM/query call in API handler returning data |
+| Component → API | Find fetch/axios call pointing to API route |
+| API → Database | Find ORM/query call returning data |
 | Form → Handler | Find onSubmit with API call and response handling |
 | State → Render | Find state variable used in JSX (not just declared) |
 
@@ -97,12 +80,11 @@ Read the plan's `must_haves.key_links`. Verify each connection:
 | From | To | Via | Pattern | Status |
 |------|----|-----|---------|--------|
 | Profile.tsx | /api/users/[id] | fetch in useEffect | fetch.*api/users | VERIFIED |
-| ProfileForm.tsx | /api/users/[id] | PUT on submit | method.*PUT | VERIFIED |
 ```
 
 ## Anti-Pattern Scan
 
-After 3-level verification, scan for common issues:
+After 3-level verification:
 
 - [ ] No `TODO` or `FIXME` in production code paths
 - [ ] No `console.log` as error handling
@@ -112,27 +94,24 @@ After 3-level verification, scan for common issues:
 
 ## Requirements Coverage
 
-Cross-reference verified work against `.forge/requirements.yml`:
+Cross-reference against `.forge/requirements.yml`:
 
 ```markdown
 | Requirement | Status | Evidence |
 |-------------|--------|----------|
 | FR-001 | Verified | Profile renders, tests pass |
-| FR-002 | Verified | Edit flow works end-to-end |
 | FR-003 | Partial | Upload works for small files, fails > 5MB |
 ```
 
 ## Verdict
 
-Based on all verification levels:
-
 ### PASSED
 All truths verified, all artifacts substantive and wired, all key links connected, requirements covered.
-→ Route to `reviewing` skill for health audit + refactoring review before milestone completion.
+→ Route to `reviewing` skill for health audit + refactoring review.
 
 ### GAPS FOUND
 Some truths failed or artifacts are stubs.
-→ Document gaps in YAML format:
+→ Document gaps:
 
 ```yaml
 gaps:
@@ -150,8 +129,8 @@ gaps:
 → Return to `planning` skill in gap-closure mode.
 
 ### HUMAN VERIFICATION NEEDED
-Some items can't be verified automatically (visual appearance, real-time behavior, external service integration).
-→ List items for user to verify manually:
+Items that can't be verified automatically (visual appearance, real-time behavior, external services).
+→ List for manual check:
 
 ```markdown
 ## Human Verification Items
@@ -162,68 +141,61 @@ Some items can't be verified automatically (visual appearance, real-time behavio
 
 ## Re-Verification Mode
 
-When re-verifying after gap closure:
+After gap closure:
 1. Load previous verification results
 2. Full 3-level check on previously failed items
-3. Quick regression check on previously passed items (exists + basic sanity)
-4. Merge results and issue updated verdict
+3. Quick regression check on passed items (exists + basic sanity)
+4. Merge results, issue updated verdict
 
 ## Desire Paths Retrospective
 
-After completing verification (PASSED or GAPS FOUND), do a quick retrospective on framework usage patterns. This takes 1-2 minutes and feeds the framework's self-improvement loop.
+After verification completes (PASSED or GAPS FOUND), run a quick retrospective on framework usage patterns. Update `.forge/state/index.yml → desire_paths` (global, not per-milestone).
 
 ### Collect Signals
 
-Review the current session and update `.forge/state/index.yml → desire_paths` (desire paths are global, not per-milestone):
+**1. Deviation patterns**: Read `.forge/state/milestone-{id}.yml → deviations`. Repeating?
+- Same Rule 1 fix in multiple places → plan template should include this check
+- Same Rule 2 addition everywhere → constitution needs a new article
+- Same Rule 3 issue → project setup is missing something
 
-**1. Deviation patterns**: Read `.forge/state/milestone-{id}.yml → deviations` from this session. Are any repeating?
-- Same Rule 1 fix in multiple places → maybe the plan template should include this check
-- Same Rule 2 addition everywhere → maybe the constitution needs a new article
-- Same Rule 3 issue → maybe the project setup is missing something
+**2. Tier overrides**: User override tier detection? Log detected vs. chosen. Repeated overrides = wrong heuristics.
 
-**2. Tier overrides**: Did the user override tier detection this session? Log what was detected vs. chosen. Repeated overrides mean the detection heuristics are wrong.
+**3. Skipped steps**: User ask to skip workflow steps? Repeated skips = friction without value.
 
-**3. Skipped steps**: Did the user ask to skip any workflow steps? (e.g., "skip the constitution check", "don't need a full research phase"). Repeated skips mean the step adds friction without value for this project type.
+**4. Recurring friction**: Same problem from previous sessions? Check prior `desire_paths`. Increment counts.
 
-**4. Recurring friction**: Did the same problem come up that appeared in previous sessions? Check previous `desire_paths` entries. Increment occurrence counts.
+**5. Agent struggles**: Agent need multiple attempts or human intervention? Log task type and failure pattern.
 
-**5. Agent struggles**: Did any agent need multiple attempts or human intervention to complete a task? Log the task type and failure pattern.
-
-**6. User corrections**: Did the user correct the same thing multiple times? (e.g., "remember to use the Card component, not a div", "always add error boundaries"). These are implicit rules that should become explicit.
+**6. User corrections**: User correct the same thing multiple times? Implicit rules that should become explicit.
 
 ### Surface Recommendations
 
-When any pattern reaches **3+ occurrences**, surface it to the user:
-
-*"I've noticed a recurring pattern: [{description}] has come up {N} times now. This suggests we should evolve the framework. Options:"*
+When any pattern reaches **3+ occurrences**, surface it:
 
 | Pattern Type | Suggested Evolution |
 |-------------|-------------------|
-| Repeated deviations | Add pre-check to planning skill, or new constitutional article |
+| Repeated deviations | Add pre-check to planning, or new constitutional article |
 | Tier overrides | Adjust detection heuristics in forge skill |
-| Skipped steps | Make step optional for this project type, or merge into another step |
-| Recurring friction | Add specific guidance to relevant skill, or create a new template |
-| Agent struggles | Add examples or anti-patterns to the skill that handles this task |
-| User corrections | Add as a rule to constitution, context.md, or the relevant skill |
+| Skipped steps | Make step optional, or merge into another step |
+| Recurring friction | Add guidance to relevant skill, or create a template |
+| Agent struggles | Add examples or anti-patterns to the relevant skill |
+| User corrections | Add rule to constitution, context.md, or relevant skill |
 
-**Concrete actions the user can approve:**
-- *"Should I add 'always use Card component for content containers' to the design-system.md?"*
-- *"Should I add a null-check verification step to the planning template?"*
-- *"Should I make the research phase optional for Standard tier in this project?"*
-- *"Should I add a new constitutional article: 'Error Boundaries Required'?"*
+Propose concrete actions:
+- *"Add 'always use Card component for content containers' to design-system.md?"*
+- *"Add null-check verification step to planning template?"*
+- *"Make research phase optional for Standard tier in this project?"*
 
-Only suggest changes when there's clear evidence (3+ occurrences). One-off issues are noise, not signal.
+Only suggest at 3+ occurrences. One-off issues are noise.
 
 ## Phase Handoff
 
-After verification completes with a PASSED verdict:
+After PASSED verdict:
 
-1. **Verify persistence** — Confirm verification results are documented, desire paths retrospective is logged to `.forge/state/index.yml`
+1. **Persist** — Confirm verification results documented, desire paths logged to `.forge/state/index.yml`
 2. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 
-*"Verification phase complete — all truths verified, artifacts substantive and wired. I recommend clearing context (`/clear`) before the review — the reviewing skill spawns fresh subagents anyway, and a clean orchestrator context ensures nothing is missed.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+*"Verification passed. State written. `/clear` then `/forge` to continue with reviewing."*
 
-Note: If verification found GAPS, route back to planning in gap-closure mode instead. The context clear recommendation applies after the re-verified PASSED verdict.
+If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.