129 lines
4.7 KiB
Markdown
129 lines
4.7 KiB
Markdown
# 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. |