kb-init

Knowledge Base Initialization

You are a knowledge base setup assistant. Your job is to initialize the Knowledge Base infrastructure in the current project.

Instructions

CRITICAL: This command MUST NOT accept any arguments. Ignore any text provided after the command.

SCOPE RULE: All KB operations target only the current working directory (the parent directory where Claude Code is running). Never create docs/kb/ in subdirectories, never modify CLAUDE.md files in subdirectories, and never add KB references to sub-directory CLAUDE.md files. The docs/kb/ directory and its contents should be committed to source control for team sharing.

Step 1: Detect Current State

1. Check for docs/kb/ directory: Use Glob to check if docs/kb/ exists and contains any .md files.
2. Check for CLAUDE.md: Read the project's CLAUDE.md file (in the current working directory). If it doesn't exist, note that it will be created.
3. Check for existing KB section: If CLAUDE.md exists, look for a ## Knowledge Base section (or # Knowledge Base depending on heading conventions used in the file).

Step 2: Create Directory Structure

Resolve today's date (cross-platform, CRITICAL): Before writing any file below, run the first command that works in the current shell and use the returned YYYY-MM-DD string for every {today's date} placeholder in the templates. Never guess, never infer, never increment.

• macOS / Linux / WSL / Git Bash (bash, zsh, sh): date +%Y-%m-%d
• Windows PowerShell / pwsh: Get-Date -Format 'yyyy-MM-dd'
• Windows cmd.exe: powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-dd'"
• Portable fallback (Node or Python available): node -e "console.log(new Date().toISOString().slice(0,10))" or python -c "import datetime; print(datetime.date.today().isoformat())"

If docs/kb/ does not exist, create it with a placeholder README:

File: docs/kb/README.md

# Knowledge Base

This directory contains topic-specific knowledge base files that are dynamically referenced in CLAUDE.md.

## Structure

KB articles are organized in category folders. Special files (prefixed with `_`) live at the root:

docs/kb/ _global-learnings.md # Cross-cutting rules (pinned, always loaded) _index.md # Auto-generated page catalog with summaries _log.md # Chronological operation log README.md # This file architecture/ # Architecture patterns and system design conventions/ # Naming, coding, and API conventions tools/ # Tooling, workflow, and infrastructure ... # Other categories as needed

Category folders are created as needed based on article content. Articles can also be flat at the root for small KBs:

## Frontmatter Schema

Every KB file MUST include YAML frontmatter. This metadata is used by all `/kb-*` commands for search, pruning, cross-referencing, and contextual loading.

```yaml
---
tags: [api, auth, security]          # Cross-cutting topic tags for discovery
related: [[api-conventions]]         # Cross-references to other KB files (by filename without extension)
created: 2026-04-02                  # Date the file was created
last-updated: 2026-04-02            # Date the file was last modified
pinned: false                        # If true, always loaded regardless of context
scope: "packages/api/**"             # Optional glob pattern(s) for auto-matching. String or array of strings.
---

Field Reference

Field	Required	Description
tags	Yes	Array of lowercase tags for cross-cutting discovery. Used by /kb-search.
related	No	Array of [[filename]] references to other KB files. When one file is loaded, related files may also be consulted.
created	Yes	ISO date (YYYY-MM-DD) when the file was first created.
last-updated	Yes	ISO date (YYYY-MM-DD) when the file was last modified. Updated automatically by KB commands.
pinned	No	Boolean. When true, this file is always loaded at the start of every conversation. Default: false. Use sparingly.
scope	No	Glob pattern(s) matching file paths where this knowledge applies. Can be a single string ("src/api/**") or an array of strings (["src/api/**", "*.controller.ts"]). These patterns are surfaced in the CLAUDE.md table's "When to Load" column for efficient context matching.

File Format

Each KB file should follow this structure:

---
tags: [topic-tag]
related: [[other-kb-file]]
created: YYYY-MM-DD
last-updated: YYYY-MM-DD
pinned: false
scope: []                            # String or array of glob patterns for auto-matching
---