Metadata-Version: 2.4
Name: sharedincc-agent-work
Version: 2.3.4
Summary: Deterministic Git lifecycle and execution harness for AI-agent work
Author: Sharedincc
License: Proprietary
License-File: LICENSE
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: build<2,>=1.2.2; extra == 'dev'
Requires-Dist: mypy<2,>=1.15; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```text
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:

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

Install the stable wheel with an isolated tool installer:

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

Initialize and operate a repository:

```bash
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:

```bash
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/`](docs/README.md).

## Documentation

- [Architecture](docs/architecture.md)
- [Lifecycle and state machine](docs/lifecycle.md)
- [Configuration contract](docs/configuration.md)
- [Security model](docs/security.md)
- [Implementation plan](docs/implementation-plan.md)
- [Development guidelines](docs/development-guidelines.md)
- [Architecture decisions](docs/decisions/README.md)

## Distribution identity

| Surface | Identity |
| --- | --- |
| Repository | `agent-work` |
| Python distribution | `sharedincc-agent-work` |
| Python import package | `agent_work` |
| Executable | `agent-work` |
| Runtime | Python 3.11–3.13, standard-library-only runtime dependencies |

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