@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

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

@@ -0,0 +1,502 @@
+---
+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

@@ -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
+
+> 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.