rhachet-roles-bhrain 0.1.0 → 0.2.0

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.