A lightweight documentation framework for solo developers and small teams building products with AI agents. Knowledge is organized by initiatives — focused, dated units of work — instead of by document type.
docs/
├── README.md # Navigation guide
├── glossary.md # Shared vocabulary
├── TIMELINE.md # Chronological register of all initiatives
│
├── 2026-04-22-initial-vision/ # One initiative = one folder
│ ├── README.md # What this initiative is about
│ ├── vision.md # Main artifact
│ ├── journal.md # Living log of how we got here
│ ├── kanban.md # Optional: subtask board (Obsidian Kanban format)
│ └── decisions/ # ADRs born in this initiative
│ └── 0001-storage-sqlite-only.md
│
├── 2026-05-10-auth-system/
│ ├── README.md
│ ├── rfc.md
│ └── journal.md
│
└── 2026-06-03-...
One folder per unit of work. Alphabetical sort = chronological order. Everything about one topic stays together.
Most documentation conventions are type-driven: separate top-level folders for vision/, adr/, rfc/, specs/, notes/. The theory is that everyone can find everything by its shape.
In practice, when you're working on one focused thing, you want everything about that thing in one place — the goal, the decisions, the journal, the open questions, the rejected alternatives. Type-driven structure scatters a single train of thought across five folders. Six months later, nobody can reconstruct why a decision was made without an archeology dig.
Initiative-driven structure solves this: one folder per unit of work, dated, self-contained. When the initiative closes, it becomes an archive you can read end-to-end without a scavenger hunt.
Initiative-Driven Documenting is a particularly good fit when:
- You work solo or in a small team where everyone touches everything
- You collaborate with AI agents that benefit from loading a single coherent context
- Your work has distinct planning cycles (vision rounds, architecture spikes, big refactors)
- You want your documentation to double as project memory and onboarding material
- You're tired of stale
docs/architecture.mdthat nobody updates because it belongs to no one in particular
- Very large organizations where a single document might be owned and maintained by a dedicated team for years — traditional type-driven structures scale better for institutional docs
- Pure reference manuals (API docs, CLI reference) — use specialized tooling for those
An initiative is a focused stretch of work with a beginning, middle, and end. Examples:
- "Figure out what the product should be" — a vision initiative
- "Design the authentication system" — an architecture initiative
- "Decide between Postgres and SQLite" — a decision initiative
- "Plan Q2 roadmap" — a planning initiative
- "Investigate why latency spiked in week 38" — an investigation initiative
Each initiative lives in its own folder. The framework defines the container, not the content — you choose the artifacts that fit the initiative type.
README.md— navigation guide: how to read this folder, what lives whereglossary.md— terms used across initiatives; single source of truth for vocabularyTIMELINE.md— chronological register of every initiative and its status
Inside docs/YYYY-MM-DD-<kebab-name>/, you put whatever artifacts make sense for that particular piece of work. Typical artifacts:
README.md— what this initiative is, its goal, current status, what's insidevision.md/rfc.md/plan.md— the main artifact, depending on typejournal.md— a living log of the work, in reverse-chronological orderkanban.md— optional subtask board when you need in-folder task tracking (see Kanban boards)decisions/NNNN-<kebab>.md— ADRs produced during this initiative
The framework deliberately does not prescribe a fixed artifact set. An architecture spike might have rfc.md + decisions/. A retrospective might have only journal.md + README.md. Pick what fits.
YYYY-MM-DD-<kebab-name>/
- Date — when work on this initiative started (not when it finished)
- Kebab-name — short, descriptive, lowercase with hyphens
- Alphabetical sort gives you chronological order for free
Good: 2026-04-22-initial-vision/, 2026-07-03-auth-rewrite/, 2026-09-11-payment-provider-research/
Avoid: dateless folders, YYYYMMDD (no separators), camelCase, spaces.
- Lowercase
kebab-case.md - Numeric prefix
NNNN-is reserved only for ADRs insidedecisions/ - Keep names short; the folder provides the context
Every Markdown file starts with a YAML front-matter block:
---
title: Initial Vision — product vision
status: in-progress
created: 2026-04-22
updated: 2026-04-22
authors: [Your Name]
type: vision
language: en
---| Field | Purpose |
|---|---|
title |
Human-readable title |
status |
Lifecycle state (see below) |
created |
ISO date, never changes |
updated |
ISO date, bumped on every meaningful edit |
authors |
List of contributors |
type |
Free text. Conventional: readme, vision, journal, rfc, adr, glossary, timeline, plan |
language |
ISO code; one canonical language per file |
planned → in-progress → approved → (optionally) superseded
planned— folder exists, goal is stated, work has not startedin-progress— actively being worked onapproved— final state reached and agreed; the initiative is closedsuperseded— a later initiative has replaced this one; add a link to the replacement in front-matter
Status lives in the initiative README.md front-matter and is mirrored in TIMELINE.md.
TIMELINE.md is the top-level chronological register. Newest on top. One line per initiative:
| Start date | Initiative | Status | Link |
| ---------- | ----------------- | ----------- | ------------------------------ |
| 2026-05-10 | Auth System | in-progress | [./2026-05-10-auth-system/] |
| 2026-04-22 | Initial Vision | approved | [./2026-04-22-initial-vision/] |Update TIMELINE.md in the same commit that creates or closes the initiative. Never out of band.
glossary.md grows with the project. Rule: every new term appearing in an initiative's documents is added to glossary.md in the same commit that introduces it. This keeps terminology discoverable and prevents the "what does this even mean" tax on future readers (including your future self, and AI agents loading the context cold).
ADRs live in decisions/ inside the initiative that produced them. Filename: NNNN-short-kebab-name.md. Numbering is per-initiative, starting at 0001-.
If an ADR becomes load-bearing across multiple initiatives, link to it from TIMELINE.md under a dedicated "Key ADRs" section.
An initiative may include a kanban.md — a subtask board formatted for Obsidian Kanban. Use it when you need to track granular subtasks within an initiative without reaching for an external issue tracker.
---
kanban-plugin: basic
---
## To Do
- [ ] Write the RFC draft
- [ ] Get feedback from Alice
## In Progress
- [ ] Define data model
## Done
- [x] Agree on scopeThe kanban-plugin: basic front-matter key is what tells Obsidian to render the file as a board. In any other Markdown viewer the file reads as a plain checklist — no tooling lock-in.
Use exactly three columns: To Do, In Progress, Done. Do not add more columns.
When the user explicitly asks to create a Kanban board for an initiative and break the current work into subtasks:
- Create
kanban.mdinside the initiative folder with all planned subtasks under To Do. - Work through subtasks sequentially, one at a time:
- Before starting a subtask: move it from To Do → In Progress in
kanban.md. - After completing a subtask: move it from In Progress → Done in
kanban.md. - Commit after each completed subtask — the commit covers both the work product and the updated
kanban.md.
- Before starting a subtask: move it from To Do → In Progress in
- Never have more than one subtask In Progress at a time.
This framework was born from a project where a single human operator coordinates AI agents. The initiative-driven structure maps naturally to how agents consume context:
- One initiative folder = one coherent context an agent can load and reason about end-to-end
glossary.mdgives agents shared vocabulary, reducing hallucination and misunderstandingTIMELINE.mdlets agents orient themselves historically before diving injournal.mdinside each initiative captures the why of decisions — critical for resumability across sessions
Place a CLAUDE.md at your project root that tells AI agents:
- Where the source of truth for current work lives
- Naming conventions
- How to start a new initiative
- Language policy
- What to do on every new term (add to glossary)
A ready-to-copy starter block is in the Starter templates section below. Adapt the project-specific paragraphs and commit.
- Pick a short
kebab-casename and today's date - Create
docs/YYYY-MM-DD-<name>/ - Add
README.md— purpose, status (plannedorin-progress), list of expected artifacts - Add
journal.mdwith the first entry - Append a row to
docs/TIMELINE.md - Commit
Starter blocks for every file are in the Starter templates section below.
The framework is language-agnostic, but opinionated about consistency:
- Content — pick one canonical language per project and stick to it. Avoid multilingual mixing inside a single document.
- Identifiers — always English (folder names, file names, YAML keys, ADR slugs, glossary term identifiers, code).
- Glossary — bilingual is fine and often useful: term identifier in English, definition in your canonical language.
- Translations — defer bilingual content (side-by-side EN/RU/etc.) until you have an external audience that demands it. Maintaining two in-sync versions during internal work is a trap.
Recommended stance: your docs/ folder is public and checked into git. Why:
- Makes the project self-documenting for new contributors (human or AI)
- Creates accountability for the quality of thinking captured
- Forces clarity; private notes tend to drift into vagueness
- Lets you link to decisions from commits, PRs, issues, and Slack without worrying about access
For genuinely private material, use .docs-local/ (add to .gitignore). Use it sparingly — the moment private notes outweigh public ones, you've lost the benefit of the system.
All starter content is below — copy and paste into your project. No tooling required.
---
title: Project Documentation — Overview
status: living
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [Your Name]
type: readme
language: en
---
# Documentation
This folder follows the [Initiative-Driven Documenting](https://github.com/ztnkv/initiative-driven-docs-framework) framework.
## Navigation
- **[`glossary.md`](./glossary.md)** — shared vocabulary used across all initiatives
- **[`TIMELINE.md`](./TIMELINE.md)** — chronological register of every initiative with its current status
- **`YYYY-MM-DD-<name>/`** — one folder per initiative, dated by start date
## How to read this
- **To understand the current state** — open `TIMELINE.md`, go to the most recent `in-progress` or `approved` initiative
- **To understand why something was decided** — read the initiative's `journal.md` and `decisions/`
- **To understand a term** — check `glossary.md` first
## How to start a new initiative
1. Pick a `kebab-case` name and today's date
2. `mkdir docs/YYYY-MM-DD-<name>/`
3. Add `README.md`, `journal.md`, and the main artifact
4. Append a row to `TIMELINE.md`
5. Commit---
title: Glossary — project terminology
status: living
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [Your Name]
type: glossary
language: en
---
# Glossary
Single source of truth for terms used across this project. Term identifier is in English; definition is in the project's canonical language.
Rule: every new term introduced in any initiative document is added here in the **same commit**.
## Core concepts
- **example-term** — placeholder. Replace with actual project terms.---
title: Timeline — chronology of initiatives
status: living
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [Your Name]
type: timeline
language: en
---
# Timeline
Chronological register of every initiative. Newest on top.
| Start date | Initiative | Status | Link |
| ---------- | ------------------ | ----------- | --------------------------------------------------------------------- |
| YYYY-MM-DD | Example Initiative | in-progress | [`YYYY-MM-DD-example-initiative/`](./YYYY-MM-DD-example-initiative/) |
## Key ADRs
Cross-initiative decisions worth surfacing at the top level.
- _None yet._---
title: <Initiative Name> — overview
status: in-progress
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [Your Name]
type: readme
language: en
---
# <Initiative Name> — overview
## Goal
One or two sentences explaining what this initiative is trying to achieve and why it matters.
## Status
**in-progress** — describe briefly where we are right now.
| Section / Artifact | State |
| ------------------ | -------------- |
| Goal agreed | ✅ |
| Main artifact | ⏳ in progress |
| Decisions logged | ⏺ not started |
## Artifacts
- [`<main-artifact>.md`](./<main-artifact>.md) — the primary deliverable (vision, rfc, plan, etc.)
- [`journal.md`](./journal.md) — living log of how the work unfolded
- `decisions/` — ADRs produced here (created on demand)
- [`kanban.md`](./kanban.md) — subtask board in Obsidian Kanban format (optional)
## Participants
- **Operator / Lead**: Your Name
- **AI partners**: Claude, etc.
## How to read this folder
- For the *current conclusion* — read the main artifact
- For *how we got there* — read `journal.md`
- For *specific decisions* — check `decisions/`---
title: Journal — <Initiative Name>
status: living
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [Your Name]
type: journal
language: en
---
# Journal — <Initiative Name>
Living log of work on this initiative. Entries in reverse-chronological order (newest on top).
---
## YYYY-MM-DD · Session N — <short-topic>
### What happened
One or two paragraphs describing what was worked on and what came out of the session.
### Key decisions
- Bullet list of decisions made in this session
- Link to ADRs if any were created: [`decisions/0001-example.md`](./decisions/0001-example.md)
### What's open
- Questions or topics deferred to the next session
### What's next
Where work will pick up in the next session.
------
kanban-plugin: basic
---
## To Do
- [ ] <First subtask>
- [ ] <Second subtask>
- [ ] <Third subtask>
## In Progress
## Done
---
title: ADR NNNN — <short decision title>
status: proposed
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [Your Name]
type: adr
language: en
---
# ADR NNNN — <short decision title>
## Status
**proposed** · **accepted** · **rejected** · **superseded by [ADR NNNN](./NNNN-replacement.md)**
## Context
What is the problem or situation that forces us to make this decision? What constraints are in play?
## Decision
The decision itself. Start with an action verb: "We will use X because Y."
## Consequences
### Positive
- What becomes easier or possible
### Negative
- What becomes harder or requires acceptance
### Neutral
- Notable side effects that are neither wins nor losses
## Alternatives considered
### Option A — <name>
- Brief description
- Why it was rejected
## References
- Links to related ADRs, RFCs, journals, or external articles# CLAUDE.md — instructions for AI agents working on this project
> Copy this file to your project root and adapt the sections marked `<<<>>>`. Remove this note once adapted.
## About this project
<<<Briefly describe what the project is. One or two sentences.>>>
`<Project Name>` — `<one-line description>`. `<Tech stack.>`
Source of truth for current work: the most recent initiative under [`docs/`](./docs/) with status `in-progress`, or the most recent `approved` one. Chronological register: [`docs/TIMELINE.md`](./docs/TIMELINE.md).
## Documentation framework
This project uses the [Initiative-Driven Documenting](https://github.com/ztnkv/initiative-driven-docs-framework) framework. Summary:
- Documentation is organized by **initiatives** — dated folders `docs/YYYY-MM-DD-<kebab-name>/`
- Each initiative is self-contained: `README.md`, `journal.md`, main artifact, optional `decisions/`, optional `kanban.md`
- Global layer: `docs/README.md`, `docs/glossary.md`, `docs/TIMELINE.md`
- `glossary.md` updated in the **same commit** that introduces a new term
- `TIMELINE.md` updated in the **same commit** that creates or closes an initiative
Full framework docs: https://github.com/ztnkv/initiative-driven-docs-framework
## Language
<<<Define the project's language policy.>>>
- **Communication with the user** — `<e.g. Russian>`
- **Document content** — `<e.g. Russian (canonical)>`
- **Identifiers** (folder names, file names, YAML keys, ADR slugs, code) — **English**, `kebab-case`
- **Glossary** — bilingual: term in English, definition in the canonical content language
## When the user starts a new initiative
1. Confirm the initiative name (`kebab-case`) and start date (usually today)
2. Create `docs/YYYY-MM-DD-<name>/` with:
- `README.md` (goal, status `in-progress`, list of expected artifacts)
- `journal.md` with the first dated entry
3. Append a row to [`docs/TIMELINE.md`](./docs/TIMELINE.md)
4. As work unfolds, fill in artifacts. Any new term → [`docs/glossary.md`](./docs/glossary.md) in the same commit.
## Kanban workflow (when requested)
When the user explicitly asks to create a Kanban board for an initiative and break work into subtasks:
1. Create `docs/YYYY-MM-DD-<name>/kanban.md` using Obsidian Kanban format:
- Front-matter: `kanban-plugin: basic`
- Three columns only: **To Do**, **In Progress**, **Done**
- All planned subtasks start under **To Do**
2. Work through subtasks **sequentially, one at a time**:
- Before starting a subtask: move it **To Do → In Progress** in `kanban.md`
- After completing a subtask: move it **In Progress → Done** in `kanban.md`
- Commit after each completed subtask — commit covers both the work and the updated `kanban.md`
3. Never have more than one subtask **In Progress** at a time.
## Editing conventions
- Front-matter on every Markdown file (`title`, `status`, `created`, `updated`, `authors`, `type`, `language`)
- Initiative folder names: `YYYY-MM-DD-<kebab-name>/`
- File names: lowercase, `kebab-case.md`; numeric prefix `NNNN-` only for ADRs in `decisions/`
- Initiative statuses: `planned → in-progress → approved → superseded`
## Private material
For notes that should not ship publicly — use `.docs-local/` (in `.gitignore`). **Default stance: everything in `docs/` is public.**
## Project-specific notes
<<<Add any project-specific instructions here: coding conventions, review process, restricted folders, deployment notes, etc.>>>Q: What if one piece of work takes multiple initiatives?
A: That's fine. Chain them with links in README.md front-matter or a superseded-by field. The TIMELINE tells the story.
Q: What if an initiative spans months? A: Use the start date in the folder name. Keep journal entries dated inside the journal.
Q: Can two initiatives run in parallel?
A: Yes. Initiatives are content-oriented, not resource-oriented. Two initiatives can be in-progress simultaneously.
Q: Where do I put code?
A: Not in docs/. This framework is for the knowledge around code — visions, decisions, plans, journals. Code lives in src/ or equivalent.
Q: Do I need decisions/ in every initiative?
A: No. Only create decisions/ when an initiative actually produces ADRs.
Q: What about tickets, issues, PRs?
A: Keep them in your issue tracker. Link to them from journal.md entries. Don't duplicate.
Extracted from the Human Become Operator project, where the framework emerged from the need to keep a solo-developer-plus-AI-agents workflow coherent across long planning cycles and multiple session boundaries.
MIT — use it, adapt it, fork it, no warranty.