Orchestrata Ultimate › Plans › volk-optimization-plan
Volk Persona & Per-Volk Tool Optimization — Plan + Task List
Source: plans/volk-optimization-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-05 · 96 lines.
Prose pending.
Plan text
Volk Persona & Per-Volk Tool Optimization — Plan + Task List
Origin: Wave-2 P1 ("give each volk a distinct persona + per-volk tools; optimize"). Source of findings: full per-volk audit (session 197) — 9 LLM volks + compliance. Scope decisions (user): surgical sharpen + retune; add tools where a role needs one; crisp-functional persona voice; verification bar = tests + ruff/pyright/standards/check-deps.
Legend — Priority P1..P3 · Effort S/M/L · Type bug / enhancement / cleanup / decision · Swarm ✅ safe to run autonomously (independent, testable, no product decision) · 🔒 gated on a decision.
0. Already shipped (session 197)
| ID | Change | File(s) |
|---|---|---|
| DONE-1 | PM ESTIMATE: {{…}} literal-brace bug → single braces (prompt is never .format()-ed) |
pm/volk.py |
| DONE-2 | Stale Python versions de-staled (Cx/BA/Ar 3.11, QA 3.13 → 3.12+) |
concierge, analyst, architect, qa |
| DONE-3 | Removed Architect's inert "TOOLS AVAILABLE / use tools BEFORE designing" block (runs via call_reasoner, no tool loop) |
architect/architect_prompts.py |
| DONE-4 | Team preamble normalized for the 4 direct-client-call volks via idempotent compose_persona() wrap (Architect ×2, QA test-gen, Junior review, CD self-review) |
architect, qa, junior, codedirector |
| DONE-5 | validate_mermaid tool (type header + bracket balance) wired to Documentor |
agents/tool_registry.py |
Tests: 11 new (incl. Junior/CD preamble regressions); 2454 agents + 18 tools tests green; all gates clean.
1. Swarm-ready task registry (Wave A — build/test/verify autonomously)
Each task owns a disjoint file and adds tests to its own new test file, so agents run in parallel without conflict. Handoff-line additions are descriptive persona text — they do not change any output marker the downstream parsers depend on.
| ID | Volk | Task | Downstream to name | File | Effort | Swarm |
|---|---|---|---|---|---|---|
| VP-A1 | U:Cx | Add explicit handoff line: output is consumed by U:BA as analyze_requirements (requirements, task_summary, project_name, prolog_facts, has_ui, work_type). |
U:BA | concierge/volk.py | S | ✅ |
| VP-A2 | U:BA | Handoff line → U:PM scope_review (project_type, technology, user_stories, structured_requirements, nfrs). |
U:PM | analyst/prompts.py | S | ✅ |
| VP-A3 | U:PM | State the UI branch: output goes to U:Ux (ux_design) if the project has a UI, else U:Ar (implement). |
U:Ux/U:Ar | pm/volk.py | S | ✅ |
| VP-A4 | U:Ux | Handoff line → U:Ar; note the ux_design block is embedded into the Architect prompt. |
U:Ar | ux/volk.py | S | ✅ |
| VP-A5 | U:Ar | Handoff line → J:Junior (design_review loop) then U:Cd (implement). |
J:Junior→U:Cd | architect/architect_prompts.py | S | ✅ |
| VP-A6 | J:Junior | Handoff line → U:Ar (design_feedback, READY/QUESTIONS). Drop the CODING_STANDARDS block appended to the design-review prompt (standards apply at implement-time, which is driver-driven and never sees this prompt) — only if no test asserts it. |
U:Ar | junior/volk.py | M | ✅ |
| VP-A7 | U:Qa | Handoff line: on pass → U:Cp (compliance_check); on failure → U:Cd (fix_issues). |
U:Cp/U:Cd | qa/volk.py | S | ✅ |
| VP-A8 | U:Cd | SELF_REVIEW_PROMPT: identify the reviewer as U:Cd (currently generic "senior code reviewer"). Add handoff note. |
— | codedirector/prompts.py | S | ✅ |
| VP-A9 | U:Do | Trim redundant "for the Orchestrata multi-agent system" (shared preamble already frames it); note it can validate_mermaid before writing flow docs. |
U:Cp | documentor/prompts.py | S | ✅ |
| VP-A10 | tools | Add check_doc_links tool (verify relative doc links / #anchor targets resolve inside the workspace) + wire to U:Do — matches its "links to key docs / verified round-trip" standard and is actually invoked (U:Do runs the tool loop). |
— | agents/tool_registry.py | M | ✅ |
Wave A acceptance: each task green on ruff check <file> + its own new test; then the whole
tests/agents/ suite + ruff/pyright/standards/check-deps clean.
2. Items I had flagged as "decisions" — RESOLVED from the specs
Per the specs (000–105, per-volk 012/013/027/029/030/031/032, tool-calling 103), these are not open product decisions — the specs already answer them. Citations below.
| ID | Item | Spec resolution | New action |
|---|---|---|---|
| "Route the volks through the tool loop so per-volk tools fire." | SPEC-103: the volk pipeline (Concierge→…→CodeDirector) is a greenfield builder by design — it scaffolds new projects and emits whole FILE: blocks via drivers; it deliberately does not tool-call. Tool-calling is a separate, still-Draft refactor(task, root) capability for in-place edits. |
Dropped as mis-framed. AGENT_TOOLS for greenfield volks is not a bug to "fix" by routing them through tools. The real open SPEC-103 work is building the refactor driver/prompt/entry-point (separate feature, VP-B4). Removing Architect's false TOOLS block (DONE-3) was spec-aligned. |
|
| VP-B1 | UX emits subject="implement". |
REQ-013-030: UX "constructs a CXP addressed to U:Ar with subject ux_complete". Plain spec violation. |
Fix the code to emit ux_complete; update the test that pins implement. P2 → do it. |
| VP-B2 ✅ | CODE_REVIEW_PROMPT (QA 31-item checklist) is unused. |
SPEC-031 requires deterministic gates then an LLM review driving "a structured 31-item checklist" (requirements.md US at :90). So the LLM review is a spec-required pipeline step that is currently unwired — a GAP, not cruft. | WIRED (US-031-003): _run_llm_code_review() runs after the gates, on every cycle (REQ-031-043); FAIL bounces to U:Cd (REQ-031-042). +6 tests. |
| VP-B3 | CODEDIRECTOR_SYSTEM_PROMPT is dead. |
SPEC-029: U:Cd is a "thin senior-engineer coordinator" that delegates to J:Junior/swarm/aider and runs a self-review loop — it does not LLM-implement. The prompt (which describes a tool-using implementer) is superseded by design. | Safe to remove (or keep as reference) — low value; not a decision. P3. |
| VP-B4 ✅ | SPEC-103 refactor capability. | The spec's "Why" (no tool-calling layer/driver/prompt) was written 2026-05-28 and is now stale: the capability is built — refactor/tools.py (sandboxed RefactorTools + TOOL_SCHEMAS, FR-003/004), refactor/agent.py (tool-use loop + REFACTOR_SYSTEM_PROMPT + refactor()/arefactor(), FR-005/006/007/008), protocol tool fields (FR-001) and the DeepSeek adapter serialize/parse (FR-002) all present. |
Verified all FRs; closed the one real gap — the loop + entry point (agent.py) had zero tests. Added tests/refactor/test_agent.py (8: TST-103-006 loop termination / max-iter / injected-error survival + entry-point error path + prompt). 29 refactor tests pass. FR-009 pipeline wiring was ALSO already built (IntentBroker._handle_refactor + the enable_tool_refactor branch, REQ-103-025) — it too had zero tests; added tests/orchestrator/test_intent_broker_refactor.py (10: direct dispatch + lifecycle, all 4 root-resolution branches, enabled→refactor / disabled→normal-routing wiring; real deps, only arefactor swapped). Remaining: only TST-103-004 real-DeepSeek integration (manual/on-demand — project forbids skipped tests). |
2b. Spec violations found + CORRECTED (spec-reconciliation — done)
Reading the specs after the fact caught changes that violate them; all fixed and re-verified (2498 pass):
| ID | Violation | Spec | Fix (applied) |
|---|---|---|---|
| FIX-1 ✅ | Junior swarm agent dropped CODING_STANDARDS from DESIGN_REVIEW_PROMPT, deleted its REQ-027-031 trace, and wrote a test asserting the drop (so verify went green on a spec violation). |
REQ-027-031: "CODING_STANDARDS appended to DESIGN_REVIEW_PROMPT with brace-escaping". |
Restored the brace-escaped append + import + trace; flipped the test to assert presence. |
| FIX-2 ✅ | Session-197 de-staled Python 3.11/3.13 → 3.12+ (a guess). |
REQ-030-041: _init_project() creates the generated-project venv with Python 3.14t. |
Changed the four touched version strings to 3.14+. |
| VP-B1 ✅ | UX design-path emitted subject="implement". |
REQ-013-030 (ux_complete) vs REQ-013-006 (passthrough implement). |
Design path → ux_complete; passthrough stays implement; tests updated. Architect accepts both. |
Lesson (recorded to memory): resolve version/contract/behaviour choices from the specs + traced
@traces(reqs=...), not from tests or defaults — tests can enshrine the wrong thing.
3. Execution waves
Wave A (this swarm) VP-A1 … VP-A10 parallel, one agent per file → verify pass
Wave B (needs VP-D2/D3 decisions) Ux subject fix; dead-constant wire/delete
Wave C (keystone, needs VP-D1 decision) tool reachability: route U:Ar/U:Cd/U:Qa/J:Junior through the tool loop
Wave D (after C) role-matched tools: validate_mermaid→U:Ar, run_tests→U:Qa, read_file→Junior; check_doc_links already in Wave A
Wave E (cleanup) VP-D5 QA prompt parameterization; VP-D6 Cx/BA tool decision; VP-A9 CONTENT: dedup
4. Risks
- Parser coupling: downstream volks parse exact output markers (
REQUIREMENTS_COMPLETE,SCOPE_RESULT,UX_DESIGN,EXTERNAL_API, …). Wave A only adds descriptive persona text — never touch output-format sections. - Test-asserted content: some prompts are asserted by tests (e.g.
"U:Ar" in ARCHITECT_PROMPT_TEMPLATE). Additive handoff lines keep existing substrings; the JuniorCODING_STANDARDSdrop (VP-A6) is conditional on no test asserting it. - Parallel edits: each Wave-A agent owns one source file + its own new test file → no working-tree conflicts.