Skip to content

t3chn/flowkit

BranchesTags

Repository files navigation

FlowKit

AI-driven development workflow template for projects with backend/frontend split. Extracted from production experience.

Clone, plug in your stack, get a working flow of tasks, agents, and quality gates.

What's Inside

flowkit/
├── CLAUDE.md                            # Root conventions (anti-drift, team workflow)
├── Taskfile.yml                         # Root taskfile — delegates to backend/frontend
├── .pre-commit-config.yaml              # Single hook config (repo root)
├── .gitignore                           # OS, IDE, language ignores
├── .editorconfig                        # Consistent formatting (tabs, spaces, line endings)
├── .beads/                              # Task tracking (git-native, no external services)
├── scripts/
│   ├── beads_contract_lint.py           # Scope contract validator
│   ├── commit_msg_lint.py               # Commit message format validator
│   ├── no_cyrillic_lint.py              # Ensures English-only codebase
│   └── secrets_lint.py                  # Detects leaked secrets and credentials
│
├── backend/
│   ├── CLAUDE.md                        # Backend conventions
│   ├── Taskfile.yml                     # Backend commands (dev, check, test, lint)
│   ├── .claude/
│   │   ├── agents/
│   │   │   ├── dev.md                   # Implements tasks via TDD
│   │   │   ├── tester.md                # Verifies implementations
│   │   │   └── reviewer.md              # Code review + security
│   │   └── commands/
│   │       ├── new-task.md              # /new-task — create task with scope contract
│   │       ├── new-adr.md               # /new-adr — Architecture Decision Record
│   │       └── dep-review.md            # /dep-review — dependency gate
│   ├── cmd/api/                         # Entry point (placeholder)
│   ├── internal/                        # Business logic (placeholder)
│   └── docs/{plans,adr}/               # Design docs and ADRs
│
└── frontend/
    ├── CLAUDE.md                        # Frontend conventions
    ├── Taskfile.yml                     # Frontend commands (dev, check, typecheck, lint, test)
    ├── .claude/
    │   ├── agents/{dev,tester,reviewer}.md
    │   └── commands/{new-task,new-adr,dep-review}.md
    ├── src/                             # Source code (placeholder)
    └── docs/{plans,adr}/               # Design docs and ADRs

Dependencies

Required

Tool Purpose Install
Claude Code AI agent (CLI) npm install -g @anthropic-ai/claude-code
Beads (bd) Git-native task tracking cargo install beads or brew install beads
Task Command runner (Make replacement) brew install go-task or sh -c "$(curl -ssL https://taskfile.dev/install.sh)"
pre-commit Git hooks framework pip install pre-commit or brew install pre-commit
Python 3.10+ For lint scripts Usually pre-installed
Git 2.30+ VCS Usually pre-installed

Optional (stack-dependent)

Backend (Go):

Tool Purpose Install
Go 1.22+ Compiler brew install go
golangci-lint Extended linter brew install golangci-lint
golang-migrate SQL migrations brew install golang-migrate

Frontend (Node.js/TypeScript):

Tool Purpose Install
Node.js 20+ Runtime brew install node or fnm
npm / pnpm / bun Package manager Ships with Node.js

Other stacks: Plug in your own tools — the template is stack-agnostic.

Quick Start

1. Clone and configure

git clone <this-repo> my-project
cd my-project

# Initialize beads (if cloned without .beads/)
bd init

2. Configure your stack

Open backend/CLAUDE.md and frontend/CLAUDE.md, replace <!-- TODO --> blocks with your stack:

## Active Technologies
- Go 1.22, PostgreSQL, pgx/v5        # backend example
- TypeScript 5.x, React 19, Vite 7   # frontend example

3. Install hooks and dependencies

# From repo root — one command sets up everything:
task setup

This installs pre-commit hooks (beads contract lint + commit message lint + secrets detection + Cyrillic check) and runs backend/frontend setup.

4. Uncomment pre-commit hooks for your stack

In the root .pre-commit-config.yaml, uncomment the Backend/Frontend sections:

# Was (commented):
# - id: backend-build
#   entry: bash -c 'cd backend && go build ./...'

# Now:
- id: backend-build
  entry: bash -c 'cd backend && go build ./...'

5. Fill in Taskfile.yml

Replace echo "TODO: ..." with real commands in backend/Taskfile.yml and frontend/Taskfile.yml:

# backend/Taskfile.yml
dev:
  cmd: go run ./cmd/api
test:
  cmd: go test ./... {{.CLI_ARGS}}
lint:
  cmd: golangci-lint run
# frontend/Taskfile.yml
dev:
  cmd: npm run dev
typecheck:
  cmd: npm run typecheck
test:
  cmd: npm test -- --run {{.CLI_ARGS}}

How the Flow Works

Scope Contracts (Anti-Drift)

Every task is a strict contract. The agent cannot exceed its boundaries:

## Objective
Add paginated GET /api/reports endpoint.

## Must-Haves (max 3)
- [ ] Handler in internal/api/reports.go with query params ?page=&limit=
- [ ] SQL query with OFFSET/LIMIT in internal/storage/reports.go
- [ ] Table-driven test cases in internal/api/reports_test.go

## Non-Goals
- Date filtering (separate task)
- Response caching
- OpenAPI specification
- Endpoint authorization

## Constraints
- Go 1.22 stdlib http.ServeMux
- pgx/v5 for PostgreSQL
- Response: JSON `{"items": [...], "total": N, "page": N}`

## Verification
```bash
go build ./...                                    # compiles
go test ./internal/api/... -run TestReports       # tests pass
go vet ./...                                      # no issues
curl localhost:8080/api/reports?page=1&limit=10   # 200 + JSON

Acceptance Criteria

  • go test ./internal/api/... -> PASS, 3+ test cases
  • curl .../api/reports?page=1&limit=10 -> 200, JSON with items/total/page fields

**Why this matters:**
- AI agent gets clear boundaries — won't add "helpful" features
- Non-Goals explicitly list what the agent would typically add on its own
- Verification — copy-pasteable commands with expected output
- Acceptance Criteria — measurable conditions (numbers, status codes, not "works correctly")

### Three Agents

bd ready | v +---------+ +----------+ +-----------+ | dev |---->| tester |---->| reviewer |--> bd close | | | | | | | Writes | | Runs all | | Reads | | code | | Verifi- | | code, | | per | | cation | | checks | | Must- | | commands | | patterns | | Haves | | | | and | | | | | | security | | TDD | | | | | +---------+ +----------+ +-----------+


**Parallelism:** Independent tasks (no `blocked_by`) launch parallel dev agents:

Wave 1: AUTH-1 --> dev-1 DASH-1 --> dev-2 (3 parallel agents) API-1 --> dev-3

Wave 2 (after wave 1): AUTH-2 --> dev-1 DASH-2 --> dev-2 (waited for wave 1 to finish)


### Commit Messages

Format readable by both humans and AI agents:

feat: add paginated reports endpoint

Goal: enable frontend to fetch reports with pagination Why: dashboard needs to display 100+ reports without loading all at once

Refs: beads-a3f2dd Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com


Types: `feat` | `fix` | `refactor` | `docs` | `test` | `chore` | `infra`

`Why:` is mandatory for `feat`, `fix`, `refactor` — the linter will reject commits without it.

### Quality Gates (pre-commit)

On every commit, automatically:

1. **beads-contract-lint** — validates all open tasks have a complete scope contract
2. **commit-msg-lint** — validates message format (`<type>: ...` + `Why:`)
3. **secrets-lint** — detects leaked API keys, tokens, passwords, private keys
4. **no-cyrillic-lint** — ensures English-only codebase (no accidental Cyrillic)
5. **Stack-specific** (uncomment): build, typecheck, lint, test

### Slash Commands

Available in Claude Code from `.claude/commands/`:

| Command | What it does |
|---------|-------------|
| `/new-task <description>` | Creates a task with full scope contract |
| `/new-adr <decision>` | Creates an Architecture Decision Record |
| `/dep-review <package>` | Evaluates a dependency (default: REJECT) |

### Session Protocol

Before ending every session:

```bash
task done          # 1. Quality gates + beads sync
git add <files>    # 2. Stage changes
git commit         # 3. Commit with proper format
bd sync            # 4. Sync beads
git push           # 5. Push to remote

Adapting for Your Project

Minimal Setup

  1. task setup — install hooks
  2. Fill in backend/CLAUDE.md and frontend/CLAUDE.md — project description and stack
  3. Uncomment hooks in root .pre-commit-config.yaml
  4. Replace TODO in backend/Taskfile.yml and frontend/Taskfile.yml

Full Setup

  1. CLAUDE.md — add specific code patterns, banned practices, approved dependencies
  2. Agents — adapt checklists in reviewer.md for your stack (TypeScript strict? Go vet? Python mypy?)
  3. Design docs — create first plan in docs/plans/ with architectural decisions
  4. ADR — record stack choices via /new-adr
  5. Pre-commit — add stack-specific hooks (prettier, black, rustfmt)

Monorepo vs Separate Repos

FlowKit defaults to monorepo (single .beads/ for the whole project). For separate repos:

  1. Copy backend/ and frontend/ into separate git repositories
  2. Run bd init in each
  3. Use **Working directory:** ~/path/to/repo in scope contracts for cross-repo tasks

Core Principles

1. Anti-Drift

Every task is a contract. Don't add what's not in Must-Haves.

AI agents tend toward "helpful additions" — adding tests nobody asked for, refactoring adjacent code, adding error handling "for the future". Scope contracts with explicit Non-Goals prevent this.

2. Verification > Trust

Don't trust "done". Run the commands and show the output.

Every task contains copy-pasteable commands with expected results. The tester agent runs them all and reports actual output.

3. Dependency Gate

Default is REJECT. 50 lines of code beats a new dependency.

/dep-review evaluates each dependency formally: size, maintainer, alternatives, CVEs. Approved ones go into CLAUDE.md.

4. Commits = Documentation

A commit is AI-readable history. Goal + Why matters more than the diff.

Future agents (and humans) read git log to understand why changes were made, not just what changed.

5. Wave Parallelism

Independent tasks = parallel agents. Dependent tasks = sequential waves.

bd dep add builds a dependency graph. bd ready shows tasks with no blockers — they can run in parallel.

Beads Cheat Sheet

# Find work
bd ready                                  # tasks with no blockers
bd list --status=open                     # all open
bd list --status=in_progress              # in progress

# Create and update
bd create --title="Add X" --type=task --priority=2
bd update <id> --status=in_progress       # claim work
bd update <id> --description="..."        # update description
bd close <id>                             # complete

# Dependencies
bd dep add <task> <depends-on>            # task depends on depends-on
bd blocked                                # show blocked tasks
bd show <id>                              # details + what blocks it

# Sync
bd sync                                   # sync with git
bd stats                                  # project statistics

FAQ

Q: Why beads instead of GitHub Issues / Linear / Jira? A: Beads lives in git (.beads/issues.jsonl). AI agents read and write tasks via CLI without API tokens. Works offline. Merges like code.

Q: Why Taskfile instead of Makefile? A: YAML is more readable, cross-platform, supports task dependencies, CLI_ARGS passthrough. task check instead of make check.

Q: Why three agents instead of one? A: Separation of concerns. Dev doesn't verify its own work. Tester runs Verification commands literally. Reviewer checks patterns and security. Like human code review, but automated.

Q: Can I use this without Claude Code? A: CLAUDE.md, scope contracts, and Taskfile work with any AI assistant. Agents and slash-commands are Claude Code-specific. Beads is a standalone CLI.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages