docs/agent_team/README.md

# Stock Predictor Agent Team

Date: 2026-05-22

This directory defines the reusable agent team for Stock Predictor research,
implementation, and validation.  The team is designed for accuracy experiments,
factor mining, hotspot analysis, automation maintenance, and production-safe
integration.

## Layered Map

```text
docs/agent_team/
  README.md          # entry point and team map
  memory.md          # durable process decisions
  md_inventory.md    # role files and related architecture index
  skill_handoff.md   # skill selection and task routing
  rules.md           # authority and production-safety rules
  harness.md         # verification and promotion contract
  agent_*.md         # individual role definitions
```

## Team Map

| Agent | File | Primary Job |
| --- | --- | --- |
| Coordinator | `agent_01_coordinator.md` | Own task decomposition, scope, handoffs, and final decision routing. |
| Survey A | `agent_02_survey_literature.md` | Search papers, docs, public methods, and implementation references. |
| Survey B | `agent_03_survey_skills_data.md` | Search repo skills, data sources, existing harnesses, and integration constraints. |
| Implement A | `agent_04_implementation_factor.md` | Convert survey ideas into experimental factors or scripts. |
| Implement B | `agent_05_implementation_pair_validator.md` | Pair-review implementation, run local smoke, and check production boundaries. |
| QA A | `agent_06_qa_test_designer.md` | Design unit, integration, and correctness tests. |
| QA B | `agent_07_qa_history_validator.md` | Run no-lookahead historical validation and summarize metric deltas. |
| Optional Guardian | `agent_08_promotion_memory_guardian.md` | Gate promotion and update memory/rules only after evidence is accepted. |

## Default Flow

```text
Coordinator
  -> Survey A + Survey B in parallel
  -> Implement A + Implement B as pair programming
  -> QA A + QA B as pair validation
  -> Optional Guardian for promotion/memory update
  -> Coordinator final recommendation
```

## Core Rules

- No production prediction, recommendation, precompute, or HF publishing change
  can be promoted from a survey alone.
- Every factor or model change starts as a dry-run experiment.
- Historical validation must be no-lookahead and same-window against baseline.
- BUY precision must not be sacrificed unless the user explicitly changes the
  metric priority.
- Survey agents may cite methods; implementation agents must map them to local
  files and commands.
- QA agents have veto power when tests, data quality, signal count, or
  no-lookahead assumptions fail.

## Output Contract

Every run should end with:

```text
Decision: integrate / keep experimental / reject / needs more data
Changed files:
Validation commands:
Metrics:
Risks:
Next candidate:
```

## Related Canonical Docs

- `docs/knowledge_architecture.md`
- `docs/hermes/README.md`
- `docs/hermes/rules.md`
- `docs/hermes/harness.md`
- `docs/closed_loop_validation_design.md`
- `docs/self_refine_agent_architecture.md`
- `docs/factor_weight_optimization_harness.md`
- `docs/hotspot/README.md`