The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add PRD planning command flow
Affaan Mustafaf8070dd640f2
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 191b13429..b3ddf7d91 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -11,7 +11,7 @@{"name": "ecc","source": "./",- "description": "The most comprehensive Claude Code plugin — 56 agents, 217 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",+ "description": "The most comprehensive Claude Code plugin — 56 agents, 217 skills, 74 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning","version": "2.0.0-rc.1","author": {"name": "Affaan Mustafa",diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex a39d5c248..ae6040e8a 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ecc","version": "2.0.0-rc.1",- "description": "Battle-tested Claude Code plugin for engineering teams — 56 agents, 217 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",+ "description": "Battle-tested Claude Code plugin for engineering teams — 56 agents, 217 skills, 74 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use","author": {"name": "Affaan Mustafa","url": "https://x.com/affaanmustafa"diff --git a/AGENTS.md b/AGENTS.mdindex 738700a04..fe2bc7b9c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — Agent Instructions-This is a **production-ready AI coding plugin** providing 56 specialized agents, 217 skills, 72 commands, and automated hook workflows for software development.+This is a **production-ready AI coding plugin** providing 56 specialized agents, 217 skills, 74 commands, and automated hook workflows for software development.**Version:** 2.0.0-rc.1@@ -149,7 +149,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat```agents/ — 56 specialized subagentsskills/ — 217 workflow skills and domain knowledge-commands/ — 72 slash commands+commands/ — 74 slash commandshooks/ — Trigger-based automationsrules/ — Always-follow guidelines (common + per-language)scripts/ — Cross-platform Node.js utilitiesdiff --git a/README.md b/README.mdindex baa6efad8..539405554 100644--- a/README.md+++ b/README.md@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:/plugin list ecc@ecc```-**That's it!** You now have access to 56 agents, 217 skills, and 72 legacy command shims.+**That's it!** You now have access to 56 agents, 217 skills, and 74 legacy command shims.### Dashboard GUI@@ -1361,7 +1361,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.| Feature | Claude Code | OpenCode | Status ||---------|-------------|----------|--------|| Agents | PASS: 56 agents | PASS: 12 agents | **Claude Code leads** |-| Commands | PASS: 72 commands | PASS: 35 commands | **Claude Code leads** |+| Commands | PASS: 74 commands | PASS: 35 commands | **Claude Code leads** || Skills | PASS: 217 skills | PASS: 37 skills | **Claude Code leads** || Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** || Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** |@@ -1466,7 +1466,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|------------|------------|-----------|----------|| **Agents** | 56 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |-| **Commands** | 72 | Shared | Instruction-based | 35 |+| **Commands** | 74 | Shared | Instruction-based | 35 || **Skills** | 217 | Shared | 10 (native format) | 37 || **Hook Events** | 8 types | 15 types | None yet | 11 types || **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 328463306..5afc3250a 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**完成!** 你现在可以使用 56 个代理、217 个技能和 72 个命令。+**完成!** 你现在可以使用 56 个代理、217 个技能和 74 个命令。### multi-* 命令需要额外配置diff --git a/agent.yaml b/agent.yamlindex 80fa07d64..4808ec659 100644--- a/agent.yaml+++ b/agent.yaml@@ -197,10 +197,12 @@ commands:- multi-plan- multi-workflow- plan+ - plan-prd- pm2- projects- promote- project-init+ - pr- prp-commit- prp-implement- prp-plandiff --git a/commands/code-review.md b/commands/code-review.mdindex 8189f9512..2382c5996 100644--- a/commands/code-review.md+++ b/commands/code-review.md@@ -99,7 +99,7 @@ If PR not found, stop with error. Store PR metadata for later phases.Build review context:1. **Project rules** — Read `CLAUDE.md`, `.claude/docs/`, and any contributing guidelines-2. **PRP artifacts** — Check `.claude/PRPs/reports/` and `.claude/PRPs/plans/` for implementation context related to this PR+2. **Planning artifacts** — Check `.claude/prds/`, `.claude/plans/`, `.claude/reviews/`, and legacy `.claude/PRPs/{prds,plans,reports,reviews}/` for context related to this PR3. **PR intent** — Parse PR description for goals, linked issues, test plans4. **Changed files** — List all modified files and categorize by type (source, test, config, docs)@@ -188,7 +188,7 @@ Special cases:### Phase 6 — REPORT-Create review artifact at `.claude/PRPs/reviews/pr-<NUMBER>-review.md`:+Create review artifact at `.claude/reviews/pr-<NUMBER>-review.md` unless the repo already uses legacy `.claude/PRPs/reviews/` for this workstream:```markdown# PR Review: #<NUMBER> — <TITLE>@@ -273,7 +273,7 @@ Issues: <critical_count> critical, <high_count> high, <medium_count> medium, <loValidation: <pass_count>/<total_count> checks passedArtifacts:- Review: .claude/PRPs/reviews/pr-<NUMBER>-review.md+ Review: .claude/reviews/pr-<NUMBER>-review.mdGitHub: <PR URL>Next steps:diff --git a/commands/plan-prd.md b/commands/plan-prd.mdnew file mode 100644index 000000000..205082859--- /dev/null+++ b/commands/plan-prd.md@@ -0,0 +1,160 @@+---+description: "Generate a lean, problem-first PRD and hand off to /plan for implementation planning."+argument-hint: "[product/feature idea] (blank = start with questions)"+---++# PRD Command++Produces a **Product Requirements Document** — the requirements-phase artifact of the SDLC. Captures *what* must be true for success and *why*, and stops before *how*. Implementation decomposition is delegated to `/plan`.++**Input**: `$ARGUMENTS`++## Scope of this command++| This command does | This command does NOT do |+|---|---|+| Frame the problem and users | Design the architecture |+| Capture success criteria and scope | Pick files or write patterns |+| List open questions and risks | Enumerate implementation tasks |+| Write `.claude/prds/{name}.prd.md` | Produce an implementation plan — that's `/plan` |++If you find yourself writing implementation detail, stop and cut it. It belongs in `/plan`.++**Anti-fluff rule**: When information is missing, write `TBD — needs validation via {method}`. Never invent plausible-sounding requirements.++## Workflow++Four phases. Each phase is a single gate — ask the questions, wait for the user, then move on. No nested loops, no parallel research ceremony.++### Phase 1 — FRAME++If `$ARGUMENTS` is empty, ask:++> What do you want to build? One or two sentences.++If provided, restate in one sentence and ask:++> I understand: *{restated}*. Correct, or should I adjust?++Then ask the framing questions in a single set:++> 1. **Who** has this problem? (specific role or segment)+> 2. **What** is the observable pain? (describe behavior, not assumed needs)+> 3. **Why** can't they solve it with what exists today?+> 4. **Why now?** — what changed that makes this worth doing?++Wait for the user. Do not proceed without answers (or explicit "skip").++### Phase 2 — GROUND++Ask for evidence. This is the shortest phase and the most load-bearing:++> What evidence do you have that this problem is real and worth solving? (user quotes, support tickets, metrics, observed behavior, failed workarounds — anything concrete)++If the user has none, record the PRD's Evidence section as `Assumption — needs validation via {user research | analytics | prototype}`. This keeps the PRD honest.++### Phase 3 — DECIDE++Scope and hypothesis in a single set:++> 1. **Hypothesis** — Complete: *We believe **{capability}** will **{solve problem}** for **{users}**. We'll know we're right when **{measurable outcome}**.*+> 2. **MVP** — The minimum needed to test the hypothesis?+> 3. **Out of scope** — What are you explicitly **not** building (even if users ask)?+> 4. **Open questions** — Uncertainties that could change the approach?++Wait for responses.++### Phase 4 — GENERATE & HAND OFF++Create the directory if needed, write the PRD, and report.++```bash+mkdir -p .claude/prds+```++**Output path**: `.claude/prds/{kebab-case-name}.prd.md`++#### PRD Template++```markdown+# {Product / Feature Name}++## Problem+{2–3 sentences: who has what problem, and what's the cost of leaving it unsolved?}++## Evidence+- {User quote, data point, or observation}+- {OR: "Assumption — needs validation via {method}"}++## Users+- **Primary**: {role, context, what triggers the need}+- **Not for**: {who this explicitly excludes}++## Hypothesis+We believe **{capability}** will **{solve problem}** for **{users}**.+We'll know we're right when **{measurable outcome}**.++## Success Metrics+| Metric | Target | How measured |+|---|---|---|+| {primary} | {number} | {method} |++## Scope+**MVP** — {the minimum to test the hypothesis}++**Out of scope**+- {item} — {why deferred}++## Delivery Milestones+<!-- Business outcomes, not engineering tasks. /plan turns each into a plan. -->+<!-- Status: pending | in-progress | complete -->++| # | Milestone | Outcome | Status | Plan |+|---|---|---|---|---|+| 1 | {name} | {user-visible change} | pending | — |+| 2 | {name} | {user-visible change} | pending | — |++## Open Questions+- [ ] {question that could change scope or approach}++## Risks+| Risk | Likelihood | Impact | Mitigation |+|---|---|---|---|++---+*Status: DRAFT — requirements only. Implementation planning pending via /plan.*+```++#### Report to user++```+PRD created: .claude/prds/{name}.prd.md++Problem: {one line}+Hypothesis: {one line}+MVP: {one line}++Validation status:+ Problem {validated | assumption}+ Users {concrete | generic — refine}+ Metrics {defined | TBD}++Open questions: {count}++Next step: /plan .claude/prds/{name}.prd.md+ → /plan will pick the next pending milestone and produce an implementation plan.+```++## Integration++- `/plan <prd-path>` — consume the PRD and produce an implementation plan for the next pending milestone.+- `tdd-workflow` skill — implement the plan test-first.+- `/pr` — open a PR that references the PRD and plan.++## Success criteria++- **PROBLEM_CLEAR**: problem is specific and evidenced (or flagged as assumption).+- **USER_CONCRETE**: primary user is a specific role, not "users".+- **HYPOTHESIS_TESTABLE**: measurable outcome included.+- **SCOPE_BOUNDED**: explicit MVP and explicit out-of-scope.+- **NO_IMPLEMENTATION_DETAIL**: file paths, libraries, or task breakdowns are absent — if they appeared, move them to the `/plan` step.diff --git a/commands/plan.md b/commands/plan.mdindex 328c07a82..aed475034 100644--- a/commands/plan.md+++ b/commands/plan.md@@ -1,10 +1,11 @@---description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.+argument-hint: "[feature description | path/to/*.prd.md]"---# Plan Command-This command creates a comprehensive implementation plan before writing any code.+This command creates a comprehensive implementation plan before writing any code. It accepts either free-form requirements or a PRD markdown file.Run inline by default. Do not call the Task tool or any subagent by default. This keeps `/plan` usable from plugin installs that ship commands without agent files.@@ -29,11 +30,86 @@ Use `/plan` when:The assistant will:1. **Analyze the request** and restate requirements in clear terms-2. **Break down into phases** with specific, actionable steps-3. **Identify dependencies** between components-4. **Assess risks** and potential blockers-5. **Estimate complexity** (High/Medium/Low)-6. **Present the plan** and WAIT for your explicit confirmation+2. **Ground the plan** in relevant codebase patterns when the repo is available+3. **Break down into phases** with specific, actionable steps+4. **Identify dependencies** between components+5. **Assess risks** and potential blockers+6. **Estimate complexity** (High/Medium/Low)+7. **Present the plan** and WAIT for your explicit confirmation++## Input Modes++| Input | Mode | Behavior |+|---|---|---|+| `path/to/name.prd.md` | PRD artifact mode | Read the PRD, pick the next pending delivery milestone or implementation phase, and write `.claude/plans/{name}.plan.md` |+| Any other markdown path | Reference mode | Read the file as context and produce an inline plan |+| Free-form text | Conversational mode | Produce an inline plan |+| Empty input | Clarification mode | Ask what should be planned |++In PRD artifact mode, create `.claude/plans/` if needed. If the PRD contains a `Delivery Milestones` table, update only the selected row from `pending` to `in-progress` and set its `Plan` cell to the generated plan path. If the PRD uses the legacy `.claude/PRPs/prds/` format with `Implementation Phases`, read it without migrating paths.++## Pattern Grounding++Before writing the plan, search the codebase for conventions the implementation should mirror. Capture the top example for each relevant category with file references:++| Category | What to capture |+|---|---|+| Naming | File, function, type, command, or script naming in the affected area |+| Error handling | How failures are raised, returned, logged, or handled gracefully |+| Logging | Levels, format, and what gets logged |+| Data access | Repository, service, query, or filesystem patterns |+| Tests | Test file location, framework, fixtures, and assertion style |++If no similar code exists, state that explicitly. Do not invent a pattern.++## PRD Artifact Output++When called with a `.prd.md` file, write the plan to `.claude/plans/{kebab-case-name}.plan.md` using this structure:++````markdown+# Plan: {Feature Name}++**Source PRD**: {path}+**Selected Milestone**: {milestone or phase name}+**Complexity**: {Small | Medium | Large}++## Summary+{2-3 sentences}++## Patterns to Mirror+| Category | Source | Pattern |+|---|---|---|+| Naming | `path:line` | {short description} |+| Errors | `path:line` | {short description} |+| Tests | `path:line` | {short description} |++## Files to Change+| File | Action | Why |+|---|---|---|+| `path` | CREATE / UPDATE / DELETE | {reason} |++## Tasks+### Task 1: {name}+- **Action**: {what to do}+- **Mirror**: {pattern to follow}+- **Validate**: {command that proves correctness}++## Validation+```bash+{project-specific validation commands}+```++## Risks+| Risk | Likelihood | Mitigation |+|---|---|---|++## Acceptance+- [ ] All tasks complete+- [ ] Validation passes+- [ ] Patterns mirrored, not reinvented+````++After writing the artifact, report its path and WAIT for confirmation before writing code.## Example Usage@@ -108,8 +184,11 @@ After planning:- Use the `tdd-workflow` skill to implement with test-driven development- Use `/build-fix` if build errors occur- Use `/code-review` to review completed implementation+- Use `/pr` or `/prp-pr` to open a pull request-> **Need deeper planning?** Use `/prp-plan` for artifact-producing planning with PRD integration, codebase analysis, and pattern extraction. Use `/prp-implement` to execute those plans with rigorous validation loops.+> **Need requirements first?** Use `/plan-prd` for a lean PRD at `.claude/prds/{name}.prd.md`.+>+> **Need the legacy PRP flow?** Use `/prp-plan` for deep PRP planning with `.claude/PRPs/` artifacts. Use `/prp-implement` to execute those plans with rigorous validation loops.## Optional Planner Agentdiff --git a/commands/pr.md b/commands/pr.mdnew file mode 100644index 000000000..264ec3fff--- /dev/null+++ b/commands/pr.md@@ -0,0 +1,184 @@+---+description: "Create a GitHub PR from current branch with unpushed commits — discovers templates, analyzes changes, pushes"+argument-hint: "[base-branch] (default: main)"+---++# Create Pull Request++**Input**: `$ARGUMENTS` — optional, may contain a base branch name and/or flags (e.g., `--draft`).++**Parse `$ARGUMENTS`**:+- Extract any recognized flags (`--draft`)+- Treat remaining non-flag text as the base branch name+- Default base branch to `main` if none specified++---++## Phase 1 — VALIDATE++Check preconditions:++```bash+git branch --show-current+git status --short+git log origin/<base>..HEAD --oneline+```++| Check | Condition | Action if Failed |+|---|---|---|+| Not on base branch | Current branch ≠ base | Stop: "Switch to a feature branch first." |+| Clean working directory | No uncommitted changes | Warn: "You have uncommitted changes. Commit or stash first." |+| Has commits ahead | `git log origin/<base>..HEAD` not empty | Stop: "No commits ahead of `<base>`. Nothing to PR." |+| No existing PR | `gh pr list --head <branch> --json number` is empty | Stop: "PR already exists: #<number>. Use `gh pr view <number> --web` to open it." |++If all checks pass, proceed.++---++## Phase 2 — DISCOVER++### PR Template++Search for PR template in order:++1. `.github/PULL_REQUEST_TEMPLATE/` directory — if exists, list files and let user choose (or use `default.md`)+2. `.github/PULL_REQUEST_TEMPLATE.md`+3. `.github/pull_request_template.md`+4. `docs/pull_request_template.md`++If found, read it and use its structure for the PR body.++### Commit Analysis++```bash+git log origin/<base>..HEAD --format="%h %s" --reverse+```++Analyze commits to determine:+- **PR title**: Use conventional commit format with type prefix — `feat: ...`, `fix: ...`, etc.+ - If multiple types, use the dominant one+ - If single commit, use its message as-is+- **Change summary**: Group commits by type/area++### File Analysis++```bash+git diff origin/<base>..HEAD --stat+git diff origin/<base>..HEAD --name-only+```++Categorize changed files: source, tests, docs, config, migrations.++### Planning Artifacts++Check for related artifacts produced by `/plan-prd`, `/plan`, or the legacy PRP workflow:+- `.claude/prds/` — PRDs this PR implements a milestone of+- `.claude/plans/` — Plans executed by this PR+- `.claude/PRPs/prds/` — legacy PRP PRDs+- `.claude/PRPs/plans/` — legacy PRP implementation plans+- `.claude/PRPs/reports/` — legacy PRP implementation reports++Reference these in the PR body if they exist.++---++## Phase 3 — PUSH++```bash+git push -u origin HEAD+```++If push fails due to divergence:+```bash+git fetch origin+git rebase origin/<base>+git push -u origin HEAD+```++If rebase conflicts occur, stop and inform the user.++---++## Phase 4 — CREATE++### With Template++If a PR template was found in Phase 2, fill in each section using the commit and file analysis. Preserve all template sections — leave sections as "N/A" if not applicable rather than removing them.++### Without Template++Use this default format:++```markdown+## Summary++<1-2 sentence description of what this PR does and why>++## Changes++<bulleted list of changes grouped by area>++## Files Changed++<table or list of changed files with change type: Added/Modified/Deleted>++## Testing++<description of how changes were tested, or "Needs testing">++## Related Issues++<linked issues with Closes/Fixes/Relates to #N, or "None">+```++### Create the PR++```bash+gh pr create \+ --title "<PR title>" \+ --base <base-branch> \+ --body "<PR body>"+ # Add --draft if the --draft flag was parsed from $ARGUMENTS+```++---++## Phase 5 — VERIFY++```bash+gh pr view --json number,url,title,state,baseRefName,headRefName,additions,deletions,changedFiles+gh pr checks --json name,status,conclusion 2>/dev/null || true+```++---++## Phase 6 — OUTPUT++Report to user:++```+PR #<number>: <title>+URL: <url>+Branch: <head> → <base>+Changes: +<additions> -<deletions> across <changedFiles> files++CI Checks: <status summary or "pending" or "none configured">++Artifacts referenced:+ - <any PRDs/plans linked in PR body>++Next steps:+ - gh pr view <number> --web → open in browser+ - /code-review <number> → review the PR+ - gh pr merge <number> → merge when ready+```++---++## Edge Cases++- **No `gh` CLI**: Stop with: "GitHub CLI (`gh`) is required. Install: <https://cli.github.com/>"+- **Not authenticated**: Stop with: "Run `gh auth login` first."+- **Force push needed**: If remote has diverged and rebase was done, use `git push --force-with-lease` (never `--force`).+- **Multiple PR templates**: If `.github/PULL_REQUEST_TEMPLATE/` has multiple files, list them and ask user to choose.+- **Large PR (>20 files)**: Warn about PR size. Suggest splitting if changes are logically separable.diff --git a/docs/PLAN-PRD-PATTERN.md b/docs/PLAN-PRD-PATTERN.mdnew file mode 100644index 000000000..ed9b0c97a--- /dev/null+++ b/docs/PLAN-PRD-PATTERN.md@@ -0,0 +1,154 @@+# Plan-PRD Pattern: Markdown-Staged Planning Flow++A lightweight, SDLC-aligned planning workflow where each phase of the lifecycle produces a committable markdown **staging file** that the next command consumes.++> Short version: `/plan-prd` writes a PRD, `/plan` writes a plan, the `tdd-workflow` skill implements it, and `/pr` ships it. Each arrow is a file on disk, not a conversation in memory.++## Feature: Markdown Staging Files++Every planning artifact is a plain `.md` file under `.claude/`:++```+.claude/+ prds/ # Product Requirements Documents from /plan-prd+ plans/ # Implementation plans from /plan+ reviews/ # Code review artifacts from /code-review+```++These files are:++- **Plain markdown** — readable by humans, diffable in PRs, grep-able at CLI.+- **Committable** — check them in alongside code so the intent travels with the implementation.+- **Composable** — each command accepts the previous stage's file as its `$ARGUMENTS`, so the toolchain composes via paths rather than in-context state.+- **Resumable** — close the session, open a new one tomorrow, pass the file path back in.++## Flow++```+┌───────────────────────────┐+│ /plan-prd "<idea>" │ Requirements phase+│ → .claude/prds/X.prd.md │ Problem · Users · Hypothesis · Scope+└─────────────┬─────────────┘+ │+ ▼+┌───────────────────────────┐+│ /plan <prd-path> │ Design phase+│ → .claude/plans/X.plan.md│ Patterns · Files · Tasks · Validation+└─────────────┬─────────────┘+ │+ ▼+┌───────────────────────────┐+│ tdd-workflow skill │ Implementation phase+│ → code + tests │ Test-first, minimal diff+└─────────────┬─────────────┘+ │+ ▼+┌───────────────────────────┐+│ /pr │ Delivery phase+│ → GitHub PR │ Links back to PRD + plan+└───────────────────────────┘+```++Each box is a **gate**. You can:++- Stop between gates — the artifact persists.+- Restart from any gate using the artifact path.+- Skip gates for small work — feed `/plan` free-form text and ignore `/plan-prd`.+- Run a gate standalone — `/plan "refactor X"` produces a conversational plan with no artifact.++## Why `/plan-prd` Is Additional to `/plan`++They answer different questions. Mixing them causes scope creep.++| Command | Answers | SDLC Phase | Artifact |+|---|---|---|---|+| `/plan-prd` | *What problem? For whom? How do we know we're done?* | Requirements | `.claude/prds/{name}.prd.md` |+| `/plan` | *What files, patterns, and tasks satisfy the requirement?* | Design + Implementation strategy | `.claude/plans/{name}.plan.md` (PRD mode) or inline (text mode) |++### Why not combine them?++- **Separation of concerns.** PRDs ask *why*; plans ask *how*. Bundling them creates one oversized command that does both poorly, as the old `/prp-prd` → `/prp-plan` pair demonstrated (8-phase interrogation with implementation-phase tables mixed into requirements).+- **Different audiences.** A stakeholder reviewing a PRD does not care about file paths or type-check commands. An engineer reading a plan does not need the market-research phase.+- **Different lifespans.** A PRD can remain stable while its plan is rewritten multiple times as implementation assumptions change.+- **Optional step.** Many changes (bug fixes, small refactors, single-file additions) don't need a PRD. `/plan` alone is enough. Forcing a PRD on every change is bureaucracy.++### When to use each++Use `/plan-prd` when:++- Scope is unclear or contested.+- Multiple stakeholders need to align on the problem before solutioning.+- The change is large enough that writing down the hypothesis is cheaper than relitigating scope mid-implementation.++Use `/plan` directly when:++- Requirements are already clear (a bug report, a scoped refactor, a known migration).+- The work is small enough that a conversational plan + confirmation gate is sufficient.+- You already have a PRD — pass it to `/plan` and skip `/plan-prd`.++## Usage++### Full flow (feature with unclear scope)++```bash+# 1. Draft the PRD+/plan-prd "Per-user rate limits on the public API"++# → .claude/prds/per-user-rate-limits.prd.md created+# Answer the framing questions, provide evidence, define hypothesis and scope.++# 2. Pick the next pending milestone and produce a plan+/plan .claude/prds/per-user-rate-limits.prd.md++# → .claude/plans/per-user-rate-limits.plan.md created+# The plan includes patterns to mirror, files to change, and validation commands.+# PRD's Delivery Milestones table updates the selected row to `in-progress`.++# 3. Implement test-first+Use the tdd-workflow skill++# 4. Open the PR+/pr+# → PR body auto-references .claude/prds/... and .claude/plans/...+```++### Quick flow (scope already clear)++```bash+/plan "Add retry with exponential backoff to the notifier"+# Conversational planning, no artifact.+# Confirm, then use the tdd-workflow skill.+```++### Reference an existing PRD from elsewhere++```bash+# PRD was written by someone else, lives in your repo+/plan docs/rfcs/0042-rate-limiting.prd.md+```++`/plan` detects any `.prd.md` path and switches to artifact mode, parsing the Delivery Milestones table.++## Why staging files beat in-context state++- **Transferable**: drop the PRD path into a fresh session and you're caught up — no replaying a long conversation.+- **Auditable**: the PR reviewer sees *what you intended* next to *what you built*.+- **Versioned**: the staging file evolves in git history, same as code.+- **Machine-parseable**: `/plan` programmatically picks the next pending milestone; `/pr` programmatically links artifacts in the PR body. No prompt engineering required.++## Related commands++- `/plan-prd` — requirements (this pattern entry point).+- `/plan` — planning (consumes PRDs or free-form text).+- `tdd-workflow` skill — test-first implementation.+- `/pr` — open a PR that references PRDs and plans.+- `/code-review` — reviews local diffs or PRs; auto-detects `.claude/prds/` and `.claude/plans/` as context.++## Compatibility++This pattern adds ECC-native staging-file commands alongside the existing `prp-*` command set. The legacy PRP commands remain available for deeper PRP workflows and for users who already have `.claude/PRPs/` artifacts.++- `/plan-prd` is the lean requirements entry point for `.claude/prds/`.+- `/plan` can consume `.prd.md` files and produce `.claude/plans/` artifacts without requiring the legacy PRP directory layout.+- `/pr` is the ECC-native PR creation command and can reference `.claude/prds/` and `.claude/plans/`.+- `/prp-prd`, `/prp-plan`, `/prp-implement`, `/prp-commit`, and `/prp-pr` remain valid legacy/deep workflow commands.diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.mdindex 415086ee7..d29d0a74e 100644--- a/docs/zh-CN/AGENTS.md+++ b/docs/zh-CN/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — 智能体指令-这是一个**生产就绪的 AI 编码插件**,提供 56 个专业代理、217 项技能、72 条命令以及自动化钩子工作流,用于软件开发。+这是一个**生产就绪的 AI 编码插件**,提供 56 个专业代理、217 项技能、74 条命令以及自动化钩子工作流,用于软件开发。**版本:** 2.0.0-rc.1@@ -148,7 +148,7 @@```agents/ — 56 个专业子代理skills/ — 217 个工作流技能和领域知识-commands/ — 72 个斜杠命令+commands/ — 74 个斜杠命令hooks/ — 基于触发的自动化rules/ — 始终遵循的指导方针(通用 + 每种语言)scripts/ — 跨平台 Node.js 实用工具diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.mdindex e5d77e33f..0be618a77 100644--- a/docs/zh-CN/README.md+++ b/docs/zh-CN/README.md@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**搞定!** 你现在可以使用 56 个智能体、217 项技能和 72 个命令了。+**搞定!** 你现在可以使用 56 个智能体、217 项技能和 74 个命令了。***@@ -1133,7 +1133,7 @@ opencode| 功能特性 | Claude Code | OpenCode | 状态 ||---------|-------------|----------|--------|| 智能体 | PASS: 56 个 | PASS: 12 个 | **Claude Code 领先** |-| 命令 | PASS: 72 个 | PASS: 35 个 | **Claude Code 领先** |+| 命令 | PASS: 74 个 | PASS: 35 个 | **Claude Code 领先** || 技能 | PASS: 217 项 | PASS: 37 项 | **Claude Code 领先** || 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** || 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** |@@ -1241,7 +1241,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以| 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|------------|------------|-----------|----------|| **智能体** | 56 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |-| **命令** | 72 | 共享 | 基于指令 | 35 |+| **命令** | 74 | 共享 | 基于指令 | 35 || **技能** | 217 | 共享 | 10 (原生格式) | 37 || **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 || **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 |