Communitygithub.com

candycong2001-ui/agent-project-playbook

A set of human-AI collaboration playbooks that can be installed, migrated, and iterated continuously.

What is agent-project-playbook?

This skill provides a structured playbook for human-AI collaborative project management, enabling consistent handoffs, state preservation, and document governance across development cycles. It works with any AI agent that supports custom skills (Claude Code, Cursor, Codex, etc.) by defining clear workflows, document boundaries, and linting steps. The playbook ensures that agents read the latest handoff document (`CURRENT_HANDOFF.md`) at task start, verify claims against actual repository state, and update only the necessary stable documents (`BLUEPRINT.md`, `ARCHITECTURE.md`) when relevant changes occur. It also enforces line limits on key documents to keep them concise, uses Git for history instead of appending logs, and includes a lint script (`docs_lint.py`) to validate document compliance before substantial deliveries. This reduces confusion, prevents drift, and makes project collaboration predictable and scalable.

Works with~Claude Code~Codex CLI~Cursor
npx skills add candycong2001-ui/agent-project-playbook

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Project Docs

Workflow

  1. At the start of substantial implementation or diagnosis, read docs/CURRENT_HANDOFF.md and only relevant sections of the stable documents.
  2. Verify document claims against current repository evidence.
  3. During exploration or read-only review, report drift without editing unless the user authorizes changes.
  4. At task start, replace the current goal and next action in CURRENT_HANDOFF.md.
  5. After a verified milestone, replace current state and verification evidence; do not append a timeline.
  6. Before handoff, remove completed process details and leave one continuation-ready state.
  7. Update BLUEPRINT.md only when product intent, users, scope, constraints, or acceptance change.
  8. Update ARCHITECTURE.md only when components, boundaries, data flow, verified commands, deployment, rollback, or risks change.
  9. Before substantial delivery, run python3 .agents/skills/project-docs/scripts/docs_lint.py.

Boundaries

  • Current code, tests, configuration, command output, and user instruction outrank these documents.
  • Keep BLUEPRINT at or below 160 lines.
  • Keep ARCHITECTURE at or below 160 lines.
  • Keep CURRENT_HANDOFF at or below 80 lines.
  • Keep AGENTS at or below 90 lines.
  • Git stores history. CURRENT_HANDOFF stores only the latest working state.

Related Skills