brain

name	brain
description	Read/write the docs/ vault — this project's persistent memory. Use for any task that persists knowledge: reflection, planning, gotchas, principles, or direct edits. Triggers: docs/ modifications, "add to docs", "remember this".

Brain (docs/)

In this repo the persistent-memory vault is docs/. It doubles as the project wiki and the agent's long-term memory.

The brain is the foundation of the entire workflow — every agent, skill, and session reads it. Low-quality or speculative content degrades everything downstream. Before adding anything, ask: "Does this genuinely improve how the system operates?" If the answer isn't a clear yes, don't write it.

Before Writing

Read docs/index.md first. Then read the relevant entrypoint for your topic:

• docs/principles.md for principles
• docs/plans/index.md for active or past plans
• docs/patterns/effect-ai-gotchas.md for @effect/ai-specific gotchas
• docs/guides/ for how-to recipes

For directories without a dedicated index file, scan nearby files directly and edit an existing note when possible.

Structure

docs/
├── index.md                <- curated wiki landing page (manually maintained, NEVER auto-rewritten)
├── architecture.md         <- the three layers, dataflow
├── tooling.md              <- stack, check pipeline
├── testing-strategy.md     <- pyramid
├── backlog.md              <- known follow-ups
├── principles.md           <- index for principles/ (auto-rebuilt)
├── principles/             <- engineering and design principles (one per file)
├── plans/                  <- phased implementation plans
│   └── index.md            <- auto-rebuilt
├── guides/                 <- how-to recipes (adding-a-tool, testing)
├── patterns/               <- gotchas, conventions (effect-ai-gotchas)
└── stories/                <- learning narratives / journals

Rules:

• One topic per file. docs/patterns/anthropic-rate-limits.md, not a mega-file.
• docs/index.md is the curated root — every section should be reachable from it. Do not rewrite it programmatically.
• docs/principles.md and docs/plans/index.md are auto-rebuilt by the PostToolUse hook. Don't hand-edit them — just add or remove files in the directory and the hook regenerates the index.
• File names: lowercase, hyphenated. effect-ai-gotchas.md.

Wikilinks

Format: [[section/file-name]]. Resolution order: same directory, then relative path, then vault root. Heading anchors ([[file#heading]]) are stripped during resolution.

Writing Style

• Bullets over prose. No preamble.
• Plain markdown with # Title. No frontmatter on memory notes.
• Keep notes under ~50 lines. Split if longer.

After Writing

If you added or removed a file in docs/principles/ or docs/plans/, the auto-index hook will rebuild the matching index. For other directories, update docs/index.md by hand if the new entry deserves a top-level mention.

Durability Test

Ask: "Would I include this in a prompt for a different task?"

• Yes → write to docs/. It's durable knowledge.
• No, it's plan-specific → update the plan's docs instead.
• No, it's a skill issue → update the skill file directly.
• No, it needs follow-up work → add it to docs/backlog.md.

Maintenance

• Delete outdated or subsumed notes.
• Merge overlapping notes before adding new ones.
• When repos/ content makes a doc redundant, link to the source file and delete the doc.