AGENTS.md Playbook for Parallel Delivery 🤝

Practical guidance for running AI agents in parallel with a consistent, auditable, and non-chaotic workflow.

This repository centers on a production-style AGENTS.md contract so agents can:

• pick one issue at a time,
• recover execution state from Codememory instead of chat history,
• execute in dedicated worktrees,
• deliver focused commits and PRs,
• validate before merge,
• and continue autonomously, using <CONTINUE-LOOP> only when the runtime needs another turn or work is intentionally paused.

Why this exists 🧭

Most teams do not fail from lack of AI capability; they fail from coordination drift.

This playbook focuses on practical controls for multi-agent execution:

• predictable task ownership with native issue IDs,
• durable internal task/session memory through Codememory,
• e2e worktree flow (wt flow) for safe branch isolation,
• remote alignment checks before implementation and again right before merge,
• autonomous execution that keeps moving while a safe next step is clear,
• key-gate validation (pre-PR required, pre-merge conditional),
• concise final-response patterns that make pending work obvious.

Start in 5 minutes ⏱️

1. Read AGENTS.md.
   • If resuming a previous session, re-read AGENTS.md and the workflow docs you will use so repo changes beat stale session memory.
2. Sync/check remote state so local context matches the latest branch and PR status.
3. Check Codememory context with oc current, oc next, oc queue, or oc resume --scope <repo-scope> --task <task_id>.
4. List and pick a scoped delivery item with gh issue list --state open --limit 20.
5. Review context with gh issue view <id> and confirm it still fits upstream.
6. For delivery work, link the task to the relevant GitHub issue/PR; read-only work skips tracking.
7. Execute delivery work in a dedicated worktree branch (never directly on main).

For full command detail, use:

• docs/index.md
• docs/codememory-workflow.md
• docs/codememory-conventions.md
• docs/tooling-quick-ref.md
• docs/design-image-decision-guide.md
• docs/codex-image-cli.md
• docs/github-cli.md
• docs/validation-policy.md
• docs/orchestration-advanced.md
• make help for operator shortcuts
• make preflight when remote/wiki readiness is needed

What is in this repo 📚

• AGENTS.md: source-of-truth operating contract. Repo-root AGENTS.md is canonical; runtime mirrors should symlink to it rather than copy it.
• docs/index.md: concise hub for core workflow, planning, and wiki docs.
• docs/codememory-workflow.md, docs/codememory-conventions.md, docs/tooling-quick-ref.md, docs/github-cli.md, docs/validation-policy.md, docs/orchestration-advanced.md: daily operator references.
• docs/release-notes-template.md: minimal template for friendly, concise release notes and PR summaries.
• docs/codex-image-cli.md: portable, API-key-only GPT Image 2 CLI protocol for non-interactive agents.
• docs/plan/README.md: status model for long-form AI planning docs under docs/plan/.
• docs/site/index.html: generated GitHub Pages landing page with latest release notes from repo docs.
• docs/wiki-*: wiki provisioning, mirror, and fallback publication docs.
• Makefile: non-interactive operator shortcuts for docs workflows and checks.

For ongoing readiness checks, run make wiki-probe-dispatch to trigger the scheduled wiki probe workflow on demand. For publishable fallback sync, use make wiki-fallback-sync-dry-run and make wiki-fallback-sync-apply. For automated fallback sync in CI, configure FALLBACK_REPO_TOKEN and run make wiki-fallback-dispatch.

Workflow highlights (adaptive loop + wt flow e2e) 🔁

• Default execution loop: resume, classify, research, plan (review medium/large work), define validation, execute, review/fix, commit the validated slice, update Codememory, then continue or close.
• Clear implementation, fix, and improvement requests run this complete delivery loop by default. Use local-only, no-push, or no-PR when the work must stop after local validation and commit.
• Asking an agent to do work "end-to-end"/"e2e" is equivalent to the default: run the loop inside wt flow, then continue through PR, risk-based review/fix/improve, merge, worktree cleanup, and local main sync unless the request explicitly narrows the stop point.
• create a dedicated worktree and branch for each feature/bug/task,
• recover or create task/session state in Codememory before coding,
• check remote branch and PR state before implementing so overlapping AI work is caught early,
• define validation before coding,
• iterate quickly, then commit once per validated slice,
• run review/fix/improve passes according to risk,
• do one final upstream/overlap check before merge to avoid stale or conflicting changes,
• open PR, validate checks, merge,
• cleanup worktree, sync main, close the corresponding issue.

Reference flow:

TS="$(date +"%Y-%m-%dT%H:%M:%S%z")"
SID="<runtime-session-id>"
git checkout main
git pull --rebase
git worktree add ../<branch> -b <branch>
# confirm issue/PR scope still matches latest upstream before coding
# recover or attach Codememory task/session context before coding
# implement + validate, then one focused commit
# when a command writes logs or telemetry, prefix it with TS="$TS" OPENCODE_SESSION_ID="$SID"
git push -u origin <branch>
# create PR (prefer `gh api`; see docs/github-cli.md)
# re-check origin/main and overlapping PRs before merge
# after merge
git worktree remove ../<branch>
git pull --rebase

Continuation signal ✨

Continue autonomously while the next safe action is clear. Emit <CONTINUE-LOOP> only when the runtime needs a new turn or work is intentionally paused; do not use it as a routine handoff or approval prompt. Do not bounce small choices like naming, wording, file placement, or ordering back to the user when a repo-consistent default is obvious; make the call and continue. Stop with BLOCKER:, EVIDENCE:, and NEXT: only for material ambiguity, secrets, security/privacy, scope, or an unresolved check. For visible progress notes, command summaries, and local test reporting, use one local timestamp prefix per related block collected from the shell at runtime (for example by running date +"%Y-%m-%d %H:%M" first and then prefixing the block with the resulting value in the format [YYYY-MM-DD HH:MM]) so execution history is easier to trace without adding noise to every line. Do not print the literal $(date ...) form in the response.

External tools used 🔧

• oc: Codememory CLI for internal execution tracking and AI handoffs.
• native GitHub issue tracking via gh and repository workflows.
• gh: GitHub CLI for PR lifecycle and checks.
• uv: Python environment and package tooling.
• ruff: Python lint/format.
• rg and fd: fast search and discovery.
• GNU parallel: parallelized independent command execution.

The GitHub Pages site is generated from repo notes with make site-build and deployed by .github/workflows/pages.yml.

Useful links:

• GitHub CLI (gh): https://cli.github.com/
• uv: https://docs.astral.sh/uv/
• Ruff: https://docs.astral.sh/ruff/
• ripgrep (rg): https://github.com/BurntSushi/ripgrep
• fd: https://github.com/sharkdp/fd
• GNU parallel usage in this repo: docs/tooling-quick-ref.md and local utils-scripts/docs/cheatsheets/parallel.md when that clone is available.

Native issue and PR command usage is documented in AGENTS.md, docs/index.md, docs/tooling-quick-ref.md, and docs/github-cli.md. Codememory usage is documented in AGENTS.md, docs/codememory-workflow.md, docs/codememory-conventions.md, and docs/tooling-quick-ref.md.

Docs, Wiki, and GitHub Pages 🌐

• Docs folder: docs/
• Wiki home: https://github.com/dmoliveira/agents.md/wiki
• GitHub Pages site: https://dmoliveira.github.io/agents.md/

If you maintain this repo, keep README, docs, wiki, and pages aligned so new contributors can onboard quickly.

Support this project 💛

If this helps your team ship faster and safer, consider supporting maintenance and future open projects:

• Donation options: docs/support-the-project.md
• GitHub Sponsors: https://github.com/sponsors/dmoliveira

Every contribution (code, docs, sponsorship, issue triage) keeps the playbook useful and current.