Project brain map
The Amistio project brain
The project brain is the structured knowledge layer between a messy wish and safe local execution. It keeps the why, what, plan, rules, prompts, and lessons close to the repository so humans and agents can work from the same source of truth.
Why Amistio uses a project brain
Most AI coding work fails in ordinary ways: missing context, unclear decisions, forgotten constraints, vague acceptance checks, and repeated mistakes. Amistio splits that knowledge into small, named artifacts so each part can be reviewed, synced, searched, and reused.
A prompt is not enough. Amistio uses a project brain so the agent knows what the product is, why decisions were made, what work is approved, how to verify it, and what the team has already learned.
The full brain file map
AGENTS.md
The operating guide for agents in the repository. It explains mode, gates, sequencing, and what must never be changed casually.
.instructions.md files
Scoped rules for coding agents and tools. They keep local style, safety, and workflow expectations visible.
docs/architecture/
System shape, boundaries, components, and how the product is meant to fit together.
docs/context/
Product, stack, and implementation facts that should be read before planning or changing code.
docs/decisions/
ADRs and product decisions. These explain why the team chose one path instead of another.
docs/features/
Feature behavior, user stories, acceptance criteria, edge cases, and scope boundaries.
docs/memory/
Lessons, mistakes, conventions, and patterns that should shape future work.
docs/plans/
Current work plans, ordered steps, verification notes, and completion evidence.
docs/workflows/
Repeatable procedures for work the team expects to do again.
docs/prompts/
Model-agnostic implementation work units that can be executed one at a time.
How the pieces work together
- Context and architecture tell the agent what world it is operating in.
- Features describe the behavior the user should get.
- Decisions explain why a path is approved and what tradeoffs were accepted.
- Plans turn the decision into ordered work and verification steps.
- Prompts package approved implementation into a single runnable handoff.
- Memory changes future behavior by recording lessons and recurring patterns.
- AGENTS.md and instruction files keep agents inside the repo's operating rules.