Skip to content

Codex Development Process

Anuva uses Codex as an interactive engineering teammate. The process aims for high autonomy inside a clearly approved task, with durable state outside chat and deterministic side effects behind a narrow CLI.

Operating model

flowchart LR
    Developer["Developer\nCodex App task"]
    Prompt["Workflow prompt\nintent + outcome"]
    Skill["Codex skill\nprocedure + judgment"]
    CLI["Anuva CLI\nallowlisted executor"]
    Linear["Linear"]
    Git["Git + GitHub"]
    Docs["Repository docs"]
    Preview["MkDocs + Tunnel"]

    Developer --> Prompt --> Skill --> CLI
    Skill --> Docs
    CLI --> Linear
    CLI --> Git
    CLI --> Preview

The three layers are complementary:

  • A prompt describes the particular job and expected outcome.
  • A skill supplies reusable Anuva-specific workflow and decides which named CLI operations are appropriate.
  • The CLI validates inputs, executes deterministic operations, and returns stable human and JSON output.

The CLI does not decide product behavior, generate implementation, or schedule work. Codex retains reasoning responsibility inside the interactive task.

End-to-end lifecycle

Phase Codex App location Primary skill Durable result
Change intake Product Main $anuva-development:linear-plan-change ANU-100 Normalized change inputs from Linear
Product planning Product Main $anuva-development:anuva-plan-product-change Change brief and repository impact
Approval and handoff Product Main Same skill after approval Repository-scoped Linear issues
Work discovery Implementation repo $anuva-development:linear-list-ready-issues Read-only list of ready issues
Routine repository change Current configured Anuva repo $anuva-development:anuva-repository-change Issue-free branch and draft PR
Material repository change Current configured Anuva repo Same skill Approved proportionate plan, issue-free branch, draft PR
Optional tracked repository change Owning repository $anuva-development:linear-implement-issue ANU-201 Explicit standalone issue or Product Main child
Development-process change Product Main $anuva-development:anuva-development-process-change Process-only plan and draft PR set, no Linear
Implementation Owning repository $anuva-development:linear-implement-issue ANU-201 Approved plan, code/tests/docs, draft PR
PR completion Owning repository $anuva-development:anuva-review-and-complete-pr ANU-201 Ordered merge, cleanup, report, Linear Done
Product completion Product Main $anuva-development:anuva-review-product-change ANU-100 Completion review, release docs, parent issue Done

Repository-local workflow

The repository-change skill may be selected implicitly, but begins with a read-only ownership and Product Main contract preflight. Routine is issue-free; Material is issue-free by default and pauses for exact-plan approval; Product Main required returns an exact intake and creates nothing. Create a marked standalone issue only when the user explicitly chooses durable Linear tracking.

Product decisions, development-process redesign, shared contracts, schema/data migrations, authentication/authorization, privacy, security, billing, deployment architecture, release coordination, multiple implementation repositories, or unclear ownership always escalate. When the user explicitly chooses standalone Linear tracking, its legacy bounded Required documentation disposition may create one Product Main documentation companion after implementation; it cannot change code, decisions, or shared contracts.

Approval boundaries

Codex may perform read-only inspection and create/revise Markdown within the active task. It must stop and ask before these mutations:

  • creating repository implementation issues from an approved product plan;
  • creating optional standalone Linear tracking;
  • moving a Linear issue into In Progress when starting work;
  • beginning material implementation before approving its exact plan;
  • creating or publishing a PR when the user has asked to review the plan first;
  • merging a PR;
  • marking an implementation or parent change issue Done;
  • stopping services or publishing canonical docs.

At every pause, provide the proposed mutation, current verification status, and exact live documentation URLs. A command's --confirm flag records that the interactive approval boundary was crossed; it is not a substitute for approval. Skill selection is routing. A routine change request authorizes its scoped implementation and draft delivery; it never authorizes merge. Material work retains distinct plan and merge approvals.

State model

Anuva uses six Linear states: Backlog, Ready, In Progress, In Review, Done, and Canceled. Blocking is an issue relation, and approval is recorded in the durable plan rather than represented as another state. The CLI resolves the configured names to Linear IDs and refuses unsupported transitions.

See Linear Configuration and Workflow for issue hierarchy, status transitions, templates, priorities, labels, views, GitHub integration, and canonical documentation-link policy.

Durable documentation

Product Main change folders explain product intent and cross-repository impact. Implementation change folders explain how one repository delivered its issue. All changes to docs/**/*.md are immediately reviewable through the repository's machine-specific Cloudflare Access-gated MkDocs site. Canonical aggregation is manual and intentionally outside normal change workflows.

Command policy and machine parity

Product Main owns the reviewed reusable command policy at config/codex/default.rules. It allows only the guarded Anuva CLI, direct read-only GitHub inspection, one justified remote-head read, and named repository checks. Direct Git/GitHub mutations and shell wrappers remain interactive; destructive reset, clean, and repository-delete forms are forbidden. Arbitrary runtimes, patch helpers, file operations, and temporary exact commands deliberately receive no reusable rule.

Use bun run check:rules before proposing installation. An active-rule replacement, rollback, or inverse rollback is a separately approved machine transaction and requires a Codex restart.

Use the Windows Development Machine Bootstrap to reproduce the fixed repositories, CLI, plugin, toolchain, Codex policy, preview topology, and non-secret snapshot. Copying caches, working trees, raw Codex configuration, or credentials between machines is not bootstrap.

Deliberate exclusions

The current process does not include no-human-code constraints, Symphony, Codex Goals, YAML workflow execution, autonomous browser testing, automatic canonical docs publishing, Early Users deployment automation, or Production infrastructure automation. These may be reconsidered only after the interactive harness is proven.