agent-work

agent-work is a forge-neutral Git lifecycle controller for AI-agent and human implementation tasks.

It makes parallel repository work safer without introducing a coordination service, database, daemon, or vendor-specific merge system. Projects define a small amount of policy; agent-work computes and enforces the mechanical lifecycle around implementation:

start task
→ implement bounded change
→ checkpoint owned files
→ validate exact commit
→ preserve submission
→ land against current integration head
→ verify reachability
→ close and audit

The tool is designed to keep agents focused on engineering. Agents should not have to remember when to commit, which validation receipt is still valid, whether a task is integrated, or whether cleanup is safe. The CLI derives those facts from Git and returns one deterministic next action.

Product principles

• Git is the authority. Durable work is represented by commits and refs, not chat history or mutable status prose.
• Forge-neutral. Local bare repositories, SSH remotes, self-hosted forges, and hosted forges use the same core workflow.
• No background platform. The initial product has no daemon, database, scheduler, dashboard, or forge API dependency.
• Fail closed. Undeclared scope, stale validation, unsafe cleanup, and ambiguous integration block rather than guessing.
• Idempotent transitions. Repeating a command after interruption must continue safely without duplicate commits or publication.
• Small integration units. One task packet represents one independently integrable batch.
• Project-owned validation. Consumer repositories define the commands that prove their own behavior.
• Compact agent protocol. Skills delegate lifecycle reasoning to the CLI and receive structured next actions.

Intended usage

A consumer repository contains a tracked configuration file and project-owned validation commands:

consumer-repository/
├── .agent-work.toml
└── tools/ci/
    ├── test-affected
    └── test-integration

Install the stable wheel with an isolated tool installer:

pipx install sharedincc-agent-work
# or
uv tool install sharedincc-agent-work

Initialize and operate a repository:

agent-work init --json
agent-work doctor --json
agent-work profiles list --json
agent-work task create --id AUTH-17 --objective "Add token rotation" \
  --commit-summary "add token rotation" --profile auth \
  --output .agent-tasks/AUTH-17.json --json
agent-work workspace create .agent-tasks/AUTH-17.json --json
agent-work workspace inspect AUTH-17 --json
agent-work claim inspect AUTH-17 --json
agent-work claim recover --json
agent-work ready --json
agent-work run --json --output-profile agent
agent-work forecast --json
agent-work workspace retire AUTH-17 --json
agent-work operations list --json
agent-work operations inspect <operation-id> --json
agent-work operations resume <operation-id> --json
agent-work adopt --analyze --repository /path/to/consumer --json
agent-work adopt --write --analysis-sha256 <analysis-sha256> \
  --repository /path/to/consumer --json
agent-work adopt --verify --repository /path/to/consumer --json
agent-work task create --dry-run --id AUTH-18 --objective "Preview task" \
  --commit-summary "preview task" --allow "src/**" \
  --output /tmp/AUTH-18.json --json
agent-work diagnose --json
agent-work audit --json
python tools/qualify_release.py --agent-work /path/to/installed/agent-work --json
python tools/qualify_release.py --agent-work /path/to/installed/agent-work --scenario synchronization --json
python tools/qualify_release.py --agent-work /path/to/installed/agent-work --scenario adversarial --json
python tools/qualify_release.py --agent-work /path/to/installed/agent-work --scenario coordination-recovery --json
python tools/qualify_release.py --agent-work /path/to/installed/agent-work \
  --scenario lost-response --json

Install the canonical low-token skills with:

agent-work skills install --target all --json
agent-work skills verify --target all --json

Normal execution agents should not manually commit, merge, rebase, push, or retire task worktrees while the controller owns the task lifecycle.

Repository status

Version 2.0.0 provides the stable Git lifecycle, deterministic agent protocol, canonical task authoring, readiness, policy-controlled refresh, non-publishing integration forecast, managed workspaces, operation recovery, consumer adoption, and the completed packaged qualification matrix. The authoritative architecture, release procedure, and completed implementation plan are documented under docs/.

Documentation

• Architecture
• Lifecycle and state machine
• Configuration contract
• Security model
• Implementation plan
• Development guidelines
• Architecture decisions

Distribution identity

The distribution name is intentionally distinct from the import package and executable.