Customizing Spawn Prompts

The template system lets you customize the prompts generated by wu:brief for your project’s specific needs. You can add new templates, override existing ones, and create client-specific variations for different AI tools.

Defaults First

Most consumers should start with the built-in wu:brief defaults and add project-local templates only when they need different wording or extra domain-specific instructions.

• New installs get the current prompt composition automatically.
• Existing installs get the runtime defaults after pnpm lumenflow:upgrade --latest.
• lumenflow:upgrade automatically syncs onboarding docs and vendor assets (no separate docs:sync step needed).
• Create .lumenflow/templates/ only when you want to override or extend the shipped defaults.

Project-local templates are optional

wu:brief works without a project .lumenflow/templates/manifest.yaml. That directory is the override surface, not a requirement for using the defaults.

Cache-Aware Layout (Stable-Prefix Invariant)

wu:brief assembles every prompt in three regions, in this fixed order (ADR-020 §3):

1. Stable cacheable prefix — standing methodology that embeds neither the WU id nor per-WU spec content (mandatory standards, enforcement summary, code-craft, read-before-write, parallel-work directive, effort scaling, search heuristics, the watchdog liveness contract, …). Because these bytes are identical across briefs, consecutive wu:brief calls share a prompt-cache prefix.
2. Boundary marker — an HTML comment (<!-- LUMENFLOW_STABLE_PREFIX_END -->) that separates the stable prefix from the volatile body. The brief meter splits on this marker to attribute stable_prefix_tokens vs volatile_tail_tokens.
3. Volatile per-WU body — the <task> context loader, WU details, description, acceptance, code paths, memory context, action, and completion sections — followed by a constraints-only recap at the very end for attention.

Do not casually reorder the stable prefix

The stable prefix is a compatibility contract. Moving a section across the boundary marker — or reordering the prefix — changes prefix bytes, destroys prompt-cache reuse, and invalidates the brief-metrics baseline. Project overrides may change the wording of a prefix section, but should preserve whether that section stays in the stable prefix or the volatile body. The ordering guard in wu-spawn-prompt-builders.test.ts enforces the region split for the shipped composition.

Inspect the split for any WU with:

pnpm wu:brief --id WU-XXX --client <client> --report-tokens

Prompt Optimizer Dry Run

Maintainers can evaluate prompt or template rewrites with the opt-in prompt optimizer before adopting any generated wording. The optimizer is intentionally not part of wu:brief, wu:delegate, or other hot-path handoff commands. It never changes assembled briefs implicitly.

Run it against a prompt/template fixture:

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

The report includes:

• the source path and sha256: source hash;
• a before/after diff;
• before/after token estimates and the delta;
• provenance (sourceIdentifier, sourceHash, optimizerProfile, providerSurface, timestamp, and eval result);
• a schema-valid prompt:optimization_evaluated measurement event.

Eval pass is the adoption boundary

A rewrite is only an acceptable_candidate when the eval harness passes. Failed evals stay report_only; they are useful evidence, but must not be silently applied to templates or prompt sources.

By default the dry run does not write the source file or create an optimized copy. If maintainers want local telemetry, they must opt in with --telemetry-out; the event is validated against the control-plane schema before an NDJSON line is written.

Why Customize?

Project Standards

Embed your team’s coding standards, architecture patterns, and best practices.

Tool-Specific

Provide different instructions for Claude Code vs Cursor vs Windsurf.

Domain Knowledge

Include domain-specific terminology, APIs, and business logic context.

Workflow Tweaks

Adjust verification profiles, lane-specific guidance, or client-specific wording.

Quick Start

Add a Simple Template

1. Create the template file

   mkdir -p .lumenflow/templates/spawn-prompt
   cat > .lumenflow/templates/spawn-prompt/api-standards.md << 'EOF'
   ---
   id: api-standards
   name: API Standards
   required: false
   order: 150
   condition: "lane === 'Framework: Core'"
   ---
   
   ## API Design Standards
   
   When working on API endpoints:
   
   - Use RESTful conventions
   - Return consistent error formats
   - Include OpenAPI annotations
   - Write integration tests for all endpoints
   EOF

2. Add to manifest

   Edit .lumenflow/templates/manifest.yaml:

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

3. Test the template

   pnpm wu:brief --id WU-XXX --client <client>

Client-Specific Overrides

Different AI tools have different capabilities. Override templates to provide tool-specific instructions.

Override Directory Structure

.lumenflow/
  templates/
    spawn-prompt/
      code-craft.md              # Base template
  templates.claude/
    spawn-prompt/
      code-craft.md              # Claude Code override
  templates.cursor/
    spawn-prompt/
      code-craft.md              # Cursor override

How Override Resolution Works

1. Load base template from templates/spawn-prompt/
2. Normalize client name to an alias (for example claude-code -> claude)
3. Check for client override in templates.{alias}/spawn-prompt/
4. If override exists with matching id, use it instead of base
5. If no override, use base template

Client Alias Mapping

| Client Flag (--client) | Alias | Override Directory | | ------------------------ | -------- | --------------------- | | claude-code | claude | templates.claude/ | | codex-cli | codex | templates.codex/ | | gemini-cli | gemini | templates.gemini/ | | cursor | cursor | templates.cursor/ | | windsurf | windsurf | templates.windsurf/ |

Note

Client values ending in -cli are normalized by stripping -cli when no explicit alias mapping exists.

Creating a Client Override

Claude Code

---
id: skills-selection
name: Skills Selection (Claude)
required: true
order: 50
---

## Skills Selection (Claude Code)

**IMPORTANT**: Before starting work, load relevant skills.

### Loading Skills

Use the `/skill` command:

/skill wu-lifecycle # WU claim/block/done /skill tdd-workflow # RED-GREEN-REFACTOR /skill worktree-discipline # Path safety

### Skills Catalog

View available skills: `ls .claude/skills/`

Cursor

---
id: skills-selection
name: Skills Selection (Cursor)
required: true
order: 50
---

## Skills Selection (Cursor)

**IMPORTANT**: Before starting work, load relevant rules.

### Loading Rules

Reference rules with `@rules`:

- `@rules .cursor/rules/lumenflow.md`
- `@rules .cursor/rules/tdd.md`
- `@rules .cursor/rules/git-safety.md`

### Rules Catalog

View available rules: check `.cursor/rules/`

Built-In Override Keys

These template IDs ship with the default wu:brief composition and can be overridden per client or per project:

| Generator / Section | Template ID | Path | Default Order | Default Tokens | | ----------------------------------------- | ------------------------------------- | ----------------------------------------------------- | ------------- | ------------------------------------------------------- | | Methodology guidance | methodology-tdd | spawn-prompt/methodology/tdd-directive.md | 5 | - | | Methodology guidance | methodology-test-after | spawn-prompt/methodology/test-after-directive.md | 5 | - | | Methodology guidance | methodology-none | spawn-prompt/methodology/none-directive.md | 5 | - | | Architecture guidance | architecture-hexagonal | spawn-prompt/architecture/hexagonal-directive.md | 6 | - | | Architecture guidance | architecture-layered | spawn-prompt/architecture/layered-directive.md | 6 | - | | Architecture guidance | architecture-none | spawn-prompt/architecture/none-directive.md | 6 | - | | Fallback testing guidance | tdd-directive | spawn-prompt/tdd-directive.md | 10 | - | | Docs/config guidance | documentation-directive | spawn-prompt/documentation-directive.md | 10 | - | | Verification strategy | visual-directive | spawn-prompt/visual-directive.md | 15 | - | | Verification strategy | refactor-directive | spawn-prompt/refactor-directive.md | 15 | - | | Verification strategy | structured-content-directive | spawn-prompt/structured-content-directive.md | 15 | - | | Required verification rendering | verification-requirements | spawn-prompt/verification-requirements.md | 18 | REQUIRED_VERIFICATION | | generateProjectSpecificCoChangeGuidance | project-specific-co-change-guidance | spawn-prompt/project-specific-co-change-guidance.md | 19 | CO_CHANGE_GUIDANCE_SECTION | | Skills selection | skills-selection | spawn-prompt/skills-selection.md | 50 | - | | Skills guidance | code-craft | spawn-prompt/code-craft.md | 55 | - | | Edit discipline | read-before-write | spawn-prompt/read-before-write.md | 60 | - | | UI design context | design-context-ui | spawn-prompt/design-context-ui.md | 65 | - | | generateMandatoryAgentSection | mandatory-agents | spawn-prompt/mandatory-agents.md | 66 | MANDATORY_AGENTS | | generateInvariantsPriorArtSection | invariants-prior-art | spawn-prompt/invariants-prior-art.md | 67 | INVARIANTS_PRIOR_ART_SECTION | | generateImplementationContext | implementation-context | spawn-prompt/implementation-context.md | 68 | IMPLEMENTATION_CONTEXT_SECTION | | generateEffortScalingRules | effort-scaling | spawn-prompt/effort-scaling.md | 100 | - | | generateParallelToolCallGuidance | parallel-tool-calls | spawn-prompt/parallel-tool-calls.md | 110 | - | | generateIterativeSearchHeuristics | search-heuristics | spawn-prompt/search-heuristics.md | 120 | - | | generateTokenBudgetAwareness | token-budget | spawn-prompt/token-budget.md | 130 | WU_ID | | generateCompletionFormat | completion-format | spawn-prompt/completion-format.md | 135 | - | | generateCompletionWorkflowSection | completion-workflow | spawn-prompt/completion-workflow.md | 136 | WU_ID | | generateAgentCoordinationSection | agent-coordination | spawn-prompt/agent-coordination.md | 137 | AGENT_COORDINATION_SECTION | | generateBugDiscoverySection | bug-discovery | spawn-prompt/bug-discovery.md | 200 | WU_ID | | generateQuickFixCommands | quick-fix-commands | spawn-prompt/quick-fix-commands.md | 210 | - | | generateLaneSelectionSection | lane-selection | spawn-prompt/lane-selection.md | 220 | - | | Recovery guidance | worktree-recovery | spawn-prompt/worktree-recovery.md | 300 | WORKTREE_PATH | | generateWorktreePathGuidance | worktree-path-guidance | spawn-prompt/worktree-path-guidance.md | 301 | WORKTREE_PATH | | Lane-specific guidance | lane-guidance-operations | spawn-prompt/lane-guidance/operations.md | 400 | - | | Lane-specific guidance | lane-guidance-framework | spawn-prompt/lane-guidance/framework.md | 400 | - | | Lane-specific guidance | lane-guidance-content | spawn-prompt/lane-guidance/content.md | 400 | - | | generateActionSection (claimed path) | action-claimed | spawn-prompt/action-claimed.md | 820 | WORKTREE_PATH | | generateActionSection (unclaimed path) | action-unclaimed | spawn-prompt/action-unclaimed.md | 820 | WU_ID, LANE, WORKTREE_PATH_HINT, WU_EVENTS_PATH | | generateDbRiskVerificationGuidance | db-risk-verification | spawn-prompt/db-risk-verification.md | 845 | - | | Pre-completion checklist | self-review | spawn-prompt/self-review.md | 850 | WU_ID | | Full prompt constraints | constraints | spawn-prompt/constraints.md | 1000 | WU_ID |

Note

Templates such as implementation-context, invariants-prior-art, project-specific-co-change-guidance, and agent-coordination are wrapper-style overrides. Their primary token contains the fully rendered default section, which lets you wrap, prepend, or replace the built-in wording without losing the runtime-computed content.

Example: Claude-Specific Code Craft Override

---
id: code-craft
name: Code Craft (Claude)
required: true
order: 55
---

## Code Craft (Claude)

Before writing custom code, run a focused library/context search for existing patterns.

<example>
// Before
die('failed');

// After
die('Failed to parse workspace.yaml: missing lane field. Run pnpm lane:setup to regenerate.');
</example>

Tip

You don’t need to create overrides for every template. Only override templates where client behavior differs significantly.

Adding Custom Templates

Step 1: Create the Template

Create a markdown file with YAML frontmatter:

---
id: my-custom-template
name: My Custom Template
required: false
order: 250
tokens: [WU_ID, LANE]
condition: "type === 'feature'"
---

## Custom Guidance for {WU_ID}

Working in lane: {LANE}

Your custom instructions here...

Step 2: Add to Manifest

Edit .lumenflow/templates/manifest.yaml:

templates:
  # ... existing templates ...

  - id: my-custom-template
    path: spawn-prompt/my-custom-template.md
    required: false
    order: 250
    condition: "type === 'feature'"

Step 3: Verify

# Check manifest is valid
pnpm validate

# Test with a feature WU
pnpm wu:brief --id WU-XXX --client <client> | grep "Custom Guidance"

Common Customization Scenarios

Scenario 1: Project-Specific Architecture

Add guidance about your project’s architecture patterns:

---
id: architecture-patterns
name: Architecture Patterns
required: true
order: 100
---

## Project Architecture

This project uses:

- **Hexagonal Architecture**: Ports in `src/ports/`, adapters in `src/infrastructure/`
- **CQRS**: Commands in `src/commands/`, queries in `src/queries/`
- **Event Sourcing**: Events in `src/events/`, aggregates in `src/domain/`

### Import Rules

- `application/` NEVER imports from `infrastructure/`
- Use dependency injection for all adapters
- Ports are interfaces only, no implementation

Scenario 2: Testing Requirements

Customize testing guidance beyond default TDD:

---
id: testing-requirements
name: Testing Requirements
required: true
order: 20
condition: "type !== 'documentation'"
---

## Testing Requirements

### Coverage Thresholds

- Application layer: 95% coverage required
- Infrastructure: 80% coverage required
- E2E critical paths: 100% coverage

### Test Patterns

- Use `describe`/`it` blocks, not `test()`
- Mock external services with `vi.mock()`
- Use factories for test data (see `tests/factories/`)

### Required Tests for Features

- [ ] Unit tests for business logic
- [ ] Integration tests for API endpoints
- [ ] E2E test for happy path

Scenario 2b: Structured Content Profiles (YAML/JSON/Markdown)

For prompt/config/content work, override the built-in structured-content-directive instead of forcing backend-style TDD steps:

---
id: structured-content-directive
name: Structured Content Directive
required: false
order: 15
condition: "work.testMethodologyHint === 'structured-content' && type !== 'documentation' && type !== 'docs' && type !== 'config'"
---

## Structured Content Verification

- Run the project-specific prompt/classification evaluation command configured by your team
- Validate YAML/JSON schema compatibility for changed content files
- Record evaluator outputs in notes or evidence artifacts

Note

Keep project commands (for example pnpm prompts:eval) in local templates, not in core framework code. This keeps LumenFlow generic while still enabling strict domain workflows.

Scenario 3: Lane-Specific Guidance

Create guidance for specific lanes:

---
id: lane-guidance-platform
name: Platform Lane Guidance
required: false
order: 400
condition: "laneParent === 'Platform'"
---

## Platform Lane Guidelines

When working on Platform infrastructure:

### Deployment Considerations

- All changes require staging deployment first
- Use feature flags for risky changes
- Update runbooks for operational changes

### Monitoring Requirements

- Add metrics for new services
- Create alerts for error conditions
- Update dashboards for visibility

### Change Management

- Notify #platform-changes channel before deployment
- Schedule changes during low-traffic windows
- Have rollback plan documented

Lane guidance templates are selected by laneParent conditions and automatically included when the template id starts with lane-guidance-.

Scenario 4: Security-Focused Projects

Add security requirements:

---
id: security-requirements
name: Security Requirements
required: true
order: 180
---

## Security Requirements

### Input Validation

- Validate all user input at boundaries
- Use allowlists, not blocklists
- Sanitize before storing or displaying

### Authentication

- Never store plaintext passwords
- Use secure session tokens
- Implement rate limiting on auth endpoints

### Data Handling

- Encrypt PII at rest and in transit
- Audit log access to sensitive data
- Apply principle of least privilege

### Secrets

- Never commit secrets to git
- Use environment variables or secret managers
- Rotate credentials regularly

Scenario 5: Documentation WUs

Customize documentation-specific guidance:

---
id: docs-standards
name: Documentation Standards
required: false
order: 15
condition: "type === 'documentation' || type === 'docs'"
---

## Documentation Standards

### Format Requirements

- Use sentence case for headings
- Include code examples for all features
- Add links to related documentation
- Use admonitions for warnings/tips

### Content Structure

1. Start with "What" (definition/purpose)
2. Then "Why" (benefits/use cases)
3. Then "How" (step-by-step instructions)
4. End with "Next Steps" (related topics)

### Review Checklist

- [ ] Spelling and grammar checked
- [ ] Code examples tested
- [ ] Links verified
- [ ] Screenshots current

Token Usage

Use tokens to include WU-specific information:

| Token | Usage | | ------------------------------ | --------------------------------------------- | | {WU_ID} | Reference the current WU | | {LANE} | Show lane context | | {TYPE} | Conditional text based on type | | {WORKTREE_PATH} | Include worktree navigation | | {TITLE} | Show WU title in headings | | {DESCRIPTION} | Include full WU description | | {WORK_DOMAIN} | Render the classified work domain | | {WORK_TEST_METHODOLOGY_HINT} | Render the classifier-driven methodology hint | | {REQUIRED_VERIFICATION} | Render required verification from the WU spec |

Condition Variables

These context variables are especially useful for lane-aware and domain-aware composition:

| Variable | Meaning | | -------------------------- | ------------------------------------------------------------ | | work.domain | Classified domain such as ui, backend, or docs | | work.testMethodologyHint | Classifier hint such as smoke-test or structured-content | | hasRequiredVerification | Truthy when the WU spec declares any required verification | | tests.hasUnit | Truthy when the WU spec declares unit test paths | | tests.hasE2E | Truthy when the WU spec declares E2E test paths | | tests.hasManual | Truthy when the WU spec declares manual verification items |

Base variables such as type, lane, laneParent, policy.testing, and policy.architecture remain available as well.

Example with tokens:

---
id: wu-context
name: WU Context
required: true
order: 5
tokens: [WU_ID, LANE, TITLE]
---

# {TITLE}

**WU:** {WU_ID}
**Lane:** {LANE}

Follow the acceptance criteria defined in the WU specification.

Debugging Templates

Check Manifest Validity

pnpm validate

Preview Assembled Prompt

# Full output
pnpm wu:brief --id WU-XXX --client <client>

# Check specific section
pnpm wu:brief --id WU-XXX --client <client> | grep -A 10 "My Custom"

List Loaded Templates

# Show which templates were included
pnpm wu:brief --id WU-XXX --client <client>

Common Issues

Template not appearing:

1. Check id matches in both template and manifest
2. Verify condition evaluates to true for this WU
3. Check path is correct (relative to templates/)
4. Ensure file has valid frontmatter

Client override not applied:

1. Verify directory name: templates.{alias}/ (see Client Alias Mapping)
2. Check override has same id as base template
3. Confirm using correct --client flag

Token not replaced:

1. Use uppercase: {WU_ID} not {wu_id}
2. Check token is available in context
3. Verify template is loaded (check --verbose)

Best Practices

Template Design

• Focus each template - One concept per template
• Use conditions - Don’t include irrelevant content
• Document intent - Add comments in markdown
• Test thoroughly - Verify with --dry-run

Override Strategy

• Override sparingly - Most templates work across clients
• Match IDs exactly - Override uses same id as base
• Keep in sync - Update both when content changes

Maintenance

• Version templates - Commit template changes with WUs
• Review regularly - Update templates as practices evolve
• Track effectiveness - Remove templates agents ignore

Next Steps

• Template Format - Detailed template structure
• Manifest Schema - Manifest configuration
• Custom Skills - Complement templates with skills
• AI Agents - Full agent integration guide