Agent Project Control

Agent Project Control (APC) is a repository-local governance layer for coding-agent projects. It combines an Agent Skill, a Node.js CLI, and a versioned control-plane template. A Controller uses it to define bounded Work Items, register agent Executions, collect Git and test Evidence, make an independent decision, and hand the project to a later Controller without relying on chat history.

APC is not a coding-agent runtime, model gateway, messaging framework, task tracker, web application, SaaS, or automatic merge/push service. It does not create or launch an LLM/coding agent. Your existing Codex, Claude Code, Cursor, or other coding platform still runs the agent; APC records and verifies project facts.

Governance profiles

Choose the smallest profile that matches the risk of the change:

| Profile | Intended use | Controls | | --- | --- | --- | | Minimal | Demo, PoC, one-off documentation or low-risk single-writer changes | Work Item contract, branch/HEAD baseline, path boundary checks, optional checks; no Execution record | | Standard | Normal product work and changes that need traceable verification | Full Work Item + Execution lifecycle, isolated write worktrees, Git Evidence, allowlisted tests, inspection and Controller decision | | Enterprise | Large, long-lived or regulated programs | Not implemented in this release; configuration fails explicitly rather than silently weakening controls |

Standard remains the compatibility default for existing 0.1 projects. Standard is the compatibility default. A 0.2 project can opt into Minimal:

schemaVersion: "0.2"
governance:
  default: minimal
  minimum: minimal

The resolver applies the project default, Work Item override, project minimum, and a non-disableable safety floor. Multiple writers, isolation-sensitive paths, authentication, databases, CI/release/deployment, dependencies, tests/Evidence, or an explicit Standard minimum automatically require Standard.

Install and initialize

Requirements: Node.js >= 20, npm, and Git on PATH. Normal operation uses repository files only and has no database or network requirement.

npm install --save-dev agent-project-control
npx agent-control init --dry-run
npx agent-control init
npx agent-control doctor

init requires a Git repository and installs .agent-control/ without overwriting existing files, resetting a dirty worktree, or changing application code. Use --control-dir <relative-path> for another repository-local directory. Review and commit the generated control-plane files yourself.

Controller workflow

Start a session with:

npx agent-control doctor
npx agent-control takeover

doctor is read-only. It validates configuration, schemas, Work Items, the Execution Registry, lifecycle rules, isolation/concurrency, Git state, and AGENTS rules. takeover reports active/ready/blocked work, unfinished verification, minimal contextRefs, and a recommended next step without scanning the source tree.

Create and validate a Work Item:

npx agent-control work-item create --from draft.yaml
npx agent-control work-item validate WI-AUTH-001
npx agent-control work-item show WI-AUTH-001
npx agent-control work-item ready

Work Items separate delivery status from assurance level and declare dependencies, context, allowed/forbidden paths, acceptance criteria, required tests, and rollback guidance. Duplicate IDs, missing or cyclic dependencies, path escapes, and overlapping active write scopes are rejected.

For a bounded Minimal change:

Minimal saves time for one Agent and one writer. A successful Minimal flow creates no Execution, and without recorded verification assurance remains unverified.

npx agent-control work-item begin WI-DOCS-001
# invoke one native platform sub-agent
npx agent-control work-item finish WI-DOCS-001

Minimal records a baseline and final Git facts but creates no Execution. A boundary violation, failed check, changing/unattributable baseline, detached branch, or new coordination need stops advancement and requires Standard or explicit authorization.

For Standard, register an Execution. Read-only work needs an exact base commit; write work also needs an isolated branch and worktree:

npx agent-control execution register --work-item WI-AUTH-001 --mode write --runtime codex \
  --branch codex/wi-auth-001 --worktree C:/worktrees/wi-auth-001 --base-commit <head>
npx agent-control execution start EXE-001
npx agent-control execution collect EXE-001 --summary "Implemented bounded change" --claimed-changed-file src/auth/callback.mjs
npx agent-control execution test EXE-001 -- npm test -- auth
npx agent-control execution inspect EXE-001
npx agent-control execution decide EXE-001 --accept --notes "Machine evidence and registered tests pass"
npx agent-control work-item set-status WI-AUTH-001 --delivery-status implemented --assurance-level integration_tested
npx agent-control work-item set-status WI-AUTH-001 --delivery-status integrated
npx agent-control execution close EXE-001
npx agent-control work-item set-status WI-AUTH-001 --delivery-status closed

Only commands listed in requiredTests are allowed. Git facts are machine-derived and override agent claims. Failed tests, boundary/forbidden-path changes, bad base or isolation, dirty write worktrees, and read-only changes block acceptance. execution retry creates a new Execution ID and preserves the old record.

Standard registrations capture an immutable policy snapshot; retries receive a new snapshot and the previous attempt remains history. enterprise is unsupported and fails explicitly.

execution retry EXE-001 --branch codex/wi-auth-001-retry-1 --worktree C:/worktrees/wi-auth-001-retry-1 --base-commit <fresh-base-commit>
execution start <new-execution-id>

A retry uses a fresh branch, a dedicated worktree, and the current intended base commit; it never overwrites the old Execution.

Keeping the control plane fast

APC keeps active data separate from immutable history. Inspect the plan before moving terminal records:

npx agent-control execution archive --dry-run
npx agent-control execution archive --apply --keep 5
npx agent-control work-item archive --dry-run
npx agent-control work-item archive --apply
npx agent-control work-item history
npx agent-control review --json

Archive operations are explicit, locked, atomic, schema-checked, and non-destructive: they do not delete history, branches, worktrees, or user files. review is read-only and highlights retry hotspots, path churn, stale integration, dirty control data, and completed batches, then recommends continue, integrate, reprioritize, freeze_local_fix, or request_user_decision.

Skill and architecture

The packaged Skill is in skill/. It runs doctor and takeover, resolves the profile, chooses Minimal or Standard, invokes the platform's native sub-agent, and lets the CLI own storage, Git facts, tests, Evidence, and state transitions.

skill/SKILL.md -> bin/agent-control.mjs -> src/cli/ -> src/core/
                                                   -> src/storage/ + src/git/
                                                   -> .agent-control/ + Git

The Controller is the only Registry writer. Writes use a local lock, validated temporary output, atomic replacement, and a last-known-valid backup. Git commands use argument arrays through one client; paths are normalized to / and checked against the repository root. APC never performs hard reset, discard checkout, forced branch/worktree removal, automatic merge, or automatic push.

Verification and limitations

npm ci
npm test
npm run check
npm pack --dry-run

cd examples/python-project
python -m unittest discover -s tests
cd ../..

The repository includes Node and Python example projects and deterministic scenarios for initialization, takeover, Minimal/Standard execution, boundary/test/base/worktree failures, conflicts, retry, false completion claims, archive behavior, and Skill non-trigger behavior. This release run validated the controlled suite on Windows with Node.js 24.18.0 and Python 3.12.10; it did not execute the suite on macOS or Linux. Storage coordinates processes on one host only. It does not claim production, commercial, real-user, macOS, Linux, Enterprise, web UI, cloud database, user accounts, GitHub App, Jira/Linear integration, unattended development, automatic deployment, or arbitrary-agent-runtime support.

This is not production, commercial, real-user, macOS, Linux, or Enterprise validation.

GitHub and npm

Source: github.com/kiera2004/agent-project-control. Install published versions with npm; install a tagged source snapshot with:

npm install --save-dev github:kiera2004/agent-project-control#v0.2.2

Publishing is intended for the repository's GitHub Actions Trusted Publishing workflow. Do not commit tokens or .npmrc; push reviewed commits and tags only after CI is green.

The release workflow is .github/workflows/publish.yml and uses GitHub OIDC with id-token: write; it does not embed an npm Token. For version 0.2.2, keep package.json and package-lock.json aligned, then publish the reviewed tag and release:

git tag -a v0.2.2 -m "Agent Project Control v0.2.2"
git push origin main
git push origin v0.2.2
gh release create v0.2.2 --verify-tag --generate-notes

License

MIT