Bangstack

📋 Want to see what Bangstack can do RIGHT NOW? Check bangstack.yaml - Bangstack's own specification (we dogfood ourselves!). This is the single source of truth for what features exist. Run bangstack check-alignment bangstack.yaml to verify.

An Application Description Language - Write your app as a YAML specification, implement it however you want, validate it stays true to the contract.

Bangstack is a specification format + validation engine that ensures your implementation matches your design. Write bang.yaml to describe WHAT your application does (models, actions, journeys), then implement it in ANY language or framework. Bangstack validates that your code honors the contract.

Not a code generator. A specification validator.

Philosophy

The Three Pillars of Bangstack:

1. Spec-First Development

Your bang.yaml specification describes WHAT your application does - its models, actions, journeys, and actors. HOW you implement it is completely up to you:

• Any language: Python, TypeScript, Go, Ruby, Java, Rust...
• Any framework: Flask, FastAPI, Express, Rails, Spring...
• Any architecture: Microservices, monolith, serverless...

Bangstack validates that your implementation honors the contract through progressive validation levels - from simple file existence checks to full end-to-end journey tests.

2. Research-First Development (v1.8.0+)

Define WHY you're building and WHO you're building for before writing code:

• Success Philosophy: What does "done" mean? Define vision, success criteria, measurable outcomes
• Design Philosophy: Why does this experience feel right? Document principles and emotional journeys
• Personas: Who are your users? Create detailed archetypes with pain points and goals

Your specification IS your research artifact - it evolves from hypothesis → learning → validated as you ship and learn.

3. Automation-First Development (v2.0+ Vision)

Journeys are executable workflows, not just documentation:

• Orchestrated Execution: The spec doesn't just describe journeys - it runs them
• Manual Steps as Nodes: Admin approvals and human tasks are explicit pause points in automated flows
• Change Spec, Change Behavior: Update the journey in bang.yaml, the workflow updates automatically

The Vision: Your specification is executable. Write the journey once, it orchestrates your entire application flow.

Features

• Application Description Language: Describe WHAT your app does in YAML
• Progressive Validation: 4 levels from existence → protocol → tests → E2E
• Language-Agnostic: Works with ANY implementation (Python, TS, Go, Ruby...)
• Framework-Agnostic: No opinion on Flask vs FastAPI vs Express vs Rails
• Zero Implementation Coupling: Your code never imports bangstack (only tests do)
• Schema Versioning: Seamless migration between specification versions
• Code Generators (Experimental): TypeScript generators available as exploratory tools (see src/experimental/generators)

Installation

npm install -g bangstack

Quick Start

Two workflows - pick what fits your needs:

Option 1: Spec-First (New Project)

# Create a specification
mkdir my-app && cd my-app
bangstack init

# Validate the spec
bangstack validate

# Implement in YOUR chosen language/framework
# (Python + Flask, TypeScript + Express, Go + Gin, etc.)

# Validate implementation matches spec
bangstack check-alignment

Option 2: Code-First (Existing Project)

# Add bangstack to existing project
cd existing-app
bangstack init

# Discover what's already implemented
bangstack check-alignment --discover --apply

# Now bang.yaml reflects your actual implementation
bangstack validate

Experimental: TypeScript Code Generation

⚠️ EXPERIMENTAL FEATURE - Code generation is exploratory and not the production workflow.

Production approach: Write code by hand in your preferred language/framework, then validate with Bangstack.

# [EXPERIMENTAL] Generate TypeScript code as a reference implementation
bangstack generate

# Build and test
npm run build
npm test

See src/experimental/generators for generator implementation.

Want a guided tutorial? See docs/TUTORIAL.md for a complete walkthrough!

Research-First Development (NEW in v1.8.0)

Your specification IS your research artifact.

Bangstack now supports research-first development - a methodology that challenges you to think deeply about your solution before implementing it. Define success criteria, design principles, and user personas directly in your bang.yaml specification.

Start with Research

# Initialize new project with research sections
bangstack init my-app --with-research

This generates a comprehensive research framework in your bang.yaml:

• Success Philosophy: What does "done" mean? Define vision, success criteria, and measurable outcomes
• Design Philosophy: Why does this experience feel right? Document principles and emotional journeys
• Personas: Who is this for? Create detailed user archetypes with pain points, goals, and trust factors
• Enhanced Journeys: Map user flows with emotional arcs, delight moments, and failure modes

Why Research-First?

Traditional approach:

Build → Launch → Hope someone uses it → Realize you built the wrong thing

Research-first approach:

Research → Define success → Design experience → Build with clarity → Validate hypothesis

The Three Pillars

1. Success Philosophy - Define what "winning" means

success_philosophy:
  vision: "What change are you creating?"
  user_success_definition: "When does a user succeed?"
  success_criteria:
    - metric: "Validation completion rate"
      target: ">80%"
      rationale: "Shows product is intuitive and valuable"

2. Design Philosophy - Articulate why your UX feels right

design_philosophy:
  principles:
    - name: "Calm Confidence"
      description: "Reduce anxiety, increase clarity"
      manifests_as:
        - "Soft color palette"
        - "Clear next steps"

3. Persona-Driven Journeys - Know exactly who you're building for

personas:
  - id: technical_founder
    name: "Sarah, Technical Founder"
    pain_points:
      - "Don't know which idea has best chance"
      - "Scared of wasting 6 months building"

Evolution Over Time

Your research evolves as you learn:

success_philosophy:
  status: hypothesis        # → learning → validated
  hypothesis:
    problem: "What you believe"
    learnings: "What you discovered"
  validated_insights:
    - "Actual findings after user testing"

Example: ValidateStack

See test-apps/validatestack for a complete example:

• RESEARCH.md - 68-page comprehensive research document
• DESIGN_SYSTEM.md - Complete design system with components, colors, and interaction patterns
• bang.yaml - Research integrated into the specification

Key artifacts:

• 3 detailed personas (technical founder, non-technical founder, repeat entrepreneur)
• 4 core design principles with emotional journeys
• Enhanced journeys with user thoughts at each step
• Success metrics tied to PMF indicators

Learn More

• Research-First Philosophy - Complete methodology guide
• ValidateStack Case Study - Real-world example

The goal: Ensure every app built with Bangstack has clear success criteria, thoughtful design, and deep understanding of its users - before a single line of implementation code is written.

Claude Code Hooks Integration

Automatic spec-first reminders for AI assistants.

Bangstack projects can use Claude Code hooks to automatically remind AI assistants to consult bang.yaml before making changes:

• SessionStart Hook: Shows Bangstack context when session begins
• UserPromptSubmit Hook: Reminds to check spec before processing requests
• PostToolUse Hook: After code changes, suggests updating spec and checking alignment

Quick Setup

# Copy hooks configuration to your Bangstack project
cp .claude/settings.json .claude/

# Hooks will automatically:
# - Remind Claude to read bang.yaml before changes
# - Suggest spec updates after implementation
# - Prompt alignment checks after editing actions/models

Example hook output:

⚠️ REMINDER: This is a Bangstack project. Before making changes:
1. Consult bangstack.yaml to understand current spec
2. Check if changes should update the spec
3. After implementation, verify spec-code alignment

See Hooks Guide for complete documentation and advanced configurations.

CLI Commands

Core Commands

bangstack init [directory] - Create a new Bangstack project

bangstack init my-app
bangstack init --ai               # AI-assisted project setup
bangstack init --with-research    # Include research-first development sections

bangstack validate [file] - Validate a specification file

bangstack validate            # Validates bang.yaml
bangstack validate my-spec.yaml

bangstack generate [file] - [EXPERIMENTAL] Generate code from specification

bangstack generate
bangstack generate --use-ai   # AI-powered generation
bangstack generate --dry-run  # Preview without writing files

⚠️ EXPERIMENTAL: Code generation is exploratory. Production workflow is to write code by hand, then validate with bangstack.

bangstack check-alignment [file] - Check YAML ↔ Code ↔ Docs alignment

bangstack check-alignment                    # Ensures spec matches reality
bangstack check-alignment --discover         # Show undeclared implementations
bangstack check-alignment --discover --apply # Auto-fix spec alignment ✨ NEW!

The --discover flag finds code that exists but isn't documented in your spec. The --apply flag automatically adds missing entries to keep your spec in sync.

Analysis Commands

bangstack ask <question> - Ask AI about your application ✨ NEW!

# Set your API key first (or use .env file)
export ANTHROPIC_API_KEY=your-key-here

# Ask questions about your application
bangstack ask "What can users do in this app?"
bangstack ask "How does authentication work?"
bangstack ask "Is the payment service implemented?"
bangstack ask "What happens if payment fails?"

# Use verbose mode for details
bangstack ask "What are all the actors?" --verbose

The ask command uses AI to answer questions about your application based on your bang.yaml specification. Features:

• 🔄 Live progress indicators - See loading spinners while AI analyzes
• 📊 Verbose mode - Token usage and detailed stats with --verbose
• 🎯 Gap detection - AI identifies missing documentation
• ⚡ Fast responses - Typically 3-10 seconds

Perfect for:

• Onboarding new team members
• Understanding complex flows
• Validating your specification is complete
• Finding gaps in documentation

bangstack status [file] - Show project statistics

bangstack status              # Show implementation progress

Development Commands

bangstack dev [file] - [EXPERIMENTAL] Development mode with hot reload

bangstack dev                 # Watch for changes and regenerate

⚠️ EXPERIMENTAL: Current implementation is a code generation watcher. Planned: Validation orchestrator with live TUI dashboard showing 5-level pyramid status.

bangstack migrate [file] - Migrate specification to new schema version

bangstack migrate --to 1.2.0  # Upgrade to v1.2.0 schema

Validation Levels

Bangstack validates your implementation through 4 progressive levels:

Level 1: Existence Validation (< 1s)

• ✅ Files declared in file_path exist
• ✅ Actions with status: implemented have corresponding files
• ✅ Actions with status: planned don't have files yet

What you add to spec:

actions:
  - name: CreateUser
    file_path: "src/users/create.py"

What you implement: File just needs to exist. Any structure, any framework.

Level 2: Protocol Validation (5-15s) ⚡ NEW in v2.0

• ✅ HTTP endpoints exist at declared paths
• ✅ Request/response contracts match
• ✅ CLI commands accept declared arguments

What you add to spec:

actions:
  - name: CreateUser
    protocol:
      type: http
      method: POST
      path: /api/users
      request:
        body:
          email: {type: string, required: true}
      response:
        status: 201

What you implement: Endpoint at correct path. Flask, FastAPI, Express - your choice.

Level 3: Test-Based Validation (10-60s)

• ✅ Tests verify input/output contracts
• ✅ Tests use bangstack helpers for validation

What you add to spec:

actions:
  - name: CreateUser
    test_file: "tests/actions/test_create_user.py"

What you implement: Tests that import bangstack helpers (your code never imports bangstack).

Level 4: E2E Journey Validation (1-5m)

• ✅ Complete user journeys execute successfully
• ✅ Multi-step workflows verified end-to-end

What you add to spec:

journeys:
  - name: User signs up
    test_file: "tests/e2e/test_signup_journey.py"

Progressive adoption: Start with Level 1 (existence), add validation as you grow.

Reference implementation: See examples/validation-showcase for a complete fullstack application demonstrating all 5 validation levels with zero warnings, automated server management, and browser E2E testing.

Automation-First: Journeys as Executable Workflows (v2.0 Vision)

Current state: Most tools treat "user journeys" as documentation - flowcharts showing what users can do.

Bangstack vision: Journeys are executable workflows - the spec orchestrates your application logic.

The Paradigm Shift

Traditional approach:

User Journey (documentation) → Developer reads → Manually implements logic

Bangstack automation-first:

User Journey (executable spec) → Bangstack orchestrator → Automatically executes workflow

How It Works

Define a journey in bang.yaml:

journeys:
  - name: Founder Validates SaaS Idea
    actor: founder
    steps:
      - step: 1
        action: SubmitValidation
        description: "User submits idea"

      - step: 2
        action: GatherMarketData
        description: "System collects market data (automated)"

      - step: 3
        action: ReviewValidationData
        actor: admin
        description: "Admin reviews data (manual approval)"

      - step: 4
        action: GenerateReport
        description: "AI generates report (automated, triggered by approval)"

      - step: 5
        action: NotifyUser
        description: "Email user with results (automated)"

Bangstack orchestrator executes this as a state machine:

• Automated steps execute sequentially without human intervention
• Manual steps pause the workflow until approval/completion
• State tracked throughout - every journey instance has status, current step, outputs
• Failures handled gracefully - retry logic, fallbacks, error recovery from spec

Key Benefits

1. Consistency

• Every journey execution follows exact same steps
• No manual implementation drift
• Reproducible results

2. Observability

• Track journey progress in real-time
• See exactly which step failed
• Measure bottlenecks (avg duration per step)

3. Flexibility

• Change journey in spec → behavior updates automatically
• Add conditional steps, parallel execution, retries
• A/B test different journey flows

4. Testability

// Test entire journey without mocking
await orchestrator.startJourney("Founder Validates SaaS Idea", inputs);
await journey.waitForCompletion();
expect(journey.status).toBe("completed");

Advanced Features (v2.0 Roadmap)

Parallel Execution:

- step: 3
  parallel_group: "data_collection"
  actions:
    - GatherMarketData
    - AnalyzeCompetitors
    - EvaluateSeoOpportunity
  wait_for_all: true

Conditional Steps:

- step: 7
  action: ReviewValidationData
  condition: "confidence_score < 0.85"  # Only manual review if confidence low
  skip_if: "confidence_score >= 0.85"
  skip_action: AutoApproveValidation

Retry & Failure Modes:

- step: 3
  action: GatherMarketData
  timeout: 30s
  retry:
    max_attempts: 3
    backoff: exponential
  fallback_action: UseBasicMarketData

Cross-Journey Triggers:

journeys:
  - name: Validate Idea
    on_completion:
      - action: CheckUserQuota
        if_quota_exceeded:
          trigger_journey: "Upgrade to Paid Plan"

Manual Steps in Automated Flows

A key insight: Manual steps aren't failures of automation - they're intentional pause points.

Example: Admin approval in ValidateStack

• Steps 1-6 execute automatically (data collection)
• Step 7 pauses at admin review (manual quality check)
• Admin clicks "Approve" → Steps 8-9 execute automatically (report generation, notification)

Why this matters:

• Early stage: High manual review rate (learning phase)
• As confidence grows: Conditional auto-approval (85%+ confidence)
• Eventually: Mostly automated, manual review for edge cases only

This is gradual automation, codified in the spec.

CLI Commands (v2.0)

# Start a journey
bangstack journey start "Validate Idea" --input '{"idea": "AI project management"}'

# Check status
bangstack journey status val_abc123

# Approve manual step
bangstack journey approve val_abc123

# View all journeys in progress
bangstack journey list --status in_progress

# Journey analytics
bangstack journey analytics "Validate Idea"
# Shows: completion rate, avg duration per step, bottlenecks

Why This Is Powerful

Example: ValidateStack

Without automation-first:

• Implement validation logic in backend code
• Manually coordinate 9 steps
• Add admin approval somewhere
• Hope everything executes in order
• Debug by reading logs

With automation-first:

• Define 9-step journey in bang.yaml
• Bangstack orchestrator handles execution order
• Admin approval is explicit step 7
• State tracked automatically
• Debug by viewing journey instance state

The result: Your specification literally runs your application. Change the spec, change the behavior.

Status: Automation-first is the v2.0 vision. v1.x proves the spec-first concept, v2.0 makes specs executable.

Current Status

v1.x - Validation-First (Production) (Current)

• ✅ Complete YAML schema for application description
• ✅ Level 1 validation (existence + alignment)
• ✅ Spec-code synchronization
• ✅ AI-powered spec querying
• ✅ Research-first development workflow
• 🧪 TypeScript code generators (experimental, see src/experimental/generators)

v2.0 - Multi-Language Validation (In Development)

• 🔨 Level 2: Protocol validation (HTTP/CLI/gRPC contracts)
• 🔨 Level 3: Test-based validation helpers
• 🔨 Level 4: E2E journey validation
• 🔨 Language SDKs (Python, TypeScript, Go, Ruby)
• 🔨 Journey orchestration (automation-first development)

The Philosophy: Bangstack is validation-first: Write code freely in ANY language/framework, validate it matches your spec. Generation exists as an exploratory tool for prototyping, but production workflow is validation-focused.

See ROADMAP.md for the v1.x → v2.0 transition plan.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

# Development mode (watch for changes)
npm run dev

Keeping bangstack.yaml in Sync

Bangstack uses its own alignment checks to keep bangstack.yaml as the source of truth:

# Check if bangstack.yaml matches actual code
npm run check-spec

# Auto-fix bangstack.yaml when implementations are found
npm run sync-spec

How it works:

• Build/Test: npm run build and npm test automatically check alignment (warns but doesn't block)
• Auto-Fix: npm run sync-spec discovers undocumented generators, actions, docs, AND missing changelog entries, then adds them automatically
• Version Bumps: npm version patch/minor/major automatically generates changelog skeleton entries
• Pre-Commit: Husky hook blocks commits if spec is out of sync OR changelog is incomplete
• CI/CD: GitHub Actions blocks PRs if bangstack.yaml drifts from code

This ensures bangstack's spec stays accurate as the project evolves - the tool dogfoods its own alignment philosophy.

Changelog Enforcement: Every version bump automatically generates a skeleton changelog entry:

• Extracts version info from git tags
• Uses current date if tag doesn't exist yet
• Adds placeholder "TODO: Add changelog notes"
• Blocks commits if changelog is incomplete (unless --no-verify)

# Version bump automatically updates changelog
npm version patch  # Creates v1.6.3 entry automatically

# Or manually sync if you forgot
npm run sync-spec  # Auto-generates missing changelog entries

Excluding folders: To exclude certain directories from alignment checks (e.g., test apps, deprecated code), add them to bangstack.yaml:

excluded_paths:
  - v0-generators/
  - test-apps/
  - test-configs/
  - examples/

These paths will be ignored by both discovery and alignment checks.

Project Structure

bangstack/
├── src/
│   ├── core/              # Core abstractions
│   │   ├── generator.ts   # Base generator interface
│   │   ├── context.ts     # Generation context tracking
│   │   ├── graph.ts       # Dependency graph
│   │   └── registry.ts    # Component registry
│   ├── experimental/      # Experimental features
│   │   ├── generators/    # [EXPERIMENTAL] Code generators
│   │   │   ├── model-generator.ts
│   │   │   ├── action-generator.ts
│   │   │   ├── test-generator.ts
│   │   │   ├── component-generator.ts
│   │   │   └── observability-generator.ts
│   │   └── commands/      # Experimental commands
│   │       └── dev.ts     # Dev mode watcher
│   ├── plugins/           # Plugin system
│   │   ├── plugin-loader.ts
│   │   └── manifest-parser.ts
│   ├── migration/         # Schema migration engine
│   │   └── migration-engine.ts
│   └── utils/             # Utilities
│       ├── schema.ts      # Zod schema definitions
│       ├── schema-versions.ts
│       └── schema-doc-generator.ts
├── examples/              # Example specifications
├── docs/                  # Documentation
│   └── adr/              # Architecture decision records
└── tests/                 # Integration tests

Architecture

Bangstack separates concerns:

┌─────────────────────────────────────────────────┐
│  bang.yaml (The Contract)                       │
│  ─────────────────────────                      │
│  Describes WHAT the app does:                   │
│  • Models (data structures)                     │
│  • Actions (operations)                         │
│  • Journeys (user flows)                        │
│  • Actors (who/what)                            │
└─────────────────────────────────────────────────┘
                      ↕ (Validation)
┌─────────────────────────────────────────────────┐
│  Your Implementation (The HOW)                  │
│  ──────────────────────────────                 │
│  ANY language, ANY framework:                   │
│  • Python + Flask                               │
│  • TypeScript + Express                         │
│  • Go + Gin                                     │
│  • Ruby + Rails                                 │
│  • etc.                                         │
└─────────────────────────────────────────────────┘

Key Principles:

1. Spec is the source of truth (WHAT)
2. Implementation is completely free (HOW)
3. Validation ensures they match
4. Tests are the bridge (import bangstack, verify contracts)

v1.x Architecture (Validation-First):

• Progressive validation levels (existence → protocol → tests → E2E)
• Language-agnostic specification validation
• Spec-code alignment checking
• Optional experimental generators in src/experimental/generators

See Architecture Decision Records for detailed design decisions.

Example Specification

name: todo-app
version: 1.0.0
description: A simple todo application
type: api

versioning:
  strategy: semver
  current: 1.0.0
  schema_version: 1.0.0

models:
  - name: Todo
    fields:
      - name: id
        type: string
        required: true
      - name: title
        type: string
        required: true
      - name: completed
        type: boolean
        required: true

actions:
  - name: CreateTodo
    type: command
    inputs:
      - name: title
        type: string
    returns: Todo
    observability:
      log_level: info
      trace: true

Documentation

• ROADMAP.md - Development roadmap and milestones
• SCHEMA_REFERENCE.md - Complete schema documentation
• ADR-001: Schema Versioning
• ADR-002: Documentation Generation

Technology Stack

• CLI: Commander.js
• Validation: Zod
• YAML: yaml
• AST Manipulation: ts-morph
• Testing: Vitest
• AI: Anthropic SDK (optional)

Contributing

Bangstack is in active development. Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

Status

v1.9.x - Validation-first architecture (current, stable) v2.0.0 - Multi-language validation with protocol testing (in development)

Bangstack v1.x is production-ready for validation-first development. v2.0 will bring protocol validation (Level 2) and multi-language SDKs.

Experimental generators available in src/experimental/generators for prototyping.

Star this repo to follow our progress!

Test pre-push hook