rhachet-roles-bhrain 0.1.1 → 0.2.0

package/dist/roles/architect/briefs/brains.replic/arc111.concept.react-pattern.[article].md

@@ -0,0 +1,65 @@
+# react-pattern
+
+## .what
+
+a prompting paradigm that interleaves reasoning traces with actions, producing explicit Thought → Action → Observation cycles that ground reasoning in real-world feedback.
+
+## .why
+
+react addresses a fundamental limitation of pure reasoning: hallucination. by forcing the model to take actions and observe actual results between reasoning steps, react grounds abstract thought in concrete feedback. this synergy of reasoning and acting enables more reliable task completion.
+
+## dependsOn
+
+- `reasoning-trace` — the "thought" component
+- `tool-call` — the "action" component
+- `tool-result` — the "observation" component
+- `agentic-loop` — orchestrates the cycle
+
+## pattern structure
+
+```
+Thought: I need to find information about X
+Action: Search("X")
+Observation: [search results]
+Thought: Based on these results, I should check Y
+Action: Read("file_y.txt")
+Observation: [file contents]
+Thought: Now I can answer the question
+Answer: ...
+```
+
+## benchmark performance
+
+| benchmark | react vs baseline |
+|-----------|-------------------|
+| HotPotQA | competitive with CoT, lower hallucination (6% vs 14%) |
+| ALFWorld | +34% over imitation learning |
+| WebShop | significantly outperforms Act-only |
+
+## tradeoffs
+
+### strengths
+- grounded in real observations
+- lower hallucination rate
+- interpretable decision process
+- recovers from errors via feedback
+
+### weaknesses
+- structurally constrained (forced action after each thought)
+- dependent on quality of retrieved information
+- may force unnecessary actions
+
+## comparison with pure CoT
+
+| aspect | CoT | ReAct |
+|--------|-----|-------|
+| grounding | internal only | external observations |
+| hallucination | higher | lower |
+| flexibility | high | constrained by structure |
+| task types | reasoning | reasoning + interaction |
+
+## sources
+
+- [ReAct: Synergizing Reasoning and Acting](https://arxiv.org/abs/2210.03629) — original paper (ICLR 2023)
+- [Google Research Blog](https://research.google/blog/react-synergizing-reasoning-and-acting-in-language-models/) — overview
+- [Comprehensive Guide to ReAct](https://www.mercity.ai/blog-post/react-prompting-and-react-based-agentic-systems) — practical guide

package/dist/roles/architect/briefs/brains.replic/arc112.concept.reflexion-pattern.[article].md

@@ -0,0 +1,68 @@
+# reflexion-pattern
+
+## .what
+
+an agent architecture that adds explicit self-reflection after task attempts, storing verbal feedback in memory to improve performance on subsequent trials through "verbal reinforcement learning."
+
+## .why
+
+reflexion addresses a key limitation of single-attempt agents: they cannot learn from their mistakes within a session. by reflecting on failures and storing insights, the agent can iteratively improve without weight updates. this enables rapid adaptation and higher eventual success rates.
+
+## dependsOn
+
+- `agentic-loop` — base execution pattern
+- `reasoning-trace` — reflection is a form of reasoning
+- `context-window` — stores reflection memory
+
+## pattern structure
+
+```
+Attempt 1:
+  [Execute task]
+  Result: Failed (test case 3)
+
+Reflection:
+  "I failed because I didn't handle the edge case where
+   the input is empty. Next time I should check for
+   empty inputs before processing."
+
+Attempt 2:
+  [Execute task with reflection in context]
+  Result: Passed
+```
+
+## key components
+
+| component | purpose |
+|-----------|---------|
+| actor | executes actions in environment |
+| evaluator | scores trajectory (success/failure) |
+| self-reflection | generates verbal feedback |
+| memory | stores reflections for future attempts |
+
+## benchmark performance
+
+| benchmark | improvement |
+|-----------|-------------|
+| ALFWorld | +22% success rate with reflection |
+| HotPotQA | improved accuracy over baseline ReAct |
+| programming | higher pass rates on iterative debugging |
+
+## vs other patterns
+
+| pattern | learns from failure? | mechanism |
+|---------|---------------------|-----------|
+| ReAct | no | single attempt |
+| Reflexion | yes | verbal memory |
+| LATS | yes | tree search with backtracking |
+
+## implementation notes
+
+- reflection is stored as text in context or external memory
+- number of attempts typically capped (e.g., 3-5)
+- works best when failure modes are diverse
+
+## sources
+
+- [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) — original paper
+- [AgentBench](https://arxiv.org/abs/2308.03688) — benchmark including reflexion variants

package/dist/roles/architect/briefs/brains.replic/arc113.concept.tree-of-thoughts.[article].md

@@ -0,0 +1,76 @@
+# tree-of-thoughts
+
+## .what
+
+a deliberate problem-solving framework that explores multiple reasoning paths as a tree structure, using search algorithms (BFS/DFS) and evaluation to find optimal solutions.
+
+## .why
+
+tree of thoughts addresses the limitation of linear chain-of-thought: once a reasoning path is taken, there's no backtracking. by explicitly exploring multiple branches and evaluating intermediate states, ToT enables deliberate planning and can solve problems requiring lookahead that linear approaches cannot.
+
+## dependsOn
+
+- `reasoning-trace` — each node contains reasoning
+- `llm` — generates and evaluates thoughts
+
+## pattern structure
+
+```
+                    [Problem]
+                       │
+          ┌────────────┼────────────┐
+          │            │            │
+     [Thought A]  [Thought B]  [Thought C]
+          │            │            │
+       [eval: 0.8]  [eval: 0.3]  [eval: 0.9] ← best
+          │                         │
+     [Thought A1]              [Thought C1]
+          │                         │
+       [eval: 0.6]              [eval: 0.95] ← selected
+```
+
+## key components
+
+| component | purpose |
+|-----------|---------|
+| thought decomposition | break problem into steps |
+| thought generator | propose multiple candidates |
+| state evaluator | score intermediate states |
+| search algorithm | BFS, DFS, or beam search |
+
+## benchmark performance
+
+| benchmark | ToT vs CoT |
+|-----------|------------|
+| Game of 24 | 74% vs 4% |
+| Creative Writing | improved coherence |
+| Crosswords | significantly higher solve rate |
+
+## search strategies
+
+| strategy | characteristic |
+|----------|----------------|
+| BFS | explore all options at each depth |
+| DFS | explore deeply first, backtrack |
+| beam search | keep top-k candidates at each level |
+
+## cost tradeoff
+
+ToT requires significantly more LLM calls than linear approaches:
+- multiple thought proposals per step
+- evaluation calls for each candidate
+- may explore many branches
+
+## vs other patterns
+
+| pattern | exploration | backtracking |
+|---------|-------------|--------------|
+| CoT | linear | none |
+| Self-Consistency | parallel paths, no interaction | none |
+| ToT | tree structure | yes |
+| LATS | tree + MCTS | yes, with learning |
+
+## sources
+
+- [Tree of Thoughts: Deliberate Problem Solving](https://arxiv.org/abs/2305.10601) — original paper (NeurIPS 2023)
+- [CoALA](https://arxiv.org/abs/2309.02427) — positions ToT in agent framework

package/dist/roles/architect/briefs/brains.replic/arc114.concept.self-consistency.[article].md

@@ -0,0 +1,73 @@
+# self-consistency
+
+## .what
+
+a decoding strategy that samples multiple reasoning paths from the llm and selects the final answer by majority vote, leveraging the intuition that correct reasoning is more likely to converge on the same answer.
+
+## .why
+
+self-consistency exploits the stochastic nature of llm generation as a feature rather than a bug. different reasoning paths may make different mistakes, but correct paths tend to agree on the final answer. by sampling multiple times and voting, we reduce the impact of individual reasoning errors.
+
+## dependsOn
+
+- `reasoning-trace` — each sample produces a trace
+- `llm` — generates multiple samples
+
+## pattern structure
+
+```
+Question: What is the capital of Australia?
+
+Sample 1: "Australia is in Oceania. Sydney is the largest city.
+           But the capital is Canberra." → Canberra
+
+Sample 2: "Australia's government is in Canberra, which was
+           purpose-built as the capital." → Canberra
+
+Sample 3: "The largest city is Sydney, which might be the
+           capital." → Sydney
+
+Majority vote: Canberra (2/3)
+Final answer: Canberra
+```
+
+## key characteristics
+
+- **embarrassingly parallel**: all samples independent
+- **temperature > 0**: requires stochastic sampling
+- **answer extraction**: must identify final answer in each trace
+- **voting mechanism**: typically majority, can be weighted
+
+## benchmark performance
+
+| benchmark | improvement over greedy CoT |
+|-----------|---------------------------|
+| arithmetic | +17.9% (GSM8K) |
+| commonsense | +11.0% (CommonsenseQA) |
+| symbolic | significant gains |
+
+## parameters
+
+| parameter | effect |
+|-----------|--------|
+| num_samples | more samples = higher accuracy, higher cost |
+| temperature | higher = more diverse samples |
+| voting method | majority, weighted, etc. |
+
+## cost analysis
+
+self-consistency is more expensive than single-path CoT:
+- linear cost increase with sample count
+- typically 5-40 samples used
+- parallelizable (latency ≈ single sample if concurrent)
+
+## limitations
+
+- requires extractable final answers
+- expensive for long generations
+- doesn't help if all paths fail similarly
+
+## sources
+
+- [Self-Consistency Improves Chain of Thought Reasoning](https://arxiv.org/abs/2203.11171) — original paper
+- [Reasoning with LM Prompting Survey](https://github.com/zjunlp/Prompt4ReasoningPapers) — comparison with other methods

package/dist/roles/architect/briefs/brains.replic/arc115.concept.lats-pattern.[article].md

@@ -0,0 +1,78 @@
+# lats-pattern (language agent tree search)
+
+## .what
+
+an advanced agent framework that combines tree-of-thoughts with monte carlo tree search (MCTS), using external feedback and learned value functions to guide exploration of action sequences.
+
+## .why
+
+LATS addresses limitations of both linear agents (no backtracking) and static tree search (no learning). by incorporating MCTS principles — selection, expansion, simulation, backpropagation — LATS can learn from failed trajectories and allocate search effort efficiently toward promising paths.
+
+## dependsOn
+
+- `tree-of-thoughts` — tree structure for exploration
+- `agentic-loop` — action execution
+- `reflexion-pattern` — learning from feedback
+
+## mcts components in LATS
+
+| component | implementation |
+|-----------|----------------|
+| selection | UCB1-guided node choice |
+| expansion | llm generates candidate actions |
+| simulation | execute action, observe result |
+| backpropagation | update values based on outcome |
+
+## pattern structure
+
+```
+        [Root State]
+             │
+    ┌────────┼────────┐
+    │        │        │
+ [A:0.6]  [B:0.8]  [C:0.4]  ← UCB1 selects B
+             │
+    ┌────────┼────────┐
+    │        │        │
+ [B1:0.7] [B2:0.9] [B3:0.5]  ← expand B, simulate
+             │
+          [success]
+             │
+         backpropagate +reward
+```
+
+## benchmark performance
+
+| benchmark | LATS performance |
+|-----------|-----------------|
+| HotPotQA | state-of-the-art among agent methods |
+| WebShop | improved over ReAct/Reflexion |
+| Programming | higher solve rates with search |
+
+## key innovations over ToT
+
+| aspect | ToT | LATS |
+|--------|-----|------|
+| exploration | static heuristic | learned UCB1 |
+| feedback | evaluation only | environment + reflection |
+| memory | none | experience buffer |
+| replanning | from scratch | informed by history |
+
+## computational cost
+
+LATS is more expensive than simpler methods:
+- multiple simulation trajectories
+- value function updates
+- but more sample-efficient than random exploration
+
+## when to use
+
+- complex multi-step tasks
+- sparse reward signals
+- when backtracking is valuable
+- sufficient compute budget
+
+## sources
+
+- [Language Agent Tree Search (LATS)](https://arxiv.org/abs/2310.04406) — original paper (ICML 2024)
+- [Understanding LLM Agent Planning Survey](https://arxiv.org/abs/2402.02716) — positions LATS in taxonomy

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

@@ -0,0 +1,71 @@
+# context-compaction
+
+## .what
+
+techniques for reducing the token count of accumulated context while preserving essential information, enabling long-running agent sessions within fixed context window limits.
+
+## .why
+
+as replic brains iterate through the agentic loop, context accumulates: tool results, conversation turns, reasoning traces. without compaction, the context window fills and the agent cannot continue. compaction strategies allow sessions to persist indefinitely while retaining relevant information.
+
+## dependsOn
+
+- `context-window` — the constraint being managed
+- `llm` — may perform summarization
+- `agentic-loop` — produces context to compact
+
+## strategies
+
+### summarization
+condense earlier conversation/results into summaries:
+```
+[Original: 5000 tokens of tool results]
+       ↓ summarize
+[Summary: 200 tokens capturing key findings]
+```
+
+### sliding window
+keep only the most recent N turns:
+```
+[turn 1] [turn 2] [turn 3] [turn 4] [turn 5]
+       ↓ window of 3
+                 [turn 3] [turn 4] [turn 5]
+```
+
+### hierarchical memory (MemGPT)
+tier information by recency/importance:
+```
+L1 (context): current working set
+L2 (recall): summarized past sessions
+L3 (archive): compressed long-term storage
+```
+
+### selective retention
+keep only tool results that inform current task:
+```
+[file read A] [file read B] [file read C]
+       ↓ task now focuses on C
+                             [file read C]
+```
+
+## tradeoffs
+
+| strategy | preserves | loses |
+|----------|-----------|-------|
+| summarization | gist | verbatim details |
+| sliding window | recency | early context |
+| hierarchical | structure | fast access to old data |
+| selective | relevance | potentially useful info |
+
+## implementation in replic brains
+
+| system | compaction approach |
+|--------|---------------------|
+| claude code | auto-summarization when context fills |
+| codex cloud | full context (large windows) |
+| aider | git diff-based context |
+
+## sources
+
+- [MemGPT: Towards LLMs as Operating Systems](https://arxiv.org/abs/2310.08560) — hierarchical memory
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — summarization patterns

package/dist/roles/architect/briefs/brains.replic/arc117.concept.subagent.[article].md

@@ -0,0 +1,71 @@
+# subagent
+
+## .what
+
+a child agent spawned by a parent agent, operating with its own isolated context window to perform a delegated subtask before returning results.
+
+## .why
+
+subagents address two key challenges: context exhaustion and task parallelization. by delegating subtasks to agents with fresh context windows, the parent can tackle larger problems without filling its own context. subagents can also run in parallel for independent tasks.
+
+## dependsOn
+
+- `agentic-loop` — both parent and child run loops
+- `context-window` — isolation is the key benefit
+- `tool-definition` — subagent spawning is a tool
+
+## pattern
+
+```
+Parent Agent (main context)
+    │
+    ├── Task tool: "explore codebase for auth patterns"
+    │       │
+    │       └── Subagent (fresh context)
+    │               ├── Glob, Grep, Read...
+    │               └── Returns summary
+    │
+    └── Continues with summary in context
+```
+
+## key characteristics
+
+- **isolated context**: subagent starts fresh
+- **focused task**: single delegated objective
+- **returns results**: output injected into parent context
+- **may be typed**: different subagent types for different tasks
+
+## subagent types (claude code)
+
+| type | purpose | tools available |
+|------|---------|-----------------|
+| Explore | codebase exploration | Glob, Grep, Read |
+| Plan | implementation planning | Read, planning tools |
+| general-purpose | complex multi-step tasks | all tools |
+
+## parallelization
+
+subagents enable parallel execution:
+```
+Parent: "search for auth and search for database patterns"
+    │
+    ├── Subagent A: auth exploration ──────┐
+    │                                      ├── (parallel)
+    └── Subagent B: database exploration ──┘
+    │
+    └── Combine results
+```
+
+## tradeoffs
+
+| benefit | cost |
+|---------|------|
+| context isolation | summarization loss when returning |
+| parallelization | coordination complexity |
+| fresh start | loses parent context unless passed |
+| focused execution | additional API calls |
+
+## sources
+
+- [Building Agents with Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) — subagent patterns
+- [Claude Code Documentation](https://docs.anthropic.com) — Task tool specification

package/dist/roles/architect/briefs/brains.replic/arc118.concept.extended-thinking.[article].md

@@ -0,0 +1,69 @@
+# extended-thinking
+
+## .what
+
+a capability that allows an llm to allocate additional computation (serial test-time compute) to reasoning before producing a final response, controlled by a token budget.
+
+## .why
+
+extended thinking enables "thinking harder" about complex problems. by giving the model a dedicated budget for internal reasoning, it can explore approaches, verify its work, and catch errors before committing to an answer. this is particularly valuable for coding, math, and analysis tasks.
+
+## dependsOn
+
+- `llm` — must support thinking mode
+- `reasoning-trace` — thinking produces traces
+- `context-window` — thinking consumes budget tokens
+
+## mechanism
+
+```
+[User Query]
+       │
+       ↓
+[Extended Thinking: up to N tokens]
+  - "Let me consider the approaches..."
+  - "First approach: ..."
+  - "Wait, that won't work because..."
+  - "Better approach: ..."
+       │
+       ↓
+[Final Response: informed by thinking]
+```
+
+## key characteristics
+
+- **token budget**: user specifies max thinking tokens (1k-128k)
+- **hybrid mode**: can be toggled on/off per request
+- **serial compute**: sequential reasoning steps
+- **varying visibility**: thinking may be hidden or shown
+
+## budget guidelines
+
+| budget | suitable for |
+|--------|--------------|
+| 1k-4k | simple analysis |
+| 4k-16k | moderate complexity |
+| 16k-64k | complex coding/math |
+| 64k-128k | deep research |
+
+## integration with tools
+
+extended thinking can be combined with tool use:
+- think before deciding which tools to use
+- think after receiving tool results
+- "think" tool forces explicit reasoning pause
+
+## vs other patterns
+
+| pattern | mechanism |
+|---------|-----------|
+| CoT | inline reasoning in response |
+| ToT | explore multiple branches |
+| Extended thinking | dedicated compute budget |
+| Self-consistency | multiple samples, voting |
+
+## sources
+
+- [Claude's Extended Thinking](https://www.anthropic.com/news/visible-extended-thinking) — announcement
+- [Using Extended Thinking](https://support.claude.com/en/articles/10574485-using-extended-thinking) — documentation
+- [The "think" Tool](https://www.anthropic.com/engineering/claude-think-tool) — tool integration

package/dist/roles/architect/briefs/brains.replic/arc119.concept.mcp.[article].md

@@ -0,0 +1,78 @@
+# mcp (model context protocol)
+
+## .what
+
+an open protocol that standardizes how llm applications connect to external tools, data sources, and services through a unified interface.
+
+## .why
+
+mcp solves the N×M integration problem: without a standard, every llm application must build custom integrations for every tool. with mcp, tool providers implement the protocol once, and any mcp-compatible application can use it. this enables a rich ecosystem of interoperable tools.
+
+## dependsOn
+
+- `tool-definition` — mcp defines tool schemas
+- `tool-call` — mcp routes tool invocations
+- `tool-result` — mcp returns structured results
+
+## architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐
+│  LLM Application │     │   MCP Server     │
+│  (Claude Code)   │────▶│  (filesystem)    │
+└─────────────────┘     └──────────────────┘
+         │                       │
+         │     MCP Protocol      │
+         │◀─────────────────────▶│
+         │                       │
+         ▼                       ▼
+┌─────────────────┐     ┌──────────────────┐
+│   MCP Server    │     │   MCP Server     │
+│   (database)    │     │   (github)       │
+└─────────────────┘     └──────────────────┘
+```
+
+## protocol components
+
+| component | purpose |
+|-----------|---------|
+| tools | actions the server exposes |
+| resources | data the server provides |
+| prompts | templates for common operations |
+| transports | communication channels (stdio, http) |
+
+## tool definition in mcp
+
+```json
+{
+  "name": "read_file",
+  "description": "Read contents of a file",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "path": { "type": "string" }
+    },
+    "required": ["path"]
+  }
+}
+```
+
+## benefits
+
+- **extensibility**: add new tools without changing core
+- **standardization**: consistent interface across providers
+- **composability**: combine multiple servers
+- **permission control**: allowedTools/disallowedTools
+
+## adoption
+
+| system | mcp support |
+|--------|-------------|
+| claude code | native, primary integration mechanism |
+| cursor | supported |
+| cline | supported |
+
+## sources
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) — specification
+- [Building Agents with Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) — MCP integration