Repository navigation
Expand file tree
/
Copy pathREADME.html
More file actions
585 lines (518 loc) · 36.5 KB
/
Copy pathREADME.html
File metadata and controls
585 lines (518 loc) · 36.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Project Knowledge Base Template</title>
<style>
:root {
--bg: #fafafa;
--fg: #1a1a1a;
--muted: #666;
--accent: #2563eb;
--accent-light: #dbeafe;
--border: #e5e7eb;
--code-bg: #f3f4f6;
--card-bg: #fff;
--step-bg: #eff6ff;
--tier1: #059669;
--tier1-bg: #ecfdf5;
--tier2: #d97706;
--tier2-bg: #fffbeb;
--tier3: #7c3aed;
--tier3-bg: #f5f3ff;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #111;
--fg: #e5e5e5;
--muted: #999;
--accent: #60a5fa;
--accent-light: #1e3a5f;
--border: #333;
--code-bg: #1e1e1e;
--card-bg: #1a1a1a;
--step-bg: #172033;
--tier1: #34d399;
--tier1-bg: #0d2818;
--tier2: #fbbf24;
--tier2-bg: #2d1f04;
--tier3: #a78bfa;
--tier3-bg: #1e1533;
}
}
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
background: var(--bg);
color: var(--fg);
line-height: 1.7;
max-width: 780px;
margin: 0 auto;
padding: 2rem 1.5rem 4rem;
}
h1 {
font-size: 2rem;
font-weight: 700;
margin-bottom: 0.5rem;
letter-spacing: -0.02em;
}
.subtitle {
color: var(--muted);
font-size: 1.1rem;
margin-bottom: 2.5rem;
}
h2 {
font-size: 1.4rem;
font-weight: 600;
margin-top: 3rem;
margin-bottom: 1rem;
padding-bottom: 0.4rem;
border-bottom: 2px solid var(--border);
}
h3 {
font-size: 1.1rem;
font-weight: 600;
margin-top: 1.8rem;
margin-bottom: 0.6rem;
}
p { margin-bottom: 1rem; }
a { color: var(--accent); text-decoration: none; }
a:hover { text-decoration: underline; }
ul, ol { margin-bottom: 1rem; padding-left: 1.5rem; }
li { margin-bottom: 0.4rem; }
code {
font-family: "SF Mono", "Cascadia Code", "Fira Code", Consolas, monospace;
font-size: 0.88em;
background: var(--code-bg);
padding: 0.15em 0.4em;
border-radius: 4px;
}
pre {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem 1.25rem;
overflow-x: auto;
margin-bottom: 1.25rem;
font-size: 0.88rem;
line-height: 1.6;
}
pre code {
background: none;
padding: 0;
border-radius: 0;
}
.step-card {
background: var(--step-bg);
border: 1px solid var(--accent);
border-radius: 10px;
padding: 1.5rem;
margin-bottom: 1.5rem;
}
.step-card h3 {
margin-top: 0;
color: var(--accent);
font-size: 1.15rem;
}
.step-number {
display: inline-flex;
align-items: center;
justify-content: center;
width: 1.7rem;
height: 1.7rem;
background: var(--accent);
color: #fff;
border-radius: 50%;
font-weight: 700;
font-size: 0.9rem;
margin-right: 0.5rem;
vertical-align: middle;
}
.agent-option {
background: var(--card-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem 1.25rem;
margin-bottom: 0.75rem;
}
.agent-option strong { color: var(--accent); }
.tier-badge {
display: inline-block;
font-size: 0.75rem;
font-weight: 600;
padding: 0.15em 0.6em;
border-radius: 999px;
vertical-align: middle;
margin-left: 0.4rem;
}
.tier-1 { background: var(--tier1-bg); color: var(--tier1); }
.tier-2 { background: var(--tier2-bg); color: var(--tier2); }
.tier-topic { background: var(--tier3-bg); color: var(--tier3); }
.dir-tree {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1.25rem 1.5rem;
margin-bottom: 1.25rem;
font-family: "SF Mono", "Cascadia Code", "Fira Code", Consolas, monospace;
font-size: 0.88rem;
line-height: 1.8;
}
.dir-tree .label {
color: var(--muted);
font-style: italic;
}
.file-role {
background: var(--card-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1.25rem 1.5rem;
margin-bottom: 1rem;
}
.file-role h3 {
margin-top: 0;
font-family: "SF Mono", "Cascadia Code", "Fira Code", Consolas, monospace;
font-size: 1rem;
}
.file-role p:last-child { margin-bottom: 0; }
.principle {
margin-bottom: 1rem;
padding-left: 1rem;
border-left: 3px solid var(--accent);
}
.principle strong { display: block; margin-bottom: 0.25rem; }
.callout {
background: var(--tier1-bg);
border-left: 4px solid var(--tier1);
border-radius: 0 8px 8px 0;
padding: 1rem 1.25rem;
margin-bottom: 1.25rem;
}
hr {
border: none;
border-top: 2px solid var(--border);
margin: 2.5rem 0;
}
.copy-hint {
font-size: 0.82rem;
color: var(--muted);
margin-top: -0.75rem;
margin-bottom: 1.25rem;
}
</style>
</head>
<body>
<h1>Project Knowledge Base Template</h1>
<p class="subtitle">A structured directory template for maintaining durable project knowledge that AI agents (and humans) can navigate efficiently. Works with Claude Code, claude.ai, Claude Desktop, and any agent that reads files.</p>
<h2>The Problem This Solves</h2>
<p>AI agents lose context between conversations. Every new session starts cold. Project knowledge scattered across chat logs, docs, and memory is expensive to re-discover and easy to get wrong.</p>
<p>This template gives each project a small, predictable set of files that an agent can load selectively based on what kind of work is happening — without dumping everything into context at once.</p>
<h2 id="setup">Setup</h2>
<p>These steps assume an agent that can read and write a folder on your computer, such as Claude Code or Cowork. If you work in claude.ai in a browser, where the agent has no access to your local files, use <a href="#alternative-setup-google-drive-or-similar">Alternative Setup: Google Drive or Similar</a> instead.</p>
<div class="step-card">
<h3><span class="step-number">1</span> Place the Template</h3>
<p>Put this <code>project-template</code> directory inside the parent directory where you want your project knowledge base to live. For example:</p>
<pre><code>C:\Users\you\Documents\KnowledgeBase\project-template\ (Windows)
/home/you/KnowledgeBase/project-template/ (Linux)
~/KnowledgeBase/project-template/ (macOS)</code></pre>
<p>The template stays here as a reference. When you (or your agent) start a new project, the agent copies the template directory, renames it, and fills in the files from your conversation.</p>
</div>
<div class="step-card">
<h3 id="configure-your-agent"><span class="step-number">2</span> Configure Your Agent</h3>
<p>Your agent needs to know where your knowledge base directories live and how to use them. Add the following to your agent's persistent instructions, replacing <code><YOUR_KB_PATH></code> with your actual path:</p>
<pre><code>My project knowledge base is stored at <YOUR_KB_PATH>.
Each subdirectory is a project KB. The `project-template` directory
contains the blank template — copy it to create a new project KB.
To understand any project, start with its DOCUMENT-MAP.md — it indexes
all files and describes when to load each one.</code></pre>
<p class="copy-hint">Copy this text block and paste it into your agent's instructions.</p>
<p>For example, a Windows user with their knowledge base in their Documents folder would use:</p>
<pre><code>My project knowledge base is stored at C:\Users\jane\Documents\KnowledgeBase.
Each subdirectory is a project KB. The `project-template` directory
contains the blank template — copy it to create a new project KB.
To understand any project, start with its DOCUMENT-MAP.md — it indexes
all files and describes when to load each one.</code></pre>
<h3>Where to add this, by platform:</h3>
<div class="agent-option">
<strong>claude.ai / Claude Desktop / Claude Mobile</strong><br>
Add it to your <strong>Profile Instructions</strong>: click your initials → Settings → "Instructions for Claude." This applies to all conversations. Alternatively, add it to a specific Project's instructions if you only want it scoped to one project.<br>
<small>See: <a href="https://support.claude.com/en/articles/10185728-understanding-claude-s-personalization-features">Personalization guide</a> · <a href="https://support.claude.com/en/articles/9519177-how-can-i-create-and-manage-projects">Projects guide</a></small>
</div>
<div class="agent-option">
<strong>Claude Code</strong><br>
Add it to your <code>~/.claude/CLAUDE.md</code> file (user-level instructions, loaded every session).<br>
<small>See: <a href="https://docs.anthropic.com/en/docs/claude-code/memory">CLAUDE.md documentation</a></small>
</div>
<div class="agent-option">
<strong>Other agents</strong><br>
Consult your agent's documentation for how to add persistent system-level instructions.
</div>
<div class="callout">That's it. Your agent can discover the template, copy it for new projects, and fill in the files based on your conversations.</div>
</div>
<div class="step-card" style="border-color: var(--tier3); background: var(--tier3-bg);">
<h3 style="color: var(--tier3);">Bonus: Use KB Directories as Claude Projects</h3>
<p>Each project KB directory can also serve as a <strong>Claude Project</strong> — either as a chat project on claude.ai/Claude Desktop, or as a Cowork project. Since each directory is a self-contained workspace with its own files and context, it maps naturally to Claude's project model:</p>
<div class="agent-option">
<strong>Chat Projects (claude.ai / Claude Desktop)</strong><br>
Create a project and upload the KB directory's files to the project knowledge base, or add <code>00-project-brief.md</code> as project instructions.<br>
<small>See: <a href="https://support.claude.com/en/articles/9519177-how-can-i-create-and-manage-projects">Projects guide</a></small>
</div>
<div class="agent-option">
<strong>Cowork Projects (Claude Desktop)</strong><br>
Cowork can create projects directly from local folders on your computer. Point it at a KB directory and it becomes a Cowork project with its own instructions, context, and memory.<br>
<small>See: <a href="https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork">Organize tasks with projects in Cowork</a> · <a href="https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork">Getting started with Cowork</a></small>
</div>
</div>
<h2 id="alternative-setup-google-drive-or-similar">Alternative Setup: Google Drive or Similar</h2>
<p>When the agent cannot reach a folder on your computer, the knowledge base can live in Google Drive, and the agent reaches it through the Google Drive connector. This is the setup for claude.ai in a browser. The directory structure, the loading tiers, and the file roles are the same as everywhere else in this document. What changes is how files are found, how they are updated, and what format deliverables take.</p>
<p>The KB documents stay plain Markdown in Drive. That keeps them readable by any tool, and it means the same Drive folder can also be synced to a computer and used by a local agent with the instructions in <a href="#setup">Setup</a>.</p>
<div class="callout">This section is written for Google Drive. The approach very likely carries over to other cloud storage that has a Claude connector, but working out the details for your service is up to you. The one hard requirement is a connector that can create, rename, and trash files; a read-only connector cannot hold a knowledge base. Replace the connection steps with your service's own, and the Google file types for deliverables with your service's native formats.</div>
<div class="step-card">
<h3><span class="step-number">1</span> Put the Template in Drive</h3>
<p>Create a folder in Google Drive to hold your knowledge base (for example <code>KnowledgeBase</code>) and upload this <code>project-template</code> folder into it. If you have the template as a zip, unpack it first and upload the folder: Drive stores a zip as a single file and does not unpack it. After the upload, check that the files are still <code>.md</code> files and were not converted to Google Docs.</p>
<p>Use the Google account that should own this knowledge, either a personal account or your company's Google Workspace account. The agent signs in as that account and can reach only the files it can open.</p>
</div>
<div class="step-card">
<h3><span class="step-number">2</span> Connect Google Drive</h3>
<ol>
<li>In claude.ai, go to <strong>Customize > Connectors</strong>, find <strong>Google Drive</strong>, and select <strong>Connect</strong>.</li>
<li>Sign in to the Google account that holds the KB folder and grant the requested permissions. A company account signs in the way it normally does, including through company single sign-on.</li>
<li>In each conversation that uses a knowledge base, select <strong>+</strong> in the message box, select <strong>Connectors</strong>, and turn <strong>Google Drive</strong> on. The connection is made once; the toggle is per conversation.</li>
</ol>
<p>On Team and Enterprise plans, Google Drive does not appear in the connector list until an Owner adds it for the organization. Each member then connects their own Google account.<br>
<small>See: <a href="https://claude.com/docs/connectors/google/drive">Google Drive connector guide</a> · <a href="https://support.claude.com/en/articles/10166901-use-google-workspace-connectors">Use Google Workspace connectors</a></small></p>
</div>
<div class="step-card">
<h3><span class="step-number">3</span> Configure Your Agent</h3>
<p>Add the following to your <strong>Profile Instructions</strong>, or to a <strong>Project's instructions</strong> to scope it to one project, replacing <code><YOUR_KB_FOLDER></code> with the name of your folder (for example <code>KnowledgeBase</code>). Use it in place of the block in <a href="#configure-your-agent">Setup</a>, not in addition to it. The agent reads these instructions in every conversation but does not reload this README, so the block carries the working rules in full.</p>
<pre><code>My project knowledge base is stored in Google Drive, in the folder
"<YOUR_KB_FOLDER>". Reach it with the Google Drive connector. If more
than one folder has that name, ask me which one. Each sub-folder is one
project's KB. The `project-template` folder contains the blank template;
its README.md explains how to create a new project KB from it.
To understand any project, start with its DOCUMENT-MAP.md, which indexes
all files and describes when to load each one.
If the Google Drive connector is not available in this conversation,
tell me and stop. Do not work from memory or create local files instead.
FINDING AND NAMING FILES
- Refer to KB files by name and path (for example `plans/api-design.md`),
never by Drive link or file ID. An updated file gets a new ID, so its
old link stops working.
- Drive allows two items with the same name in one folder. Before you
create or rename any file or folder, list the destination folder and
compare names ignoring upper and lower case. If the name is already
there, do not create a second one: update the existing file, or ask me.
- Create a new file directly under its final name, after that check.
UPDATING A MARKDOWN FILE
The connector cannot change the content of an existing file, so every
edit, however small, replaces the whole file. Collect the changes for one
file into one replacement, then:
1. Read the current file from Drive, in full, right before you change
it. Make the change in your own working copy.
2. Create the new version in the same folder as `<name>.md.new`, as
plain Markdown text, not converted to a Google Doc.
3. Read `<name>.md.new` back from Drive and confirm it is complete and
matches your working copy. If it does not, fix it before going on.
4. Only then move the old `<name>.md` to the trash.
5. Rename `<name>.md.new` to `<name>.md`.
6. List the folder and confirm it holds exactly one `<name>.md` and no
`.new` file.
I approve the trash in step 4 as part of this procedure. It is the only
time you may trash a KB file without asking me first. To archive or
relocate a file, move it; do not recreate it.
If you find a `.md.new` file you did not just create, an earlier update
was interrupted. If the original is missing, the `.new` file had already
been checked: rename it into place and tell me. If the original is still
there, compare the two and ask me which to keep.
DELIVERABLES
Create finished deliverables under `output/` as native Google files
unless I ask for another format: a Google Doc for a written document, a
Google Sheet for tabular data, Google Slides for a presentation. Change
an existing Google file in place so its link stays the same. If you
cannot edit it in place, tell me instead of creating a second copy.
The KB documents themselves (the top-level files, `plans/`, `reference/`,
`ongoing/`, `journal/`, `scratch/`) stay Markdown.</code></pre>
<p class="copy-hint">Copy this text block and paste it into your agent's instructions.</p>
</div>
<h3>Why Updates Work This Way</h3>
<p>The Drive connector can create, rename, move, and trash a file, but it cannot change the content of a file that already exists. An edit to a Markdown document is therefore a replacement, and the procedure in the block is ordered so that there is never a moment without a complete copy: the new version is written and read back before the old one is touched.</p>
<ul>
<li><strong>Links to KB documents do not survive an update.</strong> The replacement is a new file with a new ID. This is why the block says to refer to files by name and path, which is also how <code>DOCUMENT-MAP.md</code> already refers to them.</li>
<li><strong>Names are not unique in Drive.</strong> Two files called <code>02-status.md</code>, or <code>02-status.md</code> and <code>02-Status.md</code>, can sit in the same folder, and an agent that finds two cannot tell which is live. The case-insensitive check before every create and rename is what prevents it.</li>
<li><strong>Old versions go to Drive's trash.</strong> You can restore them from there until Drive deletes them, 30 days after they were trashed. The agent cannot restore a trashed file itself, which is the reason it checks the new version first.</li>
<li><strong>Each update asks for approval three times by default</strong>, once each for the create, the trash, and the rename. Under <strong>Customize > Connectors > Google Drive > Tool permissions</strong>, each tool can be set to <strong>Always allow</strong>, <strong>Needs approval</strong>, or <strong>Blocked</strong>. Allowing create and rename while leaving trash on <strong>Needs approval</strong> cuts this to one prompt per update, at the step that matters. On Team and Enterprise plans, Owners decide whether members may skip approvals.</li>
<li><strong>One conversation at a time per file.</strong> Two conversations that update the same document replace each other's work, because each writes back the whole file it read.</li>
</ul>
<h3>Deliverables as Google Files</h3>
<p>Finished deliverables in <code>output/</code> default to native Google Docs, Sheets, and Slides, because the people you share them with can open, comment on, and edit them directly in Drive. Unlike the Markdown documents, a native Google file can be changed in place and keeps its link. Editing an existing Google file from the chat is a separate capability from the Drive connector and may not be available in every conversation or plan; where it is not, Drive can still create the file but cannot change it afterward, and the block tells the agent to say so rather than leave you with two copies.</p>
<p>The KB documents themselves are deliberately not Google Docs. Converting Markdown to a Doc and back tends to damage code blocks, tables, and formatting, and it would tie the knowledge base to one vendor's editor.</p>
<hr>
<h2>How It Works: Tiered Loading</h2>
<p>Context windows are finite. The template is organized around a loading strategy so agents only read what's relevant:</p>
<ul>
<li><strong>Tier 1 <span class="tier-badge tier-1">Always Load</span></strong> — <code>00-project-brief.md</code> — enough to orient any conversation in under 500 words.</li>
<li><strong>Tier 2 <span class="tier-badge tier-2">Working Sessions</span></strong> — <code>02-status.md</code>, <code>03-decisions.md</code>, <code>04-backlog.md</code> — progressively deeper context pulled in when relevant.</li>
<li><strong>Topic-specific <span class="tier-badge tier-topic">On Demand</span></strong> — <code>plans/</code>, <code>reference/</code> — detailed docs pulled in only when working on that specific area.</li>
</ul>
<p>An agent starting a new conversation reads the brief. If the conversation turns to active implementation, it pulls in status and decisions. If it needs the specifics of a particular subsystem, it reads the relevant plan or reference doc. The <code>DOCUMENT-MAP.md</code> file tells it what exists and when to load each document.</p>
<p>This means a quick question costs ~500 tokens of context. A deep implementation session might load 3–5 documents. Nothing loads everything.</p>
<h2>Directory Structure</h2>
<div class="dir-tree">
your-project/<br>
00-project-brief.md <span class="label">— Vision, goals, architecture, current phase (Tier 1)</span><br>
02-status.md <span class="label">— Phase status, tasks, what's next (Tier 2A)</span><br>
03-decisions.md <span class="label">— Key decisions with rationale (Tier 2B)</span><br>
04-backlog.md <span class="label">— Ideas, links, future exploration (Tier 2C)</span><br>
DOCUMENT-MAP.md <span class="label">— File index and loading guide (live material only)</span><br>
ARCHIVE-MAP.md <span class="label">— Index of archived material (load only for history)</span><br>
plans/ <span class="label">— Actionable execution plans (per-topic)</span><br>
archive/ <span class="label">— Completed/superseded plans (any directory may have one)</span><br>
reference/ <span class="label">— Full-detail research, deep dives, technical reference</span><br>
output/ <span class="label">— Finished or near-finished deliverables</span><br>
documents/ <span class="label">— Reports, memos, proposals, written deliverables</span><br>
diagrams/ <span class="label">— Flowcharts, org charts, architecture visuals</span><br>
images/ <span class="label">— Generated images, screenshots, visual assets</span><br>
data/ <span class="label">— Spreadsheets, CSVs, analysis results, exports</span><br>
ongoing/ <span class="label">— Operational runbooks, living process docs</span><br>
journal/ <span class="label">— Historical archives, session logs</span><br>
scratch/ <span class="label">— Working artifacts that haven't graduated yet</span>
</div>
<h2>File Roles</h2>
<div class="file-role">
<h3>00-project-brief.md <span class="tier-badge tier-1">Tier 1</span></h3>
<p>The single document an agent reads to understand your project. Contains:</p>
<ul>
<li>What the project is and why it exists (vision)</li>
<li>Concrete goals</li>
<li>High-level architecture or approach</li>
<li>Current phase / immediate focus</li>
<li>Top decisions that shape everything</li>
</ul>
<p>Keep this concise — under 500 words is ideal. It should orient a cold-start conversation, not explain every detail.</p>
</div>
<div class="file-role">
<h3>02-status.md <span class="tier-badge tier-2">Tier 2A</span></h3>
<p>Where you are and what's next. Phase overview table, per-phase task lists, cross-cutting TODOs. Pull this in for any conversation involving active work.</p>
<p>Update this file as phases progress. When a phase completes, move the detailed history to <code>journal/</code> and keep only the summary here.</p>
</div>
<div class="file-role">
<h3>03-decisions.md <span class="tier-badge tier-2">Tier 2B</span></h3>
<p>Currently relevant decisions with enough rationale to be useful during implementation. Each entry captures what was decided, why, and what alternatives were considered.</p>
<p>Decisions age out. When a decision is no longer load-bearing (the thing it decided is done and stable), archive it or remove it. This file should reflect the active decision landscape, not a complete history.</p>
</div>
<div class="file-role">
<h3>04-backlog.md <span class="tier-badge tier-2">Tier 2C</span></h3>
<p>Low-friction landing zone for ideas, links, tools to evaluate, integration concepts, and half-formed thoughts. Pull this in during planning sessions, not during implementation. Things here are not commitments — they're possibilities.</p>
</div>
<div class="file-role">
<h3>DOCUMENT-MAP.md</h3>
<p>Central index of every file in the project. For each file: what it is, when to load it. This is what an agent reads to decide which documents are relevant to the current conversation.</p>
<p>Update this whenever you add or rename a file. It's the table of contents for the live knowledge base; archived material is indexed in <code>ARCHIVE-MAP.md</code> instead, so this map stays small.</p>
</div>
<div class="file-role">
<h3>ARCHIVE-MAP.md</h3>
<p>Index of everything archived: where each item was, where it is now, when and why it was archived, and what superseded it. Agents load it only when going back into the project's history, never as part of normal orientation. The table doubles as the undo list, which matters when the KB is not under version control.</p>
</div>
<div class="file-role">
<h3>Archiving</h3>
<p>Anything completed, superseded, or otherwise past — a finished plan, a review of merged work, scratch from a closed task — moves into an <code>archive/</code> subdirectory beside it: <code>plans/archive/</code>, <code>reviews/archive/</code>, <code>scratch/archive/</code>, and so on. Any directory may have one; create it when first needed. On each move, remove the file's row from <code>DOCUMENT-MAP.md</code> and add a row to <code>ARCHIVE-MAP.md</code>. Archive rather than delete: archived files cost nothing to keep, and they record why things are the way they are. Delete only what has no value as history, such as regenerable build output or checked-out copies of code.</p>
</div>
<div class="file-role">
<h3>plans/</h3>
<p>Actionable documents: implementation plans, design specs, feature breakdowns. Each plan is a self-contained document for a specific topic. An agent loads the plan relevant to the current work, not all plans.</p>
<p>Plans that are completed or superseded move to <code>plans/archive/</code> (see Archiving).</p>
</div>
<div class="file-role">
<h3>reference/</h3>
<p>The complete, detailed record: research findings, deep dives, landscape analyses, technical reference material, API documentation. Things you'd look up when you're "in the weeds" on a specific topic.</p>
<p>Reference documents are as complete and detailed as possible. This is the one place in the KB where length is a feature: the point of a reference is that nobody ever has to redo the research. Whenever research is done for a project, especially detailed research, the default is to write the full, completed output here <strong>first</strong>. Summaries, syntheses, and briefs derived from it are produced <strong>afterward</strong>, shaped to the current need, and they are not references, so they do not live here unless you're told otherwise. They go to <code>output/documents/</code> (a deliverable), <code>03-decisions.md</code> (a decision), <code>plans/</code> (a plan), or simply into the conversation.</p>
</div>
<div class="file-role">
<h3>ongoing/</h3>
<p>Operational runbooks and living process documents — things that describe how to do recurring operations, not one-time plans.</p>
</div>
<div class="file-role">
<h3>journal/</h3>
<p>Historical archives. When status updates, decision logs, or phase details get long, rotate the old content here, and add a row to <code>ARCHIVE-MAP.md</code>. Useful for understanding how the project evolved, but rarely loaded. (Whole files that are past go to an <code>archive/</code> subdirectory instead; <code>journal/</code> is for content rotated out of the living top-level files.)</p>
</div>
<div class="file-role">
<h3>output/</h3>
<p>Finished or near-finished deliverables — things the agent produced that you'll use, share, or submit. Organized into subdirectories by type:</p>
<ul>
<li><strong>documents/</strong> — Reports, memos, proposals, analyses, written deliverables. Summaries and syntheses distilled from <code>reference/</code> material belong here when they are deliverables. Project-specific outputs like reviews or reports can go here or in their own subdirectory under <code>output/</code> — whatever feels natural.</li>
<li><strong>diagrams/</strong> — Flowcharts, org charts, architecture visuals, process maps.</li>
<li><strong>images/</strong> — Generated images, screenshots, visual assets.</li>
<li><strong>data/</strong> — Spreadsheets, CSVs, analysis results, data exports.</li>
</ul>
<p>The subdirectories are suggestions — use what fits your project, ignore what doesn't, add new ones if needed.</p>
</div>
<div class="file-role">
<h3>scratch/</h3>
<p>Working artifacts: drafts, explorations, calculations, intermediate outputs. When something in scratch matures, graduate it to <code>plans/</code>, <code>reference/</code>, or <code>output/</code>. When it's no longer useful, delete it.</p>
</div>
<h2>How Agents Should Use This</h2>
<p>If you're an AI agent reading this, here's the protocol:</p>
<h3>Creating a New Project KB</h3>
<p>When the user starts a new project or you determine one is needed:</p>
<ol>
<li>Create a sibling directory named after the project, and copy in <strong>only the project files</strong>: <code>00-project-brief.md</code>, <code>02-status.md</code>, <code>03-decisions.md</code>, <code>04-backlog.md</code>, <code>DOCUMENT-MAP.md</code>, <code>ARCHIVE-MAP.md</code>, plus the <code>plans/</code> and <code>reference/</code> directories.</li>
<li><strong>Do NOT copy <code>README.md</code>, <code>README.html</code>, or <code>project-template.zip</code> into the new project</strong> — those document the template <em>itself</em>, not any project. A project's <code>00-project-brief.md</code> is its README (the single orient-me document), and <code>DOCUMENT-MAP.md</code> is its canonical entry point. (A project may add its own <code>README.md</code> later if it has a real need — e.g. it gets published to a git remote — but it is never copied from the template.)</li>
<li>Fill in <code>00-project-brief.md</code> based on what you know from the conversation.</li>
<li>Update <code>DOCUMENT-MAP.md</code> with the project name in the directory tree.</li>
<li>The remaining files can stay as templates until content is needed.</li>
</ol>
<h3>Loading an Existing Project KB</h3>
<ol>
<li><strong>Start with <code>DOCUMENT-MAP.md</code></strong> to understand what files exist and when to load them.</li>
<li><strong>Always read <code>00-project-brief.md</code></strong> at the start of any conversation about this project.</li>
<li><strong>Load Tier 2 files based on the task:</strong>
<ul>
<li>Doing active work? Load <code>02-status.md</code>.</li>
<li>Making implementation decisions? Load <code>03-decisions.md</code>.</li>
<li>Planning or brainstorming? Load <code>04-backlog.md</code>.</li>
</ul>
</li>
<li><strong>Load plans/reference on demand</strong> — only when the conversation is specifically about that topic.</li>
<li><strong>Load <code>ARCHIVE-MAP.md</code> only when going back into history</strong> — something past is referenced, or the question is how the project got here. Archived files are otherwise out of scope, and searches can skip them (e.g. <code>grep --exclude-dir=archive</code>).</li>
<li><strong>Don't load everything.</strong> The whole point is selective loading. If you're answering a quick question, the brief is probably enough.</li>
</ol>
<h3>Writing Back</h3>
<p>When you produce knowledge worth keeping:</p>
<ul>
<li>Implementation plans go in <code>plans/</code>.</li>
<li>Research, deep dives, and investigations go in <code>reference/</code> <strong>in full, as the first write</strong> — before any summary exists. Then synthesize or summarize for the need at hand. The synthesis goes to <code>output/</code>, <code>03-decisions.md</code>, <code>plans/</code>, or the conversation — never to <code>reference/</code> unless directed otherwise.</li>
<li>Finished deliverables go in <code>output/</code> (documents, diagrams, images, data as appropriate).</li>
<li>Decisions go in <code>03-decisions.md</code> (brief entry) with detailed analysis linked from <code>plans/</code> or <code>reference/</code>.</li>
<li>Update <code>DOCUMENT-MAP.md</code> when adding new files.</li>
<li>When something is past, archive it (see Archiving): move it to the <code>archive/</code> beside it, drop its <code>DOCUMENT-MAP.md</code> row, add an <code>ARCHIVE-MAP.md</code> row.</li>
<li>Update <code>02-status.md</code> when phase status changes.</li>
<li>Use <code>scratch/</code> for intermediate work that might graduate later.</li>
<li>If the KB lives in Google Drive or similar cloud storage, follow the update procedure and deliverable formats in <a href="#alternative-setup-google-drive-or-similar">Alternative Setup: Google Drive or Similar</a>.</li>
</ul>
<h2>Design Principles</h2>
<div class="principle">
<strong>Files are the source of truth.</strong>
Not chat logs, not memory systems, not databases. Files on disk that any tool can read.
</div>
<div class="principle">
<strong>Predict where things go.</strong>
Anyone (human or agent) should be able to guess where a piece of information lives without consulting an index. Plans are in <code>plans/</code>. Decisions are in <code>03-decisions.md</code>. Reference material is in <code>reference/</code>.
</div>
<div class="principle">
<strong>Concise over comprehensive.</strong>
Every file should be as short as it can be while remaining useful. If a document is getting long, split it or archive the old parts. <code>reference/</code> is the deliberate exception: a reference is as complete as possible, and the conciseness lives in the summaries derived from it.
</div>
<div class="principle">
<strong>Evolve, don't ossify.</strong>
The structure serves the project, not the other way around. Add directories if your project needs them. Remove files that aren't pulling their weight. The template is a starting point.
</div>
<h2>Optional Extensions</h2>
<p>Some projects benefit from additional files not in the base template:</p>
<ul>
<li><strong>CLAUDE.md</strong> or <strong>AGENT-CONTEXT.md</strong> — Agent-specific bootstrap instructions or project-relevant personal context. Useful when the project has specific agent behaviors or constraints.</li>
<li><strong>PROJECT-INSTRUCTIONS.md</strong> — If using Claude Projects (the web UI), this can hold the canonical copy of custom instructions that get pasted into the UI.</li>
<li><strong>thoughts/</strong> — Longer-form thinking documents, explorations that aren't plans yet.</li>
</ul>
</body>
</html>