bon-agents-md

bon-agents-md is a CLI that generates lean AI-working guides plus a Delta-first documentation skeleton.

It is designed for teams and solo developers who want to:

• start AI-assisted work quickly
• keep concept / spec / architecture / plan aligned
• reduce scope creep and document drift
• keep long-running AI work reviewable

What It Generates

Run one command and bon creates:

• an editor-facing guide
  • AGENTS.md for Codex / OpenCode
  • CLAUDE.md for Claude Code
  • .cursorrules for Cursor
  • copilot-instructions.md for Copilot
• canonical project docs under docs/
  • docs/OVERVIEW.md
  • docs/concept.md
  • docs/spec.md
  • docs/architecture.md
  • docs/plan.md
  • docs/delta/TEMPLATE.md
  • docs/delta/REVIEW_CHECKLIST.md
• skills (optional)
  • includes project-validator
  • includes plan-archive-shrinker

bon no longer copies validator scripts into generated projects. Validator logic lives inside skills.

The generated structure is intentionally opinionated: the guide stays lean, and project-specific truth lives under docs/.

Philosophy

bon-agents-md is built around a simple idea:

AI work is safest when change is small, reviewable, and tied to a canonical record.

That leads to these operating principles:

1. Delta-first
   • Every requirement is handled as a delta: delta request -> delta apply -> delta verify -> delta archive
2. Canonical docs first
   • docs/OVERVIEW.md is the operational entrypoint
   • concept / spec / architecture / plan are the canonical project record
3. Minimal diffs
   • A delta should change only what it needs to change
   • speculative cleanup and unrelated refactors stay out
4. Review at milestones
   • when a major feature completes, run a review delta
   • if a plan item spreads across multiple deltas, review earlier
5. Keep the system readable
   • plan.md stays thin
   • archive details move to monthly archive files
   • oversized source files are reviewed and split

This is not just a prompt template. It is an operating model for AI-assisted development.

Reference:

• docs/philosophy.py

Install

npm install -g bon-agents-md

Requires Node.js 16+.

Basic Usage

bon
bon --dir path/to/project
bon --force
bon --lang ts
bon --agent claudecode
bon --agent cursor
bon --agent opencode
bon --skills none
bon --skills workspace
bon --skills user
bon --help
bon --version

Options:

• --dir: output directory
• --force: overwrite an existing guide file
• --lang: python | js | ts | rust
• --agent: codex | claudecode | cursor | copilot | opencode
• --skills: none | workspace | user

Meaning of --skills:

• none: generate guide + docs only
• workspace: install skills into the target project
• user: install skills into the agent's user-level skill directory

How To Use It

1. Generate the guide and docs

bon --agent codex --skills workspace --lang python

Recommended defaults:

• --agent codex
• --skills workspace

Examples:

# docs + workspace skills for the current project
bon --agent codex --skills workspace

# docs only, no skill installation
bon --agent codex --skills none

# install skills to CODEX_HOME/skills and still generate project docs
bon --agent codex --skills user

# Claude Code project setup
bon --agent claudecode --skills workspace

# OpenCode project setup
bon --agent opencode --skills workspace

Skill scope examples:

# Use skills only inside this project
bon --agent codex --skills workspace

# Install reusable skills for your whole Codex environment
bon --agent codex --skills user

2. Open the entrypoint

Read:

• AGENTS.md or the editor-specific guide
• docs/OVERVIEW.md

OVERVIEW.md tells you:

• current scope
• canonical links
• review rules
• plan slimming rules
• delta operating rules

3. Add one small plan item

Start from docs/plan.md.

Keep it small. One plan item should normally become one delta seed.

4. Create a delta

Copy docs/delta/TEMPLATE.md into a new file:

docs/delta/DR-YYYYMMDD-short-name.md

Fill in:

• Delta Type
• purpose
• In Scope
• Out of Scope
• Acceptance Criteria
• review gate requirement

5. Implement only the delta

Work only on AC-linked changes.

Do not mix in:

• unrelated refactors
• broad redesign
• speculative extension

6. Verify

Use the project-validator skill.

And run the relevant tests for the change.

Important:

• generated projects do not receive project/scripts/*.js
• validator helpers belong to the installed skill
• repo-level scripts/*.js are only for developing bon-agents-md itself

7. Archive

When verify is PASS:

• archive the delta
• move plan completion into plan archive summary if needed
• sync canonical docs with minimal diffs

Delta Types

The generated workflow supports these delta types:

• FEATURE
• REPAIR
• DESIGN
• REVIEW
• DOCS-SYNC
• OPS

REVIEW delta

REVIEW is important for long-running AI work.

Use it when:

• a major feature is complete
• one plan item has grown into 3 or more deltas
• 5 non-review deltas have continued without a review
• architecture / docs / data hygiene need a checkpoint
• you simply want a design review now

Manual trigger examples:

• run a review delta
• do a design review

REVIEW delta uses:

• docs/delta/REVIEW_CHECKLIST.md

It checks:

• layer integrity
• docs sync
• data size / record hygiene
• code split health
• verify coverage

If problems are found, the review delta should record follow-up seeds rather than mixing large fixes into the review itself.

Plan Slimming

docs/plan.md is intentionally thin.

It should contain only:

• current
• review timing
• future
• archive
• archive index

Detailed history moves into monthly files such as:

• docs/plan_archive_2026_03.md

Manual trigger examples:

• shrink the plan
• organize the archive

Use the plan-archive-shrinker skill when you trigger plan slimming manually.

Codex may also slim the plan when:

• the archive section exceeds 100 lines
• archive becomes clearly larger than current + future

Validation

Use the project-validator skill.

Checks:

• docs/plan.md
• docs/delta/DR-*.md
• archive PASS consistency

Defaults:

• over 500 lines: review target
• over 800 lines: should be split
• over 1000 lines: exception only

This applies to source-code file extensions, not Markdown docs.

Practical Working Pattern

A realistic cycle looks like this:

1. add one plan item
2. create one delta
3. implement the smallest useful change
4. verify with tests + validators
5. archive
6. run a REVIEW delta at a meaningful boundary
7. slim the plan when it starts getting noisy

That is the intended workflow.

Generated Structure

Guides

• Codex / OpenCode: AGENTS.md
• Claude Code: CLAUDE.md
• Cursor: .cursorrules
• Copilot: copilot-instructions.md

Canonical docs

• docs/OVERVIEW.md
• docs/concept.md
• docs/spec.md
• docs/architecture.md
• docs/plan.md
• docs/delta/TEMPLATE.md
• docs/delta/REVIEW_CHECKLIST.md

Skills

With --skills workspace:

• codex: ./.codex/skills
• claudecode: ./.claude/skills
• cursor: ./.cursor/skills
• copilot: ./.github/copilot/skills
• opencode: ./.opencode/skills

With --skills user:

• codex: ${CODEX_HOME}/skills or ~/.codex/skills
• claudecode: ~/.claude/skills
• opencode: ~/.config/opencode/skills

Notes for user scope:

• Codex: this follows the actual Codex skill layout: ${CODEX_HOME}/skills/<skill-name>/SKILL.md
• Claude Code: this follows the Claude Code skill layout: ~/.claude/skills/<skill-name>/SKILL.md
• OpenCode: this follows the OpenCode skill layout: ~/.config/opencode/skills/<skill-name>/SKILL.md
• Cursor: unsupported
• Copilot: unsupported
• bon exits with an error if you use --agent cursor --skills user or --agent copilot --skills user

With --skills none, bon skips skill installation, so project-validator and plan-archive-shrinker are not installed.

Relevant skills:

• project-validator
• plan-archive-shrinker

Skill ownership model:

• project docs and guides are bootstrap output
• files under skills/<skill-name>/ are skill-owned assets
• validator helpers belong to project-validator
• plan archive shrinking logic belongs to plan-archive-shrinker

Locale

Locale is inferred from:

• LANG
• LC_ALL
• OS locale

WSL prefers Windows locale.

If the locale is Japanese, generated docs are Japanese-oriented.

Development

Run tests:

npm test

Run repository validators:

node scripts/validate_delta_links.js --dir .
node scripts/check_code_size.js --dir .

These repo-level scripts are for maintaining this repository, not for generated projects.

Why This Shape Works

This project is intentionally biased toward:

• clarity over cleverness
• reviewable milestones over fully open-ended AI autonomy
• canonical documentation over scattered notes
• controlled evolution over prompt sprawl

If you want AI to work longer without drifting, this shape is the point.