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.

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 TDD requirements, gate priorities, or lane-specific guidance.

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: "laneParent === '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: "laneParent === '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/
      skills-selection.md        # Base template
  templates.claude/
    spawn-prompt/
      skills-selection.md        # Claude Code override
  templates.cursor/
    spawn-prompt/
      skills-selection.md        # Cursor override

How Override Resolution Works

1. Load base template from templates/spawn-prompt/
2. Check for client override in templates.{client}/spawn-prompt/
3. If override exists with matching id, use it instead of base
4. If no override, use base template

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/`

Supported Clients

Client	Override Directory	Used When
claude	templates.claude/	--client claude-code
cursor	templates.cursor/	--client cursor
windsurf	templates.windsurf/	--client windsurf
codex	templates.codex/	--client codex

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 exec lumenflow 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 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

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

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 exec lumenflow 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.{client}/
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