forge-orkes 0.1.0

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

@@ -0,0 +1,524 @@
+---
+name: forge
+description: "START HERE for any task. Forge orchestrates Quick fixes, Standard features, and Full complex builds. Use this skill when starting new work, resuming a project, or unsure which workflow to follow. This is the entry point to the Forge framework."
+---
+
+# Forging: Workflow Orchestration
+
+You are the entry point. Detect the right tier, route to the right skills, manage state transitions. For new projects, run the interactive init before any work begins.
+
+## Step 1: Read State
+
+### Milestone Selection
+
+Check for state files in this order:
+1. If `.forge/state/index.yml` exists → **new milestone-aware format**
+2. If `.forge/state.yml` exists (legacy) → suggest migration: *"I found a legacy state.yml. Would you like me to migrate it to the new milestone-aware format?"* If yes, create `.forge/state/` directory, split into `index.yml` + `milestone-1.yml`, delete old file.
+3. If neither exists → no state yet, proceed to init or tier detection.
+
+**When milestone-aware state exists (`state/index.yml`):**
+1. Read `.forge/state/index.yml` to get the list of active milestones
+2. **If multiple active milestones:**
+   - Present all milestones with their progress and `last_updated` timestamp
+   - Default to the most recently updated milestone
+   - Ask user to confirm or switch: *"You have {N} active milestones. Most recent: [{name}] ({progress}%, last touched {date}). Work on this one, or switch?"*
+3. **If one milestone:** Auto-select it. Inform user: *"Resuming milestone: [{name}] ({progress}%)"*
+4. **If no active milestones:** Proceed to init or ask user to create one.
+5. Load the selected milestone's state file (`.forge/state/milestone-{id}.yml`)
+6. Report position from the milestone-specific state:
+   - Current phase, plan, task
+   - Progress percentage
+   - Active blockers
+   - Recent decisions
+
+If Beads is installed and enabled (`settings.json → forge.beads_integration: true`), also run `bd prime` for cross-session context. See `beads-integration` skill for details. This is optional — Forge works fully without it.
+
+Also read `.forge/context.md` if it exists. If the **Needs Resolution** section has unchecked items:
+- **Warn the user immediately**: *"There are {N} unresolved discrepancies from project init that need your input before planning can proceed: [list items briefly]."*
+- Quick tier tasks can proceed despite unresolved items (they don't go through planning)
+- Standard/Full tier tasks will be blocked at the planning gate until resolved
+
+Check `.forge/refactor-backlog.yml` for pending items. If found:
+- Count pending items by effort level
+- **Surface them early**: *"You have {N} pending refactoring items ({Q} quick, {S} standard). Want to tackle any before starting new work?"*
+- If the user picks one → route to `quick-tasking` (for quick items) or Standard tier (for standard items). Update the item's `status` to `in_progress`.
+- If the user says not now → proceed with normal workflow.
+
+Check `.forge/state/index.yml → desire_paths` for any patterns with 3+ occurrences that haven't been acted on:
+- **Surface them early**: *"I've noticed a recurring pattern: [{description}] ({N} times). Before we start, would you like to address this by [suggested framework change]?"*
+- If the user agrees → apply the change (update skill, constitution, or template), reset the counter
+- If the user says not now → note it and move on. Don't nag every session.
+
+If no `.forge/project.yml` exists AND the task is Standard or Full tier → go to **Step 2A: Project Init** before anything else.
+
+If state exists → go to **Step 2B: Detect Tier**.
+
+## Step 2A: Project Init
+
+This interactive workflow runs once when Forge doesn't find an existing project. First, detect whether this is a **brownfield** (existing codebase) or **greenfield** (new project) — then run the appropriate init path.
+
+### Detect Project Type
+
+Check for signals of an existing codebase:
+
+```
+Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
+Check: .git/ (version control history)
+Check: src/ OR app/ OR lib/ (source directories)
+Check: existing config files (tsconfig.json, .eslintrc, vite.config, etc.)
+```
+
+- **2+ signals found** → **Brownfield path** (existing codebase)
+- **0-1 signals** → **Greenfield path** (new project)
+
+Ask user to confirm: *"This looks like an [existing project / new project]. Is that right?"*
+
+---
+
+### Brownfield Path: Discover Existing Project
+
+For existing codebases, **scan first, confirm with user second.** Don't ask the user to describe what you can discover.
+
+#### Discovery Step 0: Framework Detection
+
+Before scanning the tech stack, check for two things: (1) existing meta-prompting frameworks with project knowledge to absorb, and (2) companion tools that should be preserved alongside Forge.
+
+**Meta-Framework Signatures** (contain project knowledge — candidates for absorption):
+
+```
+# GSD (Get Shit Done)
+Check: agents/gsd-*.md OR commands/gsd/ directory
+Check: Root-level PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md
+Check: get-shit-done/ directory
+Check: CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
+
+# Spec-Kit
+Check: spec-driven.md
+Check: templates/ with spec-template.md
+Check: extensions/catalog.json
+Check: constitution-template.md
+
+# BMAD
+Check: agents/ with 20+ agent files
+Check: workflows/ directory
+Check: bmad-* prefixed files
+
+# Generic / Unknown
+Check: .claude/agents/ or .claude/skills/ (someone else's custom framework)
+Check: CLAUDE.md with framework-like routing tables
+Check: Any structured agent/workflow system
+```
+
+**Companion Tool Signatures** (not frameworks — independent tools that work alongside Forge):
+
+```
+# Beads (persistent cross-session memory)
+Check: .beads/ directory
+Check: beads.jsonl or beads.db
+Check: bd CLI available (Bash: which bd)
+→ If found: Enable forge.beads_integration in settings.json. Do NOT absorb or archive.
+→ Beads is independent — it runs alongside Forge, not inside it.
+```
+
+**If a meta-framework is detected**, present the finding and offer three options:
+
+*"I found an existing [{framework name}] setup in this project. It contains project documentation and decisions that are valuable. How would you like to handle it?"*
+
+**Option A: Absorb & Convert** (recommended)
+Read all existing framework documentation, extract the project knowledge, and convert it into Forge's format. This means:
+- Project descriptions → `.forge/project.yml`
+- Requirements → `.forge/requirements.yml`
+- Roadmaps/plans → `.forge/roadmap.yml`
+- Context/decisions → `.forge/context.md`
+- Current state/progress → `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml`
+- Constitutional rules (if any) → `.forge/constitution.md`
+- Design system rules (if any) → `.forge/design-system.md`
+
+→ Go to **Framework Absorption** below.
+
+**Option B: Archive & Start Fresh**
+Move existing framework files into `.forge/archive/{framework-name}/` for reference, then run the standard brownfield discovery (which will still scan the codebase itself). The archive is preserved and can be consulted later.
+
+**Option C: Keep Both (Transition Period)**
+Initialize Forge alongside the existing framework. Forge reads from `.forge/` while old framework files remain in place. Useful when you want to try Forge without committing. Remove the old framework later when confident.
+
+---
+
+#### Framework Absorption (Option A)
+
+When absorbing an existing framework, read its documentation and convert systematically.
+
+**GSD Absorption Map:**
+
+| GSD Source | Read | Extract | Write to Forge |
+|-----------|------|---------|---------------|
+| `PROJECT.md` | Project name, description, tech stack, goals | Structured project info | `.forge/project.yml` |
+| `REQUIREMENTS.md` | Feature requirements, acceptance criteria | Convert prose to YAML with IDs | `.forge/requirements.yml` |
+| `ROADMAP.md` | Phases, milestones, dependencies | Convert to YAML with dependency refs | `.forge/roadmap.yml` |
+| `STATE.md` | Current phase, progress, blockers | Machine-readable state | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` |
+| `CONTEXT.md` | NON-NEGOTIABLE decisions, DEFERRED ideas | Locked decisions, deferred items | `.forge/context.md` |
+| `references/ui-brand.md` | Design system rules, brand guidelines | Component mappings, style rules | `.forge/design-system.md` |
+| `references/verification-patterns.md` | Verification approach | Inform `verifying` skill config | Constitution articles |
+| `references/tdd.md` | Testing approach | Inform constitution Article II | Constitution articles |
+| Agent customizations | Custom agent behaviors, tool restrictions | Map to Forge agent definitions | `.claude/agents/*.md` (if custom) |
+
+**Spec-Kit Absorption Map:**
+
+| Spec-Kit Source | Read | Extract | Write to Forge |
+|----------------|------|---------|---------------|
+| `spec-driven.md` | Core methodology | Governance patterns | `.forge/constitution.md` |
+| `templates/spec-template.md` | Spec structure | Requirements format | `.forge/requirements.yml` |
+| `templates/constitution-template.md` | Constitutional articles | Immutable gates | `.forge/constitution.md` |
+| `extensions/` | Extension configs | Specialized skills | `.claude/skills/` (if relevant) |
+| Project specs (if filled in) | Project-specific decisions | Locked decisions | `.forge/context.md` |
+
+**Generic Framework Absorption:**
+
+For unknown frameworks, use the `researching` skill to:
+1. Read all markdown and config files in the framework directory
+2. Identify: project descriptions, requirements, decisions, state, design rules
+3. Map each to the closest Forge equivalent
+4. Present the mapping to the user for confirmation before writing
+
+**Absorption Process:**
+
+1. Read all source files from the existing framework
+2. For each Forge target file, synthesize content from the relevant sources
+3. Convert prose to YAML where Forge expects YAML (project, requirements, roadmap, state)
+4. Preserve markdown where Forge expects markdown (constitution, context, design-system)
+5. **Never discard information** — if something doesn't map to a Forge file, note it in `.forge/context.md` under a "Carried Forward" section
+6. Move original framework files to `.forge/archive/{framework-name}/`
+7. Present a diff-style summary: *"Here's what I converted: [list]. And here's what I archived for reference: [list]. Anything I should handle differently?"*
+
+After absorption, **always** continue with the standard brownfield steps below (tech stack scan, design system detection, etc.). This is critical — see the verification step next.
+
+#### Documentation vs. Codebase Verification
+
+**Never trust framework documentation at face value.** Documentation drifts. The codebase is the source of truth.
+
+After reading existing framework docs, **cross-reference every claim against the actual code**:
+
+```
+For each claim in the documentation:
+  1. Find the corresponding code (Glob, Grep, Read)
+  2. Verify the claim matches reality
+  3. Flag any discrepancies
+```
+
+**Common drift patterns to check:**
+
+| Documentation Says | Verify Against |
+|-------------------|----------------|
+| "Tech stack: React + PostgreSQL" | `package.json` dependencies, actual imports in `src/` |
+| "Uses PrimeReact for all UI" | `Grep: src/ for "from 'primereact"` — are there also raw HTML tables, custom modals? |
+| "Tests written for all features" | `Glob: src/**/*.test.*` — actual coverage vs. claimed coverage |
+| "Auth uses Clerk/Auth0/etc." | `Grep: src/ for auth imports` — is there also custom auth code? |
+| "State management via Redux" | `package.json` + actual imports — did they switch to Zustand mid-project? |
+| "API uses REST" | `Grep: src/ for GraphQL, tRPC, WebSocket` — mixed protocols? |
+| Requirements list features A, B, C | Do routes/components for A, B, C actually exist? Are any partially implemented? |
+| Roadmap says "Phase 2 complete" | Are Phase 2 features actually wired and working, or are there stubs? |
+
+**When discrepancies are found:**
+
+Present them to the user clearly:
+
+*"I found some differences between the GSD documentation and the actual codebase:*
+
+- *PROJECT.md says 'PostgreSQL' but I only see SQLite in dependencies*
+- *REQUIREMENTS.md lists a 'notifications' feature but I can't find any notification code*
+- *STATE.md says Phase 2 is complete, but the dashboard component looks like a stub (returns placeholder text)*
+- *The docs mention PrimeReact exclusively, but I found 3 files using raw HTML tables instead of DataTable*
+
+*Should I update the Forge config to match what's actually in the code, or are some of these features that were removed/deferred?"*
+
+**Priority order for truth:**
+1. **What the code actually does** — highest authority
+2. **What the user confirms** — resolves ambiguity
+3. **What the documentation says** — useful context, but may be stale
+
+Write the verified state to Forge files. For any unresolved discrepancies, add them to `.forge/context.md` under a "Needs Resolution" section so they get addressed during planning.
+
+---
+
+#### Discovery Step 1: Tech Stack Scan
+
+```bash
+# Package manifest
+Read: package.json → name, dependencies, devDependencies, scripts
+# Or: requirements.txt, go.mod, Cargo.toml, etc.
+
+# Config files
+Glob: tsconfig.json, .eslintrc*, vite.config.*, next.config.*, webpack.config.*
+Glob: .env.example, docker-compose.yml
+
+# Source structure
+Bash: find src/ -type f | head -50  # understand file organization
+Bash: wc -l src/**/*.{ts,tsx,js,jsx} 2>/dev/null | tail -1  # codebase size
+```
+
+From this, auto-detect:
+- Language and framework
+- Build tools and test framework
+- Database (from dependencies or config)
+- Project name and description (from package.json or README)
+
+#### Discovery Step 2: Design System Detection
+
+```bash
+# Check dependencies for known UI libraries
+Grep: package.json for: primereact, @mui/, @chakra-ui/, @radix-ui/, antd, @headlessui/
+Grep: package.json for: tailwindcss, primeflex, @emotion/, styled-components
+
+# Check actual usage in source
+Grep: src/ for import patterns: "from 'primereact", "from '@mui/", "from '@/components/ui"
+Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
+
+# Check for theme files
+Glob: **/*theme*, **/*variables.scss, **/tailwind.config*, **/globals.css
+```
+
+From this, auto-detect:
+- Component library (and version from package.json)
+- Icon set in use
+- Layout system (PrimeFlex, Tailwind, MUI Grid, etc.)
+- Theme approach (SCSS variables, CSS-in-JS, Tailwind config, design tokens)
+
+#### Discovery Step 3: Pattern Analysis
+
+```bash
+# Existing conventions
+Glob: src/**/*.test.* OR src/**/*.spec.*  # test patterns
+Grep: src/ for error handling patterns
+Grep: src/ for auth/session patterns
+Bash: git log --oneline -20  # commit style
+
+# Architecture patterns
+Bash: ls -la src/  # top-level structure (pages, components, services, etc.)
+Glob: src/**/index.{ts,tsx,js}  # barrel exports
+Grep: src/ for "import.*from.*@/"  # path aliases
+```
+
+#### Discovery Step 4: Present Findings
+
+Present a structured summary to the user:
+
+*"I've scanned your codebase. Here's what I found:*
+
+*Project: {name} — {description from README or package.json}*
+*Stack: {language} + {framework} + {database}*
+*UI: {component library} with {icon set}, layout via {layout system}*
+*Testing: {test framework}, {X} existing test files*
+*Size: ~{N} source files, ~{N}K lines*
+*Patterns: {commit style}, {folder structure approach}, {key conventions}*
+
+*Does this look right? Anything I missed or got wrong?"*
+
+#### Discovery Step 5: Design System Mapping
+
+If a component library was detected:
+1. Check `.forge/templates/design-systems/` for an existing example config
+2. If found (e.g., PrimeReact) → copy it as starting point for `.forge/design-system.md`
+3. If not found → use `researching` skill to build a component mapping from docs
+4. **Cross-reference with actual usage**: scan the codebase for which components are already in use and prioritize those in the mapping
+5. Present mapping to user for validation
+
+If no component library detected but UI files exist:
+- Ask: *"I see UI code but no component library. Are you using a design system, or is this custom HTML/CSS?"*
+
+#### Discovery Step 6: Constitutional Inference
+
+Based on discovered patterns, **suggest** which articles to enable:
+
+| Discovery | Suggested Articles |
+|-----------|-------------------|
+| Test files found | Article II: Test-First (already practicing) |
+| Component library detected | Article V: Design System Fidelity |
+| Auth/session patterns found | Article VI: Security by Default |
+| Established conventions detected | Article IV: Consistency (preserve them) |
+| package-lock.json or yarn.lock | Article I: Library-First (already using libraries) |
+| Logging/monitoring deps | Article IX: Observability |
+
+Present grouped recommendations and let user confirm, add, or remove articles.
+
+---
+
+### Greenfield Path: Build from Description
+
+For new projects, ask the user to describe what they're building.
+
+#### Greenfield Step 1: Project Basics
+
+Ask the user to describe the project. From their description, fill in `.forge/project.yml`:
+
+- Project name and description
+- Primary goal
+- Tech stack (language, framework, database, testing)
+- Time and scope constraints
+- Success criteria
+- Known risks
+
+Present a summary: *"Does this capture your project correctly? Anything to add or change?"*
+
+#### Greenfield Step 2: Design System Setup
+
+Ask: *"Does this project use a UI component library or design system?"*
+
+**If yes**, ask which one and configure `design_system` in `project.yml`:
+
+```yaml
+design_system:
+  library: ""           # e.g., PrimeReact, Material-UI, shadcn/ui, Ant Design, Chakra UI
+  version: ""           # e.g., 10.x, 5.x
+  icon_set: ""          # e.g., PrimeIcons, Material Icons, Lucide, none
+  layout_system: ""     # e.g., PrimeFlex, MUI Grid, Tailwind, CSS Grid
+  theme_approach: ""    # e.g., SCSS variables, CSS-in-JS, Tailwind config, design tokens
+  docs_url: ""          # e.g., https://primereact.org/datatable/
+```
+
+Then:
+1. Check `.forge/templates/design-systems/` for a starter config
+2. If found → copy and customize for the project
+3. If not → use `researching` skill to build a component mapping from docs
+4. Write the mapping to `.forge/design-system.md`
+
+**If no** (plain HTML/CSS, utility-only, or non-UI project):
+- Set `design_system.library: none` in project.yml
+- Skip design-system.md creation
+- Disable Article V in the constitution
+
+#### Greenfield Step 3: Constitutional Setup
+
+Present the 9 constitutional articles grouped by domain:
+
+**Code quality** (recommended for most projects):
+- Article I: Library-First — prefer proven libraries over custom code
+- Article II: Test-First — tests before or alongside implementation
+- Article III: Simplicity — simplest solution wins
+- Article IV: Consistency — follow existing project patterns
+
+**Design & UI** (enable if project has UI):
+- Article V: Design System Fidelity — use the design system, don't fight it
+
+**Security & data** (enable if auth, user data, or APIs involved):
+- Article VI: Security by Default — auth, validation, secrets are requirements
+
+**Architecture** (enable based on project complexity):
+- Article VII: Integration-First — real dependencies before mocks
+- Article VIII: Documentation-Driven — decisions documented where code lives
+- Article IX: Observability — logging, error reporting, health checks
+
+Ask: *"Which of these articles apply? I'd recommend [suggest based on stack and project type]. You can also add project-specific articles."*
+
+---
+
+### Finalize Init (Both Paths)
+
+1. Write `.forge/project.yml` with all gathered/discovered info
+2. Write `.forge/constitution.md` with selected articles
+3. Write `.forge/design-system.md` (if design system configured)
+4. Initialize milestone-aware state:
+   - Create `.forge/state/` directory
+   - Write `.forge/state/index.yml`:
+     ```yaml
+     milestones:
+       - id: 1
+         name: "{project name}"
+         status: active
+         last_updated: "{date}"
+     ```
+   - Write `.forge/state/milestone-1.yml`:
+     ```yaml
+     milestone:
+       id: 1
+       name: "{project name}"
+     current:
+       tier: null
+       phase: null
+       phase_name: ""
+       plan: null
+       task: null
+       status: not_started
+     ```
+5. Copy remaining templates as needed
+
+Confirm: *"Project initialized. Here's what's set up: [summary]. Ready to start working?"*
+
+## Step 2B: Detect Tier
+
+Analyze the user's request against these patterns:
+
+### Quick Tier
+Match ANY:
+- Single file change
+- Typo, grammar, formatting fix
+- Config/environment update
+- Dependency version bump
+- Under 50 lines of changes estimated
+- User says "quick", "small", "minor", "just"
+
+→ Route to `quick-tasking` skill
+
+### Standard Tier
+Match ANY:
+- New feature or component
+- Bug fix requiring investigation
+- Refactor touching multiple files
+- Integration with external service
+- Estimated 1-8 hours of work
+
+→ Route through: `researching` → `discussing` → `planning` → `executing` → `verifying` → `auditing` → `refactoring`
+
+### Full Tier
+Match ANY:
+- New project from scratch
+- Major architectural change
+- Multi-phase milestone
+- Complex system with multiple subsystems
+- Estimated days of work
+- User says "full", "complex", "project", "milestone"
+
+→ Route through: `researching` → `discussing` → `architecting` → `planning` → `executing` → `verifying` → `auditing` → `refactoring`
+→ Add `designing` if UI work involved
+→ Add `securing` if auth/data/API touched
+
+### User Override
+If user explicitly says "Use Quick/Standard/Full tier" — honor it. No arguments.
+
+## Step 3: Route to Next Skill
+
+Based on detected tier and current state, tell the user which skill comes next and invoke it.
+
+If resuming mid-workflow:
+- Read the selected milestone's state file (`.forge/state/milestone-{id}.yml`) for current position
+- Skip completed phases
+- Resume from current phase
+
+### On-Demand Discussion
+
+The `discussing` skill can be invoked at any time, regardless of current workflow position. If the user says "discuss Phase 2", "let's talk through the plan", "I want to rethink this", or similar — route to `discussing` immediately. After the discussion concludes, return to whatever skill was active (or re-plan if the discussion changed direction).
+
+## Deviation Rules (All Tiers)
+
+While working at any tier, if you encounter:
+
+| Situation | Action | Rule |
+|-----------|--------|------|
+| Bug blocking current task | Auto-fix, document | Rule 1 |
+| Missing validation/error handling/null checks | Auto-add, document | Rule 2 |
+| Broken import/dep/config blocking progress | Auto-fix, document | Rule 3 |
+| Need new DB table, service layer, library swap | **STOP. Ask user.** | Rule 4 |
+| After verifying passes | Run health audit before completion | `auditing` |
+| After auditing passes | Review refactoring opportunities | `refactoring` |
+
+When uncertain → Rule 4 (ask). Never silently make architectural decisions.
+
+## 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)
+```
+
+Update `.forge/state/milestone-{id}.yml` at each transition. Update `.forge/state/index.yml` milestone `last_updated` timestamp.