forge-orkes 0.1.0

package/template/CLAUDE.md

@@ -0,0 +1,150 @@
+# Forge
+
+A lean meta-prompting framework for Claude Code. Synthesizes context engineering (GSD) and constitutional governance (Spec-Kit) on Claude Code's native primitives.
+
+## Core Principles
+
+1. **Lean by default, powerful when needed.** Quick fixes skip ceremony. Complex features get full governance. The framework adapts — you don't.
+2. **Native-first.** Skills, agents, hooks, plugins — use Claude Code's built-in systems. No custom JavaScript, no reinvented orchestration.
+3. **Context is sacred.** Every token earns its place. Size-gate all artifacts, lazy-load skills, spawn fresh agents for isolated work.
+4. **Decisions are contracts.** User decisions lock before building begins. Downstream agents honor contracts or flag violations — never silently override.
+5. **Verify against goals, not tasks.** "Does it work?" beats "Did we complete the checklist?" Goal-backward verification at every tier.
+6. **Never forget.** Project state persists via `.forge/state/` and survives session boundaries. Milestones can be worked on concurrently across sessions. Compatible with external memory tools like Beads for deeper cross-session context.
+7. **Pave the desire paths.** When agents repeatedly deviate, users repeatedly correct, or steps repeatedly get skipped — that's a signal, not a failure. Track these patterns and evolve the framework to match how it's actually used.
+
+## Workflow Tiers
+
+Forge auto-detects complexity. Override with: "Use Quick/Standard/Full tier."
+
+### Quick (minutes)
+**Triggers:** bug fix, typo, config change, dependency bump, < 50 lines changed
+**Flow:** → `quick-tasking` → commit → done
+
+### Standard (hours)
+**Triggers:** new feature, component, significant refactor, multi-file change
+**Flow:** → `researching` → `discussing` → `planning` → `executing` → `verifying` → `auditing` → `refactoring` → done
+
+### Full (days)
+**Triggers:** new project, major milestone, complex multi-system feature, architectural decisions needed
+**Flow:** → `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `auditing` → `refactoring` → done
+**Optional additions:** `designing` (UI work), `securing` (auth/data/API), `debugging` (stuck on issue)
+
+## Skill Routing
+
+| When you need to... | Use skill | Tier |
+|---------------------|-----------|------|
+| Start any task (entry point) | `forge` | All |
+| Investigate codebase, tech, or requirements | `researching` | Standard, Full |
+| Talk through approach, trade-offs, or revisit a plan | `discussing` | Standard, Full (also on-demand) |
+| Make architectural decisions with rationale | `architecting` | Full |
+| Break work into executable tasks with gates | `planning` | Standard, Full |
+| Build code with deviation rules + atomic commits | `executing` | All |
+| Prove work actually delivers on goals | `verifying` | Standard, Full |
+| Audit application health before shipping | `auditing` | Standard, Full |
+| Review refactoring opportunities after milestone audit | `refactoring` | Standard, Full |
+| Fix a small, scoped issue fast | `quick-tasking` | Quick |
+| Build UI with design system consistency | `designing` | When UI involved |
+| Review security before shipping | `securing` | When auth/data/API involved |
+| Debug systematically with hypotheses | `debugging` | When stuck |
+| Use Beads for cross-session memory | `beads-integration` | When Beads installed |
+
+## Context Engineering
+
+### Size Gates (enforced by agents)
+| Artifact | Max Size | Why |
+|----------|----------|-----|
+| `project.yml` | 5 KB | Forces clarity — if you can't describe it concisely, you don't understand it |
+| `requirements.yml` | 50 KB | Prevents scope creep — trim to v1 essentials |
+| `plan.md` (per task) | 30 KB | Keeps executor context under 50% — quality degrades above this |
+| `constitution.md` | 10 KB | Immutable gates should be scannable, not novels |
+
+### 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.
+
+### 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.
+
+## Agents
+
+| Agent | Role | Tools | When Used |
+|-------|------|-------|-----------|
+| `researcher` | Investigation specialist | Read-only (Read, Glob, Grep, WebFetch) | Research phases |
+| `planner` | Planning with constitutional gates | Read + Write (plan files only) | Planning phases |
+| `executor` | Building with deviation rules | All dev tools | Execution phases |
+| `verifier` | Goal-backward verification | Read + Bash (test execution) | Verification phases |
+| `security-auditor` | Security vulnerability scanner | Read, Bash, Grep, Glob | Auditing phase |
+| `architecture-auditor` | Structural health assessor | Read, Grep, Glob | Auditing phase |
+| `reviewer` | Security + code quality audit | Read-only + npm audit | Before shipping |
+
+## Project Init (First Run)
+
+When `forge` detects no `.forge/project.yml`, it auto-detects the project type and runs the appropriate init:
+
+**Brownfield** (existing codebase detected — has package.json, src/, .git/):
+1. **Framework detection** — checks for existing meta-frameworks (GSD, Spec-Kit, BMAD, custom). If found, offers: absorb & convert, archive & start fresh, or keep both. Also detects companion tools (Beads, etc.) and preserves their configuration.
+2. **Framework absorption** — reads existing framework docs, converts project knowledge to Forge format (PROJECT.md → project.yml, etc.), archives originals in `.forge/archive/`
+3. **Docs vs. code verification** — cross-references all framework documentation against the actual codebase. Flags discrepancies (stale docs, missing features, drifted tech stack). The codebase is the source of truth, not the docs.
+4. **Tech stack scan** — auto-detects language, framework, dependencies, codebase size
+5. **Design system detection** — identifies component library from imports and dependencies, builds mapping
+6. **Pattern analysis** — detects testing style, commit conventions, architecture patterns
+7. **Constitutional inference** — suggests articles based on what's already in the codebase
+8. **User confirmation** — presents findings and discrepancies, user corrects/approves
+
+**Greenfield** (new project):
+1. **Project basics** — asks user to describe the project, fills in tech stack and constraints
+2. **Design system** — which component library? Researches and builds component mapping in `.forge/design-system.md`
+3. **Constitution** — walks through 9 articles grouped by domain. User selects which apply.
+4. **State init** — writes `project.yml`, `constitution.md`, `design-system.md`, `state/index.yml`, `state/milestone-1.yml`
+
+Example design system configs for PrimeReact, MUI, and shadcn/ui ship in `.forge/templates/design-systems/`.
+
+For Quick tier tasks, init is skipped — just do the work.
+
+## State Management
+
+Project state lives in `.forge/`:
+- `project.yml` — Vision, stack, design system, constraints (< 5 KB)
+- `constitution.md` — Active architectural gates (selected during init)
+- `design-system.md` — Component mapping table (generated during init)
+- `requirements.yml` — Structured requirements with `[NEEDS CLARIFICATION]` markers
+- `roadmap.yml` — Phases, milestones, dependencies
+- `state/index.yml` — Global state: active milestones list, desire_paths, metrics
+- `state/milestone-{id}.yml` — Per-milestone cursor: current position, progress, decisions, blockers, deviations
+- `context.md` — Locked user decisions + deferred ideas (created during discuss phase)
+- `plan.md` — Per-phase task plans with must_haves frontmatter
+- `refactor-backlog.yml` — Refactoring opportunities cataloged after milestone audits, worked via quick-tasking
+
+### Milestones
+Milestones group phases into concurrent work streams. Each milestone has its own state file, so different sessions can work on different milestones without conflicts. On resume, Forge shows active milestones and asks which one to work on.
+
+### Machine-Readable State
+YAML for anything agents parse programmatically (project, requirements, roadmap, state). Markdown for human-facing content (constitution, context, verification reports). Never free-form prose for machine state.
+
+## Deviation Rules (Executor Decision Tree)
+
+When the executor encounters issues during building:
+
+1. **Bug blocking current task** → Auto-fix. Document in summary with "Rule 1."
+2. **Missing critical functionality** (error handling, validation, auth, null checks) → Auto-add. Document with "Rule 2."
+3. **Blocking infrastructure issue** (missing dep, wrong types, broken imports) → Auto-fix. Document with "Rule 3."
+4. **Architectural change needed** (new DB table, service layer, library switch) → **STOP. Checkpoint with user.** Document with "Rule 4."
+
+Priority: Rule 4 first (stop if architectural). Then Rules 1-3 (auto-fix). Uncertain? → Rule 4 (ask).
+
+## Beads Integration (Optional)
+
+When Beads is installed, Forge gains persistent cross-session memory:
+- **Session start:** `bd prime` injects ~1-2K tokens of project context
+- **Task selection:** `bd ready` returns unblocked tasks sorted by priority
+- **Task completion:** `bd complete` updates dependency graph
+- **Memory hygiene:** `bd compact` summarizes old closed tasks
+
+Without Beads, Forge uses `.forge/state/` + Claude Code's Session Memory. Beads adds depth for long-horizon multi-session projects.
+
+## Atomic Commits
+
+Every task gets its own commit. Format: `{type}({scope}): {description}`
+
+Types: `feat`, `fix`, `test`, `refactor`, `chore`, `docs`
+Scope: phase-plan or feature area
+Never use `git add .` or `git add -A` — stage files individually.