rhachet-roles-bhrain 0.1.1 → 0.3.0

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

package/dist/roles/architect/briefs/brains.replic/arc120.concept.session.[article].md

@@ -0,0 +1,67 @@
+# session
+
+## .what
+
+a single continuous interaction instance between a user and a replic brain, encompassing the conversation history, tool invocations, and accumulated context from start to termination.
+
+## .why
+
+the session is the unit of work for replic brains. it defines the scope of context retention, the boundary of memory, and the lifecycle of an agent's engagement with a task. understanding sessions is essential for designing effective agent workflows.
+
+## dependsOn
+
+- `context-window` — session state lives in context
+- `agentic-loop` — session contains loop iterations
+- `message` — session contains messages
+
+## lifecycle
+
+```
+┌─────────────────────────────────────────┐
+│              SESSION START              │
+├─────────────────────────────────────────┤
+│  [system prompt loaded]                 │
+│  [user message 1]                       │
+│  [assistant response 1 + tool calls]    │
+│  [tool results]                         │
+│  [assistant response 2]                 │
+│  [user message 2]                       │
+│  ...                                    │
+├─────────────────────────────────────────┤
+│              SESSION END                │
+│  - user closes                          │
+│  - context exhausted                    │
+│  - timeout                              │
+└─────────────────────────────────────────┘
+```
+
+## key characteristics
+
+- **stateful**: accumulates context over time
+- **bounded**: limited by context window
+- **isolated**: separate from other sessions
+- **resumable**: some systems support continuation
+
+## session persistence
+
+| approach | mechanism |
+|----------|-----------|
+| ephemeral | context cleared on end |
+| summarized | save summary for resumption |
+| full history | persist all messages externally |
+| project-based | context per project directory |
+
+## multi-session patterns
+
+```
+Session 1: "Set up the database schema"
+    │
+    ↓ (summarized, ended)
+
+Session 2: "Add authentication" (builds on summary)
+```
+
+## sources
+
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — session design
+- [MemGPT](https://arxiv.org/abs/2310.08560) — cross-session memory

package/dist/roles/architect/briefs/brains.replic/arc121.concept.message.[article].md

@@ -0,0 +1,79 @@
+# message
+
+## .what
+
+the atomic unit of conversation in a replic brain session, carrying content from a specific role (user, assistant, system, tool) with associated metadata.
+
+## .why
+
+messages are the building blocks of context. understanding message structure and roles is fundamental to designing effective prompts, managing context, and debugging agent behavior. each message type serves a distinct purpose in the conversation flow.
+
+## dependsOn
+
+- `session` — messages exist within sessions
+- `context-window` — messages consume tokens
+
+## message roles
+
+| role | purpose | example |
+|------|---------|---------|
+| system | initial instructions | system prompt, tool definitions |
+| user | human input | questions, commands, feedback |
+| assistant | llm output | responses, tool calls, reasoning |
+| tool | tool execution results | file contents, command output |
+
+## message structure
+
+```json
+{
+  "role": "assistant",
+  "content": "Let me read that file for you.",
+  "tool_calls": [
+    {
+      "id": "call_abc123",
+      "type": "function",
+      "function": {
+        "name": "Read",
+        "arguments": "{\"file_path\": \"/src/main.ts\"}"
+      }
+    }
+  ]
+}
+```
+
+## content types
+
+| type | description |
+|------|-------------|
+| text | natural language content |
+| tool_calls | structured action requests |
+| tool_results | output from tool execution |
+| images | visual input (multimodal) |
+| thinking | extended reasoning (if visible) |
+
+## message flow in agentic loop
+
+```
+[user message]
+       │
+       ↓
+[assistant message + tool_calls]
+       │
+       ↓
+[tool message (result)]
+       │
+       ↓
+[assistant message (continues)]
+```
+
+## token accounting
+
+each message consumes tokens based on:
+- role tokens (small overhead)
+- content tokens (varies widely)
+- metadata (tool call structures)
+
+## sources
+
+- [Anthropic API Documentation](https://docs.anthropic.com) — message format
+- [OpenAI API Documentation](https://platform.openai.com/docs) — chat completions

package/dist/roles/architect/briefs/brains.replic/arc122.concept.plan-and-solve.[article].md

@@ -0,0 +1,80 @@
+# plan-and-solve
+
+## .what
+
+a zero-shot prompting strategy that decomposes complex tasks into two phases: first devise a plan of subtasks, then execute each subtask sequentially.
+
+## .why
+
+plan-and-solve addresses a limitation of direct chain-of-thought: models may rush into computation without strategic planning. by explicitly separating planning from execution, PS prompting improves accuracy on multi-step reasoning tasks without requiring few-shot examples.
+
+## dependsOn
+
+- `reasoning-trace` — plan is a form of reasoning
+- `llm` — generates plan and executes steps
+
+## pattern structure
+
+```
+Prompt: "Let's first understand the problem and devise a plan
+         to solve it. Then, let's carry out the plan and solve
+         the problem step by step."
+
+Response:
+Plan:
+1. Identify the variables
+2. Set up the equation
+3. Solve for x
+4. Verify the answer
+
+Execution:
+Step 1: The variables are...
+Step 2: The equation is...
+Step 3: Solving: x = ...
+Step 4: Verification: ...
+
+Answer: x = 42
+```
+
+## key characteristics
+
+- **zero-shot**: no examples needed
+- **explicit planning**: forces strategic thinking
+- **sequential execution**: follows plan order
+- **self-contained**: plan and execution in one response
+
+## variants
+
+| variant | modification |
+|---------|--------------|
+| PS | basic plan + solve |
+| PS+ | adds "extract relevant variables" |
+| ADaPT | adaptive as-needed decomposition |
+
+## benchmark performance
+
+| benchmark | improvement over zero-shot CoT |
+|-----------|-------------------------------|
+| GSM8K | +6.6% (GPT-3) |
+| AQuA | +6.0% |
+| MultiArith | +4.0% |
+
+## vs few-shot CoT
+
+| aspect | PS | few-shot CoT |
+|--------|-----|--------------|
+| examples needed | 0 | 3-8 |
+| planning | explicit | implicit |
+| adaptability | high | fixed pattern |
+
+## application in replic brains
+
+many replic brains implement plan-and-solve implicitly:
+- "Plan" subagent type
+- EnterPlanMode tool
+- explicit planning before coding
+
+## sources
+
+- [Plan-and-Solve Prompting](https://arxiv.org/abs/2305.04091) — original paper
+- [Understanding LLM Agent Planning Survey](https://arxiv.org/abs/2402.02716) — positions in taxonomy

package/dist/roles/architect/briefs/brains.replic/arc150.concepts.treestruct.[article].md

@@ -0,0 +1,126 @@
+# concepts treestruct
+
+## .what
+
+a hierarchical visualization of replic brain concepts showing dependency relationships — foundational concepts at roots, composed concepts as branches.
+
+## .why
+
+understanding how concepts compose reveals the architecture of replic brains. this treestruct shows which concepts are foundational (independent), which depend on others, and how they combine to form complete agent systems.
+
+---
+
+## dependency treestruct
+
+```
+replic-brain
+├── llm ································· [arc101]
+│   ├── context-window ················· [arc104]
+│   │   ├── context-compaction ········· [arc116]
+│   │   │   └── (llm, agentic-loop)
+│   │   └── message ···················· [arc121]
+│   │       └── session ················ [arc120]
+│   │           └── (agentic-loop)
+│   │
+│   ├── system-prompt ·················· [arc105]
+│   │   └── tool-definition ············ [arc106]
+│   │       ├── tool-call ·············· [arc107]
+│   │       │   └── tool-result ········ [arc108]
+│   │       └── mcp ···················· [arc119]
+│   │           └── (tool-call, tool-result)
+│   │
+│   └── reasoning-trace ················ [arc110]
+│       ├── react-pattern ·············· [arc111]
+│       │   └── (agentic-loop, tool-call, tool-result)
+│       ├── reflexion-pattern ·········· [arc112]
+│       │   └── (agentic-loop)
+│       ├── tree-of-thoughts ··········· [arc113]
+│       │   └── lats-pattern ··········· [arc115]
+│       │       └── (agentic-loop, reflexion-pattern)
+│       ├── self-consistency ··········· [arc114]
+│       ├── plan-and-solve ············· [arc122]
+│       └── extended-thinking ·········· [arc118]
+│           └── (context-window)
+│
+└── repl ······························· [arc102]
+    └── agentic-loop ··················· [arc109]
+        ├── (llm, context-window, tool-call, tool-result)
+        └── subagent ··················· [arc117]
+            └── (context-window, tool-definition)
+```
+
+---
+
+## concept index
+
+| arc# | concept | brief |
+|------|---------|-------|
+| 101 | llm | [arc101.concept.llm.[article].md](./arc101.concept.llm.[article].md) |
+| 102 | repl | [arc102.concept.repl.[article].md](./arc102.concept.repl.[article].md) |
+| 103 | replic-brain | [arc103.concept.replic-brain.[article].md](./arc103.concept.replic-brain.[article].md) |
+| 104 | context-window | [arc104.concept.context-window.[article].md](./arc104.concept.context-window.[article].md) |
+| 105 | system-prompt | [arc105.concept.system-prompt.[article].md](./arc105.concept.system-prompt.[article].md) |
+| 106 | tool-definition | [arc106.concept.tool-definition.[article].md](./arc106.concept.tool-definition.[article].md) |
+| 107 | tool-call | [arc107.concept.tool-call.[article].md](./arc107.concept.tool-call.[article].md) |
+| 108 | tool-result | [arc108.concept.tool-result.[article].md](./arc108.concept.tool-result.[article].md) |
+| 109 | agentic-loop | [arc109.concept.agentic-loop.[article].md](./arc109.concept.agentic-loop.[article].md) |
+| 110 | reasoning-trace | [arc110.concept.reasoning-trace.[article].md](./arc110.concept.reasoning-trace.[article].md) |
+| 111 | react-pattern | [arc111.concept.react-pattern.[article].md](./arc111.concept.react-pattern.[article].md) |
+| 112 | reflexion-pattern | [arc112.concept.reflexion-pattern.[article].md](./arc112.concept.reflexion-pattern.[article].md) |
+| 113 | tree-of-thoughts | [arc113.concept.tree-of-thoughts.[article].md](./arc113.concept.tree-of-thoughts.[article].md) |
+| 114 | self-consistency | [arc114.concept.self-consistency.[article].md](./arc114.concept.self-consistency.[article].md) |
+| 115 | lats-pattern | [arc115.concept.lats-pattern.[article].md](./arc115.concept.lats-pattern.[article].md) |
+| 116 | context-compaction | [arc116.concept.context-compaction.[article].md](./arc116.concept.context-compaction.[article].md) |
+| 117 | subagent | [arc117.concept.subagent.[article].md](./arc117.concept.subagent.[article].md) |
+| 118 | extended-thinking | [arc118.concept.extended-thinking.[article].md](./arc118.concept.extended-thinking.[article].md) |
+| 119 | mcp | [arc119.concept.mcp.[article].md](./arc119.concept.mcp.[article].md) |
+| 120 | session | [arc120.concept.session.[article].md](./arc120.concept.session.[article].md) |
+| 121 | message | [arc121.concept.message.[article].md](./arc121.concept.message.[article].md) |
+| 122 | plan-and-solve | [arc122.concept.plan-and-solve.[article].md](./arc122.concept.plan-and-solve.[article].md) |
+
+---
+
+## layer analysis
+
+### foundational (no dependencies)
+- `llm` — the reasoning engine
+- `repl` — the interaction pattern
+
+### core infrastructure
+- `context-window` — working memory
+- `system-prompt` — behavior configuration
+- `tool-definition` — capability schemas
+
+### execution layer
+- `agentic-loop` — the orchestration pattern
+- `tool-call` / `tool-result` — action interface
+- `message` / `session` — conversation structure
+
+### reasoning strategies
+- `reasoning-trace` — intermediate steps
+- `react-pattern` — grounded reasoning
+- `reflexion-pattern` — self-improvement
+- `tree-of-thoughts` — deliberate search
+- `self-consistency` — ensemble reasoning
+- `lats-pattern` — learned search
+- `plan-and-solve` — explicit planning
+- `extended-thinking` — compute scaling
+
+### extensions
+- `context-compaction` — memory management
+- `subagent` — parallel/isolated execution
+- `mcp` — tool standardization
+
+---
+
+## architectural insight
+
+the treestruct reveals that replic brains are built from:
+
+1. **two primitives**: llm + repl
+2. **three constraints**: context-window, system-prompt, tool interface
+3. **one core loop**: agentic-loop
+4. **many reasoning strategies**: interchangeable approaches to improve quality
+5. **extension mechanisms**: compaction, subagents, protocols
+
+different replic brains make different choices within this framework, but all share the same foundational structure.