brain-starter

An AI-friendly Markdown knowledge-base starter for project docs, plans, decisions, investigations, status updates, durable ticket records, career evidence, reusable skills, and reference material.

The repository is designed for coding agents such as Claude Code and Codex. AGENTS.md is the canonical contract for structure, metadata, navigation, and maintenance, so agents can work consistently without inventing a new organization on every task.

Quick Start

Clone the repository into the final directory name, then initialize it once:

git clone <brain-starter-url> my-brain
cd my-brain
./scripts/init-brain \
  --name my-brain \
  --owner "Your Name" \
  --team "Your Team"

init-brain detects the repository's canonical path, personalizes frontmatter and prompts, renames the bundled Claude skill, writes .brain.yml, and validates the result. Use --path when agents should refer to the repository through a different canonical path.

Then create a first document from docs/templates/ or ask an agent to start a project, capture an investigation, record a decision, or log a ticket. Agents should read AGENTS.md and docs/index.md first.

Run the repository checks at any time:

./scripts/check-brain

How It Is Organized

Folder	What goes there
docs/projects/	Active initiatives, using lightweight, planned, or full project profiles
docs/domains/	Durable cross-project knowledge grouped by domain
docs/decisions/	Cross-project ADRs and major decisions
docs/playbooks/	Repeatable processes, including knowledge-base maintenance
docs/reference/	Factual reference, integrations, artifact policy, and reusable prompts
docs/linear/	Optional snapshots, promoted ticket records, and project rollups
docs/career/	Optional weekly summaries, review drafts, and role/growth plans
docs/skills/	Exported skill definitions intended for sharing or handoff
docs/inbox/	Rough captures awaiting promotion
docs/archive/	Completed or stale material retained for history
docs/templates/	Copy-from templates for every supported knowledge document type

Linear and career tracking are optional. They can remain unused; if you remove either area, also remove its links and associated prompts so scripts/check-brain continues to pass.

Project Profiles

• Lightweight operational project: index.md, plus status/ when useful
• Planned initiative: index.md, prd.md, plan.md, and status updates during execution
• Full project: add notes/, decisions/, and specs/ as durable material accumulates

Every active project is linked from docs/projects/README.md. Topic-specific status records may use status-YYYY-MM-DD-<topic>.md when a project has multiple workstreams.

Core Conventions

• Treat docs/ as the system of record and start navigation at docs/index.md
• Update an existing canonical doc before creating a near-duplicate
• Use YAML frontmatter and keep document lifecycle status separate from Linear or other source-system states
• Use relative links; machine-specific absolute links fail validation
• Update parent navigation when adding projects, playbooks, top-level areas, or exported skills
• Promote durable lessons out of ticket/status logs into domain, decision, playbook, or reference docs
• Keep generated artifacts beside their source, label generated Markdown, and document regeneration
• Archive material when history matters instead of deleting it

The full rules are in AGENTS.md.

Using It With An AI Agent

• AGENTS.md and CLAUDE.md are the primary repository instructions
• .claude/skills/knowledge-base/SKILL.md provides cross-working-directory Claude Code workflows and is renamed by init-brain
• docs/reference/agent-handoff-prompt.md points an existing agent at the brain
• docs/reference/new-project-kickoff-prompt.md initializes the right project profile
• docs/reference/linear-sync-prompt.md creates durable Linear and optional career records
• docs/reference/brain-maintenance-prompt.md runs the recurring hygiene workflow

Automation

• scripts/init-brain: one-time identity, path, skill, and date customization
• scripts/check-brain: frontmatter, lifecycle status, date, link, artifact, and navigation validation
• .github/workflows/check-brain.yml: runs the validator for pushes and pull requests
• python3 -m unittest discover -s tests -v: smoke-tests initialization, portability, lifecycle enforcement, artifact exemptions, and navigation drift detection

Starting Points

• docs/index.md — top-level map
• AGENTS.md — authoring and agent contract
• docs/templates/ — templates for new canonical docs
• docs/playbooks/brain-maintenance.md — recurring maintenance workflow