octopus

Run one high-stakes decision through a council of 5 ephemeral advisor lenses that answer in parallel, peer-review each other anonymously, and get synthesised into a single verdict — agreements, clashes, blind spots, a recommendation, and the one thing to do first. Adapted from Karpathy's LLM Council. For genuine decisions with stakes and tradeoffs, not factual lookups or creation tasks.

PR-time dual-delta read of coverage/complexity/module-size/dependency-cycles vs. orphan-ref baseline; ratchet+absolute thresholds; LLM curation only on breach.

Shrink a SKILL.md without changing meaning — deterministic cleanup first, LLM rewrite only if the target isn't met. Test-file anchors preserved; frontmatter, headings, and code blocks never modified. Dry-run by default; --apply writes.

Capture insights, test hypotheses, and promote confirmed patterns to rules (adapted for multi-agent environments). Default mode is single- developer/session capture to knowledge/. Team mode aggregates recurring review feedback across the fleet into rule-promotion candidates — fleet-wide patterns promote to shared workspace rules, single-repo patterns stay local.

Create, update, and validate the team's Definition of Done (docs/definition- of-done.md). create/update scaffolds from a template and grills the manager for team items; validate walks a diff/PR against the checklist (met/unmet/not-applicable). Signal-only contract referencing existing enforcement (architect, security, audit-*, guardrails) — never gates a commit. Consumed by codereview.

Proactive cadence summary over a knowledge root — 'what changed / what needs you today' without being asked. Deterministic core (octopus briefing, over the octopus kr registry) computes the change-delta since a per-root watermark and composes octopus hygiene + synthesize; this skill narrates it, grounded to source nodes, on the cheapest tier.

Audit a registered knowledge root (docs/, standards, auto-memory, consigliere workspace) for decay — stale nodes, broken links, orphans, concluded items outside their archive. Deterministic checks via octopus hygiene over the octopus kr registry; this skill adds --gaps judgment and --fix confirmation. Read-only by default; --fix is reversible.

Surface cross-node connections in a knowledge root. The deterministic core (octopus synthesize, over the octopus kr registry) ranks candidates — shared-target, co-mention, and --node relevance (forgotten-but-relevant); this skill judges which are real, flags contradictions, and seeds missing links with --fix.

Generate a themed release announcement for existing users from one or more refs (tags, ranges, RM IDs). Produces canonical artifacts (landing HTML, plain notes, theme snapshot) and paste-ready channel messages (email, Slack, Discord, in-app banner, status page, X, WhatsApp, slide deck). Preset or on- demand custom themes.

Map a repository at a higher level in its domain vocabulary. Two modes: simplified is a one-shot ~30-line textual orientation; complete (default) does an exhaustive pass and renders a self-contained themed HTML deck (overview, business insights, architecture, API/data contracts). --save (on) writes docs/system-map/; --output markdown|html. Manual invocation only. Ships in starter.

Create new Octopus skills with the correct structure — frontmatter (name + description), SKILL.md <= 250 lines, optional REFERENCE.md/EXAMPLES.md/scripts/ at one level — and register the skill into a target bundle so none ships loose. Complements compress-skill.

Run the four quality-audit skills in parallel against one ref — audit-security, audit-money, audit-tenant, audit-contracts. Shared file discovery + parallel execution + consolidated report with a cross-audit hotspots table.

Pre-merge audit of the Octopus configuration surface (rules/, skills/, hooks/, commands/, bundles/): model-specific assumptions, stale dates, skills with no triggers, hooks untouched since the last model-family change, commands referencing deprecated paths. Severity-tiered report (block/warn/info) like audit-all. Quality bundle.

Detect API-vs-frontend contract drift in multi-stack monorepos (.NET/Node API + React/Vue/Astro). Given a branch/PR, flags endpoint additions without consumers, removals/renames that break callers, DTO/enum drift, status-code changes, auth-rule changes, and param changes. Severity-tiered report with confidence labels.

Cross-repo adoption + drift audit. Given a fleet (from the workspace fleet.yml), reports each repo's Octopus surface against its declared target — baseline + stack profile + adoption tier — plus version and CONTEXT.md/ADR adoption. Signal-only: per-repo table + drift-hotspots rollup, feeds fleet- bootstrap --from-audit. Quality/tech-lead bundle.

Signal-only review confronting the working diff against the repo's source of truth — CONTEXT.md (domain glossary), docs/adr/, and the knowledge base — to surface semantic hallucination: conventions invented without agreement (invented-convention) and domain facts asserted without support (unsupported-domain-fact). Never blocks. Triggered at task end by the grounding-check stop hook; quality bundle.

Pre-merge audit of money-touching code (branch/PR): numeric types, rounding, tests for non-round cents, env-var consistency, payment idempotency, webhook signature verification, and fee-disclosure coupling. Severity-tiered report (block/warn/info).

Security audit checklist for AI agent configurations, environment variables, and project dependencies

Signal-only review flagging code that violates the team's design rules (exceptions gate, patterns, coding-style, active stack rules) and over- engineering (premature abstraction, speculative hierarchy, DRY-before-three) — what a formatter or type-checker can't see. Never blocks; runs on demand via codereview/pr-review/implement. The house-rules complement to native simplify.

Pre-merge audit of multi-tenant data-scope enforcement (branch/PR): queries bypassing tenant filters, DbContexts missing HasQueryFilter on new entities, raw SQL without tenant restriction, route ids used without ownership checks, joins to unfiltered tables, cross-tenant admin endpoints. Severity-tiered report with confidence labels.

Signal-only audit confronting a finished task against its run evidence: a completion claimed without build/test/typecheck running (unverified- completion-claim), and a diff referencing a file the build would reject (unresolved-reference). Never blocks; runs on demand via /octopus:review- proposals on the cheapest tier. Queued by the zero-LLM verification-check Stop hook.

Scaffold the private manager-workspace (consigliere knowledge base) at a configured path: directory contract (sources/contexts/projects/people), per- node state/journal/playbook, schemas, README, recorded in consigliere.workspace. Establishes the write-guard — writes stay inside the private workspace, never a code repo. Foundation for digest-source/context- status/playbook-review. Manual; consigliere bundle.

One-time OAuth 2.1 setup connecting the Atlassian Rovo MCP server to Claude Code so digest-source can read Jira and Confluence (read-only). Registers the endpoint at user scope, writes a read-only allow/deny block to .claude/settings.json, drives browser consent via /mcp, verifies. Edits Claude config, never the workspace. Manual; optional consigliere connector.

Make the generic knowledge engines (hygiene/synthesize/briefing) read like the consigliere over the private workspace — political risk surfaced, per- node playbook heuristics applied, the 'thinks like you' voice. A wrapper: engines stay generic, the octopus lens helper surfaces grounded material, the consigliere role (opus) frames it. Read-only.

Generate brand-consistent images for blog covers, Instagram posts, and carousels via AI (Gemini Imagen, Pollinations.ai fallback). Reads brand context from .octopus/content-images.json and GEMINI_API_KEY from .env.octopus. Caches by output path; --force overrides.

Audit and optimize AI agent context window usage to reduce token overhead and improve response quality

Compact the current conversation into a handoff document another agent can pick up — with a suggested-skills section, saved to the OS tmp dir (not the workspace), referencing existing PRDs/plans/ADRs/issues/commits by path rather than duplicating, with mandatory redaction of secrets and PII.

Read side of the consigliere workspace: answer a manager's natural-language question ('how's payments?', 'what's blocked on checkout-revamp?', 'who owns X?') from the materialized state — grounded, read-only, with source citations and the consigliere lens. Says 'not recorded' rather than inventing; never writes. Manual; consigliere bundle.

Consigliere capture: turn pasted text, a local PDF/file, a Jira issue, or a Confluence page (plus a one-line description) into grounded, routed memory — immutable snapshot, confirmed route to a context/project, a 6-field extraction (status, blockers, decisions, system map, actions, political risk) with source citations, then journal + state writes. Manual; consigliere bundle.

Stress-test a plan against the project's CONTEXT.md glossary and docs/adr/ decisions by grilling the user one question at a time, surfacing contradictions between user claims and the actual code, and updating CONTEXT.md/ADRs lazily as terms resolve.

Synthesise the current conversation into a PRD and publish it to the issue tracker without re-interviewing — knowledge is assumed in context from a prior brainstorm or doc-align. Forbids file paths and code in the body (except prototype snippets that encode a decision). Skips to ready-for- agent.

Create a scoped CLAUDE.md at a monorepo subdirectory, capturing only that area's conventions without duplicating the parent. Reads the parent first, asks only about local conventions, writes lean (50–100 lines), cross- references 'inherits from ../CLAUDE.md' instead of copying. Pairs with compress-skill and doc-lifecycle. Family doc-*.

Write a baseline .editorconfig and (opt-in) .vscode/ settings + extensions aligned with the project's formatter and linter — the editor layer between keystroke and commit. Detects stack via file extensions; merges keys conservatively, never overwrites a user value. Pairs with enforce-precommit and the guardrails bundle.

Install and maintain a pre-commit framework config (.pre-commit-config.yaml by default, or lefthook/husky) aligned with the project's Octopus rules — the git-level enforcement loop hooks can't cover for Copilot or direct human commits. Detects the stack, infers checks from rules/common, merges idempotently by hook id. Guardrails bundle.

Converge a fleet of repos onto a layered Octopus standard (baseline + per- stack profile + adoption tier) by composing each repo's .octopus.yml from one fleet.yml and running octopus setup in each. Multi-stack and legacy first-class; tiers T0/T1/T2 phase adoption. Dry-run by default, non- destructive per-key merge, never force-pushes. Pairs with audit-fleet. Manual; quality/tech-lead bundle.

Frontend architecture decision patterns for component-based UIs (React, Next.js, Vue) — component composition, state vs. server cache, data fetching, styling conventions, and accessibility as first-class.

The Octopus implementation workflow — TDD, plan-before-code, verification-before-completion, simplify pass, commit cadence. Active by default on every code task; pairs with rules/common/* (static rules) and doc-lifecycle (docs).

Interactive requirements interview — one question at a time down the decision tree of a new feature/problem until shared understanding. No dependency on CONTEXT.md/docs. Produces a confirmed summary ready for doc- align, doc-prd, or implement. Greenfield counterpart to doc-align; pairs with doc-research (area-level vs one feature).

Ramp a new engineer onto a repo's standards, architecture, and way of working — a guided, scoped sequence composing what exists (CONTEXT.md, ADRs, rules/, the map-system deck, the Definition of Done, bundle config) rather than a new content store. Scopes to the engineer's area/stack; leads with the manager's optional seed (docs/onboarding/guide.md). Resumable checklist gitignored under .octopus/onboarding/. Self-serve via /octopus:onboarding.

Scan the repo's planning directories and roadmap for hygiene issues — orphan plans, plans for completed RMs outside archive/, duplicates for one RM, broken internal links, roadmap entries without a plan, and stale plans. Read-only by default; --fix applies reversible moves to plans/archive/.