@the-bearded-bear/claude-craft 8.23.3 → 8.26.0-next.2a54921

package/Project/i18n/en/commands/reverse.md

@@ -0,0 +1,249 @@
+---
+description: "Brownfield reverse-engineering pipeline: scan the codebase, then derive a draft PRD, user stories and a spec-vs-code gap analysis"
+argument-hint: "[scan|prd|stories|gaps|all] [--scope=<scope>] [--module=<name>] [--output=<path>]"
+---
+
+# /project:reverse
+
+## Mission
+
+Reverse-engineer specifications from an existing codebase (brownfield projects). One command covers the whole pipeline: inventory the code (`scan`), infer a draft PRD (`prd`), infer user stories (`stories`) and compare specs against code (`gaps`). `all` runs the four in order.
+
+## Usage
+
+| Command | What it does | Replaces |
+|---------|--------------|----------|
+| `/project:reverse scan` | Inventory of modules, endpoints, models, services, tests, infrastructure | `/project:reverse scan` |
+| `/project:reverse prd` | DRAFT PRD inferred from code | `/project:reverse prd` |
+| `/project:reverse stories` | DRAFT user stories inferred from code and tests | `/project:reverse stories` |
+| `/project:reverse gaps` | Spec vs code gap analysis, severity-ranked | `/project:reverse gaps` |
+| `/project:reverse all` | `scan` -> `prd` -> `stories` -> `gaps`, in this order | all four |
+
+## Arguments
+
+Parse `$ARGUMENTS`: first token = subcommand (`scan`, `prd`, `stories`, `gaps`, `all`). With no subcommand, ask which one (recommend `all` on a first run). Flags:
+
+| Flag | Applies to | Description |
+|------|-----------|-------------|
+| `--scope=<scope>` | `scan`: all, backend, frontend, api, tests / `stories`: all, module, endpoint / `gaps`: full, requirements, stories, code | Limits the analysis |
+| `--module=<name>` | `stories` | Generate stories for one module only |
+| `--output=<path>` | `scan`, `prd` | Output path (defaults below) |
+
+## Shared rules
+
+**Plan mode is mandatory.** Before executing, activate plan mode, propose the plan, and wait for validation before changing any file. With `all`, one plan covers the four steps.
+
+**Persona and inference rules (used by `prd` and `stories`):**
+
+| Auth pattern | Inferred persona |
+|--------------|------------------|
+| `ROLE_ADMIN` + admin routes | Administrator |
+| `ROLE_USER` + authenticated routes | Registered user |
+| `ROLE_MANAGER` + management routes | Manager / supervisor |
+| Public endpoints (no auth) | Visitor / anonymous |
+| API key auth | External system |
+
+**Everything inferred is a DRAFT.** Code shows what the system does, not what it should do. Mark every inferred artifact `INFERRED` and require human validation before it is treated as authoritative. Marker to insert in each inferred section or story:
+
+```
+> INFERRED -- This was generated by analyzing the existing codebase.
+> Human validation is required before treating this as authoritative.
+```
+
+**Status rule:** `.bmad/sprint-status.yaml` is the single source of truth for story/task STATUS. Generated stories contain content only (no status field); register them in `.bmad/sprint-status.yaml` (schema: `.claude/templates/project/sprint-status.md`) once validated.
+
+**Default paths:**
+
+```
+project-management/
++-- scan-report.md                  # scan
++-- prd.md                          # prd (DRAFT)
++-- backlog/user-stories/US-*.md    # stories
++-- analysis/
+    +-- reverse-engineering.md      # prd: analysis notes and confidence levels
+    +-- gap-analysis.md             # gaps
+```
+
+**Prerequisites:** source code accessible; optional `README.md`, `docker-compose.yml`, `./docs/`. `prd`, `stories` and `gaps` need `project-management/scan-report.md` -- if missing, run `scan` first (automatic under `all`). `gaps` also needs a PRD (`project-management/prd.md`, from `/workflow:plan --only=prd` or `prd`); `stories` and `gaps` use it for FR-xxx traceability when present.
+
+**Output convention:** each step prints a boxed progress banner, ends with a short summary and offers next steps (validate interactively, run the next subcommand). Under `all`, pause for human validation after `prd` and `stories` before continuing to `gaps`.
+
+## scan
+
+Entry point of the pipeline: a structured inventory of the codebase.
+
+**1. Stack detection.** Scan the root for framework markers, read the manifest (`composer.json`, `package.json`, `pubspec.yaml`, `*.csproj`, `pyproject.toml`), identify framework version and key dependencies, detect infrastructure (Docker, CI/CD, Redis, queues) and pick the matching reviewer agent (`@symfony-reviewer`, `@react-reviewer`...).
+
+| File pattern | Stack |
+|--------------|-------|
+| `*.php` + `symfony.lock` | Symfony |
+| `*.php` + `artisan` | Laravel |
+| `*.php` + `composer.json` | PHP (generic) |
+| `*.dart` + `pubspec.yaml` | Flutter |
+| `*.tsx` / `*.jsx` + `next.config.*` | React (Next.js) |
+| `*.tsx` / `*.jsx` + `package.json` | React |
+| `*.vue` + `package.json` | Vue.js |
+| `angular.json` | Angular |
+| `*.cs` + `*.csproj` | .NET / C# |
+| `*.py` + `pyproject.toml` | Python |
+| `Dockerfile` / `docker-compose.yml` | Docker (infra) |
+
+**2. Structure scan.** Categorize files into:
+1. Modules / domains (bounded contexts, shared modules, namespaces)
+2. Endpoints (routes, controllers, HTTP methods, paths, middleware/guards)
+3. Models / entities (fields, types, relationships, migrations)
+4. Services (services, use cases, command/query handlers, listeners, subscribers)
+5. Tests (unit / integration / E2E, test-to-source mapping, frameworks)
+6. Infrastructure (Docker, CI/CD, environment config, third-party integrations)
+
+**3. Code analysis.** Estimate LOC per module; identify the architecture pattern (MVC, Clean Architecture, DDD...); detect quality tooling (linting, static analysis); map the module dependency graph; flag technical-debt markers; use the tech-specific reviewer for stack insights.
+
+**4. Report** at `project-management/scan-report.md`, with these sections: header (project, stack, size, modules), Technology Stack, Modules / Bounded Contexts (files, LOC, tests, coverage), Endpoints (method, path, controller, auth), Models / Entities (fields, relationships, migrations), Services (dependencies, type), Tests (type, count, framework), Infrastructure (component, config file, notes) and a Complexity Summary.
+
+```
+| Module   | Files | LOC   | Tests | Coverage |
+| User     | 24    | 1,800 | 12    | ~65%     |
+| Method | Path        | Controller     | Auth |
+| GET    | /api/users  | UserController | JWT  |
+```
+
+Complexity Summary metrics: total LOC, total files, bounded contexts, API endpoints, database entities, test files, estimated test coverage, architecture pattern.
+
+## prd
+
+Brownfield counterpart of `/workflow:plan --only=prd`: a DRAFT PRD inferred from code.
+
+**1. Load** the scan report (and `./docs/`, `README.md`); parse stack, modules, endpoints, entities, services.
+
+**2. Business logic analysis**, for each module: domain events (payloads, listeners, workflows), use cases / commands / queries, validation rules (entity, request, business assertions), state machines (status enums, workflow config, guards), external integrations (payment, email, storage, third-party APIs).
+
+**3. Requirement inference.**
+
+| Code pattern | Inferred requirement |
+|--------------|---------------------|
+| Auth middleware / JWT | User authentication required |
+| Role-based guards | Authorization with roles |
+| CRUD controllers | Data management features |
+| File upload handlers | Document/media management |
+| Email services | Notification system |
+| Payment gateway | Payment processing |
+| Export endpoints | Reporting/export features |
+| Search/filter logic | Search and filtering |
+| Pagination | Large dataset handling |
+| Cache layers | Performance requirements |
+| Queue workers | Async processing requirements |
+| Rate limiting | API protection requirements |
+
+| Infrastructure | Inferred NFR |
+|----------------|--------------|
+| Docker / Kubernetes | Scalability, containerization |
+| Redis / Memcached | Performance caching |
+| Queue system (RabbitMQ...) | Async processing, reliability |
+| CI/CD pipelines | Deployment automation |
+| Load balancer config | High availability |
+| SSL/TLS configuration | Security |
+| Logging stack (ELK...) | Monitoring |
+
+Personas come from the shared persona table above.
+
+**4. Generate** `project-management/prd.md` with eight sections: Executive Summary (INFERRED), Problem Statement (INFERRED), Goals & Metrics (**PLACEHOLDER** -- cannot be inferred, needs human input), Target Users / Personas (INFERRED, each a draft), Functional Requirements (INFERRED, one per feature/endpoint group, prioritized by complexity and usage, tagged with source module), Non-Functional Requirements (INFERRED), Scope & Constraints (INFERRED), Risks & Mitigations (INFERRED: debt, untested areas, dependency risks). Write analysis notes and per-section confidence (HIGH / MEDIUM / LOW) to `project-management/analysis/reverse-engineering.md`; the PRD header shows `Status: DRAFT - Requires human validation` and the confidence table.
+
+**5. Human validation.** Show a summary of inferred sections, highlight low-confidence ones and those that could not be inferred (Goals, Metrics), ask the user to validate / correct / expand each, iterate until satisfied.
+
+## stories
+
+DRAFT user stories inferred from endpoints, services, entities and tests.
+
+**1. Load** the scan report and the PRD if present (for FR-xxx traceability); determine scope (all, a `--module`, an endpoint).
+
+**2. Feature extraction**, per endpoint/feature: controller/handler (method, route, request validation, response and status codes, authorization), service/use case (business flow, side effects, external calls, error paths), entity/model (fields and constraints, relationships, state transitions, soft delete/timestamps), tests (method names, assertions, fixtures, edge cases).
+
+**3. Story generation.**
+
+| Route | Inferred action |
+|-------|-----------------|
+| `POST /api/resources` | create a resource |
+| `GET /api/resources` | list resources |
+| `GET /api/resources/{id}` | view a resource |
+| `PUT /api/resources/{id}` | update a resource |
+| `DELETE /api/resources/{id}` | delete a resource |
+| custom action | from method name and business logic |
+
+Benefit inference: CRUD -> "so that I can manage {resource} data"; search/filter -> "find relevant {resources} quickly"; export -> "use {resource} data externally"; notifications -> "be informed about {event}"; auth -> "my data is secure and accessible only to me". Acceptance criteria come from tests: fixtures -> Given, actions -> When, expectations -> Then.
+
+```markdown
+# US-XXX: [Inferred Title]
+
+> INFERRED -- generated from codebase analysis. Human validation required.
+
+## Source
+- Module / Endpoint ({method} {path}) / Controller / Implements: FR-XXX (if PRD exists)
+
+## User Story
+As [inferred persona] I want [inferred action] So that [inferred benefit]
+Conversation: [ ] persona  [ ] action matches intent  [ ] benefit matches business goals
+INVEST: [ ] Independent / Negotiable / Valuable / Estimable / Sized / Testable
+
+## Acceptance Criteria (Gherkin)
+Scenario: nominal (from happy path)   Given / When / Then
+Scenario: error (from validation)     Given / When / Then
+
+## Technical Notes
+Entity, validation rules, auth requirements, dispatched events
+
+## Estimation
+Story Points (from complexity), MoSCoW (from usage patterns)
+```
+
+**4. Traceability** (if `project-management/prd.md` exists): map each story to an FR-xxx (add `implements: FR-xxx`), list stories without a requirement (code without spec) and requirements without a story (spec without code).
+
+**5. Output and validation.** Save to `project-management/backlog/user-stories/US-001-create-user.md`, `US-002-...`, generate a summary index grouped by module (title, points, MoSCoW, mapped-to-PRD count, unmapped count), then ask the user to validate, correct or reject each story.
+
+## gaps
+
+Compare specifications (PRD, stories, tech spec) with the actual code.
+
+**1. Load specs:** `project-management/prd.md`, `project-management/backlog/user-stories/`, `project-management/tech-spec.md` (if any), the scan report (refresh it by running `scan` if missing or outdated). Parse FR-xxx, NFR-xxx and US-xxx.
+
+**2. Scan code:** catalog endpoints, business logic, data models, tests, infrastructure into a feature inventory indexed by module.
+
+**3. Four-way comparison:**
+
+| Category | Checks |
+|----------|--------|
+| **Spec without code** (not implemented) | FR-xxx without matching endpoint; US-xxx without matching feature; NFR-xxx without matching config |
+| **Code without spec** (undocumented) | Endpoints without FR reference; services without US reference; entities without spec coverage |
+| **Spec-code mismatch** (inconsistent) | Field, status-flow, auth, validation and response-format differences |
+| **Test gaps** (untested) | Features without unit / integration tests; acceptance criteria without E2E tests; error paths without tests |
+
+**4. Classify by severity:**
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Core feature missing or broken; security vulnerability; data integrity risk | Immediate fix |
+| **Major** | Important feature gap; significant mismatch; missing critical tests | Current sprint |
+| **Minor** | Documentation gap; non-critical mismatch; missing edge-case tests | Next sprint |
+| **Info** | Style inconsistency; optional feature; enhancement | Backlog |
+
+Rules: spec without code + P0 = Critical, + P1 = Major, + P2 = Minor; code without spec + auth = Major, + CRUD = Minor; mismatch + data integrity = Critical, + UI/UX = Minor; test gap + business logic = Major, + edge case = Minor.
+
+**5. Report** at `project-management/analysis/gap-analysis.md`: header (project, date, scope), spec / code / test coverage percentages, gap counts per severity, the four category tables with evidence (file paths, line references), and a priority-ranked remediation list with effort (S < 2h, M 2-8h, L > 8h).
+
+```
+| # | Action                              | Severity | Effort |
+| 1 | Implement FR-005 (password reset)   | Critical | M      |
+| 2 | Add integration tests for payment   | Critical | S      |
+```
+
+Then offer: create stories for the missing features, generate tasks for remediation items, or focus on one gap category.
+
+## all
+
+Run `scan` -> `prd` -> `stories` -> `gaps` in order, reusing each output as the next input (no re-scan). Pause for human validation after `prd` and `stories`. End with a recap: files written, number of inferred personas / requirements / stories, gap counts per severity and the top 3 actions.
+
+## Related Commands
+
+- `/workflow:plan --only=prd` - Generate a PRD interactively (greenfield)
+- `/workflow:plan --only=backlog` - Create a SCRUM backlog from the PRD
+- `/workflow:design` - Generate a technical specification
+- `/project:backlog` - Manage epics, stories and tasks

package/Project/i18n/en/commands/run-epic.md

@@ -1,191 +1,9 @@
 ---
-description: Run all stories from an epic in batch
-argument-hint: <epic-id> [--dry-run]
+description: "Deprecated (removed in 9.0): use /workflow:implement --epic"
+deprecated: true
+replaced-by: /workflow:implement
 ---
 
-# Run Epic
+> ⚠️ `/project:run-epic` is deprecated and will be removed in 9.0. Use `/workflow:implement --epic`.
 
-Queue and process all stories from an epic in batch mode.
-
-## Arguments
-
-$ARGUMENTS (format: <epic-id> [--dry-run])
-- **epic-id** (required): Epic identifier (e.g., EPIC-001)
-- **--dry-run** (optional): Preview without executing
-
-## Plan Mode
-
-> **Plan mode is recommended.** Claude activates plan mode to structure the approach, identify dependencies, and present a generation strategy before creating artifacts.
-
-## Process
-
-### Step 1: Identify epic stories
-
-1. Read `.bmad/sprint-status.yaml`
-2. Find all stories with `epic_id` matching argument
-3. Sort by priority or ID
-
-### Step 2: Check story readiness
-
-For each story, verify:
-- Story exists and has required fields
-- Not already completed
-- Not blocked (or flag for review)
-
-### Step 3: Build execution queue
-
-Create prioritized queue:
-1. Stories with no dependencies first
-2. Lower ID = higher priority
-3. Respect explicit priority if set
-
-### Step 4: Add to batch queue
-
-Update `.bmad/batch-queue.yaml`:
-```yaml
-queue:
-  - story_id: "US-001"
-    priority: 1
-    status: "pending"
-    dependencies: []
-  - story_id: "US-002"
-    priority: 2
-    dependencies: ["US-001"]
-```
-
-### Step 5: Execute (unless --dry-run)
-
-For each story in order:
-1. Transition to in-progress
-2. Execute development workflow
-3. Run quality gates
-4. Transition through states
-5. Checkpoint after each
-
-## Output Format
-
-### Dry Run
-
-```
-═══════════════════════════════════════════════════════
-           Run Epic: EPIC-002 (DRY RUN)
-═══════════════════════════════════════════════════════
-
-Epic: EPIC-002 - User Management
-Stories: 5
-
-Execution Plan:
-──────────────────────────────────────────────────────
-[1] US-010: User registration (5 pts)
-    Status: ready-for-dev → in-progress → review → done
-    Dependencies: none
-
-[2] US-011: User login (5 pts)
-    Status: ready-for-dev → in-progress → review → done
-    Dependencies: US-010
-
-[3] US-012: Profile page (5 pts)
-    Status: ready-for-dev → in-progress → review → done
-    Dependencies: US-010
-
-[4] US-013: Password reset (3 pts)
-    Status: ready-for-dev → in-progress → review → done
-    Dependencies: US-010, US-011
-
-[5] US-014: Email verification (3 pts)
-    Status: ready-for-dev → in-progress → review → done
-    Dependencies: US-010
-
-Total Points: 21
-
-Execution Order (respecting dependencies):
-  1. US-010 (no deps)
-  2. US-011, US-012, US-014 (parallel after US-010)
-  3. US-013 (after US-010, US-011)
-
-Estimated workflow per story:
-  • Transition to in-progress
-  • TDD cycles (red → green → refactor)
-  • Code review
-  • Quality gate validation
-  • Transition to done
-
-⚠️ DRY RUN - No changes made
-
-Run without --dry-run to execute.
-═══════════════════════════════════════════════════════
-```
-
-### Execution
-
-```
-═══════════════════════════════════════════════════════
-              Run Epic: EPIC-002
-═══════════════════════════════════════════════════════
-
-Epic: EPIC-002 - User Management
-Mode: Sequential
-Stories: 5
-
-Queuing stories...
-──────────────────────────────────────────────────────
-✅ Added US-010 (priority 1)
-✅ Added US-011 (priority 2, depends on US-010)
-✅ Added US-012 (priority 3, depends on US-010)
-✅ Added US-013 (priority 4, depends on US-010, US-011)
-✅ Added US-014 (priority 5, depends on US-010)
-
-Queue Status:
-──────────────────────────────────────────────────────
-⏳ Pending: 5
-🔄 Running: 0
-✅ Completed: 0
-❌ Failed: 0
-
-Next Steps:
-──────────────────────────────────────────────────────
-Run the queue:
-  /project:run-queue
-
-Or process automatically:
-  /project:run-queue --auto
-
-Monitor progress:
-  /project:batch-status
-═══════════════════════════════════════════════════════
-```
-
-## Example
-
-```
-/project:run-epic EPIC-002 --dry-run
-/project:run-epic EPIC-002
-```
-
-## Parallel Execution
-
-For independent stories, enable parallel mode:
-```
-/project:run-queue --parallel 3
-```
-
-This processes up to 3 stories simultaneously when they have no dependencies.
-
-## Resuming
-
-If execution is interrupted:
-```
-/project:run-queue --resume
-```
-
-Continues from last checkpoint.
-
-## Integration with Ralph
-
-If Ralph is configured, batch execution integrates:
-```yaml
-# ralph.yml
-bmad_integration:
-  enabled: true
-  batch_queue_file: ".bmad/batch-queue.yaml"
-```
+Run `/workflow:implement --epic $ARGUMENTS`: read `.claude/commands/workflow/implement.md` and follow it with these arguments.