Deep Ai Council

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/convergencesignals.md). Deep Mode (iterative multi-topic): see [references/convergence/depth_dispatch.md](references/convergence/depthdispatch.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, Codex), 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 Codex; opencode-go gateway 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. a fresh Codex perspective from inside a Claude Code session, or DeepSeek/Kimi via cli-opencode from inside a Codex session). It is invoked via the cli-* skill family (cli-claude-code, cli-codex, cli-opencode) — 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 external CLI (e.g. all cli-codex seats with different reasoning levels, OR all cli-opencode seats with different gateway 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

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

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.

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 deep-loop-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

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"],
    "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/deep-loop-workflows/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.

1. ALWAYS preserve the planning-only boundary

• Implementation remains with implementation agents, commands, or the top-level caller after handoff.

1. ALWAYS use distinct strategy lenses

• Label simulated vantages honestly when an external AI system did not actually run.

1. ALWAYS append a council_complete event for completed persisted runs

• State is append-only and completion must be auditable.

1. 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.

1. ALWAYS run a single CLI per round (one-CLI-per-round invariant)

• All seats within ONE deliberation round MUST be dispatched through the SAME CLI executor (e.g. all seats from cli-claude-code, OR all seats from cli-opencode, OR all seats from cli-codex). Seat diversity WITHIN a round comes from different models/reasoning lenses on the same CLI (e.g. opencode-go/deepseek-v4-pro --variant high + opencode-go/kimi-k2.6).
• Mixing executors within one round (e.g. one seat via Codex + 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.

1. NEVER add backward-compatible old-name shims without concrete active-consumer evidence

• Rename support should follow real consumers, not speculation.

1. NEVER claim an external CLI or AI system participated unless it actually ran

• Simulated perspectives must be explicitly labeled.

1. NEVER rewrite historical state rows

• State evolution is additive-only; append new events instead.

1. 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.

1. ESCALATE IF required report sections are missing and persistence would be lossy

• Fix the report or fail before writes.

1. ESCALATE IF a caller still depends on the old ai-council runtime name and cannot be renamed

• Compatibility requires explicit user direction.

1. **ESCALATE IF a caller asks the council agent itself to mu

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory
• License: MIT

Install and usage instructions live in the source repository linked above.