Imported from kenjudy/pdca-agentic-coding-framework (AGENTS.md). Install upstream with npx skills add kenjudy/pdca-agentic-coding-framework. Copyright stays with the author.

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --status in_progress  # Claim work
bd close <id>         # Complete work
bd sync               # Sync with git

Landing the Plane (Session Completion)

When ending a work session, complete ALL steps below, then stop and wait for human approval before pushing.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. Prepare push - Stage and commit, then present the following to the human and wait for explicit approval:

   git pull --rebase
   bd sync
   git status   # show the human what will be pushed

5. Push only after explicit approval - When the human says to push, run git push
6. Verify - git status must show "up to date with origin"
7. Hand off - Provide context for next session

CRITICAL RULES:

• Do NOT push without explicit human instruction ("go ahead and push", "push it", etc.)
• Present git status and the proposed push command; wait for a clear go-ahead
• If push fails, report the error and wait for human direction before retrying

Skill Build System

The PDCA skill is built from source — never edit build artifacts directly.

skill/
├── build-skill.sh              ← thin wrapper (macOS/Linux): calls build.py
├── build-skill.ps1             ← thin wrapper (Windows): calls build.py
├── build.py                    ← the build implementation — the only place build logic lives
├── pdca-framework/
│   ├── SKILL.md                 ← SOURCE: edit this for skill descriptor changes
│   ├── beads-addon/sources/     ← SOURCE: edit these files (beads phase additions, setup, workflow)
│   ├── ponytail-addon/sources/  ← SOURCE: edit these files (ponytail phase additions, setup, workflow)
│   ├── claude-addon/injections/ ← SOURCE: CLAUDE_INJECT content
│   └── references/              ← BUILD ARTIFACT: generated by build.py
└── pdca-framework.skill         ← BUILD ARTIFACT: the installable zip

~/.claude/skills/pdca-framework/  ← Claude Code installation
~/.agents/skills/pdca-framework/  ← Codex installation

Master content (prompt text) lives in the Obsidian notes:

• 1. Plan/1a Analyze...md
• 1. Plan/1b Create a detailed implementation plan.md
• 2. Do/2. Test Drive the Change.md
• 3. Check/3. Completeness Check.md
• 4. Act/4. Retrospect for continuous improvement.md
• Human Working Agreements.md

To make prompt content changes: edit the Obsidian master files, then rebuild. To make skill structure changes: edit pdca-framework/SKILL.md or the addon source files, then rebuild. To install for Claude Code: unzip -o skill/pdca-framework.skill -d ~/.claude/skills/ To install for Codex: unzip -o skill/pdca-framework.skill -d ~/.agents/skills/

One build implementation, two entry points: skill/build.py is the only place build logic lives. bash skill/build-skill.sh (macOS/Linux) and skill/build-skill.ps1 (Windows) are thin wrappers over it — see skill/BUILD.md's Architecture section. Adding or removing a packaged file means editing build.py (and skill/tests/test_build.py's EXPECTED_FILES); neither wrapper script needs to change.