ai-dev-playbook

AI-native development methodology — rules, skills, and scripts for working with coding agents across Cursor and Claude Code.

Returning to coding after some time away? Start with WELCOME.md — an agent-driven onboarding path designed for folks who used to code and want to come back as agent-native builders. Hand it to anyone you want to bring into this style of working.

Point an agent at any repo

The playbook is installed, set up, and used by agents. After a one-time per-machine install:

• In any repo, tell your agent "use the playbook." It reads the agent-protocol block in your global rules, runs playbook-doctor.sh --agent, and branches on the exit code — offering bootstrap, sync, or update with your consent.
• In any un-bootstrapped git repo, the agent prompts at session start: "This project isn't bootstrapped with the ai-dev-playbook. Run init, skip, or add to ignore?"
• Bootstrapped repos carry an AGENTS.md pointing any agent (Cursor, Claude Code, Codex, Copilot, future) at the setup, the rules, and the doctor. Discovery is automatic.

One-time machine setup:

git clone https://bitbucket.org/pryoninc/ai-dev-playbook ~/ai-dev-playbook
bash ~/ai-dev-playbook/scripts/install-global-safety-net.sh    # per-machine agent rule blocks
bash ~/ai-dev-playbook/scripts/install-aliases.sh              # pbi, pbd shell aliases

Both installers are non-interactive and safe for agents to run on your behalf. See QUICKSTART.md for the full setup.

What's here

cursor/rules/ (source of truth)

Canonical .mdc rule files. These are the single source — edit here, then sync to project repos. Both Cursor and Claude Code formats are generated from these files.

claude/rules/ (generated, canonical source)

Claude Code-compatible .md files — same content as Cursor rules with YAML frontmatter stripped. Generated by scripts/sync-rules.sh --format claude --local. Do not edit directly. Deployed to .claude/rules/ in target repos (where Claude Code auto-discovers them).

Rule	What it does
beads-quality.mdc	Bead creation standards: --acceptance required, non-goals, evidence on close
pragmatic-tdd.mdc	Signal-first TDD by bead type, zero-signal test taxonomy
bead-completion.mdc	JIT verification, self-review against ACs, AC ownership protocol, bd remember knowledge capture
design-docs.mdc	When to create committed specs (3+ beads or high-risk areas)
worktree-awareness.mdc	Git worktree isolation: commit-early discipline, shared beads DB via redirect, no false fabrication claims
multi-agent-review.mdc	Two-tier review protocol: same-model multi-lens (autonomous) + cross-model (human-assisted), pattern-level bd remember capture
operating-model.mdc	Planner/Executor roles, mode switching, scratchpad conventions, beads task tracking, workflow
agent-identity.mdc	No human-baseline estimation — describe complexity, scope, and risk instead of timelines
session-lifecycle.mdc	Mandatory session start/close protocol: bd prime, in-progress check, knowledge capture
parallel-subagent-safety.mdc	Prevents file-edit conflicts between parent agent and running subagents — blast radius awareness
defer-convention.mdc	Mark deliberate simplifications with defer: comments: ceiling + upgrade trigger required
ponytail-playbook.mdc	Lazy senior dev implementation ladder — minimal, correct code. Stdlib/native/reuse before new

cursor/settings-ui/

Optional user-level Cursor Settings UI rule for personal conventions (e.g., "always ask before using -force git"). The operating model (Planner/Executor roles, workflow, scratchpad) now lives in operating-model.mdc and syncs automatically with all other rules.

File	What it is
instructions-rule.md	Personal conventions and lessons that apply across all projects (optional — paste into Cursor Settings if desired)

scripts/

Script	What it does
playbook-init.sh	One-command project setup. Copies rules, initializes beads, runs bd hooks install by default, creates scratchpad, emits AGENTS.md, registers for sync. Supports --tool cursor|claude|both, --stealth, and --no-hooks. Refuses non-TTY invocation without an explicit --tool flag.
playbook-doctor.sh	Validates playbook setup. Checks rules, beads, scratchpad, sync targets, worktrees, global safety net. --agent mode emits a SUMMARY: line and structured exit codes (0=ok, 2=bootstrap_needed, 3=rules_drift, 1=error). On rules_drift (exit 3) the SUMMARY carries the format that needs remediation: rules_drift_cursor, rules_drift_claude, or rules_drift_both — agents branch on the SUMMARY key, not the bare exit code, so they pass the right --format to sync-rules.sh.
install-global-safety-net.sh	One-time per-machine install. Writes marker-delimited blocks into ~/CLAUDE.md (agent-identity, session-start bootstrap check, agent-protocol) and generates a Cursor user-rules paste snippet. Content lives in global-safety-net/*.md — add a file + registry entry to add a concern. Supports --check, --uninstall, --print-cursor-snippet.
install-aliases.sh	One-time per-machine install. Writes ~/.playbook-aliases.sh and adds a single guarded source line to ~/.zshrc / ~/.bashrc. Installs pbi (init), pbd (doctor), and AI_DEV_PLAYBOOK env var. Non-interactive; safe for agents.
sync-rules.sh	Multi-format rule sync. --format cursor|claude|all (also accepts both as an alias for all). Supports --check (drift), --local (in-repo generation), --dry-run (preview). Safe-by-default: locally modified files are backed up to *.<ts>.bak before being overwritten; --unsafe disables to silently overwrite. Validates targets, cleans stale files, survives per-target errors.
sync-cursor-rules.sh	Deprecated — prints migration instructions, then syncs. Use sync-rules.sh instead.
setup-worktree.sh	Creates .beads/redirect so worktrees share the main repo's beads database. Runs automatically via IDE hooks or manually.

examples/

Real-world analysis artifacts demonstrating the Stringer scan-to-beads pipeline on Pryon repos.

Setup

Quick start (recommended)

git clone https://bitbucket.org/pryoninc/ai-dev-playbook ~/ai-dev-playbook
cd /path/to/your/project
bash ~/ai-dev-playbook/scripts/playbook-init.sh

See QUICKSTART.md for all setup options and docs/concepts.md for how the pieces fit together.

Manual setup

1. Clone this repo
2. Add your project repo roots to ~/.playbook-sync-targets (one path per line)
3. Run ./scripts/sync-rules.sh to distribute Cursor rules
4. Run ./scripts/sync-rules.sh --format claude to distribute Claude Code rules

Adding a new project repo

Add its root path to ~/.playbook-sync-targets. The file is local and untracked — no merge conflicts.

Checking for drift

./scripts/sync-rules.sh --check                  # Check cursor rules
./scripts/sync-rules.sh --format claude --check   # Check claude rules

Reports which targets have stale or missing rules without modifying anything.

Regenerating Claude rules in this repo

./scripts/sync-rules.sh --format claude --local

What syncs automatically vs. what you copy manually

Rules (cursor/rules/*.mdc) sync automatically via sync-rules.sh. Add a target repo to ~/.playbook-sync-targets and run the script — rules distribute to the repo and all its worktrees (Cursor) or to .claude/rules/ (Claude Code).

Worktree setup (.cursor/worktrees.json + scripts/setup-worktree.sh) is a one-time manual copy per repo. These files may need repo-specific customization (additional dependencies, environment setup), so they're templates you adopt, not auto-synced artifacts.

Workflow

1. Edit rules in cursor/rules/ (this repo is the canonical source)
2. Run ./scripts/sync-rules.sh --format claude --local to regenerate claude/rules/
3. Run ./scripts/sync-rules.sh to distribute Cursor rules to project repos
4. Run ./scripts/sync-rules.sh --format claude to distribute Claude rules to project repos
5. (Optional) If you use the Settings UI rule for personal conventions, keep cursor/settings-ui/instructions-rule.md in sync and paste into Cursor Settings

Rules are auto-discovered — adding a new .mdc file to cursor/rules/ automatically includes it in the next sync. No script edits needed.

Worktree setup for beads

When Cursor creates a worktree, it bypasses bd worktree create, so beads can't find the database. The setup script fixes this by writing a .beads/redirect file that points the worktree to the main repo's database. All worktrees share one beads instance.

How it works

1. .cursor/worktrees.json tells Cursor to run scripts/setup-worktree.sh on every new worktree (postCreate hook)
2. The script detects the main repo via git rev-parse --git-common-dir and writes an absolute-path redirect
3. bd list (and all other bd commands) work from the worktree immediately

Adopting in your repo

1. Copy scripts/setup-worktree.sh into your repo (keep it executable: chmod +x)
2. Copy .cursor/worktrees.json into your repo's .cursor/ directory
3. Commit both files
4. Optionally pin dolt.port in .beads/config.yaml to a repo-specific port — this prevents random-port warnings when multiple shells or worktrees connect to Dolt. Choose a port that won't collide with other beads-enabled repos on the same machine.

For existing worktrees

Run the script manually from the worktree root:

bash scripts/setup-worktree.sh

If the worktree already has a local beads database from a previous bd init, the script will detect it and warn rather than overwrite.

Portability

The setup script is pure shell (no python3 or bd binary required). Validated on bd 0.61.0 (Homebrew) and macOS/Linux. On Windows, use WSL or Git Bash.

Documentation

Document	Audience
WELCOME.md	Returning coders / first-time agent-native builders — prompt-driven onboarding
QUICKSTART.md	First-time setup in under 5 minutes
docs/concepts.md	Why the playbook exists and how the four components work together
sandbox/	Hands-on 45-min exercise teaching the full workflow by doing
docs/glossary.md	Plain-English definitions of all terminology
docs/README.md	Full reading order — decks, guides, and reference material
docs/executive-summary.md	One-page org operating model summary (CTO level)
docs/rule-effectiveness-scorecard.md	Measuring whether rules change agent behavior
CONTRIBUTING.md	How to propose and contribute changes
CODE_OF_CONDUCT.md	The Agentic Covenant — governance for human-agent collaboration
docs/governance.md	How governance fits into the playbook and positions Pryon as a thought leader
CHANGELOG.md	What changed and when

Versioning

The playbook uses semantic versioning. Teams can pin to a stable release:

./scripts/sync-rules.sh --version v1.0.0              # Sync from a specific release
./scripts/sync-rules.sh --show-version                 # Print current version

See CONTRIBUTING.md for release process details.

Origin

Rules adapted from obra/superpowers and ed3dai/ed3d-plugins, cherry-picked for signal over dogma.