# Thalarch Project Brain > Maintains an opt-in, repository-local project knowledge layer for stable architecture, invariants, decisions, regressions, commands, design rules, and project-scoped experience. Use when a project is revisited repeatedly and durable context would reduce rediscovery. Current repository/runtime evidence always outranks the brain; entries carry provenance/freshness; stale facts are retired; secrets and private chain-of-thought are forbidden; and repository files are created or changed only when durable project memory is explicitly authorized. - Skill: `luc4n3x/thalarch-project-brain` (Agent Skill) - Install (CLI): `npx skillmds@latest add luc4n3x/thalarch-project-brain` - Raw SKILL.md: https://api.skillmd.com/api/skills/luc4n3x/thalarch-project-brain/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: LUC4N3X (https://skillmd.com/u/luc4n3x) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/luc4n3x/thalarch-project-brain --- # Thalarch Project Brain A Project Brain is a **compact project-specific knowledge index**, not a replacement for the source code, tests, repository instructions, or current runtime evidence. ## 1. Activation and authorization Use when: - the repository is worked on repeatedly; - important invariants are expensive to rediscover; - regressions recur; - architecture or product decisions need durable rationale; - project-specific workflows/commands repeatedly matter. Do not create `.thalarch/brain/` automatically during ordinary work. A repository-local durable sink is an external mutation and requires user/project authorization. ## 2. Canonical layout When authorized, prefer this small inspectable layout: ```text .thalarch/brain/ project.md invariants.md decisions.md regressions.md playbooks.md design.md # only when the project has meaningful visual/product rules memory.sqlite3 # optional indexed project memory ``` Do not create empty files merely to satisfy the layout. Add only surfaces the project actually needs. If the repository already has authoritative architecture/decision/runbook documentation, reference or update that system instead of creating a competing source of truth. ## 3. What belongs where ### `project.md` Stable project identity and navigation: - language/framework/toolchain facts with provenance; - important modules/boundaries; - authoritative repository rule files; - verified build/test/lint commands; - pointers to deeper project docs. ### `invariants.md` Behavior that must remain true, for example ownership, queue identity, cache semantics, wire compatibility, data constraints, or lifecycle rules. ### `decisions.md` Durable decisions with rationale, alternatives, scope, evidence, and revisit trigger. Do not turn minor implementation choices into ADR theatre. ### `regressions.md` Compact incident cards: `trigger → proven root cause → discriminator → fix → must-preserve behavior → regression proof`. ### `playbooks.md` Verified project-specific workflows and diagnostic commands. Commands must come from real project scripts/docs/CI/tooling, never memory alone. ### `design.md` Only stable product/design rules: visual identity, spacing/interaction principles, banned patterns, accessibility constraints, and reference locations. ## 4. Entry contract Every load-bearing brain entry should make freshness inspectable: ```text Title Status: active | retired Scope: subsystem/module Last verified: date + commit/version when available Evidence: source/test/run/doc references Statement: concise invariant/decision/lesson Apply when: trigger/conditions Do not apply when: counterexample/version boundary ``` If freshness cannot be established, retrieval may still use the entry as a lead but not as current truth. ## 5. Read path At the start of meaningful repeat work: 1. read repository/system/user rules first; 2. inspect `project.md`/relevant brain index if it exists; 3. query project memory for the subsystem/failure mode; 4. retrieve only a small relevant capsule; 5. verify load-bearing claims against current source/runtime; 6. feed accepted/rejected memory into `thalarch-context`. Do not load the entire Project Brain into every task. ## 6. Write path After a verified task: 1. run `thalarch-compound`; 2. use `thalarch-experience` to create a concise candidate card; 3. classify with `thalarch-memory`; 4. persist only project-worthy knowledge; 5. deduplicate against existing entries; 6. update/retire contradicted entries instead of appending forever. Prefer editing one existing entry over adding a near-duplicate. ## 7. Current truth wins Resolve conflicts in this order: 1. explicit current user/system/repository rules; 2. current executable/runtime evidence; 3. current source/config/manifests/tests; 4. current primary/vendor contract for version-sensitive facts; 5. verified project documentation; 6. Project Brain memory. The brain speeds discovery. It never outranks the project it describes. ## 8. Privacy and repository hygiene Never store credentials, secrets, auth material, private chain-of-thought, unnecessary personal data, or raw confidential payloads. Distill the engineering lesson. Before committing a project brain file: - confirm repository policy permits it; - keep entries concise; - avoid machine-specific absolute paths unless the project contract truly requires them; - do not commit the SQLite store if repository policy prefers local-only state; add it to ignore rules only when authorized and appropriate. ## 9. Bootstrap template For a new authorized Project Brain, begin with the minimum useful `project.md`: ```text # Project Brain ## Authority - Repository rules: ## Stack - ## Critical invariants - ## Verified commands - ## Known regression areas - ## Memory policy Current source/runtime evidence overrides this file. Revalidate load-bearing entries before use. ``` Grow only from verified recurring need.