Skip to content

FEATURES.md

Latest commit

 

History

History
728 lines (540 loc) · 64 KB

FEATURES.md

File metadata and controls

728 lines (540 loc) · 64 KB
Raw

Features

This document describes what every agent, skill, reference document, and tool in this repo is for. Use it as a catalog — if you want to know how to use them, see USERGUIDE.md instead.

Table of contents

Agents

Every agent lives in agents/<name>.md or a subdirectory (agents/security/, agents/code-review/, agents/performance/, agents/sdlc/onboard/). All agents share: frontmatter, "how you think" section, progress announcements, micro-step execution, phase-by-phase workflow, orchestrator + --phase sub-task mode, confidence gate-loop, and verifier-isolation clause.

Micro-agent pattern: coordinator dispatches → each specialist writes its own output file → coordinator synthesizes. One agent = one job = one context window. Parallel waves use PARALLEL_WAVE_PROTOCOL.md (Round 1: code HANDOFFs, Round 2: review HANDOFFs, Round 3: runtime HANDOFFs).

Execution modes (all long-running agents):

  • Orchestrator mode (default) — announces phase plan, spawns one task(agent=self, prompt="--phase: N name ...") per phase. Each sub-task writes findings to docs/work/<agent>/<slug>/phaseN.md and returns in under 90 s.
  • --phase: N name mode — runs exactly one named phase, reads the previous phase output, writes its own. No sub-spawning. Used for parallelism.

Primary agents

sdlc-lead — Program manager & lead architect (mode: primary)

Orchestrates the full SDLC across 4 operating modes. Delegates every technical task to specialist agents — never does technical work itself. Enforces strict git branching discipline: main = production, every mode starts with a typed branch and ends with a PR.

  • Mode 1 (/sdlc init) — new project from scratch, Phases 0–5. Discovery interview → competitive research → planning → requirements → design → implementation → review. Phases 0–3 docs commit to sdlc/setup branch; merged to main via PR before Phase 4. Feature branches cut from updated main.
  • Mode 2 (/sdlc onboard) — understand an existing codebase. Creates docs/onboard branch. Starts with git-expert --inspect (hot files, history). Detects UI-bearing status. Produces full architecture + onboarding docs. Commits via PR to main.
  • Mode 3 (/sdlc feature) — add a feature. Discovery interview → impact analysis → design → implement on feat/[slug] branch → verify → document → squash merge to main via PR.
  • Mode 4 (/sdlc improve) — audit and improve an existing system. Discovery interview determines which dimensions to audit. Runs specialist audits (UX, code quality, performance, security, DB). Synthesizes findings into a prioritized S/M/L backlog. Executes approved items on improve/[slug] branch. PR at end. Optional focus: "ux", "performance", "security", "code-quality".

Phase 3 (Design) produces both docs/API_DESIGN.md (human-readable narrative) and docs/api/openapi.yaml (validated OpenAPI 3.0 spec). The spec is a gate requirement — Phase 3 cannot pass until it exists and passes swagger-cli validate with 0 errors.

Enforces confidence-based gates (asymmetric: < 5 fail, 5–6 revise max 3×, ≥ 7 pass) and Inter-Phase Check-In protocol at every phase boundary.

challenger — Adversarial assumption challenger (mode: primary)

Invoked between any two phases (or on demand) to pressure-test what the sdlc-lead or any specialist has concluded. Not a reviewer — a structured adversary.

What it does: Reads the output of the previous phase (design docs, audit report, architecture decision), generates 5–8 specific challenges graded by severity (FATAL / MAJOR / MINOR / NITPICK), then runs a rebuttal cycle where the original specialist must defend or concede each challenge.

Challenge categories: unstated assumptions, scope creep in disguise, missing failure modes, premature optimization, dependency risk, security gaps, scalability cliffs, testability blockers.

Output: docs/work/challenger/challenge-<phase>.md — numbered challenges, severity, supporting evidence, rebuttal outcome (DEFENDED / CONCEDED / DEFERRED). Conceded items become mandatory follow-up tasks before the gate passes.

Protocol: Fully defined in agents/shared/CHALLENGER_PROTOCOL.md. Called by sdlc-lead automatically between Phase 2→3 (requirements→design) and Phase 3→4 (design→implementation). Can be invoked manually on any output with /challenge.

coding-agent — Doc-driven implementation engineer (mode: primary)

Implements code from SDLC design documents. Called by sdlc-lead via HANDOFF for all implementation work — never invents features, never introduces unlisted tech, never writes from API training-data assumptions.

Four Laws (enforced before writing any code):

  1. Read the design docs first — ARCHITECTURE.md, SRS.md, DATABASE.md, API_DESIGN.md, IMPROVEMENT_*_DESIGN.md are the spec. Nothing gets built that isn't in the spec.
  2. Verify every library API via Context7 — calls resolve-library-id + get-library-docs for every external library before use. If Context7 is unavailable, checks node_modules/ source directly.
  3. Match existing patterns — reads 2–3 existing files in the target directory first; matches their structure, naming, imports, and error-handling style.
  4. Follow TECH_STACK.md — reads docs/TECH_STACK.md in Phase 1. All library/framework choices must match. Flags deviations in the Completion Manifest rather than silently adopting new tech.

Anti-slop rules (enforced on every file):

  • No try-catch outside system boundaries (user input, external APIs, file I/O)
  • No abstractions with fewer than 2 real implementations
  • No single-use helper functions (inline them)
  • No what-comments (only why, only when non-obvious)
  • No unused imports, no scope creep, no speculative generalization
  • Trust the framework — don't re-implement what it provides

6-phase execution: Read design docs → Verify APIs via Context7 → Implement → Test → Self-audit → Report

Produces: Implementation files + VERIFY_ITEM_[n].md Completion Manifest (files produced, API verifications, tech stack compliance, anti-slop audit result, test result, deferred items)

Distinct from: code-reviewer (audits after implementation), test-engineer (test strategy), sre-engineer (CI/CD and ops — NOT application code)

git-expert — Git & forge operations (mode: primary)

Called by sdlc-lead at every phase boundary to commit docs, create branches, cut releases, and inspect history. Six modes:

  • --init — bootstrap repo, .gitignore, remotes, hooks, branch protection
  • --feature — branch creation, atomic commits, conventional-commit messages, draft PR on Gitea + GitHub
  • --release — semver bump, Keep-a-Changelog, signed tag, GitHub + Gitea releases
  • --recover — reflog-based rescue (bad reset, detached HEAD, deleted branch)
  • --inspect — history forensics (blame, pickaxe, bisect, hot-file detection)
  • --sync — multi-remote prune + mirror

Never force-pushes protected branches, never --no-verify, scans for secrets before every commit.

researcher — Professional research analyst (mode: primary)

Three execution modes:

  • Orchestrator (default) — breaks multi-question tasks into sub-tasks, announces plan, spawns --single per question, reports each finding as it returns
  • --single: <question> — researches exactly one question (30–60 s), appends finding to output file, no sub-spawning
  • --plan: <topic> — returns a numbered question list only, no searching

security-auditor — Security assessments (mode: primary)

OWASP Top 10, threat modeling, Semgrep scans, dependency audits. Runs as 5-phase orchestrator: understand → automated scan → OWASP + STRIDE manual → verify → attack chain analysis → report.

  • Phase 5b: Attack Chain Analysis — After all individual findings are verified, runs a second-order pass that builds a pre-condition/post-condition inventory of every real finding, then tests pairs and triples for exploitable multi-step chains. Each discovered chain (e.g., "Info Disclosure → Credential Reuse → Admin Takeover") gets a C-N finding entry in the final report with step-by-step attack narrative, a severity bump rule (often higher than any individual link), and a single "break the chain" remediation priority. Tests 9 classic chain patterns: recon→targeted attack, auth bypass→privilege escalation, XSS→session hijack, SSRF→internal pivot, path traversal→credential theft, misconfiguration→enumeration, weak crypto→forgery, race condition+business logic, CVE+reachability.
  • Custom gap-filler rules (98 rules, 6 languages) installed to user's personal store at ~/.config/opencode/.semgrep/ — C#, Kotlin, Swift, Rust, PHP, and C++ bridge rules loaded automatically per detected language.
  • Offline scanning — --offline flag uses cached registry packs at ~/.semgrep/registry-cache/. Pre-populate with scripts/cache-registry-packs.sh.
  • Community rules cached at ~/.semgrep/rules/{trailofbits,elttam,gitlab,0xdea}. Install with scripts/update-semgrep-rules.sh.

code-reviewer — Code health review (mode: primary)

Four user modes (--review, --debt, --consolidate, --patterns), executed as 4-phase orchestrator internally: understand → tooling → review passes → report.

Reviews across 9 dimensions: complexity, duplication, error handling, type invariants, patterns, naming, comment accuracy, anti-slop, and tech-stack compliance (deps match TECH_STACK.md; no tech outside the design) (threshold ≥ 8). The anti-slop dimension checks for AI-generated bloat patterns cataloged in ANTI_SLOP_RULES.md.

ux-engineer — UX design & accessibility (mode: primary)

  • --design — greenfield component/workflow design, WCAG 2.2 AA, style guide, UX spec
  • --review — heuristic review of existing UI, called by sdlc-lead after code review on UI features
  • --audit — WCAG accessibility audit, called by sdlc-lead in Mode 2 (if UI-bearing) and Mode 3 verify

test-engineer — Test strategy & implementation (mode: primary)

Runs as 6-phase orchestrator: understand → research → plan → write tests → verify → report. Modes: --strategy, --unit, --e2e, --coverage.

performance-engineer — Performance profiling (mode: primary)

Profile first, optimize second. 7-phase orchestrator: understand → static analysis → profile → identify hotspot → fix → verify → document. Never optimizes without measurement.

Key capabilities added in v0.7.0:

  • PERF_TRACKER.md — persistent session tracker written at Phase 1, updated after every phase. Survives context loss and session restarts. Stored at docs/performance/PERF_TRACKER.md. Tracks: progress summary (7 rows with status/confidence), baseline metrics, static analysis findings, profiler results, hotspot log, before/after benchmark table.

  • Phase 1b — Static Analysis Pass — runs before any profiler. Five grep scans across all source files detect performance anti-patterns without executing code. Scans:

    1. O(n²) nested loops — .find() / .filter() inside for / forEach
    2. N+1 query patterns — DB/fetch call inside a loop
    3. try/catch performance anti-patterns — four language-specific patterns:
      • A: try/catch inside tight loop → V8 de-optimization (5-20x slowdown in Node.js)
      • B: Exception-driven control flow in hot paths → 100-1000× vs a guard check
      • C: Individual try/catch per await → prevents Promise.allSettled parallelism
      • D: Re-throw after logging → double stack capture cost
      • Python: EAFP misuse in hot loops → use .get() / guard check
      • Go: errors.New() in hot loop → sentinel error allocated once at init
      • Rust: unwrap() panic path in hot loop → filter_map / .ok()
    4. Blocking I/O in async paths — readFileSync, execSync, etc. inside request handlers
    5. Hot-path allocations — JSON.parse, object spread, string concat inside tight loops

  • Coverage confidence loop — after all 5 scans, the agent cross-checks its grep coverage against a find-generated source file list, answers a 9-question checklist, and rates coverage 1-10. Re-passes if < 7 (max 3 attempts); surfaces ⚠️ BLOCKED to user if still < 7.

  • Verbatim code mandate — every finding requires a read(filePath=..., offset=..., limit=...) call before it's recorded. Findings from grep output alone are prohibited. Each finding's "Verbatim code" block shows the exact lines from read().

  • Full report template (Phase 6) — docs/PERFORMANCE_REPORT.md follows a mandatory template with: executive summary, baseline measurements table, one STATIC-NNN block per finding (verbatim code + loop bound + specific impact + concrete fix + profiler confirmation status), profiler results table, fix before/after verbatim code, final benchmark (P50/P95 before and after), regression check table, remaining bottlenecks backlog (with S/M/L effort + P0/P1/P2 priority), data size thresholds, coverage verdict, and handoffs recommended.

  • Confidence gate reads from tracker file — gate prints a 7-row table derived from PERF_TRACKER.md, not from context memory. Phase 5 (verify-fix) uses a raised threshold of 8/10 — a fix without before/after numbers is not verified.

db-architect — Database design (mode: primary)

6-phase orchestrator: understand data → research → plan → design + implement → verify → report. Modes: --design, --migrate, --tune, --review.

api-designer — API design (mode: primary)

6-phase orchestrator: understand → research → design → document → verify → write docs. REST + GraphQL, contracts, versioning, pagination, error shapes.

container-ops — Container operations (mode: primary)

6-phase orchestrator: understand → research → plan → execute → verify → report. Podman/Docker, Dockerfiles, compose, networking, image optimization.

sre-engineer — Site reliability (mode: primary)

6-phase orchestrator: understand → research → plan → execute → verify → report. CI/CD pipelines, monitoring, incident response, runbooks.

frontend-design — Frontend design engineer (mode: primary)

Bridges UX specification and production UI. Turns design tokens and component specs into code that looks intentional — not AI-generated. Three modes:

  • --implement — turns UX_SPEC.md + STYLE_GUIDE.md into production components
  • --polish — takes existing UI and elevates typography, color, spacing, motion
  • --system — creates or refactors a design token system (colors, typography, spacing, shadows)

Distinct from ux-engineer: UX handles usability, workflows, and accessibility; this agent handles visual polish and implementation. Called by sdlc-lead in Phase 3 (after UX spec is approved) and Mode 4 (/sdlc improve "frontend").

ui-verifier — Live browser verification specialist (mode: primary)

Navigates a running application with playwright-mcp, captures screenshots, reads accessibility snapshots, and verifies that real UI behavior matches use cases or UX specs. Works with any LLM — no vision required (uses accessibility tree as primary signal).

Not a test-writer. test-engineer writes Playwright specs. ui-verifier runs the browser live against your deployed or local server and produces a UI_VERIFICATION_REPORT.md with per-flow PASS/FAIL/WARN verdicts.

Modes:

  • --smoke (default) — 5-min quick pass: navigate main routes, screenshot, check for errors
  • --use-cases — verify each P0 use case from docs/testing/USE_CASES.md
  • --flow "<description>" — single named flow end-to-end (login, create, submit, etc.)
  • --regression — post-change check against last-known report

Verification signals (no vision needed):

  • browser_snapshot() — accessibility tree reveals error alerts (role="alert"), aria-invalid, missing landmarks, unlabeled inputs
  • browser_get_url() — confirms redirects happened correctly
  • browser_evaluate("document.title") — catches 404/500 pages
  • browser_screenshot() — visual record, described if vision model available

Produces: docs/test/UI_VERIFICATION_REPORT.md — per-flow results table, step-by-step observations, accessibility findings, recommendations.

Requires: playwright-mcp registered (handled by install.sh).

architecture-designer — Module boundary designer (mode: primary)

Derives module boundaries from business domains and produces the structural design documents that coding-agent and validate-module-boundaries.sh enforce.

  • Primary deliverables: docs/MODULE_DESIGN.md (bounded contexts, dependency rules, naming conventions) and docs/INFRASTRUCTURE.md (environment matrix, compute, data, networking with Mermaid diagram)
  • Domain-driven decomposition — identifies bounded contexts from use cases and data models; rejects technical-layer naming (controllers/, services/, utils/) in favor of domain-aligned modules
  • Circular dependency detection — maps the full dependency graph during design; flags and resolves cycles before implementation begins
  • Infrastructure specification — documents environment matrix (dev/staging/prod), compute resources, data stores, networking topology; validates against validate-infrastructure.sh rules (rejects IaC code in the doc)
  • Handoff contract — produces MODULE_DESIGN.md that validate-module-design.sh can pass before handing off to coding-agent

Called by sdlc-lead in Phase 3 (Design), after db-architect and before coding-agent.

guide — Expert-system concierge / front door (mode: primary)

The entry point when you don't know which command to run. Takes a plain-English goal, routes it to the right expert, checks prerequisites (via doctor.sh), drives the workflow, and always offers the next step (especially "want me to fix what I found?"). Has the full intent→expert routing table, a guided security scan→triage→fix flow, and multi-step sequencing for goals like "harden before launch". Invoked with /guide.

task-decomposer — Plan-DAG builder (mode: primary)

Turns any request into plan.json — a typed DAG of bounded leaf tasks sized to the executing model's tier, with scout-before-plan and verify nodes. Executed deterministically by scripts/run-plan.mjs. The keystone for running big work reliably on small local models.

end-user-simulator — Persona-driven UAT (mode: primary)

Walks the live app as a first-time human user with zero spec knowledge — only a persona, a goal, and what's on screen. Produces friction logs with patience budgets and task-completion verdicts. Distinct from ui-verifier (which checks the implementation against the spec).

llm-integration-engineer — LLM feature design (mode: primary)

Design-side expert for building LLM features: prompt architecture, eval harnesses, model routing/fallback, token budgeting, structured-output contracts, RAG shape. Six hard rules (verify model facts, API-layer schema enforcement, no-eval-no-ship, …). Not for LLM security audits — that's owasp-llm-checker.

release-manager — Release coordinator (mode: primary)

Thin coordinator for shipping a release: version bump, changelog (via changelog-writer), tag, deploy-gate checklist, both-remotes push, and a doc-count audit that prevents version-metadata drift.

Security micro-agents

Live in agents/security/. Dispatched by security-auditor (coordinator) via HANDOFF — each runs in its own context window and writes findings to docs/work/security/<slug>.md.

Agent Purpose
owasp-web-checker OWASP Top 10 web vulnerabilities — one finding per category, verbatim evidence
owasp-llm-checker OWASP LLM Top 10 — AI-specific attack surface (prompt injection, training data poisoning, etc.)
cloud-security-checker Cloud misconfigurations — IAM, S3/GCS public buckets, security groups, KMS
iac-security-checker Infrastructure-as-Code security — Terraform/Pulumi/CDK patterns
secrets-scanner Hardcoded secrets, API keys, credentials in source + git history
dependency-auditor Known CVEs via npm audit/pip-audit/cargo audit; license risk
semgrep-runner Semgrep scan with custom gap-filler rules + community rule packs
threat-modeler STRIDE per component, trust boundary analysis, attack surface enumeration
attack-chainer Second-order pass — pairs/triples of real findings into multi-step exploit chains (C-N entries with severity bump)

Methodology docs: OWASP_METHODOLOGY.md, OWASP_LLM_METHODOLOGY.md, CLOUD_METHODOLOGY.md, IaC_METHODOLOGY.md, FINDING_SCHEMA.md (shared finding envelope format).

Code-review micro-agents

Live in agents/code-review/. Dispatched by code-reviewer (coordinator) in parallel — each covers one review dimension.

Agent Dimension
complexity-analyzer Cyclomatic complexity, nesting depth, cognitive load
duplication-detector Copy-paste patterns, near-duplicate logic, DRY violations
error-handling-auditor Silent failures, over-broad catch, missing boundary validation
type-safety-checker Any-cast abuse, non-null assertions, unsafe type coercions
pattern-consistency-checker Naming, import style, module structure — deviation from project conventions
anti-slop-auditor 31-rule AI slop catalog (R-01..R-31): bloat, speculative abstractions, generated filler, slopsquatting, credential leakage
dead-code-detector Unimplemented stubs, never-called functions, unused exports, orphan files, disconnected pipelines, unreachable branches (tool-first: knip/ts-prune/vulture/staticcheck + grep fallback)
code-health-synthesizer Coordinator synthesizer — reads all seven micro-agent outputs, produces HEALTH_ASSESSMENT.md with prioritized backlog

Methodology: agents/code-review/METHODOLOGY.md — per-dimension grading rubrics, severity escalation rules, FIX_BACKLOG format.

Performance micro-agents

Live in agents/performance/. Dispatched by performance-engineer (coordinator).

Agent Purpose
static-perf-analyzer Grep-based static scans: O(n²) loops, N+1 queries, blocking I/O in async paths, hot-path allocations
profiler-agent Runtime profiling — instruments code, runs load, captures flamegraph/heap snapshots
db-query-analyzer Slow-query detection, missing indexes, N+1 at the ORM layer, explain-plan analysis
bundle-analyzer Frontend bundle size, tree-shaking gaps, duplicate packages, lazy-load opportunities
concurrency-checker Race conditions, deadlock patterns, improper shared-state access
perf-synthesizer Coordinator synthesizer — reads all micro-agent outputs, produces PERFORMANCE_REPORT.md with before/after benchmark table

Methodology: agents/performance/METHODOLOGY.md — profile-first discipline, verbatim-code mandate, coverage confidence loop.

SDLC onboard specialists

Live in agents/sdlc/onboard/. Dispatched by sdlc-onboard-mode (coordinator) via HANDOFF in parallel where possible.

Agent Deliverable
landscape-mapper docs/LANDSCAPE.md — tech stack, project metrics, directory structure, hot files, recent focus
entry-point-tracer docs/diagrams/entry-points.md + docs/diagrams/sequences/*.md — traced call chains as Mermaid sequence diagrams
component-mapper docs/diagrams/c2-containers.md + docs/diagrams/c3-components.md — C4 container and component diagrams
health-coordinator docs/HEALTH_ASSESSMENT.md + docs/testing/USE_CASES.md + docs/testing/TEST_PLAN.md — dispatches code-reviewer, security-auditor, test-engineer, performance-engineer in parallel

Game-dev cluster

Live in agents/game/. Activated by the /sdlc init "<name>" "<desc>" --game flavor (swaps SRS→GDD, inserts a vertical-slice gate before content production). Reuse the generic engineering experts (coding-agent, perf, test, frontend) for everything else.

Agent Purpose
game-designer Core loop first, 3 pillars, lose-loop design; produces the GDD (Game Design Document, the SRS equivalent) with SLICE/POST-SLICE scoping
gameplay-engineer Engine-grain implementation (Godot/Unity/Phaser/Bevy): frame budget, fixed-timestep vs render FPS, allocation discipline, input buffering, determinism
game-balance-designer Progression curves, economy sinks/sources; simulates 1000 player-sessions as a rerunnable script before shipping numbers
playtest-evaluator Blind-first playtest of the vertical slice; 6 fun heuristics with evidence, time-to-first-success vs the slice acceptance test
game-asset-pipeline Sprite batch micro-loop: gen → lattice/pixel-snapper cleanup + transparency de-fringe (deterministic skills/game-asset-pipeline/ scripts) → sprite-sheet pack → portable TexturePacker-hash atlas manifest for engine import

SDLC mode agents

Thin orchestrators that drive each SDLC phase. Read by sdlc-lead on demand.

Agent Purpose
sdlc-init-mode Entry point for Mode 1 (new project) — loads phase files as needed
sdlc-init-phases-0-2 Ideation, planning, requirements (Phases 0–2)
sdlc-init-phase-3 Design (Phase 3): architecture, DB, API, security
sdlc-init-phase-4 Implementation (Phase 4): parallel coding waves
sdlc-init-phase-5 Review, hardening, release (Phase 5)
sdlc-feature-mode Mode 3: add a feature to an existing project
sdlc-improve-mode Mode 4: audit-driven improvement
sdlc-onboard-mode Mode 2: understand an existing codebase — thin dispatcher to onboard specialists

Skills

Skills are thin triggers that live in skills/<name>/SKILL.md. Each skill maps to an agent and accepts mode flags. Users invoke skills with /skill-name [flags].

Skill Agent Purpose
/guide guide Front door — describe any goal in plain English; routes to the right expert and drives the workflow
/sdlc sdlc-lead Full SDLC workflow (init / onboard / feature / improve / gate / status); --game flavor for games
/code coding-agent Implement from SDLC design docs — API verification, anti-slop enforcement, tech stack compliance
/git-expert git-expert Git lifecycle (init / feature / release / recover / inspect / sync)
/security security-auditor OWASP audit, threat model, Semgrep scan; --fix drives a verified remediation loop
/review-code code-reviewer 9-dimension code health review incl. dead/unused-code + tech-stack compliance (review / debt / consolidate / patterns)
/research researcher Deep research with source evaluation
/test-expert test-engineer Test strategy, unit/e2e tests, coverage
/perf performance-engineer Profile, benchmark, optimize
/dba db-architect Schema, migrations, query tuning
/ux ux-engineer UX design, heuristic review, accessibility audit
/api-design api-designer REST/GraphQL design and review
/containers container-ops Build, compose, debug, optimize images
/devops sre-engineer CI/CD, monitoring, runbooks, incident response
/gate sdlc-lead Gate check / approve / bypass for SDLC phases
/review code-reviewer + security-auditor Generic review meta-skill
/simplify code-reviewer Simplification-focused pass on recent changes
/explore sdlc-lead (inline) Codebase archaeology — trace a feature end-to-end, map blast radius
/design-options sdlc-lead (inline) Generate 2-3 architecture alternatives with trade-offs before committing
/frontend frontend-design Visual polish, design tokens, typography, color, spacing, motion
/migration-planner migration-planner Ordered, reversible DB migration plan between two schema states
/documentation-gap-finder documentation-gap-finder Audit public surface for undocumented / stale / missing docs
/llm-integration llm-integration-engineer Design LLM features — prompts, evals, routing/fallback, token budget, structured output
/end-user-simulator end-user-simulator Persona-driven UAT — walk the live app as a first-time user, log friction
/release release-manager Coordinate a release — version, changelog, tag, deploy-gate, push (on top of /git-expert --release)
/challenge challenger Adversarially verify claims in an artifact — CONFIRMED/CONTRADICTED/UNVERIFIABLE with cited evidence
/reflow sdlc-lead (inline) Recompute the module-contract ticket graph — mark done, list claimable modules, collision-check write-scopes, emit a claimed module HANDOFF
/steward sdlc-lead (inline) Audit CLAUDE.md / AGENTS.md alignment, capture session learnings
/onboard-inventory researcher Ralph Wiggum D1 — enumerate units into docs/onboard/INVENTORY.md
/onboard-verify sdlc-lead Ralph Wiggum D3 — run all onboard validators, report gaps
/onboard-gap-fill sdlc-lead Ralph Wiggum D4 — emit focused HANDOFFs for uncovered rows only
/ui-verify ui-verifier Live browser verification — screenshot flows, check accessibility snapshots, verify use cases
/design-iterate design-iterator Claude-Design-style visual loop — render → screenshot → critique against tokens.json → fix → re-verify (--sync token extraction, --real logged-in browser audit)
/gauntlet gauntlet-lead Gauntlet loop — builders + blind fresh-per-round critics iterate until the work matches or beats a named real exemplar (--bar, --budget)
/wave orchestrator (inline) Level-2 wave integration gate — reviewer set composed from the aggregate diff, concurrent isolated reviewers, finding SETS (summaries, never transcripts) synthesized into one consensus-weighted wave-gate report with findings attributed to the introducing ticket
/goal orchestrator (inline) Bounded objective loop — requires a measurable exit + budget up front, refuses unmeasurable objectives (Ralph Wiggum refuse-to-loop gate); iterations classified per FIX_VERIFY_LOOP.md (STALLED / PROGRESSED / OSCILLATING), existing caps only
/autopilot orchestrator (inline) Unattended run-to-completion outer loop — ASSESS (board + gates + requirement ledger + branches + red suites, story-denominated) / DECIDE (ordered next actions, each with an exit predicate) / DRIVE (conductor / run-until-done / run-plan, one bounded unit at a time) / HEAL (narrow → split → escalate tier → park with evidence; byte-identical gap set = no-progress HALT) / EXIT (assembly-gate predicate or documented halt; iteration cap mandatory) Field-proven 2026-09-01: a two-ticket product driven end-to-end (OpenAI terra codes, luna reviews, runtime verified, merged, board drained) — the PRIMARY agent kicks off, tracks, and reconciles it per the skill's OPERATE section; handoffs only where the ladder names one.
/vault vault Query / ingest / lint the agent-brain-vault — answer a project question from compiled, cited pages instead of re-reading raw sources (T5.6)

48 skills total (includes /guide — the concierge front door).

Shared protocols

Canonical reference files in agents/shared/. Single source of truth — update once in this canonical repo; npm run build:claude regenerates the attest-claude copies.

File Purpose
SCOPE_BOUNDARY.md Stay-in-lane rule for direct-mode invocations — per-agent in-scope / refer-back table + canonical SCOPE-BOUNDARY block
BOUNDED_TASK_CONTRACT.md Six canonical scope rules every specialist follows in Bounded Task Mode
HANDOFF_TEMPLATES.md Canonical HANDOFF block templates (standard, remediation, re-verification, parallel-wave) + context-packet template
HANDOFF_QUICK_REF.md One-page quick reference: HANDOFF format, completion phrase, manifest schema — for agents with small context budgets
FIX_VERIFY_LOOP.md Canonical review → FIX_BACKLOG → remediate → re-verify pipeline with 3-iteration cap and escalation block
RALPH_WIGGUM_LOOP.md Canonical inventory-driven deep-verification loop used by /sdlc onboard --deep and /security --deep
LOOP_PREVENTION.md Tool-selection cheat-sheet + three loop classes (failure / schema-validation / success) + BLOCKED-template
RESEARCH_TOOLS.md Mandatory research-tool surface and fallback chain (playwright-search → pullmd → STOP)
CODE_SEARCH.md The code-search MCP surface (symbol/reference index): code_symbols/code_references/code_outline/code_search + code_index, when to prefer it over grep, and the mandatory code_index()-then-grep-fallback freshness contract. Inlined as the ## Code search block into code-heavy agents
ANTI_SLOP_RULES.md 31-rule AI slop catalog (R-01..R-31) — over-engineering, defensive bloat, hallucinated patterns, slopsquatting, credential leakage
CHALLENGER_PROTOCOL.md Full Challenger adversarial review protocol — challenge categories, severity grades, rebuttal cycle, output format
GATE_SCORING_PROTOCOL.md HANDOFF resume scoring (1–10 scale, asymmetric threshold ≥7 pass / 5–6 revise / <5 auto-fail) + coverage validator table
PHASE_ROUTING_PROTOCOL.md Smart routing table per phase, escape hatches, validation gate chain, two-track system (Track 1: coverage loop; Track 2: confidence loop)
PARALLEL_WAVE_PROTOCOL.md 3-round parallel coding protocol: Round 1 code HANDOFFs → Round 2 review + Fix-Verify Loop → Round 3 runtime. Wave gate + cross-wave rules.
CONTEXT_BUDGET.md Context budget management — synthesis chunking, state-file discipline, when to stop and write to disk
SESSION_PRIMER.md ~600-token session primer with 7 core rules including HANDOFF format, disk discipline, and memory workflow
MEMORY_PRIMER.md Memory MCP protocol — 3-call workflow (session_restore → memory_store → session_save), trigger table, call format, flat-file fallback
EXECUTOR_SELECTION.md Capability-probed delegation — native Task tool / subprocess / manual paste, chosen by has_task_tool/mcp_in_subagents flags
MODEL_ADAPTER.md Per-tier behavior (small/medium/large), maker/verifier/PLANNER roles + plan-strong/execute-cheap routing (B5), local-model pointer
MICRO_LOOP.md The per-agent micro-loop: plan-shape → produce → self-verify (tool-offloaded, B3) → re-ground (B4) → revise — the produce/verify discipline every agent runs
GUIDE_CAPTURE.md Guide-capture protocol (T21.1): how a running expert records a reusable "guide" (playbook bullet + matched lesson) so the next run pre-briefs from captured knowledge instead of cold-starting
CHECKPOINT_REVERT.md Git checkpoint per gated PASS + revert-to-known-good on unrecoverable failure for multi-phase work (Lever 8 / B7)
CHECKPOINT_STATE.md Context checkpoint: write a compact docs/work/STATE.md after each step so the user can /clear and resume; the catch-up read-list /sdlc resume rehydrates from
PERSISTENCE.md Anti-announce-then-stop rule — never end a turn after announcing an action; perform it or print BLOCKED:. The prompt-side fix for the #1 accidental pause (~+20% SWE-bench)
AUTONOMY_PROTOCOL.md Autonomy level (interactive
LOCAL_LLM_PRIMER.md ~600-token session primer for local-model sessions — SDLC-TASK override, HANDOFF format, write-to-disk, stop-means-stop
BOOK_PROTOCOL.md Canonical rule for structuring long-form deliverables (> 300 lines) as multi-page books with index navigation (enforced by validate-book-structure.sh)
CODE_BOOK_PROTOCOL.md The book protocol applied to code: a source file over the size cap becomes a directory (index/barrel + one-concern chapter modules); enforced by validate-file-size.sh
BROWSER_TESTING.md Browser-automation / E2E primer — when and how to use playwright-mcp for screenshots and runtime UI verification
TUI_SESSION_HYGIENE.md TUI session-hygiene protocol — thin orchestrator, mandatory fresh-context (Executor A/B, never inline D) dispatch for tool-heavy specialists, scan-output-to-disk hard rule, 70%-of-truthful-context-display checkpoint-and-resume
SDLC_RESUME_PROTOCOL.md Deterministic resume of an incomplete SDLC (status: partial): gate-verify every claimed-complete phase, then give each artifact a disposition (locked / repair / redo) before continuing
CONTAINER_RUNTIMES.md Runtime detection and cloud-portability knowledge behind container-ops — which CLI/compose flavor is present, rootless gotchas, multi-arch, GCP/AWS-portable images
QA_VNV_TESTING.md Runnable QA/V&V technique library for qa-vnv-engineer — layout-defect detection, visual regression, resilient journey automation, evidence reporting
GAUNTLET_LOOP.md The /gauntlet harness: a real reference bar, builders in clean context, blind fresh-per-round critics; the builder never grades its own work
PRODUCT_SHAPE_PROTOCOL.md Canonical orchestration role names (GOAL / ORCHESTRATOR / BOTS / REVIEW PANEL / HONESTY LOOPS), the two-stack rule, the feature-map planning artifact, and feature-grouped landing
TOOL_PREFLIGHT.md Enforced tool-preflight + diagnose-before-retry contract for agents that run external scanners and profilers (semgrep, checkov, trivy, py-spy, lizard, jscpd …)
GAME_PRODUCTION.md How games are actually produced, indie and AAA — lifecycle gates on builds, discipline map and indie role-collapse, the artifacts that matter
GAME_TOOLING.md Game-tool MCP landscape and agentic engine loops for the game cluster — maintained engine/art/audio MCP servers and how to wire them

Memory & code-search MCPs

Four MCP servers extend agent capability beyond the session context window. For full configuration instructions see MCP_GUIDE.md.

bpm-memory-mcp — Cross-session project memory

Persistent memory store backed by SQLite + vector embeddings (LM Studio nomic-embed-text). Provides hybrid search (vector 35% + BM25 35% + link traversal 30%).

Registered via install.sh step 8 (claude mcp add memory node <path>). For OpenCode, entry in opencode.json under "mcp".

Tools used by agents:

Tool When
session_restore() Start of every session — load prior decisions, constraints, patterns for this project
memory_store({ content, type, confidence, citation }) When a significant decision, constraint, pattern, or bug root cause is found
session_save({ summary }) After every phase gate, before stopping
memory_recall({ query }) On demand — search prior project memories

Types: decision, fact, pattern, error, preference. Scope: project (default) or global.

Flat-file fallback: When the MCP is unavailable, agents fall back to docs/work/SESSION_NOTES.md. Full protocol in agents/shared/MEMORY_PRIMER.md.

bpm-code-search-mcp — Semantic + symbol code search

MCP server providing semantic search over code chunks (embedding-based) and a structural symbol index. Built on SQLite + FTS5 + cosine similarity. Provider-sticky: the embedding provider used at index time is locked in; queries from a different provider fall back to FTS5 BM25.

Source: ~/Code/bpm-code-search-mcp/. Registered in opencode.json and ~/.claude/settings.json (PostToolUse hook auto-reindexes edited files).

Tools:

Tool Purpose
code_index(path?, force?) Index or re-index the codebase. Mtime-gated — skips unchanged files.
code_search(query, top_k?, path_filter?) Semantic search — returns ranked chunks with file:line and similarity score
code_symbols(kind?, name_filter?, path_filter?, limit?) Browse symbol index — functions, classes, interfaces, types, enums, methods, Markdown sections
code_outline(file_path) Structural outline of a single file — all named symbols in line order
code_references(name, top_k?, path_filter?) Find all chunks mentioning a symbol by name (FTS exact-phrase match)
code_index_status() Provider, file count, chunk count, symbol count, DB path

Symbol extraction covers 10 languages: TypeScript/JS, Python, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, Markdown headings.

playwright-mcp — Browser automation & screenshots

LLM-agnostic browser automation via Microsoft's official Playwright MCP. No vision model required — uses the accessibility tree by default with screenshots on demand. Works identically in Claude Code and OpenCode (including local LLMs).

Why it exists: Replaces the Claude Code browser extension (claude-in-chrome) for all automated/CI use cases. The extension only works in Claude Code with cloud models; playwright-mcp works everywhere.

Tool Purpose
browser_navigate(url) Navigate to a URL
browser_screenshot() Take a screenshot (returns image)
browser_snapshot() Accessibility tree snapshot — no vision needed
browser_click(element) Click by CSS selector or text
browser_fill(element, value) Fill a form field
browser_wait_for(selector, state) Wait for element state
browser_evaluate(js) Run JavaScript in the page
browser_get_url() Get current URL
browser_close() Close the session

Full protocol: agents/shared/BROWSER_TESTING.md Install: claude mcp add playwright -- npx -y @playwright/mcp@latest

Validators

Seventy-nine bash validators + gate runners in scripts/validators/. Each returns exit 0 (clean) / 1 (gaps) / 2 (validator error) and emits a JSON gap envelope to stdout. Bash 3.2 compatible (macOS default).

Script Checks
validate-adrs.sh Every ADR-NNN reference in docs has a corresponding file with a valid status field; a hard-to-reverse choice (datastore/auth-model/core-framework/vendoring-strategy) asserted in ARCHITECTURE.md/TECH_STACK.md has a matching, on-topic ADR (T29.5)
validate-api-coverage.sh Every route in source has a row in API_DESIGN.md and a path entry in openapi.yaml
validate-architecture.sh 6 diagram types, Mermaid syntax, HLA overview, no placeholders
validate-build.sh Runs project build command and checks exit code
validate-c3-coverage.sh Every source module appears in the C3 context diagram
validate-close-receipt.sh A ticket module in_review/done has the close() receipt pasted verbatim into its Completion Manifest — not just a self-asserted "<id> done" phrase (wraps scripts/lib/tickets.mjs check-receipt; the same check accept() itself enforces, T26.3)
validate-code-health.sh 9 anti-slop patterns: catch-all error handlers, try-in-loop, what-comments, unused imports, single-use helpers, speculative abstractions, hardcoded config, re-implemented framework features, scope creep
validate-completion-manifest.sh HANDOFF manifest schema + completion phrase, AND (T27.2 v2) Files-produced paths exist on disk, Verify-result cites a real artifact, Maker/Verifier identity present and distinct
validate-deps.sh npm audit / pip-audit / cargo audit with configured waivers
validate-design-system.sh Token file present, component files match UX_SPEC inventory, no hardcoded hex colors
validate-doc-counts.sh Every " validators/skills/references" count claimed in README/docs is re-derived from the filesystem and matched (release-manager step 5, made deterministic)
validate-e2e-setup.sh playwright.config.ts has JSON reporter, retries, screenshot, baseURL; auth fixture present; POM directory present; CI E2E step present
validate-entry-points.sh Every entry point (main, index, bin) is documented
validate-erd-coverage.sh Every table/model in source has an ERD entry
validate-fix-backlog-closed.sh CRITICAL and HIGH rows in FIX_BACKLOG resolved before phase-5 gate
validate-handoff-discipline.sh Every task()-shorthand delegation maps to a HANDOFF with a no-spawn fallback; no raw Agent(...)/subagent_type spawn bypasses the contract, and concurrent HANDOFF to: dispatchers must gate on has_task_tool (runs in the git-expert merge gate when agents/**.md changes)
validate-tickets.sh Module-contract ticket graph integrity — malformed tickets, cyclic/dangling depends_on, orphan node refs, and overlapping write-scopes among active modules (wraps scripts/lib/tickets.mjs)
validate-ticket-hygiene.sh Ticket LIFECYCLE hygiene audit, distinct from graph validity — a done module missing complete history/evidence/manifest, an owner holding >1 open ticket, a claim open >7d, TICKETS.md/STATE.md status contradicting plan.json, and an evidence commit touching a file outside its write_scope or citing a commit absent from git history (wraps scripts/lib/ticket-hygiene.mjs, T26.2)
validate-requirement-closure.sh Phase 4→5 REQUIREMENT closure (not task closure, T29.2): a story is closed only when ≥1 module's stories[] references it AND every referencing module is done; also requires the mandatory docs/work/REQUIREMENT_RECONCILIATION.md reconciliation matrix to cover every story with no OUTSTANDING verdict. Skips cleanly when stories[]/docs/USER_STORIES.md aren't adopted (wraps scripts/lib/tickets.mjs requirement-status + scripts/lib/reconciliation-matrix.mjs)
validate-persistence-block.sh Every executor/coding agent carries the anti-announce-then-stop rule (PERSISTENCE.md), directly or via MODEL_ADAPTER/BOUNDED_TASK_CONTRACT — kills the #1 accidental pause
validate-autonomy-wiring.sh Every by-design pause directive is autonomy-aware — carries the AUTONOMY_PROTOCOL gate or is marked NEVER-AUTO within ±5 lines, so autonomy: auto takes documented defaults instead of silently waiting
validate-contract-conformance.sh Live app vs frozen openapi spec — every GET endpoint returns a declared 2xx with required JSON fields present; drift (spec route missing from the app) is a gap. SKIPs when no spec/base-url (wraps scripts/contract-conformance.mjs)
validate-iac.sh IaC scaffolding: entry/variables/outputs/per-env configs present, no hardcoded secrets
validate-infrastructure.sh INFRASTRUCTURE.md has env matrix, compute, data, networking + Mermaid diagram; rejects IaC code in the document
validate-inventory.sh Every row in INVENTORY.md has a corresponding artifact
validate-lint.sh Linter + typecheck exit clean
validate-migrations.sh Up/down migrations present and reversible
validate-model-pins.sh G3 config-pin lint (T30.1, M30 model-tier guard) — a frontier-tier model id hardcoded in agent frontmatter or repo config outside models.json is a hard gap ("pin roles, not models"); any other raw model:/"model" pin outside models.json warns without failing
validate-vendor-provenance.sh Anti-slop R-30 (T29.8, field lesson B-2): a vendored/copied library module must be generated from the real upstream and record its provenance (source + version), not reimplemented from memory in a library's shape; a "vendored" file with dropped/renamed variants and no provenance marker is flagged as a silent fork
validate-module-boundaries.sh Cross-module imports comply with dependency rules in MODULE_DESIGN.md
validate-module-design.sh MODULE_DESIGN.md: domain-aligned naming pattern present, no technical-layer names, circular dependency check passes
validate-no-ascii-art.sh No Unicode box-drawing characters or ASCII banners in documentation files
validate-owasp.sh All 10 OWASP categories present, confidence ≥ 7, attack-chains section present
validate-phase-gate.sh Orchestrator — chains the right validators for a given SDLC phase
validate-release-readiness.sh 10-condition release gate: FIX_BACKLOG closed, 4 review verdicts (security/code/ux/perf), coverage threshold, container CVE scan, RUNTIME PASS
validate-requirements-matrix.sh REQUIREMENTS_MATRIX.md: P0 use-case rows have Test ID and Status; cross-references USE_CASES.md
validate-scope.sh Post-HANDOFF git-scope enforcement
validate-security-controls.sh SECURITY_CONTROLS.md: HIGH/CRITICAL threats have controls; DB, API, and ARCH security sections present
validate-sequence-coverage.sh Every P0 use case has a sequence diagram
validate-smoke.sh Boots server, hits configured routes, asserts HTTP 200
validate-spec-traceability.sh docs/TRACEABILITY.md grades every founding-brief requirement against the produced doc set + tickets (T22.15)
validate-state-drift.sh docs/work/STATE.md's Done-section phase claims are backed by a real/waiver gate receipt (docs/work/gates/<phase>-receipt.json, T27.1) — used by /sdlc resume (warn) and run-until-done.sh's outer loop (block completion) so a claimed-but-unreceipted phase can't be trusted (T27.4)
validate-status-freshness.sh A generated project docs/work/STATUS.md (T29.3, H7/C-1) is flagged stale when its embedded numbers mismatch a live recompute against plan.json, or predate the plan's own last work event (latest history[]/claimed_at timestamp). Not chained into a phase gate — advisory, the intended caller is the steward skill (wraps scripts/gen-status-report.mjs --check)
validate-tech-stack.sh All runtime and dev dependencies present in TECH_STACK.md
validate-test-design.sh TEST_DESIGN.md has 5 mandatory sections: Unit, Integration, E2E, Security, Test Infrastructure
validate-tests-mapping.sh Use-case ↔ test coverage mapping; UC-level PASS/FAIL derived from jest/vitest/pytest JSON results
validate-tests.sh Runs test suite; Playwright fast-path with JSON reporter
validate-use-cases.sh UC-IDs present, required fields complete, Source traceability field populated
validate-user-stories.sh Given/When/Then acceptance criteria present, traceability to use cases
validate-ux-spec.sh UX_SPEC.md: component library chosen, ≥ 5 component inventory, P0 UCs covered, WCAG strategy, responsive strategy
run-coverage-loop.sh 3-iteration gate loop runner — re-runs validators until clean or iteration cap reached
run-handoff-gates.sh Scope + manifest + coverage gate runner with any-failure-aborts semantics
validate-api-consistency.sh The OpenAPI spec and the implemented routes agree (paths, methods, params)
validate-autonomy-ledger.sh APPROVALS.md rows are well-formed and every NEVER-AUTO row is human-signed (T27.5) — the runtime counterpart to validate-autonomy-wiring.sh's prose-adjacency lint
validate-challenger-gate.sh Any FIX_BACKLOG/review/security report with a CRITICAL or HIGH finding, or any ADR/design doc asserting an unverified external rationale, has a matching CHALLENGE_REPORT_*.md with zero unresolved CONTRADICTED verdicts (T27.3, T29.5)
validate-circular-deps.sh Detects dependency cycles in the MODULE_DESIGN.md graph
validate-data-governance.sh A schema with personal data ships with classification + retention/handling rules
validate-dead-code.sh Deterministic dead-code / stub / unused-export gate (knip / ts-prune / vulture + grep)
validate-doc-catalog.sh The FEATURES catalog lists every validator + shared protocol that actually ships (body-drift)
validate-doc-render-health.sh Markdown-table orphan-fragment linter — a |-delimited data row with no valid header/separator above it renders as literal pipe-text, not a table (T29.9)
validate-feature-coverage.sh Scoped Ralph Wiggum inventory coverage for /sdlc feature
validate-improve-coverage.sh Scoped Ralph Wiggum inventory coverage for /sdlc improve
validate-loop-readiness.sh Refuse-to-loop gate (G7) — every loopable row must name a checkable success criterion
validate-mermaid.sh Scans markdown for Mermaid syntax problems (optionally renders via mmdc)
validate-module-boundaries-transitive.sh Design-level transitive dependency-graph boundary check
validate-no-reinvent.sh Anti-reinvention / canonical-overwrite drift guard (G-B), --base merge-gate mode
validate-observability.sh The observability spec is concrete (metrics, logs, traces, alerts) at design time
validate-resilience-patterns.sh Resilience patterns (retry, timeout, circuit-breaker, fallback) designed at Phase 3
validate-tracker-fresh.sh Tracking-as-gate (G-D) — work changed but no tracker updated → fail; --base mode
validate-tracker-integrity.sh External Tracker Data Model (T29.6, H5/A-6): docs/TRACKER_DATA_MODEL.md must exist before any docs/work/tracker-snapshot.json; once a snapshot exists, every non-stray item has its required label, every story is structurally linked to its phase, and no untagged template/sample item pollutes scope math. No-op for projects using only plan.json (wraps scripts/lib/tracker-model.mjs)
validate-jira-hygiene.sh Jira mirror hygiene (offline-safe; active only when TRACKER_BACKEND=jira): flags lifecycle ops queued in the durable outbox but not mirrored to Jira, and modules that advanced (claimed/in_progress/in_review/done) without a Jira sync. No-op for the plan.json-only path (wraps scripts/lib/jira-hygiene.mjs; see references/jira-adapter.md)
validate-flows.sh docs/design/flows.md (ux-researcher's output, the ROOT of the design chain) is structurally sound: exists (unless headless), has at least one Mermaid flow diagram and a screen-inventory section, no placeholder text. Flags a missing flows.md only when downstream design artifacts (tokens.json/components.md/UX_SPEC.md) exist without their derivation root; skips clean before the design phase
validate-design-tokens.sh Figma-source ↔ tokens.json drift (offline-safe; active only when docs/design/figma-snapshot.json exists): flags a Figma color dropped from tokens.json, a snapshot pulled but never derived, and (advisory) a color that diverged. No-op for the prose-authored tokens.json path (wraps scripts/lib/design-tokens.mjs; see references/figma-adapter.md)
validate-wcag-coverage.sh Accessibility (WCAG) evidence exists for UI-bearing components
validate-qa-evidence.sh A qa-vnv-engineer V&V report is evidence-backed — traceability plus attached artifacts, not confident prose
validate-rules.sh Lints the rules/ primitive: every rule file has parseable frontmatter (description, boolean alwaysApply, and globs unless always-applied)
validate-invariants.sh Enforces a project's declared cross-cutting invariants (e.g. every route goes through the audited-transaction seam) — catches violations a ticket's own tests pass
validate-seams.sh Seam-record integrity for module boards: each shared contract has exactly one producer module, every consumer depends on it, and wiring evidence exists (wraps validateSeams() in scripts/lib/tickets-seams.mjs)
validate-scope.match.test.sh Self-test, not a gate: proves the real _scope-match.sh matcher accepts its positive cases and rejects its negative ones

Route discovery covers Express/Fastify/Next.js app router/FastAPI/Flask/Go net-http. Table discovery covers Prisma/TypeORM/Sequelize/Knex/SQLAlchemy/Django/raw SQL.

Orchestration & quality scripts

Deterministic scaffolding in scripts/ — these own control flow and verification so models only do leaf work (which keeps heavy jobs reliable on small local models).

Script Purpose
run-plan.mjs DAG runner — executes a task-decomposer plan.json node by node: topological order, tier-scaled timeouts, pre-flight model-server health check, checkpoint-continue retries, journal-based resume, --auto-replan
fix-verify.mjs Deterministic re-verify gate — snapshot/verify a finding source (semgrep or any validate-*.sh), diff by fingerprint, report CLOSED / STILL-OPEN / NEW, exit non-zero if anything remains or a fix regressed
mermaid-fix.mjs Mechanical Mermaid autofixer (--write) — smart quotes→ASCII, em-dash→hyphen, unicode arrows→-->, quote labels with specials, //→%%
build-agents.mjs Single-source boilerplate — --check/--fix/--compact (generates dist/compact-agents/ tier=small variants)
build-target-claude.mjs Generates the attest-claude copies from this canonical repo (npm run build:claude[:check])
check-tools.sh Detects (and --installs) the optional analysis tools: semgrep, knip, ts-prune, jscpd, vulture, radon, lizard, staticcheck, trufflehog, mmdc. Never sudo: installs npm/pipx tools (retrying into ~/.npm-global on EACCES), prints the real error for failures, and lists remaining system prerequisites as commands for you to run. mmdc is report-only — see SETUP.md
doctor.sh Post-install self-check — structure, deps, config permission, model backend, tier detection, agent discovery, tool presence
detect-model-context.sh Writes docs/work/.model-context (type/provider/model/context/tier + has_task_tool/mcp_in_subagents flags)

Depth modes (v0.15.0)

--quick and --deep flags on /sdlc onboard and /security:

Skill --quick (default) --deep
/sdlc onboard Steps 0–7, no inventory check (~15–20 min) Steps 0–7 + ROUTE/TABLE inventory loop (~30–40 min) + full Ralph Wiggum inventory loop (~45–90 min)
/security Wave 1 scanners + OWASP Web (~10 min) same as --quick All four specialist waves + attack chainer + security-deep coverage loop (~45–90 min)

Deep modes block until their corresponding validator gate exits clean.

Platform support

Platform Status
macOS (bash 3.2.57+) Supported
Linux (bash 4+) Supported
Windows via WSL2 Supported
Windows native (PowerShell/cmd) NOT supported — use WSL2

install.sh refuses to run on native Windows and points to the WSL2 install docs.

Reference documents

Canonical checklists and templates agents read at runtime. Each is plain markdown in references/.

Reference Used by Purpose
git-workflow-checklist.md git-expert Conventional commits, SemVer, Keep-a-Changelog, recovery scenarios, report templates
code-health-checklist.md code-reviewer 8 dimensions, silent-failure hunter, consolidation catalog, language thresholds
owasp-checklist.md security-auditor OWASP Top 10 + verification steps
semgrep-guide.md security-auditor Semgrep setup, rule packs, two-tier scans
semgrep-community-rules.md security-auditor Community rule inventory
severity-matrix.md security-auditor, code-reviewer Severity scoring rubric
rest-api-checklist.md api-designer REST conventions, pagination, errors
design-review-checklist.md ux-engineer Heuristics + WCAG 2.2 baseline
playwright-config.md test-engineer Playwright setup patterns
engineering-artifacts.md sdlc-lead SDLC phase deliverables per phase
report-template.md all agents Common report header + confidence footer
context7-mcp.md all agents Live library docs via Context7 MCP
parallel-worktree-agent-playbook.md orchestrating session Gotchas for briefing multiple agents on separate tickets concurrently: worktree isolation, git-stash cross-worktree collision, --base origin/main, build-target-claude.mjs --out, awk/bash portability traps, fixture/CHANGELOG/merge-gate conventions
jira-adapter.md orchestrating session, sdlc-lead Mirror the ticket lifecycle to Jira Data Center: setup, verbs, SDLC hygiene mapping (grab-issues-not-epics, epic-closes-when-children-done, maker≠verifier, blocking links, lane→component), and graceful fallback to plan.json-only. Wraps scripts/jira/jira.mjs; see docs/DESIGN_JIRA_ADAPTER.md
figma-adapter.md design-system-lead, frontend-design Bring a real Figma design into the design pipeline: pull a file → normalized figma-snapshot.json, derive-tokens → docs/design/tokens.json (which stays authoritative), one-way Figma→code, graceful fallback to prose-authored tokens. Wraps scripts/figma/figma.mjs; see docs/DESIGN_FIGMA_ADAPTER.md

Custom tools

Custom TypeScript tools in tools/. OpenCode loads these at startup.

Tool Purpose
bash.ts Bounded bash execution with timeout + output capture
grep-mcp.ts ripgrep wrapper with structured results
write.ts / append.ts / update.ts File write primitives
file-info.ts Stat + size + mime detection
task.ts Spawn sub-agent tasks
test-runner.ts Language-aware test runner dispatch
playwright-test.ts / playwright-web.ts Playwright harnesses
semgrep-scan.ts / semgrep-rule.ts Semgrep scanning + custom rule authoring
simplify-file.ts Simplification-focused rewrite
pomodoro.ts Work-timer helper
run.ts Generic script runner
log-parser.ts Structured log parsing
loop-detector.ts Detects infinite-loop patterns in agent output
deploy.ts Deploy helper

See tools/CUSTOM_TOOLS_GUIDE.md for authoring a new tool.

Commands

Slash command definitions in commands/ — subcommands of /sdlc:

Command Purpose
sdlc-init.md /sdlc init <name> "<desc>" — start a new project
sdlc-onboard.md /sdlc onboard [--quick | --deep] — understand an existing codebase
sdlc-feature.md /sdlc feature "<description>" — add a feature to existing project
sdlc-improve.md /sdlc improve ["<focus>"] — audit-driven improvement; runs UX / code-quality / perf / security / DB audits, synthesizes a sized backlog, routes execution through coding-agent or Mode 3 sub-workflows
sdlc-gate.md /sdlc gate — SDLC-aware gate check; auto-detects current phase from docs/work/sdlc-state.md and runs the matching validators
sdlc-status.md /sdlc status — show current phase + gate state

Plugins

plugins/expert-hooks.ts — single opencode plugin auto-loaded from ~/.config/opencode/plugins/. Hooks into the two main lifecycle events:

Event What runs
tool.execute.before Block dangerous bash (rm -rf /, git push --force, DROP TABLE, curl|bash, etc.). Block writes to credential files (.env*, *.key, *.pem, id_rsa, credentials.json). Throws to abort the call.
tool.execute.after (write/edit only) format → lint → type-check → secret-scan, all in parallel: prettier / black+isort / gofmt / rustfmt; eslint / ruff; tsc --noEmit; regex scan for hardcoded API keys, AWS creds, PEM keys, DB connection strings. Findings surface via console.warn — informational, never block. Missing formatters silently skipped.

Ports the high-value subset of the attest-claude hook catalog. Not ported (different abstractions): commit-validator.sh (use a project-level git pre-commit hook), test-on-stop.sh (no clean opencode session-idle semantic), session-start.sh (opencode lacks a UserPromptSubmit equivalent).

Hooks

Currently empty. The original hooks/pre-operation.sh was an orphan superseded by tools/loop-detector.ts and the schema guards in tools/{append,bash,run,write}.ts. Loop prevention now lives in those tools + the inlined LOOP_PREVENTION cheat-sheet at the top of every SDLC mode file. Quality + safety automation lives in the plugin above.