Idea to Shipping

Software Delivery Pack workflow

This end-to-end guide uses the Software Delivery Pack. Every command shown routes through the LumenFlow kernel for scope enforcement, policy evaluation, and evidence recording.

This guide walks through building SpendSense, a personal finance categorizer, from initial idea to deployed app. You’ll see how LumenFlow structures AI-assisted development, enabling any coding agent to understand and execute your project.

Vendor Agnostic

This guide uses Claude Code as the example, but LumenFlow works with any AI coding assistant — Cursor, Windsurf, Cline, Aider, and more. The key is AGENTS.md: a universal entry point that any agent can read to understand your workflow.

What You’ll Build

SpendSense — a local-first personal finance app that:

• Imports transactions from CSV (bank exports)
• Auto-categorizes spending using a rules engine
• Learns from your corrections
• Shows monthly spending dashboards

This isn’t a trivial example. Building it requires research into transaction categorization, financial data patterns, and local-first architecture — perfect for showcasing LumenFlow’s structured approach.

Phase 1: Deep Research

Before writing code, validate your idea and make key technical decisions. Use your preferred AI tool (Claude, GPT, etc.) for market research and technical discovery.

Research Questions for SpendSense

• Categorization: How do banks categorize transactions? (MCC codes, merchant matching)
• Data Sources: Financial APIs (Plaid, Teller) vs CSV import — what’s the MVP scope?
• Patterns: Rule-based matching vs ML classification — which handles 80% of cases?
• Security: How to handle financial data safely? (local-first, no credential storage)

Output: PRODUCT_BRIEF.md

Your research crystallizes into a product brief — the source of truth for everything that follows.

# SpendSense - Personal Finance Categorizer

## Problem

Manual transaction categorization is tedious. Bank categories are inconsistent.

## Research Findings

- MCC (Merchant Category Codes) provide baseline categorization
- Rule-based matching (merchant name → category) handles 80% of cases
- ML needed only for ambiguous merchants
- Start with CSV import, add Plaid later (reduces initial scope)

## MVP Features

1. CSV transaction import (bank export format)
2. Auto-categorization via rules engine
3. Manual override with learning
4. Monthly spending dashboard

## Technical Decisions

- Stack: Next.js + SQLite (local-first, no cloud dependency)
- No auth in MVP (local file storage)
- Categories: Standard set (Groceries, Transport, etc.) + custom user categories

Note

LumenFlow Benefit: This brief becomes the source of truth. Agents reference it when generating Work Units and making implementation decisions. No more “what did we decide about X?” — it’s documented.

Phase 2: Project Setup

Create your project and initialize LumenFlow.

create-next-app in Non-Empty Directories

pnpm create next-app . fails in non-empty directories. If you already have files (e.g., a README.md or .git), use the temp-dir workaround below.

Option A: New Project (Empty Directory)

mkdir spendsense && cd spendsense
git init
pnpm create next-app . --typescript --tailwind --app
pnpm add -D @lumenflow/cli
pnpm lumenflow

Option B: Existing Project or Non-Empty Directory

When create-next-app fails because your directory is not empty, use a temp directory:

# 1. Create Next.js app in a temp directory
pnpm create next-app /tmp/nextjs-scaffold --typescript --tailwind --app

# 2. Merge the scaffolding into your existing project
cp -rn /tmp/nextjs-scaffold/* .
cp -rn /tmp/nextjs-scaffold/.* . 2>/dev/null || true

# 3. Install dependencies and initialize LumenFlow
pnpm install
pnpm add -D @lumenflow/cli
pnpm lumenflow

# 4. Clean up
rm -rf /tmp/nextjs-scaffold

Tip

There’s no --client/--vendor flag — lumenflow init always scaffolds the same universal surfaces, for every AI tool. The --full flag (default: true) adds documentation scaffolding; pass --minimal to skip it. See AI Coding Assistant Integrations for adapting the contract into a specific tool.

What lumenflow Creates

| File | You Use It For | Agents Use It For | | --------------------------- | ---------------------- | -------------------------------------------- | | AGENTS.md | Reference docs | Entry point — first file any agent reads | | workspace.yaml | Configure lanes, gates | Lane definitions, gate commands to run | | .lumenflow/constraints.md | Understand rules | Non-negotiable constraints to follow | | docs/.../backlog.md | Track work visually | Find ready WUs to claim |

Universal Entry Point

With LumenFlow initialized, any AI coding assistant can understand your project by reading AGENTS.md. No special prompting required. This is the key to vendor-agnostic AI development.

Phase 3: Generate Your Roadmap

This is the magic moment. Drop PRODUCT_BRIEF.md into your project and ask your agent:

“Read PRODUCT_BRIEF.md and create a LumenFlow initiative with WUs organized into phases: Foundation, Categorization Engine, UI, Polish.”

What the Agent Does

1. Reads PRODUCT_BRIEF.md — extracts requirements, technical decisions, and MVP scope

2. Creates an Initiative — the container for related work

   pnpm initiative:create --id INIT-001 --slug spendsense-mvp --title "SpendSense MVP"

3. Generates Work Units — each with full specs the agent (or another agent) can execute

Sample Generated WU

# WU-001.yaml - What the agent generates
id: WU-001
title: Set up SQLite schema for transactions
lane: 'Framework: Core'
type: feature
status: ready
initiative: INIT-001
phase: 1
description: |
  Create the database schema for storing imported transactions.
  Reference: PRODUCT_BRIEF.md#technical-decisions
acceptance:
  - Transaction table with: id, date, amount, description, merchant, category
  - Category table with: id, name, parent_id (for hierarchy)
  - Indexes on date and category for dashboard queries
code_paths:
  - src/lib/db/schema.ts
  - src/lib/db/migrations/
test_paths:
  unit:
    - src/lib/db/__tests__/schema.test.ts

Note

LumenFlow Benefit: The WU YAML isn’t just documentation — it’s the agent’s work order. code_paths tells it where to write, acceptance defines done, test_paths guides TDD. Any agent can pick up this WU and know exactly what to build.

Generated Roadmap

| WU | Title | Lane | Phase | | ------ | ---------------------------------- | ----------------- | ----- | | WU-001 | SQLite schema for transactions | Framework: Core | 1 | | WU-002 | CSV parser for bank formats | Framework: Core | 1 | | WU-003 | Rule-based categorization engine | Framework: Core | 2 | | WU-004 | Category learning from corrections | Framework: Core | 2 | | WU-005 | Transaction list with filters | Experience: UI | 3 | | WU-006 | Monthly spending dashboard | Experience: UI | 3 | | WU-007 | Import flow wizard | Experience: UI | 3 | | WU-008 | Error handling and edge cases | Framework: Core | 4 | | WU-009 | Deploy to Vercel | Operations: Infra | 4 |

Phase 4: Execute

Now execute the roadmap. You can work WU-by-WU, or orchestrate parallel execution across lanes.

Single Agent Execution

pnpm wu:claim --id WU-001 --lane "Framework: Core"
# Agent is now in worktrees/framework-core-wu-001

Note

LumenFlow Benefit (Worktree Isolation): Each WU gets its own git worktree — an isolated branch. The agent can’t accidentally break main, and multiple agents can work in parallel without merge conflicts.

What Happens When an Agent Claims a WU

1. Worktree created — isolated git branch, no conflicts with main

2. Agent reads WU YAML — knows exactly what to build, where to put it

3. Loads relevant skills — /skill tdd-workflow for test-first approach

4. Implements against acceptance criteria — each criterion becomes a checklist item

5. Runs gates — pnpm wu:prep --id WU-001 validates format, lint, types, tests

6. Completes — pnpm wu:done --id WU-001 merges to main, creates completion stamp

Note

LumenFlow Benefit (Gates as Guardrails): Agents can’t merge broken code. Gates run format, lint, typecheck, and tests before allowing completion. This is especially valuable when agents work autonomously.

Parallel Agent Execution

For larger initiatives, orchestrate multiple agents working in parallel:

# Preview the execution plan
pnpm orchestrate:initiative --initiative INIT-001 --dry-run

Output:

Wave 0: WU-001, WU-002 (parallel - no dependencies)
Wave 1: WU-003, WU-004 (depends on Wave 0)
Wave 2: WU-005, WU-006, WU-007 (depends on Wave 1)
Wave 3: WU-008, WU-009 (depends on Wave 2)

Note

LumenFlow Benefit (Wave-based Orchestration): The orchestrator analyzes dependencies into logical waves, then prepares or launches one wave at a time. WU-001 and WU-002 can run in parallel because they do not conflict; WU-003 waits until the completion boundary for both is satisfied. Lane separation ensures agents do not step on each other, and the control plane keeps human, agent, and cloud orchestration on the same model.

Agent Coordination

Agents don’t work in isolation. The memory layer enables coordination:

# Agent signals progress
pnpm mem:signal "Schema complete, ready for review" --wu WU-001

# Orchestrator checks signal traffic and reconciled state
pnpm mem:inbox --since 1h
pnpm orchestrate:init-status --initiative INIT-001

Note

LumenFlow Benefit (Memory Layer): Agents can signal progress, checkpoint state for resumption, and coordinate handoffs. Signals are one input to orchestration, not the whole execution ledger; completion still reconciles against WU status, worktree / branch state, gates, and stamps. This is critical for long-running work and multi-agent scenarios.

Phase 5: Ship It

Once all WUs complete, verify and deploy:

# Check initiative completion
pnpm initiative:status --id INIT-001

# All stamps present = all WUs done
ls .lumenflow/stamps/
# WU-001.done  WU-002.done  WU-003.done ...

# Deploy
npx vercel

Note

LumenFlow Benefit (Stamps as Truth): Completion stamps (.lumenflow/stamps/WU-XXX.done) are the source of truth. The orchestrator checks stamps before spawning dependent work. No stamp = not done, regardless of what the YAML status says.

What the Agent Learned

From the agent’s perspective, here’s what it consumed and how:

| What Agent Read | What Agent Did | | --------------------- | ----------------------------------------------- | | AGENTS.md | Understood project workflow, found entry points | | PRODUCT_BRIEF.md | Extracted requirements, generated WUs | | WU-001.yaml | Knew scope, paths, acceptance criteria | | workspace.yaml | Understood lanes, ran correct gate commands | | /skill tdd-workflow | Applied test-first methodology | | pnpm wu:prep output | Fixed issues before completion | | .lumenflow/stamps/ | Verified dependencies before proceeding |

This is the power of LumenFlow: structured context that any agent can consume.

Key Takeaways

Structured Chaos

LumenFlow turns a product brief into executable work units. No more “where do I start?” — the roadmap is generated.

Agent-Native

AGENTS.md + WU YAML = agents understand your project without special prompting. Works with any AI coding assistant.

Parallel by Default

Worktree isolation + lane separation = safe concurrent execution. Multiple agents, no conflicts.

Gates as Guardrails

Agents can’t merge broken code. Format, lint, typecheck, and tests run before completion.

Coordination Built-In

Memory layer + stamps = agents know what’s done and what’s blocked. Handoffs happen automatically.

Next Steps

• Work Units — Deep dive on WU structure and lifecycle
• Initiatives — Coordinating multi-phase projects
• AI Agent Integration — Advanced agent patterns
• A Day with LumenFlow — Daily workflow walkthrough