docs: add KILO_HOWTO.md process guide for Kilo context reload and docs hygiene
This commit is contained in:
129
KILO_HOWTO.md
Normal file
129
KILO_HOWTO.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# KILO_HOWTO: Continuity and documentation hygiene
|
||||
|
||||
Purpose
|
||||
- Explain how Kilo regains context after restart and how to keep docs in sync with code.
|
||||
- Keep this file short, actionable, and authoritative for process.
|
||||
|
||||
What Kilo preloads by default after a restart
|
||||
- [PROMPT.md](PROMPT.md)
|
||||
- [README.md](README.md)
|
||||
- [TODO.md](TODO.md)
|
||||
- [docs/adr/README.md](docs/adr/README.md)
|
||||
Notes
|
||||
- Kilo can preload the entire docs/ tree on request. Ask “preload docs” or link to a specific file.
|
||||
- Anything committed in-repo is considered the source of truth.
|
||||
|
||||
Update triggers by document
|
||||
- [PROMPT.md](PROMPT.md): Update when scope/constraints change.
|
||||
- [README.md](README.md): Update when CLI flags, defaults, or preview/apply behavior change.
|
||||
- [TODO.md](TODO.md): Update when starting/finishing tasks (end-of-day hygiene).
|
||||
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): Update when component boundaries or contracts change.
|
||||
- [docs/adr/README.md](docs/adr/README.md) + ADR files: Add when decisions are made or reversed.
|
||||
- [docs/DEV_WORKFLOW.md](docs/DEV_WORKFLOW.md): Update when build/test/run steps change.
|
||||
- [docs/API-SKELETONS.md](docs/API-SKELETONS.md): Update when public surfaces or CLI/programmatic APIs change.
|
||||
|
||||
Lightweight process guardrails
|
||||
- Every feature/change should update the relevant docs in the same commit/PR.
|
||||
- Prefer ADRs for decisions that affect architecture, data formats, or safety policies.
|
||||
- Keep this KILO_HOWTO.md updated if the maintenance process itself changes.
|
||||
|
||||
Pull request checklist (copy into your template)
|
||||
|
||||
- [ ] Updated [README.md](README.md) for any CLI or behavior change
|
||||
- [ ] Added/updated ADR in [docs/adr/](docs/adr/README.md) if design changed
|
||||
- [ ] Adjusted [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) if component boundaries changed
|
||||
- [ ] Synced [TODO.md](TODO.md) (completed/in-progress/next)
|
||||
- [ ] docs sanity check passes ([tools/docs_check.sh](tools/docs_check.sh))
|
||||
- [ ] Unit/integration tests updated or added
|
||||
|
||||
Minimal docs sanity checks
|
||||
Create [tools/docs_check.sh](tools/docs_check.sh) and mark it executable. Run it locally and in CI.
|
||||
|
||||
Example tools/docs_check.sh
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
echo "[docs_check] verifying referenced files exist"
|
||||
paths=(
|
||||
"PROMPT.md"
|
||||
"README.md"
|
||||
"TODO.md"
|
||||
"docs/adr/README.md"
|
||||
"docs/ARCHITECTURE.md"
|
||||
)
|
||||
for p in "${paths[@]}"; do
|
||||
[[ -f "$p" ]] || { echo "missing: $p" >&2; exit 1; }
|
||||
done
|
||||
|
||||
echo "[docs_check] verifying CLI flags documented"
|
||||
help_out="$(cargo run -- --help 2>/dev/null || true)"
|
||||
if [[ -n "$help_out" ]]; then
|
||||
# Require README to mention each long flag token like --apply or --show
|
||||
flags=$(grep -oE -- '--[a-z0-9-]+' <<<"$help_out" | sort -u)
|
||||
missing=0
|
||||
while read -r f; do
|
||||
grep -q -- "$f" README.md || { echo "README missing flag: $f" >&2; missing=1; }
|
||||
done <<<"$flags"
|
||||
[[ $missing -eq 0 ]] || exit 1
|
||||
else
|
||||
echo "[docs_check] skipped CLI verification (binary not runnable in this context)"
|
||||
fi
|
||||
|
||||
echo "[docs_check] verifying ADR index lists all ADRs"
|
||||
if [[ -d docs/adr ]]; then
|
||||
want=$(find docs/adr -maxdepth 1 -type f -name 'ADR-*.md' -printf '%f\n' | sort -u)
|
||||
if [[ -n "$want" ]]; then
|
||||
idx="docs/adr/README.md"
|
||||
for f in $want; do
|
||||
grep -q -- "$f" "$idx" || { echo "ADR not indexed in $idx: $f" >&2; exit 1; }
|
||||
done
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "[docs_check] OK"
|
||||
```
|
||||
|
||||
CI wiring (GitHub Actions example)
|
||||
Create [.github/workflows/ci.yml](.github/workflows/ci.yml) with a docs job that runs tools/docs_check.sh.
|
||||
|
||||
Example .github/workflows/ci.yml snippet
|
||||
|
||||
```yaml
|
||||
name: CI
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
jobs:
|
||||
build-and-docs:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions-rs/toolchain@v1
|
||||
with:
|
||||
toolchain: stable
|
||||
override: true
|
||||
- name: Build
|
||||
run: cargo build --locked
|
||||
- name: Test
|
||||
run: cargo test --locked
|
||||
- name: Docs sanity
|
||||
run: bash tools/docs_check.sh
|
||||
```
|
||||
|
||||
Daily habits
|
||||
- At the end of a work session, update [TODO.md](TODO.md) to reflect reality (completed/in-progress/next).
|
||||
- When introducing or reversing a design decision, add an ADR and index it in [docs/adr/README.md](docs/adr/README.md).
|
||||
- When changing CLI or behavior, update [README.md](README.md) in the same commit as the code change.
|
||||
|
||||
Asking Kilo to (re)load context
|
||||
- “preload docs” to read the entire docs/ tree.
|
||||
- Link specific files in your message; Kilo will read those first.
|
||||
|
||||
Rationale
|
||||
- Keeping docs changes co-located with code in the same commit prevents drift.
|
||||
- A single fast docs_check.sh closes the gap when someone forgets an update.
|
||||
- Small, well-defined authorities ([PROMPT.md](PROMPT.md), [README.md](README.md), [TODO.md](TODO.md), ADRs) reduce duplication.
|
||||
Reference in New Issue
Block a user