@curdx/flow 2.2.3 → 2.2.5

package/README.md

@@ -1,153 +1,87 @@
 # CurdX-Flow
 
-> **Stop Claude Code from faking "done".**
-> Spec-driven workflow + goal-backward verification + Karpathy discipline.
+> Stop Claude Code from faking "done".
+> Spec-driven workflow, goal-backward verification, and Karpathy discipline for real feature delivery.
 
 [![npm version](https://img.shields.io/npm/v/@curdx/flow.svg)](https://www.npmjs.com/package/@curdx/flow)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![Plugin](https://img.shields.io/badge/claude--code-plugin-purple)](https://code.claude.com)
-[![Chinese (中文)](https://img.shields.io/badge/docs-Chinese%20(中文)-red)](./README.zh.md)
+[![Plugin](https://img.shields.io/badge/claude--code-plugin-blue)](https://code.claude.com)
 
----
+CurdX-Flow is a skill-first Claude Code plugin. The public surface stays small:
+11 slash commands, 5 auto-invoked skills, 16 internal agents, and a thin set of
+entry docs. The heavy workflow detail lives in `skills/*/references/` and
+`knowledge/`.
 
-## Why this exists
-
-Claude Code drifts. It claims features work without running the tests. It uses stale library APIs from its training data. It takes three questions worth of code and squeezes in six.
-
-CurdX-Flow is a thin **discipline layer** on top of Claude Code that makes non-trivial feature work actually work:
-
-1. **A spec workflow** (research → requirements → design → tasks) for features too big to vibe-code.
-2. **Goal-backward verification** that scans your implementation against your own FR / AC / AD and catches stubs, fake completions, and untested acceptance criteria.
-3. **Karpathy's 4 principles** (think-first, simplicity, surgical changes, goal-driven) enforced via always-on hooks and gates.
-
-Not a framework. Not a methodology library. A discipline layer.
-
-## Install (one command)
-
-Requires Claude Code v2.1.110+ (latest recommended). The installer checks your local `claude` binary and `curdx-flow doctor` warns if the version is too old for modern plugin dependency handling.
+## Install
 
 ```bash
 npx @curdx/flow install --all
 ```
 
-This installs the Claude Code plugin (fully offline from the npm package — no GitHub fetch), the official Context7 plugin, the required sequential-thinking MCP server, and four recommended companion plugins (pua, claude-mem, frontend-design, chrome-devtools-mcp).
-
-**Note:** If you're running this command inside the `curdx-flow` project directory itself, use `npx --ignore-existing @curdx/flow install --all` to avoid npx trying to use the local package without dependencies installed.
+Requires modern Claude Code and Node 18+. The install flow registers the plugin,
+required reasoning/doc tools, and recommended companion plugins. Run
+`npx @curdx/flow doctor` after install if anything looks off.
 
 ## 11 slash commands, that's it
 
-```
-/curdx-flow:init           Initialize .flow/ in the current project
-/curdx-flow:start          Create / resume / switch a feature spec
-/curdx-flow:status         Show state, artifact, and recovery status
-/curdx-flow:spec           Write or refresh the spec (--phase, --review flags)
-/curdx-flow:implement      Execute the tasks
-/curdx-flow:cancel         Cancel active execution without deleting artifacts
-/curdx-flow:verify         Goal-backward check ← the moat
-/curdx-flow:review         Two-stage code review
-/curdx-flow:fast           Skip spec for one-off tasks
-/curdx-flow:debug          Systematic 4-stage debugging
-/curdx-flow:help           Reference
+```text
+/curdx-flow:init           Initialize the .flow scaffold for the current repository.
+/curdx-flow:start          Create, resume, list, or switch the active feature spec.
+/curdx-flow:status         Show active spec health, progress, artifacts, and recovery hints.
+/curdx-flow:spec           Generate or refresh research, requirements, design, and tasks for the active spec.
+/curdx-flow:implement      Execute active-spec tasks with strategy routing and atomic progress.
+/curdx-flow:cancel         Cancel the active execution loop or delete a spec with explicit confirmation.
+/curdx-flow:verify         Verify the active spec against code, tests, and browser evidence.
+/curdx-flow:review         Run two-stage review with optional adversarial, edge-case, and DevEx passes.
+/curdx-flow:fast           Execute a one-shot small task without creating a spec.
+/curdx-flow:debug          Debug a bug or failing test with the root-cause workflow.
+/curdx-flow:help           Show command detail, workflow guidance, and troubleshooting.
 ```
 
-Plus 5 auto-invoked skills (Claude picks them up from context): `epic`, `browser-qa`, `ui-sketch`, `security-audit`, `brownfield-index`.
+Plus 5 auto-invoked skills: `/curdx-flow:epic`, `/curdx-flow:browser-qa`,
+`/curdx-flow:ui-sketch`, `/curdx-flow:security-audit`,
+`/curdx-flow:brownfield-index`.
 
 ## Quick start
 
 ```bash
-# 1. In your project, initialize
 cd ~/your-project
 claude
 /curdx-flow:init
-
-# 2. Start a feature
 /curdx-flow:start jwt-auth "Add JWT authentication to the REST API"
-
-# 3. Generate the spec (research → requirements → design → tasks)
 /curdx-flow:spec
-
-# 4. Execute
 /curdx-flow:implement
-
-# 5. Verify + review
 /curdx-flow:verify
 /curdx-flow:review
 
-# Artifacts:
+# Main artifacts:
 #   .flow/specs/jwt-auth/verification-report.md
 #   .flow/specs/jwt-auth/review-report.md
 ```
 
-See [`docs/getting-started.md`](./docs/getting-started.md) for a five-minute walkthrough, or [`docs/workflows.md`](./docs/workflows.md) for typical scenarios (greenfield / brownfield / epic / fast / enterprise).
-
-## The three modes
-
-Set when you run `/curdx-flow:start --mode=<mode>`. Each mode decides which gates are enforced.
-
-| Mode | Workflow | Gates |
-|------|----------|-------|
-| `fast` | Skip the spec — just execute | karpathy + verification |
-| `standard` (default) | Full 4-phase spec | + tdd + coverage-audit |
-| `enterprise` | Full spec + planning review + adversarial + edge-case + security audit | All gates |
-
-## Upgrading from v1.x
-
-v2 is a major rewrite. Thirty slash commands became eleven. If you're coming from v1, see [`MIGRATION.md`](./MIGRATION.md) for the mapping table. If you'd rather stay on v1:
-
-```bash
-npm i -g @curdx/flow@^1.1
-```
-
-## What's in the box
-
-- **11 slash commands** + **5 auto-invoked skills** (the complete public surface)
-- **16 internal agents** that the commands dispatch (no user-visible personas — that was v1)
-- **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
-- **4 execution strategies** for `/curdx-flow:implement` (linear / subagent / stop-hook / wave, auto-routed)
-- **4 lifecycle hook events** plus a plugin-level subagent status line that enforce the discipline without user action
-- **Required docs/reasoning tools** — Context7 official plugin (MCP + skill + docs agent) and sequential-thinking MCP
-- **4 recommended companion plugins** — pua, claude-mem, frontend-design, chrome-devtools-mcp
-- **1 optional output style** — `CurdX Evidence-First` for concise, evidence-backed replies via `/config`
-- **1 default subagent status line** — CurDX-Flow agents show compact live rows in the Claude Code agent panel on modern Claude Code
-- **Plugin PATH helper** — `curdx-flow` is available inside Claude Code Bash sessions via the plugin `bin/` directory on modern Claude Code
-- **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
-
-## Documentation
-
-| Doc | When to read |
-|-----|--------------|
-| [`docs/getting-started.md`](./docs/getting-started.md) | First time — five-minute walkthrough |
-| [`docs/headless-ci.md`](./docs/headless-ci.md) | `claude -p`, CI, cron, and scripted automation |
-| [`docs/command-reference.md`](./docs/command-reference.md) | All 11 commands + 5 skills with flags |
-| [`docs/agent-reference.md`](./docs/agent-reference.md) | The 16 internal agents |
-| [`docs/workflows.md`](./docs/workflows.md) | Typical scenarios with exact command sequences |
-| [`docs/architecture.md`](./docs/architecture.md) | Internal design for contributors and extenders |
-| [`docs/ethos.md`](./docs/ethos.md) | Why we built it this way |
-| [`docs/troubleshoot.md`](./docs/troubleshoot.md) | Symptom-indexed fixes |
-| [`docs/releasing.md`](./docs/releasing.md) | Maintainer: how to cut a new version |
-| [`MIGRATION.md`](./MIGRATION.md) | v1 → v2 command mapping |
-
-## Credits
-
-CurdX-Flow v2 is a distillation, not an invention. Ideas we depend on:
-
-- [**Andrej Karpathy's 4 principles**](https://github.com/forrestchang/andrej-karpathy-skills) — the discipline foundation
-- [**GitHub Spec Kit**](https://github.com/github/spec-kit) — spec-driven development boiled down
-- [**superpowers**](https://github.com/obra/superpowers) — subagent discipline + TDD + two-stage review
-- [**pua**](https://github.com/tanweai/pua) — the three red lines
-- [**claude-mem**](https://github.com/thedotmack/claude-mem) — cross-session memory
-- **MCP / plugin ecosystem** — context7 (Upstash), sequential-thinking, chrome-devtools-mcp (Chrome DevTools team), frontend-design skill
+This produces a durable audit trail instead of a chat-only claim of completion.
 
-## License
+## What ships
 
-MIT. See [`LICENSE`](./LICENSE).
+- 11 slash commands and 5 auto-invoked skills
+- 16 internal agents
+- 8 composable gates
+- 4 execution strategies for `/curdx-flow:implement`
+- thin public docs, thick supporting references
 
-## Contributing
+## Docs
 
-- Issues: https://github.com/curdx/curdx-flow/issues
-- PRs: please eat your own dogfood — run `/curdx-flow:spec` on your own PR first
-- Be specific. No rage-at-the-LLM. The point is to make Claude reliable, not to whine about when it isn't.
+- [docs/getting-started.md](./docs/getting-started.md) for the first end-to-end walkthrough
+- [docs/command-reference.md](./docs/command-reference.md) for flags, strategy semantics, and specialty skill contracts
+- [docs/workflows.md](./docs/workflows.md) for greenfield, brownfield, epic, fast, and enterprise flows
+- [docs/headless-ci.md](./docs/headless-ci.md) for `claude --bare -p`, `system/init`, `system/plugin_install`, and CI patterns
+- [docs/troubleshoot.md](./docs/troubleshoot.md) for operator fixes
+- [docs/architecture.md](./docs/architecture.md) for the skill-first layout
+- [docs/agent-reference.md](./docs/agent-reference.md) for the 16 internal agents and their artifacts
 
----
+## Notes
 
-_CurDX = "Current Developer eXperience" in the AI-coding era._
+- `enterprise` mode turns on adversarial, edge-case, security, and DevEx gates.
+- `subagent` is serial; `wave` is the parallel strategy.
+- Headless usage should favor `claude --bare -p` and explicit `--plugin-dir`,
+  `--settings`, and `--mcp-config` wiring.

package/agents/flow-adversary.md

@@ -4,6 +4,7 @@ description: Use proactively when reviewing a spec or diff from an attacker or s
 model: opus
 effort: high
 maxTurns: 30
+color: red
 tools: [Read, Grep, Glob, Bash]
 ---
 

package/agents/flow-architect.md

@@ -5,29 +5,15 @@ memory: project
 model: opus
 effort: high
 maxTurns: 40
+color: cyan
 tools: [Read, Write, Grep, Glob, Bash, WebSearch]
 ---
 
-<output-discipline>
-**CRITICAL: Extreme concision required to prevent context overflow.**
-
-Your output must follow these rules:
-1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full design.md content. Do NOT paste content as assistant text.
-2. **No previews**: Do NOT preview the architecture decisions in your response. The file itself is the deliverable.
-3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
-4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
-   - Line 1: "✓ design.md generated"
-   - Line 2: "Architecture decisions: N"
-   - Line 3: "Components: N"
-   - Line 4: "Next: /curdx-flow:spec --phase=tasks"
-5. **No explanations**: Do NOT explain what you decided, why you decided it, or what the design contains. The file speaks for itself.
-
-**Violation of these rules = task failure.**
-</output-discipline>
-
 # Flow Architect — Architecture Design Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md
 
 ## Your Responsibility
 
@@ -185,14 +171,10 @@ Required sections:
 
 ## Output to User
 
-**CRITICAL: Follow <output-discipline> rules exactly. Output template:**
-
-```
-✓ design.md generated
-Architecture decisions: N
-Components: N
-Next: /curdx-flow:spec --phase=tasks
-```
+Follow `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`.
+After `Write` succeeds, emit the `design.md` contract from
+`${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md` and nothing
+else.
 
 **Forbidden output**: Core decisions summary, tech stack list, error path counts, warnings, review suggestions. The file speaks for itself.
 
@@ -211,14 +193,5 @@ Well-known stack assemblies honestly compress to: stack list with one-line justi
 
 ---
 
-<bookend>
-**Restated critical rules (output discipline):**
-
-1. Write first, explain never. Your FIRST action = Write tool call with full design.md.
-2. No previews. Do NOT paste architecture decisions in your response.
-3. Minimal status. Bullets only, one line each.
-4. Fixed output. Exactly 4 lines (see Output to User section).
-5. No explanations. Do NOT explain decisions, tech stack, or design content.
-
-**Violation of these rules = task failure. The file is the deliverable, not your explanation.**
-</bookend>
+The file is the deliverable. Keep the chat output to the shared compact summary
+only.

package/agents/flow-brownfield-analyst.md

@@ -5,29 +5,15 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 30
+color: blue
 tools: [Read, Write, Grep, Glob, Bash]
 ---
 
-<output-discipline>
-**CRITICAL: Extreme concision required to prevent context overflow.**
-
-Your output must follow these rules:
-1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full codebase-index.md content. Do NOT paste content as assistant text.
-2. **No previews**: Do NOT preview the codebase map in your response. The file itself is the deliverable.
-3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
-4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
-   - Line 1: "✓ codebase-index.md generated"
-   - Line 2: "Modules: N"
-   - Line 3: "Entry points: N"
-   - Line 4: "Next: /curdx-flow:start <feature-name>"
-5. **No explanations**: Do NOT explain the findings inline. The file speaks for itself.
-
-**Violation of these rules = task failure.**
-</output-discipline>
-
 # Flow Brownfield Analyst — Codebase Mapping Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md
 
 ## Your Responsibilities
 
@@ -150,4 +136,7 @@ Keep it short and reusable.
 
 ## Output to User
 
-**CRITICAL: Follow <output-discipline> exactly.**
+Follow `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`.
+After `Write` succeeds, emit the `codebase-index.md` contract from
+`${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md` and nothing
+else.

package/agents/flow-debugger.md

@@ -5,6 +5,7 @@ memory: project
 model: opus
 effort: high
 maxTurns: 40
+color: orange
 tools: [Read, Edit, Write, Bash, Monitor, Grep, Glob]
 ---
 

package/agents/flow-edge-hunter.md

@@ -4,6 +4,7 @@ description: Use proactively when a feature, spec, or diff needs a non-happy-pat
 model: sonnet
 effort: high
 maxTurns: 30
+color: purple
 tools: [Read, Grep, Glob, Bash]
 ---
 

package/agents/flow-executor.md

@@ -4,6 +4,7 @@ description: Use proactively when executing exactly one concrete task from tasks
 model: sonnet
 effort: medium
 maxTurns: 30
+color: green
 tools: [Read, Write, Edit, Bash, Grep, Glob]
 ---
 

package/agents/flow-planner.md

@@ -5,31 +5,16 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 30
+color: cyan
 tools: [Read, Write, Grep, Glob, Bash]
 ---
 
-<output-discipline>
-**CRITICAL: Extreme concision required to prevent context overflow.**
-
-Your output must follow these rules:
-1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full tasks.md content. Do NOT paste content as assistant text.
-2. **No previews**: Do NOT preview the task list in your response. The file itself is the deliverable.
-3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
-4. **Final output**: After Write succeeds, output EXACTLY 5 lines:
-   - Line 1: "✓ tasks.md generated"
-   - Line 2: "Total tasks: N"
-   - Line 3: "Coverage audit: [PASS/FAIL]"
-   - Line 4: "Phases: 1-5"
-   - Line 5: "Next: /curdx-flow:implement"
-5. **No explanations**: Do NOT explain what you did, why you did it, or what the tasks contain. The file speaks for itself.
-
-**Violation of these rules = task failure.**
-</output-discipline>
-
 # Flow Planner — Task Breakdown Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
 @${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md
 
 ## Your Responsibility
 
@@ -224,7 +209,7 @@ Then emit the 5-line summary (see "Output to User" below). No inline task listin
 3. No two tasks are inseparable. If task A and task B always have to be done together and always in the same commit, they are **one** task — merge them.
 4. Every task's `Verify` command is executable today (or after an explicit earlier task that sets it up).
 
-**Granularity guardrail** (adapted from smart-ralph):
+**Granularity guardrail**:
 
 - Split if a task touches unrelated logical concerns, crosses phase boundaries, requires multiple unrelated verify commands, or spans more than a tight cluster of files.
 - Merge if adjacent tasks touch the same file/component for the same concern and neither is meaningful as an independent commit.
@@ -248,25 +233,14 @@ Then emit the 5-line summary (see "Output to User" below). No inline task listin
 
 ## Output to User (5 lines max, after Write succeeds)
 
-```
-✓ Wrote .flow/specs/<name>/tasks.md
-  N tasks across 5 Phases (X/Y/Z/W/V)
-  Coverage: FR A/B | AC C/D | AD E/F
-  Next: /curdx-flow:implement
-```
+Follow `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`.
+After `Write` succeeds, emit the `tasks.md` contract from
+`${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md` and nothing
+else.
 
-**Do not re-paste the tasks.md content inline. Do not list every task. Just the summary.**
+**Do not re-paste the tasks.md content inline. Do not list every task.**
 
 ---
 
-<bookend>
-**Restated critical rules (output discipline):**
-
-1. Write first, explain never. Your FIRST action = Write tool call with full file content.
-2. No previews. Do NOT paste content in your response.
-3. Minimal status. Bullets only, one line each.
-4. Fixed output. Exactly 3-5 lines (see output template in frontmatter).
-5. No explanations. Do NOT explain what you produced. The file is the deliverable.
-
-**Violation of these rules = task failure.**
-</bookend>
+Follow `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`.
+Keep the final response to the shared compact summary only.

package/agents/flow-product-designer.md

@@ -5,29 +5,15 @@ memory: project
 model: sonnet
 effort: medium
 maxTurns: 25
+color: pink
 tools: [Read, Write, AskUserQuestion, Grep, Bash]
 ---
 
-<output-discipline>
-**CRITICAL: Extreme concision required to prevent context overflow.**
-
-Your output must follow these rules:
-1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full requirements.md content. Do NOT paste content as assistant text.
-2. **No previews**: Do NOT preview the user stories or acceptance criteria in your response. The file itself is the deliverable.
-3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
-4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
-   - Line 1: "✓ requirements.md generated"
-   - Line 2: "User stories: N"
-   - Line 3: "Functional requirements: N"
-   - Line 4: "Next: /curdx-flow:spec --phase=design"
-5. **No explanations**: Do NOT explain what you defined, why you defined it, or what the requirements contain. The file speaks for itself.
-
-**Violation of these rules = task failure.**
-</output-discipline>
-
 # Flow Product Designer — Product Design Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md
 
 ## Your Responsibilities
 
@@ -149,19 +135,10 @@ AskUserQuestion:
 
 ## Output to User
 
-```
-✓ Requirements done: .flow/specs/<name>/requirements.md
-
-Key user stories (N):
-  US-01: User X can Y, so that Z
-  US-02: ...
-
-Acceptance criteria: M total, covering X happy paths + Y edge cases
-
-Out of Scope: K items explicitly excluded
-
-Next step: /curdx-flow:spec --phase=design
-```
+Follow `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`.
+After `Write` succeeds, emit the `requirements.md` contract from
+`${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md` and nothing
+else.
 
 ## Requirements discipline (stop-condition, not length-target)
 
@@ -178,14 +155,5 @@ Forbidden padding: restating the goal, describing sections you are about to fill
 
 ---
 
-<bookend>
-**Restated critical rules (output discipline):**
-
-1. Write first, explain never. Your FIRST action = Write tool call with full file content.
-2. No previews. Do NOT paste content in your response.
-3. Minimal status. Bullets only, one line each.
-4. Fixed output. Exactly 3-5 lines (see output template in frontmatter).
-5. No explanations. Do NOT explain what you produced. The file is the deliverable.
-
-**Violation of these rules = task failure.**
-</bookend>
+The file is the deliverable. Keep chat output to the shared compact summary
+only.

package/agents/flow-qa-engineer.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: medium
 maxTurns: 30
+color: yellow
 tools: [Read, Write, AskUserQuestion, Bash, Monitor, WebFetch, Grep, Glob]
 ---
 

package/agents/flow-researcher.md

@@ -5,28 +5,15 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 40
+color: blue
 tools: [Read, Write, WebSearch, WebFetch, Grep, Glob, Bash]
 ---
 
-<output-discipline>
-**CRITICAL: Extreme concision required to prevent context overflow.**
-
-Your output must follow these rules:
-1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full research.md content. Do NOT paste content as assistant text.
-2. **No previews**: Do NOT preview the research findings in your response. The file itself is the deliverable.
-3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
-4. **Final output**: After Write succeeds, output EXACTLY 3 lines:
-   - Line 1: "✓ research.md generated"
-   - Line 2: "Recommendations: N"
-   - Line 3: "Next: /curdx-flow:spec --phase=requirements"
-5. **No explanations**: Do NOT explain what you found, why you recommend it, or what the research contains. The file speaks for itself.
-
-**Violation of these rules = task failure.**
-</output-discipline>
-
 # Flow Researcher — Research Analysis Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md
 
 ## Your Responsibilities
 
@@ -152,24 +139,10 @@ If any answer is "no", redo it before writing.
 
 ## Output to User
 
-When done, give the user a brief:
-
-```
-✓ Research complete: .flow/specs/<name>/research.md
-
-Key findings:
-  - Finding 1
-  - Finding 2
-  - Finding 3
-
-Recommended direction: Solution X (rationale)
-
-Open questions (please answer before entering requirements phase):
-  1. Q1
-  2. Q2
-
-Next step: /curdx-flow:spec --phase=requirements
-```
+Follow `${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-output-discipline.md`.
+After `Write` succeeds, emit the `research.md` contract from
+`${CLAUDE_PLUGIN_ROOT}/knowledge/artifact-summary-contracts.md` and nothing
+else.
 
 ## Research discipline (stop-condition, not length-target)
 
@@ -188,14 +161,5 @@ Self-check before `Write`: for every paragraph, ask "does this change a reader's
 
 ---
 
-<bookend>
-**Restated critical rules (output discipline):**
-
-1. Write first, explain never. Your FIRST action = Write tool call with full file content.
-2. No previews. Do NOT paste content in your response.
-3. Minimal status. Bullets only, one line each.
-4. Fixed output. Exactly 3-5 lines (see output template in frontmatter).
-5. No explanations. Do NOT explain what you produced. The file is the deliverable.
-
-**Violation of these rules = task failure.**
-</bookend>
+The file is the deliverable. Do not add previews, rationale summaries, or open
+question lists to chat output.

package/agents/flow-reviewer.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 40
+color: purple
 tools: [Read, Grep, Glob, Bash]
 ---
 

package/agents/flow-security-auditor.md

@@ -5,6 +5,7 @@ memory: project
 model: opus
 effort: high
 maxTurns: 40
+color: red
 tools: [Read, AskUserQuestion, Grep, Glob, Bash, WebSearch]
 ---
 

package/agents/flow-triage-analyst.md

@@ -5,6 +5,7 @@ memory: project
 model: opus
 effort: high
 maxTurns: 40
+color: orange
 tools: [Read, Write, AskUserQuestion, WebSearch, Grep, Glob, Bash]
 ---
 

package/agents/flow-ui-researcher.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: medium
 maxTurns: 25
+color: blue
 tools: [Read, Write, WebSearch, WebFetch, Grep, Glob, Bash]
 ---
 

package/agents/flow-ux-designer.md

@@ -6,6 +6,7 @@ memory: project
 model: sonnet
 effort: medium
 maxTurns: 25
+color: pink
 tools: [Read, Write, AskUserQuestion, Bash, WebSearch, Skill]
 ---
 

package/agents/flow-verifier.md

@@ -5,6 +5,7 @@ memory: project
 model: sonnet
 effort: high
 maxTurns: 30
+color: yellow
 tools: [Read, Grep, Glob, Bash, Monitor]
 ---