Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(flow): FLOW unification layer + release 2.17.0 (#399)

Aurora Capitala6a149fa2af9
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 3736f2e3..9373dd62 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
"name": "ops",
"description": "Business operations command center for Claude Code — 37 skills, 19 agents, smart background daemon. Manage communications (WhatsApp/Email/Slack/Telegram), projects, infrastructure (AWS), revenue (Stripe+RevenueCat), e-commerce, marketing, monitoring (Datadog/New Relic/OTEL), voice, and smart home (Homey Pro). Includes /gtm go-to-market planner, /ops:projects portfolio dashboard, /ops:ops-home control surface, and YOLO autonomous mode with 4 parallel C-suite agents.",
"source": "./claude-ops",
- "version": "2.16.0",
+ "version": "2.17.0",
"category": "productivity",
"keywords": [
"ops",
diff --git a/claude-ops/.claude-plugin/plugin.json b/claude-ops/.claude-plugin/plugin.json
index 861845a4..7a6f8e0a 100644
--- a/claude-ops/.claude-plugin/plugin.json
+++ b/claude-ops/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "ops",
- "version": "2.16.0",
+ "version": "2.17.0",
"description": "Business operations command center for Claude Code — 37 skills, 19 agents, and a smart background daemon that manage communications (WhatsApp/Email/Slack/Telegram), projects, infrastructure (all AWS services), revenue (Stripe + RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4/GSC), monitoring (Datadog/New Relic/OTEL), and voice (Bland AI/ElevenLabs/Whisper). Includes /gtm go-to-market planner, /ops:projects portfolio dashboard, YOLO mode for autonomous operation with 4 parallel C-suite agents, and /ops:ops-home smart home control via Homey Pro.",
"author": {
"name": "Lifecycle Innovations Limited",
diff --git a/claude-ops/CHANGELOG.md b/claude-ops/CHANGELOG.md
index 272e992b..e2e50656 100644
--- a/claude-ops/CHANGELOG.md
+++ b/claude-ops/CHANGELOG.md
@@ -1,5 +1,22 @@
# Changelog
+## 2.17.0 — 2026-05-30
+
+### Added
+- **FLOW unification layer** (`/flow`) — one entrypoint over the three overlapping
+ command systems (gstack dev-lifecycle, GSD `.planning/` phase machine, claude-ops
+ `/ops:*`). Router/facade only — does NOT merge codebases; all three stay installed
+ and self-updating, `/flow` delegates to the single canonical command per stage.
+ - `skills/flow/SKILL.md` — the `/flow` router (keyword→canonical), mirrors the
+ `/ops:ops` routing-table pattern.
+ - `skills/flow/FLOW.md` — canonical lifecycle map (single source of truth):
+ ideate→spec→plan→design→build→review→test→ship→deploy→monitor→retro, plus the
+ **project-mode vs ad-hoc-mode** rule (repo `.planning/` state picks the
+ abstraction level: GSD phase machine vs gstack stateless lifecycle).
+ - `bin/flow-state` — "you are here" detector (mode + GSD phase + open PRs);
+ GitHub-quota-safe (single non-watch `gh` call), `--json` for machines.
+ - `docs/flow-guide.md` — user guide.
+
## 2.16.0 — 2026-05-29
### Added
diff --git a/claude-ops/bin/flow-state b/claude-ops/bin/flow-state
new file mode 100755
index 00000000..7142aeef
--- /dev/null
+++ b/claude-ops/bin/flow-state
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# flow-state — "you are here" on the FLOW lifecycle.
+#
+# Detects mode (PROJECT vs AD-HOC) from the current repo's .planning/ dir,
+# surfaces the current GSD phase, open PRs, and deploy hints, so `/flow` with
+# no args can show the user where they are and what the next canonical stage is.
+#
+# Read by skills/flow/SKILL.md. Self-contained, fast, and GitHub-quota-safe:
+# exactly ONE non-watching `gh` call, never in a loop (per the GitHub-API rule).
+#
+# Usage: flow-state [--json] [path]
+# path repo to inspect (default: cwd)
+
+set -uo pipefail # not -e: best-effort probes must not abort the report
+
+JSON=0
+TARGET="$PWD"
+for arg in "$@"; do
+ case "$arg" in
+ --json) JSON=1 ;;
+ *) [ -d "$arg" ] && TARGET="$arg" ;;
+ esac
+done
+
+cd "$TARGET" 2>/dev/null || true
+
+# --- git root + mode ---------------------------------------------------------
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+MODE="AD-HOC"
+PHASE=""
+PHASE_FILE=""
+PLANNING=""
+
+if [ -n "$ROOT" ] && [ -d "$ROOT/.planning" ]; then
+ MODE="PROJECT"
+ PLANNING="$ROOT/.planning"
+ # current phase: prefer STATE.md frontmatter `phase:` / `current_phase:`,
+ # else the highest-numbered phase dir.
+ if [ -f "$PLANNING/STATE.md" ]; then
+ PHASE_FILE="$PLANNING/STATE.md"
+ PHASE="$(awk -F': *' '
+ /^phase:/ { gsub(/["'"'"']/,"",$2); p=$2 }
+ /^current_phase:/{ gsub(/["'"'"']/,"",$2); p=$2 }
+ END { print p }' "$PLANNING/STATE.md" 2>/dev/null)"
+ fi
+ if [ -z "$PHASE" ]; then
+ PHASE="$(ls -d "$PLANNING"/phase-* "$PLANNING"/*/ 2>/dev/null | grep -Eo 'phase-[0-9.]+' | sort -V | tail -1)"
+ fi
+fi
+
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '-')"
+DIRTY=0
+if [ -n "$ROOT" ]; then
+ git diff --quiet 2>/dev/null && git diff --cached --quiet 2>/dev/null || DIRTY=1
+fi
+
+# --- open PRs (single quota-safe call) --------------------------------------
+PRS="?"
+if command -v gh >/dev/null 2>&1 && [ -n "$ROOT" ]; then
+ PRS="$(gh pr list --state open --json number --jq 'length' 2>/dev/null || echo '?')"
+fi
+
+# --- suggested next stage ----------------------------------------------------
+if [ "$MODE" = "PROJECT" ]; then
+ NEXT="resume GSD phase → /flow build (then review · test · ship)"
+else
+ NEXT="/flow spec → plan → build → review → test → ship"
+fi
+
+# --- output ------------------------------------------------------------------
+if [ "$JSON" -eq 1 ]; then
+ printf '{"mode":"%s","root":"%s","branch":"%s","dirty":%s,"phase":"%s","planning":"%s","open_prs":"%s"}\n' \
+ "$MODE" "${ROOT:-}" "$BRANCH" "$DIRTY" "${PHASE:-}" "${PLANNING:-}" "$PRS"
+ exit 0
+fi
+
+echo "MODE=$MODE"
+echo "ROOT=${ROOT:-<not a git repo>}"
+echo "BRANCH=$BRANCH$([ "$DIRTY" -eq 1 ] && echo ' (uncommitted changes)')"
+[ "$MODE" = "PROJECT" ] && echo "PHASE=${PHASE:-<no phase recorded>}"
+[ -n "$PLANNING" ] && echo "PLANNING=$PLANNING"
+echo "OPEN_PRS=$PRS"
+echo "NEXT=$NEXT"
diff --git a/claude-ops/docs/flow-guide.md b/claude-ops/docs/flow-guide.md
new file mode 100644
index 00000000..689eeb9e
--- /dev/null
+++ b/claude-ops/docs/flow-guide.md
@@ -0,0 +1,67 @@
+# FLOW — User Guide
+
+`/flow` is the **single entrypoint** for the whole dev lifecycle. It unifies three
+command systems that used to collide on `ship / review / plan / deploy / qa / triage`:
+
+- **gstack** — dev-lifecycle role prompts + the `/browse` browser engine
+- **GSD** — the `.planning/` phase state machine (defends against context-rot)
+- **claude-ops** — `/ops:*` business-ops + the always-on daemon
+
+It does **not** merge them. All three stay installed and self-updating. `/flow` is a
+thin router that picks the one canonical command per stage.
+
+## The one rule
+
+`/flow` reads your repo state and picks the abstraction level:
+
+| Repo state | Mode | What runs |
+|---|---|---|
+| git root has `.planning/` | **PROJECT** | GSD phase machine; phases call gstack/ops tools as sub-steps |
+| no `.planning/` | **AD-HOC** | gstack stateless lifecycle (`/spec→build→/review→/qa→/ship`) |
+| any | **OPS** | `/ops:*` always available (inbox, fires, marketing, daemon, voice, finops) |
+
+You never choose the mode — the router does, from `bin/flow-state`.
+
+## Usage
+
+```
+/flow # print the lifecycle map + "you are here" (mode, phase, PRs)
+/flow ideate # → /office-hours
+/flow spec <thing> # → /spec
+/flow plan # project → gsd-plan-phase; ad-hoc → /autoplan
+/flow design # → /design-consultation → /design-shotgun → /design-html
+/flow build # project → gsd-execute-phase; ad-hoc → direct edits (worktree)
+/flow review # → /review + /cso (+ gsd-code-review in project-mode)
+/flow test # → /qa + /browse (/ios-qa for iOS)
+/flow ship # project → gsd-ship; ad-hoc → /ship; salvage → /ops:ops-merge
+/flow deploy # → /ops:ops-deploy → /canary
+/flow monitor # → /ops:ops-fires + /ops:ops-status
+/flow retro # → /retro + /learn
+/flow ops inbox # → /ops:ops inbox (whole arg handed to the ops sub-router)
+/flow projects # → /ops:ops-projects (read-only dashboard over GSD .planning/)
+```
+
+## Canonical command per stage
+
+The authoritative table lives in [`skills/flow/FLOW.md`](../skills/flow/FLOW.md). Edit there,
+not in three separate doctrines. The same map is mirrored in `~/.claude/CLAUDE.md` under
+**FLOW DOCTRINE**.
+
+## What changed for existing commands
+
+No command was deleted. Duplicates were **demoted via description**: their skill
+`description:` now states their narrow remaining role and names the canonical (e.g.
+personal `/morning` → "DEMOTED: canonical briefing is /ops:ops-go"). This is the lever
+that fixes model routing — when a description is unambiguous, the model picks correctly.
+It's fully reversible; a later v2 can prune once `/flow` is trusted.
+
+Ownership boundaries that are now **sole-owner**:
+- **ops / comms / autonomy** → claude-ops `/ops:*`
+- **project-state** (phases, `.planning/`) → GSD; `/ops:ops-projects` is the read-only view
+- **browser** → gstack `/browse` (unchanged; safety-critical rules in CLAUDE.md)
+
+## Files
+
+- `skills/flow/SKILL.md` — the router
+- `skills/flow/FLOW.md` — canonical lifecycle map (single source of truth)
+- `bin/flow-state` — "you are here" detector (mode + phase + PRs); `--json` for machines
diff --git a/claude-ops/skills/flow/FLOW.md b/claude-ops/skills/flow/FLOW.md
new file mode 100644
index 00000000..d2c1187b
--- /dev/null
+++ b/claude-ops/skills/flow/FLOW.md
@@ -0,0 +1,89 @@
+# FLOW — The Canonical Lifecycle Map
+
+> Single source of truth for **which command runs at each lifecycle stage**.
+> The `/flow` router (`skills/flow/SKILL.md`) reads this file to dispatch.
+> Three systems stay installed and self-updating; this map is the only
+> place that decides who owns what. Edit here, not in three doctrines.
+
+---
+
+## The one routing rule: project-mode vs ad-hoc-mode
+
+`/flow` picks the **abstraction level from repo state first**, then delegates
+to the canonical tool. This single mechanism dissolves the worst collisions
+(ship / build / review / orchestrate) — there is no forced "winner", the
+router defaults correctly per context.
+
+- **PROJECT-MODE** — the repo (or cwd's git root) has a `.planning/` directory.
+ `/flow` drives the **GSD phase state machine**
+ (`spec → discuss → plan → execute → verify → ship → milestone`). Each GSD
+ phase *calls gstack / ops tools as sub-steps* (e.g. execute-phase invokes
+ `/browse` for QA, `/design-html` for UI, `ops:ops-deploy` for rollout).
+ **State + rigor come from GSD; the tools come from gstack / ops.**
+
+- **AD-HOC-MODE** — no `.planning/` dir; a quick, stateless change.
+ `/flow` runs the **gstack stateless lifecycle** directly
+ (`/spec → build → /review → /qa → /ship`) with zero `.planning/` overhead.
+
+- **OPS / COMMS / AUTONOMY** — claude-ops `/ops:*`. Always available
+ orthogonally in **either** mode (inbox, fires, marketing, daemon, voice,
+ finops, home). Never gated on repo state.
+
+Detection contract: a repo is project-mode iff `git rev-parse --show-toplevel`
+resolves and `<toplevel>/.planning/` exists. Otherwise ad-hoc-mode. `bin/flow-state`
+computes this and the "you are here" position.
+
+---
+
+## Canonical command per stage
+
+For each stage exactly **one** canonical command runs. The rest are
+"also invoked" (fired as sub-steps by the canonical) or "demoted"
+(kept installed, but their `description:` is rewritten to name the canonical).
+
+| Stage | Canonical | Also invoked (sub-steps) | Demoted → points at canonical |
+|---|---|---|---|
+| **ideate** | gstack `/office-hours` | `ops:ops-yolo` (C-suite Hard Truths) | — |
+| **spec** | gstack `/spec` (5-phase → GitHub issue → worktree agent) | feeds GSD engine | `gsd-spec-phase` (engine, not entrypoint) |
+| **plan** | **GSD** `gsd-plan-phase` / `gsd-ultraplan-phase` (goal-backward, `.planning/PLAN.md`) wrapped by gstack `/autoplan` role reviews | `gsd-plan-review-convergence` | `/plan-*-review` (run via `/autoplan`); `giga plan` |
+| **design** | gstack `/design-consultation` → `/design-shotgun` → `/design-html` | Pencil/Figma (DESIGN-FIRST rule) | — |
+| **build** | project → **GSD** `gsd-execute-phase` (fresh-context waves) / `gsd-master-orchestrator` (multi-project, ≤5 subagents/action); ad-hoc → direct edits + worktree | worktree isolation (mandatory) | `ops:ops-orchestrate`, `superpowers:dispatching-parallel-agents`, personal `subagents`/`orchestrator` |
+| **review** | gstack `/review` (pre-land) + `/cso` (security) | project also runs `gsd-code-review` (phase-gated → CODE-REVIEW.md) | standalone `code-review` / `security-review`; `gsd-review` |
+| **test** | gstack `/qa` + `/browse` (web), `/ios-qa` (iOS) | project also runs `gsd-verify-work` + `gsd-add-tests` | standalone `e2e` |
+| **ship** | project → **GSD** `gsd-ship` (phase→PR, `.planning`-filtered branch); ad-hoc single-repo → gstack `/ship`; multi-repo salvage → `ops:ops-merge` | `gsd-pr-branch` cleans the branch | `commit-commands:commit-push-pr` |
+| **deploy** | claude-ops `ops:ops-deploy` + gstack `/land-and-deploy` → `/canary` | `ops:ops-deploy-fix` (autofix) | `/setup-deploy` (config only) |
+| **monitor** | claude-ops `ops:ops-fires` + `ops:ops-status` + `ops:ops-monitor` | gstack `/health`, `/landing-report` | `gsd-health`, `gsd-progress`, personal `status` |
+| **retro / learn** | gstack `/retro` + `/learn` | `gsd-extract-learnings` / `gsd-milestone-summary` at milestone close | `giga consolidate`; `ops:ops-recap` (kept) |
+| **ops / comms** | **claude-ops `/ops:*` — SOLE OWNER** | — | personal `morning` / `wrap` → `ops-go`; `next` → `ops-next` |
+| **project-state** | **GSD `.planning/` — SOLE OWNER**; `ops:ops-projects` is the read-only dashboard over it (via `gsd-registry-sync` cron) | `ops:ops-linear` syncs phases→Linear | personal `my-project-gsd` |
+
+---
+
+## Router dispatch table (keyword → target)
+
+`/flow <intent>` keyword-matches the first column; mode-sensitive rows
+resolve via `bin/flow-state`. Mirrors the `/ops:ops` routing-table pattern.
+
+| Intent keywords | Stage | Resolves to |
+|---|---|---|
+| (empty), map, here, where | — | print this map + `bin/flow-state` "you are here" |
+| ideate, brainstorm, office-hours, hard-truths | ideate | `/office-hours` (+ `/ops:ops-yolo` if "hard truths") |
+| spec, specify, scope, issue | spec | `/spec` |
+| plan, roadmap, phase-plan | plan | project → `gsd-plan-phase`; ad-hoc → `/autoplan` |
+| ultraplan, deep-plan | plan | `gsd-ultraplan-phase` |
+| design, ui, mockup, html | design | `/design-consultation` |
+| build, execute, implement, code | build | project → `gsd-execute-phase`; multi-project → `gsd-master-orchestrator`; ad-hoc → direct + worktree |
+| review, code-review, cr | review | `/review` (+ `gsd-code-review` if project) |
+| security, cso, sec-review | review | `/cso` |
+| test, qa, e2e | test | `/qa` (+ `gsd-verify-work` if project) |
+| ios-qa, ios-test | test | `/ios-qa` |
+| ship, pr, land | ship | project → `gsd-ship`; ad-hoc → `/ship`; salvage → `/ops:ops-merge` |
+| deploy, release, rollout | deploy | `/ops:ops-deploy` → `/canary` |
+| canary | deploy | `/canary` |
+| monitor, fires, incidents, status, health | monitor | `/ops:ops-fires` (+ `/ops:ops-status`) |
+| retro, learn, reflect | retro | `/retro` (+ `/learn`) |
+| ops, inbox, comms, marketing, finops, voice, home, daemon | ops | `/ops:ops $REST` (delegate whole arg to ops sub-router) |
+| projects, portfolio, state | project-state | `/ops:ops-projects` |
+
+When the intent is ambiguous between two stages, prefer the **earliest**
+unfulfilled stage for the current `flow-state` position.
diff --git a/claude-ops/skills/flow/SKILL.md b/claude-ops/skills/flow/SKILL.md
new file mode 100644
index 00000000..5d65f782
--- /dev/null
+++ b/claude-ops/skills/flow/SKILL.md
@@ -0,0 +1,94 @@
+---
+name: flow
+description: ONE entrypoint for the whole dev lifecycle — ideate, spec, plan, design, build, review, test, ship, deploy, monitor, retro. Routes to the single canonical command per stage (gstack / GSD / claude-ops) and picks project-mode (GSD phase machine) vs ad-hoc-mode (gstack stateless) from repo `.planning/` state. Bare `/flow` prints the lifecycle map + your current "you are here" position.
+argument-hint: "[stage|intent] [args]"
+allowed-tools:
+ - Bash
+ - Read
+ - Grep
+ - Glob
+ - Skill
+ - Agent
+effort: medium
+maxTurns: 20
+---
+
+## Runtime Context
+
+Before routing, compute where the user is on the lifecycle:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT:-$HOME/Projects/claude-ops/claude-ops}/bin/flow-state"
+```
+
+This prints: mode (PROJECT / AD-HOC), current `.planning/` phase (if any),
+open PRs, and deploy state — the "you are here" marker. Read it first so
+mode-sensitive routes (build / ship / review) resolve correctly.
+
+The canonical map lives in `FLOW.md` (same dir). Read it when you need the
+full per-stage ownership table; the dispatch table below is the routing copy.
+
+---
+
+# FLOW — One Lifecycle Entrypoint
+
+**The one rule:** pick the abstraction level from repo state, then delegate
+to the canonical tool.
+
+- **PROJECT-MODE** (git root has `.planning/`): drive the **GSD phase state
+ machine**; GSD phases call gstack/ops tools as sub-steps.
+- **AD-HOC-MODE** (no `.planning/`): run the **gstack stateless lifecycle**.
+- **OPS** (`/ops:*`): always available in either mode.
+
+Route `$ARGUMENTS` (first token = intent) using this table:
+
+| Intent keywords | Resolves to |
+| --- | --- |
+| (empty), map, here, where | print map (`Read FLOW.md`) + `bin/flow-state` output. **Stop — do not delegate.** |
+| ideate, brainstorm, office-hours | `/office-hours` |
+| hard-truths, yolo | `/ops:ops-yolo` |
+| spec, specify, scope, issue | `/spec $REST` |
+| plan, roadmap, phase-plan | **project** → `gsd-plan-phase`; **ad-hoc** → `/autoplan` |
+| ultraplan, deep-plan | `gsd-ultraplan-phase` |
+| design, ui, mockup, html | `/design-consultation $REST` |
+| build, execute, implement, code | **project** → `gsd-execute-phase`; **multi-project** → `gsd-master-orchestrator`; **ad-hoc** → direct edits in an isolated worktree |
+| review, code-review, cr | `/review` — **project** also runs `gsd-code-review` |
+| security, cso, sec-review | `/cso` |
+| test, qa | `/qa $REST` — **project** also runs `gsd-verify-work` |
+| ios-qa, ios-test | `/ios-qa` |
+| ship, land | **project** → `gsd-ship`; **ad-hoc single-repo** → `/ship`; **multi-repo salvage** → `/ops:ops-merge` |
+| deploy, release, rollout | `/ops:ops-deploy` then `/canary` |
+| canary | `/canary` |
+| monitor, fires, incidents | `/ops:ops-fires` |
+| status, health | `/ops:ops-status` |
+| retro, reflect | `/retro` |
+| learn | `/learn` |
+| ops, inbox, comms, marketing, finops, voice, home, daemon | `/ops:ops $ARGUMENTS` (hand the whole arg string to the ops sub-router) |
+| projects, portfolio | `/ops:ops-projects` |
+
+### Routing notes
+
+- **`$REST`** = `$ARGUMENTS` with the leading intent token removed.
+- **Mode resolution**: use the `MODE=` line from `flow-state`. PROJECT when
+ the git root has `.planning/`; AD-HOC otherwise. "multi-project" = the user
+ named >1 repo/project or asked for portfolio-wide work.
+- **Delegation only.** This skill never does the work itself — it invokes the
+ canonical command via the `Skill` tool (or prints the route if the target is
+ a personal/plugin slash-command the model should call next). After routing,
+ the target skill's own `## CLI/API Reference` governs execution.
+- **Ambiguity**: if intent spans two stages, prefer the earliest unfulfilled
+ stage for the current `flow-state` position.
+- **`ops` passthrough**: for any `ops*` intent, forward the *entire*
+ `$ARGUMENTS` to `/ops:ops` — it has its own sub-router; do not pre-parse it.
+
+### Bare `/flow`
+
+If `$ARGUMENTS` is empty: `Read FLOW.md`, then run `bin/flow-state`, and
+present the lifecycle map with the current position highlighted. Offer the
+next canonical stage as the suggested action. **Do not auto-advance.**
+
+## CLI/API Reference
+
+Router only — no direct tool calls. `bin/flow-state` is the sole helper
+(detects mode + position). All execution is delegated to the canonical
+target skill after routing.