Skip to content

Simplify builtin pieces: remove redundant section maps and unify instruction_template resolution #152

@nrslib

Description

@nrslib

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:

  1. Section map lookup
  2. Path resolution (./, ../, /, ~, .md)
  3. 3-layer facet resolution (bare name)
  4. 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

  • Update instruction_template resolution in pieceParser.ts
  • Remove section maps from all builtin piece YAMLs (en + ja)
  • Update tests
  • Update CLAUDE.md / docs if needed

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions