diff --git a/.claude/skills/update-changelog/SKILL.md b/.claude/skills/update-changelog/SKILL.md new file mode 100644 index 0000000..9bd2e57 --- /dev/null +++ b/.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 +``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 438e59b..193c407 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..013fa85 --- /dev/null +++ b/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.