nexus-agents

Operating manual for documentation work in nexus-agents. Use when updating docs, adding new docs, changing doc pipeline, or troubleshooting doc issues. Triggers on "update docs", "add documentation", "doc pipeline".

Periodically exercise ALL nexus-agents feature families end-to-end against a real task — research → synthesize → vote → plan → dev-pipeline → graph workflow → memory → audit — capturing ACTUAL outputs to validate that fixes, docs, and claims hold in real usage (the things unit tests miss: live voter panels, adapter routing, pipeline stage wiring, audit chains). Use after a release, weekly, when several fixes have landed since the last run, or on demand. Triggers on "e2e validation", "end-to-end validation", "dogfood the loops", "validate end to end", "real usage test", "periodic validation run", "full-loop validation".

Run the CI gates locally before pushing, so failures surface in seconds instead of one CI cycle at a time. Enumerates the checks in .github/workflows/, runs the locally-runnable subset in CI's order, and pins the local-vs-CI delta as a memory the first time you work in a repo. Use before `git push` / opening a PR, or when CI just failed on something your local gate missed. Triggers on "pre-push", "before push", "ci parity", "will ci pass", "local gate", "prepush", "pre-push check".

Review code changes following project standards and security guidelines. Checks for lint compliance, type safety, test coverage, and security issues. Use when reviewing PRs, auditing code, checking implementation quality, or running a blind pre-merge review pass before merging your own change. Triggers on "review code", "code review", "check this", "audit", "PR review", "pre-merge review", "blind reviewer", "before merge".

Execute a release following project standards. Use when publishing a new version, creating release tags, or deploying. Triggers on "release", "publish", "version bump", "create release".

Improve an existing technical doc in-place via a phased Audit → Research → Rewrite → Validate workflow. Calls docs-review for audit and validate; never re-derives scoring. Applies answer-first H2s, citation capsules, and info-gain markers per .rules/docs-rubric.md. Use when the user says "rewrite docs", "improve this doc", "optimize doc", "docs rewrite".

Score a technical doc (RFC, ADR, README, CLAUDE.md, blog-style post) against the 5-category 100-point rubric in .rules/docs-rubric.md. Read-only audit. Surfaces top issues by severity. Defers to existing user-level skills (blog-llm-tells, blog-factcheck, blog-overlap, blog-argument-shape, blog-pre-publish) for prose-quality dimensions rather than re-deriving them. Use when the user says "review docs", "audit docs", "score this doc", "doc quality", "docs review".

Generate AI illustrations (hero, cover, conceptual, infographic) for nexus-agents docs via the nanobanana-mcp gateway. Use when the user needs a hero image, README cover, or conceptual illustration. NOT for precise architecture diagrams — those redirect to docs-mermaid. NOT for quantitative charts — those redirect to docs-chart. Triggers on "generate image", "blog image", "hero image", "cover image", "illustration".

Generate dark-mode-compatible inline SVG charts (bar, donut, line, lollipop, area, radar) for nexus-agents docs from quantitative data — OutcomeStore metrics, fitness scores, CLI success rates, vote pass-rates, weather report data. Use when the user says "chart", "visualize data", "svg chart", "render chart", or asks to compare CLI metrics. Cross- references docs-mermaid (precise diagrams) and docs-image (illustrative).

Generate precise diagrams (flowchart, sequence, state, ER, class, gantt, gitGraph) using Mermaid for nexus-agents docs. Use when the user wants to "diagram this", "show how X works", "draw the flow", or asks for a flowchart / sequence / state diagram. Cross-references docs-chart (for quantitative data viz) and docs-image (for illustrative AI-gen) so each visual lane has a clear winner.

Generate design systems and implement UX/UI for software products using Astro, Svelte, Tailwind CSS, Material Design 3, and OKLCH color system. Covers style selection, color palettes, typography, layout patterns, accessibility, and frontend code generation. Triggers on "design system", "UI design", "color palette", "typography", "landing page design", "dashboard design", "style guide", "component design", "frontend".

Multi-agent development pipeline (Orchestrator + workers + consensus vote). Use when the user asks to "build a feature", "fix a bug with the pipeline", or "run the dev pipeline". Triggers on "dev pipeline", "multi-agent pipeline", "run pipeline".

Score your own output 0-10 across 5 task-appropriate dimensions before emitting it. Anything below band 3 (5-6 Functional) is a regression — fix and rescore. Use as a pre-emit gate when work is complex enough that grade-inflation is a real risk. Triggers on "self-critique", "score my output", "pre-emit review", "grade my work", "five-dimension critique".

Fix a bug following project standards. Use when fixing defects, debugging issues, or resolving reported problems. Triggers on "fix bug", "debug", "fix issue", "resolve bug".

Delegate code generation tasks to Codex CLI for optimal performance. Use when implementing features, generating tests, refactoring code, or making bulk code changes. Triggers on "delegate to codex", "route to codex", "use codex", "code generation".

Process open GitHub issues using the self-development protocol. Implements features from research registry with proper voting and testing. Use when working on open issues, implementing research techniques, or following the dogfooding workflow. Triggers on "dogfood", "work on issues", "implement issue", "self-development", "process issues".

Delegate large context and multimodal tasks to Gemini CLI. Use when context exceeds 100K tokens, analyzing images/screenshots, processing large codebases, or for speed/cost-sensitive operations. Triggers on "delegate to gemini", "route to gemini", "use gemini", "large context", "analyze image", "screenshot analysis".

Apply a hotfix for critical production issues. Use for security vulnerabilities or bugs that prevent core functionality. Triggers on "hotfix", "emergency fix", "critical fix", "production bug".

Implement a new feature following project standards. Use when adding functionality, creating new modules, or extending capabilities. Triggers on "implement", "add feature", "create", "build".

Manage physical server infrastructure, bare metal systems, and OOB management. Handles iDRAC/iLO/IPMI access, SSH connectivity checks, boot time estimation, and hardware health monitoring. Triggers on "infrastructure", "bare metal", "server management", "idrac", "hardware check".

Extract structured requirements from vague user requests. Decompose ideas into user stories with acceptance criteria, map to available capabilities, and identify gaps. Triggers on "requirements", "user stories", "what do I need", "break down this request", "analyze this feature".

Research a topic using multiple sources and conduct multi-agent voting. Use when making architectural decisions, choosing dependencies, or designing APIs. Triggers on "research", "decide", "vote on", "consensus".

Respond to a reporter-filed GitHub Security Advisory with coordinated disclosure discipline: confidential triage, private-fork patching, simultaneous publish, post-mortem. Use when someone files a security advisory against this repo, OR when our own discovery (via .security-discoveries.jsonl) is escalated to a reporter-facing advisory. Triggers on "security advisory", "CVE response", "coordinated disclosure", "private fork patch".

Review and fix security scanning alerts from CodeQL and secret scanning. Run as part of system reviews, after CI runs, or on manual request. Triggers on "security scan", "codeql", "secret scanning", "security alerts".

Run a system review to check project health. Use when issues drop below 5, an EPIC closes, or 7+ days since last review. Triggers on "system review", "project health", "review system".

Check that dependencies are current stable versions and not deprecated. Use before adding new dependencies or at project setup. Triggers on "check versions", "verify dependencies", "audit packages".

Design stable, hard-to-misuse interfaces — REST endpoints, MCP tool schemas, module boundaries, type contracts. Apply when defining new surfaces or evolving public ones. Triggers on "API design", "interface", "schema", "contract", "module boundary", "type design".

Test UI in real browsers via Chrome DevTools MCP. Apply when debugging rendering issues, console errors, network behavior, performance, or accessibility — anywhere static code analysis can't see runtime state. Triggers on "browser test", "DOM inspect", "console errors", "network trace", "core web vitals in browser", "ui bug repro".

Measure-first optimization for code that has actual evidence of being slow. Apply when performance requirements exist, profiles show bottlenecks, or a change introduced a regression. Triggers on "optimize", "performance", "slow", "profile", "bottleneck", "core web vitals", "regression".

Write failing tests before implementation. The Red-Green-Refactor cycle is a core nexus-agents discipline (CLAUDE.md prime directive). Use when implementing new logic, fixing bugs (Prove-It Pattern), or modifying existing behavior. Triggers on "TDD", "write a test", "test-first", "red-green-refactor", "fixing a bug" (Prove-It).

Curate what the agent sees, when, and how it's structured. Apply when starting a session, when output quality drifts, when fanning out subagents, or when configuring rules files. Triggers on "context engineering", "rules file", "agent context", "subagent fan-out", "context budget".

Reduce nesting, extract names, eliminate redundancy without changing behavior. Apply after features work and tests pass — never as a drive-by during feature work. Triggers on "simplify", "refactor for clarity", "this is hard to read", "code review flagged complexity".

Plan and execute the removal of deprecated APIs without breaking consumers. Apply when retiring `@deprecated` markers, renaming public surfaces, or version-gating cleanup work. Triggers on "deprecate", "remove deprecated", "migration plan", "breaking change", "v3 cleanup".