pi-init

Project initialization for AI coding agents.

pi-init is a pi plugin that adds the /init command. It reads your project's development standards (CLAUDE.md), scans the codebase, generates an AI-readable project guide (AGENTS.md), audits every file against the standards, and auto-fixes violations.

The three-file philosophy

File	Author	Purpose	.gitignore?
CLAUDE.md	You	Development standards: coding conventions, tooling, architecture rules	✅ Yes
AGENTS.md	AI (/init)	Project map: structure, entry points, key modules — helps AIs navigate your codebase	❌ No
README.md	You	For humans: introduction, quick start, contribution guide	❌ No

CLAUDE.md is the law. AGENTS.md is the map. You write the law. /init draws the map and enforces compliance.

Installation

# From npm (once published)
pi install npm:pi-init

# From git
pi install git:github.com/user/pi-init

# Local development
pi install ./path/to/pi-init

Usage

In pi, run:

/init           # Full: AGENTS.md + audit + auto-fix
/init --quick   # Fast: regenerate AGENTS.md only, skip audit

What it does

1. Reads CLAUDE.md — parses your development standards into structured rules
2. Scans the project — detects language, framework, entry points, key modules, config files (pure Node.js, zero LLM tokens)
3. Generates AGENTS.md — a structured project guide optimized for AI consumption
4. Audits the project — checks every relevant file against each rule from CLAUDE.md
5. Auto-fixes violations — fixes everything that can be mechanically fixed
6. Ensures .gitignore — adds CLAUDE.md to .gitignore if not already there

When to run it

• First time setting up a project with pi
• After changing CLAUDE.md (new rules need to be enforced)
• After significant codebase changes (AGENTS.md needs updating)

What goes in CLAUDE.md?

Write your development standards. Examples:

## Build & Test

Run `pnpm dev` to start, `pnpm build` to build, `pnpm test` to test.

## Coding standards

- Use kebab-case for file names, PascalCase for components.
- Every directory must have an AGENTS.md.
- Keep changes surgical — read the local AGENTS.md before editing.

## Architecture

- `app/` is the Next.js App Router. Each route is a folder with `page.tsx`.
- `lib/` contains shared utilities. No React imports allowed in `lib/`.
- Data fetching happens server-side only. Use Server Components by default.

## Tooling

- Use `eslint` for linting. Config is in `eslint.config.mjs`.
- Use `prettier` for formatting. Run `pnpm format` before committing.

/init will parse these into actionable rules and enforce them.

Development

# Clone and link
git clone <repo-url>
cd pi-init
pi install .

# Test in any project
cd /path/to/your/project
pi
# then run /init

License

MIT