feat(flowctl): declarative Changes pattern, bidirectional dep index, --dry-run

.agents/plugins/marketplace.json

@@ -1,15 +1,20 @@
 {
+  "name": "flow-code-marketplace",
+  "interface": {
+    "displayName": "Flow-Code Plugins"
+  },
   "plugins": [
     {
       "name": "flow-code",
       "source": {
         "source": "local",
-        "path": "."
+        "path": "./plugins/flow-code"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_INSTALL"
-      }
+      },
+      "category": "Productivity"
     }
   ]
 }

.codex-plugin/plugin.json

@@ -1,9 +1,34 @@
 {
   "name": "flow-code",
   "version": "0.1.31",
-  "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default — AI decides from context, zero questions. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR. Auto-detected stack profiles with one-command guard (test/lint/typecheck). Enhanced agent definitions with permissionMode/maxTurns/effort. Lifecycle hooks with state preservation (PreCompact injects .flow state into compaction, TaskCompleted auto-unlocks files, SubagentStart context injection). Memory v2 with atomic entries, dedup, and progressive disclosure. TDD enforcement mode. Multi-epic queue with dependency visualization. Includes 20 subagents, 25+ commands, 23 skills.",
+  "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR.",
   "author": {
     "name": "z23cc",
     "url": "https://github.com/z23cc"
+  },
+  "homepage": "https://github.com/z23cc/flow-code",
+  "repository": "https://github.com/z23cc/flow-code",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "planning",
+    "execution",
+    "automation",
+    "ai",
+    "codex"
+  ],
+  "skills": "./codex/skills/",
+  "interface": {
+    "displayName": "Flow-Code",
+    "shortDescription": "Plan-first workflow with subagent execution",
+    "longDescription": "Structured plan-first workflow engine. Tracks epics and tasks in .flow/ directory. Spawns isolated worker subagents per task. Ralph mode enables fully autonomous execution with multi-model review gates. 24 subagents, 25+ commands, 23 skills.",
+    "developerName": "z23cc",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/z23cc/flow-code",
+    "brandColor": "#3B82F6"
   }
 }

README.md

@@ -1836,38 +1836,29 @@ CODEX_MAX_THREADS=12 \
 
 **Install:**
 ```bash
-# Clone the marketplace repo (one-time)
+# Clone and install (one-time)
 git clone https://github.com/z23cc/flow-code.git
 cd flow-code
-
-# Run the install script
-./scripts/install-codex.sh flow-code
+./scripts/install-codex.sh
 ```
 
-> Codex doesn't have a plugin marketplace yet, so installation requires cloning this repo and running the install script. The script copies everything to `~/.codex/` — you can delete the clone after install (re-clone to update).
+> The script copies skills/agents/prompts to `~/.codex/` and flowctl to `~/.flow/bin/`. Add `export PATH="$HOME/.flow/bin:$PATH"` to your shell profile.
 
 **Per-project setup** (run in each project):
 ```bash
 # Initialize .flow/ directory
-~/.codex/bin/flowctl init
-
-# Optional: copy flowctl locally for project portability
-mkdir -p .flow/bin
-cp ~/.codex/bin/flowctl .flow/bin/
-cp ~/.codex/bin/flowctl.py .flow/bin/
-cp -r ~/.codex/bin/flowctl .flow/bin/flowctl
-chmod +x .flow/bin/flowctl
+flowctl init
 
 # Optional: configure review backend (codex recommended for Codex CLI)
-~/.codex/bin/flowctl config set review.backend codex
+flowctl config set review.backend codex
 ```
 
 **Optional AGENTS.md snippet** (helps Codex understand flow-code):
 ```markdown
 <!-- BEGIN FLOW-CODE -->
 ## Flow-Code
 
-This project uses Flow-Code for task tracking. Use `.flow/bin/flowctl` or `~/.codex/bin/flowctl`.
+This project uses Flow-Code for task tracking. `flowctl` must be in PATH (`~/.flow/bin/`).
 
 Quick commands:
 - `flowctl list` — list epics + tasks

README_CN.md

@@ -1710,38 +1710,29 @@ CODEX_MAX_THREADS=12 \
 
 **安装：**
 ```bash
-# 克隆市场仓库（一次性）
+# 克隆并安装（一次性）
 git clone https://github.com/z23cc/flow-code.git
 cd flow-code
-
-# 运行安装脚本
-./scripts/install-codex.sh flow-code
+./scripts/install-codex.sh
 ```
 
-> Codex 还没有插件市场，所以安装需要克隆此仓库并运行安装脚本。脚本将所有内容复制到 `~/.codex/` — 安装后可以删除克隆（重新克隆以更新）。
+> 脚本将 skills/agents/prompts 复制到 `~/.codex/`，flowctl 复制到 `~/.flow/bin/`。请将 `export PATH="$HOME/.flow/bin:$PATH"` 加入 shell 配置文件。
 
 **每个项目设置**（在每个项目中运行）：
 ```bash
 # 初始化 .flow/ 目录
-~/.codex/bin/flowctl init
-
-# 可选：本地复制 flowctl 以保证项目可移植性
-mkdir -p .flow/bin
-cp ~/.codex/bin/flowctl .flow/bin/
-cp ~/.codex/bin/flowctl.py .flow/bin/
-cp -r ~/.codex/bin/flowctl .flow/bin/flowctl
-chmod +x .flow/bin/flowctl
+flowctl init
 
 # 可选：配置审查后端（推荐 codex）
-~/.codex/bin/flowctl config set review.backend codex
+flowctl config set review.backend codex
 ```
 
 **可选 AGENTS.md 片段**（帮助 Codex 理解 flow-code）：
 ```markdown
 <!-- BEGIN FLOW-CODE -->
 ## Flow-Code
 
-本项目使用 Flow-Code 进行任务追踪。使用 `.flow/bin/flowctl` 或 `~/.codex/bin/flowctl`。
+本项目使用 Flow-Code 进行任务追踪。`flowctl` 需在 PATH 中（`~/.flow/bin/`）。
 
 快速命令：
 - `flowctl list` — 列出 epic + 任务

codex/agents/agents-md-scout.toml

@@ -0,0 +1,128 @@
+# Auto-generated by flowctl codex sync — do not edit manually
+name = "agents-md-scout"
+description = "Used by /flow-code:prime to analyze CLAUDE.md and AGENTS.md quality and completeness. Do not invoke directly."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+
+You are a CLAUDE.md scout for agent readiness assessment. Analyze agent instruction files for completeness and quality.
+
+## Why This Matters
+
+Agents work better when they understand:
+- Project conventions (naming, structure, patterns)
+- Build/test commands (how to verify their work)
+- What NOT to do (common pitfalls, forbidden patterns)
+- Where things live (key directories, entry points)
+
+Without CLAUDE.md, agents guess. Guessing wastes cycles.
+
+## Scan Targets
+
+### File Locations
+```bash
+# CLAUDE.md locations (priority order)
+ls -la CLAUDE.md .claude/CLAUDE.md 2>/dev/null
+
+# AGENTS.md (Codex/other agents)
+ls -la AGENTS.md .agents/AGENTS.md 2>/dev/null
+
+# Related instruction files
+ls -la CONTRIBUTING.md DEVELOPMENT.md .github/CONTRIBUTING.md 2>/dev/null
+```
+
+### Content Analysis (if files exist)
+
+Read the files and check for these sections:
+
+**Essential sections:**
+- Project overview / purpose
+- Build commands (how to build)
+- Test commands (how to run tests)
+- Key directories / structure
+
+**Valuable sections:**
+- Code style / conventions
+- Common patterns to follow
+- Things to avoid / pitfalls
+- Dependencies / setup instructions
+
+**Advanced sections:**
+- Architecture overview
+- Data flow / key abstractions
+- Performance considerations
+- Security guidelines
+
+## Quality Signals
+
+**Good CLAUDE.md:**
+- Specific commands (not "run tests" but `pnpm test`)
+- File paths with context (`src/api/` for API routes)
+- Do/Don't lists with rationale
+- Links to detailed docs for deep dives
+
+**Weak CLAUDE.md:**
+- Generic advice ("write clean code")
+- Missing build/test commands
+- No mention of project structure
+- Outdated information (references removed files)
+
+## Output Format
+
+```markdown
+## CLAUDE.md Scout Findings
+
+### Files Found
+- CLAUDE.md: ✅ Found at [path] / ❌ Missing
+- AGENTS.md: ✅ Found at [path] / ❌ Missing
+- CONTRIBUTING.md: ✅ Found / ❌ Missing
+
+### Content Analysis (if CLAUDE.md exists)
+
+**Coverage Score: X/10**
+
+| Section | Status | Notes |
+|---------|--------|-------|
+| Project overview | ✅/❌ | [brief note] |
+| Build commands | ✅/❌ | [brief note] |
+| Test commands | ✅/❌ | [brief note] |
+| Directory structure | ✅/❌ | [brief note] |
+| Code conventions | ✅/❌ | [brief note] |
+| Patterns to follow | ✅/❌ | [brief note] |
+| Things to avoid | ✅/❌ | [brief note] |
+| Setup instructions | ✅/❌ | [brief note] |
+
+**Strengths:**
+- [What's done well]
+
+**Gaps:**
+- [What's missing or weak]
+
+### If CLAUDE.md Missing
+
+**Detected from repo scan:**
+- Build tool: [detected or unknown]
+- Test framework: [detected or unknown]
+- Key directories: [list]
+- Package manager: [detected]
+
+**Recommended sections to create:**
+1. [Most important missing section]
+2. [Second priority]
+3. [Third priority]
+
+### Recommendations
+- [Priority 1]: [specific action]
+- [Priority 2]: [specific action]
+```
+
+## Rules
+
+- If CLAUDE.md exists, read and analyze it
+- If missing, scan repo for info that SHOULD be in CLAUDE.md
+- Check for staleness (references to files that don't exist)
+- Note if CONTRIBUTING.md duplicates what should be in CLAUDE.md
+- Don't penalize for missing advanced sections in small projects
+"""