jparkerweb/plan2code
1
0
Fork 0
mirror of https://github.com/jparkerweb/plan2code.git synced 2026-09-17 16:22:23 -07:00
Code Issues Packages Projects Releases Wiki Activity

v2.1.1 - Failure Log convention in the init prompts

Browse Source
This commit is contained in:
Justin Parker
2026-08-12 13:54:43 -07:00
parent 8a8cc14e0d
commit 4cbf426df2
10 changed files with 220 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents-docs/AGENTS-code-style.md
+3
View File
@@ -13,6 +13,9 @@
- **Version sync:** When adding a new version to `CHANGELOG.md`, also update `version.json` and `package.json` (root) to match. Check `README.md` for any version badges or references that need updating. The installer displays the version from `version.json` in its header. All three files (`CHANGELOG.md`, `version.json`, `package.json`) must always show the same version number.
- **CHANGELOG ordering:** Entries in `CHANGELOG.md` must be in reverse-chronological order — newest version at the top, oldest at the bottom. New entries are always inserted immediately after the file header.
- **CHANGELOG house format is not Keep a Changelog:** version headings are `## vX.Y.Z` — with a `v` prefix and **no date**. The release date is recorded only in `version.json`'s `releaseDate`. Category headings carry emoji: `### ✨ Added`, `### 🔧 Changed`, `### 🐛 Fixed`, `### 💥 Breaking`, `### 🗑️ Removed`, `### 📚 Documentation`. Older entries contain one-off variants (`🎁 Added`, `📦 Updated`, `📝 Documentation`, `🏎️ Improved`, `🧪 Testing`) — do not introduce new ones. The `.claude/skills/plan2code-changelog/` skill automates version selection and formatting; use it rather than hand-rolling an entry.
- **PowerShell mangles the CHANGELOG emoji:** `Get-Content` / `Select-String` render the `###` heading emoji as `?` under the default Windows console encoding, so a heading audit done that way reports garbage. Read `CHANGELOG.md` with a file-read or grep tool instead.
- **`.claude/skills/` is tracked, not ignored:** repo-local skills (`plan2code-changelog`, `plan2code-publish`, `sync-repo`) live there and are committed. Nothing in `.gitignore` touches `.claude/`, so a new skill only needs `git add`. Per the Failure Log convention in `AGENTS.md`, a correction that is a *workflow* rather than a rule belongs here as a skill, linked from AGENTS.md — not as a Failure log line.
- **Loop `.gitignore` setup:** `ensureGitignore()` runs at startup in `Controller.run()` as a pre-flight step, not just inside `createTaskCommit()`. This is critical for phase mode where the Node controller doesn't handle commits — without it, `git add -A` would stage spec files.
- **Workflow file character limit:** All `src/plan2code-*.md` files must be ≤ 11,000 characters. A husky pre-commit hook enforces this. The 11,000 limit leaves buffer for platform-specific YAML headers (106-142 chars) to stay under Windsurf's 12,000 char limit.
- **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 11,000 char limit — only `src/plan2code-*.md` consumer-facing prompts are.
.claude/skills/plan2code-changelog/SKILL.md
+149
View File
@@ -0,0 +1,149 @@
---
name: plan2code-changelog
description: "Validate and fix the CHANGELOG.md version number before opening a PR. Reads main branch to determine the current latest version, classifies changes on the current branch, and proposes the correct next semver. Use this skill when the user mentions changelog, version number, preparing a PR, release version, semver check, or says 'check the changelog', 'what version should this be', 'prepare for PR', or 'fix the version'. Also use proactively when you notice a CHANGELOG entry that may have an incorrect version number."
---
# Plan2Code Changelog Validator
Ensure the CHANGELOG.md entry for the current branch has the correct semver version before a PR is opened. This skill exists because parallel branches independently pick version numbers that collide or leap-frog when merged — this validates against main's actual state right before the PR.
## Workflow
### Step 1 — Gather state
Run these commands to understand the current situation:
```bash
# 1. Current latest version on main
git show main:CHANGELOG.md | head -20
# 2. Current branch name (for ticket ID extraction)
git branch --show-current
# 3. What this branch changed (commit subjects)
git log main...HEAD --oneline
# 4. Files changed on this branch
git diff main...HEAD --name-only
```
Extract from main's CHANGELOG:
- The **latest version number** (first `## vX.Y.Z` line)
Note: on Windows, PowerShell's console encoding mangles the emoji in the `###` headings to `?`. Read `CHANGELOG.md` with the file-read or grep tool rather than `Get-Content` / `Select-String` when you need to see them.
Extract from the branch:
- The **list of changed files** to classify the change type
- The **commit messages** for changelog entry content
### Step 2 — Classify the change
Determine the change type by examining what was modified on this branch:
| Signal | Classification | Version Bump | Heading |
|--------|---------------|--------------|---------|
| An install target removed, or an existing workflow's contract broken | Breaking change | **Major** (X.0.0) | `### 💥 Breaking` |
| New workflow prompt (`.md` file under `src/`) | New workflow | **Minor** (x.Y.0) | `### ✨ Added` |
| New capability added to an existing prompt, or a new `.claude/skills/` skill | New capability | **Patch** (x.y.Z) | `### ✨ Added` |
| Behavioral changes to existing prompt(s), installer, or docs | Behavior change | **Patch** (x.y.Z) | `### 🔧 Changed` |
| Bug fix to existing prompt(s) or tooling | Bug fix | **Patch** (x.y.Z) | `### 🐛 Fixed` |
| A prompt, target, or file deleted | Removal | **Patch** (x.y.Z) | `### 🗑️ Removed` |
| README / `.readme/` / docs-site only | Documentation | **Patch** (x.y.Z) | `### 📚 Documentation` |
| Mix of the above | Use the **highest** bump (major > minor > patch) | Combine headings |
Use only the headings in this table — the CHANGELOG has historical one-off variants (`🎁 Added`, `📦 Updated`, `📝 Documentation`, `🏎️ Improved`, `🧪 Testing`) that should not be introduced in new entries.
### Step 3 — Compute the correct version
Starting from main's latest version:
- **Major bump:** increment the first number, reset the rest (e.g., `1.16.1` → `2.0.0`)
- **Minor bump:** increment the middle number, reset patch to 0 (e.g., `2.0.0` → `2.1.0`)
- **Patch bump:** increment the last number (e.g., `2.1.0` → `2.1.1`)
### Step 4 — Check the current branch's CHANGELOG
Read the current `CHANGELOG.md` on the branch. Look for:
0. **You are on `main` with no diff** — there is no branch to validate. Instead, compare the top CHANGELOG version against `git log` since the commit that released it: if commits have landed on `main` without a CHANGELOG entry, treat those commits as the change set and continue from Step 2. Say so explicitly rather than reporting "nothing to do."
1. **No entry exists yet for this branch's work** — the branch hasn't added a version entry above main's latest. Proceed to Step 5 to draft one.
2. **An entry exists but the version is wrong** — the branch has a version entry, but it doesn't match the computed correct version (common when branches were rebased or other PRs merged first). Report the discrepancy:
```
Version check for branch: {branch-name}
Main is at: {main-version}
Branch claims: {branch-version}
Correct version: {computed-version} ({classification})
The version needs to be updated: {branch-version} → {computed-version}
```
Ask: "Update the version to {computed-version}? (yes / no)"
3. **An entry exists and the version is correct** — report success:
```
Version check for branch: {branch-name}
Main is at: {main-version}
Branch version: {branch-version} ({classification})
Version is correct. CHANGELOG is ready for PR.
```
Stop here unless the user asks for content changes.
### Step 5 — Draft or fix the CHANGELOG entry
**If no entry exists**, draft a new one based on the commits and changed files. Match this repo's house format exactly — a bare `## vX.Y.Z` heading with **no date**, emoji `###` headings from the Step 2 table, and a blank line between bullets:
```markdown
## {computed-version-with-v-prefix}
### ✨ Added
- **{prompt-or-area}** — {what changed, and why it matters to someone installing it}
### 🔧 Changed
- **{prompt-or-area}** — {what changed}
```
Conventions to follow, drawn from existing entries:
- Bold lead-in naming the prompt, file, or area, then an em dash (`—`), then the description.
- Reference prompts by their command (`/plan2code-1-plan`) or path (`src/plan2code-init.md`), not by informal name.
- One paragraph per bullet is fine — this CHANGELOG favours substantive entries over terse one-liners, and a bullet may carry extra indented paragraphs for detail.
- A release with a big theme may open with a one-line summary paragraph directly under the `## vX.Y.Z` heading, before the first `###`.
Insert the new section directly below the `All notable changes...` line and above the previous version's heading.
Present the draft and ask for approval before writing.
**If the version is wrong**, update only the version number — preserve the existing content unless the user asks for content changes too.
After any changes, show the final CHANGELOG entry for confirmation.
### Step 6 — Sync `package.json` and `version.json` versions
After writing or updating the CHANGELOG entry, update the `version` field in `package.json` at the repo root to match the computed version:
1. Read `package.json` and `version.json` then check the current `version` value.
2. If it already matches the computed version, skip — no change needed.
3. If it differs, update the `"version"` field in both files to the computed version (e.g., `"version": "2.1.1"`).
4. Set `releaseDate` in `version.json` to today's date in `YYYY-MM-DD`. This is the only place a date is recorded — the CHANGELOG headings carry no date.
5. Include `package.json` and `version.json` in the same commit as the CHANGELOG changes.
This keeps `package.json`, `version.json`, and `CHANGELOG.md` in lockstep so `npm pkg get version` always reflects the latest release.
## Rules
- Never create a version entry without checking main first — the whole point is to derive the version from main's current state
- Always present changes before writing — the user should see and approve the CHANGELOG entry
- Match the existing file's format — `## vX.Y.Z` with no date, emoji `###` headings. Do not introduce Keep a Changelog's `## [x.y.z] - date` style
- Write for someone reading the release notes, not for someone reading the diff — say what the change lets them do
- If multiple change types exist (Added + Changed), use multiple headings under the same version
- `version.json`'s `releaseDate` is today's date, i.e. when the release is being prepared, not when the work started
- If the branch has no meaningful changes vs main (e.g., only non-shipping files changed), say so and ask if a CHANGELOG entry is actually needed
AGENTS.md
+17 -2
View File
@@ -1,6 +1,6 @@
# AGENTS.md
This file provides guidance to AI coding agents like Claude Code (claude.ai/code), Cursor AI, Codex, GitHub Copilot, Devin, Zed, and other AI coding assistants when working with code in this repository.
This file provides guidance to AI coding agents working with code in this repository.
## Project Overview
@@ -12,7 +12,7 @@ Plan2Code is a structured 4-step workflow methodology for AI-assisted software d
## How to Use This File
This file is an index — each section below contains a brief summary and a link to a detail file in `.agents-docs/`. Read only the sections relevant to your current task. Full details (commands, tables, file lists) are in the linked files. The sections "Git Commit Messages" and "Project Overview" are fully inline here.
This file is an index — each section below contains a brief summary and a link to a detail file in `.agents-docs/`. Read only the sections relevant to your current task. Full details (commands, tables, file lists) are in the linked files. The sections "Project Overview", "How to Use This File", "Mascot", and "Keeping this file current" / "Failure log" are fully inline here and are never split into `.agents-docs/`.
## Architecture
@@ -60,3 +60,18 @@ The project has a mascot called "Planny" — an ASCII art robot that appears in
│ ◡ │
╰───╯
```
## Keeping this file current
The `Failure log` section below is a recording of mistakes made by previous AI Agents while working with this code base.
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
2. Keep it specific to this repo. General advice belongs nowhere.
3. If this fix is a workflow rather than a rule, put it in `.claude/skills/` and link it from here.
4. Include the change in the same commit and mention it in your summary.
## Failure log
- Do not audit `CHANGELOG.md` headings through PowerShell — the emoji come back as `?`. See the gotcha for the correct approach.
CHANGELOG.md
+20
View File
@@ -2,6 +2,26 @@
All notable changes to Plan2Code will be documented in this file.
## v2.1.1
### ✨ Added
- **Failure Log convention in the init prompts** — `/plan2code-init` now generates a `## Keeping this file current` / `## Failure log` pair at the end of `AGENTS.md`, so agents record repo-specific corrections as one imperative line each instead of relearning them. The section is always-inline (never split to `.agents-docs/`) and is listed in the generated `CLAUDE.md` pointer block. `/plan2code-init-update` gains a matching **Failure Log Audit** step that flags the section as missing on existing `AGENTS.md` files and offers to add it.
- **`plan2code-changelog` skill** (`.claude/skills/plan2code-changelog/`) — validates the CHANGELOG version before a PR is opened. Reads `main` for the current latest version, classifies the branch's changes to pick minor vs patch, and keeps `CHANGELOG.md`, `package.json`, and `version.json` in lockstep. Exists because parallel branches pick colliding version numbers independently.
### 🔧 Changed
- **`AGENTS.md` preamble shortened** in the init template — the generated header no longer enumerates specific agents (Claude Code, Cursor, Codex, Copilot, Devin, Zed) and reads "AI coding agents working with code in this repository."
- **`CLAUDE.md` added at the repo root** — a pointer file to `AGENTS.md`, matching what `/plan2code-init` now tells agents to generate.
- **`CLAUDE.md` template reconciled between the two init prompts** — `/plan2code-init` emitted the `CRITICAL — MANDATORY FIRST STEP` directive followed by a seven-item bullet list, while `/plan2code-init-update`'s Step 7 reference emitted the directive followed by a single prose line. Running one workflow after the other rewrote `CLAUDE.md` back and forth. `src/plan2code-init-update-references/ai-agent-file-sync.md` now carries the bullet-list form for both the `CLAUDE.md` and the generic reference template.
### 🐛 Fixed
- **Typos in the Failure Log template** — the template shipped in `src/plan2code-init.md` and `src/plan2code-init-update.md` said `AGETNS.md`, `mistage`, and "mistakes make by". Since agents copy this block verbatim into generated `AGENTS.md` files, the errors propagated into every project initialized with it.
## v2.1.0
### ✨ Added
CLAUDE.md
+6 -3
View File
@@ -1,11 +1,14 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
**CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.**
See [AGENTS.md](./AGENTS.md) for complete project documentation including:
See AGENTS.md for complete project documentation including:
- Development commands and setup
- Architecture overview
- Workflow prompt reference
- Plan2Code Loop CLI details
- Agent Failure Log
- Code style and gotchas
- Keeping this file current / Failure log
- Section details in .agents-docs/
This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md.
package.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "plan2code",
"version": "2.1.0",
"version": "2.1.1",
"private": true,
"bin": {
"plan2code": "./install.js"
src/plan2code-init-update-references/ai-agent-file-sync.md
+16 -2
View File
@@ -47,7 +47,14 @@ CLAUDE.md gets a special template because Claude Code auto-loads it — the `CRI
**CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.**
See AGENTS.md for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details.
See AGENTS.md for complete project documentation including:
- Development commands and setup
- Architecture overview
- Environment variables
- Testing patterns
- Deployment guides
- Keeping this file current / Failure log
- Section details in .agents-docs/
This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md.
```
@@ -59,7 +66,14 @@ Use title and path from the detection table:
```markdown
# [Title]
See [AGENTS.md]([Path]) for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details.
See [AGENTS.md]([Path]) for complete project documentation including:
- Development commands and setup
- Architecture overview
- Environment variables
- Testing patterns
- Deployment guides
- Keeping this file current / Failure log
- Section details in .agents-docs/
```
**For directory configs** (`.cursor/rules/`, `.windsurf/rules/`): Delete existing `.md` files, create single `reference.md`.
src/plan2code-init-update.md
+3 -3
View File
@@ -55,9 +55,9 @@ Check AGENTS.md for a `## Keeping this file current` section at the end of the f
```
## Keeping this file current
The `Failure log` section below is a recording of mistakes make by previous AI Agents while working with this code base.
The `Failure log` section below is a recording of mistakes made by previous AI Agents while working with this code base.
When you make a mistage, get corrected, or discover something about this codebase that wasn't written down:
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
2. Keep it specific to this repo. General advice belongs nowhere.
@@ -216,7 +216,7 @@ Check for other AI agent config files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`,
Read references/ai-agent-file-sync.md
> Fallback: for each detected file, offer Yes/Select/No to replace it with a pointer to AGENTS.md (warn when a file >10 lines has custom content that would be replaced). `CLAUDE.md` gets a special template opening with a `CRITICAL — MANDATORY FIRST STEP` directive to always read `AGENTS.md` (Claude Code auto-loads it); all other files get a short "See AGENTS.md for full project documentation" pointer using the correct relative path (`./`, `../`, or `../../` by location). For directory configs (`.cursor/rules/`, `.windsurf/rules/`), delete existing `.md` files and create a single `reference.md`.
> Fallback: for each detected file, offer Yes/Select/No to replace it with a pointer to AGENTS.md (warn when a file >10 lines has custom content that would be replaced). `CLAUDE.md` gets a special template opening with a `CRITICAL — MANDATORY FIRST STEP` directive to always read `AGENTS.md` (Claude Code auto-loads it); all other files get a "See AGENTS.md for complete project documentation including:" pointer with the same bullet list, using the correct relative path (`./`, `../`, or `../../` by location). For directory configs (`.cursor/rules/`, `.windsurf/rules/`), delete existing `.md` files and create a single `reference.md`.
---
src/plan2code-init.md
+3 -3
View File
@@ -58,14 +58,14 @@ These sections must remain fully inline in AGENTS.md (never split to separate fi
### Failure Log section template
When creating or modifying `AGETNS.md`, always ensure this section is included at the end:
When creating or modifying `AGENTS.md`, always ensure this section is included at the end:
```
## Keeping this file current
The `Failure log` section below is a recording of mistakes make by previous AI Agents while working with this code base.
The `Failure log` section below is a recording of mistakes made by previous AI Agents while working with this code base.
When you make a mistage, get corrected, or discover something about this codebase that wasn't written down:
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
2. Keep it specific to this repo. General advice belongs nowhere.
version.json
+2 -2
View File
@@ -1,6 +1,6 @@
{
"name": "Plan2Code",
"version": "2.1.0",
"version": "2.1.1",
"description": "A structured 4-step workflow methodology for AI-assisted software development",
"keywords": [
"ai",
@@ -17,6 +17,6 @@
"url": "https://github.com/jparkerweb/plan2code"
},
"homepage": "https://github.com/jparkerweb/plan2code",
"releaseDate": "2026-08-08",
"releaseDate": "2026-08-12",
"mode": "utility"
}