74 lines
2.1 KiB
Markdown
74 lines
2.1 KiB
Markdown
# Design: Auto-updating README.md and AGENTS.md
|
|
|
|
## Overview
|
|
|
|
Create documentation files (README.md, AGENTS.md) that auto-update on every commit via a git pre-commit hook.
|
|
|
|
## Requirements
|
|
|
|
- README.md with: full usage docs, deck summaries, workflow guide
|
|
- AGENTS.md with: build/verify commands, code style guide, extension guide, project structure
|
|
- Pre-commit hook triggers on all file changes
|
|
- Template-based generation for maintainability
|
|
|
|
## Architecture
|
|
|
|
```
|
|
├── README.md # Generated (do not edit directly)
|
|
├── AGENTS.md # Generated (do not edit directly)
|
|
├── docs/
|
|
│ └── templates/
|
|
│ ├── README.template.md
|
|
│ └── AGENTS.template.md
|
|
├── scripts/
|
|
│ └── update_docs.py # Generator script
|
|
└── .git/hooks/
|
|
└── pre-commit # Runs update_docs.py
|
|
```
|
|
|
|
## Components
|
|
|
|
### 1. Template Files
|
|
|
|
Markdown templates with placeholders:
|
|
- `{{DECK_SUMMARIES}}` - Dynamic deck table from decks/*.json
|
|
- `{{COLLECTION_STATS}}` - Card counts from collection_hydrated/
|
|
- Static content for usage, workflow, conventions
|
|
|
|
### 2. Generator Script (`scripts/update_docs.py`)
|
|
|
|
- Reads `decks/*.json` for commander, colors, card counts
|
|
- Reads `collection_hydrated/` for collection statistics
|
|
- Fills template placeholders
|
|
- Writes README.md and AGENTS.md
|
|
|
|
### 3. Pre-commit Hook
|
|
|
|
Simple bash script that:
|
|
1. Runs `python scripts/update_docs.py`
|
|
2. Stages updated docs with `git add README.md AGENTS.md`
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
decks/*.json ──┐
|
|
├──> update_docs.py ──> README.md
|
|
collection/ ───┤ AGENTS.md
|
|
templates/ ────┘
|
|
```
|
|
|
|
## Implementation Steps
|
|
|
|
1. Create template files in `docs/templates/`
|
|
2. Create `scripts/update_docs.py` generator
|
|
3. Create `.git/hooks/pre-commit` hook
|
|
4. Run initial generation
|
|
5. Commit all files
|
|
|
|
## Success Criteria
|
|
|
|
- README.md contains current deck summaries
|
|
- AGENTS.md documents project conventions
|
|
- Running `git commit` updates docs automatically
|
|
- Templates are easy to edit for future changes
|