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.

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
generateCodexConstraints	codex-constraints	spawn-prompt/codex-constraints.md	1005	WU_ID plus numbering and TDD-block tokens

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