Anuva Development Policy Implementation Plan

Purpose

This plan defines how to replace Anuva's current uniformly strict, Linear-backed development workflow with a risk-proportionate solo-developer workflow centered on Codex App, an installable Anuva development plugin, the guarded Anuva CLI, GitHub delivery, and durable repository documentation.

The implementation must preserve strong controls for product decisions, cross-repository application contracts, destructive actions, security-sensitive work, and production-affecting changes. It must remove repeated approval prompts, temporary dependency installations, duplicated shared skills, and release-grade documentation verification from routine local development.

This document is an implementation input for a separate Codex task. It does not itself authorize plugin creation, CLI changes, repository mutations, tool installation, rule changes, pull requests, merges, or Linear changes.

Phase 0 bootstrap authorization record

On 2026-07-29, the user explicitly authorized the one-time Product Main bootstrap exception by requesting Phase 1 implementation from this plan.

Branch: codex/development-policy-phase-1
Lane: Product Main development-process change
Linear: no issue or mutation
Product runtime: no change
Implementation repositories: read-only and no product-code mutation
Compatibility: retain all checked-in shared skills
Authorized scope: durable policy, Phase 1 documentation reconciliation, skills-only plugin scaffold, repository marketplace, read-only discovery skill, local plugin installation/upgrade/rollback verification, and Phase 1 tests
Explicitly deferred: CLI packaging or behavior, Codex rules, MkDocs behavior, toolchain management, cross-repository migration, shared-skill removal, GitHub delivery, and merge

The intended repository paths are:

docs/development/DevelopmentProcessPolicy.md
docs/development/AnuvaDevelopmentPolicyImplementationPlan.md
docs/development/index.md
docs/development/SourceOfTruth.md
docs/development/DevelopmentEnvironment.md
docs/development/DocumentationLifecycle.md
docs/engineering/Skills.md
docs/engineering/AnuvaCli.md
docs/engineering/PromptSkillCliModel.md
mkdocs.yml
.agents/plugins/marketplace.json
plugins/anuva-development/**
tests/unit/plugin-distribution.test.ts

Any additional path or broader phase requires a new scope decision before mutation. Later cross-repository rollout must use the approved development-process workflow and its merge gate.

Phase 1 implementation and verification record

Phase 1 was implemented on the recorded branch with final plugin source version 0.1.0.

Durable result

DevelopmentProcessPolicy.md is policy version 0.1 and explicitly keeps current skills, CLI behavior, repository instructions, and strict docs verification in force during transition.
The repository marketplace is named anuva and publishes anuva-development from ./plugins/anuva-development.
The marketplace uses INSTALLED_BY_DEFAULT because the current Codex CLI can register marketplaces but has no plugin add command.
The plugin contains only skills; it declares no app, MCP server, hook, or custom UI.
The installed read-only skill identity is $anuva-development:anuva-development-readiness.
All checked-in .agents/skills/anuva compatibility copies remain present.

Exact local installation result

The local marketplace was registered from the Product Main repository root:

codex -c 'service_tier="fast"' plugin marketplace add C:\Anuva\dev\anuva-main-video-creator

The service_tier override is required only because this machine's Codex CLI 0.130.0 rejects the app's newer default value. The Codex plugin page was then used to enable anuva-development@anuva.

A fresh read-only task discovered:

anuva-development:anuva-development-readiness
C:\Users\Girish\.codex\plugins\cache\anuva\anuva-development\0.1.0\

The task invoked the skill and verified Product Main AGENTS.md, policy version 0.1, rollout status Phase 1 foundation, and all eight checked-in compatibility skills without mutation.

Upgrade and rollback result

Upgrade used cachebuster version 0.1.0+codex.phase1-upgrade-20260729-1317. A local marketplace does not support codex plugin marketplace upgrade, and the current app did not show an Update control. Refreshing only the anuva marketplace registration caused the next task to load:

C:\Users\Girish\.codex\plugins\cache\anuva\anuva-development\
0.1.0+codex.phase1-upgrade-20260729-1317\

Restoring the source manifest to 0.1.0 and refreshing registration did not downgrade the installed cache. The verified rollback sequence is therefore:

restore the previously validated source version;
remove only the installed anuva-development@anuva plugin;
reinstall it from the still-registered local anuva marketplace; and
inspect a fresh task's skill source locator.

The final fresh task returned to the 0.1.0 cache path. Marketplace source, repository files, and checked-in compatibility skills remained intact.

Validation result

bun run check: 78 tests passed, 0 failed, including four new plugin distribution tests.
anuva docs validate-indexes --repository current: valid.
Strict anuva docs wait verification: all changed pages returned HTTP 200 and matched a fresh strict build.
git diff --check: no whitespace errors.

The plugin-creator and skill-creator Python validators were attempted but their runtime lacks PyYAML. The documented scripts/update_plugin_cachebuster.py helper is also absent from the installed plugin-creator skill. No temporary dependency was installed. The Bun test uses the repository's pinned yaml dependency to validate the plugin manifest, marketplace entry, skill frontmatter, UI metadata, read-only contract, and compatibility-skill retention. Packaging validator dependencies and restoring the cachebuster helper remain Phase 2 toolchain work.

Phase 1's Product Main exit criterion is satisfied on this machine. This is not evidence for cross-repository discovery or permission to begin later phases.

Desired outcome

When this plan is complete:

Codex App is the normal starting point for Anuva development.
C:\Anuva\dev is the shared Anuva read boundary on every development machine.
Ordinary writes remain scoped to the active repository.
Product Main can perform narrowly allowlisted cross-repository development-process updates without changing product implementation.
Product and cross-repository application work continues to use Linear.
Routine repository maintenance, development-process changes, documentation corrections, and machine setup do not require Linear merely because files change.
Shared Anuva workflow skills are distributed through an installable Anuva development plugin owned by Product Main.
Repository-specific framework and product skills remain repository-owned.
The Anuva CLI is a packaged, versioned executable rather than a launcher for Product Main working-tree TypeScript.
Shared development tools are installed once per machine from a fixed, Product Main-owned toolchain manifest.
MkDocs and Cloudflare Tunnel previews remain pleasant, remotely accessible views of intermediate working-tree documentation without imposing a strict rebuild after every edit.
Approval gates correspond to material risk and user intent rather than every CLI --confirm flag or reversible local action.

Guiding principles

Optimize for a solo developer

The process must provide recovery, traceability, and clear decision boundaries without reproducing team ceremony that adds no value for one developer.

Automation should perform reversible, local, well-scoped actions by default. The workflow should pause when a decision, irreversible effect, external mutation, or material scope expansion genuinely needs review.

Keep responsibilities separated

Surface	Responsibility
Codex App	Primary development conversation, implementation, review, and explicit decisions
Anuva development plugin	Reusable workflow judgment, routing, risk classification, and repository-aware procedure
Anuva CLI	Typed, deterministic, allowlisted reads and mutations
Linear	Product intent, priority, cross-repository communication, and Product Main implementation handoffs
GitHub	Branches, commits, pull requests, reviews, checks, merges, and immutable delivery history
Repository Markdown	Durable policy, decisions, architecture, operating guidance, plans, and evidence where useful
Machine-specific MkDocs sites	Convenient live previews of working-tree documentation
`anuva.girishd.com`	Manually published canonical aggregate

Apply controls according to risk

The presence of a file change, branch, CLI --confirm flag, or docs preview is not by itself a reason to ask for approval. Risk, external effect, and user intent determine the gate.

Preserve repository ownership

Product Main owns the development process, shared Anuva workflow skills, the Anuva CLI, machine toolchain policy, documentation preview contract, and cross-repository process acceptance.

Implementation repositories continue to own their product code, tests, repository-specific technical documentation, framework guidance, and repository-specific verification requirements.

Work classification

Every requested change must be classified into one of the following lanes before mutation.

Lane	Examples	Linear	Durable plan	Required user gates
Product change	User-visible capability, shared application contract, cross-repository behavior, migration, auth, billing, deployment or release decision	Required Product Main parent and repository children where needed	Product Main change docs and repository plans	Product plan approval and final delivery approval
Material single-repository implementation	Significant repository-owned behavior that does not change a shared contract	Optional standalone Linear issue when prioritization or durable coordination is useful	Proportionate repository plan	Plan approval and merge approval
Routine repository change	Local bug fix, tests, refactor, dependency-neutral maintenance, local technical docs	Not required	Chat/PR description unless complexity warrants a plan	User request authorizes implementation; pause before merge
Development-process change	Shared skill, plugin, CLI workflow, AGENTS policy, development docs, toolchain policy, preview behavior	Not required	Product Main development-process plan or PR description	Material plan approval and final multi-PR merge approval
Machine/environment operation	Toolchain bootstrap, preview servers, tunnel connector, health checks	Not required	Machine-readable receipts and documented manifest	Approval only for installation, upgrade, removal, secret/tunnel administration, or destructive stop

Product decisions, application contracts spanning repositories, migrations, authentication or authorization, privacy, security, billing, deployment architecture, and release coordination must never be hidden inside the development-process or routine-change lanes.

Approval policy

Actions that do not need a separate approval

After the user requests the task, Codex may perform the following without an additional conversational gate:

read any file under C:\Anuva\dev;
inspect Git, GitHub, Linear, local service, and documentation state;
run non-destructive validation and affected-scope tests;
start or health-check an owned MkDocs preview;
return local or Cloudflare preview URLs;
create or update files in the active repository within the requested scope;
create a managed branch for an explicitly requested routine or development-process change;
stage explicitly reviewed paths, commit them, push a managed branch, and create a draft PR when the selected workflow states that these are included in the user's implementation request;
run an Anuva CLI execution form containing --confirm when a preceding user request already authorized that exact class of action.

Actions that require an explicit gate

Codex must pause before:

approving or materially revising a product or high-risk implementation plan;
merging a PR unless the user's current request explicitly says to review and complete or merge it;
deleting non-managed branches or user files;
destructive cleanup whose target is not already a validated managed artifact;
changing Linear product scope, priority, repository ownership, or terminal state outside the approved product workflow;
installing, upgrading, or removing machine-level tools;
changing authentication, authorization, secrets, billing, data, migrations, deployment architecture, Cloudflare routes, Access policies, DNS, certificates, or tunnel tokens;
expanding from one repository's implementation into another repository's product-owned files;
proceeding after review findings, failed required checks, merge conflicts, newly discovered shared contracts, or material scope changes.

Approval reuse

An explicit request such as Implement ANU-123 authorizes the guarded work-start operation for that exact issue. It does not authorize an unreviewed material plan or merge.

An explicit request such as Review and complete ANU-123 authorizes readiness, merge, managed branch cleanup, base synchronization, evidence recording, and the expected Linear completion if the acceptance review passes without a material finding. Codex must stop if the evidence changes the risk or scope.

Workspace and sandbox model

Desired boundary

All Anuva development machines must use:

C:\Anuva\dev
├── anuva-main-video-creator
├── anuva-bento
├── anuvax-cms
├── anuva-python-server
├── anuva-unity-video-creator
└── anuva-dev-docs

Every Anuva Codex task should be able to read this complete tree. Ordinary workspace writes should remain limited to the active repository plus temporary directories.

Product Main development-process workflows may write sibling repositories only through named Anuva CLI operations whose target repositories and path classes are allowlisted. This exception must not grant general cross-repository application-code mutation.

Effective-permission verification

The machine bootstrap must verify the effective Codex permission profile rather than assuming config.toml was honored. It should check:

the active workspace root;
read access to configured Anuva repositories;
the expected additional writable roots;
the native Windows sandbox implementation;
protected .git, .agents, and .codex behavior;
network behavior;
GitHub keyring access inside and outside the sandbox; and
the loaded rule and plugin configuration.

When a repository task cannot read Product Main, the preferred permanent fix is the shared read boundary and packaged CLI. /sandbox-add-read-dir is a session-only recovery tool, not the normal workflow.

Anuva development plugin

Decision

Create a skills-first plugin named anuva-development. Do not create a central process-sync workflow.

The plugin is the canonical distribution mechanism for shared Anuva workflow skills. It may add hooks or an MCP server only when a later requirement cannot be satisfied through skills and the packaged Anuva CLI.

The initial plugin should not include an MCP server or custom UI.

Proposed Product Main layout

plugins/
  anuva-development/
    .codex-plugin/
      plugin.json
    skills/
      linear-plan-change/
        SKILL.md
      anuva-plan-product-change/
        SKILL.md
      anuva-review-product-change/
        SKILL.md
      linear-list-ready-issues/
        SKILL.md
      linear-implement-issue/
        SKILL.md
      anuva-implement-issue/
        SKILL.md
      anuva-review-and-complete-pr/
        SKILL.md
      anuva-repository-change/
        SKILL.md
      anuva-development-process-change/
        SKILL.md
      anuva-preview-docs/
        SKILL.md
      anuva-manage-development-environment/
        SKILL.md
      anuva-manage-toolchain/
        SKILL.md
    references/
      DevelopmentProcessPolicy.md
      RepositoryVerificationMatrix.md
      ToolchainPolicy.md

Use $plugin-creator to scaffold the manifest and a local marketplace entry. The manifest must have a stable kebab-case name, semantic version, description, and skills path.

Add a repository-owned marketplace for development and machine installation. Because repository marketplace metadata may live under the protected .agents/plugins boundary, create or update that small catalog through the explicit plugin-authoring operation rather than broad PowerShell copy scripts.

Skill ownership

The plugin owns shared workflow and development-environment judgment. Repository AGENTS.md files own repository-specific verification and product boundaries.

The following remain repository-local and are not copied into the plugin:

CMS Mastra guidance;
CMS text-to-speech and ElevenLabs guidance;
future repository-specific framework, vendor, asset, protocol, or product skills; and
skills whose behavior is meaningful only inside one implementation repository.

Repository-specific behavior

Remove repository-specific copies of the shared implementation and review skills. Their current CMS, Python, Unity, and Bento additions should become concise affected-scope verification sections in each repository's AGENTS.md or in a repository-owned reference linked by AGENTS.md.

The shared plugin skills must:

read the active repository's AGENTS.md;
apply only checks relevant to changed files and affected contracts;
record why expensive product checks were skipped for process-only or docs-only changes; and
stop when repository instructions and plugin policy conflict.

Installation and upgrade

Each development machine must install the plugin from the Product Main-owned local marketplace. The machine bootstrap documentation must define:

marketplace registration;
plugin installation;
upgrade or cache-busting during local plugin development;
restart or new-task requirements;
version inspection;
representative invocation tests; and
rollback to the previous plugin version.

Plugin installation is machine configuration. It is not repeated for every repository task.

Invocation migration

During the plugin prototype, confirm how installed plugin skills are displayed and explicitly invoked by the current Codex build. Update every AGENTS.md, prompt, and active workflow reference to the actual installed skill identity. Do not assume that the checked-in $anuva-preview-docs spelling remains unchanged if the host exposes a plugin-qualified skill name.

Removal of checked-in copies

Keep the existing .agents/skills/anuva copies only while the plugin is being tested. Remove them from Product Main and implementation repositories after:

the plugin installs successfully on every active development machine;
a new Codex task discovers the expected skills in every repository;
representative product, implementation, review, docs-preview, environment, and toolchain scenarios pass;
repository-specific verification has moved to repository-owned guidance;
rollback installation has been tested; and
active docs and prompts no longer depend on checked-in copies.

Historical change records and merged PR content remain unchanged.

Development-process change workflow

Add anuva-development-process-change to the plugin.

It must be explicit-only and usable from Product Main. Invocation authorizes a development-process planning and delivery workflow without Linear.

Eligible paths include:

Product Main plugin source and marketplace metadata;
Anuva CLI source, tests, packaging, and toolchain manifest;
Product Main development and engineering documentation;
AGENTS.md;
repository-local process and bootstrap documentation;
rule-file specifications and tested examples; and
removal of obsolete checked-in shared skills during migration.

It must reject product implementation, schemas, migrations, auth, billing, deployment architecture, application contracts, runtime assets, and arbitrary cross-repository paths.

The workflow should:

inspect all affected repositories and classify the exact process-only paths;
produce one Product Main implementation plan with repository impact;
pause once for approval of a material plan;
create one managed branch per affected repository;
edit Product Main plugin/CLI/policy and only approved repository-owned process surfaces;
run plugin validation, CLI tests, rule tests, affected docs verification, and repository-specific process-only checks;
commit, push, and create one draft PR per affected repository;
perform a cross-repository acceptance review;
present the complete merge order and cleanup effects;
after approval, merge, synchronize bases, and clean only managed branches; and
record the resulting plugin and toolchain versions.

No Linear issue or implementation child is created for this lane.

Linear and repository workflow changes

Product changes

Retain the existing Product Main Linear workflow for:

product outcomes and prioritization;
work spanning implementation repositories;
shared application contracts;
migrations;
authentication or authorization;
privacy or security;
billing;
deployment architecture;
release coordination; and
ownership uncertainty.

Product Main continues to create repository-scoped Linear implementation children after the product plan is approved.

Repository-local changes

Redefine anuva-repository-change so Linear is not automatic.

The skill should classify a request as:

Routine: issue-free local branch and PR workflow;
Material: issue-free by default with a separately approved plan, or an optional standalone Linear issue when the user requests durable tracking;
Product Main required: stop and return an exact Product Main intake.

Standalone Linear repository issues remain supported as an explicit choice, not the default for every change.

Plans and evidence

Require ImplementationPlan.md, ImplementationLog.md, and CompletionReport.md when they materially help with:

Product Main handoffs;
complex or high-risk work;
long-running implementation;
migrations or recovery;
cross-repository acceptance; or
durable operational knowledge.

Do not require all three artifacts for a small local fix merely to satisfy the workflow. A clear PR description, tests, and updated durable behavior docs may be sufficient.

MkDocs and Cloudflare preview redesign

Preserve the purpose

Machine-specific routes such as main1.girishd.com, bento1.girishd.com, web1.girishd.com, python1.girishd.com, and unity1.girishd.com exist to make intermediate Markdown pleasant to read from the development machine or another authenticated device.

They are previews of working trees, not release artifacts.

Split preview from verification

Add two distinct contracts:

Preview mode

start or health-check the repository's MkDocs server;
rely on MkDocs live reload for Markdown changes;
return exact Cloudflare URLs;
perform no strict build unless requested;
require no pre-edit timestamp;
require no per-edit restart;
require no separate user approval for an owned, reversible local preview process; and
never publish canonical docs.

Verification mode

validate relevant navigation and index rules;
run one strict build for the complete logical update;
optionally compare specified served pages with the strict build;
verify exact URLs before a material plan approval, draft PR, or completion;
produce concise evidence without repeatedly rebuilding unchanged pages.

CLI changes

Introduce or normalize:

anuva dev start --docs-only --with-tunnel
anuva docs preview --repository current --file <paths...>
anuva docs verify --repository current --file <paths...>
anuva docs links --repository current --file <paths...>
anuva docs status --all --json

Change the current implementation so:

Markdown source hash, Git branch, and Git HEAD changes do not force a server restart;
a server restarts only when its executable, arguments, port, configuration, working directory, health, or owned process identity requires it;
strict served-page comparison does not require the process to have started after a pre-edit timestamp;
one strict build verifies all requested pages;
an external listener is never killed;
an external healthy listener may be used for preview or verification only after content identity is established; and
preview link generation remains usable even when the server is stopped.

Index policy

Replace the rule requiring index.md in every directory with:

every user-facing documentation section must have an index or explicit navigation entry;
new, moved, renamed, or deleted pages must keep navigation and meaningful parent indexes accurate;
asset, generated, archive, and purely organizational directories do not need boilerplate indexes; and
validation reports orphaned pages, broken local links, invalid navigation, and genuinely empty user-facing sections.

Cloudflare protections

Retain:

one named tunnel per development machine;
one route per configured service or docs preview;
Cloudflare Access protection for every exposed route;
ACL-protected token files outside Git;
no automatic tunnel, route, DNS, certificate, or Access-policy creation or deletion; and
manual canonical publication.

Packaged Anuva CLI

Replace the current anuva.cmd launcher that runs anuva-main-video-creator\src\cli.ts with a self-contained, versioned installation under %LOCALAPPDATA%\Anuva\bin.

The packaged CLI must:

run without reading Product Main source;
expose anuva --version with semantic version and source commit;
report its installation path and build identity through anuva doctor;
use the configured C:\Anuva\dev repositories as data, not as its runtime source;
support atomic install or upgrade and rollback;
preserve the narrow allowlisted command model;
avoid arbitrary command, package, path, or workflow execution; and
remain testable from every configured repository.

The build and installation process should be owned by Product Main and included in the development-process workflow.

Shared toolchain policy

Tool classes

Product Main owns a fixed machine-toolchain manifest covering:

the packaged Anuva CLI;
Git;
GitHub CLI;
Bun;
Node and pnpm;
the Python runtime used by shared tools;
MkDocs and approved shared plugins;
Cloudflared;
skill/plugin validation tooling; and
optional machine-specific tool paths such as Unity.

Repository dependencies remain repository-local and lockfile or environment managed. Examples include CMS application packages, Mastra, ElevenLabs SDKs, the Python Server virtual environment, Bento dependencies, and Unity packages.

CLI commands

Add:

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

The manifest and command implementation must:

contain fixed tool identities, trusted sources, supported version ranges, detection commands, and installation or upgrade procedures;
reject arbitrary package names, URLs, scripts, or command strings;
distinguish missing, inaccessible-in-sandbox, installed, outdated, and incompatible states;
avoid reinstalling tools that already satisfy policy;
require explicit approval for install, upgrade, or removal;
write machine receipts outside Git without secrets; and
document manual recovery when administrative permission is required.

Skill validation

Add anuva skills validate or plugin-local validation that uses a packaged runtime and dependencies.

Do not create .validator-deps or run opportunistic pip install --target during normal implementation. Prefer the Anuva CLI's existing JavaScript YAML dependency or a validator bundled with the plugin/toolchain.

GitHub authentication

The Windows sandbox may not have access to the interactive user's credential keyring.

Shared skills should run the direct read-only gh auth status check in the known keyring-capable context before GitHub-backed delivery rather than first expecting a sandbox failure.

If it succeeds, subsequent GitHub-backed Anuva operations use the same context. Ask the user to authenticate only if the keyring-capable check fails.

Do not copy GitHub tokens into repository files, rules, logs, plugin assets, or machine configuration.

Codex rules policy

Rewrite the user rule file as a small, reviewed policy rather than an accumulation of exact chat-generated PowerShell payloads.

Retain or add only reusable prefixes such as:

guarded anuva operations;
direct read-only GitHub inspection;
direct Git remote reads where justified; and
known repository test or status commands that routinely require host execution.

Do not broadly allow:

powershell.exe -Command;
node, python, or bun;
patch helpers;
arbitrary file copy, move, or removal;
arbitrary GitHub API calls;
direct Git mutations already required to use the Anuva CLI; or
temporary issue-, PR-, path-, or process-specific command strings.

Add match and not_match examples and test the resulting file with codex execpolicy check.

Shared skills must run Anuva, GitHub, and other potentially elevated commands as separate direct commands rather than embedding them in compound PowerShell scripts with timestamps, variables, or control flow.

Repository impacts

`anuva-main-video-creator`

Owns:

DevelopmentProcessPolicy.md;
the anuva-development plugin and marketplace;
shared workflow skills;
packaged CLI and installer;
toolchain manifest and commands;
MkDocs preview/verification redesign;
rule specification and tests;
development-process workflow;
migration documentation; and
cross-repository acceptance.

`anuva-bento`

Must:

consume the installed plugin;
remove duplicated shared Anuva skills after the compatibility gate;
retain upstream, provenance, licensing, artifact, and offline verification in repository-owned guidance;
update process/bootstrap docs and active skill references; and
make no Bento runtime change for this rollout.

`anuvax-cms`

Must:

consume the installed plugin;
remove duplicated shared Anuva skills after the compatibility gate;
retain CMS affected-scope checks and workspace/auth, billing, schema/migration, Mastra, Payload, and application boundaries in repository-owned guidance;
retain CMS-owned Mastra and text-to-speech skills;
update process/bootstrap docs and active skill references; and
make no CMS runtime or schema change for this rollout.

`anuva-python-server`

Must:

consume the installed plugin;
remove duplicated shared Anuva skills after the compatibility gate;
retain affected-scope Python, protocol, security, simulator, path-safety, diagnostics, and redaction checks in repository-owned guidance;
update process/bootstrap docs and active skill references; and
make no server or protocol change for this rollout.

`anuva-unity-video-creator`

Must:

consume the installed plugin;
remove duplicated shared Anuva skills after the compatibility gate;
retain affected-scope Unity import, tests, render/capture, .meta, serialization, package, vendor, and protocol checks in repository-owned guidance;
update process/bootstrap docs and active skill references; and
make no Unity executable, serialized asset, package, or project-setting change for this rollout.

`anuva-dev-docs`

Remains generated canonical output only. It must not become the editable source for the policy, plugin, skills, or toolchain.

Implementation phases

Phase 0: Bootstrap authorization

Use one explicit Product Main bootstrap approval to change the current policy that otherwise requires Linear for changing itself.

Record:

the user-approved exception;
the exact Product Main branch and intended files;
confirmation that this is development-process work with no product runtime change; and
the requirement that later cross-repository rollout uses the new development-process workflow.

Phase 1: Policy and plugin skeleton

Create docs/development/DevelopmentProcessPolicy.md.
Reconcile overlapping development, skills, CLI, environment, and documentation-lifecycle pages around that policy.
Scaffold plugins/anuva-development with $plugin-creator.
Create the Product Main local marketplace entry.
Add initial plugin validation and discovery tests.
Install the development version locally and verify discovery in a new Codex task.

Exit criterion: the plugin is installed and exposes a harmless read-only test skill from Product Main.

Phase 2: CLI packaging and toolchain

The exact proposed scope, file list, transaction boundaries, verification matrix, and approval gates are recorded in the Phase 2 implementation plan. The user approved that plan on 2026-07-29. Gate 1 implementation is isolated to codex/development-policy-phase-2. Gate 2 installed and verified clean build 0.2.0-gc8776c067168 on machine one, including rollback to legacy-source, inverse rollback, and five-repository acceptance. Gate 3 review found no blocking issue, and PR #23 merged to main as 9c1fe7ef9ebf2c6ce65dc89844c46285a725ca6a. Phase 2 is complete. Confirmed toolchain bootstrap was unnecessary because the approved dry-run contained no actions. Phase 3 status is recorded below.

Add versioned CLI build output.
Add atomic local install, upgrade, and rollback. The approved first-install amendment preserves the Phase 1 source launcher as the one closed legacy-source rollback target before the packaged launcher becomes active.
Update anuva.cmd or replace it with the packaged executable entry point.
Add toolchain manifest, doctor, snapshot, and fixed bootstrap operations.
Add packaged skill validation.
Verify the CLI from each configured repository without Product Main source access.

Exit criterion: read-only and guarded commands work from every repository using the installed artifact, and no validator needs a temporary dependency install.

Phase 3: Documentation preview simplification

The exact Product Main scope, command contracts, compatibility path, test matrix, rollback, and three approval gates are recorded in the Phase 3 implementation plan. Gate 1 source implementation and Gate 2 live acceptance completed on 2026-07-29. The first approved artifact exposed a cross-repository structure-validator compatibility defect and was rolled back. Corrected clean artifact 0.2.1-g3dd30bca40f1 passes 109 source tests, seven packaged checks, rollback and inverse rollback, strict acceptance in all five repositories, and all five authenticated machine-one HTTPS routes. It is the active machine-one build with previous=0.2.0-gc8776c067168. Gate 3 found no blocking issue, and PR #25 merged to main as a02084cc9628973f5a965512a48486ba51c979eb. Phase 3 is complete; Phase 4 has not started.

Separate preview and verification commands.
Remove docs-source, branch, and HEAD changes as automatic restart reasons.
Remove the pre-edit timestamp requirement.
Make preview start idempotent and approval-free.
Change strict comparison to run only at meaningful gates.
Relax recursive index requirements.
Add tests for owned, external, stale, conflicting, and stopped listeners.
Verify all machine-specific Cloudflare routes.

Exit criterion: editing Markdown updates the remote preview without a manual restart, while one explicit verification command still proves a strict build.

Phase 4: Shared skill redesign

The exact proposed skill catalog, source paths, routing and approval contracts, plugin upgrade and rollback procedure, test matrix, exclusions, and three gates are recorded in the Phase 4 implementation plan. The user approved that plan. Gates 1 through 3 are complete. PR #27 merged exact reviewed head 610f3671c54f23187c02a6eb7b2d6c54f94d5491 as 7773e5db744e94a3ede35482c939210701f70527 after live upgrade, source-backed rollback, inverse rollback, and five-repository read-only acceptance. Installed plugin version 0.2.0 is active. Checked-in compatibility skills remain unchanged pending Phase 5.

Move shared skills into the plugin.
Add the work classification and risk-based approval policy.
Add the issue-free development-process skill.
Redefine repository changes so Linear is optional rather than automatic.
Simplify plan and evidence requirements for routine changes.
Add the development-environment and toolchain skills.
Remove first-failure GitHub auth instructions.
Test natural-language and explicit invocations in each repository.

Exit criterion: representative scenarios select the correct lane and request only the intended gates.

Phase 5: Repository migration

The exact proposed repository baselines, active paths, shared-skill deletions, plugin identity migration, validator adjustment, five-PR sequence, verification matrix, approval gates, and rollback procedure are recorded in the Phase 5 implementation plan. Phase 5 is complete. The five exact reviewed process-only PR heads were readied and squash-merged in the approved Bento, Web, Python, Unity, Product Main order on 2026-07-30. Product Main PR #29 merged as 7270381f562b48dbedc65e2c61392867ed9da486. Exact Git tree equality proved that each squash merge contains its reviewed head, all five main branches were synchronized, and the five managed branches were deleted.

Installed plugin version 0.2.0 is the canonical shared workflow-skill source in all five repositories. The 64 approved duplicated shared-skill files are absent, active references are plugin-qualified, Web's domain skills are preserved, and five-repository acceptance passed without product-code or historical-record changes. Packaged CLI build 0.2.1-g2fecf51439fc is active with 0.2.1-g3dd30bca40f1 as its verified rollback target. The Phase 5 plan records the exact heads, merges, readiness and CLI receipts, checks, and post-merge evidence. Phase 6 Gate 1 source implementation and its focused raw Codex configuration checksum evidence amendment were delivered as draft PR #31. Gate 2 machine-one rules installation, rollback to the 134-rule baseline, inverse rollback to the tracked minimal file, required restarts, and both 48-case acceptance runs are complete. The final active rules are 35eed0fb26bae95c7a45a4a1c83c119dcb012a4e5082758c1e02ef51379a4077, with baseline ebf0accf7700ee41f0334ed29d74f61c03a79d18221d73e367a6762179c26360 retained as the rollback target. Its exact implementation plan records the receipts and sanitized configuration-projection evidence. CLI and plugin installation, machine-two work, and Cloudflare remain behind later gates. Gate 3 subsequently merged exact reviewed PR #31 as Product Main 731782780f7cb11190dc2c976ed33135dfe76f35.

For each implementation repository:

install and verify the same plugin version;
move repository-specific verification out of shared skill copies;
update AGENTS.md, process docs, bootstrap docs, and active references;
prove no product implementation files changed;
remove checked-in shared Anuva skills;
validate domain-specific local skills remain discoverable; and
create one process-only PR.

The Product Main development-process workflow coordinates these PRs from one Codex task without Linear children.

Exit criterion: every repository uses the plugin and contains no active duplicated shared workflow skill.

Phase 6: Rules and machine replication

The durable gate sequence, exact Product Main path scope, minimal-rule contract, clean-machine CLI rollback prerequisite, two-machine verification, and stop conditions are defined in the Phase 6 implementation plan. The approved Gate 1 candidate and draft PR did not authorize a live machine mutation. Gate 2 separately authorized and completed only the machine-one rules transaction. Gate 3 merged the exact reviewed source as Product Main 731782780f7cb11190dc2c976ed33135dfe76f35.

The first Gate 4 preview stopped before machine-two or Cloudflare inspection because a clean Windows checkout with core.autocrlf=true expanded the reviewed 9,924-byte LF rules blob into a 10,187-byte CRLF working-tree file. The approved focused pre-Gate-4 correction adds only the exact config/codex/default.rules text eol=lf attribute, an installer-test regression assertion, and bounded evidence updates. A clean Windows verification checkout with core.autocrlf=true preserved the exact 9,924-byte reviewed rules source, and the complete 48-case matrix plus 4-test, 41-assertion installer suite passed. Gate 4 must restart from the correction merge with a newly built clean CLI artifact. No active rule, CLI, plugin, PATH, Codex configuration, machine-two, Cloudflare, Linear, sibling-repository, product, or Phase 7 state is authorized by that correction.

PR #32 merged the rules-EOL correction as cbdc3dd900a8d2b1e8c4ea992875f8e20ae3635f. The restarted Gate 4 preview built but did not install clean artifact 0.2.1-gcbdc3dd900a8, then stopped when a temporary-Git integration test repeatedly exceeded Bun's implicit five-second timeout despite passing unchanged with a 30-second limit. The focused timeout amendment adds an explicit 30-second timeout only to the two temporary-Git repository-change tests and records the verified restoration of canonical active rules after five user-approved persistent command rules were removed. Gate 4 must restart from the timeout-correction merge and rebuild the artifact. No machine-two, Cloudflare, Linear, product, sibling, plugin, CLI installation, PATH, config.toml, or Phase 7 mutation is authorized.

PR #33 merged that timeout correction as Product Main 011f29a884d17825eece19dce8d9bd4c62dd71ae. The corrected Gate 4 preparation passed the full source, packaged, and canonical-rules verification and built but did not install clean artifact 0.2.1-g011f29a884d1, SHA-256 2f8f19124742fb2cb2b87716c644d8e7f0a48ae61926ff5bdca128004314211b. Read-only route inspection then found that all six machine-two hostnames had no DNS record. No machine or Cloudflare state changed.

On 2026-07-31 the user directed the unavailable machine-two work to be deferred and Phase 7 planning to proceed. Phase 6 is closed for rollout ordering with a recorded exception, not with two-machine acceptance. The exact future setup and re-entry gates remain in the Phase 6 plan and Machine Bootstrap page.

Replace accumulated rules with the reviewed minimal file.
Test direct and wrapped command cases with codex execpolicy check.
Document machine bootstrap from a clean Windows development machine.
Verify plugin, CLI, toolchain, Codex configuration, Cloudflare Tunnel, Access-protected routes, and repository registry.
Capture a non-secret machine snapshot for comparison.

Original exit criterion: a second development machine can reproduce the workflow without ad hoc package installs or issue-specific approval rules. This remains unverified and is now an explicit deferred operational follow-up.

Phase 7: Completion and cleanup

The exact machine-one acceptance, cleanup, generated-documentation ordering, machine-two exception, path boundaries, and approval gates are defined in the Phase 7 implementation plan. Planning PR #34 merged as 117f7241f6f3e18440afdf49b11221d8fde5b80b. Gate 2 then completed the machine-one and cross-repository acceptance matrix under its approved environment-only amendment.

All six repository baselines finished clean. Plugin 0.2.0, the twelve-skill inventory, active CLI 0.2.1-g2fecf51439fc, rollback target 0.2.1-g3dd30bca40f1, canonical 9,924-byte rules, and the fixed toolchain remain unchanged. Source verification passed 123 tests and 509 assertions; packaged verification passed 7 tests and 125 assertions; and the 48-case rules matrix plus 4 installer tests and 41 assertions passed. Clean but uninstalled artifact 0.2.1-g117f7241f6f3 has SHA-256 674cadce76a84d316f04023603f74bbdc2d50169bd2620cee327c06c8a130fb1.

The bounded active-scope audit found no duplicated shared skill, obsolete unqualified invocation, or compatibility cleanup target. Five isolated strict documentation builds passed. The Product Main candidate has 48 generated additions, 50 changes, no removals, and path-manifest SHA-256 1efb9bc71d5dae586b5af1e5e08ae8d3c401aba2818fafeaa01bf18bfd21dc91 against canonical generated docs. Canonical mutation remains Gate 4 work. The machine-two exception remains explicit: machine two deferred, not accepted.

Run cross-repository acceptance scenarios.
Remove transitional compatibility instructions.
Remove obsolete shared skill copies and stale generated references.
Confirm Product Main source and canonical generated docs agree.
Record final plugin, CLI, toolchain, and policy versions.
Merge Product Main last if its final docs describe repository migrations that must already be true, or split foundation and completion PRs when that ordering is clearer.

Verification strategy

Plugin

Validate .codex-plugin/plugin.json.
Validate every bundled SKILL.md.
Confirm marketplace registration and installation.
Confirm upgrade and rollback.
Start a new task in every repository and inspect discovered skill names.
Test natural-language routing and explicit invocation.
Confirm repository-local Mastra and text-to-speech skills coexist with the plugin.

Workflow scenarios

Test at least:

Product change spanning CMS, Python, and Unity selects Linear Product Main planning.
Product-level auth or billing work cannot enter a routine lane.
Small CMS-local refactor uses the routine repository path without Linear.
Material Python-local behavior produces a plan gate but not automatic Product Main escalation.
Shared protocol change escalates to Product Main.
Plugin or AGENTS update selects the development-process workflow and creates no Linear issue.
Implement ANU-<id> starts the exact Ready child without a redundant start prompt, then pauses for a material plan.
Review and complete ANU-<id> merges after a clean review without asking for a second synonymous completion approval.
A review finding or scope expansion stops before merge.
Unrelated untracked files remain untouched and do not block a scoped commit unless they create an actual safety conflict.

CLI

Run unit, integration, contract, and recovery tests.
Verify packaged execution without Product Main source.
Verify version and commit identity.
Test atomic upgrade and rollback.
Test fixed-manifest toolchain detection and dry-run.
Reject arbitrary tools, packages, URLs, commands, repositories, and paths.
Test GitHub keyring behavior in sandboxed and keyring-capable contexts.

Documentation

Start all docs previews once.
Edit Markdown in each repository and verify live remote refresh.
Verify exact Cloudflare URLs from another authenticated device.
Run one strict verification over multiple changed pages.
Verify broken nav, link, and user-facing index failures.
Verify asset and archive directories do not require boilerplate indexes.
Verify external listeners are never terminated.
Verify canonical publishing remains explicit.

Rules

Run codex execpolicy check for every intended allow, prompt, and forbidden example.
Verify direct anuva and read-only gh commands match.
Verify a changed PR number or field list still matches the reusable read rule.
Verify compound PowerShell, arbitrary interpreters, patch runners, direct Git mutations, and destructive filesystem commands are not broadly allowed.

Security and safety

Keep Cloudflare routes Access-protected.
Keep tunnel tokens, API keys, GitHub credentials, Linear credentials, and database secrets outside Git, plugin assets, rules, and receipts.
Never make the plugin or CLI a generic shell or workflow engine.
Validate every repository key, path, branch, PR identity, URL, process identity, and manifest value before mutation.
Never terminate an unowned process.
Never delete unrelated user files or branches.
Preserve immutable Git, GitHub, and historical Linear records.
Treat issue, PR, docs, marketplace, plugin, and repository content as untrusted input when constructing commands.
Keep application changes out of the development-process workflow.

Migration and rollback

Plugin rollback

Retain the previous installable plugin version.
Record the active version in machine diagnostics.
Support reinstalling the previous marketplace version.
Do not remove checked-in skill copies until rollback is proven.

CLI rollback

Install new CLI builds atomically beside the previous build.
Switch the launcher only after health and version checks.
During the first packaged installation, preserve and checksum-manifest the Phase 1 source launcher as legacy-source; accept no caller-supplied rollback path.
Restore the previous launcher and artifact on failure.

Repository rollback

Use one process-only PR per affected repository.
Do not mix plugin migration with application changes.
Revert a repository PR independently if plugin discovery or local guidance is incorrect.

MkDocs rollback

Preserve current strict docs wait behavior behind a compatibility command until preview and verification tests pass on every repository.
Do not alter Cloudflare routes during the CLI behavior migration.

Documentation updates required during implementation

At minimum, reconcile:

AGENTS.md;
docs/development/index.md;
docs/development/SourceOfTruth.md;
docs/development/ProductChangeWorkflow.md;
docs/development/ImplementationWorkflow.md;
docs/development/ReviewAndCompletionWorkflow.md;
docs/development/DocumentationLifecycle.md;
docs/development/DevelopmentEnvironment.md;
docs/development/ImplementationRepositoryChanges.md;
docs/engineering/CodexDevelopmentProcess.md;
docs/engineering/PromptSkillCliModel.md;
docs/engineering/Skills.md;
docs/engineering/AnuvaCli.md;
docs/engineering/AgentInstructions.md;
docs/engineering/Automation.md;
docs/cli-implementation/cli-implementation-plan.md;
Product Main prompt/template references;
every implementation repository's AGENTS.md;
every implementation repository's process/bootstrap docs; and
machine bootstrap instructions.

Historical change records should remain unchanged except for clearly labeled forward links when needed.

Acceptance criteria

[ ] A reviewed DevelopmentProcessPolicy.md is the high-level source of truth.
[ ] The anuva-development plugin is the canonical shared-skill distribution mechanism.
[ ] The plugin installs, upgrades, rolls back, and is discovered in every Anuva repository.
[ ] Shared workflow skill copies are removed after a verified compatibility period.
[ ] Repository-specific technical skills remain repository-owned.
[ ] Product changes and shared application contracts still route through Linear.
[ ] Routine and development-process changes no longer create Linear issues automatically.
[ ] Approval gates follow the documented risk model.
[ ] A packaged Anuva CLI runs without Product Main source access.
[ ] Shared toolchain checks and bootstrap use a fixed allowlisted manifest.
[ ] Normal tasks never install temporary validator dependencies.
[ ] C:\Anuva\dev is readable from all Anuva Codex tasks on each machine.
[ ] Ordinary writes remain repository-scoped.
[ ] Product Main development-process work can update only approved process surfaces across repositories.
[ ] MkDocs previews refresh intermediate working-tree docs without per-edit restart or strict build.
[ ] Strict docs verification remains available at material delivery gates.
[ ] All machine-specific routes remain Access-protected and canonical publication remains manual.
[ ] GitHub authentication uses the keyring-capable context without a deliberate first failure.
[ ] The user rule file contains only reusable, tested command prefixes.
[ ] All repository and cross-repository verification scenarios pass.
[ ] A second development machine can reproduce the complete setup from Product Main documentation.

Recommended separate-session prompt

Use the following intent in the implementation task:

Implement the approved Anuva Development Policy plan in
docs/development/AnuvaDevelopmentPolicyImplementationPlan.md.

Treat this as the explicitly authorized one-time Product Main bootstrap
exception described in Phase 0. Begin with Phase 1 only: create the durable
DevelopmentProcessPolicy, scaffold and locally test the skills-only
anuva-development plugin and marketplace, and present the resulting exact
implementation plan and preview before broader CLI, rules, MkDocs, or
cross-repository migration work.

Do not create Linear issues. Do not modify implementation-repository product
code. Do not remove checked-in shared skills until plugin discovery, upgrade,
and rollback have been verified.