CLAUDE.md

The org/docs layer is mature and the first product slice — the intranet/ portal (Astro) — is live. Keep this file current as more product code lands; that’s part of the definition of done for any significant change.

This file gives AI assistants (and new contributors) the context needed to work productively in this repository: what the project is, how it’s organized, how to build/run/test it, and the conventions to follow.

This repository also serves as a reusable template. The agent org, Golden Rules, archive system, and HR policies are portable scaffolding; project content (e.g. docs/concept.md, history/chronicle.md) is replaced per new repo. See TEMPLATE.md to instantiate a new repository.

Golden Rules

Project-wide rules that take priority over convenience. Referenced by ID (GR-#). Maintained by the Rules & Governance unit (see ORG.md).

1. GR-1 — Always use the best available model. Default to the most capable model available for the task (e.g. the latest, top-tier Claude model); never silently downgrade to a cheaper or faster model. If a constraint forces a lesser model, say so and name the tradeoff — because output quality is the priority for this project.
2. GR-2 — Always use Claude Code workflows as much as possible. Prefer native Claude Code mechanisms — subagents (.claude/agents/), skills / slash commands, hooks, plan mode, MCP tools, and the Agent/Task tool — over ad-hoc manual steps whenever one fits the job — because they are repeatable, auditable, and reduce drift.
3. GR-3 — Co-create rules: ideate, optimize, then approve. New rules are developed with the human: ideate together, optimize the wording against the golden bar, and obtain explicit final approval before the rule is finalized or committed. The Golden Rule agent must not one-shot a rule — because rules are governance and must reflect intent, not assumption.
4. GR-4 — Analyze the need before you tool (or build). Before adding tools / MCP wiring to an agent (deferred) or building a feature, first do a needs analysis: what capability is actually required, for what, and under what constraints — then add only what the need justifies. (The venture itself is entered via the ideation spec, not a needs analysis — see docs/methodology.md.) Headcount is not the limiter. To create an agent/role the bar is clear purpose and defined scope — not workload volume. The AI workforce carries nominal cost; scope clarity is the real constraint. (Supersedes any lean/hiring-freeze default.)
5. GR-5 — Two entry points only. A venture is entered only via (a) an injected JSON ideation spec (sourced from the monorepo), which seeds Ideate, or (b) direct chat. There are no other entry points.
6. GR-6 — Capture decisions before close. As part of the session-close routine, reconcile the session’s decisions and directives into rules (CLAUDE.md) and policies (hr/policies/) so nothing durable is lost — owned by Golden Rule (rules) and HR (policies).
7. GR-7 — Batch pushes to checkpoint; never push mid-task. Push to main or any Vercel-connected branch only at deliberate session checkpoints (end of session, end of a named task group, or an explicit release boundary) — not after every PR or micro-task. Keep branches local or as draft PRs until the work is complete; undraft and push only when the checkpoint is reached. Reason: every push to a Vercel-connected branch consumes a deploy credit from the daily budget (ADR-0009); mid-task pushes burn credits with no user-facing value.
8. GR-8 — Protect the archive record. When you change an archived source file, refresh its archive/documents/<id>/latest/ copy and the MANIFEST hash in the same commit; never modify or bulk-replace first/ rows (write-once). Treat scripts/archive-manifest.sh verify as authoritative; never use update/refresh to mass-rewrite hashes, and never bypass the CI archive check — because the archive is the project’s write-once memory: first/ rows must stay immutable, and rewriting hashes to silence verify would hide drift instead of fixing it, defeating the record.

Project Overview

KLMS (Kevin’s Learning and Mentorship System) is a personal AI-assisted operating system for one Principal (Kevin Wong). The system organizes knowledge, tracks decisions, and hosts the org-as-code infrastructure that powers the Principal’s ventures — including a YouTube channel and web learning platform built around “showing the work” with LLMs. The concept (see docs/concept.md) describes a dual-flywheel model: public content generates scored learning chunks; a retrieval-first web platform assembles those chunks into lessons and feeds performance signals back to improve ranking.

The intranet (intranet/) is the first product slice — a private static portal that surfaces the repo’s documents, org chart, briefings, and activity feed in a single browser UI.

• Name: KLMS — Kevin’s Learning and Mentorship System
• Purpose: Personal AI operating system for the Principal’s ventures; org-as-code infrastructure + intranet portal over the repo.
• Primary users: The Principal (single-user; Vercel Authentication enforces this). AI agents act as the workforce.
• Status: Org/docs layer mature; intranet portal shipped; product data layer (Supabase, live chatter) deferred (ADR-0006).

Tech Stack

The org/docs layer is Markdown + Bash + Git. The product layer begins with the intranet (intranet/):

Repository Structure

.
├── CLAUDE.md, ORG.md, CONTRIBUTING.md, TEMPLATE.md, LICENSE
├── docs/              # foundational docs, ADRs, canon, methodology, glossary
├── hr/                # handbook + policy library + hiring/onboarding
├── archive/           # versioned preservation (first/latest/milestones + MANIFEST)
├── history/           # narrative chronicle
├── reports/ reviews/ specs/
├── scripts/           # archive-manifest.sh, new-repo.sh
├── .claude/           # agents/, commands/, hooks/, settings
└── intranet/          # Astro static portal (the first product slice)

Getting Started

Prerequisites: Node.js 18+ (LTS) and npm. No other system dependencies for local development. Git must be available (sync-content reads git log at build time).

# Clone and enter the repo
git clone <repo-url> && cd KLMS

# Install intranet dependencies
cd intranet && npm install

# Start the dev server (syncs repo content first, then serves on :4321)
npm run dev

Required environment variables: None for local development. The Vercel deployment uses Vercel Authentication (no env vars needed in the bundle — secrets never enter the repo; see hr/policies/security.md).

Common Commands

# Intranet (the product slice)
cd intranet && npm install     # install deps
npm run dev                    # local dev (syncs repo content, serves :4321)
npm run build                  # static build to intranet/dist
npm run preview                # serve the built dist locally
npm run sync                   # regenerate src/generated/ from the repo (runs automatically before dev/build)

# Archive integrity / upkeep (the record)
./scripts/archive-manifest.sh verify    # check integrity (read-only)
./scripts/archive-manifest.sh update    # refresh latest-version checksums

Architecture & Key Concepts

The system has two layers: the org/docs layer (Markdown, Bash, Git) and the product layer (the intranet portal).

Org / docs layer

The repo is the single source of truth. Documents live in docs/, hr/, reports/, reviews/, specs/, and history/. Agent definitions live in .claude/agents/. The archive (archive/) is a versioned record with a content-addressed MANIFEST. No runtime database exists yet.

Intranet portal (intranet/)

A static Astro 6 site. It has no server runtime — all data is baked in at build time by scripts/sync-content.mjs.

Build-time data pipeline (sync-content.mjs):

1. Reads the repo’s Markdown files and renders them with markdown-it (html:false, so <placeholders> and {{vars}} appear literally rather than being parsed as HTML).
2. Parses ORG.md to build the people roster and extract the Mermaid org chart.
3. Reads archive/MANIFEST.md, counts agents in .claude/agents/, and runs git log to populate dashboard stats.
4. Reads the most recent reports/*-briefing.md and reports/*-report.md for the Dashboard briefing widgets.
5. Writes everything to src/generated/ (gitignored JSON files).

Pages:

Mermaid: bundled (not CDN) so diagrams render offline. The Base layout initializes Mermaid client-side and converts fenced ```mermaid blocks from rendered markdown into Mermaid <pre> elements.

Styling: Tailwind CSS v4 via @tailwindcss/vite. No PostCSS config — Vite handles it directly. Typography plugin (@tailwindcss/typography) styles rendered markdown in the docs and dashboard prose blocks.

Deployment: Vercel static hosting, GitHub-connected. Vercel Authentication provides single-user access control (ADR-0008). Each push to main triggers a deploy — batch pushes per session to stay within the daily budget (ADR-0009).

Coding Conventions

• Naming: Astro component files use PascalCase (Base.astro). Scripts and data files use kebab-case (sync-content.mjs, chatter.json). TypeScript/JS variables use camelCase.
• Formatting / linting: No enforced formatter or linter is configured yet (no .eslintrc, no Prettier config, no tsconfig.json in intranet/). Match the style of the surrounding file — two-space indentation, single quotes in JS/TS.
• Imports / module layout: Node built-ins first, then third-party, then local. The intranet uses "type": "module" — all imports use ESM (import/export). Astro components import generated JSON directly from ../generated/.
• Error handling: sync-content.mjs wraps git log in a try/catch and silently falls back to an empty array. This pattern (silent fallback with a sensible default) is the convention for optional/external data. Do not throw from sync — a missing file should degrade gracefully.
• Logging: sync-content.mjs emits a single summary line to stdout ([sync] N docs · N people · ...). Keep logging minimal and prefixed with [sync] or a similar context tag.

Testing

No test framework is configured yet. There are no test files in intranet/ and no test script in package.json.

When a framework is added, the natural targets will be:

• sync-content.mjs — unit tests for the Markdown-to-JSON pipeline (title extraction, slug generation, category ordering, graceful fallback when files are absent).
• Astro pages — build-time smoke tests (does npm run build complete without error? Do all generated routes resolve?).
• Archive integrity — ./scripts/archive-manifest.sh verify already serves as a lightweight integration check for the record layer.

Add tests and flesh out this section when the first test file lands.

Git & PR Workflow

• Branching: feature work on claude/<topic> or <type>/<short-desc> branches; do not commit directly to the default branch.
• Commits: clear, imperative subject lines describing the change.
• Push deliberately: commit freely, but batch pushes to main (once per session/milestone) — each push deploys the intranet on Vercel, and the daily budget is limited (ADR-0009).
• Pull requests: open as draft first; keep the description focused on what changed and why. Update CLAUDE.md in the same PR when the change affects structure, commands, or conventions.

Notes for AI Assistants

• Keep this file truthful. If you discover the docs here are stale or wrong, fix them as part of your change rather than working around them.
• Prefer existing patterns and utilities over introducing new ones; match the style of the surrounding code.
• Verify before asserting done — run the relevant build/test/lint commands and report real results, including failures.
• Confirm before irreversible or outward-facing actions (deleting data, pushing, opening PRs) unless already authorized.
• Replace placeholders as you learn the codebase. The first contributor to add real modules, commands, or conventions should also flesh out the matching section above and remove the starter banner once the file reflects reality.