Skip to content

Codex Skills

Anuva skills hold reusable workflow judgment and approval gates. Prompts express task intent; the Anuva CLI performs typed allowlisted side effects; GitHub owns branches, pull requests, reviews, checks, and merges.

The Anuva Development Process Policy makes the Product Main-owned anuva-development plugin the shared distribution mechanism. Phase 4 source version 0.2.0 contains twelve skills and three references. Machine one runs installed plugin version 0.2.0 after verified upgrade, source-backed rollback, inverse rollback, and five-repository fresh-process acceptance.

Phase 5 verified fresh-process discovery and routing in every active repository, then removed the checked-in shared workflow copies. Repository-local domain skills remain repository-owned.

Source and validation

plugins/anuva-development/
  .codex-plugin/plugin.json
  references/
    DevelopmentProcessPolicy.md
    RepositoryVerificationMatrix.md
    ToolchainPolicy.md
  skills/<skill-name>/
    SKILL.md
    agents/openai.yaml

The repository marketplace remains .agents/plugins/marketplace.json.

Validate source, marketplace, installed caches, frontmatter, and UI metadata with:

anuva skills validate --json
anuva skills cachebuster --label <label> --dry-run
anuva skills cachebuster --label <label> --confirm

Validation uses the packaged JavaScript yaml and zod dependencies. It does not invoke Python, create .validator-deps, or install a temporary dependency. Cachebuster changes only the fixed plugin manifest version under a lock.

Phase 4 plugin catalog

Fresh tasks expose installed skills with the plugin-qualified identity $anuva-development:<skill-name>.

Need Skill Linear
Validate Product Main intake linear-plan-change Existing Product Main parent
Plan or deliver a Product Main phase anuva-plan-product-change Parent and approved children
Complete a Product Main change anuva-review-product-change Parent Done after accepted children
List ready implementation children linear-list-ready-issues Read-only
Validate an exact tracked issue linear-implement-issue Child or explicitly tracked standalone
Implement a validated tracked issue anuva-implement-issue Supplied issue only
Review and complete tracked delivery anuva-review-and-complete-pr Supplied issue only
Classify and deliver repository-local work anuva-repository-change None by default
Deliver a process-only change anuva-development-process-change None; explicit-only
Preview and strictly verify docs anuva-preview-docs None
Inspect or operate the environment anuva-manage-development-environment None; explicit-only
Inspect or apply fixed toolchain policy anuva-manage-toolchain None; explicit-only

The Phase 1 anuva-development-readiness skill is absent from 0.2.0 source. Merged main retains its complete 0.1.0 source as the durable rollback target. The Codex plugin page manages one active cache and recreated 0.1.0 from that source during Gate 2 before restoring 0.2.0.

Work classification

anuva-repository-change may be selected implicitly. Before mutation it reads the active AGENTS.md, ownership boundaries, likely paths, Product Main contracts, and affected verification requirements, then returns:

  • Routine: issue-free. The request authorizes bounded implementation, checks, docs verification, commit, push, and draft PR; merge remains a separate gate.
  • Material: issue-free by default. Produce an exact proportionate plan and stop; later plan and merge approvals remain distinct.
  • Product Main required: create nothing and return an exact Product Main intake proposal.

Product behavior, shared application contracts, multi-implementation-repository work, migrations, authentication or authorization, privacy, security, billing, deployment architecture, release coordination, and uncertain ownership always use Product Main.

Create a standalone Linear issue only when the user explicitly requests durable tracking. That optional path continues through the typed anuva repository-change, linear-implement-issue, anuva-implement-issue, and anuva-review-and-complete-pr contracts.

Approval policy

The current bounded task request authorizes reversible, in-scope work described by the selected workflow. It does not authorize merge.

  • Routine: implementation request, then merge approval.
  • Material repository work: exact-plan approval, then merge approval.
  • Product change: product-plan approval and final product completion approval.
  • Development-process change: material process-plan approval and final complete-PR-set approval.
  • Machine/environment work: read-only diagnosis by default; exact approval for install, upgrade, removal, secrets, tunnel administration, or destructive stop.

A CLI --confirm flag selects an already authorized execution form. It does not replace a workflow approval.

Product and tracked-issue skills

Product skills retain the Linear Product Main hierarchy. Planning creates repository children only after its planning PR merges. Completion reads every terminal child and acceptance record before moving the parent Done.

Tracked-issue skills retain the exact issue boundary and implementation-plan pause. A child or explicitly tracked standalone issue may use durable ImplementationPlan, ImplementationLog, and CompletionReport artifacts. Do not require those three artifacts for every routine issue-free fix.

Development-process, environment, and toolchain skills

anuva-development-process-change is explicit-only in Product Main. It may write only approved process surfaces, creates no Linear issue, and uses one material-plan gate plus one reviewed merge-set gate. Phase 5 is its first cross-repository migration use.

anuva-manage-development-environment uses named health, service, docs, and tunnel operations. It never becomes a generic process-kill or Cloudflare administration workflow.

anuva-manage-toolchain uses only:

anuva toolchain doctor --json
anuva toolchain snapshot --json
anuva toolchain bootstrap --dry-run
anuva toolchain bootstrap --confirm

Doctor, snapshot, and dry-run are read-only. A nonempty confirmed action set requires exact approval. Arbitrary tools, packages, URLs, commands, and paths are rejected.

Documentation skill

anuva-preview-docs uses the Phase 3 contract:

  1. start or health-check an owned preview before editing;
  2. rely on live reload without a timestamp or content-driven restart;
  3. run one strict docs verify for the complete logical update; and
  4. return every exact HTTPS review URL.

It never adopts or terminates an external listener and never publishes canonical docs automatically.

Repository-specific behavior

Every shared skill reads the active repository's AGENTS.md. Repository instructions own product boundaries and affected checks. Shared skills run only relevant checks, explain skipped expensive checks, and stop on conflict.

CMS Mastra and text-to-speech guidance, plus framework, vendor, asset, protocol, and product-specific skills, remain repository-owned. They must coexist with the plugin.

GitHub authentication

Before the first GitHub-backed delivery operation, run direct read-only gh auth status in the known keyring-capable approved context. Continue GitHub-backed Anuva or gh operations there when it succeeds. Ask for authentication only when that check fails; do not deliberately trigger a sandbox failure first.

Repository migration

Phase 5 updates each repository's AGENTS.md, process docs, bootstrap docs, and active references; keeps repository-specific verification in repository-owned guidance; verifies plugin routing in fresh processes; and removes checked-in shared copies. Explicit-only skills load through the literal qualified $ selector. Historical change records remain unchanged.