Skip to content

Prompt, Skill, and CLI Model

Why this composition

The workflow has enough repeated structure to justify skills and a CLI, but not enough stable branching to justify a YAML workflow engine. Keeping orchestration inside an interactive Codex task makes product judgment visible and lets the user redirect work without maintaining a second execution runtime.

Layer Owns Does not own
Workflow prompt Task intent, required inputs, expected artifacts, constraints API calls, shell details, persistent process state
Skill Reusable procedure, context selection, approval points, validation choices Arbitrary external mutations or hidden state
Anuva CLI Typed validation, named side effects, stable outputs, process control Product reasoning, code generation, open-ended command execution
AGENTS.md Durable repository rules and required verification One-off change details

Shared skill source and distribution are separate concerns. Product Main owns the source, and plugin version 0.2.0 contains twelve shared skills and three distributable references. Repository AGENTS.md files own repository-specific verification. Phase 5 removes checked-in shared copies after fresh-process plugin acceptance; repository-local domain skills remain checked in.

Prompt policy

The files in this handbook are versioned workflow prompt specifications. They can be copied into a task for debugging or embedded as skill references, but the normal interface is explicit skill invocation. They are not Codex “custom prompts”; custom prompts are deprecated in favor of skills.

Use a manual prompt when:

  • the task is exceptional or exploratory;
  • Unity work needs highly contextual interactive direction; or
  • a skill needs debugging and the exact expanded instructions must be visible.

Use a skill when the same inputs, output artifacts, and approval boundaries recur. Use a CLI operation when execution must be deterministic, validated, repeatable, and easy to audit.

$anuva-development:anuva-repository-change may be selected implicitly from an ordinary request. It returns Routine, Material, or Product Main required. A routine request authorizes scoped implementation, commit, push, and draft PR delivery but not merge. Material work requires a separate exact-plan approval and later merge approval. Product Main routing creates nothing.

Standalone Linear tracking is optional and begins only when the user explicitly requests it. The existing typed anuva repository-change commands remain that tracked path; issue-free Git/GitHub delivery uses scoped repository and connected GitHub operations. The CLI remains mandatory for implemented Linear, documentation-process, environment, and fixed machine mutations.

Data flow

All CLI read commands support --json. Skills should consume JSON and present a concise human summary. State-changing commands accept structured file inputs when the payload is larger than a few scalar arguments.

Request or Linear JSON -> Codex reasoning -> Markdown/manifest -> named mutation -> receipt or GitHub record

Never parse decorative terminal tables in a skill. Never pass untrusted Linear text into a shell expression. Never expose anuva exec, anuva shell, or a YAML step runner.

Reference: OpenAI Codex skills.