rhachet-roles-bhrain 0.1.0 → 0.2.0

package/dist/roles/architect/briefs/brains.replic/arc202.blueprint.codex.[article].md

@@ -0,0 +1,354 @@
+# blueprint: openai codex
+
+## .what
+
+openai codex is a cloud-based coding agent that runs tasks in isolated sandbox containers, enabling parallel task execution, background processing, and integration with github workflows.
+
+## .why
+
+codex represents a different architectural approach than claude code: cloud-first with network isolation, parallel task model, and deep github integration. comparing these architectures reveals tradeoffs in the replic brain design space.
+
+---
+
+## core agentic loop
+
+### pseudocode
+
+```python
+def run_cloud_task(task_description, repository, environment):
+    # provision isolated cloud container
+    container = provision_sandbox(
+        repository=repository,
+        environment=environment,
+        network_access=False  # disabled by default
+    )
+
+    # clone repository into container
+    container.clone_repo(repository)
+
+    # run setup script if defined
+    if environment.setup_script:
+        container.run(environment.setup_script)
+
+    # agentic loop within sandbox
+    context = initialize_context(task_description)
+
+    while True:
+        response = llm.generate(
+            messages=context,
+            tools=SANDBOX_TOOLS,
+            model="gpt-5-codex"
+        )
+
+        if response.has_tool_calls:
+            for tool_call in response.tool_calls:
+                # execute within sandbox (no external network)
+                result = container.execute(tool_call)
+                context.append(result)
+
+                # run tests after code changes
+                if is_code_change(tool_call):
+                    test_result = container.run_tests()
+                    context.append(test_result)
+        else:
+            # task complete
+            break
+
+    # propose changes
+    return container.create_pr_proposal()
+```
+
+### key characteristics
+
+| aspect | implementation |
+|--------|----------------|
+| execution environment | isolated cloud container |
+| network access | disabled by default (configurable) |
+| loop type | async, runs in background |
+| parallelism | multiple tasks can run simultaneously |
+| termination | agent decides task complete, proposes PR |
+
+### sources
+
+- [Codex Cloud Architecture](https://developers.openai.com/codex/cloud/) — cloud sandbox docs
+- [Codex Security Guide](https://developers.openai.com/codex/security/) — isolation model
+
+---
+
+## context management
+
+### strategy: full context with large windows
+
+unlike claude code's compaction approach, codex leverages large context windows and cloud execution:
+
+```
+┌────────────────────────────────────────┐
+│         CODEX CONTEXT MODEL            │
+├────────────────────────────────────────┤
+│  [task description]                    │
+│  [repository state]                    │
+│  [execution history]                   │
+│  [test results]                        │
+│  [full file contents as needed]        │
+│                                        │
+│  (no explicit compaction — session     │
+│   scoped to single task completion)    │
+└────────────────────────────────────────┘
+```
+
+### context characteristics
+
+| aspect | approach |
+|--------|----------|
+| session length | single task (not open-ended) |
+| history accumulation | full for task duration |
+| compaction | not prominent; tasks are bounded |
+| persistence | task artifacts saved, context ephemeral |
+
+### sources
+
+- [Codex CLI Features](https://developers.openai.com/codex/cli/features/) — context handling
+
+---
+
+## tool interface
+
+### sandbox tools
+
+| category | capabilities |
+|----------|--------------|
+| filesystem | read, write, edit files in workspace |
+| execution | run commands, tests, builds |
+| git | commit, branch, diff |
+| github | create PRs, read issues |
+
+### network isolation
+
+```
+┌────────────────────────────────────────┐
+│           CODEX SANDBOX                │
+├────────────────────────────────────────┤
+│                                        │
+│  [Agent]───[Filesystem]                │
+│      │                                 │
+│      └────[Shell Execution]            │
+│      │                                 │
+│      └────[Git Operations]             │
+│                                        │
+│  ┌─────────────────────────────────┐   │
+│  │     NETWORK: BLOCKED BY DEFAULT │   │
+│  │  (can be enabled by admin)      │   │
+│  └─────────────────────────────────┘   │
+│                                        │
+└────────────────────────────────────────┘
+```
+
+### sandboxing methods
+
+| environment | method |
+|-------------|--------|
+| local (cli) | seatbelt (macos), seccomp+landlock (linux) |
+| cloud | isolated containers |
+
+### sources
+
+- [Codex Security Guide](https://developers.openai.com/codex/security/) — sandboxing details
+- [Codex SDK](https://developers.openai.com/codex/sdk/) — tool interface
+
+---
+
+## parallel task pattern
+
+### multi-task execution
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   USER REQUEST                       │
+│  "Fix auth bug AND add logging to API endpoints"    │
+└──────────────────────┬──────────────────────────────┘
+                       │
+          ┌────────────┴────────────┐
+          │                         │
+    ┌─────▼─────┐            ┌──────▼─────┐
+    │  Task 1   │            │   Task 2   │
+    │ (auth bug)│            │ (logging)  │
+    │           │            │            │
+    │ Container │            │ Container  │
+    │     A     │            │     B      │
+    └─────┬─────┘            └──────┬─────┘
+          │                         │
+          │    [run in parallel]    │
+          │                         │
+    ┌─────▼─────┐            ┌──────▼─────┐
+    │   PR #1   │            │   PR #2    │
+    └───────────┘            └────────────┘
+```
+
+### task lifecycle
+
+1. task created (via chat, github, slack, etc.)
+2. container provisioned with repo
+3. agent executes in background
+4. tests run automatically after changes
+5. PR proposed when complete
+6. user reviews and merges
+
+### sources
+
+- [Codex Cloud Architecture](https://developers.openai.com/codex/cloud/) — parallel execution
+
+---
+
+## reasoning strategy
+
+### test-driven iteration
+
+codex emphasizes running tests as the verification mechanism:
+
+```
+[Write code change]
+        │
+        ↓
+[Run tests automatically]
+        │
+        ├── tests pass → continue
+        │
+        └── tests fail → iterate
+                │
+                ↓
+        [Analyze failure]
+                │
+                ↓
+        [Fix and re-run]
+```
+
+### implicit CoT/ReAct
+
+reasoning is embedded in the agent's approach but not always explicitly visible to users.
+
+---
+
+## github integration
+
+### workflow triggers
+
+| trigger | action |
+|---------|--------|
+| @codex mention | create task from issue/PR |
+| slack command | create task |
+| chat interface | create task |
+| api call | create task |
+
+### pr proposal flow
+
+```
+[Task completes in sandbox]
+         │
+         ↓
+[Generate diff + description]
+         │
+         ↓
+[Propose as draft PR]
+         │
+         ↓
+[User reviews]
+         │
+    ┌────┴────┐
+    │         │
+[merge]  [request changes]
+              │
+              ↓
+         [new task]
+```
+
+### sources
+
+- [Codex Cloud Architecture](https://developers.openai.com/codex/cloud/) — github integration
+
+---
+
+## model
+
+### gpt-5-codex
+
+- purpose-built for codex workloads
+- optimized for code understanding and generation
+- supports tool use
+- available via api key or chatgpt subscription
+
+### sources
+
+- [Introducing Upgrades to Codex](https://openai.com/index/introducing-upgrades-to-codex/) — model details
+
+---
+
+## benchmark performance
+
+| benchmark | notes |
+|-----------|-------|
+| SWE-bench | competitive performance |
+| practical tasks | strong on isolated, test-driven tasks |
+| pr proposals | high quality with context |
+
+---
+
+## architectural summary
+
+```
+┌────────────────────────────────────────────────────────┐
+│                     OPENAI CODEX                       │
+├────────────────────────────────────────────────────────┤
+│  ┌──────────────────────────────────────────────────┐  │
+│  │              TASK QUEUE                          │  │
+│  │  [task 1] [task 2] [task 3] ... (parallel)      │  │
+│  └──────────────────────────────────────────────────┘  │
+│                         │                              │
+│  ┌──────────────────────▼──────────────────────────┐  │
+│  │          CLOUD SANDBOX (per task)               │  │
+│  │  ┌────────────────────────────────────────┐     │  │
+│  │  │  Repository Clone                      │     │  │
+│  │  │  + Environment Setup                   │     │  │
+│  │  │  + Network Isolation                   │     │  │
+│  │  └────────────────────────────────────────┘     │  │
+│  │                    │                             │  │
+│  │  ┌─────────────────▼────────────────────────┐   │  │
+│  │  │          AGENTIC LOOP                    │   │  │
+│  │  │  while not done:                         │   │  │
+│  │  │    response = llm.generate()             │   │  │
+│  │  │    execute_tools()                       │   │  │
+│  │  │    run_tests()  # automatic              │   │  │
+│  │  │    iterate_if_failing()                  │   │  │
+│  │  └──────────────────────────────────────────┘   │  │
+│  └──────────────────────────────────────────────────┘  │
+│                         │                              │
+│  ┌──────────────────────▼──────────────────────────┐  │
+│  │              PR PROPOSAL                         │  │
+│  │  [diff] [description] [test results]            │  │
+│  └──────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## concepts utilized
+
+- [llm](./arc101.concept.llm.[article].md)
+- [context-window](./arc104.concept.context-window.[article].md)
+- [agentic-loop](./arc109.concept.agentic-loop.[article].md)
+- [tool-call](./arc107.concept.tool-call.[article].md)
+- [tool-result](./arc108.concept.tool-result.[article].md)
+- [session](./arc120.concept.session.[article].md) (task-scoped)
+- [react-pattern](./arc111.concept.react-pattern.[article].md) (implicit)
+
+---
+
+## key differences from claude code
+
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| execution | local or sdk | cloud sandbox |
+| network | controlled | blocked by default |
+| parallelism | subagents | multiple tasks |
+| context | compaction | task-bounded |
+| integration | cli + ide | github + slack + api |
+| pr workflow | manual | auto-proposed |

package/dist/roles/architect/briefs/brains.replic/arc300.blueprints.comparison.[catalog].md

@@ -0,0 +1,284 @@
+# blueprints comparison catalog
+
+## .what
+
+a systematic comparison of replic brain architectures across key dimensions: loop architecture, context management, tool interface, subagent patterns, git integration, and performance.
+
+## .why
+
+comparing architectures reveals the design tradeoffs in the replic brain space. understanding why different systems make different choices informs future architecture decisions and helps practitioners select the right tool for their needs.
+
+---
+
+## architectural comparison matrix
+
+| dimension | claude code | codex |
+|-----------|-------------|-------|
+| **execution** | local/sdk | cloud sandbox |
+| **loop type** | single-threaded, synchronous | async, background |
+| **network** | controlled (permissions) | blocked by default |
+| **parallelism** | subagents | multiple tasks |
+| **context** | compaction | task-bounded |
+| **model** | claude-sonnet/opus | gpt-5-codex |
+| **interface** | cli, ide extensions | github, slack, api, ios |
+
+---
+
+## dimension analysis
+
+### 1. loop architecture
+
+#### claude code: single-threaded with subagent delegation
+```
+main loop ────────────────────────►
+     │
+     └──► subagent (isolated context)
+              │
+              └──► returns summary
+```
+
+- synchronous within session
+- user interacts directly with main loop
+- subagents for context isolation and parallel work
+
+#### codex: async task-based with parallel execution
+```
+task queue ────────────────────────►
+     │
+     ├──► task 1 (container A) ──► PR
+     │
+     ├──► task 2 (container B) ──► PR
+     │
+     └──► task 3 (container C) ──► PR
+```
+
+- asynchronous, runs in background
+- multiple tasks execute in parallel
+- each task gets isolated container
+
+#### tradeoff
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| interactivity | high (real-time) | low (async) |
+| parallelism | via subagents | native multi-task |
+| user feedback | immediate | at task completion |
+
+---
+
+### 2. context management
+
+#### claude code: compaction via summarization
+```
+[context fills] ──► [summarize] ──► [continue]
+```
+
+- auto-summarization when approaching 200k limit
+- enables unbounded session length
+- trades verbatim history for longevity
+
+#### codex: task-bounded full context
+```
+[task starts] ──► [full context] ──► [task ends]
+```
+
+- no explicit compaction needed
+- tasks are bounded in scope
+- fresh context per task
+
+#### tradeoff
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| session length | unbounded | task-scoped |
+| history loss | yes (via summarization) | no (per task) |
+| complexity | higher (compaction logic) | lower |
+
+---
+
+### 3. tool interface
+
+#### claude code: builtin + MCP extensibility
+```
+┌─────────────────────────────────────┐
+│  [25+ builtin tools]               │
+│  + [MCP servers for custom tools]  │
+│  + [permission-based access]       │
+└─────────────────────────────────────┘
+```
+
+#### codex: sandbox-restricted tools
+```
+┌─────────────────────────────────────┐
+│  [file, shell, git tools]          │
+│  [network blocked by default]      │
+│  [test execution built-in]         │
+└─────────────────────────────────────┘
+```
+
+#### tradeoff
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| extensibility | high (MCP) | limited |
+| security | permission-based | sandbox isolation |
+| web access | yes (controlled) | blocked (default) |
+
+---
+
+### 4. subagent patterns
+
+#### claude code: typed subagents
+```
+Task(subagent_type="Explore", prompt="...")
+Task(subagent_type="Plan", prompt="...")
+Task(subagent_type="general-purpose", prompt="...")
+```
+
+- explicit types with different capabilities
+- isolated context per subagent
+- can use different/cheaper models
+
+#### codex: parallel task containers
+```
+[Task A: Container 1] ──► PR #1
+[Task B: Container 2] ──► PR #2
+```
+
+- each task is essentially a "subagent"
+- full container isolation
+- natural parallelism
+
+#### tradeoff
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| granularity | fine (subagents within session) | coarse (separate tasks) |
+| model flexibility | per-subagent | per-task |
+| coordination | parent context | independent |
+
+---
+
+### 5. git integration
+
+#### claude code: user-driven commits
+```
+[changes made]
+     │
+     └──► user: "commit this"
+              │
+              └──► git add + git commit
+```
+
+- only commits when explicitly asked
+- guardrails against dangerous operations
+- manual push
+
+#### codex: auto-proposed PRs
+```
+[task completes]
+     │
+     └──► auto-generate PR proposal
+              │
+              └──► user reviews + merges
+```
+
+- automatic PR creation
+- built-in github integration
+- streamlined review workflow
+
+#### tradeoff
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| automation | low (user-driven) | high (auto-PR) |
+| control | high | lower |
+| workflow fit | cli/local dev | github-centric |
+
+---
+
+### 6. performance dimensions
+
+#### benchmark comparison
+
+| benchmark | claude code | codex |
+|-----------|-------------|-------|
+| SWE-bench (verified) | ~49% | competitive |
+| HumanEval | strong | strong |
+| practical tasks | strong (interactive) | strong (batch) |
+
+#### reasoning strategy effectiveness
+
+| strategy | claude code | codex |
+|----------|-------------|-------|
+| react-style | implicit | implicit |
+| extended thinking | yes (configurable) | via model |
+| test-driven | user-initiated | automatic |
+
+#### token efficiency
+
+| aspect | claude code | codex |
+|--------|-------------|-------|
+| context usage | compacted | full per task |
+| model calls | single-threaded | parallel |
+| cost model | per-session | per-task |
+
+---
+
+## shared patterns
+
+despite architectural differences, both systems share:
+
+1. **agentic loop** — generate → tool → observe → repeat
+2. **tool-based interaction** — structured tool calls, not free-form execution
+3. **git awareness** — understand and manipulate repositories
+4. **test integration** — verify changes via tests
+5. **llm-driven reasoning** — model decides actions
+6. **safety constraints** — guardrails on dangerous operations
+
+---
+
+## divergent approaches
+
+| decision point | claude code choice | codex choice |
+|----------------|-------------------|--------------|
+| where to run | user's machine | openai's cloud |
+| how to isolate | permissions + subagents | containers + network block |
+| how to scale | session compaction | bounded tasks |
+| how to integrate | cli + MCP | github + slack + api |
+| when to commit | on user request | auto-propose PR |
+
+---
+
+## insights
+
+### pattern: cloud vs local tradeoff
+- **cloud** (codex): easier deployment, better isolation, async-first
+- **local** (claude code): immediate feedback, user control, privacy
+
+### pattern: compaction vs bounding
+- **compaction**: enables unbounded sessions but loses detail
+- **bounding**: preserves detail but scopes to single tasks
+
+### pattern: permission vs sandbox
+- **permission**: flexible but requires trust decisions
+- **sandbox**: restrictive but eliminates classes of risk
+
+### correlation: architecture → use case
+| architecture | best for |
+|--------------|----------|
+| claude code | interactive development, exploration, refactoring |
+| codex | batch tasks, CI integration, github workflows |
+
+---
+
+## sources
+
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
+- [Codex Cloud Architecture](https://developers.openai.com/codex/cloud/)
+- [AI Coding Agents Benchmark](https://render.com/blog/ai-coding-agents-benchmark)
+- [Claude Code vs Cursor Deep Comparison](https://www.qodo.ai/blog/claude-code-vs-cursor/)
+
+---
+
+## related briefs
+
+- [arc201.blueprint.claude-code.[article].md](./arc201.blueprint.claude-code.[article].md)
+- [arc202.blueprint.codex.[article].md](./arc202.blueprint.codex.[article].md)
+- [arc109.concept.agentic-loop.[article].md](./arc109.concept.agentic-loop.[article].md)
+- [arc117.concept.subagent.[article].md](./arc117.concept.subagent.[article].md)

package/dist/roles/thinker/briefs/term=brain.atomic_vs_replic.md

@@ -0,0 +1,8 @@
+
+- brains come in two fundamental frames
+  - atomic = llm direct invocation
+    - e.g., `atomic:openai:o4`
+    - e.g., `atomic:anthropic:claude-opus-v4.3`
+  - replic = llm behind a repl (read-execute-print-loop)
+    - e.g., `replic:openai:codex`
+    - e.g., `replic:anthropic:claude-code`