Spaces:

hjerpe
/

sql_env

Running

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)

# 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:

{
  "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

# 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.

# 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):

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

Manual Workflow:

fan-out creates sibling clones, each on a feat/F###-slug branch
User runs opencode-ctx ralph start <spec> (or manual implementation) in each clone
fan-in runs trial merges to detect conflicts and suggests merge order
User merges per-feature PRs in the suggested order
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

# 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

OpenCode Workflow Handbook

Pipeline (What Comes Next)

Delegation Brief (Required)