Dual Execution Paths

The same committee logic, two independent implementations: The Coordinator path lets the user's Claude act as the coordinator to truly spawn 4 subagents, while the Direct path uses DeepSeek + ThreadPool for in-process multi-threading. Results may differ—this is a feature.

← 03-dreaming · Wiki Index · 05-data-model →

2026-05 Rename: Old documents called it "Skill path" vs "Web/Cron path". But skills now support both paths (prepare_committee + spawn subagent goes via Coordinator; run_committee goes via Direct, usable by any non-Claude agent), so it's uniformly renamed to Coordinator vs Direct. Direct includes the original cron path + Web GUI triggered version + the run_committee subcommand within skills.

TL;DR

Path	Who Can Use	Trigger	Coordinator	Worker Implementation	Model	Real Subagent?	Cost
Coordinator	Claude Code only (requires `Agent({...})` tool)	skill `prepare_committee SYM`	User's Claude	`Agent({subagent_type})` truly spawns 4 subagents (subprocess isolation)	Claude 4	✅	Covered by user subscription (project ¥0)
Direct	Any agent (Cursor / Cline / Codex / regular scripts) + cron	skill `run_committee SYM` / `POST /api/committee/run` / cron `daily_report`	`core/committee/`	4 `SDKAgent` + `ThreadPoolExecutor` in-process multi-threading	DeepSeek-Chat	❌ (Information separated but not subprocess)	¥0.01-0.03 per run

Functionally equivalent: Same prompts, same cross-challenge protocol, same regime classification + neutral probability metrics. Different models: Verdicts may differ—this is a comparative validation mechanism, not a bug.

1. Coordinator Path (Claude Code Only)

Trigger

bash

~/.claude/skills/invest/scripts/run.sh prepare_committee NDQ.AX

Or, in a Claude Code conversation, say: "Run committee analysis for NDQ"—Claude will automatically invoke the skill.

Implementation

skills/invest/scripts/run.sh prepare_committee does the following:

Fetches NDQ.AX market data + calculates REGIME
Writes the system prompts and input data for the 4 roles to /tmp/.committee/<task_id>/{macro,quant,risk,cio}.md
Outputs an instruction for the user's Claude, telling it to spawn 4 subagents to run

After seeing the instruction, the user's Claude executes:

Agent({
  subagent_type: "general-purpose",
  description: "Macro analysis for NDQ.AX",
  prompt: <macro role system prompt + input>
})
Agent({...})  // quant
Agent({...})  // risk

// After the three subagents complete
Agent({...})  // cio synthesizes transcript

True Isolation: Each Agent() is a subprocess with its own independent context window. Claude 4 acts as the worker, offering high capability.

Advantages

✅ Zero API cost for the project itself (user is already subscribed to Claude; running it 100 times costs ¥0)
✅ Claude model is powerful, verdict quality is typically high
✅ True subagent isolation = True Agent Teams (subprocess, not in-process token binding)

Limitations

❌ Must be run within Claude Code; cannot be a background cron job
❌ User must be present to trigger it
❌ No SSE live streaming; results are output all at once
❌ Skill state is not persisted to invest memory after completion (unless the user manually forwards it)

See skills/invest/SKILL.md for details.

2. Direct Path (Any Agent / Cron / Web GUI)

All three entry points use the same core/committee/debate.py:run_committee:

Entry Point	Who Uses It	Notes
`~/.claude/skills/invest/scripts/run.sh run_committee SYM`	Cursor / Cline / Codex / regular scripts / local DeepSeek / any agent	Single command to get verdict JSON + CIO memo
`POST /api/committee/run`	Web GUI "Trigger/Live" button	Asynchronous + SSE progress push
cron `0 3 * * *` runs `jobs/daily_report.py`	Server auto-daily	Runs all target_assets, optionally sends email

Trigger

Manual: POST /api/committee/run (Web GUI "Trigger/Live" button) Automatic: cron 0 3 * * * runs jobs/daily_report.py

Implementation

core/committee/debate.py:run_committee runs within the same process:

python

# Round 1: Quant + Risk in parallel
with ThreadPoolExecutor(max_workers=2) as ex:
    quant_future = ex.submit(_ask, quant_agent, quant_prompt)
    risk_future = ex.submit(_ask, risk_agent, risk_prompt)
    quant_r1 = quant_future.result()
    risk_r1 = risk_future.result()

# Round 2..N: cross-challenge with convergence detection
for round_idx in range(2, max_debate_rounds + 1):
    quant_rN, risk_rN = _parallel_ask([
        (quant_agent, quant_prompt_rN),
        (risk_agent, risk_prompt_rN),
    ])
    if _check_convergence(...):
        break

# CIO serial
cio_memo = _ask(cio_agent, cio_prompt_with_full_transcript)

Each _ask calls the DeepSeek-Chat HTTP API once. Concurrent multi-threading within the same process.

Information isolation via convention: Each agent receives its own prompt string; no shared variables. However, physically it's the same process and GIL, not a subprocess.

Advantages

✅ Background cron auto-runs (daily at 03:00 for daily_report)
✅ Web GUI SSE real-time streaming of stage progress
✅ True parallelism for multiple assets (ThreadPoolExecutor wrapping multiple run_committee_for_symbol)
✅ State persistence (.committee/<task_id>/status.json + daily/<date>/<sym>.md)
✅ DeepSeek-Chat fast response (2-3s/request vs Claude 5-10s/request), overall convergence ~16s

Limitations

❌ DeepSeek model capability < Claude 4, verdict quality slightly lower for complex scenarios
❌ User pays DeepSeek costs (though cheap, ¥0.01-0.03 per run)
❌ In-process, not a true subagent (information isolation is correct, but Claude proponents will nitpick from a marketing perspective)

3. Why Not Merge

Having two paths coexist is a feature, not debt. Reasons:

3.1 Different Cost Structures

Scenario	Skill Suitable	Web/Cron Suitable
User actively asks "Should I add to position?"	✅ (Claude for personal use, ¥0 cost)	❌ (¥0.03 each time)
Cron auto-run daily at 03:00	❌ (User not in Claude Code)	✅ (DeepSeek monthly cost controllable)
Scan multiple assets in parallel	❌ (User's Claude not good at long batch processing)	✅ (ThreadPool completes in 16s)

3.2 Validation Mechanism

Two verdicts for the same question—validates model bias. For example, if Skill outputs BUY and Web outputs HOLD, it indicates the judgment doesn't converge across models, warranting manual review. Merging into a single path → losing this comparative signal.

3.3 Disaster Recovery

DeepSeek rate-limited / price hike / shutdown? The Coordinator path is unaffected; users can continue as usual. Claude API unstable? The Direct path is unaffected; automation continues to run.

4. Implementation Layers (Which Code is Shared Between Paths)

┌────────────────────────────────────────────────────────────────┐
│  agents/{macro,quant,risk,cio}.py prompts                     │ ← Shared
├────────────────────────────────────────────────────────────────┤
│  core/regime.py REGIME classification + probability metrics    │ ← Shared
├────────────────────────────────────────────────────────────────┤
│  core/committee/debate.py run_committee orchestration logic    │ ← Direct only
│  skills/invest/scripts/run.sh prepare_committee prompt gen     │ ← Coordinator only
│  skills/invest/scripts/run.sh run_committee (wraps run_committee)│ ← Direct entry in skill
├────────────────────────────────────────────────────────────────┤
│  agents/sdk_agent.py SDKAgent (DeepSeek HTTP)                  │ ← Direct only
│  Claude Agent({...}) tool                                      │ ← Coordinator only
└────────────────────────────────────────────────────────────────┘

~70% shared (prompts + REGIME + sanity check + data preparation). ~30% divergence (orchestrator + LLM client).

Adding a new role (e.g., ESG analyst) requires registration on both sides—this is the cost of consistency.

5. Upgrade to Claude Agent SDK?

Investigated (2026-05): Could use anthropics/claude-agent-sdk-python to let the Direct path also use Claude's true subagents.

Issues:

Strongly tied to Claude model (cannot use DeepSeek); daily cron cost would be 30-100× higher
The SDK is a subprocess wrapper for the Claude Code CLI, requiring the server to have the claude CLI binary installed
Single committee run ¥0.5-2; daily cron = hundreds of yuan per month

Conclusion: No upgrade for now. See adr/002-no-claude-agent-sdk.md for details.

6. Decision Tree: Which Path Should You Use

Are you in Claude Code and want to ask "Should I buy?"
  → Coordinator path (let your Claude spawn 4 subagents, no DeepSeek token burn)

Are you in Cursor / Cline / Codex / another non-Claude agent?
  → Direct path (skill `run_committee SYM` for one-click verdict, requires DEEPSEEK_API_KEY)

Are you in the Web GUI wanting to click a button to trigger + see real-time progress?
  → Direct path (POST /api/committee/run, includes SSE)

Do you want to auto-run daily at 03:00 (unattended)?
  → Direct path cron (jobs/daily_report.py)

Do you want to compare verdicts from two models on the same question for consistency?
  → Run both paths

Next Steps

→ adr/001-dual-execution-paths.md — Why this decision is not tech debt

→ adr/002-no-claude-agent-sdk.md — Specific reasons for not upgrading to the Claude Agent SDK

→ 02-agents.md — What the 4 role prompts look like in both paths

Dual Execution Paths ​

TL;DR ​

1. Coordinator Path (Claude Code Only) ​

Trigger ​

Implementation ​

Advantages ​

Limitations ​

2. Direct Path (Any Agent / Cron / Web GUI) ​

Trigger ​

Implementation ​

Advantages ​

Limitations ​

3. Why Not Merge ​

3.1 Different Cost Structures ​

3.2 Validation Mechanism ​

3.3 Disaster Recovery ​

4. Implementation Layers (Which Code is Shared Between Paths) ​

5. Upgrade to Claude Agent SDK? ​

6. Decision Tree: Which Path Should You Use ​

Next Steps ​

Dual Execution Paths

TL;DR

1. Coordinator Path (Claude Code Only)

Trigger

Implementation

Advantages

Limitations

2. Direct Path (Any Agent / Cron / Web GUI)

Trigger

Implementation

Advantages

Limitations

3. Why Not Merge

3.1 Different Cost Structures

3.2 Validation Mechanism

3.3 Disaster Recovery

4. Implementation Layers (Which Code is Shared Between Paths)

5. Upgrade to Claude Agent SDK?

6. Decision Tree: Which Path Should You Use

Next Steps