{ "markdown": "# okf-project-template\n\nA starter template for **agent-driven projects** that keeps project knowledge,\ndecisions, and plan in a small set of Markdown docs an AI agent maintains — and,\ncrucially, *instructions that tell the agent how to work* so those docs don't rot.\n\nIt's built on the\n[OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\nknowledge-catalog format (that's the `context/` bundle) and adds a\nplanning/decisions/working-hygiene layer around it. It is **not** an official OKF\nartifact — OKF is one of the four parts.\n\n## Quick Start\n\n**1. Make your own copy.** On this repo's GitHub page, click **\"Use this\ntemplate\" → Create a new repository** (or\n`gh repo create my-project --template /okf-project-template --private`).\nThen clone your new repo locally.\n\n**2. Customize it — let an agent walk you through it (recommended).** Open the new\nproject in your coding agent (e.g. Claude Code) and paste this:\n\n> I just created this project from **okf-project-template** and it still has the\n> template's placeholders. Please run the setup dialog in `SETUP.md`: ask me what\n> you need to know, fill in the project's docs (name, scope, preferences, first\n> tasks), and remove the example/placeholder content when we're done.\n\nThe agent runs a short Q&A, fills in the docs, deletes the example artifacts, and\nremoves the onboarding scaffolding — leaving a clean, customized project. Prefer\nto do it by hand? Follow [Manual setup](#manual-setup) below instead.\n\n**3. Start working.** Your project now has a knowledge bundle (`context/`), a\ndecision register (ADRs), a living plan (`planning/`), and agent working rules\n(`AGENTS.md`) — all wired together.\n\n## The doc taxonomy\n\nFour top-level doc directories, each with one job:\n\n| Dir | Role | Audience |\n|-----|------|----------|\n| `references/` | Source-of-truth inputs (specs, standards, prior art), **append-only**: each snapshot is immutable; ingests add, never edit. | inputs |\n| `context/` | **Agent-owned** knowledge bundle (OKF): synthesized concepts + the decision register (ADRs). | agent |\n| `planning/` | **Volatile** plan + present state — `ROADMAP.md` (scope/phases/open forks) and `PROGRESS.md` (Now/Next). | both |\n| `docs/` | **Human-facing** authored guides (terse). | humans |\n\nPlus [`AGENTS.md`](AGENTS.md) at the root — the *how-to-work* instructions an\nagent loads: the doc roles above, a pre-commit checklist, and the\nplanning-hygiene rules that keep the four from re-narrating each other. The\nreasoning behind those rules — the failure mode each one prevents — is in\n[`context/workflow-rationale.md`](context/workflow-rationale.md).\n\n`AGENTS.md` is the one canonical copy, and it is vendor-neutral by convention.\n[`CLAUDE.md`](CLAUDE.md) is a one-line adapter — `@AGENTS.md` — because Claude\nCode auto-loads that filename; agents that read `AGENTS.md` need no adapter at\nall. If yours reads a third name, add another thin pointer. **Never a second\ncopy of the rules**: two copies of a doc that tells you not to keep two copies\nof a doc is the failure this whole template exists to prevent.\n\n> **This section is the template's pitch, not project content.** Setup deletes it\n> along with Quick Start and Manual setup: a set-up project's `README.md` is\n> human-facing (what it is, how to build it, how it's laid out), and the workflow\n> directives live where agents read them — `AGENTS.md` and `context/`.\n\n## Manual setup\n\nThe by-hand alternative to the agent dialog (Quick Start step 2) — the same\nresult, done yourself:\n\n1. Copy/clone this tree into your new project (or use it as a GitHub template).\n2. Fill in [`AGENTS.md`](AGENTS.md): the project description (top) and the\n **Project preferences** section (commit policy, repo layout, build/test/run).\n Leave `CLAUDE.md` as the one-line `@AGENTS.md` import (drop its comment).\n3. **Rewrite this `README.md` as your project's own** — it should end up\n **human-facing**: what the project is, how to build and run it, how it's laid\n out, its license. Delete *all* of the template's pitch and adoption sections —\n title/intro, Quick Start, this Manual setup section, \"The doc taxonomy\", \"Why\n these rules\", and the template's Structure block. Don't carry the workflow\n directives into your README: they already live where agents read them\n (`AGENTS.md` and [`context/`](context/workflow-rationale.md)), and a second\n copy in the README is exactly the duplication these rules exist to prevent.\n Keep Quick Start only if you want others to re-template from your repo.\n4. Set the real `generated:` (`by:` an actor, `at:` an ISO 8601 timestamp) in the\n frontmatter of `context/CONVENTIONS.md` and `context/workflow-rationale.md`;\n trim the `type` vocabulary to your domain.\n5. Delete (or replace) the **example artifacts**, each marked with an\n `[EXAMPLE — replace or delete]` note:\n - `context/decisions/0001-example-decision.md` (a worked ADR)\n - the example entry in `context/log.md`\n - the example rows/sections in `context/index.md`,\n `context/decisions/index.md`, `planning/ROADMAP.md`, `planning/PROGRESS.md`\n6. Decide on [`LICENSE`](LICENSE): the template ships **0BSD** (permissive, no\n attribution). Keep it for your project or swap in your own — and update the\n README license line (step 3) to match, so the two can't contradict each other.\n7. Start working. On the first real decision, write ADR `0001`.\n\nTo find every spot that needs your attention (and confirm you got them all when\ndone), grep for the markers:\n`grep -rnE '|<[a-z][^>]*>|\\[EXAMPLE|