Agent Ops Kit

Agent Ops Kit is a vendor-neutral workflow scaffold for AI-assisted coding. It gives Codex, Claude Code, GitHub Copilot / VS Code, and OpenCode the same project workflow, document templates, project rules, knowledge base, skills, and agent structure.

The package is installed from npm, then explicitly initialized inside a project. npm install does not modify your repository.

Why

AI coding tools often fail in predictable ways:

• coding starts before requirements are clear
• generated specs use inconsistent formats
• review and test results are not recorded
• prompts drift between tools
• useful corrections stay trapped in chat history

Agent Ops Kit keeps the workflow in repository files so every supported tool can read the same source of truth.

Install And Initialize

Install the package in your project:

npm install --save-dev agent-ops-kit

Initialize Agent Ops Kit:

npx agent-ops-kit init --all

This creates the workflow files, document templates, active/archive spec folders, and selected AI tool adapters.

You can also run the initializer without adding the package to package.json:

npx agent-ops-kit@latest init --all

Install multiple selected tool adapters:

npx agent-ops-kit init --tools codex,claude
npx agent-ops-kit init --tools github,opencode

Choose a workflow profile during initialization:

npx agent-ops-kit init --all --workflow standard
npx agent-ops-kit init --all --workflow strict
npx agent-ops-kit init --all --workflow lightweight
npx agent-ops-kit init --all --workflow review-only

Preview changes first:

npx agent-ops-kit init --all --dry-run

Validate the installed scaffold:

npx agent-ops-kit doctor

Recommended first run:

npm install --save-dev agent-ops-kit
npx agent-ops-kit init --all --dry-run
npx agent-ops-kit init --all
npx agent-ops-kit doctor

Install one adapter when the project uses only one AI coding tool:

npx agent-ops-kit init --tools codex
npx agent-ops-kit init --tools claude
npx agent-ops-kit init --tools github
npx agent-ops-kit init --tools opencode

The generated files are normal project files. Review them before committing:

.workflow/
docs/specs/
.codex/       # only when Codex is installed
.claude/      # only when Claude Code is installed
.github/      # only when GitHub Copilot / VS Code is installed
.opencode/    # only when OpenCode is installed

First-Time Setup

After init, open your chosen AI coding tool and run setup before starting a feature. Setup should populate or review .workflow/project/* and confirm the installed adapter files.

Use this prompt:

Use the setup skill.
Read `.workflow/coding.yml` and `.workflow/workflow-spec.md`.
Initialize Agent Ops Kit for this project.
Update `.workflow/project/*` with project-specific rules.
Leave unknowns as `TBD`.

The setup skill initializes project context, checks templates and knowledge files, and confirms the installed tool adapters are usable.

Do not start implementation during setup.

Select The Orchestrator Agent

Every feature must start from the Orchestrator agent. Do not start by asking the default chat agent to implement code.

The Orchestrator must:

• read .workflow/coding.yml
• read .workflow/workflow-spec.md
• create or update docs/specs/active/<feature>/todo.md
• create or update docs/specs/active/<feature>/progress.md
• select the current stage.agent and stage.skill
• read the selected tool skill
• delegate to the selected role agent
• ask before moving to the next stage

If your tool provides an agent picker, select the installed Orchestrator agent. If it does not, explicitly name the Orchestrator agent file in the prompt.

Adapter entry points:

| Tool | Orchestrator agent | Skill root | | --- | --- | --- | | Codex | .codex/agents/orchestrator.toml | .codex/skills/ | | Claude Code | .claude/agents/orchestrator.md | .claude/skills/ | | GitHub Copilot / VS Code | .github/agents/orchestrator.agent.md | .github/skills/ | | OpenCode | .opencode/agents/orchestrator.md | .opencode/skills/ |

Start By Tool

Codex

Install with:

npx agent-ops-kit init --tools codex

Start a feature by selecting or invoking the Codex Orchestrator agent:

Use `.codex/agents/orchestrator.toml` as the Orchestrator agent.
Feature: `user-login`.
Read `.workflow/coding.yml` and `.workflow/workflow-spec.md`.
Start from Requirements Clarification.
Create or update `docs/specs/active/user-login/todo.md`.
Create or update `docs/specs/active/user-login/progress.md`.
Select the stage agent and skill from `.workflow/coding.yml`.
Read the selected `.codex/skills/<skill>/SKILL.md`.
Do not implement before Specification Approval is complete.
Ask before moving to the next stage.

Claude Code

Install with:

npx agent-ops-kit init --tools claude

Use the Orchestrator as the main session agent. Claude Code subagents should not spawn other subagents; the main session Orchestrator coordinates role agents.

Use `.claude/agents/orchestrator.md` as the Orchestrator agent.
Feature: `user-login`.
Read `.workflow/coding.yml` and `.workflow/workflow-spec.md`.
Start from Requirements Clarification.
Create or update `docs/specs/active/user-login/todo.md`.
Create or update `docs/specs/active/user-login/progress.md`.
Select the stage agent and skill from `.workflow/coding.yml`.
Read the selected `.claude/skills/<skill>/SKILL.md`.
Delegate only to the role agent declared by `stage.agent`.
Ask before moving to the next stage.

GitHub Copilot / VS Code

Install with:

npx agent-ops-kit init --tools github

Start from the installed Copilot Orchestrator agent. If your environment does not show an agent picker, paste the prompt and explicitly name the agent file.

Use `.github/agents/orchestrator.agent.md` as the Orchestrator agent.
Feature: `user-login`.
Read `.github/copilot-instructions.md`.
Read `.workflow/coding.yml` and `.workflow/workflow-spec.md`.
Start from Requirements Clarification.
Create or update `docs/specs/active/user-login/todo.md`.
Create or update `docs/specs/active/user-login/progress.md`.
Select the stage agent and skill from `.workflow/coding.yml`.
Read the selected `.github/skills/<skill>/SKILL.md`.
Delegate only to the agent declared by `stage.agent`.
Ask before moving to the next stage.

OpenCode

Install with:

npx agent-ops-kit init --tools opencode

Use the OpenCode Orchestrator agent or the installed workflow command if your OpenCode setup exposes commands.

Use `.opencode/agents/orchestrator.md` as the Orchestrator agent.
Feature: `user-login`.
Read `.workflow/coding.yml` and `.workflow/workflow-spec.md`.
Start from Requirements Clarification.
Create or update `docs/specs/active/user-login/todo.md`.
Create or update `docs/specs/active/user-login/progress.md`.
Select the stage agent and skill from `.workflow/coding.yml`.
Read the selected `.opencode/skills/<skill>/SKILL.md`.
Delegate only to the agent declared by `stage.agent`.
Ask before moving to the next stage.

Start A Feature

After setup, start work from the Orchestrator agent in your AI coding tool.

Do not start a feature by asking the default chat agent to write code. Select or invoke the Orchestrator agent first. The Orchestrator owns the workflow state, creates todo.md, updates progress.md, selects stage.agent and stage.skill from .workflow/coding.yml, reads the selected tool skill, and delegates work to role subagents.

The first Orchestrator response should not contain implementation code. It should produce:

• Workflow Start Report
• selected stage
• selected agent
• selected skill
• active feature folder
• todo.md path
• progress.md path
• approval status
• current TODO checklist
• clarifying questions for the current stage
• whether user confirmation is required before continuing

Generic prompt:

Use the Orchestrator agent for feature `user-login`.
Read `.workflow/coding.yml`.
Follow the workflow strictly.
Start from Requirements Clarification.
First produce a Workflow Start Report.
Show the selected stage agent and selected stage skill.
Create or update `docs/specs/active/user-login/todo.md`.
Create or update `docs/specs/active/user-login/progress.md`.
Create the todo checklist from the active workflow stage.
Read the selected tool skill before stage work.
Delegate work to the subagent declared by `stage.agent`.
At the end of each stage, ask me whether to proceed to the next stage.
Do not implement before Specification Approval is complete.

Continue an existing feature:

Use the Orchestrator agent for feature `user-login`.
Continue from the current workflow stage.
Infer the stage from existing files under `docs/specs/active/user-login/`.
Read `docs/specs/active/user-login/todo.md`.
Read `docs/specs/active/user-login/progress.md`.
Select the current `stage.agent` and `stage.skill` from `.workflow/coding.yml`.
Read the selected tool skill.
Update the todo checklist from the active workflow stage.
At the end of each stage, ask me whether to proceed to the next stage.
Do not skip Specification Approval.

The expected control loop is:

Orchestrator
  -> updates progress.md and todo
  -> selects stage.agent and stage.skill from .workflow/coding.yml
  -> reads the selected tool skill
  -> delegates to planner / reviewer / implementer / tester
  -> receives Subagent Report
  -> updates progress.md and todo
  -> asks whether to proceed to the next stage
  -> decides next stage, blocked state, or rollback

TODO tracking is required, but todo is not a portable agent tool name. If the selected AI tool exposes a native TODO or planning tool in the current session, the Orchestrator should use it. In all cases, it must maintain the durable checklist in docs/specs/active/<feature>/todo.md.

todo.md and progress.md have different jobs:

• todo.md records the executable checklist for the current workflow stage.
• progress.md records workflow status, user input, AI output, confirmations, decisions, blockers, and stage results.

Default Workflow

Requirements Clarification
  - generates requirements.md
Specification Design
  - generates tasks.md
  - generates implementation.md
Specification Approval
Code Implementation
Code Inspection
  - generates inspection.md
Code Testing
  - generates testing.md
Archive

Active feature documents live under:

docs/specs/active/<feature-id>/

Completed feature documents move to:

docs/specs/archive/<feature-id>/

Repository Layout

.workflow/coding.yml        # active workflow
.workflow/workflow-spec.md  # YAML field guide
.workflow/versions/         # workflow profiles
.workflow/templates/        # output document templates
.workflow/project/          # project-specific engineering rules
.workflow/knowledge/        # durable corrections, decisions, and conventions
docs/specs/active/          # active feature specs
docs/specs/archive/         # archived feature specs
.codex/                     # Codex adapter
.claude/                    # Claude Code adapter
.github/                    # GitHub Copilot / VS Code adapter
.opencode/                  # OpenCode adapter

Tool-specific folders are adapters. They should not define a separate workflow.

The npm package stores scaffold source files under src/. Users do not need to edit src/; it is only used by the CLI when copying files into a project.

Skills

Each supported tool exposes the same thin skill entry points:

orchestrator
setup
requirements
spec
approval
implementation
inspection
testing
archive
knowledge
project
template
workflow

The tool-specific skill files contain the operational rules for each tool. They all follow .workflow/coding.yml and keep the workflow behavior inside the selected tool adapter.

Agents

Each adapter includes one coordinating agent and four role subagents:

orchestrator  # controls workflow transitions, todo, and progress.md
planner       # requirements, specification, archive planning
implementer   # code implementation after approval
reviewer      # approval and code inspection
tester        # test execution and acceptance reporting

The orchestrator owns workflow state. It creates a Workflow Start Report, maintains todo.md, and updates:

docs/specs/active/<feature-id>/todo.md
docs/specs/active/<feature-id>/progress.md

Role subagents execute scoped work and return a Subagent Report. They must not decide stage transitions, mark approval complete, or bypass rollback rules.

Subagent boundaries:

• planner may write workflow documents, but not source code.
• reviewer may edit workflow review documents, but must not modify production source code unless explicitly delegated and allowed by the code edit gate.
• implementer may modify source code only after approval and only for approved tasks.
• tester may run or record tests, but must not claim acceptance without evidence.

Workflow Profiles

Agent Ops Kit installs one active workflow and selectable profiles:

.workflow/coding.yml
.workflow/versions/standard.yml
.workflow/versions/strict.yml
.workflow/versions/lightweight.yml
.workflow/versions/review-only.yml

List profiles:

npx agent-ops-kit workflow list

Activate a profile:

npx agent-ops-kit workflow use strict --force

Validate the active workflow:

npx agent-ops-kit workflow validate

Use the workflow skill when editing .workflow/coding.yml or .workflow/versions/*.yml.

CLI Reference

npx agent-ops-kit init
npx agent-ops-kit init --all
npx agent-ops-kit init --all --workflow strict
npx agent-ops-kit init --tools codex,claude
npx agent-ops-kit init --all --dry-run
npx agent-ops-kit init --all --force
npx agent-ops-kit workflow list
npx agent-ops-kit workflow use strict --force
npx agent-ops-kit workflow validate
npx agent-ops-kit doctor

Defaults:

• init installs only the core workflow unless --all or --tools is provided.
• init uses the standard workflow profile unless --workflow is provided.
• existing files are skipped unless --force is provided.

Knowledge

Use the knowledge skill when a durable correction, repeated AI mistake, important decision, or project convention should be stored.

Default files:

.workflow/knowledge/learned-rules.md
.workflow/knowledge/mistakes.md
.workflow/knowledge/decisions.md
.workflow/knowledge/glossary.md

Do not store temporary task notes, secrets, credentials, or personal data.

License

MIT. See LICENSE.