Compare commits

..
76 Commits
Author SHA1 Message Date
jparkerweb 4cbf426df2 v2.1.1 - Failure Log convention in the init prompts 2026-08-12 13:54:43 -07:00
jparkerweb 8a8cc14e0d update init instructions 2026-08-12 13:15:50 -07:00
jparkerweb 1907281b40 Add a GitHub Issues backend to Pathfinder
Chart Step 1 now asks where the map should live: local files under
gitignored specs/ (the default) or a pathfinder:map issue whose decision
questions are its sub-issues, driven by gh. The pick is recorded as the
first Ground rules bullet and never re-asked; Auto-Discovery resolves
either backend, and an issue URL routes straight to github.

On github the local model maps onto the tracker's own primitives rather
than being simulated in issue bodies: sub-issues, native issue
dependencies for blocking, the assignee as the claim, one
pathfinder:<type>-<mode> label so type and mode cannot drift, and an
Answer comment plus a close reason that distinguishes a decision from a
question ruled out of scope. Both wiring calls key on the database id,
not the number. The map body therefore carries no checklist at all.

Sketches, secrets and the PLAN-DRAFT stay on local disk regardless --
plan2code-1-plan discovers its input with ls specs/ and has no notion of
a tracker. github is only offered after a five-check preflight, and the
offer names the repo's visibility, because a map on a public tracker
publishes the destination and the codebase recon. The Step 3 recon is
held until Step 6 so the no-fog off-ramp leaves no litter.

Depth lives in a seventh reference file; the orchestrator was
recompressed to absorb the new section within the 11,000 char limit by
removing duplication with its references. Adapted from the GitHub
tracker doc behind Matt Pocock's wayfinder skill (MIT).

AI Assisted
2026-08-08 19:00:26 -07:00
jparkerweb cf9fe6d80f Point plan2code-bot at the GitHub repo URL
AI Assisted
2026-08-08 12:39:52 -07:00
jparkerweb 0c17ef1454 Release v2.0.0
Ports upstream v1.17.0 and v2.0.0. Breaking: Gemini CLI is no longer an
install target. Adds Pathfinder Step 0, community feedback submission and
ingestion, and Devin CLI as an agent backend.

AI Assisted
2026-08-08 12:39:37 -07:00
jparkerweb 0767c6b4c7 Update the Claude Code status line
AI Assisted
2026-08-08 12:39:29 -07:00
jparkerweb b78b3cd6a3 Document Pathfinder and community feedback across the contributor docs
Moves the README's deep material into .readme/ (walkthrough, autonomous
loop, status line, metrics, test bot) and brings AGENTS.md, the .agents-docs
set and QUICK-REFERENCE.md in line with Step 0 and the metrics ingestion
flow.

AI Assisted
2026-08-08 12:39:29 -07:00
jparkerweb 474c76e564 Ingest community feedback submissions in plan2code-metrics
Adds a CLI flow that lists open community-feedback issues via gh, validates
and parses each METRICS_JSON payload, imports them deduped by run_id,
re-aggregates and closes the issue. Community runs cohort by Plan2Code
version rather than prompt fingerprint, and local cohorts stay preferred so
ingested feedback never displaces the maintainer's current generation. Adds
Devin CLI as an AI backend.

AI Assisted
2026-08-08 12:39:28 -07:00
jparkerweb 161e424632 Add Devin CLI as a selectable agent backend in plan2code-loop
Upstream replaced GitHub Copilot CLI with Devin; Plan2Code keeps both, so
Claude Code, Copilot CLI and Devin are all selectable and existing Copilot
selections keep working.

AI Assisted
2026-08-08 12:39:28 -07:00
jparkerweb 09aa565559 Drop Gemini CLI as an install target and register Pathfinder
Removes the .gemini/commands/*.toml surface and the build-time inlining it
required; every remaining target resolves reference directives at runtime.
The uninstall entry is retained behind an uninstallOnly flag so .toml files
from earlier versions can still be cleaned up.

AI Assisted
2026-08-08 12:39:13 -07:00
jparkerweb 0501260098 Add Pathfinder as an optional Step 0 and offload prompt depth to references
Pathfinder charts an idea that is too big to plan as a map of decision
questions under specs/<idea>/pathfinder/, clearing one per session until it
can hand a PLAN-DRAFT to Step 1. Finalize now archives pathfinder/ with the
spec and revise-plan no longer deletes it — both previously described the
cleanup target in wording that pointed at questions/. Init-update Step 7 and
review Session End move to reference files with inline fallbacks.

AI Assisted
2026-08-08 12:39:13 -07:00
jparkerweb 48a7cf68bd Pin LF line endings and renormalize the working tree
scripts/validate-char-count.js measures characters on disk, so a CRLF
checkout added ~1 char per line and pushed the 11k-budget prompt files over
the limit depending on how the repo was cloned. Pins eol=lf, marks binaries,
and renormalizes the files that had CRLF.

AI Assisted
2026-08-08 12:38:58 -07:00
jparkerweb 30860a7654 Redesign docs site and README around an airmail postcard theme
Adds a postage-stamp favicon set and banner, removes three orphaned images,
and records the site and README as protected divergences so an upstream sync
can't revert them.

AI Assisted
2026-08-08 12:32:17 -07:00
jparkerweb fda0146969 URL updates 2026-08-01 13:04:39 -07:00
jparkerweb 75605e5e41 update URLs 2026-08-01 12:56:52 -07:00
jparkerweb 3b18b42e30 Merge pull request #3 from jparkerweb/statusline-worktree
Add git worktree awareness to status line (v1.16.1)
2026-07-31 22:24:02 -07:00
jparkerweb 8e457fa6e4 Bump to v1.16.1 for status line git worktree awareness 2026-07-31 22:20:38 -07:00
jparkerweb 6740e26261 Add git worktree awareness to status line
Sessions in a linked worktree previously showed only the worktree's
directory name, so the underlying repository was unidentifiable and the
session looked like an unrelated project.

The project segment now renders as "repo | worktree". Repo identity comes
from git rev-parse --git-common-dir, so it is correct regardless of how the
worktree directory was named. A leading repo prefix is stripped from the
worktree name, and the name collapses to a bare marker when it merely
restates the branch already on screen -- matched across / _ . - separators
and type prefixes like feature/, and only when the branch is displayed.

Gated behind the new items.worktree config flag (default on). Costs one
extra timeout-bounded git call, skipped entirely outside git repos.
2026-07-31 22:20:38 -07:00
jparkerweb aedfe944b2 Merge pull request #2 from jparkerweb/handoff
Release v1.16.0: install handoff skill, add publish skill, sync upstream
2026-07-20 22:39:25 -07:00
jparkerweb 9b3c06b498 Address PR review feedback: update step label + release-list limit 2026-07-20 22:36:35 -07:00
jparkerweb 8fe1bfa805 Set v1.16.0 releaseDate to 2026-07-20 2026-07-20 22:33:24 -07:00
jparkerweb 68542fd778 Release v1.16.0: install handoff skill, add publish skill, sync upstream
- Make plan2code-handoff an installed workflow prompt: move to src/,
  register in install.js SOURCE_PROMPTS, remove repo-local-only copy
- Add repo-local maintainer /plan2code-publish skill (cuts GitHub Releases;
  excluded from install.js)
- Review workflow next-step suggestion made context-aware (upstream v1.15.4)
- Doc updates: list handoff in README, QUICK-REFERENCE, architecture table;
  add "Adding a New Workflow Prompt / Skill" checklist to dev-commands
- Fix broken AGENTS.md index links: rename .agents-docs loop/metrics files
  to plan2code-* to match references
- Bump version.json to 1.16.0 to align with package.json and CHANGELOG
2026-07-20 22:31:37 -07:00
jparkerweb 4656a6ebb7 Merge pull request #1 from jparkerweb/handoff
Add plan2code-handoff skill for conversation handoff documents
2026-07-20 22:09:45 -07:00
jparkerweb 7e9de755f1 Add plan2code-handoff skill for conversation handoff documents
AI Assisted
2026-07-20 22:07:21 -07:00
jparkerweb 4b20f93bb9 Bump to v1.15.4 for status line reasoning effort and context token count
AI Assisted
2026-07-19 21:22:54 -07:00
jparkerweb 5b3b84f0a9 Add reasoning effort label and context token count to status line
AI Assisted
2026-07-19 21:18:10 -07:00
jparkerweb 1015b99a6a Sync upstream workflow improvements (v1.15.3): session-end summaries, Sync & Maintain in init-update, plan research steps, ls-based spec discovery, revision/commit guardrails; bump version to v1.15.3
AI Assisted
2026-06-28 11:46:40 -07:00
jparkerweb 20a9e2f040 sync update 2026-06-01 20:44:05 -07:00
jparkerweb 28bda05cbf Stop ignoring CLAUDE.md
AI Assisted
2026-06-01 19:42:19 -07:00
jparkerweb 5274bdbd51 Add password-protected sync-repo skill with encrypted body
Adds a project-local /sync-repo skill whose real instructions are encrypted
at rest (AES-256-GCM + scrypt) in sync-repo.enc and only revealed in-session
after the user supplies the correct passphrase. Plaintext SYNC.md is gitignored
and never committed; *.enc is marked binary to protect the ciphertext bytes.

AI Assisted
2026-06-01 19:41:34 -07:00
jparkerweb 25d874d87d v1.15.2 — add Claude CLI status line, Zed support, rename 3b-review to review
- Status line: new src/statusline-claude/ (Planny box-star mascot icon),
  install/uninstall wiring in install.js, Install All (A) + Custom (S)
- Zed agent support across README, AGENTS, docs, init prompt, installer
- Rename /plan2code-3b-review to /plan2code-review (now a standalone
  utility workflow); update file, reference dir, and all cross-references
- install.js: fs.rmSync simplifications, async install, summary cleanup
- Bump to v1.15.2; CHANGELOG entries for v1.15.0/1/2
2026-06-01 16:39:35 -07:00
jparkerweb 5e48e98293 v1.14.0 — add Step 3b review workflow, unify file naming, resilient code references
- Add /plan2code-3b-review: 5-step post-implementation review with adaptive
  scope, 11 dimensions, reference-file architecture, and Plan/Apply/Verify fixes
- Unify workflow/skill file naming to single-dash (drop -- and --- conventions)
- Add Devin platform support and CLAUDE.md MANDATORY FIRST STEP template
- Guide agents to use semantic anchors over line numbers in workflow prompts
- Bump version to 1.14.0
2026-05-23 06:58:20 -07:00
jparkerweb 8e0b1a2ab2 v1.11.1 — installer 'A' option and bot evaluation notes
- install.js: split into 'I' (prompts + loop) and new 'A' (everything
  including bot + metrics); update prompt to (I, A, U, C, Q).
- CHANGELOG: document complexity check (1.11.1) and expand 1.11.0
  notes for the LLM-as-judge evaluation system.
- version.json: 1.10.0 -> 1.11.1.
2026-05-11 13:14:35 -07:00
jparkerweb c2579a7b6a plan2code-bot: replace auto-responder with LLM-as-judge evaluation
Bot now acts as an authentic QA agent instead of rubber-stamping every
question and step.

- intelligent-responder answers AskUserQuestion via LLM using current
  observations (tools used, files created, errors) instead of keyword
  matching; auto-responder removed.
- evaluator runs after each step with step-specific criteria
  (prompts/evaluation-criteria.ts), produces 0-100 score plus
  strengths/weaknesses/critical issues. Avg <60 blocks finalization.
- observation-collector captures tool_use, file writes, errors, and
  question reasoning; session-runner falls back to scraping tool_use
  blocks when canUseTool doesn't fire and dedupes both sources.
- Bot writes BOT-EVALUATION.md and BOT-NOTES.md for metrics analysis.
- Idea generator: 12 categories instead of CLI/web-app coin flip,
  stronger seed adherence, less developer-tool bias.
- Init step now writes a minimal AGENTS.md stub instead of running
  the full init skill, avoiding hallucinated architecture before plan.
- Implement step uses Read/Write/Edit/Glob/Grep directly instead of
  a Skill sub-session that produced no visible tool observations.
- bin: add --help, accept --idea="value" form, strip surrounding
  quotes; evaluator maxTurns 3 -> 30; warn when parser misses SCORE.
2026-05-11 13:14:28 -07:00
jparkerweb 9d1104d105 metrics: adopt METRICS_JSON HTML comment as primary format
Plan, document, and finalize prompts now emit a single
<!-- METRICS_JSON {...} --> block with all structured fields. Collector
parses these directly and keeps the old prose/table parsing as fallback.

Also adds a per-task complexity check to the document prompt:
split tasks with 3+ complexity signals (5+ logic branches, 2+
integration points, shared interface mutation, etc.), combine
adjacent trivial tasks.
2026-05-11 13:14:15 -07:00
jparkerweb 72fed09aab prompts: drop Git Commit Messages section from AGENTS.md and init flows
Project-specific commit conventions don't belong in the generic init
templates. AGENTS.md, init, and init-update no longer mention or audit
a Git Commit Messages section.
2026-05-11 13:14:08 -07:00
jparkerweb 37311a7e68 v1.11.0 — add plan2code-bot to root changelog 2026-03-01 21:33:57 -08:00
jparkerweb c92865c395 feat: add plan2code-bot with --resume capability and state cleanup
Add the autonomous workflow test runner (plan2code-bot) that uses the
Claude Agent SDK to run plan2code end-to-end. Includes --resume flag
to continue incomplete runs from saved state, and automatic state file
cleanup on successful completion.
2026-03-01 21:30:45 -08:00
jparkerweb 63656d339d v1.10.0 2026-03-01 12:24:11 -08:00
jparkerweb 628e688ab9 Planny hit the gym and lost some weight
Trimmed the mascot ASCII art across all prompts and installer.
Planny is now more aerodynamic and 40% less chunky.
2026-02-22 21:48:13 -08:00
jparkerweb 157e55ef2e docs: update AGENTS.md with plan2code-metrics section and corrections
- Add plan2code-metrics to architecture tree, dev commands, installer menu
- Add full metrics section (data flow, CLI menu, key files, feedback format, metric targets)
- Fix Code Style: split install.js (CommonJS) vs loop/metrics (TypeScript+ESM)
- Update finalize prompt description to reflect 7 steps
- Add metrics-specific gotchas (internal prompts, feedback table format)
2026-02-22 21:47:45 -08:00
jparkerweb 02fd4efa40 v1.8.1 — add user feedback collection to plan2code-metrics 2026-02-22 21:41:16 -08:00
jparkerweb 348c8ed7b2 feat: add user feedback collection to plan2code-metrics
- Add UserFeedback type (rating 1-10, reason, went well, went poorly)
- Collector parses ## User Feedback table from overview.md
- Aggregator computes avg_user_rating and feedback_count per cohort
- CLI offers interactive feedback collection with pipe-safe escaping
- Finalize prompt collects optional feedback as Step 5 (before archival)
- Analysis/improvement prompts reference avg_user_rating metric target
2026-02-22 21:38:58 -08:00
jparkerweb 5c2f70a37c v1.8.0 — add plan2code-metrics recursive self-improvement toolchain
New package for contributors to collect, aggregate, analyze, and improve
workflow prompts based on real project data. Includes unit tests (vitest),
installer integration, and loop/finalize hints.
2026-02-22 19:57:40 -08:00
jparkerweb de46275b51 v1.7.0 2026-02-22 12:58:08 -08:00
jparkerweb b7b2595fe1 v1.6.1 2026-02-18 15:16:11 -08:00
jparkerweb 6f98f6bd7f v1.5.4 2026-02-17 09:13:23 -08:00
jparkerweb 035cc680a7 spacing 2026-02-03 20:32:18 -08:00
jparkerweb 34704eaf84 v1.5.2 2026-01-27 12:11:00 -08:00
jparkerweb 474e591f58 v1.3.3: Learning Capture Protocol and improved session instructions 2025-12-31 13:07:27 -08:00
jparkerweb 6a6b4c6fac naming and prompt cleanup 2025-12-25 22:02:24 -08:00
jparkerweb b865b74cd0 docs 2025-12-25 21:45:41 -08:00
jparkerweb f8c7a96bc7 docs
Updated README to include new workflow details and installation instructions.
2025-12-25 21:45:05 -08:00
jparkerweb edee3fc65e docs 2025-12-23 17:23:23 -08:00
jparkerweb 9d67de78c8 improved build and install process 2025-12-23 15:42:35 -08:00
jparkerweb 2409e8dbfb Delete .windsurf directory 2025-12-22 09:11:18 -08:00
jparkerweb eaa9a633a0 Delete .github directory 2025-12-22 09:11:10 -08:00
jparkerweb 9a49ba09fb Delete .cursor directory 2025-12-22 09:11:00 -08:00
jparkerweb 7898ebf7ab Delete .continue directory 2025-12-22 09:10:49 -08:00
jparkerweb e33a67e269 Delete .claude directory 2025-12-22 09:10:40 -08:00
jparkerweb 92acc99b71 Delete .agent directory 2025-12-22 09:10:27 -08:00
jparkerweb 50c281f11f v1.0.4 - Added explicit transition check to Planning Phase 6 2025-12-07 17:52:40 -08:00
jparkerweb 5159b531ec v1.0.3 2025-12-05 21:44:21 -08:00
jparkerweb 0cee0f8962 v1.0.2 2025-12-05 15:41:23 -08:00
jparkerweb b2fdab6814 - Added Initial Context Check to Planning Phase 1 - Model now asks about additional files, reference materials, and external integrations before
analyzing requirements
- Added user verification checklist and git checkpoint to `Implementation Phase 3` - Phase completion reports now guide users through verification and git checkpointing before starting the next phase
2025-12-05 10:43:58 -08:00
jparkerweb f7da7d34c0 docs 2025-12-04 21:30:41 -08:00
jparkerweb 18321b62da docs 2025-12-04 20:51:05 -08:00
jparkerweb 495a5bb861 docs 2025-12-04 20:28:25 -08:00
jparkerweb d9f87a7eb1 update website 2025-12-04 20:23:33 -08:00
jparkerweb be41f3f1f8 Revise README for Plan2Code workflow updates
Updated the README to reflect changes in the Plan2Code workflow, including new file references and installation instructions.
2025-12-04 18:10:42 -08:00
jparkerweb 87167f54f4 docs 2025-12-04 18:09:23 -08:00
jparkerweb a4d15faba9 Create CNAME 2025-12-04 17:47:20 -08:00
jparkerweb 7a25084d25 Update and rename plan2code.html to index.html 2025-12-04 17:42:27 -08:00
jparkerweb d908a4d44c docs 2025-12-04 17:36:20 -08:00
jparkerweb 15911e970a v1.0.0 2025-12-04 17:34:22 -08:00
jparkerweb 4086c2e592 Initial commit 2025-12-02 20:59:19 -08:00
12 changed files with 279 additions and 11 deletions

No files matched your search

+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.
+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
+1 -1
View File
@@ -15,7 +15,7 @@ background processes.** Optional, and unrelated to the workflow itself.
On Pro / Max / Teams accounts, where rate limits are available:
```
◦ ◦ Opus 5 / high │ plan2code │ feature/pathfinder-github-iss │ +12 -3
◦ ◦ Opus 5 / high │ plan2code │ feature/PCWEB-11702-pathfinder │ +12 -3
╭●╮ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
├■┤ 3h 5m ($4.62) │ ▰▰▰▰▰▱▱▱▱▱▱▱ 42% (84K) │ 5h: 28% · 7d: 61%
```
+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.
+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
+14
View File
@@ -0,0 +1,14 @@
# CLAUDE.md
**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 complete project documentation including:
- Development commands and setup
- Architecture overview
- Workflow prompt reference
- Plan2Code Loop CLI details
- 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.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "plan2code",
"version": "2.1.0",
"version": "2.1.1",
"private": true,
"bin": {
"plan2code": "./install.js"
@@ -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`.
+28 -1
View File
@@ -48,6 +48,33 @@ Section files:
Wait for user response before continuing. If user accepts, restructure existing content: create `.agents-docs/` directory with section files, convert AGENTS.md to index with summaries and links. Always-inline sections (Project Overview, Git Commit Messages, How to Use This File) stay in AGENTS.md. If user declines, continue with single-file editing.
### Failure Log Audit
Check AGENTS.md for a `## Keeping this file current` section at the end of the file describing this format:
```
## 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
-
```
If the section is missing, flag it:
> "Your Keeping this file current section is missing. Want me to add it?"
If user confirms, add/update the section before proceeding. If user declines, continue.
Proceed to Step 2.
---
@@ -189,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`.
---
+27 -1
View File
@@ -17,6 +17,7 @@ Analyze this codebase and create `AGENTS.md` to guide future AI coding agents (C
1. **Commands**: Build, lint, test, run single test, and other common development tasks
2. **Architecture**: High-level "big picture" structure requiring multi-file context to understand
3. **How to Use This File**: A short paragraph explaining that sections below contain brief summaries and agents should follow the markdown links to `.agents-docs/` for full details — only read what's relevant to the current task.
4. **Failure Log**: running list of mistakes and/or corrections that went wrong via the AI Agent at least once.
## Rules
@@ -31,7 +32,7 @@ Prefix the file with:
```
# 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.
```
---
@@ -53,6 +54,29 @@ Generate AGENTS.md as an **index file** — each section gets a 2-3 line summary
These sections must remain fully inline in AGENTS.md (never split to separate files):
- Project Overview
- How to Use This File
- Keeping this file current / Failure log
### Failure Log section template
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 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
-
```
### Directory Setup
@@ -121,6 +145,7 @@ See AGENTS.md for complete project documentation including:
- 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.
@@ -137,5 +162,6 @@ See [AGENTS.md]([Path]) for complete project documentation including:
- Environment variables
- Testing patterns
- Deployment guides
- Keeping this file current / Failure log
- Section details in .agents-docs/
```
@@ -57,7 +57,7 @@ Run against EVERY finding. If any question raises doubt, re-investigate or drop.
**Finding survives (real bug):** Reviewer finds `processItems()` at line 47 accesses `items[0].id` with no empty-array check. Re-reads source — confirmed no guard. Traces callers — `orchestrator.js:82` can pass empty array. Adversarial check passes (correctness issue, additive fix). Presented at High.
**Finding dropped (jira skill false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (pcweb-jira false positive):** Reviewer recommends removing `jira-api-catalog.md` from consumer loading to "reduce context." Adversarial check: "Does my fix remove something the system depends on?" YES — agents Read these files at runtime to construct valid API calls. Four of five checks fail. Dropped.
**Finding dropped (false consolidation):** Reviewer flags per-platform config files as "duplicates." Adversarial check: "Am I optimizing for the wrong metric?" YES — platforms have distinct values and will diverge further. Separation is a design choice. Dropped.
+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"
}