Customizing Spawn Prompts

wu:brief ships with a host-neutral prompt composition. Projects can add or override domain guidance under .lumenflow/templates/ without creating a second agent contract.

Generated guidance respects configured lane WIP limits and invokes only mandatory agents resolved from project configuration. Exploration delegation is optional when the active host supports it. The brief names the canonical managed skills catalog separately from any project-owned host adapter discovery path; the adapter path does not replace the canonical catalog.

The built-in completion section keeps one ordered path: run wu:prep, check wu:status and stop if the WU is already done, then run only the exact completion command printed by prep when status remains in_progress. That status guard does not create a second completion authority.

Keep one authority

LUMENFLOW.md remains the sole managed agent contract. Prompt templates may add task or domain context, but should not restate lifecycle policy or encode a particular agent host’s instruction syntax.

Defaults first

Most projects should use the built-in composition unchanged:

pnpm wu:brief --id WU-XXX

Create .lumenflow/templates/ only when the project needs additional domain, architecture, verification, or lane guidance.

Cache-aware layout

Every brief has three stable regions:

1. a cacheable prefix containing standing methodology;
2. <!-- LUMENFLOW_STABLE_PREFIX_END -->;
3. the volatile WU body and final constraints recap.

Do not move content across that boundary casually. Changing the prefix bytes reduces prompt-cache reuse and invalidates brief-metrics baselines.

Inspect token attribution with:

pnpm wu:brief --id WU-XXX --report-tokens

Add a project template

1. Create a template

   Add .lumenflow/templates/spawn-prompt/api-standards.md:

   ---
   id: api-standards
   name: API Standards
   required: false
   order: 150
   condition: "lane === 'Framework: Core'"
   ---
   
   ## API Design Standards
   
   - Return consistent error formats.
   - Maintain the OpenAPI contract.
   - Verify endpoints with integration tests.

2. Register it in the manifest

   templates:
     - id: api-standards
       path: spawn-prompt/api-standards.md
       required: false
       order: 150
       condition: "lane === 'Framework: Core'"

3. Validate and preview

   pnpm validate
   pnpm wu:brief --id WU-XXX

Override built-in sections

A project template with the same id as a built-in section replaces that section. Common IDs include:

Purpose	Template ID
Testing methodology	methodology-tdd, methodology-test-after, methodology-none
Verification	verification-requirements, structured-content-directive
Skill selection	skills-selection, code-craft
Edit discipline	read-before-write
Coordination	mandatory-agents, agent-coordination
Completion	self-review, completion-workflow, constraints

Caution

There is no architecture-* override point today. A project template named architecture-hexagonal, architecture-layered, or architecture-none loads without error but is never read back by the spawn-prompt composer — it is silently inert. Only the methodology row above has a working prefix-based resolver.

Wrapper-style overrides can use the fully rendered default section token to prepend or append project guidance without losing computed content.

Tokens and conditions

Useful tokens include:

Token	Meaning
{WU_ID}	Current WU id
{LANE}	Lane name
{TYPE}	WU type
{WORKTREE_PATH}	Claimed worktree path
{TITLE}	WU title
{DESCRIPTION}	WU description
{WORK_DOMAIN}	Classified work domain
{REQUIRED_VERIFICATION}	Verification declared by the WU

Conditions may use type, lane, laneParent, work.domain, work.testMethodologyHint, hasRequiredVerification, and the tests.* presence flags.

Portability rules

• Keep project commands and domain knowledge in project templates.
• Refer to canonical skills by their .lumenflow/skills/<name>/SKILL.md name.
• Treat each lane’s configured WIP limit as authoritative; generated guidance does not assume a limit of one.
• Fix newly introduced test failures. Adding an accepted infrastructure failure to the baseline requires explicit authorization and an operator-run pnpm test:baseline:update -- --wu <wu-id> --reason "<approved reason>" command. Fixed known failures leave the baseline through an operator-approved ratchet refresh.
• Do not embed host invocation syntax, plugin namespaces, or host-specific paths.
• If a host requires a different prompt transport, adapt the completed brief in project-owned configuration; do not fork the canonical template policy.
• Test conditions and token replacement after every template change.

Next steps

• Template Format
• Manifest Schema
• Custom Skills
• AI Agent Integration