agents-workflow

A portable, low-token workflow for building small and medium software projects with AI without losing decisions, scope, or evidence between conversations.

Project state lives in versioned Markdown under .agents/. An executor owns product work; a planner/auditor owns control state and verifies deliveries. The workflow scales assurance to risk, so a basic AI subscription does not need a second full conversation for every low-risk commit.

Status: 2.0.0-dev. The public contract is in skill/agents-workflow.md.

Who it is for

Use it when a project spans multiple sessions, files, agents, or handoffs and needs enough order to remain resumable. It is designed for learners, solo builders, and small teams.

It is not a workflow engine, graph orchestrator, critical-infrastructure framework, or replacement for domain expertise. A one-sitting script probably does not need it.

Core model

• Product plane: executor changes code, tests, assets, and task-specific product docs.
• Control plane: planner/auditor maintains .agents/, audits, indexes, and snapshots.
• Product commits: one bounded task, subject contains [T-NN].
• Control commits: planning, repair, closure, or export uses [STATE].
• Evidence: claims name the command and result; unavailable checks are declared.
• Durability: local Git is required. A remote is useful but optional.

.agents/
  AGENTS.md              roles, assurance, boundaries, gates
  APPCORE.md             stable purpose, architecture, invariants
  CURRENT.md             concise current state and next action
  CONTEXT.md             chronological append-only log
  INDEX.md               navigation and important paths
  TESTING.md             human or unavailable checks
  PLAN_vX.Y-name.md      active milestone and task briefs
  archive/               closed plans and preserved history

Markdown plus Git is the source of truth. Vector indexing, databases, and external memory are intentionally not required. They may help very large knowledge bases later, but they add cost and synchronization failure modes before most small projects benefit.

Eight jobs

Job	Purpose
INIT	Create .agents/ for a project that lacks it
MAINTAIN	Repair stale or contradictory control state without reinitializing
AUDIT	Independently verify a delivery and return APTO, NO APTO, or BLOCKED
RUN THE LOOP	Execute and audit bounded tasks until a stop condition
CLOSE	Reconcile and archive a verified milestone
COMPACT	Reduce repeated context cost without losing decisions or traceability
REINDEX	Rebuild navigation from repository facts
EXPORT DOCUMENTATION	Generate a dated root DOCUMENTATION.md snapshot for a human

DOCUMENTATION.md is exported on demand. It is not another living file agents must update after every change. Generate it when the project grows, before a handoff, or when a technical collaborator needs a readable overview.

Token-aware assurance

• Lean (default): deterministic gates per product commit; model audit when risk, failure, phase boundary, or release warrants it. Adjacent low-risk work may be reviewed in a batch.
• Standard: independent model audit at milestones and selected tasks.
• Strict: independent audit for every task plus domain gates; reserve for real high risk.

Audits start from a compact audit capsule: criteria, commits, changed files, diff, gate results, risks, and questions. They expand context only when evidence requires it.

Install

Clone this repository, then use the installer matching your shell.

./install.sh --agent claude --global
./install.sh --agent cursor --project .
./install.sh --agent opencode --project .
./install.sh --agent generic --project .

.\install.ps1 -Agent claude -Global
.\install.ps1 -Agent cursor -Project .
.\install.ps1 -Agent opencode -Project .
.\install.ps1 -Agent generic -Project .

Supported targets:

• claude: installs a SKILL.md with frontmatter.
• cursor: installs a project rule.
• opencode: manages a marked block in AGENTS.md.
• generic: manages the same portable block for agents that read AGENTS.md.

Installers are idempotent and refuse malformed managed markers instead of overwriting ambiguous owner content. Manual installation is also valid: copy skill/agents-workflow.md into your agent's instruction file.

Use

Examples:

Use agents-workflow. INIT this repository with Lean assurance.
Use agents-workflow. MAINTAIN .agents; repair contradictions and old absolute paths.
Use agents-workflow. AUDIT the executor's [T-07] delivery.
Use agents-workflow. RUN THE LOOP for the active milestone.
Use agents-workflow. EXPORT DOCUMENTATION for a technical collaborator.

INIT records sibling-system boundaries and whether Git is local-only, remote-backed, or backed up elsewhere. Persistent briefs use repository-relative paths.

Starter files are in templates/.agents/. A filled example is in examples/todo-api/.agents/; see its walkthrough.

Migrate from v1

Update the installed skill, then ask it to MAINTAIN the existing .agents/. It should preserve product code and history, create/repair INDEX and the active milestone plan, record Lean/Standard/Strict, replace durable absolute paths, reconcile stale status, and use a [STATE] commit. Do not run INIT over an existing control plane.

Optional pre-commit guard

hooks/pre-commit blocks valued environment files and common secret shapes, including current OpenAI project-key prefixes. It also warns when CURRENT grows past the compaction signal. See hooks/README.md.

The hook is a safety net, not a complete secret scanner.

Develop and verify

The repository uses only Python's standard library for contract tests:

python -m unittest discover -s tests -v
bash -n install.sh
bash -n hooks/pre-commit

The evaluation prompts and v1 baseline are under evals/. CI runs the contract and installer tests on Linux and Windows.

License

MIT. See LICENSE.