Summary
3-layer facet resolution (project → user → builtin) makes piece-level section maps (personas:, policies:, knowledge:, instructions:, report_formats:) redundant for builtin facets. All builtin facets can be referenced by bare name.
Changes
1. Unify instruction_template resolution
Currently instruction_template only supports path or inline string (resolveResourceContent). Change it to use resolveRefToContent (same as instruction, policy, knowledge) so it goes through:
- Section map lookup
- Path resolution (
./, ../, /, ~, .md)
- 3-layer facet resolution (bare name)
- Fallback (inline string)
Code change in pieceParser.ts:192:
// Before
instructionTemplate: resolveResourceContent(step.instruction_template, pieceDir) || expandedInstruction || '{task}',
// After
instructionTemplate: (step.instruction_template
? resolveRefToContent(step.instruction_template, sections.resolvedInstructions, pieceDir, 'instructions', context)
: undefined) || expandedInstruction || '{task}',
Inline multi-line templates are unaffected (they fall through all lookups and are returned as-is).
Note: Bare single-word instruction_template values (e.g., instruction_template: implement) that were previously treated as literal strings would now resolve to instruction facet files if they exist. This is technically breaking but unlikely to affect any real usage.
2. Remove section maps from builtin pieces
With all fields supporting 3-layer resolution, builtin pieces can drop their section maps:
# Before
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
knowledge:
architecture: ../knowledge/architecture.md
instructions:
plan: ../instructions/plan.md
movements:
- name: plan
persona: planner
knowledge: architecture
instruction: plan
# After — section maps removed
movements:
- name: plan
persona: planner # → builtins/{lang}/personas/planner.md
knowledge: architecture # → builtins/{lang}/knowledge/architecture.md
instruction: plan # → builtins/{lang}/instructions/plan.md
Section maps remain useful only for custom mappings (name ≠ file path).
Scope
Summary
3-layer facet resolution (
project → user → builtin) makes piece-level section maps (personas:,policies:,knowledge:,instructions:,report_formats:) redundant for builtin facets. All builtin facets can be referenced by bare name.Changes
1. Unify
instruction_templateresolutionCurrently
instruction_templateonly supports path or inline string (resolveResourceContent). Change it to useresolveRefToContent(same asinstruction,policy,knowledge) so it goes through:./,../,/,~,.md)Code change in
pieceParser.ts:192:Inline multi-line templates are unaffected (they fall through all lookups and are returned as-is).
Note: Bare single-word
instruction_templatevalues (e.g.,instruction_template: implement) that were previously treated as literal strings would now resolve to instruction facet files if they exist. This is technically breaking but unlikely to affect any real usage.2. Remove section maps from builtin pieces
With all fields supporting 3-layer resolution, builtin pieces can drop their section maps:
Section maps remain useful only for custom mappings (name ≠ file path).
Scope
instruction_templateresolution inpieceParser.ts