<!-- handbook:ref cli opencode-ctx ralph run -->
<!-- handbook:ref cli opencode-ctx ralph start -->
<!-- handbook:ref cli opencode-ctx ralph spec -->
<!-- handbook:ref cli opencode-ctx ralph review -->

# OpenCode Workflow Handbook

Short, terminal-friendly map of the agentic workflow.

Assets discovered from: /Users/hjerp/.config/opencode

## Pipeline (What Comes Next)

## Delegation Brief (Required)

For any non-trivial work (anything you would normally put in a ticket/PRD), start with a short **Delegation Brief**.

This is the invariant "front page" that gets carried through discovery, delivery, and implementation so agents do not drift.

Minimum fields:

```text
Objective (what + why):
Deliverables (artifacts/capabilities):
In scope / Out of scope (non-goals):
Boundaries (authority + constraints):
Checkpoints (when to show work / ask):
Acceptance checks (how we know it's done):
```

How it glues into the existing workflow:

- `strategy` strengthens Objective/why (when the why is unclear or long-horizon).
- `discovery` turns Objective into validated scope + taste, and sharpens Acceptance checks.
- `delivery-spec` turns Deliverables/Boundaries into an engineering handoff.
- `design-doc` records decision rationale when the "how" has meaningful options.
- `autocode-implementation-planner` encodes the brief as **Core Intent (Immutable)** in the implementation spec, then uses the information barrier to generate independent verification.

**Note:** `strategy` is optional — use it when the "why" matters as much as the "what" (methodologies, frameworks, platforms). Most projects start at `discovery`.

```
[delegation brief] -> [strategy] -> discovery -> delivery-spec -> design-doc
      |            |            |            |
      v            v            v            v
   vision      validate     scope+handoff   decisions
  (optional)   +taste

architecture -> autocode-implementation-planner -> verification-planner -> execution loop
      |                    |                      |                   |
      v                    v                      v                   v
 system map        IMPLEMENTATION_SPEC.md   VERIFICATION_SPEC.md   build/review/verify
```

## When to Create Which Doc

| Complexity | Product Spec? | Design Doc? | Start With |
|------------|---------------|-------------|------------|
| **Simple** (CRUD, config) | Skip | Skip | `autocode-implementation-planner` |
| **Standard** (new feature) | Recommended | Optional | `discovery` skill → implementation planner |
| **Complex** (multi-system) | Required | Required | `discovery` → `delivery-spec` → design doc → implementation planner |
| **Exploratory** (unknown) | Skip | Skip | `prototype` skill first |

**Decision criteria:**
- Create **discovery** doc when stakeholders need to agree on scope
- Create **design-doc** when architecture decisions need to be recorded
- Skip both for tactical work that doesn't need alignment

## Where Artifacts Live

- vision/ = project philosophy (optional, for methodologies/frameworks) [explanation]
- docs/ = durable knowledge, organized by Diataxis type:
  - docs/guides/ = how-to procedures [how-to]
  - docs/design-docs/ = decision rationale [explanation]
  - docs/discovery/ = problem validation + taste [explanation]
  - docs/delivery-specs/ = engineering handoff [reference]
  - docs/references/ = external docs for agents [reference]
  - docs/exploration/ = ideas, scratchpad [exploration]
  - docs/learnings/ = durable patterns [reference]
  - docs/DOCS_TAXONOMY.md = where to put new docs
- specs/ = per-slice execution artifacts (FEATURES.json, impl specs, verification specs, CLARIFICATION_QUESTIONS.md (optional))

**Architecture lives in `docs/ARCHITECTURE.md`** — it's durable system knowledge, not a per-feature artifact.

## Architecture: One File, Multiple Tools

**Canonical location:** `docs/ARCHITECTURE.md`

All architecture tools output to the same file:

| Tool | Purpose |
|------|---------|
| `architecture` skill | Create NEW architecture (greenfield, redesign) |
| `codebase-onboarding` skill | Understand EXISTING architecture |
| `opencode-ctx docs architecture apply` | Refresh auto-managed snapshot |
| `/update-architecture-diagram` | Quick diagram refresh |

**Workflow:**
- Joining existing project → `codebase-onboarding` first
- Building new system → `architecture` skill
- Regular maintenance → `opencode-ctx docs architecture apply`

**Keep it fresh:**
- Human-curated sections: coarse (5-10 boxes, 2-4 key flows)
- Auto-managed snapshot: refresh with `opencode-ctx docs architecture apply`
- CI gate: `opencode-ctx docs architecture check`

## What To Run (Typical Flow)

- Start by writing (or asking the agent to draft) a Delegation Brief (required for significant work).
- To draft a Delegation Brief as a reusable artifact: use `delegation-brief`.
- If you are unsure what doc to write: use `triage`.
- To generate "what to build next" ideas from a codebase or product: use `ideation`.
- To capture project philosophy (rare): use `strategy` or create `vision/VISION.md` manually.
- To set direction for a longer horizon: use `strategy`.
- To validate and capture taste for a feature: use `discovery`.
- To hand off a concrete solution: use `delivery-spec`.
- To record architectural decisions: use `design-doc`.
- To map shared components across features: use `architecture`.
- To plan implementation with verification barrier: use `autocode-implementation-planner`.

- To inject baseline guardrails into `AGENTS.md`: `opencode-ctx guidelines apply --packs <lang>,testing,delivery-safety --file AGENTS.md`

**Vision vs Discovery:**
- Vision = enduring project philosophy (rare, for methodologies/frameworks)
- Discovery = feature-specific validation and taste capture (common)

| Use Vision When... | Use Discovery When... |
|--------------------|----------------------|
| The project IS a methodology or framework | You're validating a specific feature idea |
| Philosophy needs to persist across many features | The "why" is feature-specific |
| Multiple contributors need philosophical alignment | Taste capture is per-feature |
| The project will evolve over years | The project is < 6 months |

**Lightweight vision alternative:** Add a "Vision" section to README.md (2-3 paragraphs) instead of a full `vision/` directory.

Then build + ship with commands:

- /autocode-next-step (implement next spec step)
- /feature-demo F### (generate executable demo proving the feature works — auto-runs at loop end)
- /review-changes (auto-review)
- /commit-push-pr (commit, push, PR)
- /techdebt (tech debt scan)

For hands-free loops (optional):

- `opencode-ctx ralph start <spec>` (start server + browser + autonomous loop + cleanup)
- `opencode-ctx ralph run <spec>` (autonomous implement loop)
- `opencode-ctx ralph spec <spec>` (iterative spec refinement)
- `opencode-ctx ralph review` (review/fix bounded loop)

Common options: `-m MODEL` (alias: sonnet, opus, gpt-builder), `--max-iter N`

## Full Workflow (Complex Features)

```
0. Delegation Brief (required for significant work)
   └─→ docs/delegation-briefs/<feature>.md      # delegation-brief skill

1. Discovery (taste capture + problem validation)
   └─→ docs/discovery/<feature>.md            # discovery skill
   └─→ docs/discovery/<feature>.json          # Machine-readable taste data

1b. Delivery spec (engineering handoff - optional for simple features)
   └─→ docs/delivery-specs/<feature>.md       # delivery-spec skill

2. Design doc (architectural decisions)
   └─→ docs/design-docs/<feature>.md          # design-doc skill (ADR-style)

3. Feature planning (multi-feature projects)
   └─→ specs/FEATURES.json                    # autocode-plan-features skill

4. Implementation planning (reads taste from step 1)
   └─→ specs/F001-IMPLEMENTATION_SPEC.md      # autocode-implementation-planner skill
   └─→ specs/F001-VERIFICATION_SPEC.md        # Auto-generated

5. Execution
    └─→ /autocode-next-step                    # Or: opencode-ctx ralph start <spec>

6. Knowledge extraction (automatic)
   └─→ docs/learnings/*.md                    # compound-engineer at finalization
```

**Taste flows through the pipeline:**
- `discovery` captures delights, frustrations, feeling
- `delivery-spec` (optional) translates to functional requirements
- `autocode-implementation-planner` reads taste JSON and uses as success criteria
- Verification checks implementation against captured taste

## Quick Workflow (Simple Features)

```bash
# Plan directly
skill({ name: "autocode-implementation-planner" })

# Execute
/autocode-next-step
# Or autonomous: opencode-ctx ralph start <spec>

# Review and ship
/review-changes
/commit-push-pr
```

## Linking Docs to Features (FEATURES.json)

When using `FEATURES.json`, link to related documentation:

```json
{
  "id": "F001",
  "name": "User Authentication",
  "docs": {
    "discovery_json": "docs/discovery/auth.json",
    "discovery_md": "docs/discovery/auth.md",
    "delivery_spec": "docs/delivery-specs/auth.md",
    "design_doc": "docs/design-docs/auth-system.md"
  },
  "specs": {
    "implementation": "specs/F001-IMPLEMENTATION_SPEC.md",
    "verification": "specs/F001-VERIFICATION_SPEC.md"
  }
}
```

The `autocode-implementation-planner` skill automatically checks each linked doc and uses it as context.

## AGENTS.md Convention

AGENTS.md is a **navigation map**, not an encyclopedia:

- ~60-80 lines
- Links to docs/ for details
- No inline learnings (those go in `docs/learnings/`)
- Injectable guidelines via `<!-- GUIDELINES-BEGIN/END -->`

```bash
# Apply or update language guidelines (idempotent)
opencode-ctx guidelines apply --packs python,testing,delivery-safety --file AGENTS.md

# Frontend projects
opencode-ctx guidelines apply --packs frontend,testing,delivery-safety --file AGENTS.md

# Preview without writing
opencode-ctx guidelines apply --packs python,testing,delivery-safety --file AGENTS.md --dry-run
```

Available packs: `python`, `testing`, `frontend`, `delivery-safety`

## Parallel Feature Development (Fan-Out / Fan-In)

When a project has multiple independent features to implement, use the
parallel workflow to create isolated clones for each, then merge back safely.

```bash
# Plan: AI-assisted analysis of which features can run in parallel
opencode-ctx parallel plan                           # analyze FEATURES.json + specs
opencode-ctx parallel plan --status ready            # filter by status
opencode-ctx parallel plan --format json             # machine-readable output

# Fan-out: create parallel clones for features
opencode-ctx parallel fan-out                        # reads FEATURES.json (planned/ready)
opencode-ctx parallel fan-out --features F001,F002   # explicit feature list
opencode-ctx parallel fan-out --from-local           # clone from local (faster)

# Status: check all parallel clones
opencode-ctx parallel status
opencode-ctx parallel status --format json

# Work in each clone independently
cd ../repo-F001-auth-system
opencode-ctx ralph start specs/F001-IMPLEMENTATION_SPEC.md

# Fan-in: pre-merge conflict analysis
opencode-ctx parallel fan-in                         # trial merge against main
opencode-ctx parallel fan-in --format json

# Cleanup: remove clones after merging
opencode-ctx parallel cleanup F001
opencode-ctx parallel cleanup --all --force
```

**AI-Orchestrated Workflow (recommended):**
1. Use `/parallel-plan` command — analyzes implementation specs for file overlaps
   and dependencies, recommends parallelizable batches, asks for confirmation
2. On confirmation, automatically calls `fan-out` for the batch
3. User runs `opencode-ctx ralph start <spec>` (or manual implementation) in each clone
4. Use `parallel-orchestrator` agent to monitor progress and coordinate merges
5. `fan-in` runs trial merges; orchestrator generates a merge playbook
6. User merges per-feature PRs in the suggested order
7. `cleanup` removes clones after merge

**Manual Workflow:**
1. `fan-out` creates sibling clones, each on a `feat/F###-slug` branch
2. User runs `opencode-ctx ralph start <spec>` (or manual implementation) in each clone
3. `fan-in` runs trial merges to detect conflicts and suggests merge order
4. User merges per-feature PRs in the suggested order
5. `cleanup` removes clones after merge

The `plan` command reads Section 2 (Change Manifest) from implementation specs to
extract file lists, computes pairwise file overlaps, and partitions features into
conflict-free batches. Fan-in respects feature dependencies from FEATURES.json
and orders clean merges before conflicting ones.

## Maintenance Commands

```bash
# Keep the architecture snapshot current
opencode-ctx docs architecture apply     # refresh auto-managed snapshot
opencode-ctx docs architecture check     # CI gate

# Keep the FEATURES.json schema current (multi-feature projects)
opencode-ctx features schema apply       # creates specs/schemas/autocode-features-v1.schema.json
opencode-ctx features schema check       # CI gate
opencode-ctx features schema apply --dry-run

# Validate docs structure
opencode-ctx docs validate
```

## Global Configuration

Additional commands, agents, and skills are in `/Users/hjerp/.config/opencode`:

| Path | Contents |
|------|----------|
| `AGENTS.md` | Global workflow policies |
| `commands/` | Slash commands (`/autocode-*`, `/review-*`, etc.) |
| `agents/` | Specialized agents (planner, reviewer, executor, etc.) |
| `skills/` | Product planning skills (strategy, discovery, delivery-spec, etc.) |
| `scripts/` | Automation scripts (legacy, deprecated — use `opencode-ctx ralph`) |

## Skills (Discovered)

| Skill | Description |
|---|---|
| `ai-adoption-engagement` | Run an end-to-end AI adoption consulting engagement: scoping, current-state maturity di... |
| `ai-strategy` | Plan, evaluate, and iteratively update AI implementation strategy for an organization o... |
| `architecture` | Create lightweight system architecture establishing shared understanding across feature... |
| `autocode-implementation-planner` | Research and plan software changes with structured verification handoff. Orchestrates s... |
| `autocode-plan-features` | Create machine-parseable feature lists for multi-feature projects. Generates FEATURES.j... |
| `causal-driver` | Build causal driver trees for any metric — separate accounting identities from causal h... |
| `checkpoint-protocol` | Structured human checkpoint protocol that minimizes evaluation overhead. Transforms 're... |
| `codebase-onboarding` | Rapidly understand an unfamiliar codebase by generating a structured overview with ASCI... |
| `communication` | Craft compelling communication for stakeholders. Covers storytelling frameworks, persua... |
| `core-web-vitals` | Optimize Core Web Vitals (LCP, INP, CLS) for better page experience and search ranking.... |
| `delegation-brief` | Create a short delegation contract (objective, deliverables, boundaries, checkpoints, a... |
| `delivery-spec` | Create delivery specs that define solutions for engineers and AI agents (Phase 3). Use... |
| `design-doc` | Record architectural decisions with rationale (ADR-style). Captures WHY decisions were... |
| `discovery` | Validate and prioritize product ideas using PR/FAQ, Opportunity Solution Trees, Taste C... |
| `execution` | Translate PRDs into user stories with acceptance criteria (Phase 4). Use when: (1) Engi... |
| `frameworks` | Reusable frameworks, checklists, and templates (a lightweight reference library). Use w... |
| `frontend-builder` | LLM-optimized frontend implementation guidance. Use when: (1) Starting new frontend pro... |
| `ideation` | Generate structured 'what to build next' candidates from a codebase or product using th... |
| `landscape-scan` | Competitive intelligence for company building and investment diligence. Maps the full c... |
| `ml-concept-eval` | Evaluate an ML/statistical technique against a specific business context: is it viable,... |
| `peer-collaboration` | Coordinate volunteer or peer teams without formal authority. Use when: (1) Working with... |
| `principal-ml-engineer` | Principal ML engineer playbook: design ML/LLM systems that are reliable, observable, ex... |
| `project-leadership` | Adaptive project leadership for competitions, research, coursework, ventures, and deliv... |
| `prototype` | Rapid exploratory prototyping to resolve ambiguity and validate ideas before committing... |
| `sector-primer` | Rapid industry understanding for consultants and investors. Produces a structured Indus... |
| `seo` | Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "op... |
| `spec-staff-review` | Deliberate quality review of implementation specs by a staff engineer persona. Use for... |
| `strategic-thinker` | Guide users through strategic thinking using the Strategy Kernel framework. Facilitates... |
| `strategy` | Create product vision boards and outcome-based roadmaps (Phase 0-1). Use when: (1) Annu... |
| `team-lead` | Reference skill for team leadership principles: coaching, feedback, delegation. Use whe... |
| `triage` | Guide users through product planning workflow and select the right documentation (Triag... |
| `visual-artifacts` | Create professional visual artifacts: diagrams (Mermaid, Excalidraw) and presentations... |
| `web-performance` | Optimize web performance for faster loading and better user experience. Use when asked... |
| `web-security` | Apply modern web security best practices including CSP, HTTPS, XSS prevention, and depe... |
| `what-how-alignment` | System-level alignment between intent (what) and implementation (how). Analyzes complet... |

## Commands (Discovered)

| Command | Agent | Description |
|---|---|---|
| `/autocode-fix-from-review` | `executor` | Apply fixes from review report and run verification |
| `/autocode-fix-verification` | `verifier` | Fix features marked complete without proper verification evidence |
| `/autocode-next-step` | `executor` | Execute the next implementation step with verification |
| `/autocode-refine-spec` | `reviewer` | Iteratively refine an implementation spec before verification planning |
| `/autocode-verification-planner` | `verification-planner` | Generate verification criteria from sanitized spec |
| `/commit-push-pr` | `executor` | Commit, Push, and Create Pull Request |
| `/feature-demo` | `feature-demo` | Generate an executable demo document for a completed feature |
| `/full-web-audit` | `executor` | Comprehensive web quality audit (performance, accessibility, SEO, security) |
| `/parallel-plan` | `parallel-orchestrator` | Analyze FEATURES.json and plan parallelizable feature batches |
| `/review-changes` | `reviewer` | Review changes before commit or PR |
| `/review-frontend` | `frontend-reviewer` | Visual review of running frontend via Playwright MCP |
| `/techdebt` | `reviewer` | Analyze code for technical debt, duplications, and AI slop patterns |
| `/update-architecture-diagram` | `executor` | Refresh the System Diagram in ARCHITECTURE.md to match current codebase |
| `/update-model-routing` | `executor` | Refresh model routing recommendations with current pricing from models.dev |
| `/validate-spec` | `verifier` | Check if implementation matches spec; report discrepancies |

## Ralph CLI (Autonomous Loops)

| Command | Purpose |
|---------|---------|
| `opencode-ctx ralph start <spec>` | Start server + browser + run loop + cleanup (all-in-one) |
| `opencode-ctx ralph run <spec>` | Run implementation loop (attach to existing server with `-s`) |
| `opencode-ctx ralph spec <spec>` | Iterative spec refinement (default: 3 iterations) |
| `opencode-ctx ralph review` | Review + fix loop on current changes |

Common options: `-m MODEL` (aliases: sonnet, opus, gpt-builder), `--max-iter N`

## Scripts (Discovered — legacy, prefer `opencode-ctx ralph`)

| Script | Description |
|---|---|
| `cleanup-feature.sh` | Remove a parallel feature clone |
| `learnings.sh` | Query learnings (AGENTS.md or docs/LEARNINGS) |
| `parallel-feature.sh` | Create isolated clone for parallel feature development |
| `ralph-loop.sh` | ┌─────────────────────────────────────────────────────────────────────────┐ |
| `ralph-review-loop.sh` | ┌─────────────────────────────────────────────────────────────────────────┐ |
| `ralph-spec-loop.sh` | ┌─────────────────────────────────────────────────────────────────────────┐ |
| `update-model-routing.sh` | Fetch model pricing from models.dev and generate routing tables |