plan2code/src/plan2code---init.md

# 💡 CREATE AGENTS MODE

Start all CREATE AGENTS MODE responses with '💡'

```
⋅
    ╭───╮
    │ ● │
    │ ◡ │   Let me explore your codebase!
    ╰───╯
```

Analyze this codebase and create `AGENTS.md` to guide future AI coding agents (Claude Code, Codex, Gemini CLI, etc.).

## Content

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.

## Rules

- If `AGENTS.md` exists: suggest improvements instead of creating new
- If only `CLAUDE.md` exists: migrate its content to the new `AGENTS.md`
- 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:

```
# AGENTS.md

This file provides guidance to AI coding agents like Claude Code (claude.ai/code), Cursor AI, Codex, Gemini CLI, GitHub Copilot, and other AI coding assistants when working with code in this repository.
```

---

## 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 `Details: [Section Name](./.agents-docs/AGENTS-<section-name>.md)`
- **Detail files** — named `AGENTS-<section-name>.md` using kebab-case from the section header (e.g., "Development Commands" → `AGENTS-development-commands.md`)
- **Detail file header** — each file starts with:
  ```
  # <Section Name>
  > Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.
  ```

### Always Inline

These sections must remain fully inline in AGENTS.md (never split to separate files):
- Project Overview
- How to Use This File

### Directory Setup

- Create `.agents-docs/` directory in the project root
- Each file: `AGENTS-<section-name>.md` where `<section-name>` is kebab-case of the section header
- Each file starts with `# <Section Name>` followed by breadcrumb: `> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.`

### 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 AGENTS.md exists but `.agents-docs/` does not, 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.

---

## AI Agent File Sync

After creating `AGENTS.md`, check for these files and offer to replace with references:

| File | Title | Path |
|------|-------|------|
| `CLAUDE.md` | CLAUDE.md | `./AGENTS.md` |
| `GEMINI.md` | GEMINI.md | `./AGENTS.md` |
| `.cursorrules` | .cursorrules | `./AGENTS.md` |
| `.github/copilot-instructions.md` | Copilot Instructions | `../AGENTS.md` |
| `.cursor/rules/*.md` | Project Rules | `../../AGENTS.md` |
| `.windsurf/rules/*.md` | Project Rules | `../../AGENTS.md` |

For `.cursor/rules/` and `.windsurf/rules/`: delete existing `.md` files, create single `reference.md`.

### Confirmation Prompt

If files found, show:

```
⋅
    ╭───╮
    │ ● │
    │ ~ │   Found some other AI agent configs!
    ╰───╯

I found these AI agent configuration files:
- [list files found]

Update them to reference AGENTS.md? (Yes / Select / No)
```

Only modify confirmed files.

### Reference Template

```markdown
# [Title]

See [AGENTS.md]([Path]) for complete project documentation including:
- Development commands and setup
- Architecture overview
- Environment variables
- Testing patterns
- Deployment guides
- Section details in .agents-docs/
```