# Deep Review > Autonomous iterative code-review loop with externalized state, convergence detection, P0/P1/P2 findings, fresh context per pass. - **Type:** Skill - **Install:** `agentstack add skill-michelkerkmeester-opencode-skilled-agent-loops-with-spec-kit-memory-deep-review` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [MichelKerkmeester](https://agentstack.voostack.com/s/michelkerkmeester) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [MichelKerkmeester](https://github.com/MichelKerkmeester) - **Source:** https://github.com/MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory/tree/main/.opencode/skills/deep-loop-workflows/deep-review ## Install ```sh agentstack add skill-michelkerkmeester-opencode-skilled-agent-loops-with-spec-kit-memory-deep-review ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Autonomous Deep Review Loop Iterative code review and quality auditing protocol with fresh context per iteration, externalized state, convergence detection, and severity-weighted findings (P0/P1/P2). Runtime path resolution: - OpenCode/Copilot runtime: `.opencode/agents/*.md` - Claude runtime: `.claude/agents/*.md` - Codex runtime: `.codex/agents/*.toml` Convergence threshold semantics and sibling-parity notes (deep-review 0.10 vs deep-research 0.05 vs deep-ai-council 0.20) live in `references/convergence/convergence.md` §1 under "Threshold Semantics and Sibling Parity". ## 1. WHEN TO USE ### When to Use This Skill Use this skill when: - Code quality audit requiring multiple rounds across different review dimensions - Spec folder validation requiring cross-reference checks between docs and implementation - Release readiness check before shipping a feature or component - Finding misalignments between spec documents and actual code - Verifying cross-references across documentation, agents, commands, and code - Iterative review where each dimension's findings inform subsequent dimensions - Unattended or overnight audit sessions ### When NOT to Use - Simple single-pass code review (use `sk-code-review` instead) - Known issues that just need fixing (go directly to implementation) - Implementation tasks (use `sk-code` or `/speckit:implement`) - Quick one-file checks (use direct Grep/Read) - Fewer than 2 review dimensions needed (single-pass suffices) ### FORBIDDEN INVOCATION PATTERNS This skill is invoked EXCLUSIVELY through the `/deep:review` command. The command's YAML workflow owns state, dispatch, and convergence. **NEVER:** - Write a custom bash/shell dispatcher to parallelize iterations (ad-hoc shell fan-out) - Invoke cli-codex / cli-claude-code directly in a loop to simulate iterations - Manually write iteration prompts to `/tmp` and dispatch them via `copilot -p` - Dispatch the `@deep-review` LEAF agent via the Task tool for iteration loops (the agent is LEAF, a single iteration, and MUST be driven by the command's workflow) - Skip the state machine: `deep-review-state.jsonl`, `deep-review-config.json`, `deltas/`, `prompts/`, `logs/` - Manage iteration state outside the resolved local review packet under `{spec_folder}/review/` **COMMAND-DRIVEN FAN-OUT IS SUPPORTED:** use `--executor`/`--executors`/`--concurrency` flags on `/deep:review`. The command's YAML `step_fanout_spawn` owns multi-lineage dispatch; `fanout-merge.cjs` applies strongest-restriction (any lineage active P0 → merged FAIL). This is not ad-hoc shell dispatch — it is the canonical fan-out path. Intra-lineage wave orchestration remains deferred. **ALWAYS:** - Invoke via `/deep:review :auto` or `/deep:review :confirm` - Let the command's YAML workflow own dispatch (auto: `.opencode/commands/deep/assets/deep_review_auto.yaml`) - Let `scripts/reduce-state.cjs` be the SINGLE state writer - Require every iteration to produce BOTH the markdown narrative AND the JSONL delta (dispatch scripts must fail if either is missing) - Use `resolveArtifactRoot(specFolder, 'review')` from `.opencode/skills/system-spec-kit/shared/review-research-paths.cjs` to locate the canonical review root ### Trigger Phrases - "review code quality" / "audit this code" - "audit spec folder" / "validate spec completeness" - "release readiness check" / "pre-release review" - "find misalignments" (between spec and implementation) - "verify cross-references" (across docs and code) - "deep review" / "iterative review" / "review loop" - "quality audit" / "convergence detection" ### Keyword Triggers `deep review`, `code audit`, `iterative review`, `review loop`, `release readiness`, `spec folder review`, `convergence detection`, `quality audit`, `find misalignments`, `verify cross-references`, `pre-release review`, `audit spec folder` --- ## 2. SMART ROUTING ### Resource Loading Levels | Level | When to Load | Resources | |-------|-------------|-----------| | ALWAYS | Every skill invocation | `references/protocol/quick_reference.md` | | CONDITIONAL | If intent signals match | Loop protocol, convergence, state format, review contract | | ON_DEMAND | Only on explicit request | Full protocol docs, detailed specifications | ### Smart Router Pseudocode - Pattern 1: Runtime Discovery - `discover_markdown_resources()` recursively inventories `references/` and `assets/`. - Pattern 2: Existence-Check Before Load - `load_if_available()` guards markdown paths, checks `inventory`, and uses `seen`. - Pattern 3: Extensible Routing Key - `get_routing_key()` derives the review phase from dispatch context. - Pattern 4: Multi-Tier Graceful Fallback - `UNKNOWN_FALLBACK` returns review disambiguation and missing phases return a "no review resources" notice. ```python from pathlib import Path SKILL_ROOT = Path(__file__).resolve().parent RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets") DEFAULT_RESOURCE = "references/protocol/quick_reference.md" INTENT_SIGNALS = { "REVIEW_SETUP": {"weight": 4, "keywords": ["deep review", "review mode", "code audit", "iterative review", ":review", "audit spec"]}, "REVIEW_ITERATION": {"weight": 4, "keywords": ["review iteration", "dimension review", "review findings", "P0", "P1", "P2"]}, "REVIEW_CONVERGENCE": {"weight": 3, "keywords": ["review convergence", "coverage gate", "verdict", "binary gate", "all dimensions"]}, "REVIEW_REPORT": {"weight": 3, "keywords": ["review report", "remediation", "verdict", "release readiness", "planning packet"]}, } NOISY_SYNONYMS = { "REVIEW_SETUP": {"audit code": 2.0, "review spec folder": 1.8, "release readiness": 1.5, "pre-release": 1.5}, "REVIEW_ITERATION": {"review dimension": 1.5, "check correctness": 1.4, "check security": 1.4, "check alignment": 1.4}, "REVIEW_CONVERGENCE": {"all dimensions covered": 1.6, "coverage complete": 1.5, "stop review": 1.4}, "REVIEW_REPORT": {"review results": 1.5, "what to fix": 1.4, "ship decision": 1.6, "final report": 1.5}, } # RESOURCE_MAP: local markdown assets + local review-specific protocol docs RESOURCE_MAP = { "REVIEW_SETUP": [ "references/protocol/loop_protocol.md", "references/state/state_format.md", "references/state/state_outputs.md", "references/state/state_reducer_registry.md", "assets/deep_review_strategy.md", ], "REVIEW_ITERATION": [ "references/protocol/loop_protocol.md", "references/convergence/convergence.md", "references/convergence/convergence_signals.md", ], "REVIEW_CONVERGENCE": [ "references/convergence/convergence.md", "references/convergence/convergence_signals.md", "references/state/state_outputs.md", ], "REVIEW_REPORT": [ "references/state/state_format.md", "references/state/state_outputs.md", "references/state/state_reducer_registry.md", "assets/deep_review_dashboard.md", ], } LOADING_LEVELS = { "ALWAYS": [DEFAULT_RESOURCE], "ON_DEMAND_KEYWORDS": ["full protocol", "all templates", "complete reference", "resume deep review", "deep-review wave", "review artifact", "release-readiness audit", "convergence-tracked", "same session lineage", "P0"], "ON_DEMAND": [ "references/protocol/loop_protocol.md", "references/state/state_format.md", "references/convergence/convergence.md", "references/convergence/convergence_signals.md", "references/state/state_outputs.md", "references/state/state_reducer_registry.md", ], } PHASE_RESOURCE_MAP = { "init": ["references/protocol/loop_protocol.md", "references/state/state_format.md", "references/state/state_outputs.md"], "iteration": ["references/protocol/loop_protocol.md", "references/convergence/convergence.md", "references/convergence/convergence_signals.md"], "stuck": ["references/convergence/convergence.md", "references/convergence/convergence_signals.md", "references/protocol/loop_protocol.md", "references/state/state_reducer_registry.md"], "synthesis": ["references/state/state_format.md", "references/state/state_outputs.md", "references/state/state_reducer_registry.md", "assets/deep_review_dashboard.md"], } NON_MARKDOWN_REFERENCES = { "review_contract": "assets/review_mode_contract.yaml", } UNKNOWN_FALLBACK_CHECKLIST = [ "Confirm the review target or spec folder", "Confirm the review phase", "Provide one concrete file, diff range, or expected finding class", "Confirm the verification command set before final review", ] def _guard_in_skill(relative_path: str) -> str: resolved = (SKILL_ROOT / relative_path).resolve() resolved.relative_to(SKILL_ROOT) if resolved.suffix.lower() != ".md": raise ValueError(f"Only markdown resources are routable: {relative_path}") return resolved.relative_to(SKILL_ROOT).as_posix() def discover_markdown_resources() -> set[str]: docs = [] for base in RESOURCE_BASES: if base.exists(): docs.extend(path for path in base.rglob("*.md") if path.is_file()) return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs} def get_routing_key(dispatch_context) -> str: phase = str(getattr(dispatch_context, "phase", "")).strip().lower() if phase: return phase text = str(getattr(dispatch_context, "text", "")).lower() if "recovery" in text: return "stuck" if "convergence" in text or "synthesis" in text: return "synthesis" if "iteration" in text or "dimension" in text: return "iteration" return "init" def route_review_resources(task, dispatch_context): inventory = discover_markdown_resources() routing_key = get_routing_key(dispatch_context) scores = score_intents(task, INTENT_SIGNALS, NOISY_SYNONYMS) intents = select_intents(scores, ambiguity_delta=1.0) loaded = [] seen = set() def load_if_available(relative_path: str) -> None: guarded = _guard_in_skill(relative_path) if guarded in inventory and guarded not in seen: load(guarded) loaded.append(guarded) seen.add(guarded) for relative_path in LOADING_LEVELS["ALWAYS"]: load_if_available(relative_path) if max(scores.values() or [0]) --strict` exits 0 on the target spec folder. --- ## 7. INTEGRATION POINTS ### Framework Integration This skill operates within the behavioral framework defined in the active runtime's root doc (CLAUDE.md, AGENTS.md, or CODEX.md). Key integrations: - **Gate 2**: Skill routing via `skill_advisor.py` (keywords: deep review, code audit, iterative review) - **Gate 3**: File modifications require spec folder question per the root doc Gate 3. The spec folder determines the `{spec_folder}/review/` state packet location - **Continuity**: `/speckit:resume` is the operator-facing recovery surface. Canonical packet continuity is written via `generate-context.js` - **Command**: `/deep:review` is the primary invocation point ### Continuity Integration Recover context via `/speckit:resume` in the order `handover.md -> _memory.continuity -> spec docs`. During review, the agent writes iteration, strategy, and JSONL state. After synthesis, run `generate-context.js`. ### Code Graph Integration `code_graph_query + Grep` is available to `@deep-review` for semantic code search when Grep/Glob exact matching is insufficient. Use for: - Finding all usages of a pattern by concept/intent - Locating implementations when exact symbol names are unknown - Cross-referencing behavior across unfamiliar code paths ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [MichelKerkmeester](https://github.com/MichelKerkmeester) - **Source:** [MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory](https://github.com/MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-michelkerkmeester-opencode-skilled-agent-loops-with-spec-kit-memory-deep-review - Seller: https://agentstack.voostack.com/s/michelkerkmeester - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.