Purpose
Create a fresh implementation issue for orchestrator prompt loading, independent from the tangled history and misleading done-state churn around #183.
This new issue should be the clean source of truth for how the feature is supposed to work.
Background
The earlier #183 lane became hard to trust because:
- implementation history became tangled across repeated redesigns
- workflow state repeatedly drifted into false done/refining states
- review/test comments from older lanes kept re-closing or over-validating the wrong shape
- release/promotion work became mixed up with implementation cleanup
So this issue is for a clean reimplementation, not another patch on top of that history.
Reset baseline
Use commit 562d2fdb8207b53df71edd063f3df510a56f9fb8 as the conceptual rollback baseline for the feature design.
The goal is to rebuild the intended behavior cleanly from there.
Required implementation model
The orchestrator prompt loader should behave like the worker prompt loaders in one key respect:
Winner-takes-all fallback
Resolve one orchestrator prompt source by fallback order, and inject only that resolved source.
Required resolution order:
devclaw/projects/<project>/prompts/orchestrator.mddevclaw/prompts/orchestrator.md- package default orchestrator prompt, if present
No layering / no merge behavior
Do not merge or append multiple orchestrator prompt sources together.
Do not layer workspace + project orchestrator prompts.
One source wins.
Bootstrap shape
AGENTS.md remains the baseline bootstrap context- after that, inject the resolved orchestrator prompt as
orchestrator.md
- do not use a synthetic wrapper name like
DEVCLAW_ORCHESTRATOR_PROMPT.md
Correct session targeting
The orchestrator prompt injection path must apply only to the real orchestrator/main session shape.
It must not treat every non-worker or unknown session as an orchestrator session.
A prior reviewer concern on #183 correctly flagged that overly broad if (!parsed) logic was too permissive.
That must be avoided in this clean implementation.
Acceptance requirements
Code/test requirements
- targeted unit/bootstrap/E2E coverage for the winner-takes-all resolution order
- explicit regression coverage proving non-orchestrator / unknown sessions do not get
orchestrator.md
- coverage for project-specific override, workspace fallback, and package-default fallback
- coverage for topic-aware/chat-aware project resolution where applicable
Live semantic requirements
Filename presence alone is not enough.
A passing implementation must prove that the resolved prompt content is actually available in session context memory in a real session.
The key acceptance rule is semantic/live behavior:
- the agent must actually answer based on the resolved orchestrator prompt content
- not merely show
orchestrator.md in the startup file list
Important known trap
A prior failure mode showed that generic orchestrator.md presence could still coexist with the wrong prompt source being loaded.
This clean reimplementation must avoid that trap.
Nice-to-have
If the implementation can be kept smaller and simpler than the prior #183 lane, prefer the smaller simpler version.
The operator preference here is clarity and clean behavior over cleverness.
Related issues
#183 old tangled implementation lane#186 promotion tracker that should stay paused until this clean implementation is truly validated#188 runbook/orchestrator-ownership follow-up
Purpose
Create a fresh implementation issue for orchestrator prompt loading, independent from the tangled history and misleading done-state churn around
#183.This new issue should be the clean source of truth for how the feature is supposed to work.
Background
The earlier
#183lane became hard to trust because:So this issue is for a clean reimplementation, not another patch on top of that history.
Reset baseline
Use commit
562d2fdb8207b53df71edd063f3df510a56f9fb8as the conceptual rollback baseline for the feature design.The goal is to rebuild the intended behavior cleanly from there.
Required implementation model
The orchestrator prompt loader should behave like the worker prompt loaders in one key respect:
Winner-takes-all fallback
Resolve one orchestrator prompt source by fallback order, and inject only that resolved source.
Required resolution order:
devclaw/projects/<project>/prompts/orchestrator.mddevclaw/prompts/orchestrator.mdNo layering / no merge behavior
Do not merge or append multiple orchestrator prompt sources together.
Do not layer workspace + project orchestrator prompts.
One source wins.
Bootstrap shape
AGENTS.mdremains the baseline bootstrap contextorchestrator.mdDEVCLAW_ORCHESTRATOR_PROMPT.mdCorrect session targeting
The orchestrator prompt injection path must apply only to the real orchestrator/main session shape.
It must not treat every non-worker or unknown session as an orchestrator session.
A prior reviewer concern on
#183correctly flagged that overly broadif (!parsed)logic was too permissive.That must be avoided in this clean implementation.
Acceptance requirements
Code/test requirements
orchestrator.mdLive semantic requirements
Filename presence alone is not enough.
A passing implementation must prove that the resolved prompt content is actually available in session context memory in a real session.
The key acceptance rule is semantic/live behavior:
orchestrator.mdin the startup file listImportant known trap
A prior failure mode showed that generic
orchestrator.mdpresence could still coexist with the wrong prompt source being loaded.This clean reimplementation must avoid that trap.
Nice-to-have
If the implementation can be kept smaller and simpler than the prior
#183lane, prefer the smaller simpler version.The operator preference here is clarity and clean behavior over cleverness.
Related issues
#183old tangled implementation lane#186promotion tracker that should stay paused until this clean implementation is truly validated#188runbook/orchestrator-ownership follow-up