agentinit 0.3.6

Scaffold agent context files into a project.

agentinit

Scaffold hardened, router-first context files so your AI coding agents stop guessing and start delivering.

Pure Python standard library. No runtime dependencies. Generates 2026-ready manifests for Claude Code, Cursor, Copilot, and Gemini CLI. llms.txt also provides discovery-friendly routing for other tools (for example, Windsurf).

llms.txt now includes auto-summary and mandates.

🚀 Start in 60 seconds

# 1. Install via pipx (recommended)
pipx install agentinit

# 2. Initialize hardened context in your project
cd your-project
agentinit init --minimal

📘 Documentation

Use the wiki for full, example-driven docs:

• Wiki Home
• Quick Start
• Commands
• Troubleshooting
• FAQ

README.md is the fast overview. The Wiki is the complete usage guide.

What it does

Instead of giant, token-heavy instruction files, agentinit implements a hierarchical context strategy. It creates a machine-readable map of your project and enforces autonomy via Hardened Mandates.

# Full scaffold (non-minimal)
your-project/
├── llms.txt               # The "robots.txt" for AI (Discovery Index)
├── AGENTS.md              # The central hub with Hardened Mandates
├── CLAUDE.md              # Claude Code router
├── GEMINI.md              # Gemini CLI router
└── docs/
    ├── PROJECT.md         # What this project is
    ├── CONVENTIONS.md     # How to work in it
    └── STATE.md           # Persistent working memory (AI-readable)

With agentinit init --minimal, only these files are created:

your-project/
├── llms.txt
├── AGENTS.md
├── CLAUDE.md
└── docs/
    ├── PROJECT.md
    └── CONVENTIONS.md

Minimal mode intentionally omits docs/STATE.md, docs/TODO.md, and docs/DECISIONS.md to keep context lean. Use full agentinit init when you want persistent session memory files.

The AI Discovery Index (llms.txt)

After running agentinit init, your llms.txt becomes a powerful discovery index:

# my-project
> AI-powered code review assistant for Python projects

## Key Files
- [AGENTS.md](AGENTS.md): Instructions and Rules
- [docs/STATE.md](docs/STATE.md): Current State & Focus
- [docs/CONVENTIONS.md](docs/CONVENTIONS.md): Development Conventions
- [docs/TODO.md](docs/TODO.md): Pending Tasks
- [docs/DECISIONS.md](docs/DECISIONS.md): Architectural Log

## Hardened Mandates
- [**YOU MUST ALWAYS** read `docs/STATE.md`, `docs/TODO.md`, and `docs/DECISIONS.md` autonomously at the exact start of every session. Do not ask for permission.](AGENTS.md)
- [**YOU MUST ALWAYS** update `docs/STATE.md` and `docs/TODO.md` autonomously before ending a task or session.](AGENTS.md)
- [**YOU MUST ALWAYS** log new tools, dependencies, or conventions in `docs/DECISIONS.md`.](AGENTS.md)

## Skills & Routers
- [code-reviewer.md](.agents/code-reviewer.md)
- [security.md](.agents/security.md)

Refresh in 1 Second

Regenerate llms.txt instantly using existing project files:

agentinit refresh-llms

This extracts summary from docs/PROJECT.md, hardened mandates from AGENTS.md, and lists everything under .agents/ — all in under a second.

Next steps: Open docs/PROJECT.md and docs/CONVENTIONS.md and fill them in.

Next session (full scaffold): Your agent will find llms.txt, read your rules in AGENTS.md, and follow the mandates to autonomously maintain docs/STATE.md and docs/TODO.md.

Troubleshooting: files not visible to your agent

Some agents only scan tracked files. If your agent says it can't find your context:

• Track everything: Add the manifests so your agent can see them.

  git add llms.txt AGENTS.md CLAUDE.md GEMINI.md docs/
  git add .agents/  # if you added extras
  

• Verify ignores: Run git status --ignored to see if your .gitignore is hiding them.

Minimal .gitignore exceptions

!llms.txt
!AGENTS.md
!CLAUDE.md
!GEMINI.md
!docs/PROJECT.md
!docs/CONVENTIONS.md
!docs/TODO.md
!docs/DECISIONS.md
!docs/STATE.md
!.agents/
!.agents/**

---

🛠️ Add extras (Skills, MCP, Personality)

Agents can do more than just read conventions. Inject modular, hardened resources directly into your project.

# View available resources by type
agentinit add skill --list
agentinit add mcp --list

# Add specific capabilities
agentinit add skill code-reviewer
agentinit add security
agentinit add soul "YourAgentName"

Resources in .agents/ are automatically linked in AGENTS.md and use Imperative Mandates (MUST ALWAYS, MUST NEVER) to ensure compliance and zero-sycophancy.

---

🚦 Keep your context clean (Status & CI)

Token limits matter. agentinit includes a validator to prevent context bloat, broken links, and missing information.

# View line budgets, broken references, and missing details
agentinit status

# Perfect for CI (exits non-zero on violations)
agentinit status --check

---

🤖 AI Prompt: Fill the docs fast

After running agentinit init, paste this to your favorite AI agent:

Read the entire repository. Fill in docs/PROJECT.md and docs/CONVENTIONS.md using only facts found in the repo (package files, configs, source code, CI). Do not invent commands. If information is missing, write TODO: <what's needed>. Update docs/STATE.md and docs/TODO.md to reflect our current progress. Do not modify any other files.

---

📚 Advanced Usage & Commands

Core Commands

• agentinit init — Add missing files to an existing directory.
• agentinit minimal — Shortcut for init --minimal.
• agentinit refresh-llms — Regenerate llms.txt in 1 second (refresh alias also available).
• agentinit status — Check health, line budgets, and broken links.
• agentinit add <type> <name> — Add modular resources (skills, mcp, security, soul).
• agentinit new <project> — Create a new directory and scaffold files.
• agentinit remove — Safely remove or archive agent files.

Common Flags

• --detect — Auto-detect stack and commands from package files (e.g., package.json, pyproject.toml).
• --yes / -y — Runs non-interactively and skips the wizard.
• --purpose "<text>" — Prefill the project purpose non-interactively.
• --translate-purpose — Translate non-English purpose text to English in docs/* (and keep original summary in llms.txt).
• --skeleton fastapi — Copy a minimal FastAPI + SQLite boilerplate (pyproject.toml, main.py, tests) after context files.

Examples

# Existing repo: detect + auto-translate purpose into English docs
agentinit init --detect --purpose "Una semplice API REST per gestire todo list con FastAPI + SQLite"

# Force translation even without detect
agentinit init --purpose "Une API REST simple pour gerer une liste de taches" --translate-purpose

# New project with context files + FastAPI starter skeleton
agentinit new demo-fastapi --detect --purpose "Modern FastAPI API with SQLite" --skeleton fastapi

💡 Why Hardened Context?

• Agent Autonomy: Explicit mandates (YOU MUST ALWAYS read state.md) transform the agent from a chatbot into a disciplined project maintainer.
• AI-Discovery Index: llms.txt ensures any tool (Cursor, Windsurf, Claude) immediately understands your project map.
• Progressive Disclosure: Keeps the context window high-signal by loading deep details only when relevant.
• Zero Sycophancy: Mandates force the agent to skip "I'd be happy to help!" and jump straight to the technical solution.

⚙️ Installation & Development

Requires Python 3.10+.

# Install (pipx is recommended)
pipx install agentinit

# Update
pipx upgrade agentinit

Development

pip install -e . --group dev
python3 -m ruff check agentinit tests cli
python3 -m pytest tests/ -v

License

MIT