forge-orkes 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

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

@@ -119,3 +119,15 @@ After completing architectural work:
 3. API contracts defined (if applicable)
 4. Constitutional gates verified
 5. User has approved significant decisions
+
+## Phase Handoff
+
+After architectural decisions are documented:
+
+1. **Verify persistence** — Confirm ADRs are written to `.forge/decisions/`, data models and API contracts to `.forge/phases/{N}-{name}/`
+2. **Update state** — Set `current.status` to `planning` in `.forge/state/milestone-{id}.yml`
+3. **Recommend context clear:**
+
+*"Architecting phase complete. Decisions are documented in `.forge/decisions/` and phase artifacts. I recommend clearing context (`/clear`) before starting the planning phase — the planner will load ADRs, contracts, and state from disk.*
+
+*Ready to continue? Clear context and invoke `/forge` to resume."*

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

@@ -300,3 +300,15 @@ This is a soft gate — critical issues strongly recommend fixing before complet
 - The user always has final authority over ship decisions
 
 The report documents the decision either way, creating an audit trail.
+
+## Phase Handoff
+
+After auditing routes to refactoring (all three paths: HEALTHY, accepted risk, accepted warnings):
+
+1. **Verify persistence** — Confirm health report is written to `.forge/audits/milestone-{id}-health-report.md`
+2. **Update state** — Set `current.status` to `refactoring` in `.forge/state/milestone-{id}.yml`
+3. **Recommend context clear:**
+
+*"Health audit complete. Report written to `.forge/audits/`. I recommend clearing context (`/clear`) before the refactoring review — the refactoring scanner spawns a fresh agent with the git diff and health report, so a clean context ensures accurate scanning.*
+
+*Ready to continue? Clear context and invoke `/forge` to resume."*

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

@@ -29,7 +29,20 @@ The only output is the conversation itself and, at the end, a summary of decisio
 
 ## Pre-Planning Discussion
 
-When entering from `researching` with findings in hand:
+When entering from `researching` (potentially after a context clear):
+
+### Step 0: Load Context
+
+If entering with a fresh context (after `/clear`):
+
+```
+Read: .forge/state/milestone-{id}.yml → current position, progress
+Read: .forge/project.yml → tech stack, project description
+Read: .forge/context.md → any existing locked decisions (if exists)
+Read: .forge/constitution.md → active gates (if exists)
+```
+
+Check if research findings were written to files (`.forge/phases/` or similar). If so, read them. If research was inline-only (conversation context), the findings may need to be re-summarized from the user — ask briefly: *"We're picking up after the research phase. Can you summarize the key findings, or should I re-scan the relevant areas?"*
 
 ### Step 1: Present the Landscape
 
@@ -227,3 +240,15 @@ If re-planning is needed, route back to the `planning` skill with the discussion
 - **Premature convergence** — locking decisions before the user has had a chance to think. Don't rush the summary.
 - **Scope creep via discussion** — "While we're at it, should we also..." Keep discussion focused on the work at hand.
 - **Discussion as procrastination** — if the user keeps wanting to discuss but never approves a plan, gently surface the pattern.
+
+## Phase Handoff
+
+After discussion converges on decisions:
+
+1. **Persist decisions** — The decision summary from Step 5 (pre-planning) or Step 6 (post-planning) will flow into `context.md` when the planning skill runs. For post-planning revisions, note the changes clearly so planning can pick them up.
+2. **Update state** — Set `current.status` to `planning` (or `architecting` for Full tier) in `.forge/state/milestone-{id}.yml`
+3. **Recommend context clear:**
+
+*"Discussion phase complete. Decisions are captured and will be written to context.md during planning. I recommend clearing context (`/clear`) before starting the {planning/architecting} phase — the planner will load everything it needs from `.forge/` state files.*
+
+*Ready to continue? Clear context and invoke `/forge` to resume."*

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

@@ -152,3 +152,17 @@ While executing, watch for and log these patterns in `.forge/state/index.yml →
 - **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.
+
+## 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.

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

@@ -512,13 +512,64 @@ While working at any tier, if you encounter:
 
 When 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
+
+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.
+
+### When to Recommend
+
+Recommend clearing context at every phase boundary in Standard and Full tiers:
+
+```
+researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → auditing → [clear] → refactoring
+```
+
+**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.*
+
+*Ready to continue? Clear context and invoke `/forge` to resume."*
+
+4. **If user declines** — proceed normally. The recommendation is advisory, not blocking.
+
+### What Each Phase Writes (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 |
+| architecting | ADRs in `.forge/decisions/`, data models, API contracts | planning reads decisions |
+| planning | Plans in `.forge/phases/`, 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 | auditing reads project.yml + source files |
+| auditing | Health report in `.forge/audits/` | refactoring reads health report + 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.
+
 ## State Transitions
 
 ```
-not_started → [init if new] → researching → discussing → planning → executing → verifying → auditing → refactoring → complete
-                                                                   ↗ debugging (if stuck)
-                                                         ↗ designing (if UI)
-                                                         ↗ securing (if auth/data)
+not_started → [init if new] → researching → [clear] → discussing → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → auditing → [clear] → refactoring → complete
+                                                                                                    ↗ debugging (if stuck)
+                                                                                          ↗ designing (if UI)
+                                                                                          ↗ securing (if auth/data)
 ```
 
 Update `.forge/state/milestone-{id}.yml` at each transition. Update `.forge/state/index.yml` milestone `last_updated` timestamp.

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

@@ -223,3 +223,15 @@ Show the user:
 4. Ask: "Does this plan match your expectations? Any changes?"
 
 Planning is complete when user approves.
+
+## Phase Handoff
+
+After the user approves the plan:
+
+1. **Verify persistence** — Confirm all plans are written to `.forge/phases/{N}-{name}/plan-{NN}.md`, requirements to `.forge/requirements.yml`, roadmap to `.forge/roadmap.yml`, and 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."*

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

@@ -115,3 +115,15 @@ Research output should be under 500 lines. If larger, split into focused documen
 - `research-codebase.md` for codebase findings
 - `research-tech.md` for technology evaluation
 - `research-requirements.md` for requirements analysis
+
+## 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)
+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."*

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

@@ -12,6 +12,20 @@ Prove completed work actually delivers what was promised. Task completion ≠ go
 Don't ask: "Did we complete all the tasks?"
 Ask: "Does the user get what they were promised?"
 
+## Load Context
+
+When entering with a fresh context (after `/clear`):
+
+```
+Read: .forge/state/milestone-{id}.yml → current phase, plans completed
+Read: .forge/project.yml → tech stack (for running tests)
+Read: .forge/phases/{N}-{name}/plan-{NN}.md → must_haves (truths, artifacts, key_links)
+Read: .forge/context.md → locked decisions (to understand intent)
+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
@@ -199,3 +213,17 @@ When any pattern reaches **3+ occurrences**, surface it to the user:
 - *"Should I add a new constitutional article: 'Error Boundaries Required'?"*
 
 Only suggest changes when there's clear evidence (3+ occurrences). One-off issues are noise, not signal.
+
+## Phase Handoff
+
+After verification completes with a PASSED verdict:
+
+1. **Verify persistence** — Confirm verification results are documented, desire paths retrospective is logged to `.forge/state/index.yml`
+2. **Update state** — Set `current.status` to `auditing` 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 health audit — the auditing skill spawns fresh subagents anyway, and a clean orchestrator context ensures nothing is missed.*
+
+*Ready to continue? Clear context and invoke `/forge` to resume."*
+
+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.

package/template/CLAUDE.md

@@ -61,6 +61,9 @@ Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
 ### Fresh Agent Pattern
 When a task touches 20+ files or a complex subsystem, spawn a fresh executor agent with isolated context. This prevents context rot — the #1 cause of quality degradation in long sessions.
 
+### Context Handoff Between Phases
+Each phase writes its outputs to `.forge/` before completing. At every phase boundary (researching → discussing → planning → executing → verifying → auditing → refactoring), the completing skill recommends clearing context (`/clear`) before the next phase begins. The next phase loads what it needs from disk. This is advisory — skip for short phases where context is under 40%. See the `forge` skill's "Context Handoff Protocol" for full details.
+
 ### Lazy Loading
 Skills load only when invoked. CLAUDE.md stays in context; skill details load on demand. This keeps base context lean (~300 lines) while making full framework available.