forge-orkes 0.3.11 → 0.3.14

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

@@ -1,15 +1,13 @@
 ---
 name: initializing
-description: "Run once per project to detect brownfield/greenfield, scan tech stack, absorb existing frameworks, configure design system, and set up constitutional gates. Invoked by the forge skill when no .forge/project.yml exists."
+description: "Detect brownfield/greenfield, scan stack, absorb frameworks, configure design system + constitution. Runs when no .forge/project.yml exists."
 ---
 
-# Initializing: Project Setup
+# Initializing
 
-Runs once when no `.forge/project.yml` exists. Detect **brownfield** vs **greenfield**, then run the matching init path.
+Once (no `.forge/project.yml`). Detect **brownfield** vs **greenfield**.
 
-## Detect Project Type
-
-Check for existing codebase signals:
+## Detect Type
 
 ```
 Check: package.json OR requirements.txt OR go.mod OR Cargo.toml (dependency manifest)
@@ -18,22 +16,13 @@ Check: src/ OR app/ OR lib/ (source directories)
 Check: existing config files (tsconfig.json, .eslintrc, vite.config, etc.)
 ```
 
-- **2+ signals** → **Brownfield path**
-- **0-1 signals** → **Greenfield path**
-
-Confirm with user: *"This looks like an [existing project / new project]. Is that right?"*
-
----
-
-## Brownfield Path: Discover Existing Project
+**2+** → Brownfield. **0-1** → Greenfield. Confirm.
 
-Scan first, confirm with user second. Don't ask what you can discover.
+## Brownfield
 
-### Discovery Step 0: Framework Detection
+Scan first, confirm second. Discover, don't ask.
 
-Check for: (1) meta-prompting frameworks with project knowledge to absorb, (2) companion tools to preserve.
-
-**Meta-Framework Signatures:**
+### Step 0: Framework Detection
 
 ```
 # GSD (Get Shit Done)
@@ -59,23 +48,11 @@ Check: CLAUDE.md with framework-like routing tables
 Check: Any structured agent/workflow system
 ```
 
-**Companion Tool Signatures:**
-
-```
-# 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**, offer three options:
+**Companion:** Beads (.beads/, beads.jsonl, `bd`) → enable `forge.beads_integration`, don't absorb.
 
-*"I found [{framework name}] in this project with valuable project documentation. How would you like to handle it?"*
+**If meta-framework found**, offer:
 
-**Option A: Absorb & Convert** (recommended)
-Read existing framework docs, extract project knowledge, convert to Forge format:
+**A: Absorb** (recommended) — extract → Forge:
 
 | Source | Target |
 |--------|--------|
@@ -87,19 +64,13 @@ Read existing framework docs, extract project knowledge, convert to Forge format
 | Constitutional rules | `.forge/constitution.md` |
 | Design system rules | `.forge/design-system.md` |
 
-Go to **Framework Absorption** below.
-
-**Option B: Archive & Start Fresh**
-Move framework files to `.forge/archive/{framework-name}/` for reference, then run standard brownfield discovery.
-
-**Option C: Keep Both (Transition Period)**
-Initialize Forge alongside the existing framework. Remove the old framework later when confident.
+**B: Archive** — `.forge/archive/{name}/`, run brownfield. **C: Keep Both** — init alongside, remove later.
 
 ---
 
-### Framework Absorption (Option A)
+### Absorption (A)
 
-**GSD Absorption Map:**
+**GSD:**
 
 | GSD Source | Extract | Write to Forge |
 |-----------|---------|---------------|
@@ -113,7 +84,7 @@ Initialize Forge alongside the existing framework. Remove the old framework late
 | `references/tdd.md` | Testing approach | Constitution articles |
 | Agent customizations | Custom behaviors, tool restrictions | `.claude/agents/*.md` (if custom) |
 
-**Spec-Kit Absorption Map:**
+**Spec-Kit:**
 
 | Spec-Kit Source | Extract | Write to Forge |
 |----------------|---------|---------------|
@@ -123,31 +94,13 @@ Initialize Forge alongside the existing framework. Remove the old framework late
 | `extensions/` | Specialized skills | `.claude/skills/` (if relevant) |
 | Project specs (if filled in) | 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. If something doesn't map to a Forge file, note it in `.forge/context.md` under "Carried Forward"
-6. Move originals to `.forge/archive/{framework-name}/`
-7. Present a diff-style summary: *"Here's what I converted: [list]. Archived for reference: [list]. Anything to handle differently?"*
+**Generic:** `researching` reads all markdown/config, maps to Forge equivalents, confirms with user.
 
-After absorption, **always** continue with the standard brownfield steps below — see the verification step next.
+**Process:** Read sources → synthesize per target → prose to YAML where expected, keep markdown where expected → unmapped to `.forge/context.md` "Carried Forward" → originals to `.forge/archive/{name}/` → show summary. Then continue brownfield steps.
 
-### Documentation vs. Codebase Verification
+### Docs vs. Code
 
-**Never trust framework documentation at face value.** The codebase is the source of truth.
-
-After reading framework docs, cross-reference every claim against actual code:
+**Never trust docs.** Code = truth.
 
 ```
 For each claim in the documentation:
@@ -156,8 +109,6 @@ For each claim in the documentation:
   3. Flag any discrepancies
 ```
 
-**Common drift patterns:**
-
 | Documentation Says | Verify Against |
 |-------------------|----------------|
 | "Tech stack: React + PostgreSQL" | `package.json` deps, actual imports in `src/` |
@@ -169,15 +120,10 @@ For each claim in the documentation:
 | Requirements list features A, B, C | Do routes/components for A, B, C exist? Partially implemented? |
 | Roadmap says "Phase 2 complete" | Are Phase 2 features wired and working, or stubs? |
 
-**When discrepancies are found**, present them clearly and ask whether Forge config should match the code or whether features were removed/deferred.
+Discrepancies: ask if config matches code or features removed/deferred. Priority: Code > User > Docs.
+Verified → Forge files. Unresolved → `.forge/context.md` "Needs Resolution".
 
-**Truth priority:** (1) What the code does, (2) What the user confirms, (3) What the docs say.
-
-Write verified state to Forge files. Unresolved discrepancies go in `.forge/context.md` under "Needs Resolution".
-
----
-
-### Discovery Step 1: Tech Stack Scan
+### Step 1: Tech Stack
 
 ```bash
 # Package manifest
@@ -193,11 +139,9 @@ 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
 ```
 
-Auto-detect: language, framework, build tools, test framework, database, project name/description.
-
-### Discovery Step 1.5: Verification Command Detection
+Auto-detect: language, framework, build tools, tests, DB, name.
 
-Auto-detect verification commands from the project's package manifest and config:
+### Step 1.5: Verification Commands
 
 ```bash
 # Node.js projects — scan package.json scripts
@@ -214,7 +158,7 @@ Check: Makefile, tox.ini, pyproject.toml for test/lint commands
 # Rust projects — cargo test, cargo clippy
 ```
 
-**Node.js auto-detection rules:**
+**Node.js:**
 
 | `package.json` script | Verification command |
 |----------------------|---------------------|
@@ -224,7 +168,7 @@ Check: Makefile, tox.ini, pyproject.toml for test/lint commands
 | `tsc` in scripts or `typescript` in devDeps | `npx tsc --noEmit` |
 | `eslint` in devDeps but no `lint` script | `npx eslint .` |
 
-**Advisory mode detection:** Run each command once to check baseline health. Commands that fail on the current codebase (before Forge changes anything) get `advisory: true` — they run but don't block. This prevents pre-existing tech debt from blocking execution.
+Run once for baseline. Pre-existing failures → `advisory: true` (run, don't block).
 
 ```yaml
 # Example auto-detected config:
@@ -240,9 +184,9 @@ verification:
   max_retries: 2
 ```
 
-Present findings to user with pass/fail status and advisory flags. Ask if they want to add, remove, or adjust commands.
+Present pass/fail + flags. User adjusts.
 
-### Discovery Step 2: Design System Detection
+### Step 2: Design System
 
 ```bash
 # Check dependencies for known UI libraries
@@ -257,9 +201,9 @@ Grep: src/ for icon usage: "pi pi-", "Material", "lucide-react"
 Glob: **/*theme*, **/*variables.scss, **/tailwind.config*, **/globals.css
 ```
 
-Auto-detect: component library (+ version), icon set, layout system, theme approach.
+Auto-detect: library (+version), icons, layout, theme.
 
-### Discovery Step 3: Pattern Analysis
+### Step 3: Patterns
 
 ```bash
 # Existing conventions
@@ -274,33 +218,26 @@ Glob: src/**/index.{ts,tsx,js}  # barrel exports
 Grep: src/ for "import.*from.*@/"  # path aliases
 ```
 
-### Discovery Step 4: Present Findings
-
-Present a structured summary:
-
-*"Project: {name} — {description}*
-*Stack: {language} + {framework} + {database}*
-*UI: {component library} with {icon set}, layout via {layout system}*
-*Testing: {test framework}, {X} test files*
-*Size: ~{N} source files, ~{N}K lines*
-*Patterns: {commit style}, {folder structure}, {key conventions}*
+### Step 4: Present
 
-*Does this look right? Anything I missed or got wrong?"*
+*"Project: {name} — {description}
+Stack: {language} + {framework} + {database}
+UI: {library} + {icons}, layout: {system}
+Testing: {framework}, {X} files
+Size: ~{N} files, ~{N}K lines
+Right? Anything missed?"*
 
-### Discovery Step 5: Design System Mapping
+### Step 5: Design System Mapping
 
-If a component library was detected:
-1. Check `.forge/templates/design-systems/` for a starter config
-2. If found → copy as starting point for `.forge/design-system.md`
-3. If not → use `researching` skill to build a component mapping from docs
-4. Cross-reference with actual usage: scan for which components are already used
-5. Present mapping to user for validation
+Library detected:
+1. Check `.forge/templates/design-systems/` for starter
+2. Found → copy to `.forge/design-system.md`
+3. Not found → `researching` builds mapping
+4. Cross-ref actual usage, present for validation
 
-If no library detected but UI files exist, ask: *"I see UI code but no component library. Are you using a design system, or custom HTML/CSS?"*
+No library + UI files → *"No component library. Design system or custom?"*
 
-### Discovery Step 6: Constitutional Inference
-
-Suggest articles based on discovered patterns:
+### Step 6: Constitutional Inference
 
 | Discovery | Suggested Articles |
 |-----------|-------------------|
@@ -311,30 +248,19 @@ Suggest articles based on discovered patterns:
 | package-lock.json or yarn.lock | Article I: Library-First |
 | Logging/monitoring deps | Article IX: Observability |
 
-Present grouped recommendations. User confirms, adds, or removes.
-
----
-
-## Greenfield Path: Build from Description
+Present grouped. User confirms/adds/removes.
 
-### Greenfield Step 1: Project Basics
+## Greenfield
 
-Ask the user to describe the project. From their description, fill in `.forge/project.yml`:
+### Step 1: Basics
 
-- Project name and description
-- Primary goal
-- Tech stack (language, framework, database, testing)
-- Time and scope constraints
-- Success criteria
-- Known risks
+User describes project → `.forge/project.yml`: name, goal, stack, constraints, success criteria, risks.
 
-Confirm: *"Does this capture your project correctly? Anything to add or change?"*
+### Step 2: Design System
 
-### Greenfield Step 2: Design System Setup
+*"UI library?"*
 
-Ask: *"Does this project use a UI component library or design system?"*
-
-**If yes**, ask which one and configure `design_system` in `project.yml`:
+**Yes** — configure in `project.yml`:
 
 ```yaml
 design_system:
@@ -346,20 +272,11 @@ design_system:
   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
-3. If not → use `researching` skill to build a component mapping from docs
-4. Write 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
+Check `.forge/templates/design-systems/` for starter → copy/customize, or `researching` builds mapping → `.forge/design-system.md`.
 
-### Greenfield Step 2.5: Verification Commands
+**No**: `library: none`, skip design-system.md, disable Article V.
 
-Ask: *"What verification commands should run after each task?"*
+### Step 2.5: Verification
 
 | Stack | Suggested commands |
 |-------|-------------------|
@@ -371,43 +288,24 @@ Ask: *"What verification commands should run after each task?"*
 | Go | `go test ./...`, `go vet ./...` |
 | Rust | `cargo test`, `cargo clippy` |
 
-Pre-fill based on the chosen tech stack. User confirms or adjusts. Write to the `verification` section of `project.yml`.
-
-If the user doesn't want verification gates: set `verification.commands: []`.
-
-### Greenfield Step 3: Constitutional Setup
-
-Present the 9 articles grouped by domain:
+Pre-fill from stack → `verification` in `project.yml`. No gates → `[]`.
 
-**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
+### Step 3: Constitution
 
-**Design & UI** (if project has UI):
-- Article V: Design System Fidelity — use the design system, don't fight it
+**Code quality** (most projects): I Library-First, II Test-First, III Simplicity, IV Consistency
+**Design & UI** (if UI): V Design System Fidelity
+**Security & data** (if auth/data/APIs): VI Security by Default
+**Architecture** (by complexity): VII Integration-First, VIII Documentation-Driven, IX Observability
 
-**Security & data** (if auth, user data, or APIs involved):
-- Article VI: Security by Default — auth, validation, secrets are requirements
-
-**Architecture** (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 articles apply? I'd recommend [suggest based on stack]. You can also add project-specific articles."*
-
----
+User selects per stack.
 
-## Finalize Init (Both Paths)
+## Finalize
 
-1. Write `.forge/project.yml` with all gathered/discovered info (including `verification` section)
-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`:
+1. Write `.forge/project.yml` (all info + `verification`)
+2. Write `.forge/constitution.md`
+3. Write `.forge/design-system.md` (if configured)
+4. Init state:
+   - `.forge/state/index.yml`:
      ```yaml
      milestones:
        - id: 1
@@ -415,7 +313,7 @@ Ask: *"Which articles apply? I'd recommend [suggest based on stack]. You can als
          status: active
          last_updated: "{date}"
      ```
-   - Write `.forge/state/milestone-1.yml`:
+   - `.forge/state/milestone-1.yml`:
      ```yaml
      milestone:
        id: 1
@@ -428,8 +326,8 @@ Ask: *"Which articles apply? I'd recommend [suggest based on stack]. You can als
        task: null
        status: not_started
      ```
-5. Copy remaining templates as needed
+5. Templates as needed
 
-Confirm: *"Project initialized: [summary]. Ready to start working?"*
+*"Initialized. Ready?"*
 
-Return control to the `forge` skill for tier detection and routing.
+Return to `forge`.