Init Command

The /init command is designed to initialize or update an AGENTS.md file at the root of your project, following the open standard described at agents.md.

AGENTS.md acts as a developer handbook for AI agents, providing essential, project-specific context, commands, and rules so that any agent working on the codebase can immediately operate productively and safely.

---

The Three-Phase Execution Flow

When you run /init, PostQode executes in three distinct phases to ensure the file accurately reflects both the code and your team's intentions.

graph TD
    A[Phase 1: Explore] -->|Codebase Analysis| B[Phase 2: Interview]
    B -->|Interactive Questions| C[Phase 3: Generate]
    C -->|Save/Update AGENTS.md| D[Complete]

Phase 1: Explore (Silent Analysis)

PostQode silently analyzes your repository to gather all context that is already visible in the code. It scans:

• Package manifests and build configurations (e.g. package.json, pyproject.toml, Makefile, CI workflows).
• The README and any existing documentation.
• The directory structure, main entry points, and test setups.
• Any existing AGENTS.md or CLAUDE.md files.

note

This explore phase is entirely silent. PostQode gathers this information automatically so it doesn't ask you redundant questions about details already documented in the repository.

Phase 2: Interview (Interactive Session)

Using the ask_followup_question tool, PostQode asks you 3 to 4 targeted questions, one at a time. These questions focus on capturing knowledge that is not visible in the code, such as:

1. Commands & workflows: Day-to-day commands (build, test, lint, run) and any environment-specific quirks.
2. Conventions & style: Code style requirements or review expectations not automatically checked by linters.
3. Architecture intent: Which parts of the codebase are deprecated, active, or off-limits, and where new code should reside.
4. Gotchas & constraints: Hidden pitfalls, things that break CI, or files/settings that must never be altered.

Phase 3: Generate

After completing the interview, PostQode creates or updates the AGENTS.md file at the workspace root:

• In-place updates: If AGENTS.md already exists, PostQode updates it by preserving accurate sections, correcting outdated info, and incorporating your interview responses.
• No fluff: The file only contains verified, project-specific commands and rules, avoiding generic advice.

---

Document Format and Content

The generated AGENTS.md follows a clean, plain Markdown format without frontmatter and typically includes:

• Project Overview: Scope of the repository.
• Setup & Commands: Canonical commands for running, building, and testing.
• Code Style & Conventions: Naming, structure, and design expectations.
• Architecture Notes: Frameworks, data flow, and entry points.
• Testing & Validation: Test suites and verification commands.
• Gotchas: Common pitfalls, API rate limits, or restricted files.

---

How to Run

1. Type /init in the chat.
2. Respond to the questions prompted by PostQode one by one.
3. Once the interview is complete, PostQode writes/updates the AGENTS.md file at your workspace root and presents the completed summary.