rhachet-roles-bhrain 0.1.0 → 0.2.0

package/dist/roles/architect/briefs/brains.replic/arc000.sources.[catalog].md

@@ -0,0 +1,178 @@
+# research sources catalog
+
+## .what
+
+a comprehensive catalog of sources documenting replic brain architectures, reasoning patterns, and performance benchmarks.
+
+## .why
+
+these sources form the foundation for understanding how replic brains (LLMs behind REPLs) are constructed, compared, and evaluated.
+
+---
+
+## foundational papers
+
+### reasoning patterns
+
+| # | title | authors | url | date | relevance |
+|---|-------|---------|-----|------|-----------|
+| 1 | ReAct: Synergizing Reasoning and Acting in Language Models | Yao et al. | [arXiv:2210.03629](https://arxiv.org/abs/2210.03629) | 2022-10, ICLR 2023 | foundational pattern for interleaved reasoning + action in agentic loops |
+| 2 | Chain-of-Thought Prompting Elicits Reasoning in Large Language Models | Wei et al. | [arXiv:2201.11903](https://arxiv.org/abs/2201.11903) | 2022-01, NeurIPS 2022 | foundational technique enabling step-by-step reasoning |
+| 3 | Tree of Thoughts: Deliberate Problem Solving with Large Language Models | Yao et al. | [arXiv:2305.10601](https://arxiv.org/abs/2305.10601) | 2023-05, NeurIPS 2023 | exploration over reasoning paths, enables backtracking |
+| 4 | Reflexion: Language Agents with Verbal Reinforcement Learning | Shinn et al. | [arXiv:2303.11366](https://arxiv.org/abs/2303.11366) | 2023-03 | self-reflection and iterative refinement for agents |
+| 5 | Self-Consistency Improves Chain of Thought Reasoning | Wang et al. | [arXiv:2203.11171](https://arxiv.org/abs/2203.11171) | 2022-03 | multiple reasoning paths with majority voting |
+| 6 | Language Agent Tree Search (LATS) | Zhou et al. | [arXiv:2310.04406](https://arxiv.org/abs/2310.04406) | 2023-10, ICML 2024 | Monte Carlo tree search for language agents |
+
+### prompting techniques
+
+| # | title | authors | url | date | relevance |
+|---|-------|---------|-----|------|-----------|
+| 7 | Plan-and-Solve Prompting | Wang et al. | [arXiv:2305.04091](https://arxiv.org/abs/2305.04091) | 2023-05 | zero-shot decomposition into planning + execution |
+| 8 | Least-to-Most Prompting | Zhou et al. | [arXiv:2205.10625](https://arxiv.org/abs/2205.10625) | 2022-05 | decompose complex problems into simpler subproblems |
+| 9 | Self-Ask: Measuring and Narrowing the Compositionality Gap | Press et al. | [arXiv:2210.03350](https://arxiv.org/abs/2210.03350) | 2022-10, ICLR 2023 | model asks follow-up questions before answering |
+| 10 | Auto-CoT: Automatic Chain of Thought Prompting | Zhang et al. | [arXiv:2210.03493](https://arxiv.org/abs/2210.03493) | 2022-10 | automatic demonstration construction with diversity |
+| 11 | Show Your Work: Scratchpads for Intermediate Computation | Nye et al. | [arXiv:2112.00114](https://arxiv.org/abs/2112.00114) | 2021-12 | intermediate computation steps improve multi-step tasks |
+
+### tool use and function calling
+
+| # | title | authors | url | date | relevance |
+|---|-------|---------|-----|------|-----------|
+| 12 | Toolformer: Language Models Can Teach Themselves to Use Tools | Schick et al. | [arXiv:2302.04761](https://arxiv.org/abs/2302.04761) | 2023-02 | self-supervised tool use learning |
+| 13 | PAL: Program-Aided Language Models | Gao et al. | [arXiv:2211.10435](https://arxiv.org/abs/2211.10435) | 2022-11 | offload computation to program interpreter |
+
+### embodied and agentic systems
+
+| # | title | authors | url | date | relevance |
+|---|-------|---------|-----|------|-----------|
+| 14 | Inner Monologue: Embodied Reasoning through Planning with Language Models | Huang et al. | [arXiv:2207.05608](https://arxiv.org/abs/2207.05608) | 2022-07, CoRL | closed-loop feedback for robot planning |
+| 15 | Generative Agents: Interactive Simulacra of Human Behavior | Park et al. | [arXiv:2304.03442](https://arxiv.org/abs/2304.03442) | 2023-04 | memory architecture for believable agent behavior |
+| 16 | MemGPT: Towards LLMs as Operating Systems | Packer et al. | [arXiv:2310.08560](https://arxiv.org/abs/2310.08560) | 2023-10 | virtual context management, memory hierarchy |
+
+### surveys and meta-analyses
+
+| # | title | authors | url | date | relevance |
+|---|-------|---------|-----|------|-----------|
+| 17 | CoALA: Cognitive Architectures for Language Agents | Sumers et al. | [arXiv:2309.02427](https://arxiv.org/abs/2309.02427) | 2023-09 | systematic framework for language agent architectures |
+| 18 | AgentBench: Evaluating LLMs as Agents | Liu et al. | [arXiv:2308.03688](https://arxiv.org/abs/2308.03688) | 2023-08 | comprehensive benchmark for evaluating LLM agents |
+| 19 | Understanding the Planning of LLM Agents: A Survey | Huang et al. | [arXiv:2402.02716](https://arxiv.org/abs/2402.02716) | 2024-02 | taxonomy of planning approaches |
+| 20 | ADaPT: As-Needed Decomposition and Planning | Prasad et al. | [arXiv:2311.05772](https://arxiv.org/abs/2311.05772) | 2023-11, NAACL 2024 | adaptive decomposition based on task complexity |
+| 21 | Reasoning with Language Model Prompting: A Survey | Qiao et al. | [github.com/zjunlp](https://github.com/zjunlp/Prompt4ReasoningPapers) | 2023, ACL 2023 | comprehensive survey of prompting for reasoning |
+| 22 | LLM-Based Agents for Tool Learning: A Survey | - | [Springer](https://link.springer.com/article/10.1007/s41019-025-00296-9) | 2024 | survey of tool learning approaches |
+| 23 | A Survey of Task Planning with Large Language Models | - | [Intelligent Computing](https://spj.science.org/doi/10.34133/icomputing.0124) | 2024 | task planning and decomposition survey |
+
+---
+
+## claude-code architecture
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 24 | Building Effective Agents | Anthropic blog | [anthropic.com/research](https://www.anthropic.com/research/building-effective-agents) | 2024-12 | official guidance on agent architecture patterns |
+| 25 | Building Agents with the Claude Agent SDK | Anthropic engineering | [anthropic.com/engineering](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) | 2024 | SDK architecture and design principles |
+| 26 | Advanced Tool Use on Claude | Anthropic engineering | [anthropic.com/engineering](https://www.anthropic.com/engineering/advanced-tool-use) | 2024 | tool search, programmatic calling, examples |
+| 27 | Claude's Extended Thinking | Anthropic | [anthropic.com/news](https://www.anthropic.com/news/visible-extended-thinking) | 2025 | hybrid reasoning with thinking budgets |
+| 28 | The "think" Tool: Enabling Claude to Stop and Think | Anthropic engineering | [anthropic.com/engineering](https://www.anthropic.com/engineering/claude-think-tool) | 2024 | structured thinking during tool use |
+| 29 | Model Context Protocol (MCP) | Anthropic | [modelcontextprotocol.io](https://modelcontextprotocol.io/) | 2024 | standardized tool integration protocol |
+| 30 | Claude Agent SDK Repository | GitHub | [github.com/anthropics/claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python) | 2024 | reference implementation |
+| 31 | Claude Code System Prompt Analysis | Zenn (community) | [zenn.dev](https://zenn.dev/) | 2024 | detailed analysis of system prompt structure |
+
+---
+
+## alternative architectures
+
+### openai codex
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 32 | Codex Cloud Architecture | OpenAI | [developers.openai.com/codex/cloud](https://developers.openai.com/codex/cloud/) | 2025 | cloud sandbox execution environment |
+| 33 | Codex CLI Features | OpenAI | [developers.openai.com/codex/cli/features](https://developers.openai.com/codex/cli/features/) | 2025 | CLI capabilities and workflows |
+| 34 | Codex Security Guide | OpenAI | [developers.openai.com/codex/security](https://developers.openai.com/codex/security/) | 2025 | sandboxing and network isolation |
+| 35 | Codex SDK | OpenAI | [developers.openai.com/codex/sdk](https://developers.openai.com/codex/sdk/) | 2025 | programmatic integration |
+
+### other coding assistants
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 36 | Devin AI Architecture | various | (multiple sources) | 2024 | autonomous software engineer |
+| 37 | Aider: AI Pair Programming | aider.chat | [aider.chat](https://aider.chat/) | 2024 | git-integrated coding assistant |
+| 38 | Cursor AI | cursor.com | [cursor.com](https://cursor.com/) | 2024 | AI-augmented IDE |
+| 39 | GitHub Copilot | GitHub | [github.blog](https://github.blog/) | 2024 | code completion and chat |
+
+---
+
+## context management
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 40 | MemGPT: Virtual Context Management | Packer et al. | [arXiv:2310.08560](https://arxiv.org/abs/2310.08560) | 2023-10 | hierarchical memory for extended context |
+| 41 | Extended Thinking Documentation | Anthropic | [support.claude.com](https://support.claude.com/en/articles/10574485-using-extended-thinking) | 2025 | thinking budgets and serial test-time compute |
+| 42 | Context Window Management Strategies | various | (multiple sources) | 2024 | summarization and compaction techniques |
+
+---
+
+## benchmarks and performance
+
+### code generation benchmarks
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 43 | SWE-bench: Software Engineering Benchmark | Princeton NLP | [swebench.com](https://www.swebench.com/) | 2024 | real-world github issue resolution |
+| 44 | HumanEval Benchmark | OpenAI | [paperswithcode.com](https://paperswithcode.com/dataset/humaneval) | 2021 | function synthesis from docstrings |
+| 45 | HumanEval Pro and MBPP Pro | - | [arXiv:2412.21199](https://arxiv.org/abs/2412.21199) | 2024-12, ACL 2025 | self-invoking code generation |
+| 46 | MBPP Benchmark | Google | [paperswithcode.com](https://paperswithcode.com/sota/code-generation-on-mbpp) | 2021 | mostly basic python problems |
+| 47 | EvalPlus Leaderboard | - | [evalplus.github.io](https://evalplus.github.io/leaderboard.html) | 2024 | augmented test suites for HumanEval/MBPP |
+
+### agent benchmarks
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 48 | AgentBench | Liu et al. | [arXiv:2308.03688](https://arxiv.org/abs/2308.03688) | 2023-08 | multi-environment agent evaluation |
+| 49 | LiveBench | - | [livebench.ai](https://livebench.ai/) | 2024 | continuously updated LLM evaluation |
+
+### tool comparisons
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 50 | Coding Agents Comparison | Artificial Analysis | [artificialanalysis.ai](https://artificialanalysis.ai/insights/coding-agents-comparison) | 2024 | Claude Code, Cursor, Copilot comparison |
+| 51 | AI Coding Agents Benchmark 2025 | Render | [render.com/blog](https://render.com/blog/ai-coding-agents-benchmark) | 2025 | practical benchmark results |
+| 52 | Best AI Code Apply Tools 2025 | Morph | [morphllm.com/comparisons](https://www.morphllm.com/comparisons) | 2025 | enterprise benchmarks |
+| 53 | Claude Code vs Cursor Deep Comparison | Qodo | [qodo.ai/blog](https://www.qodo.ai/blog/claude-code-vs-cursor/) | 2025 | detailed feature comparison |
+
+---
+
+## reasoning strategy comparisons
+
+| # | title | source | url | date | relevance |
+|---|-------|--------|-----|------|-----------|
+| 54 | ReAct vs CoT Performance | Google Research | [research.google/blog](https://research.google/blog/react-synergizing-reasoning-and-acting-in-language-models/) | 2022 | comparative analysis on HotPotQA, FEVER, ALFWorld |
+| 55 | Comprehensive Guide to ReAct Prompting | Mercity | [mercity.ai/blog-post](https://www.mercity.ai/blog-post/react-prompting-and-react-based-agentic-systems) | 2024 | practical guide with performance notes |
+
+---
+
+## key performance findings
+
+### reasoning strategies (from sources)
+
+| strategy | benchmark | performance | source |
+|----------|-----------|-------------|--------|
+| ReAct | HotPotQA | competitive with CoT, better grounding | [1] |
+| ReAct | ALFWorld | +34% over imitation learning | [1] |
+| CoT | HotPotQA | higher success, but 56% hallucination in failures | [1] |
+| Self-Consistency | various | significant improvement over single-path CoT | [5] |
+| Tree of Thoughts | Game of 24 | 74% (vs 4% CoT) | [3] |
+| LATS | HotPotQA | state-of-the-art with MCTS | [6] |
+| Reflexion | ALFWorld | +22% improvement via self-reflection | [4] |
+
+### code generation (from sources)
+
+| model/tool | HumanEval | MBPP | SWE-bench | source |
+|------------|-----------|------|-----------|--------|
+| o1-mini | 96.2% | - | - | [45] |
+| o1-mini (Pro) | 76.2% | - | - | [45] |
+| GPT-4o + planning | - | 84.8% | - | [43] |
+| Claude Code | - | - | ~49% (verified) | [44] |
+
+---
+
+## access date
+
+all sources accessed: 2025-12-23

package/dist/roles/architect/briefs/brains.replic/arc101.concept.llm.[article].md

@@ -0,0 +1,25 @@
+# llm (large language model)
+
+## .what
+
+a neural network trained on vast text corpora that predicts the next token in a sequence, enabling it to generate coherent text, follow instructions, and perform reasoning.
+
+## .why
+
+the llm is the core intelligence of a replic brain. it provides the reasoning and generation capabilities that power all downstream behaviors — from understanding natural language to generating code to deciding which tools to invoke.
+
+## dependsOn
+
+- (none — foundational primitive)
+
+## key characteristics
+
+- **autoregressive generation**: produces output one token at a time, conditioning on all previous tokens
+- **context window**: has a fixed maximum number of tokens it can process at once
+- **emergent capabilities**: reasoning, instruction-following, and tool use emerge at scale
+- **stochastic**: outputs are probabilistic, controlled via temperature parameter
+
+## sources
+
+- [Chain-of-Thought Prompting](https://arxiv.org/abs/2201.11903) — demonstrates reasoning emergence in LLMs
+- [CoALA: Cognitive Architectures for Language Agents](https://arxiv.org/abs/2309.02427) — positions LLM as central to agent architecture

package/dist/roles/architect/briefs/brains.replic/arc102.concept.repl.[article].md

@@ -0,0 +1,33 @@
+# repl (read-eval-print-loop)
+
+## .what
+
+an interactive programming pattern where the system reads user input, evaluates it, prints the result, and loops back to read more input.
+
+## .why
+
+the repl pattern enables iterative, conversational interaction. when an llm operates behind a repl, it can receive feedback, execute actions, observe results, and refine its approach — the foundation of agentic behavior.
+
+## dependsOn
+
+- (none — foundational primitive)
+
+## key characteristics
+
+- **read**: accept input from user or environment
+- **eval**: process and execute the input
+- **print**: display results or output
+- **loop**: repeat the cycle indefinitely
+
+## in replic brains
+
+the repl structure manifests as:
+1. **read**: receive user message or tool result
+2. **eval**: llm generates response/action
+3. **print**: emit response or execute tool
+4. **loop**: continue until task complete
+
+## sources
+
+- unix shell, lisp repl — historical precedent
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — describes agentic loop as repl-like

package/dist/roles/architect/briefs/brains.replic/arc103.concept.replic-brain.[article].md

@@ -0,0 +1,35 @@
+# replic-brain
+
+## .what
+
+an llm operating behind a repl interface, forming an interactive system capable of iterative reasoning, tool use, and task completion through conversation.
+
+## .why
+
+the term "replic brain" names the specific architectural pattern where an llm's capabilities are harnessed through a read-eval-print-loop. this pattern enables the llm to act as an agent — receiving feedback, taking actions, and iterating toward goals.
+
+## dependsOn
+
+- `llm` — provides reasoning and generation
+- `repl` — provides interactive loop structure
+
+## key characteristics
+
+- **conversational**: maintains dialogue state across turns
+- **tool-capable**: can invoke external tools and process results
+- **iterative**: refines approach based on feedback
+- **goal-directed**: works toward completing user tasks
+
+## examples
+
+| name | organization | context |
+|------|--------------|---------|
+| claude code | anthropic | cli-based coding assistant |
+| codex | openai | cloud sandbox coding agent |
+| cursor | cursor inc | ide-integrated coding assistant |
+| aider | open source | git-integrated pair programmer |
+
+## sources
+
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — describes the agentic loop pattern
+- [CoALA](https://arxiv.org/abs/2309.02427) — systematic framework for language agent architectures

package/dist/roles/architect/briefs/brains.replic/arc104.concept.context-window.[article].md

@@ -0,0 +1,40 @@
+# context-window
+
+## .what
+
+the fixed-size buffer of tokens that an llm can process in a single forward pass, representing its working memory during generation.
+
+## .why
+
+the context window is the fundamental constraint that shapes all replic brain architectures. it determines how much conversation history, code, and tool results can be processed simultaneously. strategies like context compaction, subagents, and memory hierarchies exist specifically to work within or around this limit.
+
+## dependsOn
+
+- `llm` — context window is a property of the llm
+
+## key characteristics
+
+- **fixed size**: measured in tokens (e.g., 200k tokens for claude)
+- **attention-based**: all tokens attend to all other tokens (O(n²) complexity)
+- **includes everything**: system prompt, conversation, tool calls, tool results
+- **ephemeral**: cleared between sessions (no persistent memory)
+
+## size examples (2024-2025)
+
+| model | context window |
+|-------|----------------|
+| gpt-4o | 128k tokens |
+| claude 3.5/4 | 200k tokens |
+| gemini 1.5 | 1m+ tokens |
+
+## implications for architecture
+
+- longer context = more code/conversation in single pass
+- summarization needed when context fills
+- subagents can isolate context usage
+- caching optimizes repeated prompts
+
+## sources
+
+- [MemGPT](https://arxiv.org/abs/2310.08560) — virtual context management
+- [Claude Documentation](https://docs.anthropic.com) — 200k token context

package/dist/roles/architect/briefs/brains.replic/arc105.concept.system-prompt.[article].md

@@ -0,0 +1,44 @@
+# system-prompt
+
+## .what
+
+the initial instructions provided to an llm at the start of a conversation that define its behavior, capabilities, constraints, and persona.
+
+## .why
+
+the system prompt is the primary mechanism for shaping a replic brain's behavior. it establishes what tools are available, how to use them, what style to adopt, and what constraints to follow. changes to the system prompt fundamentally alter the agent's capabilities.
+
+## dependsOn
+
+- `llm` — interprets and follows the system prompt
+- `context-window` — system prompt consumes context tokens
+
+## key characteristics
+
+- **persistent**: remains in context for entire conversation
+- **privileged**: typically cannot be overridden by user messages
+- **declarative**: describes desired behavior, not code
+- **composable**: can include tool definitions, examples, constraints
+
+## typical contents (replic brains)
+
+```
+- persona/role definition
+- available tools and their schemas
+- behavioral constraints
+- output format requirements
+- examples of desired behavior
+- safety guardrails
+```
+
+## examples
+
+| system | system prompt size | notable elements |
+|--------|-------------------|------------------|
+| claude code | ~15k tokens | tool definitions, coding guidelines, git workflow |
+| codex | varies | sandbox rules, security constraints |
+
+## sources
+
+- [Claude Code System Prompt Analysis](https://zenn.dev/) — detailed breakdown
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — system prompt design

package/dist/roles/architect/briefs/brains.replic/arc106.concept.tool-definition.[article].md

@@ -0,0 +1,59 @@
+# tool-definition
+
+## .what
+
+a schema that describes a tool's interface — its name, purpose, parameters, and expected behavior — enabling an llm to understand when and how to invoke it.
+
+## .why
+
+tool definitions are the contract between the llm and external capabilities. by providing structured schemas, the llm can reason about which tools apply to a task, what parameters to provide, and what results to expect. well-designed tool definitions are essential for reliable agent behavior.
+
+## dependsOn
+
+- `system-prompt` — tool definitions are typically included in system prompt
+- `llm` — interprets tool definitions and decides when to invoke
+
+## key characteristics
+
+- **name**: unique identifier for the tool
+- **description**: natural language explanation of purpose
+- **parameters**: typed schema (often JSON Schema) for inputs
+- **returns**: description of expected output format
+
+## example schema
+
+```json
+{
+  "name": "Read",
+  "description": "Reads a file from the filesystem",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "file_path": {
+        "type": "string",
+        "description": "Absolute path to the file"
+      },
+      "offset": {
+        "type": "number",
+        "description": "Line number to start reading from"
+      }
+    },
+    "required": ["file_path"]
+  }
+}
+```
+
+## tool categories (replic brains)
+
+| category | examples |
+|----------|----------|
+| filesystem | Read, Write, Edit, Glob, Grep |
+| execution | Bash, Task |
+| communication | WebSearch, WebFetch |
+| coordination | TodoWrite, AskUserQuestion |
+
+## sources
+
+- [Advanced Tool Use on Claude](https://www.anthropic.com/engineering/advanced-tool-use) — tool definition patterns
+- [Toolformer](https://arxiv.org/abs/2302.04761) — self-supervised tool learning
+- [MCP Specification](https://modelcontextprotocol.io/) — standardized tool protocol

package/dist/roles/architect/briefs/brains.replic/arc107.concept.tool-call.[article].md

@@ -0,0 +1,54 @@
+# tool-call
+
+## .what
+
+a structured request generated by an llm to invoke a specific tool with given parameters, representing the agent's decision to take an external action.
+
+## .why
+
+tool calls are the mechanism by which replic brains interact with the world beyond text generation. when the llm determines that a task requires external action — reading a file, executing code, searching the web — it emits a tool call. this is the bridge between reasoning and action.
+
+## dependsOn
+
+- `tool-definition` — provides the schema for valid calls
+- `llm` — generates the tool call
+- `agentic-loop` — processes and executes the call
+
+## key characteristics
+
+- **structured**: follows the schema defined in tool-definition
+- **atomic**: one tool call = one action
+- **declarative**: specifies what to do, not how
+- **interruptible**: execution may require user approval
+
+## example
+
+```json
+{
+  "tool": "Read",
+  "parameters": {
+    "file_path": "/home/user/project/src/main.ts",
+    "offset": 100,
+    "limit": 50
+  }
+}
+```
+
+## lifecycle
+
+1. llm generates tool call in response
+2. system extracts and validates parameters
+3. permission check (if required)
+4. tool executes
+5. result returned to context as `tool-result`
+
+## parallelism
+
+some systems allow multiple tool calls in a single response:
+- **independent calls**: can execute in parallel
+- **dependent calls**: must execute sequentially
+
+## sources
+
+- [ReAct](https://arxiv.org/abs/2210.03629) — action in reasoning+acting loop
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — tool call patterns

package/dist/roles/architect/briefs/brains.replic/arc108.concept.tool-result.[article].md

@@ -0,0 +1,58 @@
+# tool-result
+
+## .what
+
+the output returned from executing a tool call, injected back into the llm's context as feedback for continued reasoning.
+
+## .why
+
+tool results close the feedback loop in agentic systems. they allow the llm to observe the consequences of its actions, verify success or failure, and adjust its approach. without tool results, the agent would be operating blind.
+
+## dependsOn
+
+- `tool-call` — produces the result
+- `context-window` — result consumes context tokens
+
+## key characteristics
+
+- **structured or text**: depends on tool (json, stdout, file contents)
+- **may be truncated**: large outputs compressed to fit context
+- **includes metadata**: success/failure, error messages
+- **grounds reasoning**: provides factual information
+
+## example
+
+```
+Tool Result (Read):
+     1→import { Component } from 'react';
+     2→
+     3→export class App extends Component {
+     4→  render() {
+     5→    return <div>Hello World</div>;
+     6→  }
+     7→}
+```
+
+## handling large results
+
+| strategy | description |
+|----------|-------------|
+| truncation | cut output at N characters/lines |
+| summarization | llm summarizes before adding to context |
+| pagination | return chunks with offset/limit |
+| streaming | process incrementally |
+
+## error results
+
+tool results may indicate failures:
+- file not found
+- permission denied
+- timeout exceeded
+- invalid parameters
+
+the llm must interpret these and adapt its approach.
+
+## sources
+
+- [ReAct](https://arxiv.org/abs/2210.03629) — observation in ReAct loop
+- [Inner Monologue](https://arxiv.org/abs/2207.05608) — environment feedback

package/dist/roles/architect/briefs/brains.replic/arc109.concept.agentic-loop.[article].md

@@ -0,0 +1,62 @@
+# agentic-loop
+
+## .what
+
+the core execution pattern of replic brains: repeatedly generate llm response, check for tool calls, execute tools, append results, and continue until task completion.
+
+## .why
+
+the agentic loop is what transforms a stateless llm into a persistent, goal-directed agent. by iterating through generate → execute → observe cycles, the agent can accomplish complex multi-step tasks that exceed what a single generation could produce.
+
+## dependsOn
+
+- `llm` — generates responses and tool calls
+- `repl` — the agentic loop is the repl pattern applied to llms
+- `tool-call` — actions to execute
+- `tool-result` — feedback from actions
+- `context-window` — accumulates conversation history
+
+## pseudocode
+
+```python
+while True:
+    response = llm.generate(context_window)
+
+    if response.has_tool_calls:
+        for tool_call in response.tool_calls:
+            result = execute_tool(tool_call)
+            context_window.append(result)
+    else:
+        return response  # task complete, exit loop
+```
+
+## key characteristics
+
+- **unbounded iteration**: continues until llm stops calling tools
+- **context accumulation**: history grows with each turn
+- **goal-directed**: llm decides when task is complete
+- **interruptible**: user can inject messages mid-loop
+
+## termination conditions
+
+| condition          | trigger                         |
+| ------------------ | ------------------------------- |
+| natural completion | llm responds without tool calls |
+| context exhaustion | context window fills up         |
+| user interruption  | user sends new message          |
+| timeout            | max iterations or time exceeded |
+| error              | unrecoverable tool failure      |
+
+## variants
+
+| variant     | modification                         |
+| ----------- | ------------------------------------ |
+| react       | interleave explicit reasoning traces |
+| reflexion   | add self-reflection after failures   |
+| tree search | explore multiple action branches     |
+
+## sources
+
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — canonical loop description
+- [ReAct](https://arxiv.org/abs/2210.03629) — reasoning-augmented loop
+- [CoALA](https://arxiv.org/abs/2309.02427) — framework for loop variants

package/dist/roles/architect/briefs/brains.replic/arc110.concept.reasoning-trace.[article].md

@@ -0,0 +1,58 @@
+# reasoning-trace
+
+## .what
+
+explicit intermediate reasoning steps that an llm produces before generating a final answer, making its thought process visible and improving accuracy on complex tasks.
+
+## .why
+
+reasoning traces transform black-box generation into interpretable problem-solving. by externalizing intermediate steps, the llm can break down complex problems, catch errors in its reasoning, and provide explanations that humans can verify. this is the foundation for chain-of-thought and related techniques.
+
+## dependsOn
+
+- `llm` — generates the reasoning trace
+- `context-window` — traces consume tokens
+
+## key characteristics
+
+- **intermediate**: produced before final answer
+- **natural language**: typically readable text
+- **step-by-step**: decomposed reasoning
+- **self-documenting**: explains the llm's approach
+
+## example
+
+```
+Question: What is 23 × 17?
+
+Reasoning trace:
+- I need to multiply 23 by 17
+- 23 × 17 = 23 × (10 + 7)
+- = 23 × 10 + 23 × 7
+- = 230 + 161
+- = 391
+
+Answer: 391
+```
+
+## elicitation methods
+
+| method | technique |
+|--------|-----------|
+| zero-shot | "Let's think step by step" |
+| few-shot | provide example traces |
+| trained | fine-tune on trace datasets |
+| scratchpad | dedicated trace output space |
+
+## benefits
+
+- improved accuracy on reasoning tasks
+- reduced hallucination
+- debuggable/auditable outputs
+- enables self-correction
+
+## sources
+
+- [Chain-of-Thought Prompting](https://arxiv.org/abs/2201.11903) — seminal paper
+- [Scratchpads](https://arxiv.org/abs/2112.00114) — intermediate computation
+- [Extended Thinking](https://www.anthropic.com/news/visible-extended-thinking) — claude's thinking mode