Coeus

Titan of Intelligence and Foresight

     

All skills and agents for EP industry, self-created only — including improvisations from existing skills that have been changed to suit EP needs. For modified work, please give credits and acknowledgement to the original work, and include links to the original work. Once any new skills or agents are added to this repo, please update this README and Wiki. This mono repo works with Claude.

Repository: https://github.com/keithceh/Coeus
Licensor: ENERGEIA SERVICES PTE. LTD. (202401987H)
License: BSL 1.1 → Apache 2.0 on May 28, 2028

Release badges: Coeus is a private repo, so the native shields.io GitHub-release badge cannot read it. The release, released (date), and release count badges above are driven by a public Gist that the update-badge workflow refreshes automatically on every published Release. The date badge shows the latest release date in YYYY-MM-DD format. The release-count badge shows the total number of published Releases (counted by paginating /releases on the GitHub API). The release workflow also asserts the GitHub Release tag matches the version field in .claude-plugin/plugin.json — so the version reported by the plugin can never drift from the Release that shipped it.

Changelog

See CHANGELOG.md for full change history.

Notes

1. Caveman in Coeus tracks JuliusBrussee/caveman@main directly. The local skills/caveman/ directory is auto-synced weekly via the sync-upstream-skills workflow and bundled fresh on every release. Future improvements follow upstream.
2. Prompt-master in Coeus tracks nidhinjs/prompt-master@main directly (currently v1.7+). It is bundled and auto-installed exactly like caveman: the local skills/prompt-master/ directory is auto-synced weekly via the sync-upstream-skills workflow and bundled into coeus.plugin on every release. prompt-master has no formal upstream releases — the latest version is always on main.

Skills at a Glance

Both dependencies (prompt-master and caveman) are bundled in Coeus and auto-synced from upstream — no separate install required when using the plugin. v3.8.0 adds Coeus-Router and the formal Skill Architecture (three tiers, 3,000-token cap, skills/_shared/ convention, canonical registry).

How the Skills Relate

/morpheus                          /council
    │                                  │
    ▼                                  ▼
prompt-master ──► caveman ──────► llm-council
                                       ▲
                              /architect (chains all three)

/ep-council (standalone — domain-specific E&P council)

Morpheus = prompt crafting + compression.
LLM-council = multi-model adversarial deliberation.
The Architect = chains all three into one end-to-end pipeline.
EP-Council = adversarial 9-supermajor council for upstream E&P decisions.

Slash Commands

Installing coeus.plugin registers a typeable slash command for every skill, namespaced under coeus. Slash commands auto-register from each skill's SKILL.md frontmatter (name + argument-hint) — matching the convention in anthropics/knowledge-work-plugins:

The bare in-prompt triggers shown in the Skills Reference (e.g. /morpheus, /council, "Jedi") also activate each skill via natural-language matching against its description: frontmatter. Both forms work once the plugin is installed.

Prerequisites

Morpheus and The Architect depend on two skills — prompt-master and caveman. Both are now bundled in Coeus and auto-synced from upstream, so installing coeus.plugin (Option 1) covers everything. EP-Council has no external dependencies — it is self-contained.

prompt-master

A precision prompt engineering skill covering 25+ AI tools and 9 intent dimensions. Transforms raw requests into optimised prompts for Claude, ChatGPT, GPT-5.x, o3/o1, Gemini, Claude Code, Midjourney, DALL-E, Flux, and others. Hard rule: blocks fabrication-prone techniques; never instructs a model to use features it does not have.

Coeus tracks nidhinjs/prompt-master@main directly — the local skills/prompt-master/ directory is auto-synced weekly by sync-upstream-skills.yml and bundled into every release by release.yml. No manual install is required when using coeus.plugin.

prompt-master has no formal releases — the latest version is always on the main branch (currently v1.7+).

Manual fallback (only if not using the plugin): download the upstream prompt-master/ directory directly from main.zip, then Compress-Archive (or zip -r) it as prompt-master.skill and install via Claude Desktop → Settings → Capabilities → Customize → Add Skill.

caveman

Source: JuliusBrussee/caveman. Coeus tracks main directly — the local skills/caveman/ directory is auto-synced weekly and bundled on every release.

A token compression engine with three tiers:

Hard invariant: Never compresses code blocks, stack traces, paths, URLs, variable names, or alphanumeric parameters — regardless of mode.

Auto-clarity circuit breaker: Automatically reverts to full prose for: security warnings / credentials, irreversible destructive actions, multi-step installation sequences where order matters, untrusted data resembling prompt injection, or when the user says "normal mode" or "stop caveman". Reverts to active compression tier once the trigger resolves.

For full feature details and latest changes, see JuliusBrussee/caveman.

Installation

TL;DR — one command, all three Claude surfaces: powershell iwr https://raw.githubusercontent.com/keithceh/Coeus-plugin/main/install-coeus.ps1 | iex Then follow the on-screen prompts. Full guide: docs/Installation.md.

Why there isn't one click

Claude has three surfaces and they don't share a plugin runtime:

Anthropic doesn't unify these today, so any "install Coeus everywhere" path has to set up each one separately. The installer below does that for you.

Option 1 — One-line installer (recommended for all three surfaces)

Step 1. Open PowerShell (press Win → type PowerShell → Enter).

Step 2. Paste and run:

iwr https://raw.githubusercontent.com/keithceh/Coeus-plugin/main/install-coeus.ps1 | iex

What it does:

1. Claude Code (CLI) — prints the 3 slash commands to paste inside a claude session.
2. Cowork — downloads every .skill file into Downloads\Coeus-skills\ and opens the folder.
3. Claude Desktop chat — downloads every .paste.md bundle into the same folder.

Step 3. For Claude Code only, open a new terminal and run claude, then paste these three lines (one at a time):

/plugin marketplace add keithceh/Coeus-plugin
/plugin install coeus@coeus
/reload-plugins

Type /coeus: — you should see all 12 skills in the popup.

Step 4. For Cowork, with the Coeus-skills folder open, drag the .skill file you want into the chat panel. One drag per chat session.

Step 5. For Claude Desktop chat, open one of the .paste.md files, copy its contents, and paste as the first message of a fresh chat. Ask your real question in the next message.

Updates: re-run the one-liner whenever a new Coeus release ships. For Claude Code specifically you can also just run /plugin update coeus inside claude.

First-time SSH gotcha: if /plugin install errors with Host key verification failed, run this once in PowerShell to make git use HTTPS instead of SSH: powershell git config --global url."https://github.com/".insteadOf "git@github.com:"

Option 2 — Manual marketplace install (Claude Code only, no installer script)

If you only use Claude Code in the terminal and want to skip the installer script, run these inside a claude session:

/plugin marketplace add keithceh/Coeus-plugin
/plugin install coeus@coeus
/reload-plugins

That's it for the CLI. Updates: /plugin update coeus. This path persists across restart (the older Personal-upload path did not, per Anthropic #40600).

How it works: every tagged release of this repo runs .github/workflows/release.yml, which builds dist/coeus.plugin with the UTF-8-flagged Python builder and force-pushes the extracted runtime + marketplace.json to the public mirror. The mirror is history-less and source-free. Source remains private under BSL 1.1.

Install order (only matters if installing individual .skill files)

The coeus.plugin bundle and the marketplace install handle this order automatically.

Option 3 — Personal-upload .plugin (legacy fallback)

If you need to install without the marketplace (e.g. air-gapped machine), download coeus.plugin from Releases and use Claude Desktop / Cowork → Settings → Capabilities → Customize → Add Plugin. Note: this install path does NOT persist across Cowork restart and is subject to several Anthropic-side state bugs (#40600 / #28554 / #63624). Prefer Option 1 wherever possible.

Option 4 — Install from GitHub Releases (individual .skill files)

1. Go to Releases
2. Download the .skill files you need: - Coeus skills: llm-council.skill, morpheus.skill, the-architect.skill, ep-council.skill - Bundled prerequisites (auto-built at release time): caveman.skill (JuliusBrussee/caveman@main), prompt-master.skill (nidhinjs/prompt-master@main)
3. In Claude Desktop: Settings → Capabilities → Customize → Add Skill
4. Select each downloaded .skill file (install order above)

Option 5 — Org / Enterprise managed install (Team & Enterprise plans)

On Team and Enterprise Claude plans, admins can ship Coeus to every member automatically via the org-managed plugin config. This is the only install path Anthropic guarantees persists across uninstall attempts (#45323) and survives all the Personal-upload state bugs.

Admin setup (one-time, per org):

Add to the org's managed claude-config.json (or the equivalent admin settings panel):

{
  "extraKnownMarketplaces": {
    "coeus": {
      "source": {
        "source": "github",
        "repo": "keithceh/Coeus-plugin"
      }
    }
  },
  "enabledPlugins": {
    "coeus@coeus": "required"
  }
}

Set the plugin level: - "required" — installs automatically for every member; members cannot uninstall - "installed by default" — installs automatically; members can opt out

Member experience: zero install steps. Coeus skills appear in their Claude session the first time they connect after the admin pushes the config.

Member can verify their org-managed install with /plugin list — Coeus appears with the [org-managed] marker.

Option 6 — Paste-prompt (for claude.ai web chat)

claude.ai web chat does not support plugin uploads. For web-chat users who want a single Coeus skill without a Cowork/Code/Desktop install, download a per-skill paste bundle from Releases:

• coeus-llm-council.paste.md — the 4-phase council
• coeus-the-architect.paste.md — adaptive routing (A/C/D)
• coeus-ep-council.paste.md — 9-supermajor E&P decision engine
• coeus-morpheus.paste.md — prompt-engineering pipeline
• coeus-plugin-creator.paste.md — autobot transformer
• coeus-project-lifecycle.paste.md — multi-session lifecycle

Use: paste the file's contents as the first message of a fresh chat, then ask your real question in the next message. The model treats the embedded protocol as load-bearing instructions.

Limitations: no slash commands, no auto-fire on trigger phrases, no cross-skill chaining (each chat is one skill). The protocol still runs; the install ergonomics don't.

Bundles are generated by scripts/build-skill-paste.py — concatenates the SKILL.md + every _shared/*.md it references into one self-contained Markdown file (12–38 KB each).

Option 7 — Build locally (for maintainers / forks)

Reproducible build producing dist/coeus.plugin identical to the release-workflow output. All wrappers delegate to a single cross-platform Python builder that guarantees the UTF-8 filename flag (0x800) and POSIX permissions required by Claude Cowork's strict upload validator (Desktop is more lenient, but the same bundle works for both):

python scripts/build-plugin.py         # → dist/coeus.plugin   (recommended, cross-platform)
bash   scripts/build-plugin.sh         # → dist/coeus.plugin   (Unix wrapper)

powershell .\scripts\build-plugin.ps1  # → dist\coeus.plugin   (Windows wrapper)

Install the resulting dist/coeus.plugin via Claude Desktop / Cowork → Settings → Capabilities → Customize → Add Plugin.

Why the dedicated Python builder? PowerShell's Compress-Archive and zip -r produce archives that Claude Desktop accepts but Claude Cowork rejects with zip file contains path with invalid characters — Cowork's validator requires every zip entry to carry the 0x800 UTF-8 filename flag, and the standard tools either omit it (Compress-Archive) or only set it for non-ASCII names (CPython's zipfile). scripts/build-plugin.py subclasses ZipInfo to force the flag on every entry. Fixed in v3.6.1.

Plugin spec requirements (per anthropics/knowledge-work-plugins): - The manifest lives at .claude-plugin/plugin.json inside the ZIP (root placement is rejected with "Zip must contain a .claude-plugin/plugin.json file"). - The manifest is slim — only name, version, description, author. - Skills live under skills/<name>/SKILL.md and auto-discover; the slash command /coeus:<name> registers from each skill's name + argument-hint frontmatter (no commands/ wrappers needed). - See docs/CONFORMANCE_REPORT.md for the full v3.4.0 alignment notes and docs/COEUS_EXTENSIONS.md for the three deliberate divergences (cleanup hook, LLM handover, vendored upstream skills).

Skill Reference

LLM-council

Triggers: /council, "Jedi", "May 4th", "run the council", "stress-test this", "red team this", "premortem", "multi-model analysis", "get all the AIs to weigh in", "simulate expert debate", "adversarial review"

What it is: A structured 4-phase deliberation engine that simulates 6 frontier LLMs as distinct epistemic voices. Claude impersonates each model's reasoning style — no external API calls are made. The value is adversarial diversity: 6 different analytical frameworks attacking the same problem.

The 6 Simulated Models:

The 4-Phase Pipeline:

Phase 1 — Socratic Clarification & Context Gating
3–7 targeted Yes/No or multiple-choice questions to eliminate assumptions and establish clear system bounds. Short-circuits if the input is already complete and unambiguous.

Phase 2 — Strategic Roadmap & Gated Approval (mandatory gate — Claude stops and waits)
High-level end-to-end roadmap presented to the user. Explicit approval required ("Proceed", "Go ahead", "Yes") before Phase 3 begins. Neutral responses do not count.

Phase 3 — Tri-Team Round-Robin Red-Teaming
3 rounds with 2 models per faction, randomised each round (no model holds the same role twice in a row):

• 🔵 Blue Team (Architects/Defenders): Builds and patches the core proposal
• 🔴 Red Team (Adversarial Attackers): Finds flaws, edge-case failures, engineering traps
• 🟢 Green Team (Independent Verifiers): Checks scientific rigour, testability, real-world execution

Each round: Red attacks → Blue patches → Green verifies. Summary of what survived, what was patched, what remains contested.

Phase 4 — 6-Month Failure Premortem Engine
Assumes catastrophic failure 6 months from today. 3 distinct scenarios, each analysed for: - Most Likely Root Causes — high-probability, practical failure points - Red Herrings — decoy symptoms that distract from the true root cause (what a panicked team chases first) - Black Swans — low-probability, high-impact disruptions (regulatory shifts, infrastructure failures, model behaviour changes)

Mitigations ranked by severity × impact, not probability.

Mandatory Artifacts (both produced at the end of every full run): - Final_Plan.md — council synthesis table, tri-team debate record, critical findings, best-of-all-worlds step-by-step execution plan - Premortem_Report.md — 3 failure scenarios, ranked mitigation framework (🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low), premortem confidence rating matrix

Behavioural Guardrails: - Phase gates cannot be skipped, even under user pressure - No fabricated citations — if a real source cannot be named, it must be flagged - Unresolved tensions are surfaced; false consensus is never acceptable - Simulated model voices use hedged language and do not impersonate real products

Morpheus

Triggers: /morpheus, /morph, "engineer this prompt", "optimise this prompt", "compress this prompt", "make this prompt better", "refine my prompt for [model]"

What it is: A two-stage pipeline — prompt engineering then caveman compression — that transforms a raw request or rough draft into a precision-engineered, token-efficient prompt ready to paste into any AI system.

Pre-Flight Checks (run before pipeline; pause if any check triggers):

Step 1 — Prompt-Master (Craft)

Identifies or infers the target model and applies model-specific best practices:

Hard rules: never fabricate capabilities; every prompt must specify output format and include uncertainty-handling instruction; persona framing uses generic roles only (e.g., "expert engineer", never a real person's name).

Output: ## Engineered Prompt (for [Target Model]) block.

Step 2 — Caveman (Compress)

Compresses the engineered prompt for token efficiency.

Critical scope rule: Caveman applies to the PROMPT ONLY — never to deliverables, artifacts, structured data, tables, code, or any output the user intends to use as-is.

Compression rules: strip articles where meaning is preserved; remove filler phrases; collapse verbose instructions; preserve precision, format markers (XML/markdown), uncertainty-handling instructions, and output format specs.

Auto-disable conditions (returns Step 1 prompt unchanged, with explanation): - Prompt already under 150 tokens - Target model is o3/o1 (already benefits from concision; over-compression may degrade reasoning) - User says "don't compress" or "keep it verbose"

Output: ## Compressed Prompt (caveman) — [Target Model] block with compression ratio (~X → ~Y tokens, ~Z% reduction).

Auto-execution (v1.0.1): When all three pre-flight checks pass without flags and no Pipeline Pause Condition applies, Morpheus skips intermediate step blocks and delivers only the Final Delivery Format. Intermediate Engineered Prompt and Compressed Prompt blocks are shown only when a gate actually fires (escalation recommendation, narrow-scope flag, or pause condition).

Step 3 — Auto-run compressed prompt (v1.1.0): When all stages pass without firing a gate AND the target model is the current runtime (Claude / Claude Code), Morpheus immediately executes the compressed prompt in the same conversation after delivering the Morpheus Output block. If the target is an external tool (ChatGPT, Gemini, Midjourney, etc.) or the user opts out ("just give me the prompt", "deliver only"), Step 3 is skipped and only the prompt is delivered for the user to paste.

Final delivery: Both versions in a single Morpheus Output block — target model named, caveman status and reason stated.

Absolute Hard Rules:

Trigger reference:

The Architect

Triggers: /architect, /archi, /architect --explore, /archi --explore, "full pipeline", "architect this", "run the full council with prompt engineering", "stress-test and plan this properly"

What it is: The highest-intensity tool in the Coeus suite. Chains prompt-master, caveman, and llm-council into a single orchestrated pipeline with an adaptive routing decision. Use when the stakes justify the full deliberation cycle.

Routing Decision:

Does the user want to explore the problem space before engineering prompts?
    │
    ├── YES (--explore flag, or problem is ambiguous/novel) → ROUTE C
    │
    └── NO (default) → ROUTE A

ROUTE A — Default Pipeline

Step A1 — Prompt-Master (Craft)
Applies full prompt-master process. Structures the user's input into a precision-engineered council brief: problem statement, key constraints, desired output format, success criteria. Target context = LLM-council phase.

Step A2 — Caveman (Compress)
Applies caveman to the council brief from A1. Scope restriction: the brief/prompt only — never any artifact the council will produce.

Step A3 — LLM-Council (Full Run)
Feeds compressed brief into the full 4-phase council pipeline. Phase 2 gate (roadmap approval) is mandatory before Phase 3.

ROUTE C — Deep Explore Pipeline

Step C1 — Council Explore
Scoped session using LLM-council Phases 1 and 2 only (no red-teaming yet). The 6 models each frame the problem. Key assumptions, definitions, and scope boundaries surface. Output: a Problem Definition Document. User must confirm before proceeding.

Step C2 — Prompt-Master (Craft)
Applies prompt-master to the confirmed Problem Definition Document from C1.

Step C3 — Caveman (Compress)
Applies caveman to the engineered brief from C2.

Step C4 — LLM-Council (Full Run)
Feeds compressed brief into the full 4-phase council pipeline.

Mandatory Final Artifacts (both routes, without exception): - Final_Plan.md — council synthesis recommendation, full roadmap, tri-team debate record, best-of-all-worlds step-by-step execution plan - Premortem_Report.md — 3 failure scenarios, ranked mitigation framework, premortem confidence matrix

Caveman is never applied to these artifacts.

Absolute Hard Rules (inherits from all 3 component skills):

EP-Council

Triggers: /ep-council, "board review", "investible", "run the E&P council", or any natural-language description of an upstream E&P decision, acquisition, exploration commitment, or capital allocation question.

What it is: A domain-specific adversarial decision engine for upstream E&P operators. Nine supermajors — BP, Chevron, TotalEnergies, Shell, QatarEnergy, ExxonMobil, ConocoPhillips, ENI, and Occidental — model the distinct epistemic and strategic lens of each operator's known decision culture. Three adversarial red-team rounds (3-3-3 faction split) plus a 10-trap Council Trap Screen catch E&P-specific failure modes that a general-purpose council would miss.

The 9 Council Members:

The Pipeline:

Phase 0: Strategy Brief Lock (7 dimensions — mandatory before any red-teaming)
     │
     ▼
Phase 1: Blue Team Assessment (full opportunity case)
     │
     ▼
Round 1: Red Team (3 members) → Trap Screen T0–T10
     │
     ▼
Round 2: Red Team (3 members) → Trap Screen T0–T10
     │
     ▼
Round 3: Red Team (3 members) → Trap Screen T0–T10
     │
     ▼
Phase 2: Green Team Synthesis + Final Vote (9 named votes: PROCEED / CONDITIONAL / REJECT)

Faction allocation: 3-3-3 per round (clean split, all three factions equal size across all rounds).

The 11 Council Traps (T0–T10):

Receive 9 named votes: Each member votes PROCEED, CONDITIONAL, or REJECT. Conditions from CONDITIONAL votes are documented before execution.

Full 9-option menu at session start — choose from standard E&P opportunity types or describe the decision in plain language.

EP-Council Engine v9 ready · 9 members · T0–T10 traps (11 traps) · 3-3-3 factions · BSL 1.1

EP-Council Wiki Pages:

Repo Structure

Coeus/
├── .claude-plugin/
│   └── plugin.json                # Canonical manifest — 4 keys: name, version, description, author
├── skills/                        # Auto-discovered by Claude Code (plugin spec layout)
│   ├── llm-council/SKILL.md
│   ├── morpheus/SKILL.md
│   ├── the-architect/SKILL.md
│   ├── ep-council/SKILL.md
│   ├── caveman/SKILL.md           # vendored from JuliusBrussee/caveman@main
│   └── prompt-master/             # vendored from nidhinjs/prompt-master@main
│       ├── SKILL.md
│       └── references/{patterns,templates}.md
├── hooks/                         # Coeus extension (see docs/COEUS_EXTENSIONS.md)
│   ├── hooks.json                 # SessionStart hook registration
│   ├── cleanup-stale-install.sh   # Purges stale files from prior in-place upgrades (Unix)
│   └── cleanup-stale-install.ps1  # Same, PowerShell mirror
├── scripts/
│   ├── build-plugin.py            # Cross-platform builder (single source of truth; UTF-8 flag + POSIX perms)
│   ├── build-plugin.sh            # Unix wrapper -> build-plugin.py
│   └── build-plugin.ps1           # PowerShell wrapper -> build-plugin.py
├── docs/
│   ├── CONFORMANCE_REPORT.md      # Audit vs anthropics/knowledge-work-plugins (v3.4.0 alignment)
│   ├── COEUS_EXTENSIONS.md        # The three deliberate divergences from official
│   ├── PLUGIN_MANIFEST_EXTENSIONS.md  # Metadata displaced from the slim manifest
│   ├── TEST_REPORT_v3.3.0.md      # Rigorous-test report from v3.3.0 → v3.3.1
│   └── EP-Council*.md             # EP-Council skill reference docs
├── assets/coeus-header.jpg        # Referenced by README header
├── README.md
├── CHANGELOG.md
├── Coeus_LLM_HANDOVER.md          # LLM cold-start brief (Coeus extension)
├── CONTRIBUTING.md
├── CLA.md
├── LICENSE
├── .gitattributes
├── .gitignore
└── .github/
    ├── upstream-caveman-sha.txt
    ├── upstream-prompt-master-sha.txt
    ├── workflows/{release.yml, sync-upstream-skills.yml, update-badge.yml}
    ├── ISSUE_TEMPLATE/{bug_report.md, feature_request.md}
    └── PULL_REQUEST_TEMPLATE.md

Per-skill .skill baselines and coeus.plugin are build artefacts, not source. They're produced fresh by release.yml on every Release (and attached as Release assets), or built locally with scripts/build-plugin.*. The repo does not commit them — see .gitignore.

Each .skill file is a ZIP archive containing skillname/SKILL.md (plus any reference files). These are attached to GitHub Releases for one-click download and install. The .claude-plugin/plugin.json manifest enables installing all skills in a single .plugin file via Claude Desktop. Claude requires the manifest at .claude-plugin/plugin.json inside the ZIP (not at the root).

License

This project is licensed under the Business Source License 1.1 (BSL 1.1).

• Non-commercial use only until May 28, 2028
• On May 28, 2028 the license automatically converts to Apache License 2.0
• As-a-service restriction: The licensed work or any derivative may not be offered as a hosted or managed service without a separate commercial agreement with the Licensor
• Model distillation prohibition: Outputs may not be used to train, fine-tune, distill, or ot

Installing Coeus

This page is the full install guide. For a quick command, see the README's TL;DR at the top of its Installation section.

Before you start

Coeus runs across three Claude surfaces, and they don't share a plugin runtime:

There is no Anthropic-side mechanism today that installs once and registers everywhere. Every "install Coeus everywhere" path is really three smaller installs done in one go. The one-line installer below does the three for you.

Quickest path: the one-line installer

Step 1. Open PowerShell.

Press Win, type PowerShell, press Enter. Any folder is fine — the script writes to your user profile, not the current directory.

Step 2. Run the installer.

iwr https://raw.githubusercontent.com/keithceh/Coeus-plugin/main/install-coeus.ps1 | iex

You'll see three sections of output:

[1/3] Claude Code: ...
[2/3] Cowork + [3/3] Desktop chat: fetching latest release artifacts...
Done.
  .skill files (drag into Cowork chat): C:\Users\<you>\Downloads\Coeus-skills
  .paste.md files (paste into Desktop chat): C:\Users\<you>\Downloads\Coeus-skills

A File Explorer window will open at Downloads\Coeus-skills\.

Step 3 (Claude Code only). Open a terminal, run claude, then paste:

/plugin marketplace add keithceh/Coeus-plugin
/plugin install coeus@coeus
/reload-plugins

Verify by typing /coeus: — you should see a popup listing all 12 skills.

Step 4 (Cowork only). Drag any .skill file from the open Explorer window into the Cowork chat panel. One drag per chat session. Cowork doesn't persist plugin state across restart yet (Anthropic #40600).

Step 5 (Claude Desktop chat only). Open any .paste.md file in Notepad (or VS Code), copy all of it, paste as the first message of a fresh chat. Ask your real question in the second message.

Updates

• Claude Code — /plugin update coeus inside claude, or re-run the installer.
• Cowork — re-run the installer (it re-downloads the latest .skill files), then drag the fresh one in.
• Claude Desktop chat — re-run the installer, use the new .paste.md.

Troubleshooting

iwr errors / "running scripts is disabled"

If PowerShell blocks the script with running scripts is disabled on this system, run this once and retry:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

/plugin install errors with Host key verification failed

Windows OpenSSH can't negotiate with GitHub's current SSH KEX. Force git to use HTTPS instead of SSH:

git config --global url."https://github.com/".insteadOf "git@github.com:"

Then retry /plugin install coeus@coeus.

/reload-plugins says 0 skills

That's a counting quirk in Claude Code's reload output. Verify the install actually worked by listing the cache:

ls $env:USERPROFILE\.claude\plugins\cache\coeus\coeus\

You should see a version dir containing skills/, hooks/, scripts/, and .claude-plugin/. Then in claude type /coeus: — the popup should show all 12 skills.

Cowork doesn't see Coeus after /plugin install

By design. Cowork doesn't read the Claude Code plugin cache. Drag a .skill file into Cowork chat instead.

Claude Desktop chat doesn't have /plugin

By design. Claude Desktop chat has no plugin runtime. Use the paste-prompt path (.paste.md bundles) instead.

Manual install paths (skip the installer)

Claude Code only

/plugin marketplace add keithceh/Coeus-plugin
/plugin install coeus@coeus
/reload-plugins

Cowork only

1. Download a .skill file from Releases.
2. Drag it into the Cowork chat panel.

Install order if you grab multiple: prompt-master → caveman → llm-council → morpheus → the-architect → ep-council.

Claude Desktop chat only

1. Download a coeus-<skill>.paste.md bundle from Releases.
2. Open in any text editor, copy all.
3. Paste as the first message of a fresh chat.

Org / Enterprise managed install

The most durable Anthropic-supported install path. Survives uninstall attempts (#45323) and bypasses all Personal-upload state bugs.

Admin adds to the org's managed claude-config.json:

{
  "extraKnownMarketplaces": {
    "coeus": {
      "source": {
        "source": "github",
        "repo": "keithceh/Coeus-plugin"
      }
    }
  },
  "enabledPlugins": {
    "coeus@coeus": "required"
  }
}

• "required" — auto-installs for every org member; cannot uninstall.
• "installed by default" — auto-installs; member can opt out.

Local build (maintainers / forks)

python scripts/build-plugin.py

Produces dist/coeus.plugin. Use the Python builder — Compress-Archive and stock zip omit the UTF-8 0x800 flag and Cowork rejects the result.

Why this is the install story today

Two upstream constraints:

1. No shared plugin runtime across surfaces. Code reads ~/.claude/plugins/. Cowork reads per-chat skill uploads. Desktop chat reads nothing — it has no plugin runtime at all.
2. Personal-upload state bugs. Anthropic #40600, #28554, #63624. Cowork doesn't persist installs across restart; the Personal install path silently drops state.

The marketplace path (Option 1 inside Claude Code) avoids #2 by going through /plugin. Cowork and Desktop chat have no equivalent path, so the installer downloads the right artifact for each.

If Anthropic ships a unified runtime later, the installer collapses to one /plugin install call. Until then, this is the cleanest "one command" we can offer.

🛢️ EP-Council

Adversarial 9-supermajor decision council for E&P operators. Phase-gated workflow that stress-tests every opportunity against documented institutional playbooks, hard failures, and through-cycle economics.

Version: v9 (current) | Triggers: /ep-council · /coeus:ep-council · "board review" · "investible"

What It Does

EP-Council replaces gut-feel capital allocation with a structured, mandatory workflow. It simulates nine supermajor E&P companies — each with distinct institutional memory, failure modes, and primary questions — as an adversarial council that evaluates your opportunity across three red-team rounds before delivering named votes.

It is not a chatbot. It is a phase-gated engine. Phases cannot be skipped. The verdict cannot be reached without completing the red team.

Installation

Option 1 — Download .skill file (recommended)

1. Go to Releases
2. Download ep-council-v9.skill
3. Open Claude Desktop → Settings → Skills → Install from file
4. Select ep-council-v9.skill

Option 2 — Build from source

git clone https://github.com/keithceh/Coeus.git
cd Coeus

# macOS / Linux
zip -r ep-council.skill ep-council/

# Windows (PowerShell)
Compress-Archive -Path ep-council\ -DestinationPath ep-council.skill

Triggers

Auto-trigger: Describing any E&P opportunity — block, well, acquisition, farm-in, JV, FLNG, divestment, or strategic pivot — activates EP-Council automatically.

The Pipeline

[Strategy Document / 12 Questions]
           │
     Phase 0: Strategy Brief Lock
     ─ 7 dimensions: geography, asset type, capital,
       returns, portfolio philosophy, financing, constraints
           │
     Phase 1: Opportunity Intake + Strategy Fit Check
     ─ 6-dimension fit check against Strategy Brief
     ─ T0 Strategic Drift fires if any dimension contradicts
           │
     Phase 1.5: Enforcer Selection
     ─ Opportunity-tailored recommendation first
     ─ Full 9-option menu always shown
           │
     Phase 2: Strategic Roadmap
     ─ Opportunity summary, decision type, active Enforcer,
       strategy fit results, 3 most dangerous assumptions,
       active Council Traps
     ─ ★ EXPLICIT USER APPROVAL REQUIRED ★
           │
     Phase 3: Tri-Team Red-Team (3 rounds, 3-3-3 per round)
     ─ Blue builds · Red attacks · Green verifies
     ─ Patch ratings: STRONG / PARTIAL / WEAK
     ─ Weak patches trigger mandatory re-attack
     ─ Green runs Council Trap Screen after every round
     ─ Through-Cycle Stress Test mandatory in Green faction
           │
     Phase 3.5: Council Verdict
     ─ 9 named votes: PROCEED / MODIFY / REJECT
     ─ 5-4 → SPLIT COUNCIL
     ─ 6-3 → CONTESTED (minority dissent documented)
     ─ Contradicts Strategy Brief → STRATEGIC OVERRIDE
           │
     Phase 4: EP Premortem
     ─ Failure scenarios from Decision Type Classifier
     ─ 3-4 scenarios, root causes, red herrings, black swans
     ─ Ranked SEVERITY × IMPACT
           │
  [EP_Decision_Plan.md + EP_Premortem_Report.md]

Tri-Team Faction Allocation

All rounds use a 3-3-3 split.

• No member holds the same faction in consecutive rounds
• Blue builds the case
• Red attacks every assumption
• Green verifies, rates patches, runs Council Trap Screen
• The Enforcer names one specific Strategy Brief risk per round
• Through-Cycle Stress Test ($30 / $50 / $70 / $90/bbl) is mandatory in Green every round

Output Artifacts

Both delivered as standalone code-fenced Markdown documents.

EP_Decision_Plan.md - 9 named council votes with positions and conditions - Tri-team red-team summary (3 rounds, patch ratings) - Council Trap Screen results (T0–T10 status) - Through-Cycle Stress Test outcomes - Cycle-tested execution plan

EP_Premortem_Report.md - Decision-type-specific failure scenarios - Root cause, red herrings, black swan variant per scenario - Severity × Impact ranking - Ranked mitigation framework with named responsible parties

Mid-Session Commands

Mandatory Flags

Related Wiki Pages

• Council Members →
• Trap Screen T0–T10 →
• Step-by-Step Session Walkthrough →

Version History

Go back to the Main README.

EP-Council — Council Members

Nine supermajor E&P companies, each with distinct institutional memory, a documented failure mode, and one primary question they ask verbatim in every round.

Hard rule: Each member's primary question is asked verbatim. No substitution. No skipping.

The Nine Members

★ ExxonMobil is the default Enforcer. Enforcer selection occurs in Phase 1.5, with an opportunity-tailored recommendation provided automatically. The full 9-option menu is always shown.

Member Profiles

1 · BP — Business Efficiency Optimizer

Lens: Upstream return discipline, exit speed, portfolio restructuring

Primary question: Does the return profile justify the entry, or are we substituting strategic narrative for IRR?

Red flag: Assets that require integration complexity to generate returns. Upstream commitments that dilute capital efficiency metrics.

Council Trap: T1 — Strategy Whiplash (pivoting strategy under price pressure)

2 · Chevron — Concentrator Business Model

Lens: Tier-1-or-exit mandate, Hess arbitration discipline, Stabroek 30% WI benchmark

Primary question: Is this a tier-1 asset by Permian / Stabroek standards, or are we rationalising tier-2 with strategic framing?

Red flag: Assets that require a strategic narrative to justify entry. Any acquisition where the competing bidder walked away — the price paid above the walkaway is not a premium, it is a signal.

Council Trap: T2 — Tier-2 Masquerade (below-tier-1 asset dressed as tier-1)

3 · TotalEnergies — Energy Integration Business Model

Lens: Gas-to-power vertical stack (EPH), dividend consistency, segment mix discipline

Primary question: Does this asset generate cash at $30/bbl, or does it only work inside a vertical integration thesis that may not exist at trough?

Red flag: Integration theses that substitute for standalone asset economics. LNG or gas assets priced on integration value rather than spot.

Council Trap: T3 — Integration Illusion (integration thesis fails at $30/bbl)

4 · Shell — Energy Trader Strategic Pivot

Lens: ARC Resources 75/25 structure, trading-led portfolio, Chemicals discipline after Q4 2025 loss; duration vs distribution discipline (reserve life, organic renewal, harvest-vs-compounder framing)

Primary question: Does the financing structure optimise capital efficiency, or are we taking balance sheet risk that a carry or satellite structure would eliminate? And: is organic reinvestment funded before distributions, or has the portfolio drifted from compounder to harvest vehicle?

Red flag: Adding business segments without removing any. Chemical or downstream exposure without ring-fencing. Distributions funded before best organic reinvestment; R/P shortening materially faster than production; M&A used as the primary reserve-replacement mechanism without a working organic engine.

Council Traps: T4 — Complexity Creep (adding segments without removing any); T10 — Duration Drift (acquired duration ≠ created duration)

5 · QatarEnergy — Global Energy Monopoly and Security

Lens: 77→142→160 MTPA expansion, demand-lock framing, NFE/NFS partner %

Primary question: Does this lock in demand at a price that works through the cycle, or are we assuming a price environment that may not persist?

Red flag: Geographic concentration above 40% in one country or asset type. Demand assumptions priced above cycle-trough.

Council Trap: T5 — Concentration Kill (>40% exposure in one geography or asset type)

6 · ExxonMobil ★ — Strategic Consistency Manufacturer

Lens: $4.6B Q1 timing effects awareness, Specialty vs commodity chemical distinction, long-cycle discipline

Primary question: Is this in the Strategy Brief? If not, why are we looking at it?

Red flag: Opportunity that arrived via a banker rather than a portfolio screen. Strategic rationale constructed post-opportunity-identification.

When Enforcer: Enforces Strategy Brief integrity through every round. The Enforcer's one job is to name one specific Strategy Brief risk per round — not a generic concern, not a restatement of the opportunity.

Council Trap: T6 — Distraction Decision (not in the Strategy Brief)

7 · ConocoPhillips — Upstream Energy Business Strategy Evolution

Lens: PE buy-improve-return 4-cycle, VROC 45% CFO target 2026, cycle discipline

Primary question: Are we allocating to short-cycle at cycle peak, or do we have a plan to shift allocation as the cycle turns?

Red flag: Short-cycle shale over-allocation when long-cycle assets are available at cycle-trough pricing. VROC targets that require oil above $60/bbl to be sustained.

Council Trap: T7 — Shale Plateau Cliff (short-cycle over-allocation at cycle peak)

8 · ENI — Corporate Financial Exploration Model

Lens: FLNG on 3 continents, satellite architecture, self-funding exploration loop

Primary question: Is there a carry, FLNG, or satellite structure that funds this without balance sheet exposure, or are we defaulting to conventional financing when a better structure exists?

Red flag: Funding conventional exploration when a carry or satellite structure exists. Exploration cost taken to the income statement when it could be ring-fenced.

Council Trap: T8 — Exploration Cost Trap (funding conventional exploration when carry/FLNG/satellite structure exists)

9 · Occidental — Capital Allocation Redemption Engine

Lens: $38B Anadarko acquisition (2019), $40B→$13.8B deleveraging over 6 years, Buffett 26.64% stake, T9 Acquisition Leverage Trap

Institutional memory: Houston, August 2019 — CEO Vicki Hollub outbid Chevron's $33B offer for Anadarko Petroleum, paying $38B and quadrupling Occidental's debt to ~$40B in a single transaction. Carl Icahn (who built ~10% stake) called it "a catastrophic capital allocation error." The board was bypassed. Eight months later, oil prices went negative for the first time in history. The Chevron walkaway price is the permanent benchmark: the discipline Occidental abandoned is now its own primary institutional lesson.

The asset quality proved sufficient — barely. By 2025–2026: record production 1.43M BOEPD, principal debt ~$13.8B (deleveraged from ~$40B peak — over $26B retired in six years [UNCONFIRMED]), FCF $4.3B (2025). Warren Buffett's Berkshire Hathaway: 26.64% of common stock [UNCONFIRMED].

Primary question: What is this asset's standalone FCF at $30/bbl? If we acquire with debt, can we service it at $30/bbl for 24 consecutive months without an equity raise or dividend suspension?

Red flag: Acquisition premium paid over a competing bidder treated as proof of quality rather than evidence of price discipline failure. Debt load requiring >$50/bbl to service without asset sales. Synergy arguments substituting for asset-level FCF proof at $30/bbl. Board bypassed in deal approval. Second major acquisition before first acquisition debt is substantially retired.

When Enforcer: Guards balance sheet survivability across the full commodity price cycle. Every acquisition or major capital commitment is stress-tested at $30/bbl debt service capacity for 24 months. The question is never "can we fund this at today's oil price?" — it is "can we survive this debt at $30/bbl for 24 months without equity dilution or dividend suspension?"

Canonical lesson: Asset quality is the only margin of safety when leverage is existential. Without world-class underlying assets, T9 is terminal.

Council Trap: T9 — Acquisition Leverage Trap (overleveraged M&A at cycle peak — existential balance sheet exposure at $30/bbl)

Enforcer Selection Guide

The Enforcer is selected in Phase 1.5. EP-Council provides an opportunity-tailored recommendation, but the full 9-option menu is always shown.

See also: Trap Screen T0–T10 →

Go back to the Main README.

EP-Council — Trap Screen T0–T10

The Council Trap Screen is run by the Green Team after every red-team round. Any trap firing halts progress until the issue is addressed.

Traps are named after the supermajor whose institutional failure most clearly exemplifies the risk.

Trap Table

T0 — Strategic Drift

The non-negotiable stop. T0 fires whenever the opportunity contradicts the Strategy Brief on any of the 7 Strategy Brief dimensions: geography, asset type, capital envelope, return thresholds, portfolio philosophy, financing posture, or mandate constraints.

What happens when T0 fires: 1. The council halts immediately 2. The contradiction is documented explicitly 3. The user must choose: (a) reject the opportunity, or (b) formally amend the Strategy Brief before proceeding 4. If the Strategy Brief is amended, Phase 0 re-locks before any further assessment

T0 cannot be overridden by strategic rationale, timing pressure, or council consensus. It is a structural check, not a vote.

T9 — Acquisition Leverage Trap (New in v9)

The Occidental lesson. T9 fires when an acquisition is financed with debt that cannot be serviced from the target's own cash flows at $30/bbl for 24 consecutive months without an equity raise or dividend suspension.

The $30/bbl / 24-month test:

Can the target's standalone FCF at $30/bbl service the acquisition debt for 24 consecutive months? Yes → proceed to further analysis. No → T9 fires. No synergy premium, no integration argument, no strategic rationale substitutes for this test.

What T9 does NOT prohibit: - Leveraged acquisitions where the target's own FCF passes the $30/bbl / 24-month test - A second acquisition after the first acquisition debt is substantially retired - CrownRock-style re-entry (Occidental, December 2023) — a chastened acquirer with substantially retired debt, targeting a standalone tier-1 asset

Why the Chevron walkaway price matters: If a competing bidder walked away at a lower price, that price is a data point. The premium paid above the walkaway is not proof of quality — it is evidence of price discipline failure. Occidental paid $38B when Chevron walked at $33B. The $5B premium nearly destroyed the company.

Scale adjustment: The T9 test applies at any scale. The absolute numbers differ; the logic is identical. One tier-1 asset at low leverage beats two tier-2 assets at high leverage in every downturn.

T10 — Duration Drift (New in v9.1 / Skill v1.7)

The Shell lesson. T10 fires when a major funds distributions before/instead of the best organic reinvestment, allows R/P (reserve life) to shorten materially faster than production, or uses M&A as the primary reserve-replacement mechanism without a working organic engine.

The core distinction: acquired duration ≠ created duration. A buyback flatters EPS for a quarter; a producing barrel underwrites the next decade. When the shell of distribution discipline replaces the substance of organic renewal, the portfolio drifts from compounder to harvest vehicle without anyone naming the shift.

What T10 watches for: - Distribution policy fixed first, then organic capex sized to whatever remains - R/P shortening materially faster than production (i.e. reserves consumed faster than replaced) - M&A as the primary reserve-replacement mechanism — acquiring barrels because the organic engine isn't producing them

What T10 does NOT prohibit: - High distributions where organic reinvestment is fully funded first - M&A to add tier-1 acreage alongside a functioning organic program - Buyback programs in genuine harvest-vehicle strategies that have been explicitly chosen (rare, and must be in the Strategy Brief)

Relationship to T4 (Complexity Creep): Both are Shell-named, both are portfolio-shape traps. T4 catches additive drift (segments added without removal). T10 catches subtractive drift (organic renewal starved to fund distribution). A major can pass T4 and still fail T10.

Running the Trap Screen

The Green Team runs the trap screen after every red-team round. The screen covers all 11 traps in sequence.

For each trap: 1. State whether it fires: CLEAR or ACTIVE 2. If ACTIVE: document the specific evidence and halt until addressed

A round cannot close with any trap in ACTIVE status unless the full council votes to acknowledge and explicitly accept the risk — and the Enforcer documents the override.

See also: Council Members → | Walkthrough → | EP-Council main page →

Go back to the Main README.

EP-Council — Step-by-Step Walkthrough

A complete worked example showing how a full EP-Council session runs from invocation to final vote.

Before You Start

Have ready: - A clear description of the opportunity or decision you want tested - A Strategy Brief (or enough context for the council to construct one) - Approximately 30–90 minutes for a full multi-round session

Step 1 — Invoke the Council

Trigger the council with any of the following:

/ep-council [your opportunity description]

Or use natural language:

"Run the EP-Council on our proposed acquisition of a 40% working interest in Block X offshore Namibia, $800M carry, 3-year farm-in."

What happens next: The council opens with a Phase 0 Strategy Brief lock. The council will ask you to confirm the Strategy Brief before any red-teaming begins.

Step 2 — Lock the Strategy Brief

The council presents 7 dimensions for your review and confirmation:

Your action: Confirm, amend, or redirect the Strategy Brief.

Once you confirm, the brief is locked. No changes until all three red-team rounds are complete.

💡 Tip: If you are still exploring and don't have a firm strategy, tell the council. They will help you construct one before locking.

Step 3 — Phase 1 · Blue Team Assessment

The Blue Team (advocate faction) presents the opportunity's best case:

• Asset quality and resource characterisation
• Commercial terms and competitive context
• Strategic fit against the locked Strategy Brief
• Key value drivers and upside scenarios

Example Blue Team output:

"Block X is a proven play — Galp's discovery well logged 30m net pay at 29.7° API. At the proposed $800M carry, we are acquiring access to a 600MMboe resource at ~$1.33/boe discovered cost. The carry structure eliminates balance sheet exposure through the drill campaign. This is a tier-1 frontier basin with an established operator and a 2027 FID timeline consistent with our long-cycle mandate."

Step 4 — Round 1 Red Team (3 members challenge)

Three council members attack the Blue Team thesis. In Round 1, the faction is typically your most aggressive challengers for this opportunity type.

Example Round 1 — Offshore conventional (QatarEnergy, ConocoPhillips, Shell assigned):

QatarEnergy: "The 600MMboe resource estimate is unrisked. Risked recoverable resource at this play maturity is typically 30–40% of that number. We are not paying $800M for 180MMboe — that is $4.44/boe discovered cost. At what risked resource estimate does this deal still work at $60/bbl?"

ConocoPhillips: "The carry eliminates drilling exposure but not reservoir risk. What is the production decline rate on a Namibia-analog discovery, and what is the re-investment rate required to sustain plateau from 2030 onward? We need to model what the asset looks like in 2035, not at first oil."

Shell: "We are adding a new basin with a new operator. What are we removing from the portfolio to make room? Complexity Creep trap — T4 fires unless you can name what comes out."

Step 5 — Green Team Trap Screen (after Round 1)

The Green Team runs the full T0–T10 trap screen. Each trap is reported as CLEAR or ACTIVE.

Example trap screen after Round 1:

Your action: Respond to active traps before Round 2 begins.

"On T0: amend the Strategy Brief to include frontier deepwater where a carry structure eliminates balance sheet exposure. On T4: we will exit our 20% stake in Block Y Guyana to make room."

Step 6 — Round 2 Red Team (next 3 members)

Three new council members attack. Different perspectives, new angles.

Example Round 2 (BP, TotalEnergies, ExxonMobil assigned):

BP: "We amended the strategy to include frontier plays with carry. That is a meaningful change. Does the board know we are now in frontier exploration? This amendment should be flagged for board awareness even if it does not require a vote."

TotalEnergies: "The carry covers drilling. It does not cover development capital. If the discovery is commercial, development capex is our balance sheet risk. What is the estimated development cost per boe and what is the timeline to first cashflow?"

ExxonMobil (Enforcer): "We have an active trap resolution on T0 and T4. Before we proceed: confirm the board notification protocol for the strategy amendment, and confirm which asset exits Block Y Guyana with a timeline. Without those two confirmations, this round cannot close."

Step 7 — Green Team Trap Screen (after Round 2)

Re-run all traps. Active traps from Round 1 that were addressed should now clear.

Example:

Step 8 — Round 3 Red Team (final 3 members)

Final attack round. Remaining council members focus on residual risks and decision quality.

Example Round 3 (Chevron, ENI, Occidental assigned):

Chevron: "The 2027 FID assumption drives everything. What is the probability that FID slips to 2029? If it slips, what is the IRR impact and does the deal still clear our thresholds?"

ENI: "The carry structure — is it a gross carry or net carry? Gross carry removes all cost exposure. Net carry means we still carry our proportional share of G&G and well costs. What is the actual cash exposure under the net carry scenario?"

Occidental: "We are exiting Block Y Guyana to make room. What is the exit price assumption and what is the NAV drag if we sell in a soft market? The room-making exercise could cost us more than the upside we are acquiring."

Step 9 — Final Green Team Synthesis and Council Vote

After Round 3 and final trap screen, the Green Team synthesizes all rounds:

Green Team synthesis structure: 1. Trap screen summary (all traps: final status) 2. Round-by-round attack summary (key unresolved questions) 3. Modified opportunity profile (what changed from the original thesis) 4. Risk-adjusted return range 5. Council vote recommendation

Step 10 — The Vote

All 9 council members cast a named vote: PROCEED, CONDITIONAL, or REJECT.

Example vote:

Tally: 2 PROCEED · 6 CONDITIONAL · 1 REJECT

Verdict: Council recommends CONDITIONAL PROCEED. Six conditions must be documented before execution. QatarEnergy dissents on risked resource valuation — dissent is noted in the record.

Mid-Session Commands

What Makes a Good EP-Council Session

Do: - Lock a tight, specific Strategy Brief before red-teaming begins - Respond to trap screens directly — the council cannot proceed past an active trap without your acknowledgment - Name the specific conditions for CONDITIONAL votes — vague conditions do not protect you - Push back on council members — the council is adversarial by design; your defense strengthens the analysis

Do not: - Change the Strategy Brief mid-session without a formal /amend-brief command (T0 fires automatically) - Accept a CONDITIONAL vote without documenting every condition - Skip the trap screen output — traps protect you from the errors that have destroyed real companies - Run the council on an opportunity that is not in the Strategy Brief without first amending the brief

See also: Trap Screen → | Council Members → | EP-Council main page →

Go back to the Main README.

LLM-Council

Multi-LLM adversarial deliberation engine. Six simulated frontier models stress-test any decision, plan, or strategy across four mandatory phases — Socratic clarification, gated roadmap, tri-team red-team, and a 6-month failure premortem — then optionally deliver a single production-ready consolidated Word document.

Version: v1.1 (current) | Triggers: /coeus:llm-council · /council · "Jedi" · "May 4th" · "stress-test this plan" · "red team this" · "premortem"

What It Does

LLM-Council replaces single-pass, single-model reasoning with a structured, phase-gated multi-model debate. It simulates six distinct frontier AI voices — each with a documented epistemic style and failure mode — as an adversarial council that hardens any plan across two-to-three red-team rounds and a 6-month premortem before producing the final artifacts.

It is not a chatbot. It is a phase-gated engine. Phases cannot be skipped. The strategic roadmap cannot proceed to red-teaming without explicit user approval. The two artifacts (Final_Plan.md + Premortem_Report.md) are mandatory. The optional Phase 5 production document is opt-in and emoji-free by design.

LLM-Council is the general-purpose decision engine in Coeus. EP-Council is the domain-specific variant for upstream E&P opportunities — same phase-gate philosophy, different jury.

Installation

LLM-Council is bundled in coeus.plugin. No separate install.

Recommended: 1. Download coeus.plugin from Releases 2. Claude Desktop / Cowork → Settings → Capabilities → Customize → Add Plugin 3. Select coeus.plugin

Build from source:

git clone https://github.com/keithceh/Coeus.git
cd Coeus
python scripts/build-plugin.py     # cross-platform; UTF-8-flagged for Cowork

Then install dist/coeus.plugin via Add Plugin as above.

Triggers

Auto-trigger: Any consequential decision, plan, strategy, or technical question where depth is preferred over speed. LLM-Council leans toward firing rather than waiting for explicit invocation.

When to not trigger: trivial lookups, single-fact questions, code-only refactors, anything a one-pass answer handles well. Use Morpheus for prompt engineering and The Architect for the full prompt-engineering-plus-council pipeline.

The Pipeline

[User question / decision / plan]
           │
     Phase 1: Socratic Clarification
     ─ ≤3 targeted questions to refine the problem statement
     ─ Surface ambiguities, hidden assumptions, scope edges
     ─ Short-circuit if the input is already unambiguous
           │
     Phase 2: Strategic Roadmap + Gated Approval
     ─ 6 models each propose a high-level approach
     ─ Synthesis: primary recommendation, 3-5 action steps,
       key assumptions, top 3 risks
     ─ ★ EXPLICIT USER APPROVAL REQUIRED ★
           │
     Phase 3: Tri-Team Round-Robin Red-Team (2-3 rounds)
     ─ Blue defends · Red attacks · Green proposes alternatives
     ─ Models randomly re-assigned to factions every round
       (no model holds the same role in consecutive rounds)
     ─ Per-round synthesis incorporates strongest arguments
     ─ Convergence check after each round
           │
     Phase 4: 6-Month Failure Premortem Engine
     ─ Each model proposes 2-3 distinct failure scenarios
     ─ Scenarios clustered by theme
     ─ Severity × Probability matrix; top 3 clusters flagged
     ─ Pre-mortem mitigations baked back into the plan
           │
  [Final_Plan.md + Premortem_Report.md]
           │
     Phase 5: Production-Ready Document (OPT-IN)
     ─ Single yes/no prompt to the user
     ─ Consolidates all artifacts into one .docx
     ─ Every emoji replaced with plain-language substitute
     ─ 10-item failable QA checklist before delivery
           │
  [<topic>_Final_Production_v1.docx]

The Six Simulated Models

Each model plays a distinct epistemic role. Claude simulates all six voices in turn — they are simulations of epistemic styles, not impersonations of real products.

See Council Members → for the full profile of each voice (lens, primary question, characteristic failure mode, when to listen, when to discount).

Tri-Team Faction Allocation

Phase 3 splits the six models into three two-member factions, re-randomised every round.

Rules: - No model holds the same faction in consecutive rounds. - Assignments are stated at the top of every round so the user can see who is in which role. - Minimum 2 rounds; maximum 3 unless the user explicitly requests more. - Convergence check after each round — if factions converge, proceed to Phase 4; if not, run another round.

Phase Gates

LLM-Council has two mandatory gates and one optional gate. Gates cannot be bypassed by the assistant.

Output Artifacts

Both delivered as standalone code-fenced Markdown documents at the end of every council run.

Final_Plan.md - Executive summary (2–3 sentences) - Approved Strategic Roadmap (Phase 2 output with Phase 3 patches folded in) - Key decisions and rationale (with reference to the debate) - Assumptions the plan rests on - Top 3–5 risks with brief mitigations - Concrete, time-bound next steps

Premortem_Report.md - Failure scenarios grouped by cluster (resource, market, internal, technical, regulatory, key-person, etc.) - Severity × Probability matrix per cluster - Top 3 highest-risk clusters - Recommended safeguards embedded in the plan

Optional <topic>_Final_Production_v1.docx (Phase 5) - All 12 consolidated sections (cover page → glossary) - Emoji-free (canonical substitution table applied) - 10-item pre-delivery QA passed - Generated via python-docx or pandoc; markdown-only fallback if neither is in the runtime

See Step-by-Step Walkthrough → for what each artifact looks like in a real session.

Mid-Session Commands

Mandatory Flags & Guardrails

When To Use LLM-Council vs The Architect vs EP-Council

Related Pages

• Council Members → six-voice profiles
• Step-by-Step Session Walkthrough →
• EP-Council main page → (the E&P-specific sibling)
• Coeus README →

Version History

Go back to the Main README.

LLM-Council — Council Members

Six simulated frontier-model voices, each with a distinct epistemic role, a primary question, a characteristic failure mode, and a "when to listen / when to discount" call.

Hard rule: Each voice's primary question is asked at least once per phase. The six voices must each appear in every round of Phase 3 (distributed across the three factions, 2 per faction, re-randomised each round).

Reminder: These are simulations of epistemic styles — not impersonations of the real products. Treat the session as a structured debate, not as ground-truth multi-vendor consensus.

The Six Voices

The bias column shows the role each voice naturally leans into. Phase 3 randomisation overrides these defaults — every voice must spend time in every faction so its habitual lens does not become a fixed identity in the session.

Voice Profiles

1 · ChatGPT (GPT-4o) — Pragmatic Synthesiser

Lens: Actionable clarity, structured outputs, moderate hedging. Optimises for "what does the user do on Monday morning?"

Primary question: What is the concrete next action, and what does success look like in measurable terms?

Characteristic failure mode: Confident-sounding synthesis that smooths over genuine disagreement to produce a tidy bullet list. Risk: false consensus.

When to listen: When the council is over-philosophising and the user needs a usable plan by end of session.

When to discount: When the question is genuinely contested and the synthesis is hiding the contest behind a "balanced" recommendation.

2 · Grok — Contrarian Provocateur

Lens: Challenges consensus, surfaces uncomfortable truths, high epistemic confidence even on shaky ground.

Primary question: What is the council afraid to say out loud about this plan?

Characteristic failure mode: Confidence that outruns evidence. Will overstate a contrarian position to make it land.

When to listen: When the other voices have converged too quickly. Grok is the cheapest insurance against premature consensus.

When to discount: When the contrarian claim has no falsifiable mechanism behind it — provocation without substance.

3 · Claude — Careful Reasoner

Lens: Ethics-aware, uncertainty-flagging, multi-step logical decomposition. Treats reasoning chains as load-bearing.

Primary question: Which load-bearing claim in this plan depends on an unvalidated assumption, and how would we test it?

Characteristic failure mode: Over-hedging. May refuse to commit to a recommendation when commitment is what the user needs.

When to listen: Always. Claude is the conscience of the council — its job is to slow down decisions that have not earned their confidence.

When to discount: When the hedging has become a substitute for analysis. Force a "if you had to choose, what would you do?" prompt.

4 · Perplexity — Citation-Oriented Researcher

Lens: Grounds claims in evidence, flags unsupported assertions, distinguishes fact from inference.

Primary question: What is the source for that claim, and what would a contrary source say?

Characteristic failure mode: Treating presence of citations as proof of correctness. May cite poorly while sounding rigorous.

When to listen: When the plan rests on empirical claims that could be checked. Perplexity catches assertions presented as facts.

When to discount: When the question is normative, not factual — Perplexity has nothing distinctive to say about "should we?"

5 · DeepSeek — Systems Thinker

Lens: Second-order effects, game-theoretic framing, long-horizon analysis. Asks "if everyone did this, what happens?"

Primary question: What does this plan look like at 12, 24, and 36 months, including the reactions of every other party?

Characteristic failure mode: Analysis paralysis. Can map five interaction layers when one would have sufficed.

When to listen: When the plan involves other actors (competitors, regulators, partners) whose responses are not yet modelled.

When to discount: When the timeline is short and the actors are few. DeepSeek's edge dulls when the system is small.

6 · Le Chat (Mistral) — Nuanced European Perspective

Lens: Regulatory and societal context, human-centred design, jurisdictional nuance. Defaults to thinking about what regulators, civil society, and end-users will say.

Primary question: Who is harmed by this plan if it succeeds — and which regulator will notice first?

Characteristic failure mode: Treating EU/precautionary framing as a universal default. May over-weight regulatory risk in jurisdictions where it does not apply.

When to listen: When the plan touches data, people, money flows, or any regulated activity in a jurisdiction with active enforcement.

When to discount: When the activity is internal, low-stakes, or in a permissive jurisdiction where the regulatory frame adds noise rather than signal.

Faction Mechanics

Phase 3 places two voices in each of three factions:

Randomisation rule: Before every round, the six voices are randomly assigned (2 per faction). No voice may hold the same faction in consecutive rounds. The Phase 3 output explicitly states the round's assignment so the user can trace which voice argued what.

Why randomise: Habitual identification of a voice with a faction (e.g., always-Red Grok, always-Blue ChatGPT) becomes a fixed template and loses adversarial value. Forcing Claude into the Red role on round 2 produces a different (and often sharper) class of attack than Grok-as-Red.

Calibration Notes

• Six voices is the maximum, not the floor. If the user's question has no normative dimension, Le Chat may add noise — flag it but do not drop the voice; instead, weight its contribution less.
• Don't conflate "majority" with "right." A 5-1 vote where the dissenter is Claude flagging an unvalidated assumption is not a strong consensus. It is a 5-vote signal that the assumption has not been tested.
• The voices are weighted equally by default. If the user has domain context that justifies up- or down-weighting a voice for a specific session, they can request it (e.g., "for this regulatory question, weight Le Chat 2× and Grok 0.5×"). The council should accept the weighting and document it in the Final Plan.

See also: LLM-Council main page → | Step-by-Step Walkthrough →

Go back to the Main README.

LLM-Council — Step-by-Step Walkthrough

A complete worked example showing how a full LLM-Council session runs from invocation to final delivery, including the optional Phase 5 production document.

Before You Start

Have ready: - A clear description of the decision, plan, or strategy you want stress-tested. - Approximately 20–60 minutes for a full multi-round session (longer if you opt into Phase 5). - For Phase 5 (optional): Python with python-docx installed, or pandoc on PATH. If you have neither, the council will deliver the consolidated emoji-free markdown plus a one-line conversion command.

Step 1 — Invoke the Council

Trigger with any of:

/coeus:llm-council [your decision or plan]
/council [your decision or plan]

Or use natural language:

"Run the council on our plan to consolidate four regional data warehouses into a single lakehouse over the next 18 months."

What happens next: the council opens with Phase 1 (Socratic Clarification). The clarifying questions may be minimal if your input is already well-formed.

Step 2 — Phase 1 · Socratic Clarification

The council asks up to three decisive clarifying questions:

1. "Is the 18-month horizon a hard board-mandated date, or your internal preference?"
2. "Are the four warehouses owned or contracted — do we control the migration timing, or do we depend on vendor cooperation?"
3. "Does 'lakehouse' mean a specific platform (Databricks, Snowflake, Iceberg-on-S3) or is the platform itself in scope?"

Your action: answer the questions, or say "proceed as-is" if you want the council to work with stated assumptions.

💡 Tip: If your input was already unambiguous, the council short-circuits Phase 1 and goes straight to Phase 2. State your assumptions explicitly to skip this step.

Step 3 — Phase 2 · Strategic Roadmap + Gated Approval

Each of the six voices independently proposes a high-level approach (1–2 paragraphs each). Claude then synthesises:

Strategic Roadmap (draft):

Primary recommendation: Phased consolidation onto Iceberg-on-S3, starting with the smallest regional warehouse as a learn-as-we-go pilot in months 1–4, then parallelising the remaining three across months 5–14, with months 15–18 reserved for decommissioning and read-traffic verification.

Key action steps: (1) Pilot scope-lock in month 1; (2) Pilot cutover at month 4; (3) Parallel migration tracks for the remaining three warehouses with separate owner per track; (4) Read-traffic shadowing for 30 days before each cutover; (5) Decommissioning gate at month 16.

Key assumptions: vendor cooperation on read-only mirrors is achievable; team can hire two specialised engineers by month 2; the 18-month horizon includes a 2-month buffer.

Top 3 risks: (a) hidden semantic drift between regional schemas; (b) read-traffic dependencies the team is unaware of; (c) hiring slippage cascading into the parallel-track phase.

---

Gate: Do I have your approval to proceed to Phase 3 (tri-team red-team)?

Your action: reply "Proceed", "Approve", or your specific changes. Neutral responses do not pass the gate — the council will repeat the roadmap until you give an explicit yes or no.

Step 4 — Phase 3 · Tri-Team Round-Robin Red-Team

Round 1

Faction assignment (Round 1): 🔵 Blue: ChatGPT, Le Chat 🔴 Red: Grok, DeepSeek 🟢 Green: Claude, Perplexity

Red Team attacks: - Grok: "The 'smallest first' pilot is the wrong shape — small warehouses are small for a reason (low value), so the lessons learned don't generalise. Migrate the middle warehouse first." - DeepSeek: "The parallel-track phase assumes the four migrations are independent. In practice, the second-track team will be blocked by lessons from the first track they have not yet documented. This is a hidden serialisation."

Green Team proposes: - Claude: "Add an explicit 'lessons log' gate at month 5 that gates the parallel-track start on the pilot having produced a written runbook." - Perplexity: "There is published evidence from large warehouse-consolidation programs (Netflix 2019, Airbnb 2021) showing 12-month projects routinely run 60% over. An 18-month plan is realistically a 24-month plan with a hard deadline pressure."

Blue Team patches: - ChatGPT: "Accept Grok's middle-warehouse-first amendment. Accept Claude's lessons-log gate. The Perplexity overrun observation is a board-conversation, not a roadmap change — flag in the Final Plan." - Le Chat: "Add an explicit regulatory checkpoint: each regional warehouse may have residency requirements that differ. If the lakehouse is on US-East S3, we need a per-region legal review before each cutover."

Round-1 synthesis: Plan amended — pilot is now the middle-sized warehouse, lessons-log gate at month 5, per-region legal review embedded in each cutover. Perplexity's overrun warning recorded as a roadmap risk, not a roadmap change. Convergence check: factions still divergent on whether the 18-month horizon is realistic. Run round 2.

Round 2

Faction assignment (Round 2 — re-randomised, no voice in the same role as round 1): 🔵 Blue: Grok, Perplexity 🔴 Red: ChatGPT, Claude 🟢 Green: DeepSeek, Le Chat

(Round 2 proceeds in the same shape — Red attacks the amended plan, Green proposes alternatives, Blue patches. Synthesis at the end.)

Round-2 synthesis: Convergence on the technical roadmap. Remaining divergence: whether to negotiate a 21-month horizon with the board now or attempt 18 months and re-baseline at month 9.

Round 3 (optional, user decision)

If convergence is strong enough at round 2, the council proposes proceeding to Phase 4. The user accepts, and round 3 is skipped.

Step 5 — Phase 4 · 6-Month Failure Premortem

"Assume this plan has already failed catastrophically six months from now. What went wrong?"

Each voice proposes 2–3 distinct failure scenarios. Scenarios are clustered:

Top-3 mitigations (baked back into the plan): 1. Hiring: Start the engineering hire process in month 0, not month 2. Have one offer accepted before pilot kick-off. 2. Semantic drift: Add a 2-week schema-reconciliation phase before each migration track begins, owned by a data steward from the source warehouse. 3. Read-traffic: Run 60 days of read-traffic logging on each warehouse before any cutover plan is committed. The plan currently assumes 30 days post-amendment — bump to 60 pre-amendment.

Step 6 — Artifacts Delivered

The council now delivers the two mandatory artifacts inline:

# Final Plan — Warehouse Consolidation (4→1 Lakehouse, 18 months)
...
## Executive Summary
A 4-to-1 warehouse consolidation onto Iceberg-on-S3, phased over 18 months,
starting with the middle-sized regional warehouse as a pilot in months 1–4,
followed by parallel migration tracks for the remaining three across months 5–14,
with months 15–18 reserved for decommissioning and verification...

# Premortem Report — Warehouse Consolidation (4→1 Lakehouse, 18 months)
...
## Top 3 Risk Clusters
| Rank | Cluster | Likelihood | Impact | Risk Score |
|---|---|---|---|---|
| 1 | Hiring slippage | 4 | 4 | 16 |
| 2 | Hidden semantic drift | 3 | 5 | 15 |
| 3 | Read-traffic surprise | 3 | 4 | 12 |
...

Step 7 — Phase 5 · Production Document (Optional)

After the two artifacts land, the council asks exactly once:

"Final_Plan.md and Premortem_Report.md are delivered. Do you want a single production-ready Word document (.docx) that consolidates both artifacts, the Strategic Roadmap, and the red-team synthesis — emoji-free and distribution-ready? (yes / no)"

If you say no

The session ends. The two markdown artifacts above are the final delivery. Copy them into your tracking system, share with stakeholders, or paste into a doc tool yourself.

If you say yes

The council:

1. Consolidates all artifacts into a single document with 12 sections (cover page → executive summary → problem statement → strategic roadmap → six-model synthesis → tri-team rounds → final plan → premortem report → ranked mitigation framework → assumptions → decision-gate appendix → glossary).
2. Substitutes every emoji with a plain-language equivalent using the canonical table — 🔴 → [CRITICAL], 🟢 Green Team → Green Team, ✅ → [PASS], etc.
3. Runs a 10-item failable QA checklist: - Zero emojis remain (regex sweep clean) - All 12 sections present and in order - No TBD / placeholder tokens - All tables have header + data rows - All cross-references resolve - Heading levels contiguous - Page numbering + document title in footer/header - Word count and section count reported - Source artifacts match what was delivered in Phase 4 - Author/owner field matches the session
4. Generates the .docx via (in preference order) python-docx → pandoc → fallback (emoji-free markdown + one-line pandoc command).
5. Delivers with filename, word count, section count, generator tool used, and a confirmation that all 10 QA checks passed.

⚠️ If any QA check fails and cannot be auto-fixed, the council refuses to issue the file and surfaces the failure to you. A production document with an unresolved bug is worse than no document.

What A Full Session Looks Like (Time-Wise)

Common Pitfalls

• Approving the roadmap with "ok". "Ok" is not "approve". The gate requires an explicit affirmative — the council will repeat the roadmap until you give one.
• Asking for round 4+ without reason. More rounds rarely improve the plan; they usually re-cycle the same arguments. Trust the convergence check.
• Treating the six voices as ground truth. They are simulations. The session's value is the structure of the debate, not the literal positions attributed to each "model".
• Skipping Phase 5 because you "can just save the markdown". True for personal use; if the artifact is going to a board, regulator, or non-technical stakeholder, Phase 5's emoji substitution + QA checklist is the difference between a draft and a deliverable.

See also: LLM-Council main page → | Council Members →

Go back to the Main README.

Office Tools — OOXML & Project Lifecycle

Four utility skills that close gaps the generic docx / xlsx / memory-management skills do not cover. Born from real long-running document projects where repair, field correction, inventory extraction, and multi-session continuity all became repeated workflows.

Sibling family: Seismic Tools covers subsurface / DUG Insight project artefacts.

Version: 1.0 (current) | Triggers: see each skill below

What This Is

A bundle of four narrow, high-precision tools delivered together because they share an operational domain (long-running DOCX-centric project work) and call each other in practice:

1. ooxml-repair — diagnose and fix "Word found unreadable content" errors.
2. ooxml-fields — correct SEQ field numbering, REF field targets, caption styles.
3. docx-inventory — extract a complete figure/table inventory to xlsx.
4. project-lifecycle — session resume, handover note maintenance, file audit.

Each one is standalone and non-overlapping with the existing Coeus suite. None duplicates llm-council, ep-council, morpheus, the-architect, or plugin-creator.

When to Use Which

The Four Skills

1. ooxml-repair

Purpose: Diagnose and repair "Word found unreadable content" errors and other OOXML schema violations in DOCX files.

Slash command: /coeus:ooxml-repair

Triggers: "Word unreadable content", "docx corrupt", "fix docx error", "Word recovery dialog", "OOXML schema violation", "repair Word document".

Covers: ZIP integrity, XML well-formedness, w14:paraId validity and cross-file uniqueness, orphaned bookmarkEnd tags, orphaned comment references (most common root cause), duplicate style IDs, numbering chain integrity, relationship target existence, revision ID uniqueness, footnote reference integrity, mc:Requires namespace declarations. Includes the safe ZIP rebuild recipe that preserves flag_bits and create_version.

Does NOT cover: general Word editing (use docx), SEQ field correction (use ooxml-fields), inventory extraction (use docx-inventory).

Full SKILL.md →

2. ooxml-fields

Purpose: Manage SEQ fields, REF fields, and caption numbering inside DOCX files via direct XML manipulation.

Slash command: /coeus:ooxml-fields

Triggers: "fix figure numbers", "SEQ field", "caption numbering wrong", "table numbers out of order", "cross-reference broken", "REF field", "figure captions incorrect", "renumber figures", "SEQ counter reset", "caption style", "hardcoded figure number".

Covers: locating SEQ fields, reading and correcting cached SEQ values, detecting hardcoded caption numbers, auditing sequence integrity (gaps/duplicates), checking REF field targets resolve to defined bookmarks.

Does NOT cover: DOCX corruption (use ooxml-repair), general editing (use docx), structured xlsx inventory (use docx-inventory).

Full SKILL.md →

3. docx-inventory

Purpose: Extract a complete figure and table inventory from a DOCX file and write it to a two-sheet xlsx (Figures, Tables) with per-row issue flagging.

Slash command: /coeus:docx-inventory

Triggers: "figure inventory", "table inventory", "list all figures", "list all tables", "extract captions", "caption list", "figure list from docx", "audit captions", "inventory of figures", "what figures are in the document".

Output: xlsx with two sheets. Each row: paragraph index, cached SEQ number, caption text, style, detected issues (no-SEQ-field, duplicates, gaps).

Does NOT cover: editing (use docx), repair (use ooxml-repair), SEQ correction (use ooxml-fields), standalone xlsx creation (use xlsx).

Full SKILL.md →

4. project-lifecycle

Purpose: Manage the full lifecycle of a long-running, multi-session LLM project. Three sub-functions in one cluster skill.

Slash command: /coeus:project-lifecycle

Triggers: "resume this project", "pick up where we left off", "update the handover", "write a handover note", "create a handover doc", "update the changelog", "audit the project files", "what files are obsolete", "clean up the project folder", "which files can I delete", "session close", "end of session checklist".

Sub-functions:

Does NOT cover: Claude's own memory (use memory-management), creating specific document types (use docx/xlsx/pptx), or general research.

Full SKILL.md →

Why These Four Belong Together

Bundled as one umbrella so a user thinking "I have a DOCX problem and a project to manage" sees all four together rather than hunting through the wider skill list.

Related Pages

• OOXML Repair → full SKILL.md
• OOXML Fields → full SKILL.md
• DOCX Inventory → full SKILL.md
• Project Lifecycle → full SKILL.md
• Coeus README →

Version History

Go back to the Main README.

name: ooxml-repair version: 1.0 argument-hint: "[path to DOCX file with corruption or unreadable-content error]" description: > Trigger on: /ooxml-repair, "Word unreadable content", "docx corrupt", "fix docx error", "Word recovery dialog", "OOXML schema violation", "repair Word document", "unreadable content error", "Word can't open this file".

Diagnose and repair "Word found unreadable content" errors in DOCX files. Covers ZIP integrity, XML well-formedness, w14:paraId validity and uniqueness, orphaned bookmarkEnd tags, orphaned comment references (most common root cause), duplicate style IDs, numbering chain, rels targets, revision IDs, footnotes, mc:Requires. Includes the safe ZIP rebuild recipe that preserves flag_bits and create_version.

Do NOT use for normal Word editing (use docx), SEQ field correction (use ooxml-fields), or figure/table extraction (use docx-inventory). dependencies: []

Shared rules: confidence markers and hedged voices come from _shared/uncertainty_rules.md. Apply these whenever this skill emits a judgment, recommendation, or simulated voice.

OOXML DOCX Repair Skill

A complete, ordered checklist for diagnosing and fixing DOCX files that trigger Word's "Word found unreadable content" recovery dialog, built from the MAE-1R1 Well Completion Report repair sessions (June 2026).

Working Environment

All work on DOCX files happens in a scratch directory — never edit the source file in place. The safe rebuild recipe is mandatory for every deployment.

scratch/
├── unpacked_<name>/word/document.xml   ← edited XML
└── <name>_base_fixed.docx             ← ZIP template (never edited directly)

Safe Rebuild Recipe

Use this for every output DOCX. It preserves the original ZIP's flag_bits and create_version per entry, which Word checks during open.

import zipfile, io

def rebuild_docx(base_path, new_doc_xml_path, out_path):
    with open(base_path, 'rb') as f:
        orig_data = f.read()
    with open(new_doc_xml_path, 'rb') as f:
        new_doc_xml = f.read()
    buf = io.BytesIO(orig_data)
    with zipfile.ZipFile(buf, 'r') as zf_in:
        with zipfile.ZipFile(out_path, 'w') as zf_out:
            for info in zf_in.infolist():
                data = new_doc_xml if info.filename == 'word/document.xml' \
                       else zf_in.read(info.filename)
                new_info = zipfile.ZipInfo(filename=info.filename)
                new_info.flag_bits    = info.flag_bits
                new_info.create_version = info.create_version
                new_info.compress_type  = info.compress_type
                zf_out.writestr(new_info, data)

Important ZIP notes: - Some large DOCX files have zero-padding after the EOCD (End Of Central Directory). Read only the bytes before the EOCD if zipfile raises BadZipFile. Use orig_data[:real_eocd_end] after finding the EOCD offset. - Never use Python's default zipfile.ZipFile(path, 'w') on the original file — it discards flag_bits and create_version.

Diagnosis Checklist

Run every check before deploying. Each check is independent.

1. ZIP Integrity

import zipfile
with zipfile.ZipFile('output.docx', 'r') as zf:
    bad = zf.testzip()
    print('CRC OK' if bad is None else f'FAIL: {bad}')

2. XML Well-Formedness (All XML Files)

from lxml import etree
import zipfile, io
with zipfile.ZipFile('output.docx', 'r') as zf:
    for name in [n for n in zf.namelist() if n.endswith('.xml') or n.endswith('.rels')]:
        try:
            etree.fromstring(zf.read(name))
        except etree.XMLSyntaxError as e:
            print(f'PARSE ERROR: {name}: {e}')

3. w14:paraId Validity (document.xml + all headers/footers)

Every w14:paraId must be exactly 8 uppercase hex digits, unique across all XML files in the ZIP (document.xml, header.xml, footer.xml, footnotes.xml, endnotes.xml, comments.xml).

import re

def check_para_ids(text, label):
    all_ids = re.findall(r'w14:paraId="([^"]+)"', text)
    invalid = [p for p in all_ids if not re.match(r'^[0-9A-Fa-f]{8}$', p)]
    dupes   = {v for v in all_ids if all_ids.count(v) > 1}
    print(f'{label}: total={len(all_ids)}, invalid={len(invalid)}, dupes={len(dupes)}')
    return all_ids

Fix for invalid paraIds (must be 8 hex chars): generate new random hex IDs using uuid.uuid4().hex[:8].upper() and ensure uniqueness across the pool.

Fix for duplicate paraIds in VML textbox fallbacks: OOXML DrawingML textboxes (<wps:txbx>) have a legacy VML mirror (<v:textbox>). The paragraphs inside both representations share the same w14:paraId, causing cross-document duplicates. Rename the second (VML) occurrence by searching for the pattern:

# VML fallback paragraphs appear AFTER the DrawingML block.
# Find paragraphs in <v:textbox> context and assign new unique IDs.

4. Orphaned bookmarkEnd Tags

Every <w:bookmarkEnd w:id="N"/> must have a matching <w:bookmarkStart w:id="N"/> earlier in the document.

starts = set(re.findall(r'<w:bookmarkStart\b[^>]+w:id="(\d+)"', doc))
ends   = set(re.findall(r'<w:bookmarkEnd\b[^>]+w:id="(\d+)"', doc))
orphaned_ends = ends - starts
# Fix: delete each <w:bookmarkEnd w:id="N"/> where N in orphaned_ends

Note: Two <w:sectPr> in a document is not a violation when one is inside <w:pPr> (mid-doc section break marker). Only the final direct child of <w:body> is the "real" sectPr.

5. Orphaned Comment References — PRIMARY FIX for MAE-1R1

This was the root cause of the persistent "unreadable content" error.

Every <w:commentReference w:id="N"/>, <w:commentRangeStart w:id="N"/>, and <w:commentRangeEnd w:id="N"/> in document.xml must have a corresponding <w:comment w:id="N"> in word/comments.xml. When comments are deleted in Word but their range markers remain in the document body, this violation occurs.

# Detect
comment_ids_defined = set(re.findall(r'<w:comment\b[^>]+w:id="(\d+)"', comments_xml))
comment_ids_in_doc  = set(re.findall(r'<w:commentReference[^>]+w:id="(\d+)"', doc))
orphaned = comment_ids_in_doc - comment_ids_defined

# Fix via lxml (removes commentRangeStart, commentRangeEnd, and containing run)
from lxml import etree
W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
tree = etree.fromstring(doc_bytes)
# For each elem in tree.iter():
#   if elem.get('{W}id') in orphaned:
#     tag = elem.tag.split('}')[-1]
#     if tag == 'commentRangeStart': parent.remove(elem)
#     if tag == 'commentRangeEnd':   parent.remove(elem)
#     if tag == 'commentReference':
#       r = parent_of_elem  # the containing <w:r>
#       non_rpr = [c for c in r if c.tag not in (rPr_tag, commentReference_tag)]
#       if not non_rpr: grandparent.remove(r)  # run is comment-only
#       else: r.remove(elem)                   # run has real content

6. Duplicate Style IDs (styles.xml)

style_ids = re.findall(r'w:styleId="([^"]+)"', styles_xml)
dupes = {v for v in style_ids if style_ids.count(v) > 1}

7. Numbering Chain Integrity (numbering.xml)

defined_abstract = set(re.findall(r'<w:abstractNum\b[^>]+w:abstractNumId="(\d+)"', num_xml))
num_refs         = set(re.findall(r'<w:abstractNumId w:val="(\d+)"', num_xml))
broken = num_refs - defined_abstract
# Also check: numIds referenced in document exist in numbering.xml

8. Relationship Target Existence (all .rels files)

with zipfile.ZipFile('output.docx', 'r') as zf:
    all_files = set(zf.namelist())
    for rels_name in [n for n in all_files if n.endswith('.rels')]:
        rels = zf.read(rels_name).decode('utf-8')
        for target in re.findall(r'Target="([^"]+)"', rels):
            if target.startswith(('http', 'mailto', '#')): continue
            full = target[3:] if target.startswith('../') else 'word/' + target
            if full not in all_files:
                print(f'MISSING: {rels_name} -> {target}')

9. Revision ID Uniqueness (document.xml)

for rtype in ['w:ins', 'w:del', 'w:moveFrom', 'w:moveTo',
              'w:rPrChange', 'w:pPrChange', 'w:sectPrChange',
              'w:tblPrChange', 'w:trPrChange', 'w:tcPrChange']:
    ids = re.findall(rf'<{rtype}\b[^>]+w:id="(\d+)"', doc)
    dupes = {v for v in ids if ids.count(v) > 1}
    if dupes: print(f'{rtype} DUPES: {dupes}')

10. Cross-File paraId Uniqueness

all_ids = {}
for fname in ['word/document.xml', 'word/header1.xml', 'word/header2.xml',
              'word/header3.xml', 'word/footer1.xml', 'word/footer2.xml',
              'word/footer3.xml', 'word/footnotes.xml', 'word/endnotes.xml',
              'word/comments.xml']:
    data = zf.read(fname).decode('utf-8')
    for pid in re.findall(r'w14:paraId="([^"]+)"', data):
        all_ids.setdefault(pid, []).append(fname)
cross_dupes = {k: v for k, v in all_ids.items() if len(v) > 1}

11. Footnote / Endnote Reference Integrity

fn_refs     = set(re.findall(r'<w:footnoteReference[^>]+w:id="(\d+)"', doc))
fn_defined  = set(re.findall(r'<w:footnote\b[^>]+w:id="(\d+)"', footnotes_xml))
missing_fn  = fn_refs - fn_defined

12. Header/Footer r:id Without Rels File

If word/header2.xml has a rels file but header1.xml does not, any r:id references in header1.xml are broken. Check:

for hf in ['word/header1.xml', 'word/header2.xml', 'word/header3.xml',
           'word/footer1.xml', 'word/footer2.xml', 'word/footer3.xml']:
    rels_name = hf.replace('word/', 'word/_rels/') + '.rels'
    has_rels = rels_name in all_files
    r_refs = re.findall(r'\br:(?:id|embed)="([^"]+)"', zf.read(hf).decode())
    if r_refs and not has_rels:
        print(f'ORPHANED refs in {hf}: {r_refs}')

13. mc:Requires Namespace Declarations

required = re.findall(r'mc:Requires="([^"]+)"', doc)
ns_decls = re.findall(r'xmlns:(\w+)=', doc[:5000])
for req in required:
    for prefix in req.split():
        if prefix not in ns_decls:
            print(f'UNDECLARED required ns: {prefix}')

Document.xml lxml Round-Trip

When using lxml to edit document.xml, serialize with:

new_bytes = etree.tostring(tree, xml_declaration=True, encoding='UTF-8', standalone=True)

lxml is safe for this document (confirmed). It preserves namespace declarations and attribute order. The round-trip does not introduce any paraId or structural changes.

MAE-1R1 v11 Reference Data (Known-Good State + Repair History)

Project-specific reference data lives in ../../docs/Ooxml-Repair-MAE1R1-Reference.md. Load it when comparing a current diagnostic against the v11 baseline or when reviewing the session-by-session repair history (Sessions 4, 5, 6 — including the orphaned-commentReference root-cause find).

Notes

• Narrow no-break space (U+202F): Used throughout document between numerals and units (e.g., 88.5 MMscfd). Preserve when editing text content.
• Two sectPr in document: Valid — first is inside <w:pPr> (mid-document section break), second is the final body element. Not a violation.
• Comments defined greater than referenced: 81 defined / 38 referenced in v11. The 43 extra comment definitions in comments.xml (defined but not anchored to any document text) are not an OOXML violation per spec. Only orphaned references (in doc body pointing to non-existent comments) are violations.
• commentsExtended.xml / commentsIds.xml: Reference w15:paraId of paragraphs within comments.xml, not the document body. Safe to leave untouched when only cleaning document.xml.

name: ooxml-fields version: 1.0 argument-hint: "[path to DOCX file with SEQ field, REF field, or caption numbering issue]" description: > Trigger on: /ooxml-fields, "fix figure numbers", "SEQ field", "caption numbering wrong", "table numbers out of order", "cross-reference broken", "REF field", "figure captions incorrect", "renumber figures", "SEQ counter reset", "caption style", "hardcoded figure number".

Manage SEQ fields, REF fields, and caption numbering in DOCX files. Use this skill when figure or table numbers are wrong, out of sequence, duplicated, or missing; when cross-references (REF fields) point to the wrong caption; when SEQ counter resets unexpectedly; or when a caption inventory needs to be audited or corrected programmatically via XML. Also use for identifying and correcting hardcoded caption numbers (plain text "Figure X:" that lacks a SEQ field) and for checking that all captions use the correct paragraph style (Caption style).

Do NOT use for DOCX corruption repair (use ooxml-repair), general Word editing (use docx), or extracting a full figure/table inventory to xlsx (use docx-inventory). dependencies: []

OOXML Fields — SEQ Field and Caption Management

Overview

DOCX figure and table numbering is controlled by SEQ fields inside <w:fldChar> / <w:instrText> elements in document.xml. When these are wrong, the F9 recalculation in Word fixes displayed values — but the underlying XML may still have cached wrong values or be missing fields entirely.

All work on DOCX files must happen in a scratch copy. Never edit the source file in place.

1. Locate All SEQ Fields

Parse document.xml (unzip the DOCX first):

import zipfile, re

def get_seq_fields(docx_path):
    with zipfile.ZipFile(docx_path, 'r') as zf:
        doc = zf.read('word/document.xml').decode('utf-8')
    # SEQ instructions appear in <w:instrText> elements
    # They may be split across multiple instrText elements (complex fields)
    # Simple pattern covers most cases:
    seq_figure = re.findall(r'SEQ\s+Figure\b[^<]*', doc, re.IGNORECASE)
    seq_table  = re.findall(r'SEQ\s+Table\b[^<]*',  doc, re.IGNORECASE)
    return seq_figure, seq_table

For paragraph-level analysis, extract paragraphs with their indices:

from lxml import etree

W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'

def get_caption_paragraphs(doc_bytes):
    tree = etree.fromstring(doc_bytes)
    body = tree.find(f'{{{W}}}body')
    results = []
    for i, para in enumerate(body):
        tag = para.tag.split('}')[-1]
        if tag != 'p':
            continue
        # Get paragraph style
        pPr = para.find(f'{{{W}}}pPr')
        style = None
        if pPr is not None:
            pStyle = pPr.find(f'{{{W}}}pStyle')
            if pStyle is not None:
                style = pStyle.get(f'{{{W}}}val')
        # Get all text
        texts = ''.join(t.text or '' for t in para.iter(f'{{{W}}}t'))
        # Get SEQ field instruction text
        instrs = [e.text or '' for e in para.iter(f'{{{W}}}instrText')]
        seq_instr = [i for i in instrs if 'SEQ' in i.upper()]
        if seq_instr or (style and 'caption' in style.lower()):
            results.append({
                'para_index': i,
                'style': style,
                'text': texts,
                'seq_instrs': seq_instr,
            })
    return results

2. Read Cached SEQ Values

The displayed number (cached result) is in <w:fldChar w:fldCharType="separate"> ... <w:t> ... <w:fldChar w:fldCharType="end">. Extract it:

def get_cached_seq_value(para_element):
    """Returns the cached display value of the first SEQ field in a paragraph."""
    W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
    in_field = False
    after_sep = False
    for run in para_element.iter(f'{{{W}}}r'):
        for child in run:
            tag = child.tag.split('}')[-1]
            if tag == 'fldChar':
                ftype = child.get(f'{{{W}}}fldCharType')
                if ftype == 'begin':
                    in_field = True
                    after_sep = False
                elif ftype == 'separate':
                    after_sep = True
                elif ftype == 'end':
                    in_field = False
                    after_sep = False
            elif tag == 't' and after_sep and in_field:
                return child.text
    return None

3. Correct Cached Values

When a cached value is wrong (e.g., shows "3" but should show "4"), update it:

def set_cached_seq_value(para_element, new_value: str):
    """Replace the cached display value of the first SEQ field in a paragraph."""
    W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
    in_field = False
    after_sep = False
    for run in para_element.iter(f'{{{W}}}r'):
        for child in list(run):
            tag = child.tag.split('}')[-1]
            if tag == 'fldChar':
                ftype = child.get(f'{{{W}}}fldCharType')
                if ftype == 'begin':   in_field = True;  after_sep = False
                elif ftype == 'separate': after_sep = True
                elif ftype == 'end':   in_field = False; after_sep = False
            elif tag == 't' and after_sep and in_field:
                child.text = new_value
                return True
    return False

Note: Correcting the cached value fixes what is displayed when the DOCX is opened WITHOUT recalculation. The user should still press Ctrl+A then F9 in Word after opening to recalculate all fields from scratch.

4. Check for Hardcoded Caption Numbers

A "hardcoded" caption has plain text like "Figure 3:" with no SEQ field:

def find_hardcoded_captions(results):
    """Flag caption-style paragraphs that have no SEQ field instruction."""
    return [r for r in results
            if not r['seq_instrs']
            and re.search(r'(Figure|Table)\s+\d+', r['text'], re.IGNORECASE)]

Hardcoded captions will NOT update when fields are recalculated. They must either be left as-is (with a note) or converted to proper SEQ fields manually in Word. Do not attempt to add SEQ fields programmatically — the field structure is complex and safer to insert via Word's Insert then Field dialog.

5. Audit SEQ Sequence Integrity

def audit_seq_sequence(caption_paragraphs, seq_type='Figure'):
    """Check for gaps and duplicates in the SEQ sequence."""
    seq_items = [r for r in caption_paragraphs
                 if any(seq_type.upper() in i.upper() for i in r['seq_instrs'])]
    numbers = []
    for item in seq_items:
        val = item.get('cached_value')
        if val and val.isdigit():
            numbers.append((item['para_index'], int(val)))
    numbers.sort(key=lambda x: x[1])
    issues = []
    for i, (pidx, n) in enumerate(numbers):
        expected = i + 1
        if n != expected:
            issues.append(f'Para #{pidx}: expected SEQ {seq_type} #{expected}, cached = {n}')
    return issues

6. REF Field Checking

Cross-references to captions use REF fields pointing to bookmarks created by the SEQ field. Check that every REF target bookmark exists:

def check_ref_fields(doc_bytes):
    W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
    doc = doc_bytes.decode('utf-8')
    ref_targets = re.findall(r'REF\s+(_Ref\w+)', doc)
    bookmark_names = re.findall(r'w:name="(_Ref\w+)"', doc)
    defined = set(bookmark_names)
    missing = [t for t in ref_targets if t not in defined]
    return missing  # Empty list = all REFs have targets

7. MAE-1R1 WCR v11 — Protected Elements

When working on ZZ-99-TN-xxxxxx-MAE-1R1 Well Completion Report_draft_v11.docx, the following elements MUST NOT be modified under any circumstances:

Protected drawing paragraphs (Section 8.3 images)

Para indices in body element list: {2377, 2387, 2390, 2402} These contain drawings for Figures 67–70 (rIds rId92–rId95, image73–image76.png). Do not alter, remove, or reparent these paragraphs.

Protected caption paragraph indices (SEQ cached values only — safe to edit)

2380 (Figure 68 caption), 2391 (Figure 69 caption), 2403 (Figure 70 caption) These captions may have their cached SEQ values corrected. The paragraph element itself and its drawing sibling must not be touched.

Protected rIds

rId92, rId93, rId94, rId95 map to image73.png, image74.png, image75.png, image76.png. Do not reassign, delete, or renumber these relationship IDs.

Hardcoded caption — do not convert

Para #2454: contains plain text "Table 36:" with no SEQ field. This is intentional. Do not add a SEQ field here — it would conflict with any Table SEQ field inserted before it.

8. Known Good State — MAE-1R1 v11 (after Session 13)

name: docx-inventory version: 1.0 argument-hint: "[path to DOCX file to inventory] [optional output xlsx path]" description: > Trigger on: /docx-inventory, "figure inventory", "table inventory", "list all figures", "list all tables", "extract captions", "caption list", "figure list from docx", "audit captions", "inventory of figures", "what figures are in the document".

Extract a complete figure and table inventory from a DOCX file and write it to an xlsx spreadsheet. Use this skill when the user needs a list of all figures or tables in a Word document, wants to audit caption numbering, needs to find captions with missing or incorrect SEQ fields, or wants a structured inventory for cross-referencing. Output is an xlsx with two sheets: one for figures, one for tables. Each row includes: paragraph index, SEQ number (cached), caption text, paragraph style, and any issues detected.

Do NOT use for general DOCX editing (use docx), DOCX repair (use ooxml-repair), SEQ field correction (use ooxml-fields), or standalone xlsx creation (use xlsx). dependencies: []

DOCX Inventory — Figure and Table Extraction

Produces a structured xlsx inventory of all figures and tables in a DOCX file by parsing the OOXML directly. Does not require Word to be installed.

1. Dependencies

pip install openpyxl lxml --break-system-packages

2. Extraction Script

Save as extract_inventory.py and run it, or execute inline via bash:

import zipfile, re, sys
from lxml import etree
import openpyxl
from openpyxl.styles import Font, PatternFill, Alignment

def extract_inventory(docx_path, out_xlsx_path):
    W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'

    with zipfile.ZipFile(docx_path, 'r') as zf:
        doc_bytes = zf.read('word/document.xml')

    tree = etree.fromstring(doc_bytes)
    body = tree.find(f'{{{W}}}body')

    figures = []
    tables  = []

    def get_text(para):
        return ''.join(t.text or '' for t in para.iter(f'{{{W}}}t'))

    def get_seq_instr(para):
        return [e.text or '' for e in para.iter(f'{{{W}}}instrText')
                if e.text and 'SEQ' in e.text.upper()]

    def get_cached_value(para):
        in_field = after_sep = False
        for run in para.iter(f'{{{W}}}r'):
            for child in run:
                tag = child.tag.split('}')[-1]
                if tag == 'fldChar':
                    ft = child.get(f'{{{W}}}fldCharType', '')
                    if ft == 'begin':    in_field = True;  after_sep = False
                    elif ft == 'separate': after_sep = True
                    elif ft == 'end':    in_field = False; after_sep = False
                elif tag == 't' and after_sep and in_field:
                    return child.text
        return None

    for i, elem in enumerate(body):
        tag = elem.tag.split('}')[-1]
        if tag != 'p':
            continue
        pPr = elem.find(f'{{{W}}}pPr')
        style = None
        if pPr is not None:
            pStyle = pPr.find(f'{{{W}}}pStyle')
            if pStyle is not None:
                style = pStyle.get(f'{{{W}}}val', '')

        text    = get_text(elem)
        instrs  = get_seq_instr(elem)
        cached  = get_cached_value(elem)

        is_fig_seq = any('SEQ' in s.upper() and 'FIGURE' in s.upper() for s in instrs)
        is_tbl_seq = any('SEQ' in s.upper() and 'TABLE'  in s.upper() for s in instrs)

        # Also catch caption-style paragraphs starting with Figure/Table
        is_fig_text = bool(re.match(r'Figure\s+\d+', text, re.IGNORECASE))
        is_tbl_text = bool(re.match(r'Table\s+\d+',  text, re.IGNORECASE))

        issues = []
        if (is_fig_text or is_fig_seq) and not is_fig_seq:
            issues.append('No SEQ Figure field — hardcoded')
        if (is_tbl_text or is_tbl_seq) and not is_tbl_seq:
            issues.append('No SEQ Table field — hardcoded')

        if is_fig_seq or is_fig_text:
            figures.append({
                'para_index': i,
                'seq_num': cached or '',
                'text': text[:200],
                'style': style or '',
                'issues': '; '.join(issues),
            })
        elif is_tbl_seq or is_tbl_text:
            tables.append({
                'para_index': i,
                'seq_num': cached or '',
                'text': text[:200],
                'style': style or '',
                'issues': '; '.join(issues),
            })

    # Check for duplicate and gap SEQ numbers
    def add_seq_issues(rows, label):
        nums = [(r['seq_num'], r['para_index']) for r in rows if r['seq_num'].isdigit()]
        nums.sort(key=lambda x: int(x[0]))
        seen = {}
        for n, pidx in nums:
            if n in seen:
                for r in rows:
                    if r['para_index'] == pidx:
                        r['issues'] = (r['issues'] + f'; DUPLICATE SEQ {label} #{n}').strip('; ')
            seen[n] = pidx
        # Gap check
        int_nums = sorted(int(n) for n, _ in nums)
        for j, n in enumerate(int_nums):
            if n != j + 1:
                print(f'  GAP: expected {label} #{j+1}, found #{n}')

    add_seq_issues(figures, 'Figure')
    add_seq_issues(tables, 'Table')

    # Write xlsx
    wb = openpyxl.Workbook()
    header_font = Font(bold=True, color='FFFFFF')
    header_fill = PatternFill('solid', fgColor='2F4F8F')

    def write_sheet(ws, rows, label):
        ws.title = label
        headers = ['Para Index', f'SEQ # (cached)', 'Caption Text', 'Style', 'Issues']
        ws.append(headers)
        for cell in ws[1]:
            cell.font = header_font
            cell.fill = header_fill
            cell.alignment = Alignment(horizontal='center')
        for r in rows:
            ws.append([r['para_index'], r['seq_num'], r['text'], r['style'], r['issues']])
            if r['issues']:
                ws.cell(ws.max_row, 5).font = Font(color='CC0000')
        ws.column_dimensions['C'].width = 80
        ws.column_dimensions['E'].width = 40

    ws_fig = wb.active
    write_sheet(ws_fig, figures, 'Figures')
    ws_tbl = wb.create_sheet('Tables')
    write_sheet(ws_tbl, tables, 'Tables')

    wb.save(out_xlsx_path)
    print(f'Inventory written: {out_xlsx_path}')
    print(f'  Figures: {len(figures)} ({sum(1 for r in figures if r["issues"])} with issues)')
    print(f'  Tables:  {len(tables)} ({sum(1 for r in tables if r["issues"])} with issues)')

3. Usage

python extract_inventory.py \
  "C:/Claude/Claude-Work/Projects/Technical_Reports/Inputs/ZZ-99-TN-xxxxxx-MAE-1R1 Well Completion Report_draft_v11.docx" \
  "C:/Claude/Claude-Work/Projects/Technical_Reports/Outputs/MAE-1R1_WCR_Figure_Table_Inventory_v11.xlsx"

Or run inline via the bash tool using the script content above.

4. Output Format

Sheet: Figures

Sheet: Tables

Same structure for tables.

Issues column flags: No SEQ field — hardcoded, DUPLICATE SEQ Figure #N, gaps printed to stdout.

5. Known Output — MAE-1R1 v11 (reference values)

After Session 13 corrections:

Project-Lifecycle

Five-sub-function cluster skill that manages the full lifecycle of a long-running, multi-session LLM project: kickoff, resume, handover-doc maintenance, file audit, and session close. Three core files (handover, artefacts index, telemetry log) are created once at kickoff and updated in place thereafter — no timestamped duplicates.

Version: v1.3.0 (current) | Triggers: /coeus:project-lifecycle · "new project" · "resume this project" · "update the handover" · "audit the project files" · "session close"

What It Does

Project-Lifecycle replaces ad-hoc session management with a structured five-stage protocol. It is not a chatbot — it is a phase-gated cluster that creates persistent project artefacts at kickoff and refreshes them at every cadence trigger. The contract is "one file per concern, write-once-create / update-in-place" — the artefacts index never points at files that no longer exist, the telemetry log never fragments across timestamped files, and the handover note is the single source of truth for project state.

It is the only Coeus skill that fires at session boundaries (start + end). Every other skill fires on demand; this one fires on the clock.

Installation

Bundled in coeus.plugin. No separate install.

Recommended: 1. Download coeus.plugin from Releases 2. Claude Desktop / Cowork → Settings → Capabilities → Customize → Add Plugin 3. Select coeus.plugin

Build from source: python scripts/build-plugin.py (cross-platform, UTF-8-flagged for Cowork).

Triggers

Auto-trigger: firing the skill at session boundaries is its purpose — never wait for the user to ask twice if they say "new chat", "starting work on", or "session close".

Do NOT use for: Claude's own memory (use memory-management), creating specific document types (use docx / xlsx / pptx), or general research.

The Five Sub-Functions

                                  PROJECT TIMELINE
                                  ─────────────────────────────────
  Session 1  │  Session 2  │  …  │  Session N
  ▼          ▼             ▼     ▼
  K          A (or K)      A     A         ← at every session start
  │          │             │     │
  ├──────────┴─────────────┴─────┤
  │   B / C fire ad-hoc          │         ← during work
  │                              │
  ▼                              ▼
  D                              D         ← at every session end

Detail for each sub-function lives in skills/_shared/lifecycle_{kickoff,resume,handover,audit,close}.md — load on demand.

The Three Core Files

Project-Lifecycle's defining design: every multi-session project has exactly three persistent files, created once at kickoff, updated in place thereafter. No timestamped duplicates. No _telemetry/index.md rollup. No write amplification.

This contract closes three failure modes: - FM-L2-01 (kickoff friction) — silent cadence default, no menu - FM-L2-02 (write amplification) — artefacts index regen on close only - FM-L2-03 (telemetry orphan) — single append-only log is its own index

Update Cadence

Selected silently at kickoff; default = end-of-session. Override anytime by saying "use ultradian", "per-action", "daily", "milestone", or "custom: <spec>".

Full options table + evidence basis in ../skills/_shared/lifecycle_frequency.md.