kodelyth-ecc 2.19.0 → 2.20.0

package/.agent/workflows/prp-plan.md

@@ -1,502 +0,0 @@
----
-description: Create comprehensive feature implementation plan with codebase analysis and pattern extraction
-argument-hint: <feature description | path/to/prd.md>
----
-
-> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
-
-# PRP Plan
-
-Create a detailed, self-contained implementation plan that captures all codebase patterns, conventions, and context needed to implement a feature in a single pass.
-
-**Core Philosophy**: A great plan contains everything needed to implement without asking further questions. Every pattern, every convention, every gotcha — captured once, referenced throughout.
-
-**Golden Rule**: If you would need to search the codebase during implementation, capture that knowledge NOW in the plan.
-
----
-
-## Phase 0 — DETECT
-
-Determine input type from `$ARGUMENTS`:
-
-| Input Pattern | Detection | Action |
-|---|---|---|
-| Path ending in `.prd.md` | File path to PRD | Parse PRD, find next pending phase |
-| Path to `.md` with "Implementation Phases" | PRD-like document | Parse phases, find next pending |
-| Path to any other file | Reference file | Read file for context, treat as free-form |
-| Free-form text | Feature description | Proceed directly to Phase 1 |
-| Empty / blank | No input | Ask user what feature to plan |
-
-### PRD Parsing (when input is a PRD)
-
-1. Read the PRD file with `cat "$PRD_PATH"`
-2. Parse the **Implementation Phases** section
-3. Find phases by status:
-   - Look for `pending` phases
-   - Check dependency chains (a phase may depend on prior phases being `complete`)
-   - Select the **next eligible pending phase**
-4. Extract from the selected phase:
-   - Phase name and description
-   - Acceptance criteria
-   - Dependencies on prior phases
-   - Any scope notes or constraints
-5. Use the phase description as the feature to plan
-
-If no pending phases remain, report that all phases are complete.
-
----
-
-## Phase 1 — PARSE
-
-Extract and clarify the feature requirements.
-
-### Feature Understanding
-
-From the input (PRD phase or free-form description), identify:
-
-- **What** is being built (concrete deliverable)
-- **Why** it matters (user value)
-- **Who** uses it (target user/system)
-- **Where** it fits (which part of the codebase)
-
-### User Story
-
-Format as:
-```
-As a [type of user],
-I want [capability],
-So that [benefit].
-```
-
-### Complexity Assessment
-
-| Level | Indicators | Typical Scope |
-|---|---|---|
-| **Small** | Single file, isolated change, no new dependencies | 1-3 files, <100 lines |
-| **Medium** | Multiple files, follows existing patterns, minor new concepts | 3-10 files, 100-500 lines |
-| **Large** | Cross-cutting concerns, new patterns, external integrations | 10+ files, 500+ lines |
-| **XL** | Architectural changes, new subsystems, migration needed | 20+ files, consider splitting |
-
-### Ambiguity Gate
-
-If any of these are unclear, **STOP and ask the user** before proceeding:
-
-- The core deliverable is vague
-- Success criteria are undefined
-- There are multiple valid interpretations
-- Technical approach has major unknowns
-
-Do NOT guess. Ask. A plan built on assumptions fails during implementation.
-
----
-
-## Phase 2 — EXPLORE
-
-Gather deep codebase intelligence. Search the codebase directly for each category below.
-
-### Codebase Search (8 Categories)
-
-For each category, search using grep, find, and file reading:
-
-1. **Similar Implementations** — Find existing features that resemble the planned one. Look for analogous patterns, endpoints, components, or modules.
-
-2. **Naming Conventions** — Identify how files, functions, variables, classes, and exports are named in the relevant area of the codebase.
-
-3. **Error Handling** — Find how errors are caught, propagated, logged, and returned to users in similar code paths.
-
-4. **Logging Patterns** — Identify what gets logged, at what level, and in what format.
-
-5. **Type Definitions** — Find relevant types, interfaces, schemas, and how they're organized.
-
-6. **Test Patterns** — Find how similar features are tested. Note test file locations, naming, setup/teardown patterns, and assertion styles.
-
-7. **Configuration** — Find relevant config files, environment variables, and feature flags.
-
-8. **Dependencies** — Identify packages, imports, and internal modules used by similar features.
-
-### Codebase Analysis (5 Traces)
-
-Read relevant files to trace:
-
-1. **Entry Points** — How does a request/action enter the system and reach the area you're modifying?
-2. **Data Flow** — How does data move through the relevant code paths?
-3. **State Changes** — What state is modified and where?
-4. **Contracts** — What interfaces, APIs, or protocols must be honored?
-5. **Patterns** — What architectural patterns are used (repository, service, controller, etc.)?
-
-### Unified Discovery Table
-
-Compile findings into a single reference:
-
-| Category | File:Lines | Pattern | Key Snippet |
-|---|---|---|---|
-| Naming | `src/services/userService.ts:1-5` | camelCase services, PascalCase types | `export class UserService` |
-| Error | `src/middleware/errorHandler.ts:10-25` | Custom AppError class | `throw new AppError(...)` |
-| ... | ... | ... | ... |
-
----
-
-## Phase 3 — RESEARCH
-
-If the feature involves external libraries, APIs, or unfamiliar technology:
-
-1. Search the web for official documentation
-2. Find usage examples and best practices
-3. Identify version-specific gotchas
-
-Format each finding as:
-
-```
-KEY_INSIGHT: [what you learned]
-APPLIES_TO: [which part of the plan this affects]
-GOTCHA: [any warnings or version-specific issues]
-```
-
-If the feature uses only well-understood internal patterns, skip this phase and note: "No external research needed — feature uses established internal patterns."
-
----
-
-## Phase 4 — DESIGN
-
-### UX Transformation (if applicable)
-
-Document the before/after user experience:
-
-**Before:**
-```
-┌─────────────────────────────┐
-│  [Current user experience]  │
-│  Show the current flow,     │
-│  what the user sees/does    │
-└─────────────────────────────┘
-```
-
-**After:**
-```
-┌─────────────────────────────┐
-│  [New user experience]      │
-│  Show the improved flow,    │
-│  what changes for the user  │
-└─────────────────────────────┘
-```
-
-### Interaction Changes
-
-| Touchpoint | Before | After | Notes |
-|---|---|---|---|
-| ... | ... | ... | ... |
-
-If the feature is purely backend/internal with no UX change, note: "Internal change — no user-facing UX transformation."
-
----
-
-## Phase 5 — ARCHITECT
-
-### Strategic Design
-
-Define the implementation approach:
-
-- **Approach**: High-level strategy (e.g., "Add new service layer following existing repository pattern")
-- **Alternatives Considered**: What other approaches were evaluated and why they were rejected
-- **Scope**: Concrete boundaries of what WILL be built
-- **NOT Building**: Explicit list of what is OUT OF SCOPE (prevents scope creep during implementation)
-
----
-
-## Phase 6 — GENERATE
-
-Write the full plan document using the template below. Save to `.claude/PRPs/plans/{kebab-case-feature-name}.plan.md`.
-
-Create the directory if it doesn't exist:
-```bash
-mkdir -p .claude/PRPs/plans
-```
-
-### Plan Template
-
-````markdown
-# Plan: [Feature Name]
-
-## Summary
-[2-3 sentence overview]
-
-## User Story
-As a [user], I want [capability], so that [benefit].
-
-## Problem → Solution
-[Current state] → [Desired state]
-
-## Metadata
-- **Complexity**: [Small | Medium | Large | XL]
-- **Source PRD**: [path or "N/A"]
-- **PRD Phase**: [phase name or "N/A"]
-- **Estimated Files**: [count]
-
----
-
-## UX Design
-
-### Before
-[ASCII diagram or "N/A — internal change"]
-
-### After
-[ASCII diagram or "N/A — internal change"]
-
-### Interaction Changes
-| Touchpoint | Before | After | Notes |
-|---|---|---|---|
-
----
-
-## Mandatory Reading
-
-Files that MUST be read before implementing:
-
-| Priority | File | Lines | Why |
-|---|---|---|---|
-| P0 (critical) | `path/to/file` | 1-50 | Core pattern to follow |
-| P1 (important) | `path/to/file` | 10-30 | Related types |
-| P2 (reference) | `path/to/file` | all | Similar implementation |
-
-## External Documentation
-
-| Topic | Source | Key Takeaway |
-|---|---|---|
-| ... | ... | ... |
-
----
-
-## Patterns to Mirror
-
-Code patterns discovered in the codebase. Follow these exactly.
-
-### NAMING_CONVENTION
-// SOURCE: [file:lines]
-[actual code snippet showing the naming pattern]
-
-### ERROR_HANDLING
-// SOURCE: [file:lines]
-[actual code snippet showing error handling]
-
-### LOGGING_PATTERN
-// SOURCE: [file:lines]
-[actual code snippet showing logging]
-
-### REPOSITORY_PATTERN
-// SOURCE: [file:lines]
-[actual code snippet showing data access]
-
-### SERVICE_PATTERN
-// SOURCE: [file:lines]
-[actual code snippet showing service layer]
-
-### TEST_STRUCTURE
-// SOURCE: [file:lines]
-[actual code snippet showing test setup]
-
----
-
-## Files to Change
-
-| File | Action | Justification |
-|---|---|---|
-| `path/to/file.ts` | CREATE | New service for feature |
-| `path/to/existing.ts` | UPDATE | Add new method |
-
-## NOT Building
-
-- [Explicit item 1 that is out of scope]
-- [Explicit item 2 that is out of scope]
-
----
-
-## Step-by-Step Tasks
-
-### Task 1: [Name]
-- **ACTION**: [What to do]
-- **IMPLEMENT**: [Specific code/logic to write]
-- **MIRROR**: [Pattern from Patterns to Mirror section to follow]
-- **IMPORTS**: [Required imports]
-- **GOTCHA**: [Known pitfall to avoid]
-- **VALIDATE**: [How to verify this task is correct]
-
-### Task 2: [Name]
-- **ACTION**: ...
-- **IMPLEMENT**: ...
-- **MIRROR**: ...
-- **IMPORTS**: ...
-- **GOTCHA**: ...
-- **VALIDATE**: ...
-
-[Continue for all tasks...]
-
----
-
-## Testing Strategy
-
-### Unit Tests
-
-| Test | Input | Expected Output | Edge Case? |
-|---|---|---|---|
-| ... | ... | ... | ... |
-
-### Edge Cases Checklist
-- [ ] Empty input
-- [ ] Maximum size input
-- [ ] Invalid types
-- [ ] Concurrent access
-- [ ] Network failure (if applicable)
-- [ ] Permission denied
-
----
-
-## Validation Commands
-
-### Static Analysis
-```bash
-# Run type checker
-[project-specific type check command]
-```
-EXPECT: Zero type errors
-
-### Unit Tests
-```bash
-# Run tests for affected area
-[project-specific test command]
-```
-EXPECT: All tests pass
-
-### Full Test Suite
-```bash
-# Run complete test suite
-[project-specific full test command]
-```
-EXPECT: No regressions
-
-### Database Validation (if applicable)
-```bash
-# Verify schema/migrations
-[project-specific db command]
-```
-EXPECT: Schema up to date
-
-### Browser Validation (if applicable)
-```bash
-# Start dev server and verify
-[project-specific dev server command]
-```
-EXPECT: Feature works as designed
-
-### Manual Validation
-- [ ] [Step-by-step manual verification checklist]
-
----
-
-## Acceptance Criteria
-- [ ] All tasks completed
-- [ ] All validation commands pass
-- [ ] Tests written and passing
-- [ ] No type errors
-- [ ] No lint errors
-- [ ] Matches UX design (if applicable)
-
-## Completion Checklist
-- [ ] Code follows discovered patterns
-- [ ] Error handling matches codebase style
-- [ ] Logging follows codebase conventions
-- [ ] Tests follow test patterns
-- [ ] No hardcoded values
-- [ ] Documentation updated (if needed)
-- [ ] No unnecessary scope additions
-- [ ] Self-contained — no questions needed during implementation
-
-## Risks
-| Risk | Likelihood | Impact | Mitigation |
-|---|---|---|---|
-| ... | ... | ... | ... |
-
-## Notes
-[Any additional context, decisions, or observations]
-```
-
----
-
-## Output
-
-### Save the Plan
-
-Write the generated plan to:
-```
-.claude/PRPs/plans/{kebab-case-feature-name}.plan.md
-```
-
-### Update PRD (if input was a PRD)
-
-If this plan was generated from a PRD phase:
-1. Update the phase status from `pending` to `in-progress`
-2. Add the plan file path as a reference in the phase
-
-### Report to User
-
-```
-## Plan Created
-
-- **File**: .claude/PRPs/plans/{kebab-case-feature-name}.plan.md
-- **Source PRD**: [path or "N/A"]
-- **Phase**: [phase name or "standalone"]
-- **Complexity**: [level]
-- **Scope**: [N files, M tasks]
-- **Key Patterns**: [top 3 discovered patterns]
-- **External Research**: [topics researched or "none needed"]
-- **Risks**: [top risk or "none identified"]
-- **Confidence Score**: [1-10] — likelihood of single-pass implementation
-
-> Next step: Run `/prp-implement .claude/PRPs/plans/{name}.plan.md` to execute this plan.
-```
-
----
-
-## Verification
-
-Before finalizing, verify the plan against these checklists:
-
-### Context Completeness
-- [ ] All relevant files discovered and documented
-- [ ] Naming conventions captured with examples
-- [ ] Error handling patterns documented
-- [ ] Test patterns identified
-- [ ] Dependencies listed
-
-### Implementation Readiness
-- [ ] Every task has ACTION, IMPLEMENT, MIRROR, and VALIDATE
-- [ ] No task requires additional codebase searching
-- [ ] Import paths are specified
-- [ ] GOTCHAs documented where applicable
-
-### Pattern Faithfulness
-- [ ] Code snippets are actual codebase examples (not invented)
-- [ ] SOURCE references point to real files and line numbers
-- [ ] Patterns cover naming, errors, logging, data access, and tests
-- [ ] New code will be indistinguishable from existing code
-
-### Validation Coverage
-- [ ] Static analysis commands specified
-- [ ] Test commands specified
-- [ ] Build verification included
-
-### UX Clarity
-- [ ] Before/after states documented (or marked N/A)
-- [ ] Interaction changes listed
-- [ ] Edge cases for UX identified
-
-### No Prior Knowledge Test
-A developer unfamiliar with this codebase should be able to implement the feature using ONLY this plan, without searching the codebase or asking questions. If not, add the missing context.
-
----
-
-## Next Steps
-
-- Run `/prp-implement <plan-path>` to execute this plan
-- Run `/plan` for quick conversational planning without artifacts
-- Run `/prp-prd` to create a PRD first if scope is unclear
-````

package/.agent/workflows/prp-pr.md

@@ -1,184 +0,0 @@
----
-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
-
-> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
-
-**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. Use `/prp-commit` to commit." |
-| 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.
-
-### PRP Artifacts
-
-Check for related PRP artifacts:
-- `.claude/PRPs/reports/` — Implementation reports
-- `.claude/PRPs/plans/` — Plans that were executed
-- `.claude/PRPs/prds/` — Related PRDs
-
-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 PRP reports/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.