@samahlstrom/forge-cli 0.1.0

package/templates/core/skill-creator.md.hbs

@@ -0,0 +1,151 @@
+---
+name: skill-creator
+description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
+---
+
+# Skill Creator
+
+A skill for creating new skills and iteratively improving them.
+
+At a high level, the process of creating a skill goes like this:
+
+- Decide what you want the skill to do and roughly how it should do it
+- Write a draft of the skill
+- Create a few test prompts and run claude-with-access-to-the-skill on them
+- Help the user evaluate the results both qualitatively and quantitatively
+- Rewrite the skill based on feedback from the user's evaluation of the results
+- Repeat until you're satisfied
+
+Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages.
+
+## Creating a skill
+
+### Capture Intent
+
+Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first.
+
+1. What should this skill enable Claude to do?
+2. When should this skill trigger? (what user phrases/contexts)
+3. What's the expected output format?
+4. Should we set up test cases to verify the skill works?
+
+### Interview and Research
+
+Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.
+
+### Write the SKILL.md
+
+Based on the user interview, fill in these components:
+
+- **name**: Skill identifier (kebab-case, max 64 chars)
+- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. Make descriptions slightly "pushy" to combat undertriggering.
+- **the rest of the skill**
+
+### Skill Writing Guide
+
+#### Anatomy of a Skill
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description required)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/    - Executable code for deterministic/repetitive tasks
+    ├── references/ - Docs loaded into context as needed
+    └── assets/     - Files used in output (templates, icons, fonts)
+```
+
+#### Progressive Disclosure
+
+Skills use a three-level loading system:
+1. **Metadata** (name + description) - Always in context (~100 words)
+2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
+3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)
+
+**Key patterns:**
+- Keep SKILL.md under 500 lines; if approaching this limit, add hierarchy with clear pointers
+- Reference files clearly from SKILL.md with guidance on when to read them
+- For large reference files (>300 lines), include a table of contents
+
+#### Writing Patterns
+
+Prefer using the imperative form in instructions.
+
+**Defining output formats:**
+```markdown
+## Report structure
+ALWAYS use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+```
+
+**Examples pattern:**
+```markdown
+## Commit message format
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+### Writing Style
+
+Try to explain to the model why things are important in lieu of heavy-handed MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples.
+
+### Test Cases
+
+After writing the skill draft, come up with 2-3 realistic test prompts. Share them with the user for review. Save test cases to `evals/evals.json`:
+
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's task prompt",
+      "expected_output": "Description of expected result",
+      "files": []
+    }
+  ]
+}
+```
+
+## Running and Evaluating Test Cases
+
+For each test case, spawn two subagents — one with the skill, one without. Launch everything at once.
+
+**With-skill run:**
+```
+Execute this task:
+- Skill path: <path-to-skill>
+- Task: <eval prompt>
+- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
+```
+
+**Baseline run** (same prompt, no skill, save to `without_skill/outputs/`).
+
+While runs are in progress, draft quantitative assertions for each test case. Good assertions are objectively verifiable and have descriptive names.
+
+## Improving the Skill
+
+1. **Generalize from the feedback.** Don't overfit to specific examples.
+2. **Keep the prompt lean.** Remove things that aren't pulling their weight.
+3. **Explain the why.** Explain the reasoning behind instructions so the model understands importance.
+4. **Look for repeated work across test cases.** If all test cases independently wrote similar scripts, bundle that script in `scripts/`.
+
+### The Iteration Loop
+
+1. Apply improvements to the skill
+2. Rerun all test cases into a new `iteration-<N+1>/` directory
+3. Wait for the user to review
+4. Read feedback, improve again, repeat
+
+Keep going until the user is satisfied or feedback is all empty.
+
+## Skill Location
+
+New skills should be created at: `.claude/skills/<skill-name>/SKILL.md`
+
+This project uses forge for orchestration. When creating skills for this project, place them in the standard Claude Code skills directory so they're automatically available via `/skill-name`.

package/templates/core/skill-deliver.md.hbs

@@ -0,0 +1,46 @@
+# deliver
+
+> Intake, classify, and execute tracked work through the forge pipeline.
+
+## Trigger
+
+User runs `/deliver <description>` or `/deliver --flag`
+
+## Process
+
+1. Run: `bash .forge/pipeline/orchestrator.sh <user-input>`
+2. Read the JSON output line. Branch on `status`:
+
+### PAUSE
+The pipeline needs LLM work.
+- Read the file at `prompt_file` for instructions
+- Read each context file listed in `context[]` from `.forge/context/`
+- Execute the work described in the prompt
+- Write your output to `output_file`
+- Run the `resume` command to continue the pipeline
+
+### HUMAN_INPUT
+The pipeline needs a user decision.
+- Present `question` and `options` to the user via AskUserQuestion
+- Get their answer (option index)
+- Run the `resume` command with their answer
+
+### DONE
+Pipeline complete.
+- Report: PR URL from `pr_url`, branch from `branch`, summary from `summary`
+
+### ERROR
+Pipeline failed.
+- Report: which `stage` failed, the `error` message
+- Point user to the debug file at `debug_file`
+- Suggest running the `action` command to retry
+
+3. After handling the JSON output, if another orchestrator call is needed (PAUSE resume), repeat from step 1 with the resume command.
+4. Continue until you receive DONE or ERROR.
+
+## Flags
+
+- `--quick` — Lightweight mode: skip decomposition, minimal verification
+- `--hotfix` — Fast-path: skip decomposition, auto T1, minimal checks
+- `--issue <N>` — Fetch GitHub issue as input
+- `--resume <id>` — Resume a halted or interrupted pipeline run

package/templates/core/skill-ingest.md.hbs

@@ -0,0 +1,245 @@
+---
+name: ingest
+description: Parse a spec document into a structured project plan with epics, features, and atomic tasks. Use when a user has a PRD, technical spec, or requirements document and wants to decompose it into executable work before writing code. Triggers on /ingest, or when user mentions ingesting a spec, parsing requirements, or planning from a document.
+---
+
+# ingest
+
+> Decompose a spec document into a structured project plan, generate custom skills, and execute phase-by-phase through the /deliver pipeline.
+
+## Trigger
+
+User runs `/ingest <spec-id>` where spec-id corresponds to a directory in `.forge/specs/`.
+
+## Process
+
+### Step 1: Load the spec
+
+1. Read `.forge/specs/<spec-id>/meta.json` to get source file path, format, page count, and chunk size
+2. If `.forge/specs/<spec-id>/analysis.json` exists, read it — this contains project metadata extracted during `forge init --spec`
+3. Read the source document at `.forge/specs/<spec-id>/source.*`
+   - For PDFs: read in chunks using the `pages` parameter (e.g., pages 1-20, then 21-40)
+   - For text/markdown: read the full file (or chunk by heading if very large)
+
+### Step 2: Multi-pass analysis
+
+Run four analysis passes. Each pass builds on the previous ones. Write outputs to `.forge/specs/<spec-id>/`.
+
+#### Pass 1: Structure Extraction
+
+Read the spec (chunk by chunk for large documents) and extract:
+
+- **Sections**: headings, hierarchy, page ranges
+- **Requirements**: SHALL/MUST/SHOULD statements with IDs
+- **User stories**: As a... I want... So that...
+- **Constraints**: performance, compliance, compatibility, security
+- **Data entities**: models, schemas, relationships
+- **Glossary**: domain-specific terms
+
+Write to: `.forge/specs/<spec-id>/pass-1-structure.json`
+
+For chunked documents: run pass 1 per chunk, then consolidate into a single pass-1-structure.json before proceeding.
+
+#### Pass 2: Domain Mapping
+
+Read pass-1 output. Identify:
+
+- **Domains/modules**: logical groupings (e.g., auth, billing, scheduling)
+- **Cross-references**: which sections feed which domains
+- **Dependency graph**: which domains depend on others
+- **Shared concerns**: cross-cutting things like logging, auth, multi-tenancy
+
+Write to: `.forge/specs/<spec-id>/pass-2-domains.json`
+
+#### Pass 3: Epic/Feature/Task Breakdown
+
+Read pass-1 + pass-2 outputs. Decompose into:
+
+- **Epics**: one per domain or major capability
+- **Features**: logical groupings within an epic (max 5 per epic)
+- **Tasks**: atomic units of work, each completable in a single `/deliver` call (max 8 per feature)
+
+Each task gets:
+- `id`: unique identifier (e.g., task-1-1-1)
+- `title`: what to do
+- `description`: detailed description with acceptance criteria
+- `risk_tier`: T1 (low), T2 (moderate), T3 (critical) — using the same classification as the pipeline
+- `dependencies`: list of task IDs that must complete first
+- `files_likely`: predicted files to create or modify
+- `agent`: which agent handles this (architect, backend, frontend, quality, security)
+
+Write to: `.forge/specs/<spec-id>/pass-3-breakdown.json`
+
+#### Pass 4: Skill Identification
+
+Read pass-3 output. Look for:
+
+- **Repeated patterns**: if "create CRUD for entity X" appears 4+ times, that's a skill
+- **Domain workflows**: complex multi-step processes that appear more than once
+- **Boilerplate patterns**: things like "add API endpoint with validation + tests + docs"
+
+For each identified skill:
+- `name`: kebab-case identifier
+- `description`: what it does and when to trigger
+- `pattern`: the repeated work it captures
+- `estimated_savings`: how many tasks it simplifies
+
+Write to: `.forge/specs/<spec-id>/pass-4-skills.json`
+
+### Step 3: Synthesize
+
+Combine all pass outputs into a single `spec.yaml`:
+
+```yaml
+version: 1
+spec_id: "<id>"
+status: "draft"
+summary: "<1-2 sentence project summary>"
+
+domains:
+  - id: "dom-<name>"
+    name: "<Domain Name>"
+    dependencies: ["dom-<other>"]
+
+epics:
+  - id: "epic-<N>"
+    domain: "dom-<name>"
+    title: "<Epic title>"
+    features:
+      - id: "feat-<N>-<M>"
+        title: "<Feature title>"
+        tasks:
+          - id: "task-<N>-<M>-<K>"
+            title: "<Task title>"
+            description: "<Detailed description>"
+            risk_tier: "T1|T2|T3"
+            dependencies: []
+            files_likely: []
+            agent: "backend|frontend|quality|security"
+
+execution_plan:
+  phases:
+    - id: "phase-<N>"
+      name: "<Phase name>"
+      epics: ["epic-<N>"]
+      rationale: "<Why this phase comes here>"
+      parallelizable: true|false
+
+  total_tasks: <count>
+  critical_path: ["task-...", "task-..."]
+
+generated_skills: ["skill-name-1", "skill-name-2"]
+
+constraints:
+  - "<Hard constraint from the spec>"
+```
+
+Write to: `.forge/specs/<spec-id>/spec.yaml`
+
+### Step 4: Review Gate
+
+Present the plan to the user. Show:
+
+```
+Spec Analysis Complete
+═══════════════════════
+
+  Domains:       6
+  Epics:         8
+  Features:      31
+  Tasks:         52
+  Phases:        4
+  Custom skills: 4
+  Risk profile:  23 T3, 18 T2, 11 T1
+
+  Phase 1 — Foundation
+    <epics and task count>
+
+  Phase 2 — Core Features
+    <epics and task count>
+
+  ...
+
+  Constraints:
+    • <constraint 1>
+    • <constraint 2>
+
+  Custom skills to generate:
+    • <skill-1>: <what it does>
+    • <skill-2>: <what it does>
+```
+
+Ask: **Approve, refine, or cancel?**
+
+### Step 5: Refinement (if needed)
+
+If the user wants changes:
+1. Take their feedback as natural language
+2. Re-run the affected passes with the feedback as additional context
+3. Update spec.yaml
+4. Return to the review gate
+
+Common refinement requests:
+- "Split epic X into two epics"
+- "Move module Y to an earlier phase"
+- "Add a constraint about Z"
+- "This task is too big, break it down further"
+- "Remove the reporting module, that's out of scope"
+
+Loop until the user approves.
+
+### Step 6: Generate Skills
+
+After approval, for each skill identified in pass-4:
+
+1. Create `.claude/skills/<skill-name>/SKILL.md` with proper frontmatter
+2. Write the skill body with:
+   - Step-by-step instructions specific to this project's stack
+   - References to project context files
+   - Output format expectations
+   - Examples from the spec
+
+Use the `/skill-creator` skill's patterns for writing good skill files.
+
+### Step 7: Execution Handoff
+
+After skills are generated, present the execution plan:
+
+```
+Ready to execute. How would you like to proceed?
+
+  1. Phase-by-phase (recommended) — execute one phase at a time with review gates
+  2. Full auto — execute all phases sequentially
+  3. Manual — I'll run /deliver for individual tasks myself
+```
+
+**Phase-by-phase mode** (recommended):
+- For each phase, iterate through its epics and tasks in dependency order
+- For each task, construct a `/deliver` call with the task's description from spec.yaml
+- After each phase completes, update spec.yaml status and ask user to review before next phase
+- Parallelizable phases: tasks without inter-dependencies can be delivered concurrently via subagents
+
+**Constructing deliver calls from spec.yaml tasks**:
+```
+/deliver "<task.title> — <task.description>. Target files: <task.files_likely>. Risk: <task.risk_tier>. Spec ref: <task.id>"
+```
+
+### Resuming
+
+If the session is interrupted, the user can run `/ingest <spec-id>` again. Check `spec.yaml` status:
+- `pending-analysis`: start from pass 1
+- `draft`: show the review gate
+- `approved`: resume skill generation or execution
+- `in-progress`: find the last completed phase and resume from the next one
+
+## Output Protocol
+
+All intermediate outputs go to `.forge/specs/<spec-id>/`:
+- `meta.json` — source file metadata
+- `analysis.json` — project metadata from init
+- `pass-1-structure.json` — extracted structure
+- `pass-2-domains.json` — domain mapping
+- `pass-3-breakdown.json` — epic/feature/task breakdown
+- `pass-4-skills.json` — identified skills
+- `spec.yaml` — the final synthesized plan
+- `refinement-log.json` — history of user refinements

package/templates/presets/go/stack.md.hbs

@@ -0,0 +1,133 @@
+# Stack Context: Go
+
+## Tech Stack
+
+- **Language**: Go 1.22+
+- **Modules**: Go modules
+- **Testing**: `go test` (standard library)
+- **Linting**: golangci-lint
+- **Formatting**: gofmt (enforced)
+
+## Project Structure
+
+```
+cmd/
+  server/
+    main.go               # Entry point
+internal/
+  handler/                # HTTP handlers
+    user.go
+    user_test.go
+  service/                # Business logic
+    user.go
+    user_test.go
+  repository/             # Data access
+    user.go
+    user_test.go
+  model/                  # Domain types
+    user.go
+  middleware/              # HTTP middleware
+    auth.go
+    logging.go
+  config/                 # Configuration
+    config.go
+pkg/                      # Public packages (if any)
+```
+
+## Key Patterns
+
+### Handler Structure
+```go
+type UserHandler struct {
+    service *service.UserService
+}
+
+func NewUserHandler(svc *service.UserService) *UserHandler {
+    return &UserHandler{service: svc}
+}
+
+func (h *UserHandler) Create(w http.ResponseWriter, r *http.Request) {
+    var input model.CreateUserInput
+    if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
+        http.Error(w, "invalid request body", http.StatusBadRequest)
+        return
+    }
+
+    user, err := h.service.Create(r.Context(), input)
+    if err != nil {
+        // Handle specific error types
+        http.Error(w, err.Error(), http.StatusInternalServerError)
+        return
+    }
+
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(http.StatusCreated)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+### Error Handling
+- Return errors, don't panic
+- Wrap errors with context: `fmt.Errorf("create user: %w", err)`
+- Use sentinel errors for known conditions
+- Check errors immediately after function calls
+
+### Interfaces
+- Define interfaces where they are USED, not where they are implemented
+- Keep interfaces small (1-3 methods)
+- Accept interfaces, return structs
+
+### Testing
+```go
+func TestUserService_Create(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   model.CreateUserInput
+        want    *model.User
+        wantErr bool
+    }{
+        {
+            name:  "valid input",
+            input: model.CreateUserInput{Name: "Alice", Email: "alice@example.com"},
+            want:  &model.User{Name: "Alice", Email: "alice@example.com"},
+        },
+        {
+            name:    "empty name",
+            input:   model.CreateUserInput{Name: "", Email: "alice@example.com"},
+            wantErr: true,
+        },
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            // test implementation
+        })
+    }
+}
+```
+
+### Context Propagation
+- Pass `context.Context` as first parameter to all functions that do I/O
+- Use context for cancellation, timeouts, and request-scoped values
+- Never store context in structs
+
+### Dependency Injection
+- Use constructor injection (NewXxx functions)
+- Wire dependencies in `main.go`
+- No DI frameworks — keep it simple
+
+## Anti-Patterns
+
+- Never use `interface{}` or `any` without strong reason
+- Never ignore errors (`_ = someFunc()`)
+- Never use `init()` for complex logic
+- Never use package-level mutable state
+- Never use `panic` for expected errors
+- Never use `*` imports (dot imports)
+- Never hardcode secrets — use environment variables
+
+## Quality Gates
+
+- `go vet ./...` — Static analysis
+- `golangci-lint run` — Comprehensive linting
+- `go test ./...` — Tests
+- `gofmt -w .` — Formatting (enforced)

package/templates/presets/python-fastapi/stack.md.hbs

@@ -0,0 +1,101 @@
+# Stack Context: FastAPI + Python
+
+## Tech Stack
+
+- **Framework**: FastAPI
+- **Language**: Python 3.11+
+- **Validation**: Pydantic v2
+- **ORM**: SQLAlchemy 2.0 (async)
+- **Testing**: pytest + pytest-asyncio
+- **Linting**: ruff
+- **Type checking**: mypy or pyright
+
+## Project Structure
+
+```
+src/
+  main.py                 # FastAPI app creation + router mounting
+  config.py               # Settings via pydantic-settings
+  routers/                # API route modules
+    users.py
+    items.py
+  models/                 # SQLAlchemy models
+    user.py
+    item.py
+  schemas/                # Pydantic request/response models
+    user.py
+    item.py
+  services/               # Business logic
+    user_service.py
+  dependencies/           # FastAPI dependencies (DI)
+    auth.py
+    database.py
+  middleware/              # Custom middleware
+tests/
+  conftest.py             # Fixtures
+  test_users.py
+  test_items.py
+```
+
+## Key Patterns
+
+### Route Structure
+```python
+from fastapi import APIRouter, Depends, HTTPException, status
+from ..schemas.user import UserCreate, UserResponse
+from ..services.user_service import UserService
+from ..dependencies.auth import get_current_user
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    data: UserCreate,
+    service: UserService = Depends(),
+    current_user = Depends(get_current_user),
+):
+    return await service.create(data)
+```
+
+### Pydantic Models (v2)
+```python
+from pydantic import BaseModel, Field, ConfigDict
+
+class UserCreate(BaseModel):
+    model_config = ConfigDict(strict=True)
+    name: str = Field(min_length=1, max_length=100)
+    email: str = Field(pattern=r'^[\w.-]+@[\w.-]+\.\w+$')
+```
+
+### Dependency Injection
+- Use `Depends()` for all shared logic (auth, DB sessions, services)
+- Never create DB sessions manually — inject via dependency
+- Keep dependencies small and composable
+
+### Database Sessions
+```python
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        yield session
+```
+
+### Error Handling
+- Use `HTTPException` with proper status codes
+- Never expose internal error details to clients
+- Log errors with structured logging
+
+## Anti-Patterns
+
+- Never use `Any` type — always type hints
+- Never use raw SQL — use SQLAlchemy ORM or `text()` with parameters
+- Never hardcode secrets — use `pydantic-settings` with env vars
+- Never use `*` imports
+- Never use mutable default arguments
+- Never use `global` variables for state
+
+## Quality Gates
+
+- `mypy .` — Type checking
+- `ruff check .` — Linting
+- `pytest` — Tests
+- `ruff format .` — Formatting