AGENTS Orchestrate

Version: 0.2.0

Reusable AGENTS.md instruction system with modular workflow files and a bundled orchestration layer for multi-agent repository coordination.

Repository Layout

Path	Purpose
AGENTS.md	Universal startup instructions for agents.
AGENTS.d/	Triggered workflow modules and orchestration tooling.
_cmd	Root user command entrypoint for AGENTS helper access and .dev/_cmd.d project commands.
AGENTS.d/config.md	Repo-specific switches, identity, and local policy.
agents-propagation	Repo-local UI/CLI for propagating AGENTS payloads to local repos.
agents-propagation.json	Source-only canonical manifest for propagation payload files.
.dev/	Project goals, structure notes, and local agent records.
private/	Source-only docs, tests, and helper-script context excluded from target repos.
VERSION.md	Canonical version log.

Verification

Run routine/default contract checks before handoff:

python3 private/tests/agents-cli/agents_propagation_test.py
python3 private/tests/agents-cli/agents_cli_test.py
python3 private/tests/agents-cli/user_cmd_test.py
python3 private/tests/agents-cli/user_logged_issues_test.py
python3 private/tests/orchestrator/orchestration_cli_test.py
python3 private/tests/agents-cli/public_publish_test.py

Run the full orchestrator contract suite for release readiness or orchestrator-risk changes:

python3 private/tests/orchestrator/orchestration_cli_test.py --full

AGENTS CLI

Use the unified helper entrypoint for AGENTS-defined workflows:

./_cmd help
./_cmd agents-cli status
./_cmd agents-cli get ORCHESTRATION
./_cmd hello
./_cmd custom hello
./AGENTS.d/agents-cli -h
./AGENTS.d/agents-cli status
./AGENTS.d/agents-cli get ORCHESTRATION
./AGENTS.d/agents-cli issue status
./AGENTS.d/agents-cli issue archive --days 2
./AGENTS.d/agents-cli note add -m "One compact paragraph describing the change"
./AGENTS.d/agents-cli note list
./AGENTS.d/agents-cli plan new --name NAME --goal TEXT --scope TEXT
./AGENTS.d/agents-cli plan executed list
./AGENTS.d/agents-cli orchestrate -h
./AGENTS.d/agents-cli publish --help
./AGENTS.d/agents-cli propagate --help

./_cmd is the user-facing wrapper. It requires no .dev/_cmd file and shows commands grouped as AGENTS, Custom, then .dev/_cmd.d commands. It discovers custom commands from .dev/_cmd.custom.d/commands/*.sh and project commands from .dev/_cmd.d/commands/*.sh when those folders exist.

AGENTS Propagation

Run the simple terminal UI:

./AGENTS.d/agents-cli propagate

Useful direct commands:

./AGENTS.d/agents-cli propagate refresh
./AGENTS.d/agents-cli propagate list
./AGENTS.d/agents-cli propagate safe
./AGENTS.d/agents-cli propagate status
./AGENTS.d/agents-cli propagate apply --dry-run
./AGENTS.d/agents-cli propagate apply
./AGENTS.d/agents-cli propagate apply --target /path/to/repo --yes

The maintained target inventory and safe target list live in ignored .agents-propagation/; apply backups live in ignored .tmp/agents-propagation/backups/. refresh updates .agents-propagation/safe-targets.txt with active untracked repos where propagation can run without tracked payload edits or both-folder manual review. Propagation reads committed HEAD:agents-propagation.json as the canonical source-only manifest, so dirty source edits and untracked files are ignored. The manifest lists explicit payload files only: AGENTS.md, _cmd, and exported AGENTS.d/** blobs. It excludes AGENTS.d/config.md, agents-propagation, agents-propagation.json, .dev/, private/, .agents-propagation/, and old source-only test paths. Payload changes must update the manifest in the same change.

By default, status and apply only select active repos where AGENTS.md and the module folder are untracked, and either AGENTS.d/ exists or legacy AGENTS/ exists for migration. Use --include-non-active, --include-tracked, or repeated --target PATH arguments for explicit non-default work.

Each repo update prints a full per-repo change report before mutation: added files, replaced files, deleted files, unchanged count, and blockers. Deleted is currently always (none) because propagation never removes target files. Bulk approval is forbidden; bulk apply asks separately for each repo. --yes is accepted only with one explicit --target PATH.

The legacy root ./agents-propagation entrypoint remains available for compatibility.

Version

Current release: 0.2.0.