From 8a8cc14e0d15e27c35475f7b4008b1039c13d9be Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Wed, 12 Aug 2026 13:15:50 -0700 Subject: [PATCH] update init instructions --- CLAUDE.md | 11 +++++++++++ src/plan2code-init-update.md | 27 +++++++++++++++++++++++++++ src/plan2code-init.md | 28 +++++++++++++++++++++++++++- 3 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f3fb2b3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,11 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +See [AGENTS.md](./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 diff --git a/src/plan2code-init-update.md b/src/plan2code-init-update.md index a23d3c9..a7ac233 100644 --- a/src/plan2code-init-update.md +++ b/src/plan2code-init-update.md @@ -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 make 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: + +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. --- diff --git a/src/plan2code-init.md b/src/plan2code-init.md index 84ae241..02a2058 100644 --- a/src/plan2code-init.md +++ b/src/plan2code-init.md @@ -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 `AGETNS.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. + +When you make a mistage, 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/ ```