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.
`<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.
1.**Commands**: Build, lint, test, run single test (and beside it a note of which checks are quick), other common development tasks, and how to start the app and where to view it (URL or command), when it has one. Then the **`## Test map`** section: run `node "<S>/test-commands.mjs" discover` and `node "<S>/test-map.mjs" read`. When test commands are found and no map exists, propose a `## Test map` table (`| Area | Paths | Run | Shared |`, one row per area with its own run command, `Shared: yes` for helper, fixture and config areas) for the person to approve, and write it only on a yes with `test-map.mjs write --rows <file>` (the rows file in the session folder or the OS temp folder, never the project). In a progressive `AGENTS.md`, the heading holds one link to `.agents-docs/AGENTS-test-map.md` and the table goes there. Omit the map when the project has no tests.
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.
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.
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
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.
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.
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.
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`.
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`).