@curdx/flow 1.1.3 → 1.1.5

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "curdx-flow-marketplace",
+  "owner": {
+    "name": "wdx",
+    "email": "bydongxin@gmail.com"
+  },
+  "metadata": {
+    "description": "CurDX-Flow marketplace — distributes the curdx-flow meta-framework plugin",
+    "version": "1.1.5"
+  },
+  "plugins": [
+    {
+      "name": "curdx-flow",
+      "source": "./",
+      "description": "AI engineering workflow meta-framework — spec-driven + autonomous execution + quality gates + multi-agent collaboration",
+      "keywords": [
+        "workflow",
+        "spec-driven",
+        "ai-engineering",
+        "orchestration"
+      ],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "curdx-flow",
+  "version": "1.1.5",
+  "description": "AI engineering workflow meta-framework — spec-driven + autonomous execution + quality gates + multi-agent collaboration. Distills Karpathy + BMAD + GSD + Ralph + Superpowers + GStack and orchestrates context7 / sequential-thinking / chrome-devtools / frontend-design / claude-mem / pua dependencies.",
+  "author": {
+    "name": "wdx",
+    "email": "bydongxin@gmail.com"
+  },
+  "homepage": "https://github.com/wdx/curdx-flow",
+  "repository": "https://github.com/wdx/curdx-flow",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "spec-driven",
+    "ai-engineering",
+    "orchestration",
+    "karpathy",
+    "claude-code"
+  ],
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp@latest"
+      ]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "chrome-devtools-mcp@latest"
+      ]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,279 @@
+# Changelog
+
+All notable changes to CurDX-Flow will be documented here.
+
+## [1.1.1] - 2026-04-20
+
+### Fixed
+- **Plugin load failure** — removed the explicit `"hooks": "./hooks/hooks.json"` declaration from `plugin.json`.
+  Claude Code auto-loads the default path `hooks/hooks.json`; declaring it explicitly caused a duplicate-hook-file
+  error. Symptom: `claude plugin list` showed `Status: ✘ failed to load`.
+- The local `claude --plugin-dir` mode does not trigger duplicate detection, so all 8 rounds of dev-time validation
+  passed; only a real marketplace install exposed this bug (lesson from the first publish).
+
+## [1.1.0] - 2026-04-20
+
+### Changed — **BREAKING**: command namespacing
+
+All 31 commands moved from `/flow-<name>` to **`/curdx-flow:<name>`** (Claude Code's native plugin namespace).
+
+**Migration map (old → new)**:
+- `/flow-init` → `/curdx-flow:init`
+- `/flow-start` → `/curdx-flow:start`
+- `/flow-research` → `/curdx-flow:research`
+- `/flow-requirements` → `/curdx-flow:requirements`
+- `/flow-design` → `/curdx-flow:design`
+- `/flow-tasks` → `/curdx-flow:tasks`
+- `/flow-spec` → `/curdx-flow:spec`
+- `/flow-implement` → `/curdx-flow:implement`
+- `/flow-verify` → `/curdx-flow:verify`
+- `/flow-review` → `/curdx-flow:review`
+- `/flow-audit` → `/curdx-flow:audit`
+- `/flow-debug` → `/curdx-flow:debug`
+- `/flow-triage` → `/curdx-flow:triage`
+- `/flow-discuss` → `/curdx-flow:discuss`
+- `/flow-party` → `/curdx-flow:party`
+- `/flow-qa` → `/curdx-flow:qa`
+- `/flow-sketch` → `/curdx-flow:sketch`
+- `/flow-security` → `/curdx-flow:security`
+- `/flow-index` → `/curdx-flow:index`
+- `/flow-doctor` → `/curdx-flow:doctor`
+- `/flow-status` → `/curdx-flow:status`
+- `/flow-switch` → `/curdx-flow:switch`
+- `/flow-help` → `/curdx-flow:help`
+- `/flow-install-deps` → `/curdx-flow:install-deps`
+- `/flow-fast` → `/curdx-flow:fast`
+- `/flow-spike` → `/curdx-flow:spike`
+- `/flow-plan-ceo` → `/curdx-flow:plan-ceo`
+- `/flow-plan-eng` → `/curdx-flow:plan-eng`
+- `/flow-plan-design` → `/curdx-flow:plan-design`
+- `/flow-plan-dx` → `/curdx-flow:plan-dx`
+- `/flow-autoplan` → `/curdx-flow:autoplan`
+
+### Changed
+- Renamed `commands/flow-*.md` to `commands/*.md` (history preserved via `git mv`)
+- Each command's `name: flow:xxx` frontmatter changed to `name: xxx`
+- 78 doc files updated for a total of 594 + 38 command references
+- Template strings that dynamically generate command names (help/switch/start/spec) updated in lockstep
+- `plugin.json` / `marketplace.json` version: 1.0.0 → 1.1.0
+
+### Unchanged (intentional)
+- `agents/flow-*.md` file paths (agent internal namespace, not commands)
+- `CHANGELOG.md` historical entries (history is not rewritten)
+- References to future Phase 6+ commands (e.g. `/curdx-flow:ship`, marked "not implemented")
+
+### Why
+Claude Code natively supports the `<plugin-name>:<command>` namespace, which avoids collisions with other plugins'
+`/flow-*` commands and makes provenance clearer. When users see `/curdx-flow:start` they immediately know it
+belongs to curdx-flow.
+
+### Migration
+Old commands no longer work. If your scripts or docs reference the old names, do a global replace
+`/flow-` → `/curdx-flow:` (note: agent file paths `agents/flow-*.md` stay unchanged).
+
+## [1.0.0] - 2026-04-20
+
+### Added — Phase 7: Polish & Release
+
+- **7 complete user docs** (`docs/*.md`):
+  - `getting-started.md` — 5-minute on-ramp
+  - `command-reference.md` — all 31 commands grouped by family
+  - `agent-reference.md` — all 24 agents (15 functional + 9 personas)
+  - `workflows.md` — 5 typical workflows (greenfield/brownfield/epic/fast/ui-heavy)
+  - `architecture.md` — technical architecture (hook system / strategy router / gate composition / extension points)
+  - `ethos.md` — design philosophy (five pillars / credits / trade-offs / anti-patterns)
+  - `troubleshoot.md` — symptom-indexed troubleshooting
+- **README upgrade** (English + Chinese) — added badges / overview list / Quick Start / credits / explicit "skipped" notes
+
+### Changed
+- `plugin.json` version: 0.6.0 → **1.0.0** (Polish complete = official 1.0 release)
+
+### Design Decision
+- v1.0 marks "feature-complete + publishable"
+- Subsequent versioning is semantic:
+  - 1.0.x patch — doc fixes, hook fixes
+  - 1.x.0 minor — new commands / new agents / new gates
+  - 2.0.0 major — breaking changes (e.g. frontmatter schema change)
+- **Phase 6 intentionally skipped** (ship/land/canary/retro) — low ROI for private repos
+
+## [0.6.0] - 2026-04-19
+
+### Added — Phase 5: Tools & UI
+
+- **4 tool-class agents** (`agents/*.md`):
+  - `flow-qa-engineer` — runs real-browser QA via the chrome-devtools MCP, capturing bugs / performance / accessibility
+  - `flow-ux-designer` — invokes the frontend-design skill to generate HTML variants
+  - `flow-security-auditor` — OWASP Top 10 + STRIDE + npm audit
+  - `flow-ui-researcher` — UI pattern research; scans codebase + WebSearch + screenshots
+- **2 new gates** (`gates/*.md`):
+  - `security-gate` — SR blocking red lines (hard-coded credentials, injection, sensitive logging) + SW warnings + SM mandatory items
+  - `devex-gate` — 8 dimensions (naming/comments/structure/error-handling/setup/types/tests/dev loop)
+- **4 tool commands**:
+  - `/curdx-flow:qa [--url=...]` — dispatches Oliver for browser QA
+  - `/curdx-flow:sketch "<description>"` — dispatches Emma to generate UI variants
+  - `/curdx-flow:security` — dispatches Serena for security audit
+  - `/curdx-flow:index [--force]` — scans a brownfield codebase and generates an index
+- **5 Planning Review commands** (inherited from gstack and extended):
+  - `/curdx-flow:plan-ceo` — strategic-layer review (scope / ROI / opportunity cost)
+  - `/curdx-flow:plan-eng` — engineering-layer review (architecture lock / risks)
+  - `/curdx-flow:plan-design` — UI/UX review (accessibility / design system)
+  - `/curdx-flow:plan-dx` — DevEx review (8-dimension scoring)
+  - `/curdx-flow:autoplan` — runs the 4 reviews above in parallel and aggregates findings
+- **New knowledge doc** (`knowledge/planning-reviews.md`) — 4-dimension methodology + when to use + when to skip
+
+### Changed
+- `plugin.json` version: 0.5.1 → 0.6.0
+
+## [0.5.1] - 2026-04-19
+
+### Added — Wave Execution complete (Phase 2 follow-up)
+
+- **`knowledge/wave-execution.md`** — DAG analysis algorithm, parallel dispatch mechanism,
+  conflict detection (pre + post), failure strategy, configuration notes, 3 file-conflict scenarios
+- **`commands/curdx-flow:implement.md`** wave section expanded from a 20-line concept sketch
+  to a complete 6-step execution flow: DAG analysis → pre-conflict check → single-message
+  parallel Task dispatch → result aggregation → failure handling → progress feedback
+
+### Changed
+- `plugin.json` version: 0.5.0 → 0.5.1
+
+## [0.5.0] - 2026-04-19
+
+### Added — Phase 4: Advanced (Triage / Party / Debug / Personas)
+
+- **2 new functional agents**:
+  - `flow-triage-analyst` — Epic vertical-slice decomposition, splitting by user value (not technical layer); produces a dependency graph + frozen shared interfaces
+  - `flow-debugger` — systematic 4-stage debugging (root cause → pattern → hypothesis → fix); ≥3 failures triggers an architecture challenge
+- **9 persona agents** (`agents/persona-*.md`) — BMAD-style personalization:
+  - Mary (Senior Analyst → flow-researcher)
+  - John (Product Manager → flow-product-designer)
+  - Winston (Architect → flow-architect)
+  - Amelia (Developer → flow-executor)
+  - Rachel (Code Reviewer → flow-reviewer)
+  - David (Debugger → flow-debugger)
+  - Oliver (QA Engineer → flow-edge-hunter + Phase 5+ flow-qa-engineer)
+  - Serena (Security Auditor → Phase 5+ flow-security-auditor)
+  - Emma (UX Designer → Phase 5+ flow-ux-designer)
+- **4 new commands**:
+  - `/curdx-flow:triage "<epic goal>"` — dispatches flow-triage-analyst to slice the Epic vertically
+  - `/curdx-flow:discuss` — captures key decisions (D-NN), writes to STATE.md + .progress.md
+  - `/curdx-flow:party <personas...> "<question>"` — multiple personas reason in parallel and independently (true multi-agent, not single-LLM role-play)
+  - `/curdx-flow:debug "<bug>"` — dispatches David / flow-debugger for systematic 4-stage debugging
+- **2 new knowledge docs**:
+  - `knowledge/epic-decomposition.md` — vertical slice vs horizontal layer, dependency types, shared-interface freeze
+  - `knowledge/systematic-debugging.md` — full 4-stage methodology + forbidden anti-patterns
+
+### Changed
+- `plugin.json` version: 0.4.0 → 0.5.0
+
+## [0.4.0] - 2026-04-19
+
+### Added — Phase 3: Gates & Review
+
+- **6 core gates** (`gates/*.md`) — composable quality-gate definitions:
+  - `karpathy-gate` (always-on, blocking) — code-level checks for the 4 principles
+  - `verification-gate` (always-on, blocking) — completion claims require fresh evidence
+  - `tdd-gate` (standard, blocking) — RED → GREEN → YELLOW enforcement + exemption paths
+  - `coverage-audit-gate` (standard, blocking) — 4-source (FR/AD/Research/D-NN) coverage audit
+  - `adversarial-review-gate` (enterprise, warning) — zero-findings forbidden + minimum findings across 3 categories
+  - `edge-case-gate` (enterprise, warning) — 7 categories of edge cases + test-gap checklist
+- **4 review agents** (`agents/*.md`):
+  - `flow-verifier` — goal-backward verification; detects stubs / fake completions
+  - `flow-reviewer` — Two-Stage Review (Stage 1 spec compliance + Stage 2 code quality)
+  - `flow-adversary` — adversarial review; 6 dimensions × 2 rounds of sequential-thinking
+  - `flow-edge-hunter` — hunts 7 categories of edge cases; generates a test-gap checklist
+- **3 new commands** (`commands/*.md`):
+  - `/curdx-flow:verify` — goal-backward verification (dispatches flow-verifier)
+  - `/curdx-flow:review [--adversarial|--edge-case|--both]` — Two-Stage Review with optional adversarial / edge-case scan
+  - `/curdx-flow:audit` — multi-source coverage audit (tasks-vs-specs cross-check)
+- **New knowledge doc** (`knowledge/two-stage-review.md`) — Stage 1/2 design principles + typical anti-patterns
+
+### Changed
+- `plugin.json` version: 0.3.0 → 0.4.0
+
+## [0.3.0] - 2026-04-19
+
+### Added — Phase 2: Execution Engine
+
+- **flow-executor agent** (`agents/flow-executor.md`) — core execution agent:
+  - Executes a single task with POC-First + TDD
+  - Verify must pass
+  - Atomic commits in conventional-commit format
+  - Emits `TASK_COMPLETE` / `TASK_FAILED` / `ALL_TASKS_COMPLETE` markers
+  - 5-round retry mechanism (pua-style pressure escalation)
+- **2 new knowledge docs**:
+  - `knowledge/execution-strategies.md` — 4 execution strategies in detail (linear / subagent / stop-hook / wave / auto)
+  - `knowledge/atomic-commits.md` — atomic-commit rules + conventional-commit format
+- **2 new hook scripts**:
+  - `hooks/scripts/stop-watcher.sh` — StopHookLoop implementation (detects `ALL_TASKS_COMPLETE`, tracks failure count, prevents infinite loops)
+  - `hooks/scripts/quick-mode-guard.sh` — Quick Mode blocks AskUserQuestion (so the autonomous loop does not stall)
+- **`hooks.json`** registers the new hooks:
+  - `Stop` → stop-watcher.sh
+  - `PreToolUse(AskUserQuestion)` → quick-mode-guard.sh
+- **3 new commands**:
+  - `/curdx-flow:implement` — main execute command, with Strategy Router (`--strategy=auto|linear|subagent|stop-hook|wave`, `--task=X.Y`, `--quick`)
+  - `/curdx-flow:fast` — skip the spec, implement directly (one-shot tasks)
+  - `/curdx-flow:spike` — feasibility experiment (2–5 small tests to validate a hypothesis)
+
+### Changed
+- `plugin.json` version: 0.2.0 → 0.3.0
+
+## [0.2.0] - 2026-04-19
+
+### Added — Phase 1: Spec Engine
+
+- **5 spec templates** (`templates/*.tmpl`):
+  - `research.md.tmpl` — research report structure
+  - `requirements.md.tmpl` — user stories + acceptance criteria + FR/NFR
+  - `design.md.tmpl` — architecture decisions + component boundaries + mermaid diagrams
+  - `tasks.md.tmpl` — POC-First 5 Phases + coverage audit
+  - `progress.md.tmpl` — progress log + learnings
+- **3 JSON Schemas** (`schemas/*.schema.json`):
+  - `spec-state.schema.json` — cross-session state
+  - `config.schema.json` — project configuration
+  - `spec-frontmatter.schema.json` — spec file YAML frontmatter
+- **2 knowledge docs** (`knowledge/*.md`):
+  - `spec-driven-development.md` — SDD methodology
+  - `poc-first-workflow.md` — POC-First 5 Phases
+- **4 functional agents** (`agents/*.md`):
+  - `flow-researcher` — deep research (context7 + claude-mem + sequential-thinking ≥5 rounds + WebSearch)
+  - `flow-product-designer` — user stories + acceptance criteria + FR/NFR
+  - `flow-architect` — architecture design (sequential-thinking ≥8 rounds + context7 to validate technology choices)
+  - `flow-planner` — POC-First decomposition + multi-source coverage audit
+- **7 new commands** (`commands/*.md`):
+  - `/curdx-flow:start` — intelligent entry (new spec / resume spec)
+  - `/curdx-flow:switch` — switch the active spec
+  - `/curdx-flow:research` — dispatches flow-researcher
+  - `/curdx-flow:requirements` — dispatches flow-product-designer
+  - `/curdx-flow:design` — dispatches flow-architect
+  - `/curdx-flow:tasks` — dispatches flow-planner
+  - `/curdx-flow:spec` — runs the 4 phases sequentially in one shot
+
+### Changed
+- `plugin.json` version: 0.1.0 → 0.2.0
+
+## [0.1.0] - 2026-04-19
+
+### Added — Phase 0: Foundation
+
+- Project skeleton for Claude Code plugin
+- `plugin.json` with inline `mcpServers` declaring 3 auto-installed MCPs:
+  - `context7` — latest documentation fetcher
+  - `sequential-thinking` — structured reasoning
+  - `chrome-devtools` — browser automation
+- `marketplace.json` for future plugin market publishing
+- Hook system:
+  - `SessionStart` — dependency check + project state load
+  - `InstructionsLoaded` — inject Karpathy L1 baseline
+  - `PostToolUseFailure` — fail counter (pua integration prep)
+- Shared agent preamble (`agent-preamble/preamble.md`) — enforces `context7` / `sequential-thinking` / `claude-mem` usage in all agents
+- Core commands:
+  - `/curdx-flow:init` — initialize `.flow/` project structure
+  - `/curdx-flow:install-deps` — one-click install of recommended plugins (pua, claude-mem, frontend-design)
+  - `/curdx-flow:doctor` — dependency health check
+  - `/curdx-flow:status` — project & spec status
+  - `/curdx-flow:help` — smart help
+- Document templates (`templates/*.tmpl`) for PROJECT/CONTEXT/STATE/ROADMAP/config
+- Knowledge base (`knowledge/karpathy-guidelines.md`) for agents to `@`-reference
+- CLAUDE.md with L1-L4 rules
+- README (English + Chinese) + LICENSE (MIT)

package/agent-preamble/preamble.md

@@ -0,0 +1,214 @@
+# CurDX-Flow Agent Shared Preamble
+
+> All `flow-*` agents and commands inherit this file via `@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md`.
+> This is a behavioral baseline, not a suggestion. Violation counts as agent failure.
+
+---
+
+## L1: Karpathy Mind Baseline (hard rules)
+
+### 1. Think Before Coding
+- State your assumptions before starting
+- When uncertain, use AskUserQuestion — do not silently assume
+- Offer multiple interpretations and let the user choose
+- Never skip "understanding" and jump straight to "implementation"
+
+### 2. Simplicity First
+- YAGNI principle
+- No features beyond what was requested
+- No single-use abstractions
+- If 200 lines suffice, do not write 1000
+
+### 3. Surgical Changes
+- Modify only the lines that must change
+- Match existing style (indentation, naming, quotes)
+- Do not delete pre-existing dead code
+- Only clean up orphan code that you yourself created
+
+### 4. Goal-Driven Execution
+- Define a verifiable success criterion
+- Do not say done/fixed/working without evidence
+- Tests first, goals first
+
+---
+
+## L2: Mandatory Tool Rules (enforced)
+
+### Documentation lookup → context7 MCP
+
+For any question involving a library / framework / SDK / CLI / API:
+
+```
+1. mcp__context7__resolve-library-id("react")     → resolve library ID
+2. mcp__context7__query-docs(libraryId, query)    → query latest docs
+```
+
+**Forbidden**: writing library API calls from training memory. Training data may be stale.
+
+**Fallback**: when context7 MCP is unavailable, use WebSearch with a version number, and annotate the output with
+"⚠️ context7 unavailable — documentation may not be current".
+
+---
+
+### Structured thinking → sequential-thinking MCP
+
+For the following scenarios, sequential-thinking is mandatory beforehand:
+
+- Planning (≥5 thoughts)
+- Architecture design (≥8 thoughts)
+- Epic decomposition (≥10 thoughts)
+- Adversarial review (≥6 thoughts)
+- Complex bug root-cause analysis (≥5 thoughts)
+
+```
+mcp__sequential-thinking__sequentialthinking({
+  thought: "...",
+  thoughtNumber: N,
+  totalThoughts: M,
+  nextThoughtNeeded: true/false
+})
+```
+
+**Fallback**: when seq-think is unavailable, simulate it inside `<thinking>...</thinking>` blocks
+in the response, still listing numbered thoughts (at least 5).
+
+---
+
+### Historical context → claude-mem (if installed)
+
+Before starting any task (**especially the planning phase**):
+
+```
+mcp__claude_mem__search("<task keywords>")
+  → if relevant observations exist:
+mcp__claude_mem__get_observations([ids])
+  → fold the relevant history into your decisions
+```
+
+**Fallback**: when claude-mem is not installed, read the `decisions` array in `.flow/STATE.md`
+and `.flow/specs/*/.progress.md` for project-level history.
+
+---
+
+### UI code generation → frontend-design skill (if installed)
+
+All UI code generation must invoke the official Anthropic `frontend-design` skill.
+
+**Fallback**: when the skill is unavailable, use Tailwind CSS + shadcn/ui defaults.
+
+---
+
+### Browser QA → chrome-devtools MCP
+
+UI testing, performance traces, console inspection, network analysis:
+
+```
+mcp__chrome_devtools__*
+```
+
+**Fallback**: when the MCP is unavailable, produce a manual test checklist and explicitly tell the user.
+
+---
+
+## L3: Three Red Lines (inherited from pua, universal)
+
+Self-check before every agent output:
+
+### 1. Closed loop
+> Claiming "done / fixed / passed"? Provide evidence.
+
+- ✗ "I fixed the bug"
+- ✓ "I fixed the bug. `npm test` output: `✓ 42 tests passed` (log attached)"
+
+### 2. Fact-driven
+> Verify before saying "maybe" or "probably".
+
+- ✗ "This is probably a permission issue"
+- ✓ "I ran `ls -la config.json` and saw permissions `-rw-------`, unreadable by user. Fix: `chmod 644`"
+
+### 3. Exhaust everything
+> Before saying "I cannot", complete the systematic 4-stage debugging.
+
+1. **Root-cause investigation**: read the error → reproduce → check recent changes → trace the data flow
+2. **Pattern analysis**: find a working counter-example to compare against
+3. **Hypothesize and test**: form a single hypothesis → minimal test → verify
+4. **Implement the fix**: write a failing test → fix the root cause → verify
+
+If ≥3 fix attempts fail, stop and challenge the architecture (rather than continuing to patch blindly).
+
+---
+
+## L4: State-Reading Conventions
+
+### Read before every task
+
+1. `.flow/PROJECT.md` — project vision
+2. `.flow/CONTEXT.md` — user preferences
+3. `.flow/STATE.md` — cross-session state + decisions
+4. `.flow/specs/<active>/.progress.md` — current spec progress
+5. `.flow/.active-spec` — name of the currently active spec
+
+### Update after every task
+
+1. Update `.progress.md` with what you learned (gotchas, patterns, decisions)
+2. Update `.state.json` to advance the state machine (phase, taskIndex, etc.)
+3. If a significant decision was made, append to the `decisions` array in `STATE.md` (D-NN format)
+
+---
+
+## L5: Atomic Commit Convention
+
+One commit per logical unit:
+
+```
+<type>(<scope>): <summary>
+
+[body — explain why, not what]
+
+Decisions: D-01, D-02  (when referencing user decisions)
+```
+
+**Types**:
+- `feat` — new feature
+- `fix` — bug fix
+- `refactor` — refactor (behavior unchanged)
+- `test` — tests (TDD: red/green/yellow)
+- `docs` — documentation
+- `chore` — miscellaneous
+
+**TDD stage markers**:
+- `test(scope): red - add failing test for X`
+- `feat(scope): green - implement X to pass test`
+- `refactor(scope): yellow - clean up X`
+
+---
+
+## L6: Anti-Patterns (forbidden)
+
+Patterns every agent must avoid:
+
+- ✗ Starting work without reading `.flow/` state
+- ✗ Claiming completion without running a verification command
+- ✗ "should / probably / seems" as a conclusion (unless explicitly labeled as an assumption)
+- ✗ Skipping context7 and writing library calls directly
+- ✗ Skipping sequential-thinking and giving an architecture decision directly
+- ✗ Refactoring while fixing a bug (violates the surgical-changes rule)
+- ✗ Adding features beyond what was requested (violates YAGNI)
+- ✗ Creating `*.md` documentation or README files unless the user explicitly asked for them
+
+---
+
+## L7: Delegation Convention (sub-agent dispatch)
+
+When you need to delegate to a sub-agent:
+
+1. Give the sub-agent **complete task context** (it cannot read the conversation history)
+2. State the **input paths** and **output paths** explicitly
+3. State the **success criteria** explicitly (must be verifiable)
+4. State the **forbidden behaviors** explicitly (cf. L6)
+5. After the sub-agent finishes, the parent agent **reads the output** and reviews it
+
+---
+
+**Remember**: this preamble exists because, without discipline, AI tends to slack off, hallucinate, and over-engineer.
+These rules are not constraints — they are the tools that make you reliable.