diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 191b1342..b3ddf7d9 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.json index a39d5c24..ae6040e8 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.md index 738700a0..fe2bc7b9 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 subagents skills/ — 217 workflow skills and domain knowledge -commands/ — 72 slash commands +commands/ — 74 slash commands hooks/ — Trigger-based automations rules/ — Always-follow guidelines (common + per-language) scripts/ — Cross-platform Node.js utilities diff --git a/README.md b/README.md index baa6efad..53940555 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.md index 32846330..5afc3250 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.yaml index 80fa07d6..4808ec65 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-plan diff --git a/commands/code-review.md b/commands/code-review.md index 8189f951..2382c599 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 PR 3. **PR intent** — Parse PR description for goals, linked issues, test plans 4. **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--review.md`: +Create review artifact at `.claude/reviews/pr--review.md` unless the repo already uses legacy `.claude/PRPs/reviews/` for this workstream: ```markdown # PR Review: # — @@ -273,7 +273,7 @@ Issues: <critical_count> critical, <high_count> high, <medium_count> medium, <lo Validation: <pass_count>/<total_count> checks passed Artifacts: - Review: .claude/PRPs/reviews/pr-<NUMBER>-review.md + Review: .claude/reviews/pr-<NUMBER>-review.md GitHub: <PR URL> Next steps: diff --git a/commands/plan-prd.md b/commands/plan-prd.md new file mode 100644 index 00000000..20508285 --- /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.md index 328c07a8..aed47503 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 Agent diff --git a/commands/pr.md b/commands/pr.md new file mode 100644 index 00000000..264ec3ff --- /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.md new file mode 100644 index 00000000..ed9b0c97 --- /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.md index 415086ee..d29d0a74 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.md index e5d77e33..0be618a7 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 | 插件钩子 |