@samahlstrom/forge-cli 0.1.0

package/templates/core/CLAUDE.md.hbs

@@ -0,0 +1,70 @@
+# CLAUDE.md — Agent Harness Instructions
+
+> Generated by forge. These instructions apply to all AI agents working in this codebase.
+
+## Read First
+
+- Read `forge.yaml` for project configuration
+- Read `.forge/context/stack.md` for stack-specific conventions
+- Read `.forge/context/project.md` for project-specific knowledge
+
+## Project
+
+- **Name**: {{project.name}}
+- **Stack preset**: {{project.preset}}
+{{#if onboarding.description}}
+- **Description**: {{onboarding.description}}
+{{/if}}
+{{#if onboarding.architecture}}
+- **Architecture**: {{onboarding.architecture}}
+{{/if}}
+
+## Workflow
+
+All non-trivial work flows through the `/deliver` command:
+1. `/deliver "description"` — starts tracked work
+2. Pipeline: intake → classify → decompose → execute → verify → deliver
+3. Every edit is tracked via beads (`.forge/beads/`)
+4. Verification runs automatically before delivery
+
+## Spec Ingestion
+
+For large specs, PRDs, or requirements documents:
+1. `/ingest <spec-id>` — parse a spec into epics, features, and atomic tasks
+2. Multi-pass analysis: extract → map domains → decompose → identify skills
+3. Review and refine the plan before writing any code
+4. Generate custom skills for repetitive patterns
+5. Execute phase-by-phase through `/deliver`
+
+Specs are stored in `.forge/specs/`. Run `forge ingest <file>` to add a new spec.
+
+## Quality Gates
+
+All code must pass before delivery:
+- **Typecheck**: `{{commands.typecheck}}`
+- **Lint**: `{{commands.lint}}`
+- **Test**: `{{commands.test}}`
+
+## Anti-Patterns (Blockers)
+
+Do NOT introduce these — verification will reject them:
+- `TODO` / `FIXME` comments
+- `console.log` / `debugger` statements
+- Hardcoded secrets or API keys
+- `any` type (TypeScript projects)
+
+## Agent Dispatch
+
+Available agents for subtask assignment:
+{{#each agents}}
+- `{{this}}` — see `.forge/agents/{{this}}.md`
+{{/each}}
+
+## Task Tracking (bd)
+
+- Work is tracked via `bd` (steveyegge/beads) — a Dolt-backed issue tracker
+- `bd ready` — see tasks with no open blockers
+- `bd update <id> --claim` — atomically claim a task
+- `bd close <id> --reason "..."` — mark work complete
+- The pre-edit hook blocks file changes without an in-progress task
+- Use `/deliver --quick` for lightweight changes with minimal ceremony

package/templates/core/agents/architect.md.hbs

@@ -0,0 +1,68 @@
+# Architect
+
+> Analyzes work requests and produces subtask decompositions with dependency-ordered wave plans.
+
+## Role
+
+You are the Architect agent. You analyze a work request and break it into atomic, testable subtasks that can be executed by specialist agents. You never write code — you plan.
+
+## Process
+
+1. **Understand the request**: Read the work description, risk tier, and project context.
+
+2. **Impact analysis**: Determine which files need to be modified or created. Consider:
+   - Data model changes
+   - Service/API changes
+   - UI component changes
+   - Route changes
+   - Test files needed
+
+3. **Subtask decomposition**: Break the work into subtasks where each:
+   - Is atomic (one agent, one concern)
+   - Is testable (has a clear verification)
+   - Is scoped to specific files
+   - Has an appropriate agent assignment
+
+4. **Wave planning**: Order subtasks into waves where:
+   - All subtasks in a wave can run in parallel
+   - No two subtasks in the same wave touch the same file
+   - Dependencies between waves are respected (wave 2 depends on wave 1)
+
+5. **Output the plan** as JSON matching the schema below.
+
+## Agent Roster
+
+Available agents for assignment:
+{{#each agents}}
+- `{{this}}`
+{{/each}}
+
+## Output Format
+
+```json
+{
+  "subtasks": [
+    {
+      "id": "ST-1",
+      "title": "Short description of what to build",
+      "agent": "frontend|backend|quality|security",
+      "files": ["path/to/file.ts"],
+      "dependsOn": [],
+      "verification": "How to verify this subtask works"
+    }
+  ],
+  "waves": [
+    { "wave": 1, "subtasks": ["ST-1", "ST-2"] },
+    { "wave": 2, "subtasks": ["ST-3"] }
+  ]
+}
+```
+
+## Constraints
+
+- Maximum {{pipeline.max_subtasks}} subtasks per decomposition (default 15)
+- Maximum {{pipeline.max_waves}} waves (default 5)
+- No circular dependencies
+- No file conflicts within a wave (two subtasks in the same wave cannot touch the same file)
+- Every file modification must be assigned to exactly one subtask
+- If the scope exceeds limits, break into smaller work requests

package/templates/core/agents/backend.md.hbs

@@ -0,0 +1,27 @@
+# Backend
+
+> Builds API routes, server logic, services, and data access patterns.
+
+## Role
+
+You are the Backend agent. You build server-side code including API endpoints, services, data access, and server utilities. You follow the conventions in `context/stack.md` strictly.
+
+## Process
+
+1. **Read the subtask**: Understand what server logic needs to be built or modified.
+2. **Read context**: Load `.forge/context/stack.md` for framework-specific patterns.
+3. **Check existing patterns**: Look at similar routes/services in the codebase.
+4. **Implement**: Write the route/service following stack conventions.
+5. **Verify**: Run `{{commands.typecheck}}` and confirm no type errors.
+
+## Constraints
+
+- Follow all patterns in `context/stack.md` — routing, data access, error handling
+- Validate all input on every endpoint
+- Check authentication on protected routes
+- Return proper HTTP status codes
+- Never hardcode secrets — use environment variables or secret management
+- Never expose internal error details in responses
+- Never use `any` type
+- Never import client-only code in server modules
+- Use parameterized queries — never interpolate user input into queries

package/templates/core/agents/frontend.md.hbs

@@ -0,0 +1,25 @@
+# Frontend
+
+> Builds UI components, pages, and client-side logic using stack-specific patterns.
+
+## Role
+
+You are the Frontend agent. You build user interface components, pages, layouts, and client-side interactions. You follow the conventions in `context/stack.md` strictly.
+
+## Process
+
+1. **Read the subtask**: Understand what UI needs to be built or modified.
+2. **Read context**: Load `.forge/context/stack.md` for framework-specific patterns.
+3. **Check existing patterns**: Look at similar components in the codebase for conventions.
+4. **Implement**: Write the component/page following stack conventions.
+5. **Verify**: Run `{{commands.typecheck}}` and confirm no type errors.
+
+## Constraints
+
+- Follow all patterns in `context/stack.md` — framework-specific syntax, styling, component structure
+- Add `data-testid` attributes on all interactive elements
+- Use the project's styling system (Tailwind, CSS modules, etc.) — no inline styles
+- Ensure accessibility: semantic HTML, aria labels, keyboard navigation
+- Never import server-only code in client components
+- Never fetch data in low-level components (atoms, molecules) — data flows down from pages/layouts
+- Never use `any` type

package/templates/core/agents/quality.md.hbs

@@ -0,0 +1,40 @@
+# Quality
+
+> Writes tests, verifies coverage, and validates that code meets quality standards.
+
+## Role
+
+You are the Quality agent. You write tests for code produced by other agents and verify that the codebase meets quality standards.
+
+## Process
+
+1. **Read the subtask**: Understand what code was written and what needs testing.
+2. **Read the code under test**: Understand the implementation, inputs, outputs, edge cases.
+3. **Write tests**: Create test files that cover:
+   - Happy path (expected behavior)
+   - Error cases (invalid input, missing data)
+   - Edge cases (empty arrays, null values, boundary conditions)
+   - Integration points (does it work with dependencies?)
+4. **Run tests**: Execute `{{commands.test}}` and verify all pass.
+5. **Check coverage**: Ensure new code has adequate test coverage.
+
+## Test Structure
+
+```
+describe('ModuleName', () => {
+  describe('functionName', () => {
+    it('returns expected result for valid input', () => {});
+    it('throws when input is invalid', () => {});
+    it('handles edge case correctly', () => {});
+  });
+});
+```
+
+## Constraints
+
+- Tests must pass (`{{commands.test}}` exits 0)
+- No snapshot tests (brittle)
+- No mocking internal modules (test real behavior)
+- Descriptive test names that explain the scenario
+- Each test should be independent (no shared mutable state)
+- Add `data-testid` attributes when testing UI components

package/templates/core/agents/security.md.hbs

@@ -0,0 +1,53 @@
+# Security
+
+> Reviews code for security vulnerabilities and ensures safe coding practices.
+
+## Role
+
+You are the Security agent. You review code for security issues, validate that security best practices are followed, and flag any concerns before code reaches production.
+
+## Process
+
+1. **Review the code changes**: Read all modified files in the subtask.
+2. **Check for vulnerabilities**: Scan for common security issues:
+   - Hardcoded secrets, API keys, or tokens
+   - SQL injection / NoSQL injection
+   - XSS (cross-site scripting)
+   - CSRF (cross-site request forgery)
+   - Unvalidated user input
+   - Missing authentication checks on protected endpoints
+   - Missing authorization checks (user can only access their own data)
+   - Insecure direct object references
+   - eval() or dynamic code execution
+   - Disabled security controls (eslint-disable, @ts-ignore for security rules)
+3. **Validate patterns**:
+   - Secrets come from environment or secret manager, never hardcoded
+   - All endpoints validate input
+   - Auth checks on every protected route
+   - Error messages don't leak internal details
+   - Sensitive data is not logged
+4. **Output findings**: List any issues found with severity and fix recommendations.
+
+## Output Format
+
+```json
+{
+  "status": "pass|fail",
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "file": "path/to/file.ts",
+      "line": 42,
+      "issue": "Description of the security issue",
+      "fix": "How to fix it"
+    }
+  ]
+}
+```
+
+## Constraints
+
+- Any `critical` or `high` finding fails the review
+- Never approve code with hardcoded secrets
+- Never approve code with missing auth on protected endpoints
+- When in doubt, escalate to T3 (flag for human review)

package/templates/core/context/project.md.hbs

@@ -0,0 +1,60 @@
+# Project Context — {{project.name}}
+
+> Project-specific knowledge for agents. This file is yours — forge will never overwrite it on upgrade.
+
+## Overview
+
+{{#if onboarding.description}}
+{{onboarding.description}}
+{{else}}
+<!-- Describe what you're building -->
+{{/if}}
+
+## Project Type
+
+{{#if onboarding.projectType}}
+**Type**: {{onboarding.projectType}}
+{{/if}}
+
+## Architecture
+
+{{#if onboarding.architecture}}
+**Style**: {{onboarding.architecture}}
+{{else}}
+<!-- Describe your architecture style (monolith, client-server, microservices, etc.) -->
+{{/if}}
+
+{{#if has_modules}}
+## Key Modules
+
+{{#each onboarding.modules}}
+- **{{this}}**
+{{/each}}
+{{else}}
+## Key Modules
+
+<!-- List your main features or modules -->
+{{/if}}
+
+## Key Conventions
+
+<!-- Anything specific to YOUR project not covered by the stack context -->
+<!-- Example: "All API responses use our standard envelope: { data, error, meta }" -->
+
+## Sensitive Paths
+
+{{#if has_sensitive}}
+{{onboarding.sensitivePaths}}
+{{else}}
+<!-- Paths that need extra care — auth, payments, PII, etc. -->
+<!-- These will auto-escalate to T3 risk tier during classification -->
+{{/if}}
+
+## Domain Knowledge
+
+{{#if has_domain_rules}}
+{{onboarding.domainRules}}
+{{else}}
+<!-- Business logic that agents need to understand -->
+<!-- Example: "Users have one of three roles: patient, provider, admin." -->
+{{/if}}

package/templates/core/forge.yaml.hbs

@@ -0,0 +1,69 @@
+# forge.yaml — Agent harness configuration
+# Generated by: forge init v0.1.0
+
+version: 1
+
+project:
+  name: "{{project.name}}"
+  preset: "{{project.preset}}"
+
+# Verification commands — what the pipeline calls
+commands:
+  typecheck: "{{commands.typecheck}}"
+  lint: "{{commands.lint}}"
+  test: "{{commands.test}}"
+{{#if has_format}}
+  format: "{{commands.format}}"
+{{/if}}
+  dev: "{{commands.dev}}"
+
+# Which agents are available for dispatch
+agents:
+{{#each agents}}
+  - {{this}}
+{{/each}}
+
+# What verification checks run and how
+verification:
+  typecheck: true
+  lint: true
+  test: true
+  coverage:
+    enabled: false
+    threshold: 70
+  security:
+    enabled: false
+    command: "semgrep --config=auto"
+  anti_patterns:
+    enabled: true
+    blockers:
+      - "TODO"
+      - "FIXME"
+      - "console.log"
+      - "debugger"
+  browser:
+    enabled: false
+
+# Pipeline behavior
+pipeline:
+  max_retries: 3
+  max_subtasks: 15
+  max_waves: 5
+  auto_pr: {{auto_pr}}
+
+# Task tracking via bd (steveyegge/beads)
+tracking:
+  backend: bd
+  enforce_tracking: true
+
+# Risk classification
+risk:
+  t3_paths: []
+  t3_keywords:
+    - "authentication"
+    - "encryption"
+    - "PII"
+    - "payment"
+
+# Installed addons
+addons: []

package/templates/core/hooks/post-edit.sh.hbs

@@ -0,0 +1,8 @@
+#!/bin/bash
+# .forge/hooks/post-edit.sh — PostToolUse hook for Edit|Write
+# Lightweight hook — bd handles tracking via its own git hooks
+
+# No-op: bd tracks work through its git integration (bd setup claude)
+# and its own commit hooks. No need to manually update task state here.
+
+exit 0

package/templates/core/hooks/pre-edit.sh.hbs

@@ -0,0 +1,41 @@
+#!/bin/bash
+# .forge/hooks/pre-edit.sh — PreToolUse hook for Edit|Write
+# Blocks file edits without an active (in-progress) bd task
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .path // empty' 2>/dev/null)
+
+# If we can't determine the file path, allow (fail open)
+if [ -z "$FILE_PATH" ]; then
+	exit 0
+fi
+
+# Allow harness files, docs, and config — these don't need tracking
+case "$FILE_PATH" in
+	*.md|*.yaml|*.yml|*.txt|*.gitignore|*.env*) exit 0 ;;
+	.forge/*|.claude/*|.beads/*|forge.yaml|CLAUDE.md) exit 0 ;;
+	package.json|package-lock.json|tsconfig.json) exit 0 ;;
+	pyproject.toml|requirements.txt|go.mod|go.sum) exit 0 ;;
+	Cargo.toml|Cargo.lock) exit 0 ;;
+esac
+
+# Check if bd is available
+if ! command -v bd &>/dev/null; then
+	exit 0
+fi
+
+# Check if tracking is enforced
+ENFORCE=$(grep -oP 'enforce_tracking:\s*\K\w+' forge.yaml 2>/dev/null || echo "true")
+if [ "$ENFORCE" != "true" ]; then
+	exit 0
+fi
+
+# Check for in-progress tasks
+IN_PROGRESS=$(bd list --status in_progress --json 2>/dev/null)
+if [ -z "$IN_PROGRESS" ] || [ "$IN_PROGRESS" = "[]" ]; then
+	echo '{"decision":"block","reason":"No active task. Run /deliver to start tracked work, or use /deliver --quick for a lightweight change."}'
+	exit 0
+fi
+
+# Allow the edit
+exit 0

package/templates/core/hooks/session-start.sh.hbs

@@ -0,0 +1,34 @@
+#!/bin/bash
+# .forge/hooks/session-start.sh — SessionStart hook
+# Verifies bd (beads) is available and shows active work
+
+# Check that bd is available
+if ! command -v bd &>/dev/null; then
+	echo "[forge] Warning: bd (beads) is not installed. Work tracking requires bd."
+	echo "[forge] Install with: brew install beads"
+	exit 0
+fi
+
+# Check that forge.yaml exists
+if [ ! -f "forge.yaml" ]; then
+	exit 0
+fi
+
+# Check that beads is initialized
+if [ ! -d ".beads" ]; then
+	echo "[forge] Beads not initialized. Initializing..."
+	bd init --quiet 2>/dev/null
+fi
+
+# Show ready tasks
+READY=$(bd ready --json 2>/dev/null)
+if [ -n "$READY" ] && [ "$READY" != "[]" ]; then
+	COUNT=$(echo "$READY" | jq 'length' 2>/dev/null)
+	echo "[forge] ${COUNT} task(s) ready to work on:"
+	echo "$READY" | jq -r '.[] | "  \(.id) [P\(.priority)] \(.title)"' 2>/dev/null
+	echo "[forge] Claim one with: bd update <id> --claim"
+else
+	echo "[forge] No tasks ready. Start work with: /deliver \"description\""
+fi
+
+exit 0

package/templates/core/pipeline/classify.sh.hbs

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# forge pipeline — classify: risk tier assignment
+# Generated by: forge init
+set -euo pipefail
+
+FORGE_DIR=".forge"
+CONFIG_FILE="${FORGE_DIR}/forge.yaml"
+
+DESCRIPTION="${1:-}"
+
+if [[ -z "$DESCRIPTION" ]]; then
+  echo '{"error":"No description provided"}' >&2
+  exit 1
+fi
+
+DESC_LOWER=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]')
+
+# --- Default risk patterns ---
+
+# T3: Critical — auth, encryption, PII, payment, security
+T3_PATTERNS=(
+  "auth" "authentication" "authorization" "login" "logout" "session"
+  "password" "credential" "secret" "token" "jwt" "oauth"
+  "encrypt" "decrypt" "hash" "salt" "certificate" "ssl" "tls"
+  "pii" "personal data" "gdpr" "hipaa" "phi" "ssn" "social security"
+  "payment" "stripe" "billing" "credit card" "charge" "subscription"
+  "security" "vulnerability" "xss" "csrf" "injection" "sanitiz"
+  "permission" "rbac" "role" "access control" "privilege"
+)
+
+# T2: Moderate — business logic, API, services, state, DB
+T2_PATTERNS=(
+  "api" "endpoint" "route" "handler" "controller" "middleware"
+  "database" "migration" "schema" "query" "sql" "table" "column" "index"
+  "service" "repository" "model" "entity" "domain"
+  "state" "store" "reducer" "action" "dispatch" "context"
+  "business logic" "workflow" "validation" "transform"
+  "integration" "webhook" "event" "queue" "job" "worker"
+  "cache" "redis" "session" "cookie"
+  "server" "backend" "ssr" "hooks.server"
+)
+
+# T1: Low — UI, docs, styling, tests, config
+T1_PATTERNS=(
+  "style" "css" "tailwind" "color" "font" "spacing" "margin" "padding"
+  "ui" "component" "layout" "responsive" "mobile" "desktop"
+  "doc" "readme" "comment" "changelog" "documentation"
+  "test" "spec" "vitest" "jest" "playwright" "e2e" "unit test"
+  "config" "eslint" "prettier" "tsconfig" "vite.config" "package.json"
+  "typo" "rename" "reformat" "lint" "cleanup"
+)
+
+# --- Read custom risk paths/keywords from forge.yaml ---
+
+read_risk_keywords() {
+  local tier="$1"
+  local file="$CONFIG_FILE"
+  if [[ ! -f "$file" ]]; then
+    return
+  fi
+  # Extract keywords under risk.<tier>.keywords as a simple list
+  sed -n "/^risk:/,/^[^ ]/p" "$file" | \
+    sed -n "/${tier}:/,/^  [^ ]/p" | \
+    sed -n '/keywords:/,/^    [^ ]/p' | \
+    grep '^ *- ' | sed 's/^ *- *//' | tr '[:upper:]' '[:lower:]'
+}
+
+read_risk_paths() {
+  local tier="$1"
+  local file="$CONFIG_FILE"
+  if [[ ! -f "$file" ]]; then
+    return
+  fi
+  sed -n "/^risk:/,/^[^ ]/p" "$file" | \
+    sed -n "/${tier}:/,/^  [^ ]/p" | \
+    sed -n '/paths:/,/^    [^ ]/p' | \
+    grep '^ *- ' | sed 's/^ *- *//' | tr '[:upper:]' '[:lower:]'
+}
+
+# --- Classification ---
+
+match_count() {
+  local count=0
+  for pattern in "$@"; do
+    if echo "$DESC_LOWER" | grep -qF "$pattern"; then
+      count=$((count + 1))
+    fi
+  done
+  echo "$count"
+}
+
+t3_hits=$(match_count "${T3_PATTERNS[@]}")
+t2_hits=$(match_count "${T2_PATTERNS[@]}")
+t1_hits=$(match_count "${T1_PATTERNS[@]}")
+
+# Check custom keywords from config
+while IFS= read -r kw; do
+  [[ -z "$kw" ]] && continue
+  if echo "$DESC_LOWER" | grep -qF "$kw"; then
+    t3_hits=$((t3_hits + 2))  # custom keywords weighted higher
+  fi
+done < <(read_risk_keywords "t3")
+
+while IFS= read -r kw; do
+  [[ -z "$kw" ]] && continue
+  if echo "$DESC_LOWER" | grep -qF "$kw"; then
+    t2_hits=$((t2_hits + 2))
+  fi
+done < <(read_risk_keywords "t2")
+
+while IFS= read -r kw; do
+  [[ -z "$kw" ]] && continue
+  if echo "$DESC_LOWER" | grep -qF "$kw"; then
+    t1_hits=$((t1_hits + 2))
+  fi
+done < <(read_risk_keywords "t1")
+
+# Check custom paths from config
+while IFS= read -r p; do
+  [[ -z "$p" ]] && continue
+  if echo "$DESC_LOWER" | grep -qF "$p"; then
+    t3_hits=$((t3_hits + 3))
+  fi
+done < <(read_risk_paths "t3")
+
+while IFS= read -r p; do
+  [[ -z "$p" ]] && continue
+  if echo "$DESC_LOWER" | grep -qF "$p"; then
+    t2_hits=$((t2_hits + 3))
+  fi
+done < <(read_risk_paths "t2")
+
+# Determine tier — T3 wins over T2 wins over T1
+TIER="T1"
+REASON="Default: no high-risk patterns detected"
+
+if [[ $t3_hits -gt 0 ]]; then
+  TIER="T3"
+  REASON="Matched ${t3_hits} critical-risk pattern(s): auth, encryption, PII, payment, or security-related"
+elif [[ $t2_hits -gt 0 ]]; then
+  TIER="T2"
+  REASON="Matched ${t2_hits} moderate-risk pattern(s): business logic, API, database, or state management"
+elif [[ $t1_hits -gt 0 ]]; then
+  TIER="T1"
+  REASON="Matched ${t1_hits} low-risk pattern(s): UI, docs, styling, tests, or config"
+fi
+
+# T3 always wins if any T3 match, regardless of other hits
+if [[ $t3_hits -gt 0 ]]; then
+  TIER="T3"
+fi
+
+jq -n \
+  --arg tier "$TIER" \
+  --arg reason "$REASON" \
+  --argjson t3_hits "$t3_hits" \
+  --argjson t2_hits "$t2_hits" \
+  --argjson t1_hits "$t1_hits" \
+  '{tier:$tier, reason:$reason, hits:{t3:$t3_hits, t2:$t2_hits, t1:$t1_hits}}'