llm-workflow

A complete prompt library and workflow system for bootstrapping LLM-driven projects.

Run a single command, answer an interview, and get a fully structured project — spec, tasks, workflows, architecture, and scaffold — in minutes. Works with any tech stack, any project structure, and any deployment target.

Why llm-workflow?

Building with LLMs is powerful, but projects quickly become unstructured — scattered prompts, undocumented decisions, no task tracking, and inconsistent workflows.

llm-workflow gives you a battle-tested operating system for LLM-driven development:

• Structured bootstrapping — An interview-driven process that discovers your domain, stack, and constraints before generating anything
• Works with any setup — Monorepo, single project, or existing codebase. Any language, any framework, any deployment target
• Spec-as-authority — Goals, non-goals, decisions, and safety rules live in versioned files that govern all LLM behavior
• Milestone-driven execution — Tasks are scoped to milestones with test gates, acceptance criteria, and progress tracking
• Prompt-as-infrastructure — LLM prompts are versioned files with a fragment system, schema validation, and optional DB registry
• Daily workflow prompts — Copy-paste prompts that keep your LLM sessions focused and productive

Quick start

Install via npx (recommended)

npx llm-workflow init

This will:

1. Ask where to set up (current directory or a new one)
2. Copy the blueprint/ prompt library into your project
3. Optionally create the initial folder structure (spec/, tasks/, workflow/, etc.)
4. Print your next steps

Options:

npx llm-workflow init ./my-project       # setup in a specific directory
npx llm-workflow init -y                  # non-interactive, full scaffold
npx llm-workflow init --blueprint-only    # just the prompt library, no folders
npx llm-workflow --help                   # all options

Or copy manually

git clone https://github.com/asadighi/llm-workflow.git
cp -r llm-workflow/blueprint/ /path/to/your-project/blueprint/

Or browse directly

Use the blueprint/ folder as a reference and adapt templates to your workflow.

How it works

Phase 1: Bootstrap interview

Open an LLM session and paste blueprint/00-BOOTSTRAP_INTERVIEW_PROMPT.md. The LLM will interview you:

| Section | What it discovers | |---------|-------------------| | Domain + product shape | What does it do? Who are the users? Top workflows? | | Constraints + risk | Security? Safety risks? Uncertainty behavior? | | Data + integrations | Core entities? External systems? Source of truth? | | Project structure + tech | Greenfield or existing? Monorepo or single project? Language, framework, DB? | | Deployment | Existing pipeline? Need recommendations? Or handling it yourself? | | LLM + model behavior | Which tasks are model-driven? Dedicated AI package or embedded? | | Testing + delivery | Test strategy? CI? Definition of done? |

The LLM adapts to your answers — it doesn't prescribe a monorepo, a specific framework, or a deployment platform.

Phase 2: Scaffold generation

When you say "generate the scaffold now", the LLM generates what you need:

your-project/
├── spec/                        # project specification (authoritative)
│   ├── readme.md                # authority order + how to use
│   ├── goals.md                 # what success looks like
│   ├── non-goals.md             # explicit exclusions
│   ├── decisions.md             # binding decisions (append-only)
│   ├── changelog.md             # spec change history
│   ├── master-project-plan.md   # milestones + task breakdown
│   ├── tests.md                 # test strategy + regression gates
│   ├── llm-system-prompt.md     # LLM behavior constraints
│   ├── prompt-schemas.md        # JSON schemas for LLM outputs
│   └── llm-context-loading.md   # which files to load per task type
│
├── workflow/                    # execution workflow prompts
│   ├── 00-start.md              # router — decides what to do next
│   ├── 01-pick-next-task.md     # propose + confirm next task
│   ├── 02-execute-current-focus.md
│   ├── 03-wrap-up-current-focus.md
│   ├── 04-unblock-me.md
│   ├── 05-run-tests.md
│   ├── 06-milestone-check.md
│   └── 07-progress-report.md
│
├── tasks/                       # milestone + task tracking
│   ├── readme.md                # task system rules
│   ├── tasks-index.md           # current milestone + focus task
│   └── tasks-milestone-*.md     # per-milestone task files
│
├── architecture/                # system architecture docs
│   ├── architecture-overview.md
│   ├── tech-stack.md
│   ├── data-persistence.md
│   ├── auth-and-security.md
│   ├── deployment-hosting.md
│   └── llm-integration.md
│
├── docs/                        # standards
│   ├── logging-observability.md
│   └── fixtures-and-evals.md
│
├── [project scaffold]           # adapted to YOUR structure
│                                # monorepo, single project, or
│                                # integration guide for existing codebases
│
└── blueprint/                   # ← this prompt library (reference)

Phase 3: Daily execution

Use the workflow prompts for structured daily sessions:

"Run the router described in workflow/00-start.md
 and tell me which workflow file to run next."

See blueprint/09-ITERATION_WORKFLOWS.md for all copy-paste prompts.

Workflow visualization

Bootstrap flow

flowchart TD
    A["npx llm-workflow init"] --> B[Copy blueprint/ into project]
    B --> C[Start LLM session]
    C --> D[Paste 00-BOOTSTRAP_INTERVIEW_PROMPT.md]
    D --> E{Interview\n28 questions}
    E --> F["Say: generate the scaffold now"]
    F --> G[LLM generates spec pack]
    G --> H[LLM generates workflow pack]
    H --> I[LLM generates tasks pack]
    I --> J[LLM generates architecture docs]
    J --> K{Project type?}
    K -->|Greenfield| L[Generate project scaffold]
    K -->|Existing| M[Generate integration guide]
    L --> N{Deployment?}
    M --> N
    N -->|User wants it| O[Generate deployment config]
    N -->|User handles it| P[Skip deployment]
    O --> Q[Done — approve & start building]
    P --> Q

    style A fill:#e1f5fe
    style Q fill:#c8e6c9
    style E fill:#fff3e0
    style K fill:#fff3e0
    style N fill:#fff3e0

Daily execution loop

flowchart TD
    START[Start session] --> ROUTER[00-start.md\nRouter]
    ROUTER --> DECISION{What needs\ndoing?}

    DECISION -->|blocked| UNBLOCK[04-unblock-me.md]
    DECISION -->|task done| WRAP[03-wrap-up-current-focus.md]
    DECISION -->|tests needed| TEST[05-run-tests.md]
    DECISION -->|milestone done?| MILE[06-milestone-check.md]
    DECISION -->|has focus task| EXEC[02-execute-current-focus.md]
    DECISION -->|no focus task| PICK[01-pick-next-task.md]

    UNBLOCK --> ROUTER
    WRAP --> TEST
    TEST -->|pass| MILE
    TEST -->|fail| FIX[Create fix tasks] --> PICK
    MILE -->|complete| REPORT[07-progress-report.md]
    MILE -->|not ready| PICK
    EXEC --> WRAP
    PICK --> EXEC

    REPORT --> DONE[End session]

    style START fill:#e1f5fe
    style DONE fill:#c8e6c9
    style DECISION fill:#fff3e0

Authority hierarchy

flowchart TD
    GOALS[goals.md] --> NONGOALS[non-goals.md]
    NONGOALS --> DECISIONS[decisions.md]
    DECISIONS --> CHANGELOG[changelog.md]
    CHANGELOG --> PLAN[master-project-plan.md]
    PLAN --> TESTS[tests.md]
    TESTS --> SYSPROMPT[llm-system-prompt.md]
    SYSPROMPT --> SCHEMAS[prompt-schemas.md]
    SCHEMAS --> CONTEXT[llm-context-loading.md]

    GOALS -.->|overrides all| CONTEXT

    subgraph "/spec (authoritative)"
        GOALS
        NONGOALS
        DECISIONS
        CHANGELOG
        PLAN
        TESTS
        SYSPROMPT
        SCHEMAS
        CONTEXT
    end

    ARCH["/architecture"] -.->|guides implementation\nbut does NOT override /spec| PLAN
    TASKS["/tasks"] -.->|derived from\nmaster-project-plan.md| PLAN

    style GOALS fill:#c8e6c9
    style NONGOALS fill:#c8e6c9
    style DECISIONS fill:#e1f5fe

Prompt-as-infrastructure

flowchart LR
    subgraph "Prompt files (git-versioned)"
        FRAG[_fragments/\nsafety_rules.md\nstyle_rules.md]
        PROMPT[tool_name/\nv1.0.0.md\nv1.1.0.md\nfragments.json]
    end

    PROMPT -->|seed script| DB[(Database\nprompt registry)]
    FRAG -->|"{{fragment:name}}"| RENDER[renderPrompt]
    DB --> RENDER
    RENDER -->|rendered prompt| LLM[LLM Provider]
    LLM -->|JSON output| VALIDATE[Schema\nvalidation]
    VALIDATE -->|pass| SERVICE[Service layer]
    VALIDATE -->|fail| ERROR[Error /\nclarification]

    style DB fill:#e1f5fe
    style LLM fill:#fff3e0
    style VALIDATE fill:#c8e6c9

Blueprint file index

| File | Purpose | |------|---------| | 00-BOOTSTRAP_INTERVIEW_PROMPT.md | Interview questions + generation protocol | | 01-OUTPUT_SCHEMAS.md | JSON schemas for project brief, milestones, tasks, scaffold plan | | 02-SPEC_PACK_TEMPLATE.md | Full structural templates for every /spec file | | 03-WORKFLOW_PROMPTS_TEMPLATE.md | Templates for /workflow routing + execution prompts | | 04-TASKS_AND_MILESTONES_TEMPLATE.md | Full structural templates for tasks system (states, rules, editing) | | 05-PROJECT_SCAFFOLD_PROMPT.md | Project scaffold — monorepo, single project, or existing codebase integration | | 06-LOGGING_OBSERVABILITY_STANDARD.md | Structured logging, correlation IDs, redaction, prompt IO logging | | 07-FIXTURES_AND_EVAL_STANDARD.md | Fixture types, naming, rules, eval harness | | 08-MCP_PACKAGE_GUIDE.md | AI/MCP package design, prompt management system | | 09-ITERATION_WORKFLOWS.md | Copy-paste prompts for daily LLM sessions | | 10-ARCHITECTURE_TEMPLATE.md | Full structural templates for /architecture docs | | 11-DEPLOYMENT_GUIDE.md | Platform-agnostic deployment guide with appendices |

Design principles

| Principle | Description | |-----------|-------------| | No assumptions | Discovers your stack, structure, and deployment through the interview | | Authority order | goals → non-goals → decisions → architecture → tests → tasks → workflows | | No hidden state | Decisions in /spec/decisions.md, changes logged in /spec/changelog.md | | Taskification | Milestones define outcomes + test gates; tasks define acceptance criteria | | Observability-first | Prompt inputs/outputs logged with redaction rules | | Prompt-as-infrastructure | Prompts versioned as files, rendered via fragments, tested via fixtures | | Spec overrides all | /spec always wins over /tasks or /architecture | | Major decision gate | LLM stops and asks before making undecided architectural choices |

Works with any setup

| Dimension | Supported options | |-----------|-------------------| | Project type | Greenfield, existing codebase, monorepo, single project | | Languages | TypeScript, Python, Go, Java, Rust, or any language | | Frontend | Next.js, Vite, SvelteKit, Nuxt, mobile, CLI, API-only, or none | | Backend | Express, Fastify, Nest, FastAPI, Django, Spring, Go, or any framework | | Database | Postgres, MySQL, SQLite, MongoDB, DynamoDB, or any database | | Deployment | Docker, Vercel, Fly.io, AWS, GCP, Railway, Kubernetes, or self-managed | | Monorepo tooling | npm workspaces, pnpm, yarn, Nx, Turborepo, Bazel, or none | | LLM provider | OpenAI, Anthropic, local models, or provider-agnostic | | CI/CD | GitHub Actions, GitLab CI, Jenkins, existing pipeline, or none |

Integration patterns

With Cursor

1. Run npx llm-workflow init in your project
2. Add blueprint/ as context (drag folder into chat or use @blueprint)
3. Paste the bootstrap interview prompt
4. Use workflow prompts for daily sessions

With ChatGPT / Claude

1. Copy the contents of blueprint/00-BOOTSTRAP_INTERVIEW_PROMPT.md
2. Paste into a new conversation
3. Answer the interview, then say "generate the scaffold now"
4. Copy generated files into your project

With GitHub Copilot

1. Run npx llm-workflow init in your project
2. Reference specific templates via #file:blueprint/02-SPEC_PACK_TEMPLATE.md
3. Use Copilot Chat for interview and generation

Existing enterprise codebase

1. Run npx llm-workflow init in your project root
2. During the interview, explain your existing project structure, build system, and deployment pipeline
3. The LLM will generate a spec/workflow/tasks layer that integrates with your setup — no scaffold conflicts

Contributing

Contributions are welcome! If you've found patterns that improve the workflow:

1. Fork this repo
2. Create a feature branch
3. Submit a PR with a clear description of the improvement

Areas where contributions are especially valuable:

• Additional deployment platform appendices
• Framework-specific scaffold patterns
• Additional workflow prompts for specialized tasks
• Improvements to the interview questions
• Language-specific adaptations

License

MIT — use it, fork it, ship it.