Domain Reviewer

Three modes: Audit (autonomous loop), Retire (post-completion), and Retire-Session (session plan consolidation).

Skill root: ~/.claude/skills/domain-reviewer/ — all relative paths below resolve from here.

Auth Service Requirements (All Modes)

The shared auth/payments/identity service ({auth_packages_root} from mode config) is the canonical authentication, payments, and identity layer.

Audit and retire decisions must treat existing auth service packages as the source of truth for auth/payments/identity behaviors.
If implementation needs functionality not covered by current auth service packages, require an "auth-scope proposal" instead of accepting local replacement layers.
If local unpublished auth service versions are used via symlink/link, require final verification against published/live auth service packages before considering a slice fully compliant.

Delivery Strategy Guardrails (All Modes)

Default expectation is big-bang target-state delivery.
Flag unrequested compatibility mechanics (legacy endpoints, dual routing, adapter layers, shadow write/read paths) as scope violations.
If production data is affected, require a dedicated DB transition section with backup, raw psql execution plan, transactional/idempotent safety, verification, and rollback.

Audit: Autonomous audit→fix→retire loop — runs worker phases (subagents if available, inline fallback), converges to 94%, then retires
Retire: Investigate completed slices, categorize user stories, clean up bloat
Retire-Session: Roll DONE session plans into domain COMPLETED.md files, archive originals

Execution Profiles

This skill is agent-platform neutral. Pick the profile your runtime supports:

Profile A: Subagent-capable runtimes (Claude Task agents, Agents SDK with worker agents, similar)
- Run audit/re-review/fix as separate worker runs with fresh context where possible.
- Orchestrator coordinates handoffs, score parsing, and loop control.
Profile B: Single-agent runtimes (Codex CLI session without subagent primitives)
- Run the same phases inline in one session.
- Simulate fresh context by re-reading required files at each phase.
- Keep phase boundaries explicit: AUDIT -> SCORE CHECK -> FIX -> repeat.

Terminology bridge used throughout this skill:

This skill says	Means
"Task agent" / "subagent"	Worker phase execution unit
"Spawn"	Delegate if runtime supports it; otherwise execute inline
"Orchestrator"	The active agent/session coordinating loop decisions

Subagent Runtime Setup (Codex MCP + Agents SDK)

When using a subagent-capable runtime with Codex:

Start one Codex MCP server rooted at the target repo (cwd = repo root).
Run one orchestrator worker plus scoped workers (audit, fix-backend, fix-frontend, retire).
Give each worker explicit owned paths (for example backend/** vs frontend/**).
Keep shared files single-owner/sequential (orchestrator-owned).
No extra worktrees required; workers collaborate in the same repository.
Reuse references/codex-mcp-orchestration-template.md for standard worker prompts.
For prompt generation/launch, use python3 ~/.claude/skills/domain-reviewer/scripts/launch_codex_worker.py.
For full audit loop automation, use python3 ~/.claude/skills/domain-reviewer/scripts/run_codex_audit_loop.py.

Plan Storage (Mode-Defined)

Plan storage comes from the active reviewer mode file (~/.claude/skills/domain-reviewer/modes/{mode}.md):

plan_root: <mode value>
plan_index: <mode value>
session_plan_index: <mode value>

To find a slice: read {plan_root}/{slice}/. To check what exists: read {plan_index}. DO NOT search the filesystem for plans.

Modes (Implementation Context)

Modes provide implementation context and plan storage paths for reviewer workflows.

Check ~/.claude/skills/domain-reviewer/modes/ for project-specific configuration. Each mode defines:

cwd_match -- directory pattern for auto-detection
Implementation locations -- backend and frontend repos with path patterns
Compliance standards -- backend convention files, frontend patterns reference
Tag-to-domain mapping -- maps plan tags to domain folders (for retire-session mode)
Commit conventions -- message formats for audit and retire commits

If no mode matches the current directory:

You can still run workflows if explicit plan paths are provided via CLI arguments.
For retire mode, implementation context can be minimal, but plan storage paths are still required.
For audit mode, list available modes (from ~/.claude/skills/domain-reviewer/modes/*.md filenames) and ask the user which to use when auto-detection fails.
DO NOT search the filesystem. DO NOT launch extra discovery workers.

See references/mode-template.md for the mode file format.

Mode Detection

User Says	Mode	Read
"review", "audit"	Audit	references/orchestration-workflow.md
"retire", "close out", "consolidate", "clean up", "finalize" + slice name	Retire	references/retire-workflow.md
"retire session plans", "consolidate session plans", "clean up session plans"	Retire-Session	references/retire-session-workflow.md

After detecting mode, read the corresponding workflow reference file and follow it.

Note: "re-review" and "check fixes" are no longer user-triggered — they happen automatically within the audit orchestration loop.

Context Detection

On trigger, detect project context from the mode file (match CWD to cwd_match patterns).

The mode file specifies:

Which repos to audit (backend, frontend, or both)
Where implementation code lives (path patterns per layer)
Which convention files define compliance standards
Where plan artifacts are stored

Before auditing, read the mode's convention files for the compliance standards to check against.

On Trigger

Ask for slice name if not provided: "Which slice should I review? (e.g., protocol-actions, key-insights)"
Detect mode from user's words (see Mode Detection table above)
Read the corresponding workflow reference file
Follow that workflow's step-by-step process

Audit Mode: Orchestrator Behavior

In audit mode, you are the orchestrator. Use worker phases for heavy work (delegate when supported, otherwise execute inline):

Read mode file + reference files (audit-workflow.md, audit-template.md, convention files)
Enter the autonomous loop (see orchestration-workflow.md)
Run audit/re-review worker phase with full instructions and clean inputs
Parse scores from AUDIT_REPORT.md after each cycle
Dispatch fix worker phase(s) when score < 94%
Enforce auth service compliance in auth/payments/identity scope: no local replacement layer, gaps captured as auth-scope proposals, local-link flow finalized on published/live packages
Enforce delivery strategy compliance: no unrequested legacy compatibility code; DB-transition runbook required when production data is impacted
On convergence (>= 94%): transition to retirement — you do this yourself (you have context budget)
On max iterations (5): escalate to user with current score + remaining issues

Concurrency Contract

When running multiple workers in parallel in the same repository:

Assign explicit owned file scopes per worker.
Shared files have a single owner (typically orchestrator), edited sequentially only.
- Examples: package.json, lockfiles, root configs, shared index files.
Workers must not run destructive git operations or revert teammate changes.
- Forbidden unless explicitly requested by user: git reset --hard, git checkout --, mass revert commands.
If a worker needs to touch another scope, it asks for a handoff instead of editing directly.

Severity Levels

Level	Impact	Example
Critical	Blocks deploy	Zero test coverage, security hole
High	Major deviation	Placeholder returning fake data
Medium	Notable gap	Signature changed without docs update
Low	Minor issue	Inline loading state vs shared component

Centralized Plan Tracking

Plans, COMPLETED.md, AUDIT_REPORT.md, and INDEX.md all live under mode-defined plan_root:

{plan_root}/{slice}/

Implementation code lives in context-specific repos, but plan artifacts remain centralized by mode.

If the released folder for a slice doesn't exist yet (e.g., slice was built ad-hoc without formal planning), create it before writing COMPLETED.md or AUDIT_REPORT.md.

Automated Handoffs (Audit Mode)

In audit mode, handoffs to fix workers are automated by the orchestrator — no manual copy-paste needed.

The orchestrator:

Reads the ## Agent Handoffs section from AUDIT_REPORT.md
Augments each handoff block with mode-specific paths and convention file references
Runs worker phase(s) with the constructed prompts (delegated or inline)
Backend and frontend fix workers run in parallel when both have issues and scopes are disjoint

The handoff blocks in AUDIT_REPORT.md still reference companion skills by name for documentation, but the orchestrator constructs the actual worker prompts with all necessary context included.

Issue Type	Worker Gets	Key Context
Backend fixes	Handoff block + backend convention file paths + plan paths	TDD-first, domain structure
Frontend fixes	Handoff block + frontend patterns reference path + plan paths	Component patterns, hooks

Related Skills

domain-planner -- Creates the plans this skill audits
domain-scaffolder-backend -- Generates backend code from plan (TDD-first)
domain-scaffolder-frontend -- Generates frontend code from plan (pattern-adherent)
divide-and-conquer -- Decompose multi-agent work into independent parallel concerns