flowspec

KO | EN

gitlite — search

#react #ai #typescript #machine-learning #deep-learning #linux #macos #awesome #cli #awesome-list #pytorch #mcp #openai #open-source

(★ 50)

flowspec is a deliberate implementation of spec-kit & backlog md with task memory

flowspec Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
    <img src="./images/flowspec.png"/>
    <h1>flowspec</h1>
    <h3><em>Spec-Driven Development with AI-Powered Task Management</em></h3>
</div>

<p align="center">
    <strong>Plan features with specialized AI agents. Track tasks with backlog.md + beads. Ship with confidence.</strong>
</p>

---

## What is flowspec?

flowspec transforms how you build software with AI. Instead of giving AI loose instructions, you give it **structured specifications** and **tracked tasks**. Each `/flowspec` command launches specialized AI agents that:

1. **Read** existing specifications and tasks
2. **Create** the right artifacts for each phase
3. **Track** progress in your backlog
4. **Commit** with proper formatting and validation

## Quick Start

### Installation

```bash
# Install flowspec CLI
uv tool install flowspec-cli --from git+https://github.com/jpoley/flowspec.git

# Initialize your project (prompts to install backlog.md + beads if missing)
flowspec init my-project --ai claude
cd my-project
```

> **Note:** During `flowspec init`, you'll be prompted to install:
> - **backlog.md** - task management
> - **beads** - issue tracking for AI agents

### Establish Principles (Optional but Recommended)

```bash
/flow:init   # Creates constitution with project principles
```

### Assess Your Feature

```bash
/flow:assess Build a REST API for task management with JWT authentication
```

### Run the Appropriate Workflow

**For Full SDD (complex features):**
```bash
/flow:specify Build a REST API for task management with JWT authentication
/flow:plan
/flow:implement
/flow:validate
```

**For Light/Medium (medium features):**
```bash
/flow:specify Build a new user settings page
/flow:implement
```

**For Simple tasks:**
```bash
# Just create a task and implement
backlog task create "Fix login button alignment" --ac "Button aligns with form fields"
# Then code directly
```

## Choose Your Workflow Mode

```
┌────────────────────────────────────────────────────────────────────────┐
│                        WORKFLOW MODE SELECTION                          │
├────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐              │
│  │   SIMPLE    │     │   MEDIUM    │     │   COMPLEX   │              │
│  │  (Score 8-12)│     │ (Score 13-20)│    │ (Score 21+) │              │
│  └──────┬──────┘     └──────┬──────┘     └──────┬──────┘              │
│         │                   │                   │                      │
│         ▼                   ▼                   ▼                      │
│    Skip SDD           Light/Medium            Full SDD                 │
│    Just code          Quick specs             All phases               │
│                                                                         │
│  Examples:            Examples:               Examples:                 │
│  • Bug fix            • New endpoint          • New auth system         │
│  • Config change      • UI component          • Payment integration     │
│  • Doc update         • Small feature         • Major refactor          │
│                                                                         │
└────────────────────────────────────────────────────────────────────────┘
```

### Quick Decision: Run `/flow:assess` first

```bash
/flow:assess Build a REST API with user authentication
```

This scores your feature across 8 dimensions and recommends: **Skip SDD**, **Light/Medium**, or **Full SDD**.

## Workflow Modes Explained

All modes produce the same artifacts - only the **review depth** changes:

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           WORKFLOW MODES                                 │
├───────────┬─────────────────────────┬───────────────────────────────────┤
│   MODE    │    ARTIFACTS PRODUCED   │         REVIEW APPROACH           │
├───────────┼─────────────────────────┼───────────────────────────────────┤
│   FULL    │ PRD                     │ Deep review at each stage         │
│           │ Functional Spec         │ Explicit approval gates           │
│           │ Technical Spec          │ Formal ADRs                       │
│           │ ADRs                    │ Multi-reviewer sign-off           │
│           │ Code + Tests            │                                   │
│           │ Runbook                 │                                   │
├───────────┼─────────────────────────┼───────────────────────────────────┤
│  MEDIUM   │ PRD                     │ Quick review                      │
│           │ Functional Spec         │ Proceed unless issues found       │
│           │ Technical Spec          │ Combined passes allowed           │
│           │ ADRs                    │ Single reviewer OK                │
│           │ Code + Tests            │                                   │
│           │ Runbook                 │                                   │
├───────────┼─────────────────────────┼───────────────────────────────────┤
│   LIGHT   │ PRD                     │ Minimal review                    │
│           │ Functional Spec         │ Trust the process                 │
│           │ Technical Spec          │ Decision notes (not full ADRs)    │
│           │ ADRs                    │ Fast iteration                    │
│           │ Code + Tests            │                                   │
│           │ Runbook                 │                                   │
└───────────┴─────────────────────────┴───────────────────────────────────┘

Light mode is NOT an excuse to skip artifacts. It's permission to move faster.
```

## The Workflow: Commands → Artifacts → States

```
┌────────────────────────────────────────────────────────────────────────────────┐
│                        FLOWSPEC WORKFLOW STATE MACHINE                          │
├────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   COMMAND              STATE                ARTIFACTS PRODUCED                  │
│   ───────              ─────                ─────────────────                   │
│                                                                                 │
│   (start)          ┌──────────┐                                                │
│                    │  To Do   │            (none)                               │
│                    └────┬─────┘                                                 │
│                         │                                                       │
│                         ▼                                                       │
│   /flow:assess   ┌──────────┐            • [feature]-assessment.md            │
│                    │ Assessed │            • Complexity scoring                 │
│                    └────┬─────┘                                                 │
│                         │                                                       │
│                         ▼                                                       │
│   /flow:specify  ┌──────────┐            • [feature]-prd.md                   │
│                    │Specified │            • Implementation tasks               │
│                    └────┬─────┘                                                 │
│                         │                                                       │
│                         ▼                                                       │
│   /flow:plan     ┌──────────┐            • [feature]-technical.md             │
│                    │ Planned  │            • adr-XXX-[topic].md                 │
│                    └────┬─────┘            • Platform design docs               │
│                         │                                                       │
│                         ▼                                                       │
│   /flow:implement┌──────────┐            • Source code (src/)                 │
│                    │   In     │            • Unit & integration tests           │
│                    │Progress  │            • API documentation                  │
│                    └────┬─────┘                                                 │
│                         │                                                       │
│                         ▼                                                       │
│   /flow:validate ┌──────────┐            • QA reports                         │
│                    │Validated │            • Security scan results              │
│                    └────┬─────┘            • Test coverage reports              │
│                         │                                                       │
│                         ▼                                                       │
│                    ┌──────────┐                                                │
│                    │   Done   │                                                 │
│                    └──────────┘                                                 │
│                                                                                 │
│   Note: /flow:research (optional) can be run after Specified → Researched     │
│         before proceeding to /flow:plan                                        │
│                                                                                 │
└────────────────────────────────────────────────────────────────────────────────┘
```

## Command Reference

```
┌────────────────────────────────────────────────────────────────────────────────┐
│                           FLOWSPEC COMMAND REFERENCE                            │
├──────────────────┬───────────────┬────────────────┬────────────────────────────┤
│     COMMAND      │  INPUT STATE  │  OUTPUT STATE  │     PRIMARY AGENTS         │
├──────────────────┼───────────────┼────────────────┼────────────────────────────┤
│ /flow:assess   │ To Do         │ Assessed       │ Workflow Assessor          │
│ /flow:specify  │ Assessed      │ Specified      │ PM Planner                 │
│ /flow:research │ Specified     │ Researched     │ Researcher, Validator      │
│ /flow:plan     │ Specified*    │ Planned        │ Architect, Platform Eng    │
│ /flow:implement│ Planned       │ In Progress    │ Frontend/Backend Engineers │
│ /flow:validate │ In Progress   │ Validated      │ QA, Security Engineers     │
└──────────────────┴───────────────┴────────────────┴────────────────────────────┘
* Also accepts "Researched" state
  /flow:research is optional - can skip directly from Specified to /flow:plan
```

## Artifact Progression

Every feature follows this document progression:

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                          ARTIFACT PROGRESSION                                 │
│                                                                               │
│   Assessment ──► PRD ──► Technical ──► ADR ──► Code + Tests                  │
│                           Spec                                                │
│                                                                               │
│   "Is SDD      "What &    "How to      "Why this   Working                   │
│    needed?"     Why"       build"       path"      software                   │
│                                                                               │
└──────────────────────────────────────────────────────────────────────────────┘
```

| Stage | Artifact | Question Answered | Location |
|-------|----------|-------------------|----------|
| 1 | **Assessment** | Is SDD appropriate, what's the complexity | `docs/assess/` |
| 2 | **PRD** | What must it do and why the user cares | `docs/prd/` |
| 3 | **Technical Spec** | How will we build it | `docs/specs/` |
| 4 | **ADR** | Why we chose this technical path | `docs/adr/` |
| 5 | **Implementation** | The code and tests | `src/`, `tests/` |

### Document Naming

| Document | Pattern | Example |
|----------|---------|---------|
| Assessment | `[feature]-assessment.md` | `user-auth-assessment.md` |
| PRD | `[feature]-prd.md` | `user-auth-prd.md` |
| Technical Spec | `[feature]-technical.md` | `user-auth-technical.md` |
| ADR | `adr-[number]-[topic].md` | `adr-015-auth-provider.md` |

## Working with Tasks

```bash
# View kanban board
backlog board

# List tasks (AI-friendly)
backlog task list --plain

# Start work on a task
backlog task edit 42 -s "In Progress" -a @myself

# Check off acceptance criteria as you work
backlog task edit 42 --check-ac 1
backlog task edit 42 --check-ac 2

# Complete task
backlog task edit 42 -s Done
```

## Implementation = Code + Docs + Tests

Every `/flow:implement` produces **three mandatory deliverables**:

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    IMPLEMENTATION DELIVERABLES                           │
├─────────────────┬─────────────────────┬─────────────────────────────────┤
│   DELIVERABLE   │    DESCRIPTION      │        VERIFICATION             │
├─────────────────┼─────────────────────┼─────────────────────────────────┤
│   Code          │ Production-ready    │ PR passes CI, review approved   │
│                 │ reviewed source     │                                 │
├─────────────────┼─────────────────────┼─────────────────────────────────┤
│   Documents     │ API docs, comments  │ Docs updated, comments added    │
│                 │ config examples     │                                 │
├─────────────────┼─────────────────────┼─────────────────────────────────┤
│   Tests         │ Unit, integration   │ Test suite passes               │
│                 │ edge cases          │ Coverage threshold met          │
└─────────────────┴─────────────────────┴─────────────────────────────────┘

Implementation is NOT complete until all three are delivered.
```

## Supported AI Agents

| Agent | Support |
|-------|---------|
| [Claude Code](https://www.anthropic.com/claude-code) | Fully supported (primary) |
| [GitHub Copilot CLI](https://githubnext.com/projects/copilot-cli/) | Fully supported |
| [Codex CLI](https://github.com/openai/codex) | Fully supported |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Fully supported |
| [Cursor](https://cursor.sh/) | Fully supported |
| [Windsurf](https://windsurf.com/) | Fully supported |

### Multi-Agent Setup

```bash
# Initialize with multiple agents
flowspec init my-project --ai claude,copilot,cursor-agent
```

## File Structure

```
project/
├── docs/
│   ├── assess/                 # Assessment reports from /flow:assess
│   ├── prd/                    # PRDs from /flow:specify
│   ├── specs/                  # Technical specs from /flow:plan
│   ├── adr/                    # Architecture Decision Records
│   ├── platform/               # Platform design docs
│   ├── qa/                     # QA reports from /flow:validate
│   └── security/               # Security scans
├── src/                        # Implementation code
├── tests/                      # Test suites
├── backlog/                    # Task management
└── memory/                     # Constitution and specs
    └── constitution.md         # Project principles
```

## Documentation

### Getting Started
- **[Spec-Driven Development](docs/spec-driven.md)** - Core SDD methodology
- **[What's New](docs/whats-new.md)** - Recent updates and changes

### Guides
- **[Task Management Tiers](docs/guides/task-management-tiers.md)** - Backlog.md + Beads workflow
- **[Custom Workflows](docs/guides/custom-workflows.md)** - Customize flowspec workflows
- **[Logging](docs/guides/logging.md)** - Agent logging configuration

### Reference
- **[Security CI/CD Setup](docs/guides/security-cicd-setup.md)** - Security scanning in CI/CD
- **[Pre-commit Hooks](docs/guides/pre-commit-hooks.md)** - Git hook integration

## Legacy /speckit Commands

The original `/speckit.*` commands are available for standalone specification work but **do not integrate with backlog.md**. Use `/flow:*` commands for the fully integrated workflow with task tracking.

## Contributing

Contributions are welcome! All commits require DCO sign-off:

```bash
git commit -s -m "feat: your feature"
```

See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

**Found a bug or have a suggestion?** Please open an issue at [github.com/jpoley/flowspec/issues](https://github.com/jpoley/flowspec/issues)

## License

MIT License - see [LICENSE](LICENSE) for details.

---

<div align="center">
    <p><em>Built on <a href="https://github.com/github/spec-kit">GitHub's spec-kit</a> | Powered by <a href="https://github.com/MrLesk/Backlog.md">Backlog.md</a></em></p>
</div>

flowspec

flowspec Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

flowspec

flowspec Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README