@mhd-ghaith-abtah/flow 0.7.2-beta.0

package/templates/flow.config.yaml.tmpl

@@ -0,0 +1,94 @@
+# Flow project configuration — generated by /flow-init.
+# Re-run /flow-init --update to regenerate. Hand-edit when needed.
+#
+# This file is intended to be **committed** — it captures team-wide conventions
+# (adapter choices, review policy, verify command, etc) with no secrets. Per-
+# developer overrides live in `flow.config.local.yaml` (gitignored) which Flow
+# merges on top of this one when both are present. Secrets live in
+# `~/.claude/.env.flow` (chmod 600, never committed).
+
+version: 1
+generated: {{date}}
+flow_version: {{flow_version}}
+
+# Mode controls how much ceremony flow-story applies per story.
+mode: {{mode}}                          # mini | standard | team
+
+# File paths (relative to project root)
+sprint_file:   docs/flow/sprint.yaml
+stories_dir:   docs/flow/stories
+journeys_dir:  docs/flow/journeys
+retros_dir:    docs/flow/retros
+archive_dir:   docs/flow/archive
+deferred_file: docs/flow/deferred.md
+artifacts_dir: docs/flow/artifacts
+
+# Active adapters — pick one per category. Swap with /flow adapter swap.
+adapters:
+  issue_tracker: {{adapters.issue_tracker}}    # linear | github-issues | none | ...
+  pr:            {{adapters.pr}}                # github | gitlab | none | ...
+  e2e:           {{adapters.e2e}}               # playwright-mcp | playwright-cli | none | ...
+  verify:        {{adapters.verify}}            # make | pnpm | custom | ...
+
+# Adapter config (consumed by the active adapters above)
+integrations:
+{{#if adapters.issue_tracker == 'github-issues'}}
+  issue_tracker:
+    repo: {{integrations.issue_tracker.repo}}
+    label_prefix: flow
+{{/if}}
+{{#if adapters.issue_tracker == 'linear'}}
+  issue_tracker:
+    team_key: {{integrations.issue_tracker.team_key}}
+{{/if}}
+{{#if adapters.e2e == 'playwright-mcp'}}
+  e2e:
+    base_url: {{integrations.e2e.base_url}}
+    journeys_dir: docs/flow/journeys
+    viewport: { width: 1280, height: 720 }
+{{/if}}
+{{#if adapters.verify == 'pnpm'}}
+  verify:
+    script: {{integrations.verify.script}}
+{{/if}}
+{{#if adapters.verify == 'custom'}}
+  verify:
+    command: "{{integrations.verify.command}}"
+{{/if}}
+
+# Review behaviour
+review:
+  use_separate_model: {{review.use_separate_model}}    # team mode → true; spawns reviewer agent with model override
+  auto_hard_review_tags: [auth, payments, migration, pii, security]
+  language_reviewer: {{review.language_reviewer}}      # e.g. typescript-reviewer | python-reviewer | null
+  barrier_timeout_seconds: 900                          # max wall-clock to wait on background reviewers before halting (default 15 min)
+
+# PR behaviour
+pr:
+  auto_merge_wait_seconds: 90                           # single bounded wait under --auto-merge; CI longer than this → end turn + handoff
+
+# Implementation behaviour
+implement:
+  default: prp-implement                                # or 'direct' (no /prp-implement wrapper)
+  use_tdd: {{implement.use_tdd}}                        # invoke /tdd before /prp-implement
+  e2e_auto_trigger_tags: [ui, e2e, marketing, navigation]
+  docs_auto_trigger: {{implement.docs_auto_trigger}}    # always run /update-docs in commit phase
+
+# Secrets storage (used by env-var-auth MCPs)
+secrets:
+  store: {{secrets.store}}                              # env_file | shell | onepassword
+
+# Reference docs (Flow does NOT regenerate these — just paths for context)
+reference_docs:
+{{#each reference_docs}}
+  - {{this}}
+{{/each}}
+
+# Upstream installs (recorded for repair / update)
+upstreams:
+  bmad:
+    installed: {{upstreams.bmad.installed}}
+    subset: {{upstreams.bmad.subset}}
+  ecc:
+    installed: {{upstreams.ecc.installed}}
+    subset: {{upstreams.ecc.subset}}

package/templates/pr.md.tmpl

@@ -0,0 +1,40 @@
+## Summary
+
+{{summary}}
+
+{{issue_ref}}
+
+## What changed
+
+{{#each changes}}
+- {{this}}
+{{/each}}
+
+## Test plan
+
+{{#each acceptance_criteria}}
+- [ ] {{this}}
+{{/each}}
+
+{{#if has_e2e}}
+## E2E
+
+Journey ran against {{base_url}}. Artifacts at `docs/flow/artifacts/{{story_id}}/`.
+
+{{#each e2e_passed}}
+- ✓ {{this}}
+{{/each}}
+{{/if}}
+
+{{#if has_verify}}
+## Verify
+
+```bash
+$ {{verify_cmd}}
+{{verify_summary}}
+```
+{{/if}}
+
+---
+
+🌊 Created via [Flow](https://github.com/mhd-ghaith-abtah/flow) · story `{{story_id}}`

package/templates/retro.md.tmpl

@@ -0,0 +1,58 @@
+# {{epic_id}} — {{epic_title}} — Retro
+
+*Generated by /flow-sprint retro on {{date}}*
+
+## Shipped
+
+- **{{shipped_count}} stories**, {{commit_count}} commits, {{pr_count}} PRs
+- **Cycle time:** {{avg_cycle_days}} days/story (median {{median_cycle_days}})
+- **Date range:** {{date_start}} → {{date_end}}
+
+### Stories
+
+{{#each stories}}
+- ✓ {{this.id}}  {{this.title}}  ({{this.cycle_days}}d)
+{{/each}}
+
+## What worked
+
+<!-- 2-4 bullets. Concrete, not platitudes. Examples:
+  - Tokens-first approach kept components consistent (E1-002, E1-003 reused tokens cleanly)
+  - Playwright MCP smoke test caught a console error in E1-002 (PR #14)
+-->
+
+-
+
+## What didn't
+
+<!-- 1-3 bullets. Specific cases, not generalities. Examples:
+  - E1-004 theme switcher hit a Tailwind v4 SSR issue mid-implement; scope expanded — should have planned with /plan first
+  - Two deferred items still open (see deferred.md): X, Y
+-->
+
+-
+
+## Carry into next epic
+
+<!-- Adjustments to make next time. Examples:
+  - Always use /plan for stories tagged 'client-side'
+  - Add a `client_side: true` story field that triggers --plan auto
+-->
+
+-
+
+## Open deferred items at epic close
+
+{{#if open_deferred_count > 0}}
+{{#each open_deferred}}
+- {{this}}
+{{/each}}
+{{else}}
+*(none)*
+{{/if}}
+
+## Next
+
+```bash
+/flow-sprint add "<title>" --epic E{{next_epic_num}} --tags <list>
+```

package/templates/sprint.yaml.tmpl

@@ -0,0 +1,18 @@
+# Flow sprint state — single source of truth for story tracking.
+# Edit via /flow-sprint subcommands rather than by hand when possible.
+
+version: 1
+project: {{project_name}}
+generated: {{date}}
+last_updated: {{timestamp}}
+
+# STATUS LEGEND
+#   backlog    — not started
+#   doing      — branch checked out, work in progress
+#   review     — PR open, awaiting merge
+#   done       — PR merged, story archived
+#   cancelled  — abandoned (see story file Notes for reason)
+
+epics: []
+
+stories: []

package/templates/story.md.tmpl

@@ -0,0 +1,35 @@
+# {{story_id}} — {{title}}
+
+**Epic:** {{epic_id}} — {{epic_title}}
+{{#if issue}}**Issue:** {{issue}}{{/if}}
+**Tags:** {{tags_csv}}
+**Status:** {{status}}
+
+**Why:** {{why}}
+
+{{#if refs}}
+**Refs:**
+{{#each refs}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+## Acceptance
+{{#each acceptance_criteria}}
+- [ ] {{this}}
+{{/each}}
+
+## Files
+{{#each files}}
+- {{this}}
+{{/each}}
+
+{{#if has_e2e}}
+## E2E Journey
+- navigate /
+- assert visible "{{expected_heading}}"
+- assert no console errors
+{{/if}}
+
+## Notes
+<!-- Decisions, deferred items, follow-ups appear here during implementation. -->

package/tools/fix-caveman-shrink.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# tools/fix-caveman-shrink.sh — print the commands needed to fix a broken
+# caveman-shrink MCP registration.
+#
+# Background: caveman-shrink is an MCP *proxy* — it must wrap an upstream MCP
+# server (passed as extra command-line args). The Caveman installer sometimes
+# registers it standalone (no upstream args), which crashes the proxy on first
+# call with the error "-32000: server failed to start" because index.js exits
+# immediately at the "missing upstream command" guard.
+#
+# This script does NOT execute `claude mcp` for you — modifying MCP
+# registration affects every Claude Code session, so we print the exact
+# commands and let you run them yourself.
+#
+# Usage:
+#   tools/fix-caveman-shrink.sh                  # wraps context7 (default)
+#   tools/fix-caveman-shrink.sh playwright       # wrap a known preset
+#   tools/fix-caveman-shrink.sh 'npx -y @org/x'  # pass full upstream command
+
+set -euo pipefail
+
+UPSTREAM="${1:-context7}"
+
+# Bash 3.2 (macOS default) doesn't support associative arrays — use case.
+case "$UPSTREAM" in
+  context7)
+    UPSTREAM_CMD="npx -y @upstash/context7-mcp@latest"
+    ;;
+  playwright)
+    UPSTREAM_CMD="npx -y @playwright/mcp@latest"
+    ;;
+  filesystem)
+    UPSTREAM_CMD="npx -y @modelcontextprotocol/server-filesystem $HOME"
+    ;;
+  *)
+    # Treat as a literal upstream command.
+    UPSTREAM_CMD="$UPSTREAM"
+    UPSTREAM="(custom)"
+    ;;
+esac
+
+cat <<EOF
+━━━ fix-caveman-shrink ━━━
+
+caveman-shrink is registered standalone (no upstream wrap) — it will crash with
+\`-32000: server failed to start\` on the first call.
+
+To fix, run these two commands yourself (they modify your Claude Code MCP
+registration globally — review them before executing):
+
+  1. Remove the broken registration:
+
+       claude mcp remove caveman-shrink
+
+  2. Re-add it as a wrapper around '${UPSTREAM}' (${UPSTREAM_CMD}):
+
+       claude mcp add caveman-shrink -- npx caveman-shrink ${UPSTREAM_CMD}
+
+Verify:
+
+       claude mcp get caveman-shrink
+
+The fixed registration should show 'caveman-shrink' followed by the upstream
+command. Restart Claude Code if MCP isn't picked up.
+
+Known upstream presets: context7, playwright, filesystem.
+Or pass the full upstream command as a single arg.
+EOF

package/tools/lint-changelog.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// tools/lint-changelog.js — enforce CONTRIBUTING.md's "one-line entries" rule.
+//
+// CHANGELOG entries under ### Added / ### Changed / ### Fixed / ### Removed
+// must each be a single line. A wrapped entry (a continuation line that
+// doesn't start with `- `, `#`, or a blank line) is a violation. Excludes
+// indented continuation under fenced code blocks and list-of-list bullets.
+//
+// Exit codes:
+//   0 — all entries one-line
+//   1 — at least one wrapped entry
+//   2 — usage error / file not found
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const path = process.argv[2];
+if (!path) {
+  console.error('usage: lint-changelog.js <CHANGELOG.md>');
+  process.exit(2);
+}
+if (!existsSync(path)) {
+  console.error(`✗ File not found: ${path}`);
+  process.exit(2);
+}
+
+const text = readFileSync(resolve(path), 'utf-8');
+const lines = text.split('\n');
+
+let inEntrySection = false;
+let inCodeBlock = false;
+let currentEntryStart = -1;  // line number of the most recent `- ` entry, or -1
+const violations = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+
+  // Track fenced code blocks — entries inside them are not subject to the rule.
+  if (line.trim().startsWith('```')) {
+    inCodeBlock = !inCodeBlock;
+    continue;
+  }
+  if (inCodeBlock) continue;
+
+  // Entry sections start with `### Added | Changed | Fixed | Removed | Deprecated | Security`.
+  const sectionMatch = line.match(/^###\s+(Added|Changed|Fixed|Removed|Deprecated|Security)\b/);
+  if (sectionMatch) {
+    inEntrySection = true;
+    currentEntryStart = -1;
+    continue;
+  }
+
+  // Any other heading ends the entry section.
+  if (line.startsWith('#')) {
+    inEntrySection = false;
+    currentEntryStart = -1;
+    continue;
+  }
+
+  if (!inEntrySection) continue;
+
+  // Blank line ends the current entry (no continuation).
+  if (line.trim() === '') {
+    currentEntryStart = -1;
+    continue;
+  }
+
+  // Entry line starts with `- ` (top-level bullet).
+  if (line.startsWith('- ')) {
+    currentEntryStart = i + 1;  // 1-indexed
+    continue;
+  }
+
+  // Indented sub-bullet or literal block — allowed for nested lists.
+  if (line.startsWith(' ') || line.startsWith('\t')) {
+    continue;
+  }
+
+  // Otherwise it's wrapped prose (starts at column 0, follows a `- ` entry).
+  if (currentEntryStart > 0) {
+    violations.push({ entryLine: currentEntryStart, wrapLine: i + 1, sample: line.slice(0, 80) });
+    currentEntryStart = -1;  // only flag once per entry
+  }
+}
+
+if (violations.length === 0) {
+  console.log(`✓ CHANGELOG entries are one-line (${path})`);
+  process.exit(0);
+}
+
+console.error(`✗ Found ${violations.length} wrapped CHANGELOG entr${violations.length === 1 ? 'y' : 'ies'} in ${path}:`);
+for (const v of violations) {
+  console.error(`  Line ${v.wrapLine} continues the entry that started at line ${v.entryLine}:`);
+  console.error(`    "${v.sample}${v.sample.length === 80 ? '…' : ''}"`);
+}
+console.error('');
+console.error('CONTRIBUTING.md requires one-line entries. Move detail into a referenced doc or split into multiple entries.');
+process.exit(1);