docs: add CONTRIBUTING.md

.claude/skills/update-changelog/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: update-changelog
+description: Updates a project changelog with entries for changes since the branch diverged from main. Use when about to open a PR, cutting a release, or when the user asks about changelog, release notes, or migration notes.
+---
+
+# Update Changelog
+
+## Step 0 — Bind the version
+
+If an argument that looks like a version number was provided (e.g.,
+`v1.2.0`, `1.2.0`, `v2.0.0-rc.1`), store it as `VERSION`, normalising
+to include a `v` prefix if absent. Otherwise VERSION defaults to
+`Unreleased`.
+
+**STOP gate:** Verify `CHANGELOG.md` exists in the repo root using the
+Read tool. If it does not exist, report "CHANGELOG.md not found at repo
+root." and halt.
+
+## Step 1 — Get today's date
+
+Run `date +%Y-%m-%d` and store the result as `TODAY`.
+
+## Step 2 — Draft entries from commits
+
+Run:
+
+```sh
+git log --oneline main..HEAD
+```
+
+Store the result as `COMMIT_LIST`. If the command fails, report the error and halt.
+
+**STOP gate:** If `COMMIT_LIST` is empty, tell the user: "No commits found ahead of `main` — nothing to changelog. Is that expected?" and halt.
+
+Draft changelog entries from `COMMIT_LIST`. Group them under `### Category` subheadings. Use the categories that best match the changes (e.g., `### New Skills`, `### PDCA Framework Redesigns`, `### Beads and Workflow`, `### Build and Distribution`, `### Dependency Updates`, `### Documentation`). Prefer the established category names from the existing changelog over inventing new ones.
+
+Classify each entry as one of:
+
+- **Regular entry** — new feature, bug fix, config change, anything user-visible
+- **Migration note** — anything requiring user action: renamed files or commands, removed options, changed install paths, new required config keys
+
+Skip internal-only changes (refactors, test additions, CI tweaks) that are not user-visible — do not propose entries for them.
+
+## Step 3 — Review with user
+
+**STOP gate:** If no entries were drafted, halt without writing — do not create an empty heading.
+
+Print the proposed changelog block in chat. If VERSION is `Unreleased`,
+the heading will be `## Unreleased`; if a version was provided, it will
+be `## VERSION (TODAY)` (e.g., `## v1.2.0 (2026-06-01)` — substitute
+the actual bound values). Below the block, print `COMMIT_LIST` under a
+`**Commits for reference:**` label.
+
+Ask: "Does this look right? (yes / no / paste edits)"
+Wait for the response before continuing.
+
+- If yes: proceed to Step 4.
+- If no: halt without writing.
+- If the user provides edited text: replace the draft with their version,
+  then proceed to Step 4.
+
+## Step 4 — Write the entries
+
+On confirmation, write the entries to `CHANGELOG.md`.
+
+**If VERSION is `Unreleased`:**
+- If no `## Unreleased` heading exists, insert one at the top of the changelog body (below any `# Title` line), followed by a `---` separator before the first pre-existing versioned section.
+- If `## Unreleased` already exists, append the new category subheadings and entries to it; do not create a duplicate heading.
+
+**If VERSION is a version number (e.g., `v1.2.0`):**
+- If no `## Unreleased` heading exists, insert a new `## VERSION (TODAY)`
+  heading at the top of the changelog body (e.g., `## v1.2.0 (2026-06-01)`).
+- If `## Unreleased` exists, rename it to `## VERSION (TODAY)` rather
+  than creating a duplicate.
+
+**New `## Unreleased` section** (none exists yet):
+
+```markdown
+## Unreleased
+
+### New Skills
+- My new skill
+
+### Migration Notes  ← omit this subsection if there are no migration notes
+- Thing the user must do manually
+
+---
+
+## v1.1.0 (2026-05-28)  ← existing versioned section follows the --- separator
+```
+
+**Appending to an existing `## Unreleased` section:**
+
+```markdown
+## Unreleased
+
+### New Skills
+- Earlier entry
+- My new skill  ← append here
+
+### PDCA Framework Redesigns
+- My change  ← add new category subheading if not present; append if already present
+
+### Migration Notes  ← add subsection if not present; append if already present
+- Thing the user must do manually
+```
+
+**Versioned heading** (cutting a release):
+
+```markdown
+## v1.2.0 (2026-05-27)
+
+### New Skills
+- My feature
+
+### Migration Notes  ← omit if none
+- Thing the user must do manually
+```

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### New Skills
+- **update-changelog**: New skill that drafts changelog entries from commits ahead of `main`, groups them by category, shows a preview, and writes to `CHANGELOG.md` (or a named changelog file) only after user confirmation.
+
+### Documentation
+- Add `CONTRIBUTING.md`: contribution workflow, issue filing guidance,
+  PDCA process, commit style, master prompt validation steps, and PR
+  checklist including changelog format and version bump guidance
+
+### Repository Changes
 - Renamed `claude-skill/` to `skill/` and added Codex installation support via `~/.agents/skills/pdca-framework`.
 
 ---
@@ -11,6 +20,7 @@
 ### Repository Split
 - **human-directed-ai-workflow-builder** moved to its own repository: [kenjudy/human-directed-ai-workflow-builder](https://github.com/kenjudy/human-directed-ai-workflow-builder). Removed `5. Scaffold/`, `claude-skill/pdca-scaffold/`, `claude-skill/build-scaffold.sh`, `plugins/pdca-scaffold/`, `scaffolded-skills/`, and `presentations/` from this repo.
 
+
 ---
 
 ## v1.1.0 (2026-05-28)

CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to PDCA Framework
+
+Thank you for your interest in contributing. This project uses a
+human-supervised PDCA (Plan–Do–Check–Act) cycle for all code generation,
+and we ask that contributions follow the same discipline.
+
+## Contents
+
+- [Development Setup](#development-setup)
+- [AI-Assisted Contributions](#ai-assisted-contributions)
+- [Filing Issues](#filing-issues)
+- [Contribution Process](#contribution-process)
+- [Commit Style](#commit-style)
+- [Changing Master Prompt Files](#changing-master-prompt-files)
+- [Pull Requests](#pull-requests)
+- [License](#license)
+
+---
+
+## Development Setup
+
+```sh
+cd claude-skill
+uv sync            # install dependencies
+bash run-tests.sh  # build skill, run ruff + mypy + pytest
+```
+
+Eval tests require an `ANTHROPIC_API_KEY` and cost ~$2–5 per run:
+
+```sh
+uv sync --extra eval
+bash run-evals.sh
+```
+
+See `claude-skill/README.md` for full details.
+
+## AI-Assisted Contributions
+
+All changes that can be test-driven must be, regardless of whether the
+implementer is human or AI. A human must be present and approving at
+each PDCA gate. The human supervision protocol in `Agent.md` applies to
+all code contributions.
+
+For changes to the skill's code or prompts, we recommend using the
+pdca-framework skill itself to guide your session — we use it to build
+itself. Documentation changes don't require it.
+
+## Filing Issues
+
+Open a GitHub issue before starting any non-trivial change. Describe what
+you want to fix or add and, if you have one, your proposed approach. Wait
+for a response before writing code — this prevents duplicate work and lets
+the maintainer flag any design concerns early.
+
+Bug reports and feature requests without a corresponding PR are also
+welcome. If you are not sure whether something is worth pursuing, open an
+issue and ask.
+
+## Contribution Process
+
+All contributions follow the PDCA cycle:
+
+1. **Plan** — open an issue (see above); describe the problem and your
+   proposed approach. Wait for feedback before proceeding.
+2. **Do** — implement using TDD: write a failing test first, and then make
+   it pass. One failing test at a time, no exceptions.
+3. **Check** — run the full test suite (`bash run-tests.sh`). For
+   changes to master prompt files, run the affected eval classes and
+   confirm that no previously-passing scenarios regress (see below).
+4. **Act** — open a PR with a summary of what changed and why.
+
+## Commit Style
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```txt
+feat: add X
+fix: correct Y
+docs: update Z
+refactor: rename W
+chore: bump dependency
+```
+
+- Subject line ≤ 50 characters. Imperative mood. No period at the end.
+- Scope tags (e.g., `feat(scope):`) are optional.
+
+## Changing Master Prompt Files
+
+Changes to `1. Plan/`, `2. Do/`, `3. Check/`, or `4. Act/` require eval
+validation before the PR can merge:
+
+1. Record baseline scores from the most recent report in
+   `claude-skill/eval/results/`.
+2. Make one discrete change; rebuild: `bash claude-skill/build-skill.sh`.
+3. Run only the affected eval class:
+
+   ```sh
+   cd claude-skill && bash run-evals.sh tests/test_evals.py::TestPrompt2Evals
+   ```
+
+   See `Agent.md` for the full phase → eval class mapping.
+
+4. All previously passing scenarios must still pass. Do not submit a PR
+   that regresses a passing scenario.
+
+## Pull Requests
+
+- Keep PRs focused on a single concern.
+- Include the test(s) that cover your change in the same commit.
+- Add an entry to `CHANGELOG.md` (repo root) under an `## Unreleased`
+  section. Group entries under a `### Category` subheading (e.g.,
+  `### New Features`, `### Bug Fixes`, `### Build and Distribution`).
+  If you are using Claude Code, run `/update-changelog` to draft entries
+  from your commits and write them to the file automatically.
+  If your change requires any action from existing users (renamed files,
+  changed install paths, removed options), add a `### Migration Notes`
+  subsection.
+- Reference the issue your PR addresses.
+
+Version numbers are assigned by the maintainer at release time. Do not
+bump the version in `claude-skill/README.md` yourself unless you are
+cutting a release.
+
+Dependency bump PRs are handled automatically by Dependabot. No manual
+contribution needed.
+
+## License
+
+By contributing, you agree that your work will be released under the
+[Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/)
+license that covers this project.