The kiki Reference

This directory is the implementation reference for kiki (kk).

Read it as a small spec book: first the reason for the tool, then the model, then the safety rules, then the user surfaces and machinery. The book is normative. It defines kiki's permitted behavior, prohibited behavior, and v1 boundaries. Ambiguity should be treated as a documentation bug to fix.

New readers should start with the Abstract and Orientation. Together they carry the narrative — the hand-built workspace-per-line-of-work workflow kiki automates, its frictions, and the mechanism that answers each one — before the contract chapters tighten the screws.

Reading order

The chapters tell the story in order; the appendices hold reference material you dip into rather than read through.

1. Abstract
2. Orientation
3. Invariants
4. Threads
5. Authority
6. Cascade
7. Transcript
8. Publishing
9. Metadata Evolution
10. Commands
11. Interface
12. Configuration
13. Observability
14. Architecture
15. Testing
16. Build Sequencing
17. Roadmap
18. Decisions

Appendices:

• Appendix A: Glossary
• Appendix B: User Stories
• Appendix C: Naming

Authority

The numbered chapters and appendices are the live contract. The Decisions chapter explains why parts of the contract look the way they do, but the behavioral chapters remain authoritative.

When two live chapters appear to conflict, use this order:

1. Invariants
2. Behavioral chapters: Threads, Authority, Cascade, Transcript, Publishing, Metadata Evolution, Commands, Interface, Configuration, and Observability
3. User Stories, as product intent that the stricter chapters must satisfy
4. Architecture
5. Testing, Build Sequencing, Roadmap, Decisions, and the remaining appendices

Language

The words must, must not, may, and should are normative in the ordinary RFC sense. The voice is plain by design: kiki coordinates expensive, stateful work, and the docs should say exactly what they mean.