AI Operator System

AI Operator System is a practical file-and-review workflow for maintainers using AI coding tools on real repositories.

It is built around a small set of files: repo guardrails, review gates, handoff docs, backlog notes, and short specs. The workflow is designed to work across tools like Claude Code and Codex because the durable truth lives in files, not in chat history.

Quick Start

1. Read docs/global-doctrine.md and docs/file-model.md.
2. Copy only the templates you need from templates/ into your repo.
3. Fill in repo-specific rules in CLAUDE.md, review checks in REVIEW.md, and restart state in HANDOFF.md.
4. Write a short spec before non-trivial work, then implement the smallest useful slice.
5. Run the review gate, update the handoff/backlog, and commit only after the human reviewer is satisfied.

Why This Exists

Most "AI coding workflow" material either collapses into vague prompt advice or overclaims autonomy. This repo takes the opposite approach:

• verification-first instead of "implemented = done"
• spec-before-build for non-trivial work
• review-before-commit for sensitive changes
• file-based continuity instead of chat-only memory
• human approval for trust-sensitive or irreversible steps
• clear global vs repo-local file roles

The goal is simple: make AI-assisted implementation easier to review, safer to continue, and less dependent on chat memory.

What This Is

• a practical operator system for AI-assisted repo work
• a reusable file-role architecture
• a documentation and template repo
• a concrete example of applied AI workflow discipline

Who It Helps

This is for maintainers, solo developers, and small teams that want AI assistance without losing reviewability. It is most useful when a repo has enough complexity that chat-only context starts to fail: recurring bugs, sensitive flows, long-running refactors, release prep, or multiple AI sessions touching the same codebase.

What This Repo Is Not

• not an autonomous-agent vanity repo
• not a giant AI framework
• not plugin or MCP theater
• not a dump of private notes or internal operating logs
• not a mass-automation system

Architecture

The operating model is intentionally small:

1. Global doctrine defines durable work principles.
2. Repo-local files define project-specific truth.
3. Claude is typically used for framing, research, inventory, and short specs.
4. Codex is typically used for bounded implementation, cleanup, and polish once the shape is clear.
5. Sensitive work passes through explicit review and validation gates before commit or publication.
6. Handoff and backlog files keep continuity outside chat context.

This is less an "AI orchestration layer" and more a shared operating surface for disciplined repo work.

Use Cases

• PR review: capture repo-specific pass/fail checks before merge.
• Issue triage: turn messy reports into scoped specs, known gaps, or backlog items.
• Refactor planning: define non-goals, risk areas, and validation before changing code.
• Docs generation: produce docs from repo truth instead of chat memory alone.
• Release/checkpoint handoff: summarize what landed, what was verified, and what remains.
• AI coding session continuity: restart work across tools without rebuilding context from scratch.

Maintainer Workflows

The system assumes a human maintainer owns intent, risk, and final approval.

• Claude Code can help inventory a repo, clarify the problem, draft a spec, or critique a plan.
• Codex can help implement bounded slices, tighten docs, run checks, and prepare a reviewable patch.
• Shared files keep both tools aligned on the same repo truth.
• The maintainer decides what ships, what waits, and when a task needs a stricter review.

This is intentionally not a claim of autonomous maintenance. The value is making AI-assisted work easier to bound, review, continue, and hand off.

Safety Model

• Spec before build: write down the goal, constraints, non-goals, and validation path first.
• Bounded implementation: prefer the smallest useful change over broad rewrites.
• Review before commit: use a clear gate for sensitive logic, data integrity, dependency, or release changes.
• No irreversible actions without human approval: destructive commands, publication, and trust-sensitive changes stay human-gated.
• Durable file-based handoff state: use files for restart context so the next session does not depend on chat memory.

Example Workflow

1. Write a short spec that defines the problem, constraints, smallest slice, and validation plan.
2. Implement a small slice against the spec.
3. Run tests, lint, dry runs, or other focused checks.
4. Do a strict review against REVIEW.md and the spec.
5. Update HANDOFF.md and BACKLOG.md with what changed, what passed, and what remains.

Repo Structure

ai-operator-system/
├── README.md
├── CONTRIBUTING.md
├── ROADMAP.md
├── LICENSE
├── .gitignore
├── .github/
│   ├── pull_request_template.md
│   └── ISSUE_TEMPLATE/
│       ├── workflow_idea.md
│       ├── docs_improvement.md
│       └── example_request.md
├── docs/
│   ├── global-doctrine.md
│   ├── model-role-split.md
│   ├── file-model.md
│   ├── review-and-validation.md
│   ├── orchestration-pattern.md
│   ├── adoption-framework.md
│   └── skills/
│       ├── spec-writer.md
│       ├── strict-review.md
│       ├── startup-ritual.md
│       ├── repo-eval.md
│       └── adoption-decision.md
├── templates/
│   ├── CLAUDE.md
│   ├── REVIEW.md
│   ├── HANDOFF.md
│   ├── BACKLOG.md
│   └── SPEC_TEMPLATE.md
└── examples/
    ├── pipeline-review-example.md
    ├── handoff-example.md
    ├── repo-eval-example.md
    └── adoption-decision-example.md

How To Use This

1. Read docs/global-doctrine.md and docs/file-model.md.
2. Copy the templates you actually need into a real repo.
3. Put repo-specific truth in CLAUDE.md, not in a broad project memo.
4. Put the pass/fail gate in REVIEW.md and use it before committing sensitive changes.
5. Use a short spec before non-trivial work, then implement the smallest safe slice.
6. Keep HANDOFF.md short enough to restart from quickly and keep BACKLOG.md as the place for deferred work.

When It Helps

This model is most useful when you want:

• clearer boundaries between planning, execution, and review
• continuity across chats, sessions, and tools
• smaller, more honest commits
• human approval before sensitive continuation

How Codex/API Credits Would Help

Additional Codex/API credits would support practical improvements without changing the human-in-the-loop model:

• test the templates against more example repo shapes
• create Codex prompt templates for common maintainer workflows
• generate and review CI/checklist examples
• iterate on issue triage and release handoff patterns
• run more validation passes on docs, examples, and safety gates

Publishing Notes

If you use this publicly, keep the same standard this repo argues for:

• do not overclaim automation
• do not advertise ceremony as rigor
• do not duplicate doctrine into every file
• do not confuse tooling inventory with operating quality

Suggested GitHub Topics

If publishing on GitHub, these topics describe the repo without implying adoption:

ai-workflows, codex, claude-code, ai-assisted-development, human-in-the-loop, developer-tools, repo-automation