References

Use this document for external references and design notes that inform Braincode.

Agent design

Amp note: https://ampcode.com/notes/how-to-build-an-agent
- Agent loop: model + system prompt + tools.
- Tool calls are executed locally and returned to the model as tool results.

Amp guide: https://ampcode.com/guides/context-management
- Context windows are a primary design constraint.
- Handoff creates a fresh context from a distilled message.
- Referencing other threads should pull only the relevant information, not the entire history.
Amp note: https://ampcode.com/notes/200k-tokens-is-plenty
- Short, focused threads produce better results and lower cost than one large thread.
- Treat threads as task units; a feature or bugfix can be a cluster of small contexts.
- For Braincode, this maps to Brain owning the orchestration context while each subagent owns one task context.
GSD Core repository: https://github.com/open-gsd/gsd-core
- The original https://github.com/gsd-build/get-shit-done repository has moved to open-gsd/gsd-core.
- GSD's useful transferable idea is an artifact-driven phase loop: Discuss, Plan, Execute, Verify, Ship.
- GSD uses durable project files such as state, context, plan, summary, and verification artifacts so agents can resume without relying on one long transcript.
- For Braincode, this maps to Development workflow: project-level phase contracts complement runtime worker handoffs and session JSONL rather than replacing them.

Pi repository: https://github.com/earendil-works/pi
- Use @earendil-works/pi-ai for normalized LLM provider/model streaming.
- Use @earendil-works/pi-agent-core for agent runtime, tool calling, sessions, and compaction where it fits.
- Do not use Pi's TUI as the Braincode product interface; Braincode owns its Ink TUI and its routing/model-selection semantics.
- Do not fork Pi unless there is no viable public API or integration point.