5 Red tests in tests/test_ai_client_tool_loop.py verify the planned
run_with_tool_loop contract (no-tool-call fast path, tool-call
dispatch, max-rounds safety, history append, error tolerance).
Deviation from plan: tests patch src.ai_client.send_openai_compatible
(plan's Task 1.1 had src.tool_loop.send_openai_compatible). The plan
predates the AGENTS.md HARD RULE on src/<thing>.py files; per the
follow-up track's Naming Convention section, run_with_tool_loop lives
IN src/ai_client.py. The function body imports send_openai_compatible
from src.openai_compatible, so src.ai_client.send_openai_compatible
is the correct patch path.
state.toml: current_phase 0 -> 1, phase_1 pending -> in_progress,
t1_1 pending -> in_progress, blocked_by status
phase_6_in_progress -> phase_6_complete (parent's Phase 6
checkpointed at 064cb26).
Confirmed red: 5 ImportError against src.ai_client.run_with_tool_loop
at collection time.
The user explicitly stated 2026-06-11: 'I need a naming convention
enforce for separate files you keep introducing that are technically
part of a system or parent module.' Per AGENTS.md 'File Size and
Naming Convention' HARD RULE: new src/<thing>.py files may only be
created on the user's explicit request. All AI-client code lives
IN src/ai_client.py.
Sweep through all follow-up track files to remove the stale
references to the no-longer-planned new src/ files:
- TODO.md: t1.4 'Implement helper in src/tool_loop.py' -> '...in
src/ai_client.py'
- plan.md: 5 stale references updated (Task 4.3 title, Step 1
'Files:', Step 5 'git add', Phase 4 git note, the function
summary in Phase 1 verification)
- plan.md: 'src/llama_ollama_native.py' removed (ollama_chat and
_send_llama_native both in src/ai_client.py)
- spec.md: Phase Plan section T1.2 and T4.2/T4.3 updated to
reference src/ai_client.py
- state.toml: t1.4, t4_2, t4_3 descriptions updated
- metadata.json: new_files list shrunk (3 new src/ files removed);
verification_criteria updated to reference src/ai_client.py
functions; follow_up_audit_report reference updated to point to
the actual file (docs/reports/qwen_llama_grok_followup_audit_20260611.md)
Spec additions from the same turn (not in the previous plan version):
- Naming Convention section explicitly references AGENTS.md HARD
RULE; 'If you find yourself about to create one, ASK FIRST'
- 'Non-Goals' section now lists 8 explicit non-goals (vs the
previous 4) including history management lift, reasoning
extraction lift, error classification lift
- 'Deferred Work' section documents 3 separate follow-up tracks
(namespace_cleanup_20260611, ai_client_codepath_consolidation_20260611,
mcp_architecture_refactor_20260606 [already specced])
- 'Open Questions' has 1 RESOLVED (PROVIDERS location) and 2 still
open (Meta URL verification; local model UI mode)
- 'Goals' table: 'local-backend' field added separately from
'cost_tracking' (per user feedback: distinct concept)
- 'B.1 Local-First' section: native Ollama DEFAULT for localhost
(not fallback), Meta Llama API prerequisite (verify URL first)
- 'B.2 Matrix Expansion' section: full list of 12 v2 fields + UI
adaptations for each
This is docs-only. The plan is now complete and aligned with the
HARD RULE. The next agent can pick up at Phase 1, Task 1.1 and
execute straight through.
The user called out the LLM training data bias: 'small files are
good, large files are bad.' This is wrong for production codebases.
Unreal has 15K+ line files; OS kernels, game engines, compilers all
routinely have 10K+ line files. File size is a non-issue. Cognitive
load is managed via naming, regions, and navigation tools (the
manual-slop MCP) — NOT via file splitting.
Updates:
1. AGENTS.md (master agent guidance):
- Added 'File Size and Naming Convention' section
- Added the hard rule: 'New namespaced src/<thing>.py files may
only be created on the user's explicit request. If you find
yourself about to create one, ASK FIRST.'
- Defaults: helpers and sub-systems go in the parent module
2. conductor/workflow.md (Guiding Principles):
- Removed 'Do NOT perform large file writes directamente' from
principle 7 (it was a delegating rule, but 'large file writes'
carried the propaganda)
- Added principle 8: 'File Naming Convention (HARD RULE)' that
references AGENTS.md
- Re-phrased principle 9 (Research-First) to clarify it's about
navigation efficiency, not file size
3. conductor/code_styleguides/python.md:
- Removed the 'extremely large files that violate the Anti-OOP
rule by necessity' framing
- Added the new rule about new src/<thing>.py files
4. .opencode/agents/tier3-worker.md and .opencode/agents/tier4-qa.md:
- Re-phrased 'Do NOT read full large files' to 'Use skeleton
tools to navigate any file regardless of size. File size is
not a concern; the right tools are.'
- Added the new rule about not creating new src/<thing>.py
files unless user explicitly requests it
5. conductor/tracks/qwen_llama_grok_followup_20260611/plan.md:
- Updated the 'Naming Convention' section to reference the new
'user explicit request' rule
This is docs-only. No code changes. The rule is now codified:
agents must ASK FIRST before creating new top-level src/ files.
The follow-up track had a spec but no plan. The plan is the executable
artifact — it specifies file:line refs, exact code to type, TDD steps,
and per-file atomic commits. Without the plan, the next agent cannot
implement from the spec alone.
Plan structure (5 phases, ~40 tasks):
- Phase 1: Tool loop lift (5 Red tests + helper + apply to 8 vendors +
audit script)
- Phase 2: PROVIDERS move (decide location + move + update 4 import
sites + audit script)
- Phase 3: UX adaptations 2-9 (8 separate applications of the pattern
established in parent Phase 5)
- Phase 4: Local-first + matrix v2 (12 new fields + native Ollama
adapter + Meta Llama API + Local Model GUI badge)
- Phase 5: Anthropic / Gemini / DeepSeek migration (matrix entries
for the 3 remaining providers + docs update)
Each task has:
- WHERE: exact file and (where applicable) line range
- WHAT: the specific change
- HOW: TDD step ordering (Red then Green)
- SAFETY: thread-safety, dependency-ordering, and project-invariant
constraints
The plan models the parent track's plan structure (2177 lines,
2-5 minute steps, per-file atomic commits).
Phase 6 t6.1 + t6.2 (no archive per user directive):
- docs/guide_ai_client.md: update Overview to mention 8 providers (was 5);
add 'Shared OpenAI-Compatible Helper' section explaining
src/openai_compatible.py (NormalizedResponse, OpenAICompatibleRequest,
send_openai_compatible, usage pattern); document the Qwen adapter
and Llama multi-backend.
- docs/guide_models.md: update PROVIDERS list to 8 entries (was 5).
- conductor/tracks.md: update the Qwen track entry to reflect
'50/79 tasks done; Phase 6 in progress; NOT archiving - has follow-up';
add detailed status note pointing to the follow-up track + audit
report.
- docs/reports/qwen_llama_grok_followup_audit_20260611.md: NEW report
explaining why a follow-up is needed (7 categories of gaps; the
Tech Lead's 'footnote for now' failure mode; the lessons learned).
- conductor/tracks/qwen_llama_grok_followup_20260611/: NEW follow-up
track setup (spec.md, state.toml, metadata.json, TODO.md).
5 phases: tool loop lift, PROVIDERS move, UX adaptations 2-9,
local-first + matrix v2, Anthropic/Gemini/DeepSeek migration.
Phase 6 t6.3 (git mv to archive) and t6.4 (mark Recently Completed)
are NOT applied per user directive: 'we can then doc this we're not
archiving yet, if we have a follow up track I need this one to stay
up because there is still alot todo'.
ed