Project Brain

Assets

This skill uses a modular assets architecture. Detailed workflows, helpers, and templates are in the assets/ directory:

assets/modes/ — LOAD and SAVE mode workflows
assets/helpers/ — Brain directory config resolution, incremental merge algorithm
assets/templates/ — Standard brain document format

See assets/README.md for full directory documentation.

Purpose

Project Brain is session memory for AI agents. It bridges the gap between sessions so any agent can pick up exactly where the last one left off — and save what it learned before shutting down.

Design principle: Agents behave like professionals with a notebook. Open the notebook before work (LOAD), write a summary when done (SAVE), and the notebook persists between sessions. Memory is a natural part of the workflow, not an extra step.

What it does:

LOAD: Reads a brain document, parses structured context, delivers a concise briefing
SAVE: Captures session context, creates or incrementally updates a brain document

What a brain document is: A markdown file that captures project state, session history, architecture decisions, and next steps. The standard format (v2.0) has defined sections, but the skill also reads v1.0 and free-form documents.

Critical Rules

RULE 1 — NO FABRICATION

Only report information that exists in the brain document (LOAD) or was explicitly discussed in the session (SAVE). Never infer, guess, or complete missing data.

RULE 2 — USER CONFIRMS BEFORE WRITE

In SAVE mode, always present the gathered session data to the user for review before writing. Never write without confirmation.

RULE 3 — INCREMENTAL NOT DESTRUCTIVE

SAVE UPDATE merges new data into existing sections. It never overwrites the full document. Accumulated Context is append-only. Session Log is prepend-only.

RULE 4 — FORMAT BACKWARD-COMPATIBLE

LOAD parses three formats: v2.0 standard, v1.0 sections, and free-form markdown. SAVE UPDATE detects the format and offers migration if the document isn't v2.0.

RULE 5 — PATH RESOLUTION ONCE

Resolve {brain_dir} once per session (see Configuration Resolution). The resolved path is used for all operations. Don't re-ask unless the user wants to change the path.

RULE 6 — LANGUAGE SEPARATION

Conversation (briefings, confirmations, questions) → respond in the same language the user used. Brain document content (what gets written to file) → always in English, regardless of conversation language. Technical artifacts must be consistent across sessions.

RULE 7 — NO SILENT DEFAULTS

When {brain_dir} has not been resolved, you MUST ask the user via AskUserQuestion before proceeding. Never silently choose the default staging path. The user must actively confirm their preferred directory.

Configuration Resolution

{brain_dir} is the directory where project-brain stores brain documents. Resolve it once per session:

User message context — If the user's message contains file paths, extract {brain_dir} from those paths
Auto-discover — Scan for .agents/project-brain/ in {cwd}, or look for existing brain documents
Ask the user — If nothing found, ask where to store brain documents via AskUserQuestion. Default suggestion: .agents/project-brain/{project-name}/

No AGENTS.md. No branded blocks. The brain directory is resolved at runtime.

Full resolution algorithm: see assets/helpers/brain-resolve.md

Mode Detection

Mode	EN Signals	ES Signals	What It Does
LOAD	"load brain", "restore context", "brief me", "pick up where we left off"	"carga el brain", "recupera el contexto", "ponme al dia"	Auto-discovers brain, reads it, delivers context briefing
SAVE	"save brain", "save session", "update brain", "persist session"	"guarda el brain", "guarda la sesion", "actualiza el brain"	Gathers session data, creates or updates brain document

Disambiguation: If the user's intent is unclear, ask:

"Do you want me to load a brain document (restore context) or save the current session (capture what we did)?"

Asset Loading (Mode-Gated)

After detecting the mode, read ONLY the assets listed for that mode. Do NOT read assets for other modes — they waste context tokens.

Mode	Read These Assets	Do NOT Read
LOAD	`assets/modes/LOAD.md`, `assets/helpers/brain-resolve.md`	SAVE.md, brain-config.md, incremental-merge.md, BRAIN-DOCUMENT.md
SAVE INIT	`assets/modes/SAVE.md`, `assets/helpers/brain-config.md`, `assets/templates/BRAIN-DOCUMENT.md`	LOAD.md, brain-resolve.md, incremental-merge.md
SAVE UPDATE	`assets/modes/SAVE.md`, `assets/helpers/brain-config.md`, `assets/helpers/incremental-merge.md`	LOAD.md, brain-resolve.md, BRAIN-DOCUMENT.md

Read the mode asset first, then follow its internal references to helpers/templates as needed.

Quick Start

LOAD Mode

Use at the start of a session to restore context:

Load the project brain.

This will: resolve {brain_dir}, scan for existing documents, read the brain, parse sections, and deliver a context briefing.

Assets to read now: assets/modes/LOAD.md + brain-resolve.md

SAVE Mode

Use at the end of a session to persist what happened:

Save the session to the brain.

This will: detect if a brain exists (UPDATE) or not (INIT), gather session data, confirm with you, and write or merge the brain document.

Assets to read now: assets/modes/SAVE.md + brain-config.md (SAVE.md references additional helpers per sub-mode)

Capabilities Matrix

Capability	LOAD	SAVE (INIT)	SAVE (UPDATE)
Resolve `{brain_dir}`	Yes	Yes	Yes
Auto-discover brain documents	Yes	No	Yes
Read brain from Obsidian vault	Yes	No	No
Read brain from filesystem	Yes	No	No
Parse v2.0, v1.0, free-form	Yes	No	Yes
Deliver context briefing	Yes	No	No
Create new brain document	No	Yes	No
Incremental merge	No	No	Yes
Gather session context	No	Yes	Yes
Offer format migration	No	No	Yes

Integration with Other Skills

Skill	Integration
`sprint-forge`	LOAD reads sprint-forge re-entry prompts. SAVE captures sprint progress as session entries.
`obsidian`	LOAD can read brain documents from vault via obsidian READ mode. Invoke via `Skill("obsidian")` or say "read from obsidian". Subagent fallback: read obsidian SKILL.md directly.
`universal-planner`	LOAD reads planning documents. SAVE captures planning decisions.

Composition patterns:

session start  → project-brain LOAD  → agent is briefed → work happens
session end    → project-brain SAVE  → session persisted → next agent can LOAD

sprint-forge INIT  → generates findings + roadmap
project-brain SAVE → captures sprint-forge session → brain document created
new session        → project-brain LOAD → full context restored

Limitations

Markdown only: Handles .md files; does not parse .yaml, .json, or other formats
Single file: One brain document per project — not a recursive folder reader
No synthesis: If the brain document is outdated, the briefing reflects that
Obsidian integration in LOAD only: SAVE always writes to filesystem. To sync to Obsidian, use the obsidian skill after SAVE.
Session Log size: Compacted at 15+ entries — older sessions are archived to {brain_dir}/archive/ and replaced with a summary paragraph
No auto-save: SAVE must be explicitly invoked — the agent doesn't auto-save on exit