Skip to content

AGENTS.md

Latest commit

 

History

History
101 lines (69 loc) · 3.3 KB

AGENTS.md

File metadata and controls

101 lines (69 loc) · 3.3 KB
Raw

Agent-MD Project Rules

These rules apply when working with the agent-md project.

Project Overview

agent-md is a Rust-based Markdown editor designed for AI agents. It provides CLI tools for reading, writing, editing, and validating Markdown files with JSON output.

Task Execution Process

For any development task:

  1. On task completion, you must:
    • Update documentation in the docs/ directory
    • Update README.md
    • Write unit tests for your changes
    • Update "./CHANGELOG.md" file with summary of your changes.
  2. Validate completion:
    • Run linting: cargo clippy --all-targets --all-features -- -D warnings
    • Run formatter: cargo fmt
    • Run tests: cargo test

After creating or updating any markdown file, always run agent-md lint path/to/file.md to validate the content before considering the task complete.

Strict Rules

grep/rg for definitions, signatures, class names, or type declarations

  • NEVER start with grep/rg for definitions, signatures, class names, or type declarations, use vfs CLI first. If vfs doesn't work, then use grep/rg.

Logging

Whenever you finish a task or change codes, always log your work using the l-log bash command (llm-lean-log-cli package) with the following format:

l-log add ./logs/chat.csv "<Task Name>" --tags="<tags>" --problem="<problem>" --solution="<solution>" --action="<action>" --files="<files>" --tech-stack="<tech>" --created-by-agent="<agent-name>"

Note: --last-commit-short-sha is optional and will be auto-populated by the CLI if not provided.

Before run:

  • Install the l-log CLI if not already installed: bun add -g llm-lean-log-cli.
  • If need, run CLI help command: l-log -h for more information.
  • log path: ./logs/chat.csv.

Markdown Writing Rules

When writing Markdown files in this project, follow these critical rules:

  • No bold text: Double asterisks and double underscores are NOT allowed
  • Use italics instead of bold for emphasis
  • Use headings for structure
  • Use code formatting for technical terms with backticks

Additional rules enforced by agent-md linter:

  • Simple table syntax (5 columns or fewer, 3-dash separators)
  • No useless links (link text must differ from URL)
  • No ASCII graphs (use JSON, CSV, or Mermaid)
  • Proper heading hierarchy (no level skipping)
  • Code blocks must specify language
  • No duplicate headings
  • Single H1 title per document

Available Commands

cargo build --release # Build release version
cargo test # Run tests
cargo fmt # Format code
cargo fmt --check # Check code formatting
cargo clippy --all-targets --all-features -- -D warnings # Run clippy lints
cargo audit # Security audit

Code Quality Standards

Clippy Rules

  • Cognitive complexity 30 or less
  • Function arguments 7 or fewer
  • Type complexity 250 or less
  • Documentation required for public items
  • No unwrap/expect in production code

Formatting Rules

  • Maximum line width: 100 characters
  • 4 spaces for indentation
  • Vertical trailing commas
  • Reordered imports

Troubleshooting

  • Build fails: Check Rust version in rust-toolchain.toml (requires 1.94.0)
  • Formatting errors: Run cargo fmt
  • Clippy warnings: Address linting issues in code
  • Test failures: Check test output for specific errors

Detailed Documentation

For comprehensive project information, use the agent-md skill when available.