4.7 KiB
4.7 KiB
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
- README.md
- TODO.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: Update when scope/constraints change.
- README.md: Update when CLI flags, defaults, or preview/apply behavior change.
- TODO.md: Update when starting/finishing tasks (end-of-day hygiene).
- docs/ARCHITECTURE.md: Update when component boundaries or contracts change.
- docs/adr/README.md + ADR files: Add when decisions are made or reversed.
- docs/DEV_WORKFLOW.md: Update when build/test/run steps change.
- 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 for any CLI or behavior change
- Added/updated ADR in docs/adr/ if design changed
- Adjusted docs/ARCHITECTURE.md if component boundaries changed
- Synced TODO.md (completed/in-progress/next)
- docs sanity check passes (tools/docs_check.sh)
- Unit/integration tests updated or added
Minimal docs sanity checks Create tools/docs_check.sh and mark it executable. Run it locally and in CI.
Example tools/docs_check.sh
#!/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 with a docs job that runs tools/docs_check.sh.
Example .github/workflows/ci.yml snippet
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 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.
- When changing CLI or behavior, update 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