{
  "markdown": "# Flow\n\nA Claude Code skill for intelligent project management — an AI-driven work intelligence engine that scores, prioritizes, assigns, and picks up work items through conversation or a visual Kanban board.\n\nFlow turns Claude into a project partner that thinks in backlogs and decides what matters next. Say \"park this for later\" and it queues the idea with complexity, category, and tags. Say \"what's next?\" and it generates a scored work brief with reasoning, assignment recommendations, and model routing. It detects when priorities shift, flags stale work, and catches recurring problems before you ask.\n\n## What It Does\n\n- **Work Intelligence Engine** — every item gets a computed score based on priority, blocking relationships, freshness, complexity, and more. The score determines what matters next — not just backlog position\n- **Scored work briefs** — instead of \"here's the next item\", Claude produces structured recommendations with reasoning: why this item, who should work on it, which model to use\n- **Reprioritization triggers** — automatic re-scoring when critical bugs are created, blockers are resolved, items are reopened, or blocking relationships change\n- **Assignment intelligence** — recommends agents based on skill matching, linked item history, complexity preference, and workload balancing (max active task cap per agent)\n- **Model routing** — maps item complexity to recommended AI model (low → haiku, medium → sonnet, high → opus) to avoid spending expensive models on simple tasks\n- **Staleness & skip tracking** — flags items stuck too long in refined/ready, and items repeatedly passed over. Prevents backlog rot.\n- **Opportunistic redesign detection** — spots patterns (3+ reopens in the same code area) and suggests structural fixes before more patches\n- **Conversational backlog management** — add, reorder, refine, and complete items by talking naturally\n- **Agent-initiated items** — the agent adds bugs, tech debt, and follow-ups it discovers while working, with complexity, category, tags, and links back to the source task\n- **Linked items** — connect related items with typed links (`discovered-during`, `follow-up`, `blocks`, `related`) and a reason, so context isn't lost weeks later\n- **Visual Kanban board** — drag-and-drop web UI with score badges, complexity indicators, category labels, staleness markers, and an Intelligence tab per item\n- **Configurable workflow lanes** — default agile flow (`backlog → refined → ready → in-progress → code-review → done`) or define your own\n- **Lane gate rules** — enforce process (e.g., nothing reaches Done without passing through Code Review)\n- **Threaded refinement** — structured Q&A threads on items keep discussions organized\n- **Multi-agent support** — filtered views for worker agents, assignment tracking, `@Agent` tagging, configurable agent profiles with skills and capacity\n- **Concurrency safe** — optimistic versioning + atomic writes prevent data loss when multiple agents or the board write simultaneously\n\n## Requirements\n\n- **Python 3.11+** — required by the CLI package\n- **pip** — to install the `backlog` CLI\n\nThe skill CLI (`pip install -e .`) installs these packages automatically:\n\n| Package | Minimum version |\n|---------|----------------|\n| `typer` | 0.12 |\n| `flask` | 3.0 |\n| `rich` | 13.0 |\n| `anthropic` | 0.25 |\n\n> **Running evals?** See [Eval environment setup](#eval-environment-setup-one-time) — the eval suite needs Python 3.12 and additional packages (`deepeval`, `pytest`, `openai`).\n\n## Quick Start\n\nSetup has two parts: (1) make Claude see the skill, and (2) install the `backlog` CLI it drives. **Both are required** — the skill is just instructions; every command it runs (`backlog top`, `backlog pick`, `backlog move`, …) is the Python CLI. Without the CLI installed, the skill fails with `command not found`.\n\n### 1. Make Claude see the skill\n\nPick one option:\n\n**Option A — Standalone install (single user, simplest)**\n\nCopy the skill directly into your Claude Code skills directory:\n\n```bash\n# Available across all your projects (recommended)\ncp -r skills/backlog-manager ~/.claude/skills/\n\n# Available in this project only\ncp -r skills/backlog-manager .claude/skills/\n```\n\nThis produces `~/.claude/skills/backlog-manager/` (the directory name must stay `backlog-manager` — it matches the SKILL.md `name:` and the `/backlog-manager` invocation). Claude Code auto-discovers skills in these directories — no restart needed. Invoke the skill as **`/backlog-manager`**.\n\n**Option B — Plugin install**\n\nWorking today (local), from the repo root:\n\n```bash\nclaude --plugin-dir .\n```\n\nThen invoke as **`/flow:backlog-manager`** within that session.\n\nOr install from the marketplace (one-line), from within a Claude Code session:\n\n```\n/plugin marketplace add prajyotbankade/Flow\n/plugin install flow@flow\n```\n\n### 2. Install the CLI (required for both)\n\nThe skill **drives** the `backlog` CLI — it does not work without it. Install it once (needs Python 3.11+, see [Requirements](#requirements)):\n\n```bash\n# Project-scoped (pip in a venv — tied to that one environment)\ncd skills/backlog-manager && pip install -e .\n\n# Recommended for use across multiple projects (global `backlog` command, not tied to any venv)\npipx install --editable skills/backlog-manager\n```\n\nTradeoff: `pip install -e .` installs into the current Python/venv, so the `backlog` command only exists there. `pipx install --editable` gives you one global `backlog` command that works in every project. After standalone install (Option A), you can run the `pip` variant from `~/.claude/skills/backlog-manager` instead.\n\nCreate the backlog file — run this once in each project to write a starter `backlog.json` at the project root:\n\n```bash\ncd /path/to/your/project\nbacklog init\n```\n\nThe CLI defaults to `./backlog.json`, so no further config is needed. (Optional — only if you want the file somewhere other than the project root: `export BACKLOG_FILE=/custom/path/backlog.json`, or pass `--file` on every command.)\n\nWire agents to use the backlog — run this once per project, then commit `CLAUDE.md`:\n\n```bash\nbacklog doctor --fix\ngit add CLAUDE.md && git commit -m \"chore: add Flow Backlog setup for agents\"\n```\n\nThis writes a `## Flow Backlog` section to your project's `CLAUDE.md` so every agent on the project uses the backlog CLI instead of reasoning about priorities on its own. (`doctor --fix` only updates `CLAUDE.md` — it does not create `backlog.json`; that's what `backlog init` above is for.) Without this step, agents won't know the backlog exists.\n\nNow agents and scripts can use the CLI directly — no server required:\n\n```bash\nbacklog list                  # show board\nbacklog add \"Fix login bug\"   # add item\nbacklog pick alice            # pick top ready item, move to in-progress\nbacklog move 3 in-progress    # lane transition (gate rules enforced)\nbacklog done 3                # complete\n```\n\n### 3. Start using it\n\nVerify the CLI works, then just talk to Claude — no command needed once the skill is active:\n\n```bash\nbacklog top                   # should print the next item (or an empty backlog)\n```\n\n```\n\"Add OAuth2 support to the backlog\"\n\"Show me the backlog\"\n\"What should I work on next?\"\n\"Move #3 above #1\"\n\"Refine #2 — I think we need to scope it down\"\n```\n\n### Launch the visual board\n\n```bash\nbacklog board                  # uses BACKLOG_FILE, opens at http://localhost:8089\nbacklog-server --file backlog.json --port 8089   # explicit, same thing\n```\n\nOpens a Kanban board at `http://localhost:8089` with drag-and-drop cards, threaded conversations, and real-time sync.\n\n## Out of the Box\n\nThe repo ships with a starter `backlog.json` — zero items, but fully configured with the default workflow lanes and gate rules. You can see exactly how the board is structured before adding anything:\n\n```\nbacklog → refined → ready → in-progress → code-review → done\n```\n\nGate rules are pre-configured: items must pass through each stage in order (e.g., nothing reaches Done without Code Review). Customize the lanes anytime by editing the `statuses` array in `backlog.json` — or just start adding items and the defaults will work.\n\n## How It Works\n\nEverything lives in a single `backlog.json` at your project root. Items are stored in an ordered array — position = priority. The file is the source of truth for both the CLI agent and the web board.\n\n```\nbacklog.json\n├── version           # Optimistic concurrency counter\n├── config\n│   ├── scope         # \"project\" or \"global\" (for monorepos)\n│   ├── project_name\n│   ├── statuses[]    # Configurable workflow lanes with gate rules\n│   ├── scoring       # Intelligence engine weights (all configurable)\n│   ├── agents        # Agent profiles: skills, max_active, preferred_complexity\n│   ├── thresholds    # Staleness days, critical unassigned hours, skip escalation\n│   └── model_routing # Complexity-to-model mapping (low→haiku, medium→sonnet, high→opus)\n└── items[]           # Ordered by priority (index 0 = highest)\n    ├── id, title, description, status\n    ├── assigned_to\n    ├── complexity     # low | medium | high — drives scoring + model routing\n    ├── priority_weight # 1-10 explicit priority (overrides position)\n    ├── category       # bug | feature | chore | tech-debt — critical bugs trigger reprioritization\n    ├── tags[]         # Free-form tags for skill matching (e.g., \"auth\", \"frontend\")\n    ├── reopen_count   # Auto-incremented when moved back from done\n    ├── skip_count     # Tracks how many times item was passed over\n    ├── readiness_signals[]  # Artifact evidence (spec_written, pr_merged, etc.)\n    ├── threads[]      # Refinement Q&A\n    ├── links[]        # Connections to related items (type + reason)\n    ├── lane_history[] + gate_from  # Audit trail + rule engine\n    └── created_at, updated_at\n```\n\n### Lane Gate Rules\n\nLanes can require items to have passed through specific prior lanes before entering. This is enforced at three layers: the web board (blocked drop zones), the server API (HTTP 422), and the agent instructions.\n\n```json\n{ \"id\": \"done\", \"label\": \"Done\", \"requires\": [\"code-review\"] }\n```\n\nAn item can't be marked Done unless it's been through Code Review. Moving backward resets the watermark — the item must re-earn gates on its new journey.\n\n**Spec gate** — a complementary soft gate enforced at the skill level: before any item moves to `ready` (from any prior status), the skill requires a written spec covering acceptance criteria, failure modes, and edge cases. Answers are embedded in the item description as a `## Spec` block and the `spec_written` readiness signal (+10% readiness) is set by the skill. The gate is bypassed if either the signal or a `## Spec` block already exists — so reopened items that return to `ready` don't get re-questioned. Unlike lane gate rules (which are structural), the spec gate is semantic — it ensures the work is understood before it enters the execution queue. Items that skip the spec are a leading cause of review rejects and reopens.\n\n### Concurrency\n\nMultiple agents or the web board can write simultaneously without data loss:\n\n- Every write increments a `version` field\n- Stale writes are rejected with HTTP 409\n- All file writes are atomic (temp file + rename)\n\n## Project Structure\n\n```\nFlow/\n├── .claude-plugin/\n│   └── plugin.json           # Plugin manifest for distribution\n├── skills/\n│   └── backlog-manager/\n│       ├── SKILL.md              # Skill instructions (the brain)\n│       ├── pyproject.toml        # Package config — installs backlog + backlog-server CLI\n│       ├── backlog/              # Core Python package\n│       │   ├── core.py           # BacklogStore — all gate/versioning/CRUD logic\n│       │   ├── exceptions.py     # GateViolationError, ConflictError, ItemNotFoundError\n│       │   ├── cli.py            # Typer CLI (backlog command)\n│       │   └── server.py         # HTTP server (backlog-server command)\n│       ├── scripts/\n│       │   └── backlog_server.py # Legacy server (kept for reference)\n│       ├── assets/\n│       │   └── backlog-board.html # Kanban board UI\n│       ├── references/\n│       │   └── schema.md         # JSON schema documentation\n│       └── evals/\n│           ├── evals.json           # Test cases and assertions\n│           ├── eval_flow_skill.py   # deepeval skill harness (calls live API + Ollama)\n│           ├── test_flow_live.py    # deepeval benchmark suite (AnswerRelevancy + GEval)\n│           ├── test_cli.py          # CLI integration tests (11 scenarios, no server needed)\n│           ├── files/               # Fixture data for evals\n│           └── results/             # Test run outputs\n└── backlog.json              # Your backlog (zero items, ready to use)\n```\n\n## Board Features\n\n- Drag-and-drop cards between lanes\n- **Intelligence score badges** on every card (color-coded: green >7, yellow 4-7, gray <4)\n- **Complexity dots** (green/yellow/red) and **category badges** (BUG, FEAT, CHORE, DEBT)\n- **Staleness indicators** — amber border on items past threshold\n- **Sort toggle** — switch between position-based and score-based ordering\n- Click cards to edit — full modal with all fields including complexity, category, priority weight, and tags\n- **Intelligence tab** in modal — score breakdown, recommended agent, recommended model, reopen/skip counts\n- Threaded conversations with `@Agent` tagging\n- Linked items — view, add, and manage connections between items with type badges and reasons\n- Assignment dropdown\n- **Agent profiles in settings** — define skills, max active tasks, and preferred complexity per agent\n- **Scoring weights in settings** — tune all intelligence engine parameters\n- Position numbers, timestamps, unresolved thread counts, link counts\n- Auto-refreshes every 5 seconds (scores refresh with each cycle)\n- Keyboard shortcuts: `N` to add, `Esc` to close\n\n## Work Intelligence Engine\n\nFlow doesn't just track work — it decides what matters next. Every item gets a computed score:\n\n```\nscore = base_priority + unblock_value + freshness + complexity_bonus\n      + blocked_penalty + quick_win_bonus + reopen_penalty\n      + skip_floor + critical_bug_boost\n```\n\nItems that unblock multiple others score highest. Quick wins get a momentum bonus. Stale items get penalized. Critical bugs get a +5.0 boost that dominates the ranking.\n\n### Work Briefs\n\nInstead of \"here's the next item\", Claude produces structured work briefs:\n\n```\n=== WORK BRIEF ===\n\nNEXT: #3 — Fix auth timeout\n  Score: 9.2 | Blocks: #7, #11 | Age: 4d in ready\n  Assign: Agent-B (worked on auth in #1, load: 1/3)\n  Model: sonnet (medium complexity)\n  Why: Unblocks 2 critical items, freshness penalty kicking in\n\nTHEN: #4 — Add retry logic\n  Score: 7.1 | Quick win (low complexity)\n  Why: Clears simple item, maintains momentum\n\nWATCH:\n  #12 — Stuck in refined 9d. Kill or promote?\n  Module /auth — 3 reopens in 14d. Consider redesign.\n```\n\n### Reprioritization Triggers\n\nThe server automatically detects events and returns `_events` in write responses:\n- **`critical_bug_created`** — new bug with priority ≥ 9\n- **`blocker_resolved`** — item with `blocks` links moved to done\n- **`item_reopened`** — item moved backward from done (auto-increments `reopen_count`)\n- **`blocks_changed`** — item gained new blocking relationships\n\n### API Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/backlog` | Full backlog (or `?agent=name` for filtered view) |\n| `GET /api/scores` | All items with computed scores, breakdowns, and recommendations |\n| `GET /api/agents` | Agent profiles with current load |\n| `PUT /api/backlog` | Full write (version-checked, returns `_events`) |\n| `PUT /api/items/<id>` | Single item update (version-checked, returns `_events`) |\n\n## Configuration\n\n### Workflow Lanes\n\nDefine your own columns in `backlog.json` config:\n\n```json\n\"statuses\": [\n  { \"id\": \"backlog\",     \"label\": \"Backlog\" },\n  { \"id\": \"design\",      \"label\": \"Design Review\" },\n  { \"id\": \"ready\",       \"label\": \"Ready\" },\n  { \"id\": \"in-progress\", \"label\": \"In Progress\" },\n  { \"id\": \"qa\",          \"label\": \"QA\",          \"requires\": [\"in-progress\"] },\n  { \"id\": \"done\",        \"label\": \"Done\",        \"requires\": [\"qa\"] }\n]\n```\n\n### Scope\n\n- **`project`** (default) — `backlog.json` lives in the project root\n- **`global`** — `backlog.json` lives at `~/.claude/backlog.json`, useful for monorepos or cross-project task lists\n\n### Agent Profiles\n\nDefine agent capabilities in `config.agents` for intelligent assignment:\n\n```json\n\"agents\": {\n  \"lead-dev\": {\n    \"role\": \"lead\",\n    \"skills\": [\"python\", \"api\"],\n    \"max_active\": 1\n  },\n  \"worker-auth\": {\n    \"skills\": [\"auth\", \"backend\", \"security\"],\n    \"max_active\": 3,\n    \"preferred_complexity\": [\"medium\", \"high\"]\n  },\n  \"worker-ui\": {\n    \"skills\": [\"frontend\", \"css\", \"ux\"],\n    \"max_active\": 2,\n    \"preferred_complexity\": [\"low\", \"medium\"]\n  }\n}\n```\n\n`\"role\": \"lead\"` designates the agent that drives the full dev cycle in auto mode. Exactly one agent may have this role.\n\n`\"role\": \"reviewer\"` designates the dedicated code review agent. The orchestrator prefers it for all review handoffs. Its persona file (`.claude/agents/reviewer.md`) carries persistent learnings about what to catch.\n\nAlso configurable from the board's Settings modal.\n\n### Orchestrator\n\n`backlog orchestrate` is a persistent process that drives the dev cycle after items are ready:\n\n```bash\nbacklog orchestrate                # supervised mode — acts on ready+ items only\nbacklog orchestrate --mode auto    # auto mode — lead agent picks, refines, and starts work\nbacklog orchestrate --once         # single tick and exit (useful for testing)\nbacklog orchestrate --dry-run      # print planned actions without invoking agents\n```\n\n**Supervised mode (default):** Human moves items to `ready`. Orchestrator picks up from there — assigns agents, drives through all lanes including review, processes results.\n\n**Auto mode:** Lead agent continuously picks the highest-priority unstarted item, assesses whether it's actionable, and either moves it to `ready` (orchestrator picks it up immediately) or asks the human targeted questions via a thread. Loops until stopped (`Ctrl+C`).\n\n**Orchestrator config:**\n\n```json\n\"orchestrator\": {\n  \"mode\": \"supervised\",\n  \"require_review\": true\n}\n```\n\n`require_review: true` (default) — every item must be reviewed by a different agent before reaching done, even if no code-review lane is configured. Set to `false` with caution — a warning is printed at startup.\n\n### Scoring Weights\n\nAll scoring parameters are tunable in `config.scoring`:\n\n```json\n\"scoring\": {\n  \"unblock_weight\": 2.0,\n  \"blocked_penalty\": -3.0,\n  \"quick_win_bonus\": 1.0,\n  \"critical_bug_boost\": 5.0,\n  \"freshness_decay_days\": 14,\n  \"skip_floor_per\": 0.3\n}\n```\n\nSee [`references/schema.md`](skills/backlog-manager/references/schema.md) for the full list of configurable weights and thresholds.\n\n### Eval environment setup (one-time)\n\nDeepEval 3.9+ requires Python 3.10+. The system Python on macOS is 3.9 and will fail with a\n`TypeError: unsupported operand type(s) for |` error. Use the Homebrew Python 3.12 venv instead:\n\n```bash\n# Create the venv once\n/opt/homebrew/bin/python3.12 -m venv skills/backlog-manager/evals/.venv\nsource skills/backlog-manager/evals/.venv/bin/activate\npip install -r skills/backlog-manager/evals/requirements.txt\n```\n\nAfter that, always activate the venv before running evals:\n\n```bash\nsource skills/backlog-manager/evals/.venv/bin/activate\n```\n\n### To run stress test\n```bash\nlsof -ti :8089 | xargs kill -9\n\nBACKLOG_FILE=stress-tests/backlog_stress_2000.json backlog-server --no-open &\n\nuntil curl -sf http://localhost:8089/api/backlog > /dev/null; do sleep 0.5; done\n\necho \"--- Scores (2000) ---\"\ntime curl -s http://localhost:8089/api/scores | wc -c\n\necho \"--- Recommend (2000) ---\"\ntime curl -s http://localhost:8089/api/recommend | wc -c\n\necho \"--- Graph (2000) ---\"\ntime curl -s http://localhost:8089/api/graph | wc -c\n\necho \"--- Pulse (2000) ---\"\ntime curl -s http://localhost:8089/api/pulse | wc -c\n\nlsof -ti :8089 | xargs kill -9\n```\n\n### To run CLI stress test (agent path)\n```bash\nexport BACKLOG_FILE=stress-tests/backlog_stress_2000.json\n\necho \"--- top (2000) ---\"\ntime backlog top\n\necho \"--- list (2000) ---\"\ntime backlog list > /dev/null\n\necho \"--- show (2000) ---\"\ntime backlog show 1 > /dev/null\n```\n\n### To run all evals (full suite)\n```bash\nsource skills/backlog-manager/evals/.venv/bin/activate\nlsof -ti :8089 | xargs kill -9\n\nbacklog-server --no-open &\n\nuntil curl -sf http://localhost:8089/api/backlog > /dev/null; do sleep 0.5; done\n\ncd skills/backlog-manager/evals\nEVAL_LLM=openai python3 -m pytest test_flow_live.py -v 2>&1 | tee results/test_results_$(date +%Y%m%d_%H%M%S).txt\n```\n\n### To run tribunal ties fixture tests\n```bash\nsource skills/backlog-manager/evals/.venv/bin/activate\nlsof -ti :8089 | xargs kill -9\n\nbacklog-server --no-open &\n\nuntil curl -sf http://localhost:8089/api/backlog > /dev/null; do sleep 0.5; done\n\ncd skills/backlog-manager/evals\npython3 -m pytest test_flow_live.py::TestTribunalTiesFixture -v\n```\n\n### To run critical path fixture tests\n```bash\nsource skills/backlog-manager/evals/.venv/bin/activate\nlsof -ti :8089 | xargs kill -9\n\nbacklog-server --no-open &\n\nuntil curl -sf http://localhost:8089/api/backlog > /dev/null; do sleep 0.5; done\n\ncd skills/backlog-manager/evals\npython3 -m pytest test_flow_live.py::TestCriticalPathFixture -v\n```\n\n\n\n## License\n\nMIT\n",
  "bytes": 21441,
  "sha": "50c2f63eb448bc1e572650f55a406c729135d8404e143f395e12053c647ee43c",
  "repo_slug": "prajyotbankade/flow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_prajyotbankade_flow_flow_56fd61ed/readme"
}