npm package: @petter100/3tkb
Description: 3-Tier Knowledge Base framework for AI-powered projects
Author: Rafael Petter
Latest version: 1.0.0

# 3TKB — 3-Tier Knowledge Base

A framework for organizing project knowledge in three tiers, optimized for AI agent consumption.

```
1-index/          ← Master index — what exists and where (≤50 lines)
2-summaries/      ← One-page overviews per topic (≤2,000 chars)
3-descriptions/   ← Full specifications and details (≤50,000 chars)
```

## Why?

AI coding agents (Claude Code, Cursor, Copilot, Codex) work best when they can quickly find relevant context. But projects grow, and a flat docs folder becomes a maze.

3TKB solves this with **progressive disclosure**:

1. **Agent starts a session** → reads Tier 1 (index + briefing) in 30 seconds
2. **Agent identifies a topic** → reads the relevant Tier 2 summary
3. **Agent needs implementation detail** → reads the Tier 3 spec

This minimizes token usage while ensuring agents always have the right context at the right depth.

## Quick Start

```bash
# Scaffold a new knowledge base
npx 3tkb init my-kb

# Validate an existing knowledge base
npx 3tkb validate my-kb
```

## Tier Rules

### Tier 1 — Index (`1-index/`)

The entry point. Contains the master index and optionally an agent briefing.

- **Max 50 lines** per file
- Format: `Topic | Description | [Link](path)`
- Should link to every Tier 2 category

```markdown
# My Project — Master Index
## Version: 1.0.0 | Last Updated: 2026-02-24

Product | Features, tech stack, roadmap | [2-summaries/product/](../2-summaries/product/)
Infrastructure | Hosting, CI/CD, monitoring | [2-summaries/infrastructure/](../2-summaries/infrastructure/)
```

### Tier 2 — Summaries (`2-summaries/`)

One-page overviews organized by category. Read these for context before diving deeper.

- **Max 2,000 characters** per file
- Header format: `# Title | vX.Y.Z | YYYY-MM-DD`
- Organized into category subdirectories
- Should reference related Tier 3 files

### Tier 3 — Descriptions (`3-descriptions/`)

Full specifications, detailed designs, and complete documentation.

- **Max 50,000 characters** per file
- Header format: `# Title | vX.Y.Z | YYYY-MM-DD`
- Mirrors Tier 2 category structure
- Contains code examples, data models, architecture diagrams

### Assets (`assets/`)

Non-markdown files (PDFs, images, diagrams). Mirrors the tier folder structure.

## Version Headers

Every markdown file (except README.md) must have a version header as the first line:

```markdown
# My Document Title | v1.0.0 | 2026-02-24
```

Bump the version on every edit:
- **Patch** (1.0.0 → 1.0.1): Small fixes, typos
- **Minor** (1.0.0 → 1.1.0): Content additions, updates
- **Major** (1.0.0 → 2.0.0): Structural changes, rewrites

## Validator

The CLI validator checks your knowledge base for compliance:

```bash
npx 3tkb validate [path]
```

### What it checks

| Check | Description |
|-------|-------------|
| **Size limits** | Files within tier character/line limits |
| **Version headers** | Every .md file has `# Title \| vX.Y.Z \| YYYY-MM-DD` |
| **Cross-references** | Markdown links point to existing files |
| **Orphaned directories** | Summary directories referenced in index |

### CI Integration

```yaml
# GitHub Actions
- name: Validate knowledge base
  run: npx 3tkb validate knowledge-base/
```

Exit code 1 on errors — fails the build if the KB is invalid.

## AI Tool Integration

3TKB works with any AI coding tool. See the [Integration Guide](docs/integration-guide.md) for setup with:

- **Claude Code** — `CLAUDE.md` files
- **Cursor** — `.cursor/rules/` files
- **GitHub Copilot / Codex** — `AGENTS.md` files
- **llms.txt** — LLM-friendly documentation standard

## Example

See [`examples/saas-startup/`](examples/saas-startup/) for a complete worked example — a fictional project management SaaS with index, summaries, and a detailed feature spec.

## Origin

3TKB was born from building [ATR (All The Rest)](https://alltherest.world), a SaaS platform with 15+ knowledge categories across 4 apps. We needed a way for AI agents to quickly find relevant context without reading everything. The 3-tier pattern emerged naturally and proved effective across Claude Code, Cursor, and other tools.

## License

MIT