Files
plan2code/src/plan2code-init.md
T

138 lines
8.2 KiB
Markdown
Raw Normal View History

2025-12-23 15:42:35 -08:00
# 💡 CREATE AGENTS MODE
Start all CREATE AGENTS MODE responses with '💡'
2026-01-27 12:11:00 -08:00
```
⋅
╭───╮
│ ★ │╱
╱│ ◡ │ Let me explore your codebase!
╰┬─┬╯
2026-01-27 12:11:00 -08:00
```
Analyze this codebase and create `AGENTS.md` to guide future AI coding agents (Claude Code, Codex, Devin, Zed, etc.).
2025-12-23 15:42:35 -08:00
## Interface
The FIRST thing you do, before anything else in this file — before exploring the codebase: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow init` before reading (<D>: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-init/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md and <D>/notes/init.md. Every confirmation — the restructure offer, the AI-agent file-sync prompt — goes through it, and the finished AGENTS.md lands on the page as a doc marked `saved` (the file is already on disk — no download offered). Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Content.
## Scripts
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-init/scripts/` globally). Run from the project root; each prints one JSON object, and on a non-zero exit `next` says what to do.
- `node "<S>/agents-md.mjs" inspect`: does AGENTS.md exist, its line count against 500, `structure` (`progressive` or `single-file`), sections, `.agents-docs/` files, broken links, orphans. Run it first.
- `node "<S>/agents-md.mjs" filename "<Section Name>"`: a section's detail file name, its `Details:` link line and its two header lines.
- `node "<S>/agent-files.mjs" detect` / `apply <id> ... [--dry-run]`: AI Agent File Sync (below).
2026-02-17 09:13:23 -08:00
## Content
2025-12-23 15:42:35 -08:00
1. **Commands**: Build, lint, test, run single test (and beside it a short **Test map**: `area -> tests or command` lines saying which tests cover which areas, plus a note of which checks are quick; omit it when the project has no tests), other common development tasks, and how to start the app and where to view it (URL or command), when it has one
2026-02-17 09:13:23 -08:00
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.
2026-08-12 13:15:50 -07:00
4. **Failure Log**: running list of mistakes and/or corrections that went wrong via the AI Agent at least once.
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
## Rules
2025-12-23 15:42:35 -08:00
- If `AGENTS.md` exists (`inspect` → `exists`): suggest improvements instead of creating new
- If only `CLAUDE.md` exists (`inspect` → `otherFiles`): migrate its content to the new `AGENTS.md`
2026-02-17 09:13:23 -08:00
- Include relevant content from: `README.md`, `PROJECT.md`, `.cursorrules`, `.cursor/rules/`, `GEMINI.md`, `.github/copilot-instructions.md`
- Omit: obvious instructions, generic dev practices, easily discoverable file structures, made-up sections
- Keep under 500 lines with focused, actionable, scoped rules
Prefix the file with:
2025-12-23 15:42:35 -08:00
```
# AGENTS.md
2026-08-12 13:15:50 -07:00
This file provides guidance to AI coding agents working with code in this repository.
2025-12-23 15:42:35 -08:00
```
## Helpers
When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a `Subagents:` block says which, console-subagents.md):
- **Mapping the project:** one area per helper; each reports what the area holds, how it builds and runs, and the conventions it follows, with `file:line` where it matters.
Keep with you: every question, the judgment on what matters and the writing of AGENTS.md and its notes. Strength and effort per references/helper-strength.md. No helpers? Do the same work yourself.
2026-01-27 12:11:00 -08:00
---
2026-03-01 12:24:11 -08:00
## Progressive Discovery
Generate AGENTS.md as an **index file** — each section gets a 2-3 line summary with a markdown link to a detail file. Full content goes in `.agents-docs/` directory files.
- **Index format** — each section in AGENTS.md: heading, brief summary, then its `Details:` link line
- **Detail files** — `agents-md.mjs filename "<Section Name>"` gives the file (`AGENTS-<kebab-case>.md`, e.g. "Development Commands" → `.agents-docs/AGENTS-development-commands.md`), the `Details:` link and the two header lines (`# <Section Name>` plus the "Part of AGENTS.md" breadcrumb) to start it with
2026-03-01 12:24:11 -08:00
### Always Inline
These sections must remain fully inline in AGENTS.md (never split to separate files):
- Project Overview
- How to Use This File
2026-08-12 13:15:50 -07:00
- 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:
2026-08-12 13:15:50 -07:00
```
## 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.
2026-08-12 13:15:50 -07:00
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
2026-08-12 13:15:50 -07:00
1. Add one line to the `Failure log` below, in the imperative, describing the correct behavior.
2026-08-12 13:15:50 -07:00
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.
5. A rule broken twice becomes an automated check (a test, a lint rule or a script), not more prose.
6. Before adding a line, look for one on the same topic: sharpen or extend that one rather than adding a near-duplicate.
7. Keep the log to 17 entries at most. Over the cap, first merge entries that share a cause, then drop the lowest-value ones: one-offs unlikely to recur, rules a test or script now enforces, and entries about code that no longer exists.
2026-08-12 13:15:50 -07:00
## Failure log
-
```
2026-03-01 12:24:11 -08:00
### Directory Setup
- Create `.agents-docs/` directory in the project root, one file per split section, named and headed as `filename` prints
- After writing, rerun `inspect`: `problems` must be empty (no broken link, no orphan, no missing breadcrumb, nothing always-inline split out)
2026-03-01 12:24:11 -08:00
### Grouping Heuristics
- Combine related subsections into a single detail file (e.g., "Architecture" with its subsections → one file)
- Sections under ~10 lines of content should stay inline in AGENTS.md rather than being split out
- Decide grouping dynamically based on the project's actual content — heuristics guide, not prescribe
### Existing AGENTS.md Without `.agents-docs/`
If `inspect` reports `structure: "single-file"`, offer to restructure: "Your AGENTS.md uses a single-file format. Want to restructure it for progressive discovery? This splits detailed sections into `.agents-docs/` files and converts AGENTS.md to a lightweight index." Only restructure if the user confirms — never auto-restructure.
2026-03-01 12:24:11 -08:00
---
2026-01-27 12:11:00 -08:00
## AI Agent File Sync
After creating `AGENTS.md`, run `agent-files.mjs detect`. It finds `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`, and the `.cursor/rules/` and `.windsurf/rules/` folders, with each one's line count and `custom` (more than 10 lines). Leave out entries with `alreadyPointer: true` (already the AGENTS.md pointer) and `linkedToAgents: true` (a symlink or hard link: they are AGENTS.md); nothing left: skip this step silently.
2026-01-27 12:11:00 -08:00
2026-02-17 09:13:23 -08:00
### Confirmation Prompt
2026-01-27 12:11:00 -08:00
2026-02-17 09:13:23 -08:00
If files found, show:
2026-01-27 12:11:00 -08:00
```
⋅
╭───╮
│ ★ │╱
╱│ ~ │ Found some other AI agent configs!
╰┬─┬╯
2026-01-27 12:11:00 -08:00
I found these AI agent configuration files:
- [each `found` id, with its line count]
2026-01-27 12:11:00 -08:00
Update them to reference AGENTS.md? (Yes / Select / No)
```
Relay every `warnings` line (custom content that would be replaced). A rules folder is one entry: replacing it deletes its `.md` files (and `.mdc` for Cursor) and leaves one `reference.md`.
2026-01-27 12:11:00 -08:00
Only modify confirmed files: `agent-files.mjs apply <id> ...` with the ids the user confirmed (`--all` for Yes). It writes the pointer templates itself: `CLAUDE.md` gets the `CRITICAL — MANDATORY FIRST STEP` directive that makes Claude Code read AGENTS.md first (it auto-loads CLAUDE.md); every other file gets the "See AGENTS.md for complete project documentation including:" pointer with the same bullet list and the right relative path. Rerunning is harmless (`unchanged`).