Skip to content

AGENTS.md

Latest commit

 

History

History
102 lines (74 loc) · 5.1 KB

AGENTS.md

File metadata and controls

102 lines (74 loc) · 5.1 KB
Raw

AGENTS.md

Instructions for AI coding agents (Claude Code, Aider, Cursor, Continue, etc.) working in this repository.

This file is the entry point. For full details, read the files it points to.

Start here

  1. CLAUDE.md — complete project instructions: methodology, git workflow, commit conventions, storage model, quality gates, and hard rules. Read this first.
  2. docs/README.md — documentation index with cross-references to methodology, operations, schemas.
  3. forgeplan health — run this in the terminal to see current project state (blind spots, orphans, stale artifacts).

What this project is

Forgeplan — Rust-based methodology engine (CLI + MCP server + future Desktop app) for managing engineering artifacts (PRD, RFC, ADR, Epic, Spec, Evidence) with quality scoring, semantic search, and decision tracking.

  • Language: Rust 1.75+ (crates workspace)
  • Storage: Markdown files in .forgeplan/ as source of truth (ADR-003), LanceDB as derived index
  • Distribution: cargo-dist binaries, brew formula, install script
  • Website: Astro + Starlight at website/ (see website/README.md)

Hard rules (non-negotiable)

  1. Follow the Forgeplan methodology itself when making non-trivial changes:

    • forgeplan route "task" → determine depth (tactical / standard / deep / critical)
    • forgeplan new <kind> → create artifact for Standard+ depth
    • forgeplan validate → must PASS before coding
    • forgeplan reason → ADI reasoning (mandatory for Deep+)
    • Code → test each pub fn immediately
    • forgeplan new evidence + link + score + activate

  2. Never commit to main or dev directly. Always feature branch → PR.

  3. Never delete .forgeplan/ without forgeplan export first.

  4. Never push --force to main. The safety hook blocks this.

  5. cargo fmt + cargo check before every commit. Git hooks enforce this.

  6. Write tests for every new pub fn immediately — do not move to the next function without a test.

  7. Markdown files in .forgeplan/ are the source of truth (per ADR-003). The LanceDB index in .forgeplan/lance/ is derived — rebuild via forgeplan scan-import if needed.

Repository structure (quick map)

ForgePlan/
├── CLAUDE.md, AGENTS.md, README.md
├── crates/                ← Rust workspace (core + cli + mcp)
├── .forgeplan/            ← artifact workspace (markdown tracked, lance/cache/config local)
│   ├── adrs/, rfcs/, prds/, epics/, specs/
│   ├── evidence/, problems/, solutions/, notes/
│   ├── lance/             ← gitignored (derived)
│   └── config.yaml        ← gitignored (local)
├── docs/                  ← production documentation
│   ├── README.md          ← documentation index
│   ├── methodology/       ← how to use Forgeplan
│   ├── operations/        ← agent hooks, enforcement, repo protection
│   └── schemas/           ← formal artifact schemas
├── templates/             ← markdown templates for each artifact kind
├── website/               ← official website (Astro + Starlight)
├── marketplace/           ← plugin marketplace (plugins + skills)
├── scripts/               ← build + release + helper scripts
├── Formula/               ← Homebrew formula
└── .local/                ← gitignored — local notes, research, sessions

Language

  • Documentation & commit bodies: Russian preferred (matches project conventions)
  • Code identifiers & commit descriptions: English
  • Communication with the user: Russian

Authorship (single author)

Forgeplan is a single-author project. When generating ANY author-attributed content, use:

  • Name: Eli Rum
  • URL: https://elirum.me

This applies to:

  • Blog post AuthorBlock (website/src/components/blog/AuthorBlock.astro)
  • Blog footer author line (website/src/components/blog/BlogFooter.astro)
  • JSON-LD author.name + Person.url (website/src/components/blog/SeoMeta.astro)
  • Schema.org Organization.founder (website/src/components/SiteJsonLd.astro)
  • OpenGraph article:author meta tags
  • package.json author field (if updated)
  • Any author byline in docs/, .forgeplan/notes/, blog .mdx frontmatter
  • Conventional commit Co-Authored-By lines for solo work (do not add — Eli Rum is sole author)

DO NOT use placeholder names: Mike Kubal, Forgeplan Author, Anonymous, Maintainer, etc.

If a future contributor joins, this section will be updated to reflect multi-author conventions. Until then, treat the single-author invariant as load-bearing for credibility, SEO authority signal, and brand consistency.

See also