Customizing Spawn Prompts

Name: LumenFlow
Author: The LumenFlow Project

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.

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:

a cacheable prefix containing standing methodology;
;
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

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.

Register it in the manifest

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

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`
Architecture	`architecture-hexagonal`, `architecture-layered`, `architecture-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`

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.

Prompt optimizer dry run

Maintainers can evaluate a rewrite without applying it:

node tools/cli-entry.mjs prompt-optimize --source path/to/prompt.md --dry-run

The report contains the source hash, diff, token delta, provenance, and eval result. Only an eval-passing candidate should be adopted.

Portability rules

Keep project commands and domain knowledge in project templates.
Refer to canonical skills by their .lumenflow/skills/<name>/SKILL.md name.
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.