# Deep Ai Council

> AI Council: multi-seat planning, artifact persistence, convergence checks, packet-local ai-council outputs.

- **Type:** Skill
- **Install:** `agentstack add skill-michelkerkmeester-skilled-harness-spec-driven-agent-loops-deep-ai-council`
- **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/skilled-harness__spec-driven-agent-loops/tree/main/.opencode/skills/system-deep-loop/deep-ai-council

## Install

```sh
agentstack add skill-michelkerkmeester-skilled-harness-spec-driven-agent-loops-deep-ai-council
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AI Council

Planning-only council deliberation with diverse seats, convergence checks, and packet-local `ai-council/**` artifact persistence.

> Convergence threshold semantics: see [`references/convergence/convergence-signals.md`](references/convergence/convergence-signals.md). Deep Mode (iterative multi-topic): see [`references/convergence/depth-dispatch.md`](references/convergence/depth-dispatch.md).

---

## 1. OPERATIONAL MODES — IN-CLI (PRIMARY) + EXTERNAL-CLI (SECONDARY)

The council is **primarily an IN-CLI capability**. When invoked from inside an active runtime (OpenCode, Claude Code, OpenCode), the council deliberates using THAT runtime's own models and reasoning lenses as seats. No external dispatch is required for the common case — the active CLI's own model bench (e.g. Opus + Sonnet + Haiku on Claude Code; gpt-5.5 + gpt-5.5-pro + gpt-5.5-xhigh on OpenCode; direct DeepSeek, Xiaomi, and OpenAI provider models on OpenCode) supplies the seat diversity for a round.

**External-CLI dispatch is a SECONDARY, optional mode** for cases where a different AI vantage adds value (e.g. DeepSeek/Kimi via cli-opencode from inside another runtime). The council resolver accepts `native`, `cli-opencode`, `cli-cursor`, `cli-devin`, `cli-pi`, and the `opencode` alias; it rejects `cli-codex` and `cli-claude-code`. External dispatch is invoked via the supported `cli-*` skill family, never directly from this skill.

**Both modes obey the one-CLI-per-round invariant** (§5 ALWAYS rule 6):
- In-CLI round: all seats use the current runtime's models.
- External-CLI round: all seats use ONE supported external CLI (e.g. all `cli-opencode` seats with different reasoning levels, or all `cli-cursor`, `cli-devin`, or `cli-pi` seats with different models).
- Cross-CLI deliberation is staged as MULTIPLE rounds (one in-CLI + one external, or two different externals) — never folded into the same round.

The default and most common council run is a single in-CLI round. Add external rounds only when the active runtime cannot supply the required vantage or when explicit cross-AI validation is requested.

---

## 2. WHEN TO USE

### Activation Triggers

Use this skill when a request needs:

- Multi-seat AI council deliberation before a plan is chosen.
- Comparison of implementation, refactor, architecture, or research strategies.
- Packet-local persistence of council reports, state, seats, deliberations, and rollback evidence.
- Recovery, audit, or completion checks for existing council artifacts.

### Use Cases

### Council Planning

- Compare two or more implementation plans.
- Ask multiple reasoning lenses to critique a proposed direction.
- Decide whether a plan has enough agreement to proceed.

### Artifact Persistence

- Persist a captured council report into packet-local artifacts.
- Verify append-only state records and final `council_complete` events.
- Preserve failed rounds for forensic inspection.

### Recovery And Audit

- Inspect incomplete council output.
- Check convergence decisions against the two-of-three rule.
- Validate planning-only boundaries before handoff to implementation agents.

### When NOT to Use

Do not use this skill for:

- Direct implementation work, code edits, or spec-doc authorship outside council artifacts.
- Treating council graph rows as source-of-truth or replacing packet-local `ai-council/**` artifacts.
- Single-answer planning where no meaningful strategic disagreement is needed.
- Claims that external AI systems participated when they did not actually run.

### Keyword Triggers

- deep-ai-council
- ai council
- council deliberation
- multi-seat planning
- planning council
- council artifacts
- council convergence
- council graph
- packet-local ai-council

---

## 3. SMART ROUTING

### Primary Detection Signal

```bash
request_text="$(printf '%s' "$USER_REQUEST" | tr '[:upper:]' '[:lower:]')"
case "$request_text" in
  *"deep ai council"*|*"ai council"*|*"council deliberation"*|*"planning council"*) COUNCIL_INTENT=1 ;;
  *"persist council"*|*"ai-council artifact"*|*"council_complete"*) COUNCIL_INTENT=1 ;;
  *) COUNCIL_INTENT=0 ;;
esac
```

### Phase Detection

```text
TASK CONTEXT
    |
    +- STEP 0: Detect council intent, packet persistence intent, recovery/audit intent, or convergence intent
    +- STEP 1: Score intents and keep top-2 when ambiguity is small
    +- Phase 1: Dispatch or simulate diverse council seats
    +- Phase 2: Deliberate, critique, and test convergence
    +- Phase 3: Persist artifacts, verify state, and hand off planning result
```

### Resource Domains

The router discovers markdown resources recursively from `references/`, `assets/`, and `manual-testing-playbook/`, then applies intent scoring from `INTENT_MODEL`.

```text
references/*.md
assets/*.md
manual-testing-playbook/**/*.md
```

- `references/` contains the quick reference, loop protocol, council state, folder layout, seat diversity, output schema, convergence signals, and caller wiring.
- `assets/` contains council config, round strategy, dashboard, prompt-pack, and runtime capability templates. Markdown assets are routable; JSON/TMPL assets are operator/runtime inputs.
- `manual-testing-playbook/` contains operator validation scenarios for routing, deliberation, persistence, convergence, rollback, scope boundaries, council-graph integration, and council-graph value comparison (32 scenarios across 9 categories).
- `feature-catalog/` mirrors the playbook 1:1 with one user-facing feature entry per scenario (32 entries) — start here for "what does DAC-NNN actually do" lookups.
- `scripts/` contains deterministic helpers; scripts are invoked explicitly and are not markdown-routed. Notable entries: `persist-artifacts.cjs` (artifact writer CLI), `replay-graph-from-artifacts.cjs` (DAC-025 derived-projection rebuild — reads `ai-council-state.jsonl` and writes through `runtime//scripts/upsert.cjs --loop-type council`, with `--dry-run` for payload inspection).

### Resource Loading Levels

| Level | When to Load | Resources |
| --- | --- | --- |
| ALWAYS | Every skill invocation | `references/integration/quick-reference.md` |
| CONDITIONAL | Intent signals match | Intent-mapped references from `RESOURCE_MAP` |
| ON_DEMAND | Explicit validation or operator testing | `manual-testing-playbook/manual-testing-playbook.md` and scenario files |

### Smart Router Pseudocode

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets", SKILL_ROOT / "manual_testing_playbook")
DEFAULT_RESOURCE = "references/integration/quick-reference.md"

INTENT_MODEL = {
    "COUNCIL_RUN": {"keywords": [("deep ai council", 5), ("council deliberation", 5), ("planning council", 4), ("strategy comparison", 3)]},
    "COUNCIL_SETUP": {"keywords": [("quick reference", 3), ("loop protocol", 4), ("council setup", 4), ("round strategy", 4), ("council dashboard", 3)]},
    "ARTIFACT_PERSISTENCE": {"keywords": [("persist council", 5), ("ai-council artifact", 5), ("council report parser", 4), ("state jsonl", 3)]},
    "RECOVERY_OR_AUDIT": {"keywords": [("rollback", 4), ("audit", 3), ("missing council_complete", 5), ("completion advisory", 4)]},
    "CONVERGENCE_CHECK": {"keywords": [("convergence", 4), ("two-of-three", 5), ("max rounds", 3), ("non-converged", 4)]},
    "SCORING": {"keywords": [("scoring rubric", 5), ("five-dimension", 5), ("hunter skeptic referee", 5), ("comparison table", 4)]},
    "DEPTH_DISPATCH": {"keywords": [("depth 0", 5), ("depth 1", 5), ("parallel dispatch", 4), ("sequential thinking", 4), ("ndp compliant", 4)]},
    "FAILURE_HANDLING": {"keywords": [("seat timeout", 5), ("all seats fail", 5), ("contradiction without resolution", 4), ("insufficient vantage", 4)]},
    "ANTI_PATTERNS": {"keywords": [("anti-pattern", 5), ("convergence sycophancy", 5), ("fake consensus", 4), ("recursive council", 4)]},
    "GRAPH_SUPPORT": {"keywords": [("council graph", 5), ("graph support", 4), ("derived graph", 5), ("council_graph", 5)]},
}

RESOURCE_MAP = {
    "COUNCIL_RUN": ["references/integration/loop-protocol.md", "references/patterns/seat-diversity-patterns.md", "references/convergence/convergence-signals.md", "references/structure/output-schema.md", "assets/deep-ai-council-strategy.md", "assets/prompt-pack-round.md"],
    "COUNCIL_SETUP": ["references/integration/quick-reference.md", "references/integration/loop-protocol.md", "assets/deep-ai-council-strategy.md", "assets/deep-ai-council-dashboard.md"],
    "ARTIFACT_PERSISTENCE": ["references/structure/folder-layout.md", "references/structure/output-schema.md", "references/structure/state-format.md", "references/patterns/command-wiring.md", "references/scoring/findings-registry.md", "assets/deep-ai-council-dashboard.md"],
    "RECOVERY_OR_AUDIT": ["references/structure/state-format.md", "references/structure/folder-layout.md", "references/patterns/command-wiring.md", "references/integration/loop-protocol.md"],
    "CONVERGENCE_CHECK": ["references/convergence/convergence-signals.md", "references/patterns/seat-diversity-patterns.md", "references/structure/state-format.md", "references/integration/loop-protocol.md"],
    "SCORING": ["references/scoring/scoring-rubric.md"],
    "DEPTH_DISPATCH": ["references/convergence/depth-dispatch.md", "references/convergence/deep-mode.md", "references/scoring/findings-registry.md"],
    "FAILURE_HANDLING": ["references/convergence/failure-handling.md"],
    "ANTI_PATTERNS": ["references/patterns/anti-patterns.md"],
    "GRAPH_SUPPORT": ["references/integration/graph-support.md", "references/structure/state-format.md", "references/structure/folder-layout.md"],
}

LOAD_LEVELS = {
    "COUNCIL_RUN": "CONDITIONAL",
    "COUNCIL_SETUP": "CONDITIONAL",
    "ARTIFACT_PERSISTENCE": "CONDITIONAL",
    "RECOVERY_OR_AUDIT": "CONDITIONAL",
    "CONVERGENCE_CHECK": "CONDITIONAL",
    "SCORING": "CONDITIONAL",
    "DEPTH_DISPATCH": "CONDITIONAL",
    "FAILURE_HANDLING": "CONDITIONAL",
    "ANTI_PATTERNS": "CONDITIONAL",
    "GRAPH_SUPPORT": "CONDITIONAL",
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Confirm whether the request is council setup, planning, persistence, recovery, or convergence checking",
    "Confirm the packet/spec folder for any artifact persistence",
    "Confirm whether external AI vantages actually ran or must be labeled simulated",
    "Confirm the planning-only handoff target before implementation starts",
]

AMBIGUITY_DELTA = 1

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 classify_intents(user_request, task=None):
    text = " ".join([str(user_request or ""), str(getattr(task, "intent", "") or "")]).lower()
    scores = {intent: 0 for intent in INTENT_MODEL}
    for intent, config in INTENT_MODEL.items():
        for keyword, weight in config["keywords"]:
            if keyword in text:
                scores[intent] += weight
    ranked = sorted(scores.items(), key=lambda pair: pair[1], reverse=True)
    primary, primary_score = ranked[0]
    if primary_score == 0:
        return ("COUNCIL_RUN", None, scores)
    secondary, secondary_score = ranked[1]
    if secondary_score > 0 and (primary_score - secondary_score)  str:
    override = str(getattr(task, "routing_key", "")).strip().upper()
    if override in RESOURCE_MAP:
        return override
    intent = str(getattr(task, "intent", "")).strip().upper()
    if intent in RESOURCE_MAP:
        return intent
    return intents[0] if intents else "UNKNOWN"

def route_sk_ai_council_resources(user_request, task=None):
    inventory = discover_markdown_resources()
    primary, secondary, scores = classify_intents(user_request, task)
    intents = [primary] + ([secondary] if secondary else [])
    routing_key = get_routing_key(task, intents)
    loaded = []
    seen = set()

    def load_if_available(relative_path: str):
        guarded = _guard_in_skill(relative_path)
        if guarded in inventory and guarded not in seen:
            load(guarded)
            loaded.append(guarded)
            seen.add(guarded)

    load_if_available(DEFAULT_RESOURCE)
    if max(scores.values() or [0])  --input-file 
node .opencode/skills/system-deep-loop/deep-ai-council/scripts/advise-council-completion.cjs 
```

**References**: load `quick-reference.md` first, then intent-specific references through Section 3. Load `output-schema.md` before persistence or report validation.

**Manual testing**: load `manual-testing-playbook/manual-testing-playbook.md` only for operator validation and release checks.

---

## 5. RULES

### ✅ ALWAYS

1. **ALWAYS keep council writes scoped to packet-local `ai-council/**` artifacts**
   - This preserves the planning-only boundary and avoids mutating implementation or spec-doc surfaces.

2. **ALWAYS preserve the planning-only boundary**
   - Implementation remains with implementation agents, commands, or the top-level caller after handoff.

3. **ALWAYS use distinct strategy lenses**
   - Label simulated vantages honestly when an external AI system did not actually run.

4. **ALWAYS append a `council_complete` event for completed persisted runs**
   - State is append-only and completion must be auditable.

5. **ALWAYS treat council graph support as a derived projection**
   - The graph is rebuilt from packet-local `ai-council/**` artifacts and must not replace append-only council state.

6. **ALWAYS run a single CLI per round (one-CLI-per-round invariant)**
   - All seats within ONE deliberation round MUST be dispatched through the SAME supported CLI executor (for example all seats from `cli-opencode`, `cli-cursor`, `cli-devin`, or `cli-pi`). Seat diversity WITHIN a round comes from different models/reasoning lenses on the same CLI (e.g. `deepseek/deepseek-v4-pro --variant high` + `xiaomi/mimo-v2.5-pro`).
   - Mixing executors within one round (e.g. one seat via OpenCode + one seat via OpenCode + one seat via Claude Code) is FORBIDDEN — it conflates orchestration boundaries, complicates rollback, and produces noisy convergence signals because per-CLI guarantees (sandbox, runtime, tool surface, output schema) differ.
   - When MULTIPLE CLIs are appropriate for a deliberation, each additional CLI is a NEW DEDICATED ROUND with its own state event, its own seats, and its own convergence pass — never folded into the same round.

### ⛔ NEVER

1. **NEVER write application code, authored spec docs, or files outside `ai-council/**` as part of a council run**
   - The council recommends; it does not implement.

2. **NEVER add backward-compatible old-name shims without concrete active-consumer evidence**
   - Rename support should follow real consumers, not speculation.

3. **NEVER claim an external CLI or AI system participated unless it actually ran**
   - Simulated perspectives must be explicitly labeled.

4. **NEVER rewrite historical state rows**
   - State evolution is additive-only; append new events instead.

5. **NEVER mix CLI executors across seats within a single round**
   - See ALWAYS rule 6. A round is defined by its CLI; a CLI change is a round boundary, not a seat boundary.

### ⚠️ ESCALATE IF

1. **ESCALATE IF no packet/spec folder can be resolved for artifact persistence**
   - Ask for the destination before dispatching seats or writing artifacts.

2. **ESCALATE IF required report sections are missing and persistence would be lossy**
   - Fix the report or fail before writes.

3. **ESCALATE IF a caller still depends on the old `ai-council` runti

…

## 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/skilled-harness__spec-driven-agent-loops](https://github.com/MichelKerkmeester/skilled-harness__spec-driven-agent-loops)
- **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-skilled-harness-spec-driven-agent-loops-deep-ai-council
- 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%.