Expand Mode

Use wavemill expand when you want to prepare backlog items outside of wavemill mill. Mill mode can do this automatically, but expand is useful when you want to curate task packets ahead of time or target specific issues directly.

What It Does

With no args, fetches Linear backlog filtered to issues without detailed task packets.
Ranks issues by priority score (considers Linear priority, estimates, labels, and dependencies).
Lets you interactively select up to 3 issues to expand.
Accepts direct issue IDs or Linear issue URLs and skips the picker in that mode.
Expands each issue with Claude CLI using the issue-writer prompt template.
Gathers codebase context (directory structure, recent commits, relevant files, project-context.md).
Generates comprehensive 9-section task packets with progressive disclosure (header + details).
Validates output against quality gates (structure, completeness, actionability).
Auto-extracts and applies suggested labels from the expanded content.
Updates both description and labels in Linear.

Run It

# Interactive expand with project auto-detection
cd <your-project>
wavemill expand

# Expand a specific issue directly
wavemill expand HOK-1494

# Expand multiple issues sequentially
wavemill expand HOK-1494 HOK-1531

# Linear issue URLs are accepted too
wavemill expand https://linear.app/hokusai/issue/HOK-1494/fix-archived-routing-decision-parsing-for-eval-enrichment

Common overrides:

# Specify project explicitly
LINEAR_PROJECT="My Project" wavemill expand

# Adjust selection limits
MAX_SELECT=5 MAX_DISPLAY=15 wavemill expand

How It Works

1) Issue Selection

wavemill expand has two modes:

No args: Wavemill fetches your backlog and shows a ranked interactive picker.
One or more args: Wavemill validates each argument as TEAM-123 or a Linear issue URL, canonicalizes it, and expands those issues directly without fetching backlog candidates.

Wavemill fetches your Linear backlog and filters to issues that need expansion:

Missing detailed task packet structure
Short descriptions (< 200 words)
No implementation-ready content

In interactive mode, issues are ranked by priority score (same algorithm as mill mode) and displayed for selection.

2) Context Gathering

For each selected issue, the tool gathers:

Issue metadata — title, description, labels, estimates, parent/child relationships
Directory structure — 3-level tree of the repository
Project context — full content from .wavemill/project-context.md if available
Recent git activity — last 20 commits to understand active areas
Relevant files — keyword search based on issue title

3) Claude Expansion

The tool invokes Claude CLI with:

The issue-writer prompt template (tools/prompts/issue-writer.md)
Issue context and codebase context
Instructions to output pure markdown (no tool calls, no conversational text)

Claude produces a comprehensive task packet following the 9-section structure.

4) Quality Validation

The expanded content goes through validation:

Structure check — verifies expected section headers are present
Layer 1 gates — objective clarity, file/dependency coverage, success criteria completeness
Layer 2 gates — implementation guidance, constraint specificity, validation steps

If validation fails, you’re prompted whether to proceed or fix issues first.

5) Label Extraction & Application

The tool parses section 9 (Proposed Labels) from the expanded content and:

Extracts label names and categories
Compares against existing Linear labels
Creates new labels if needed
Applies all labels to the issue

6) Linear Update

The full expanded description (header + details) is pushed to Linear. The issue now has:

Implementation-ready task packet
Appropriate labels for conflict detection and routing
Structured validation criteria

Task Packet Structure

Expanded issues use progressive disclosure to reduce context overload:

Header (Brief Overview)

Objective (2-3 sentences)
Top 5 key files to modify
Top 3 critical constraints
High-level success criteria
Links to detailed sections

Details (Complete Specification)

Objective & Scope — what and why
Technical Context — files, dependencies, architecture patterns
Implementation Approach — step-by-step plan
Success Criteria — requirements with [REQ-FX] tags
Implementation Constraints — rules and boundaries
Validation Steps — concrete test scenarios
Definition of Done — completion checklist
Rollback Plan — how to revert if needed
Proposed Labels — for conflict detection and routing

Agents receive the brief header initially and read detail sections on-demand.

Quality Gates

Layer 1: Core Requirements

Objective is clear and actionable (< 100 words)
All key files and dependencies are identified
Success criteria are measurable and testable
Validation steps are concrete and executable

Layer 2: Implementation Readiness

Step-by-step implementation guidance provided
Constraints are specific with examples
Test scenarios cover happy path and edge cases
Labels enable proper conflict detection

Configuration lives in .wavemill-config.json:

{
  "validation": {
    "layer1": {
      "objectiveMaxWords": 100,
      "minKeyFiles": 1,
      "minSuccessCriteria": 1
    },
    "layer2": {
      "requireImplementationSteps": true,
      "minValidationSteps": 1
    }
  }
}

Environment Variables

LINEAR_PROJECT — Explicit Linear project override
PROJECT_NAME — Legacy project override, only used when no repo project is configured
MAX_SELECT — Maximum issues to select (default: 3)
MAX_DISPLAY — Maximum issues to display (default: 9)
CLAUDE_CMD — Claude CLI command (default: claude)

Direct mode expands multiple issues sequentially in the order provided so output and Linear updates stay readable.

Key Files

File	Purpose
`tools/expand-issue.ts`	Core expansion tool — fetches issue, gathers context, invokes Claude
`tools/prompts/issue-writer.md`	Task packet generation prompt template
`shared/lib/task-packet-validator.ts`	Quality gate validation logic
`.wavemill/project-context.md`	Living documentation of patterns and conventions
`.wavemill-config.json`	Validation thresholds and project settings