Flana

Page-Driven Development Framework for Claude Code

Build software the way users think about it. Flana provides a structured methodology for AI-assisted development that makes code generation predictable, auditable, and safe.

The Problem

Building software with AI assistants is powerful, but without structure, projects become chaotic:

• Context disappears between sessions - AI forgets what you discussed
• Requirements drift as you iterate without documentation
• Progress is invisible - no way to track what's done vs pending
• Inconsistent code - AI makes different decisions each time
• Integration nightmares - frontend and backend don't align

The Solution

Flana brings structure to AI-assisted development:

| Problem | Flana Solution | |---------|----------------| | Lost context | Persistent YAML specifications | | Drifting requirements | Detailed capsules with acceptance criteria | | Hidden progress | Task tracking with status and dependencies | | Inconsistent code | Tech stack configuration enforces patterns | | Integration issues | API contracts defined before implementation |

Quick Start

# Install globally
npm install -g flana

# Initialize in your project (runs interactive stack interview)
cd your-project
flana init

# The interview guides you through:
# - Quick or Full mode (~8 vs ~20 questions)
# - Optional template selection (nextjs-modern, react-vite, t3-stack, etc.)
# - Framework choices with smart defaults

# Open in Claude Code and create your first feature flow
/fl-flow "User authentication with login, register, and password reset"

# Then continue building
/fl-pages user-auth
/fl-page login
/fl-tasks login
/fl-implement login

Alternative init modes:

flana init --quick              # Quick mode (~8 essential questions)
flana init --template nextjs-modern  # Start from template defaults
flana init --skip-stack         # Skip interview, configure later

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Installation, setup, and your first project | | Core Concepts | Understanding flows, capsules, tasks, and scopes | | CLI Reference | Complete reference for all CLI commands | | Slash Commands | Commands for use in Claude Code | | Workflows | Common development patterns and best practices | | Use Cases | Real-world scenarios and examples | | Configuration | Stack configuration and project settings | | Troubleshooting | Common issues and solutions |

How It Works

1. Define Feature Flows

A flow represents a complete user journey or feature area. In Claude Code:

/fl-flow "E-commerce checkout with cart, shipping, payment, and confirmation"

2. Generate Page Specifications

Each page gets a detailed "capsule" specification:

/fl-pages checkout    # Generate stubs for all pages
/fl-page cart-review  # Create detailed specification

Capsules define:

• UI components and their states
• API contracts (endpoints, request/response schemas)
• Data requirements
• User actions and interactions
• Error handling
• Acceptance criteria

3. Generate Implementation Tasks

Tasks are atomic, ordered, and dependency-aware:

/fl-tasks cart-review

Tasks are scoped by layer:

• Data: Database schemas, migrations
• Backend: API endpoints, validation, services
• Frontend: Components, state management, hooks
• Integration: Wiring everything together
• Tests: Unit and integration tests

4. Execute Progressively

Implement one layer at a time:

/fl-ui cart-review      # Frontend with mocks
/fl-backend cart-review # Backend implementation
/fl-implement cart-review # Full integration

CLI Commands

Project Management

flana init [path]           # Initialize Flana in a project
flana adopt [path]          # Adopt existing project into Flana
flana doctor [path]         # Check setup and diagnose issues
flana focus <flow/page>     # Set working context

Information

flana list [flows|pages|tasks]  # List project items
flana stats                      # Show project statistics
flana tree [flow-id]            # Show project tree structure

Tech Stack

flana stack                  # Show current stack configuration
flana stack setup            # Re-run the interactive interview
flana stack list             # List available templates
flana stack use <template>   # Apply template directly (skips interview)
flana stack set <key> <val>  # Modify a setting

Available Templates: | Template | Stack | |----------|-------| | nextjs-modern | Next.js 14+, App Router, Tailwind, shadcn/ui, Prisma | | react-vite | React 18+ SPA, Vite, TypeScript, Tailwind, Supabase | | t3-stack | Next.js, tRPC, Prisma, NextAuth | | express-api | Express REST API, TypeScript, Prisma | | fastapi | Python FastAPI, SQLAlchemy, PostgreSQL |

Templates pre-fill interview defaults - you can accept (Enter) or customize each choice.

Maintenance

flana clean [--dry-run]      # Clean obsolete files
flana ci                     # Run CI validation checks
flana validate               # Check specs for issues
flana export [--format json] # Export all specs

Slash Commands (Claude Code)

After flana init, these commands work in Claude Code:

Core Workflow

| Command | Purpose | |---------|---------| | /fl-flow "desc" | Create a Feature Flow from description | | /fl-pages [flow] | Generate page stubs from flow | | /fl-page <id> | Generate detailed page specification | | /fl-tasks <id> | Generate implementation task plan | | /fl-implement <id> | Execute tasks and write code |

Scoped Implementation

| Command | Purpose | |---------|---------| | /fl-ui <id> | Generate frontend only (with mocks) | | /fl-backend <id> | Generate backend only | | /fl-scope | Manage development scopes |

Navigation & Status

| Command | Purpose | |---------|---------| | /fl-ls [type] | List flows, pages, or tasks | | /fl-status | Show progress and recommendations | | /fl-focus <id> | Set working context | | /fl-validate | Check specs for issues |

Debugging & Fixes

| Command | Purpose | |---------|---------| | /fl-fix-task <task> | Diagnose and fix a failed task | | /fl-fix-bug <id> | Generate fix for a tracked bug | | /fl-regen <id> | Safely regenerate after changes |

Automation

| Command | Purpose | |---------|---------| | /fl-autopilot <id> | Autonomously implement until complete | | /fl-cancel | Stop autopilot gracefully |

Project Structure

your-project/
├── CLAUDE.md              # Project context for Claude Code
├── .claude/
│   └── commands/          # Slash commands
│       ├── fl-flow.md
│       ├── fl-page.md
│       ├── fl-tasks.md
│       └── ...
├── .flana/
│   ├── config.yaml        # Project configuration
│   ├── stack.yaml         # Tech stack configuration
│   ├── focus              # Current working context
│   └── templates/         # Custom templates
└── features/
    └── <flow-id>/
        ├── flow.yaml              # Flow specification
        ├── pages/
        │   ├── <page>.yaml        # Page stub
        │   └── <page>_capsule.yaml # Detailed capsule
        └── tasks/
            ├── <page>_tasks.yaml  # Task plan
            └── <page>_state.yaml  # Execution state

Example: Building a Login Page

# 1. Initialize with stack interview
flana init --template react-vite
# Answer ~8 questions (quick mode) or accept template defaults

# 2. Create authentication flow (in Claude Code)
/fl-flow "User authentication with login and registration"

# 3. Generate page stubs
/fl-pages user-auth

# 4. Create detailed login specification
/fl-page login

# This generates a capsule with:
# - LoginForm component specs
# - POST /api/auth/login contract
# - Form validation rules
# - Error states
# - Success redirect logic

# 5. Generate tasks
/fl-tasks login

# Tasks are created for:
# - T1: Database schema (User model)
# - T2: API endpoint implementation
# - T3: Input validation
# - T4: React LoginForm component
# - T5: Form state management
# - T6: Integration tests

# 6. Implement frontend first
/fl-ui login
# Creates components with mock API

# 7. Implement backend
/fl-backend login
# Creates real API endpoints

# 8. Check progress
flana stats

Key Principles

1. Page = Unit of Delivery — Each page works independently
2. Specs = Source of Truth — YAML files persist across sessions
3. Progressive Implementation — Build layer by layer
4. Dependency Awareness — Tasks execute in correct order
5. Safe Regeneration — Changes never break other pages

Requirements

• Node.js 20+
• Claude Code CLI (for slash commands)

License

MIT

Built for developers who want AI-assisted coding without the chaos.

Report Issues | Documentation | Contributing