digital-service-orchestra

Use when the user wants a comprehensive multi-issue health pass — fix all bugs, resolve broken tests, clear CI failures, fix lint and type errors, restore green builds — not for a single targeted bug fix. Diagnoses and resolves every outstanding open bug ticket plus all validation failures (test, lint, type, format, infrastructure) using orchestrated sub-agents with TDD discipline, in tier order. Trigger phrases include 'debug everything', 'fix all bugs', 'fix the failing tests', 'CI is failing', 'build is broken', 'clean up the codebase', 'restore green', 'project health pass'.

Use when wrapping up a worktree session — closing tasks, finishing work, or merging the branch back to main. Closes completed tickets, sweeps orphaned epics, extracts technical learnings, files bug tickets for unfixed failures, commits remaining changes, syncs the tickets branch, merges to main via merge-to-main.sh, verifies the worktree is merged and clean for claude-safe auto-removal, and prints a task summary. Trigger phrases include 'end session', 'wrap up', 'finish', 'done for now', 'close out', 'merge to main and clean up', 'session complete', 'wrap up this branch'.

Use when the user is stuck in a merge conflict, rebase conflict, failed pull, or any git operation that left conflict markers in the working tree. Dispatches a conflict-analyzer sub-agent that classifies each conflicted hunk by confidence (auto-resolvable vs needs-human-review), auto-resolves high-confidence cases, validates the result, and rolls back if validation fails before falling through to human review. Trigger phrases include 'merge conflict', 'resolve conflicts', 'rebase conflict', 'git conflict', 'conflict markers', 'failed rebase', 'git pull conflict', 'fix the conflicts', 'help with this merge'.

Manual review escalation when CI llm-review blocks a PR on a finding that looks like a false positive. Dispatches dso:code-reviewer-standard at opus tier on the PR's diff, parses the result, and emits a force-merge clearance when zero critical/important/fragile findings remain. Use ONLY when CI llm-review has failed on a suspect FP; not for routine PR shipping. Trigger phrases include 'force merge this PR', 'the CI review is wrong', 'false positive from llm-review', 'manual review override', 'FP recovery'.

Use when the user wants to execute an epic, run a sprint, work through a planned epic's stories and tasks, or coordinate multi-agent task execution end-to-end. Routes the epic by complexity (SIMPLE → direct implementation-plan, MODERATE → lightweight preplanning, COMPLEX → full preplanning), runs an SC-coverage gate at haiku/sonnet/opus tiers to confirm story coverage of epic success criteria, plans the task graph, dispatches sub-agents in batches with file-overlap and semantic-conflict checks, runs per-task review and post-batch validation (test gate, lint, AC verification, visual verification for UI), commits/pushes results, and verifies epic completion via the dso:completion-verifier agent before close. Trigger phrases include 'work the epic', 'execute the sprint', 'run the epic', 'sprint this epic', 'work through the stories', 'implement the planned tasks', 'kick off the sprint'.

Use when breaking down an epic into user stories, story splitting, backlog grooming, defining acceptance criteria, or auditing and reconciling existing epic children before implementation. Dispatches an opus `dso:story-decomposer` sub-agent to draft prioritized vertical-slice user stories with measurable done definitions tied to epic Success Criteria (never inline), identifies dependencies, runs an adversarial red-team review pass, dispatches a UI designer for UI stories, and writes the story tickets to the tracker. Trigger phrases include 'break down this epic', 'split into stories', 'story splitting', 'backlog grooming', 'write user stories', 'define acceptance criteria', 'plan the epic', 'decompose the epic', 'reconcile epic children'.

Use when fixing a single bug, debugging an error or crash, investigating a defect, or routing a bug report through structured investigation. Classifies the bug by type and severity, runs pre-investigation gates (intent search, feature-request check), dispatches a tiered investigation sub-agent (BASIC/INTERMEDIATE/ADVANCED) to identify root cause, applies a TDD fix loop with RED-before-GREEN discipline, and runs post-fix gates before commit. Trigger phrases include 'fix this bug', 'debug this', 'investigate this issue', 'something is broken', 'there is a problem with', 'crash', 'error', 'defect', 'regression', 'bug triage'.

Generate a project-specific CLAUDE.md file from .claude/dso-config.conf and the Digital Service Orchestra template

Initialize project with Digital Service Orchestra config

Use when running a smoke test, sanity check, health check, or status check before closing work — also when the user asks 'is everything working', 'verify the deployment', or 'check the build'. Dispatches read-only sub-agents that run local validate.sh, check CI pipeline status, probe staging deployment health, and ping live-environment endpoints in parallel; gates Batch 2 (live env) on Batch 1 passing; reports PASS/WARN/FAIL per domain with recommended actions. Detects and reports — never fixes. Trigger phrases include 'smoke test', 'sanity check', 'health check', 'status check', 'is everything working', 'verify deployment', 'run the checks', 'is the build green', 'validate before close'.

Use when an agent or user needs to file a bug, report an issue, create a defect ticket, or capture a sub-agent blocker. Creates well-formatted, evidence-based bug tickets by collecting reproduction steps, expected vs. actual behavior, environment details, and logs, then writing the ticket via the ticket CLI using the shared bug report template. Trigger phrases include 'file a bug', 'report an issue', 'create a bug', 'open a ticket', 'log a defect', 'submit a bug report'.

Use when a user story or simple epic needs to be broken into atomic, TDD-driven implementation tasks with architectural review, or when planning the TDD task breakdown for a specific story or task ticket. Produces an ordered task list with explicit RED-test specs, identifies file impact and consumer/contract dependencies, runs an architectural review pass with a pass_threshold of 5, and writes the task tickets to the tracker with TDD task structure. Trigger phrases include 'plan this story', 'break this into tasks', 'implementation plan', 'plan the work', 'generate tasks', 'TDD task breakdown', 'how should I implement this story'.

Use when starting a new feature or epic — turns a feature idea into a defined, ticket-ready epic through Socratic dialogue with the user. Designs technical approaches, breaks features into milestones, drafts ticket descriptions and success criteria, and writes the epic to the ticket tracker. Trigger phrases include 'plan a feature', 'spec out a feature', 'break down work', 'create user stories', 'start a new epic', 'turn this idea into tickets', 'roadmap a feature'.

Use when performing periodic project health reviews, repo maintenance, code cleanup, dead-code sweeps, unused-dependency audits, stale-branch / stale-worktree cleanup, test quality / coverage-gap audits, CI failure pattern review, or technical-debt triage. Runs retro-gather.sh to collect CI failure metrics, TODO-family comment counts, validation health, and worktree state; classifies each finding via a shift-left analysis (was this catchable earlier?); produces a candidate task list (P3 maintenance tickets, Quick Wins for <5-minute removals, follow-ups) and writes the approved tasks to the tracker. Trigger phrases include 'project health check', 'code cleanup', 'dead code', 'unused dependencies', 'stale branches', 'stale worktrees', 'coverage gaps', 'repo maintenance', 'tech debt', 'retro', 'audit the tests', 'CI is flaky'.

Use when starting a new DSO project, joining an existing one, getting started in an unfamiliar codebase, doing a codebase walkthrough, or running project setup. Auto-detects the stack, scans existing docs, runs a Socratic dialogue to capture architecture / infrastructure / CI / design system / enforcement preferences, then writes dso-config.conf, CLAUDE.md, ticket-system seed files, and pre-commit hooks. Optionally installs a project template (nava-platform or Jekyll). Trigger phrases include 'onboard this project', 'set up DSO', 'getting started', 'project setup', 'codebase walkthrough', 'understand the codebase', 'run onboarding', 'init the project'.

Dispatch a code review of the current diff using the tiered LLM review workflow (light/standard/deep). Reads REVIEW-WORKFLOW.md and executes it inline. Use before committing or when CLAUDE.md says to run /dso:review. Trigger phrases include 'run a code review', 'review my changes', 'do a code review', '/dso:review', 'code review'.

Use when reviewing proposed designs (code, wireframes, screenshots) against an established DESIGN.md, or when enforcing design system compliance before merging UI changes. Checks color tokens, typography, spacing, component usage, layout, and accessibility against the project's design notes and produces a report card with critical violations, UX/accessibility risks, alignment wins, and optional refined code. Trigger phrases include 'design review', 'style guide check', 'visual consistency', 'component library compliance', 'design system check', 'review this UI', 'check design tokens'.

Use when the user wants to dry-run a DSO skill, simulate its execution, or preview its planned changes without executing them. Wraps any /dso:* skill invocation with override rules that block all mutating operations (ticket writes, file edits, git commits) while still running read-only steps; emits [DRYRUN] preview blocks for each blocked mutation and a final summary of what would have changed. Trigger phrases include 'dry run', 'simulate', 'what-if', 'test run', 'no-op', 'preview without changes', 'show me what would happen'.

Use when the user wants to (re)prioritize an existing backlog of epics — assigns P0–P4 priorities across all open epics based on a stakeholder-defined North Star, risk tolerance, tradeoffs, and out-of-scope criteria. Runs a 5-phase pipeline that (1) assesses each epic's clarity, distills the overall vision, compares it to current state, and maps risk hotspots; (2) interviews the stakeholder via Socratic dialogue to capture the prioritization rubric; (3) coarse-sorts epics into North Star / optional additions / out of scope using batched sub-agent evaluation; (4) granular-sorts within each bucket into P0–P4; (5) offers to brainstorm any P0/P1 epics that lack the `brainstorm:complete` tag. Trigger phrases include 'prioritize the epics', 'reprioritize the backlog', 'set epic priorities', 'sort the backlog', 'rank the epics', 'what should we work on next at the epic level'.

Use when the user wants to transform a high-level product vision, PRD, or project idea into a prioritized roadmap of epics, or to plan an initial milestone breakdown for a new project. Runs a 6-phase pipeline that expands the vision via "tell me more" sessions, drafts epic-level milestones with success criteria, scores each epic on a 1–5 value/effort scale, identifies critical-enabler dependencies, places each epic on a quick-wins/strategic-bets/fill-ins/avoid quadrant, runs a lightweight pre-mortem on top-priority epics, and writes the prioritized epics with P0–P4 priorities and dependency links to the ticket tracker. Trigger phrases include 'roadmap this', 'plan the project', 'build a roadmap', 'turn this PRD into epics', 'prioritize the milestones', 'what should we build first'.

Use when starting an epic's wireframe designs, scanning a frontend for UI components, cataloguing existing routes, or inventorying frontend state. Generates or refreshes the UI Discovery Cache: inventories components via Glob/Grep, crawls routes via Playwright, and writes structured results to .ui-discovery-cache/. Produces a deterministic validation script for git-based cache invalidation. Trigger phrases include 'scan UI components', 'discover routes', 'catalog UI elements', 'inventory frontend components', 'refresh ui-discovery-cache', 'before designing wireframes'.

Captures Playwright screenshots at routes from .ui-discovery-cache/route-map.json and invokes the visual-evaluator agent with explicit precondition gating. Degrades observably when prerequisites fail.

Use when an engineer wants to classify and respond to all unresolved PR review comments on a pull request. Fetches unresolved comments, classifies each as accept/defend/defer using an embedded LLM prompt, dispatches the appropriate action handler, and prints a summary table. Trigger phrases include 'respond to PR comments', 'address PR comments', 'handle PR feedback', 'respond to review comments', 'respond to my PR', '/dso:respond-to-pr-comments'.

Bootstrap skill loaded automatically at conversation start. Establishes the rule that the agent MUST invoke a matching skill via the Skill tool BEFORE any response, including clarifying questions and "simple" answers. Covers Skill tool invocation, fallback procedures (silent injection failure / 'Unknown skill'), feature-intent detection (route to /dso:brainstorm before /dso:sprint), sub-agent delegation triggers, and friction recording. Trigger phrases include 'help', 'what can you do', 'can you', 'fix', 'add', 'build' — i.e., any user message that requests action.

Use when the user wants to critically review and refactor an existing DSO skill for clarity, token efficiency, and reliability — includes script relocation, reference updates, change-detector test removal, and ticket reconciliation. Invoke when the user says "review the [skill] skill", "optimize [skill]", "clean up [skill]", or similar language about auditing or improving a specific skill file.

Use when the user asks about review metrics, review analytics, reviewer performance, the review dashboard, review trends, resolution rates, or how /dso:review has been performing over time. Runs review-stats.sh and displays its output as-is — reviewer tier distribution (light/standard/deep), autonomous resolution rates, severity-distribution trends, and time-bucketed counts. Trigger phrases include 'review stats', 'review metrics', 'review analytics', 'reviewer performance', 'review dashboard', 'how is review going', 'tier distribution'.

Surfaces calibration program health by running the monthly and quarterly calibration reports. Use when checking test-quality calibration trends, reviewing reviewer calibration data, or auditing the calibration program status. Trigger phrases include '/dso:test-quality-report', 'run calibration report', 'show calibration health', 'test quality report'.

Use when 5+ fix attempts have cascaded into new failures, when the cascade circuit-breaker fires (CLAUDE.md `rule:cascade-circuit`), or when repeated edits are propagating errors instead of resolving them. Stops further edits, assesses blast radius via git diff, decides whether to fully revert / selectively revert / keep changes, attaches cascade context to the active ticket, hands off to /dso:fix-bug for informed investigation, and resets the circuit-breaker counter. Trigger phrases include 'cascade circuit-breaker fired', 'too many failed attempts', 'rollback cascading changes', 'revert this mess', 'stop the edits', 'recover from a cascade', 'undo cascading edits'.

Use when planning a feature where multiple components implement the same boundary, work can be parallelized across agents, or several tasks are blocked by a shared dependency. Defines an abstract base class or Protocol with @abstractmethod decorators, complete type hints, behavior-documenting docstrings, and contract tests; sets up the interface task plus per-implementation tasks with depends_on links so multiple agents can work in parallel. Trigger phrases include 'interface contract', 'parallel implementation', 'shared boundary', 'multi-agent coordination', 'contract-first', 'unblock parallel work', 'define an ABC', 'set up a Protocol'.

Use before presenting an implementation plan or design document to the user, before calling ExitPlanMode, or whenever you want a quality check on a plan/design ('check this plan', 'review my design before I share it', 'validate plan completeness'). Dispatches a sub-agent that scores the plan/design across four dimensions — feasibility, completeness, YAGNI, codebase alignment — and either passes it through or revises critical/major findings before user presentation. Orchestrator-level only; refuses sub-agent invocation. Trigger phrases include 'review this plan', 'check the design', 'validate the plan', 'before showing the user', 'pre-approval review', 'plan quality check'.

Use to remediate epics flagged by the architecture-vs-evidence audit (tag `arch-evidence:remediation-needed`). Reads the audit findings for the named epic, applies probe-specific patterns established in the 2026-05-18 reference remediation pass (self-use SCs, state-lifecycle tables, bypass governance pairings, in-session CLI verification for external deps), and updates tags. Default scope is single-epic; batch mode permitted on opus-tier sessions with priming-mitigation discipline. Trigger phrases include "remediate epic <id>", "remediate <id> for architecture-vs-evidence", "fix arch-evidence gaps in <id>", "address audit findings on <id>".

Use before implementing review feedback when iteration N+1 of a review loop is about to revert changes made in iteration N — i.e., when reviewers seem to be giving contradictory feedback, flip-flopping between approaches, asking to undo a prior fix, or going back and forth on the same lines. Detects oscillation by comparing the structural diff of the current proposed change against the prior accepted change; flags reverts as OSCILLATION with a recommended action (escalate, hold for user, or accept with annotation). Trigger phrases include 'contradictory feedback', 'flip-flopping reviews', 'going back and forth', 'reviewer keeps changing their mind', 'undo the last fix', 'revert what we just did'.

Use when the user wants to set up architecture rules, code standards, guardrails, fitness functions, lint configs, or enforce project conventions after onboarding has run. Reads .claude/project-understanding.md (written by /dso:onboarding) and uses Socratic dialogue to surface enforcement preferences and anti-pattern risks, then generates targeted enforcement scaffolding (CI checks, lint rules, fitness functions, ADRs) without re-running project detection. Trigger phrases include 'set up code standards', 'add architecture rules', 'enforce conventions', 'add guardrails', 'lock in patterns', 'set up linting', 'add fitness functions'.

Use when debugging a visual bug, layout issue, CSS problem, rendering issue, broken UI, page-looks-wrong report, or any browser-visible defect. Enforces a 3-tier hypothesis-first process that minimizes @playwright/cli token usage — generates hypotheses from static code analysis (Tier 1), confirms them with targeted in-browser JS evidence (Tier 2, ≤3 run-code calls), and only escalates to full browser interaction (Tier 3) when prior tiers are exhausted. Trigger phrases include 'visual bug', 'layout issue', 'CSS problem', 'rendering issue', 'broken UI', 'the page looks wrong', 'screenshot regression', 'browser bug', 'frontend bug', 'why is this element off-screen'.

Use when the user wants to see what DSO skills and scripts are available, list installed plugin commands, or look up the description of a skill they don't recognize. Auto-discovers and displays every script under the plugin scripts directory and every skill under the plugin skills directory, with each entry's description extracted from script comments or skill YAML frontmatter. No hardcoded lists — everything resolves dynamically at invocation time. Trigger phrases include 'list available skills', 'what skills are available', 'show plugins', 'what tools are installed', 'what can DSO do', 'list dso commands', 'show plugin scripts'.

Use when a calling skill (e.g., /dso:implementation-plan, /dso:design-review, /dso:preplanning architectural-pattern check) needs to run a multi-perspective review of an artifact (plan, design, pattern). The caller passes subject, artifact, a perspectives list (each is a reviewer file), pass_threshold, start_stage, max_revision_cycles, and caller_id; this skill dispatches one sub-agent per perspective, scores on configured dimensions, detects conflicts between reviewers, runs a revision cycle up to max_revision_cycles, and returns JSON per the standardized REVIEW-SCHEMA. Not user-invocable directly — it is the shared review engine that calling skills delegate to instead of writing ad-hoc review logic.

Use when checking ticket health, cleaning up stale tickets, fixing dependency cycles, or validating that tickets are ready for sprint execution. Runs validate-issues.sh against the DSO ticket tracker to score health 1–5, surfaces common issues (orphan epics, missing acceptance criteria, dependency cycles, blocked-everywhere tasks, stale in_progress, broken interface tasks), and provides per-issue fix commands. Trigger phrases include 'ticket health', 'validate tickets', 'stale tickets', 'issue cleanup', 'check ticket dependencies', 'fix dependency cycle', 'are the tickets clean', 'audit the tracker'.

Use after an epic completes, after a substantive merge, when documentation is out of sync with the code, or when the user asks to update docs / regenerate the README / refresh stale documentation. Invokes the doc-writer agent to update project documentation based on the recent changes scoped to a commit range (default main...HEAD). Trigger phrases include 'update the docs', 'docs are outdated', 'stale README', 'regenerate docs', 'doc generation', 'refresh documentation', 'sync the docs after this epic'.

Use before saying 'done', 'finished', 'ready to merge', 'tests pass', 'all green', 'looks good', 'ship it', or any other completion claim — and before committing, creating a PR, or transitioning a ticket to closed. Forces evidence-before-assertion by requiring the actual verification command (validate.sh --ci, make lint-ruff, make lint-mypy, the test suite, etc.) and confirm exit-0 output before any success claim. State the command and the observed output, never an unverified status. Trigger phrases include 'done', 'finished', 'ready to merge', 'tests pass', 'all green', 'looks good', 'ship it', 'work is complete'.