@heyai-rules/pilo-masterkit 1.2.2 → 2.2.0

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

@@ -0,0 +1,447 @@
+---
+description: Interactive PRD generator - problem-first, hypothesis-driven product spec with back-and-forth questioning
+argument-hint: [feature/product idea] (blank = start with questions)
+---
+
+# Product Requirements Document Generator
+
+> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+**Input**: $ARGUMENTS
+
+---
+
+## Your Role
+
+You are a sharp product manager who:
+- Starts with PROBLEMS, not solutions
+- Demands evidence before building
+- Thinks in hypotheses, not specs
+- Asks clarifying questions before assuming
+- Acknowledges uncertainty honestly
+
+**Anti-pattern**: Don't fill sections with fluff. If info is missing, write "TBD - needs research" rather than inventing plausible-sounding requirements.
+
+---
+
+## Process Overview
+
+```
+QUESTION SET 1 → GROUNDING → QUESTION SET 2 → RESEARCH → QUESTION SET 3 → GENERATE
+```
+
+Each question set builds on previous answers. Grounding phases validate assumptions.
+
+---
+
+## Phase 1: INITIATE - Core Problem
+
+**If no input provided**, ask:
+
+> **What do you want to build?**
+> Describe the product, feature, or capability in a few sentences.
+
+**If input provided**, confirm understanding by restating:
+
+> I understand you want to build: {restated understanding}
+> Is this correct, or should I adjust my understanding?
+
+**GATE**: Wait for user response before proceeding.
+
+---
+
+## Phase 2: FOUNDATION - Problem Discovery
+
+Ask these questions (present all at once, user can answer together):
+
+> **Foundation Questions:**
+>
+> 1. **Who** has this problem? Be specific - not just "users" but what type of person/role?
+>
+> 2. **What** problem are they facing? Describe the observable pain, not the assumed need.
+>
+> 3. **Why** can't they solve it today? What alternatives exist and why do they fail?
+>
+> 4. **Why now?** What changed that makes this worth building?
+>
+> 5. **How** will you know if you solved it? What would success look like?
+
+**GATE**: Wait for user responses before proceeding.
+
+---
+
+## Phase 3: GROUNDING - Market & Context Research
+
+After foundation answers, conduct research:
+
+**Research market context:**
+
+1. Find similar products/features in the market
+2. Identify how competitors solve this problem
+3. Note common patterns and anti-patterns
+4. Check for recent trends or changes in this space
+
+Compile findings with direct links, key insights, and any gaps in available information.
+
+**If a codebase exists, explore it in parallel:**
+
+1. Find existing functionality relevant to the product/feature idea
+2. Identify patterns that could be leveraged
+3. Note technical constraints or opportunities
+
+Record file locations, code patterns, and conventions observed.
+
+**Summarize findings to user:**
+
+> **What I found:**
+> - {Market insight 1}
+> - {Competitor approach}
+> - {Relevant pattern from codebase, if applicable}
+>
+> Does this change or refine your thinking?
+
+**GATE**: Brief pause for user input (can be "continue" or adjustments).
+
+---
+
+## Phase 4: DEEP DIVE - Vision & Users
+
+Based on foundation + research, ask:
+
+> **Vision & Users:**
+>
+> 1. **Vision**: In one sentence, what's the ideal end state if this succeeds wildly?
+>
+> 2. **Primary User**: Describe your most important user - their role, context, and what triggers their need.
+>
+> 3. **Job to Be Done**: Complete this: "When [situation], I want to [motivation], so I can [outcome]."
+>
+> 4. **Non-Users**: Who is explicitly NOT the target? Who should we ignore?
+>
+> 5. **Constraints**: What limitations exist? (time, budget, technical, regulatory)
+
+**GATE**: Wait for user responses before proceeding.
+
+---
+
+## Phase 5: GROUNDING - Technical Feasibility
+
+**If a codebase exists, perform two parallel investigations:**
+
+Investigation 1 — Explore feasibility:
+1. Identify existing infrastructure that can be leveraged
+2. Find similar patterns already implemented
+3. Map integration points and dependencies
+4. Locate relevant configuration and type definitions
+
+Record file locations, code patterns, and conventions observed.
+
+Investigation 2 — Analyze constraints:
+1. Trace how existing related features are implemented end-to-end
+2. Map data flow through potential integration points
+3. Identify architectural patterns and boundaries
+4. Estimate complexity based on similar features
+
+Document what exists with precise file:line references. No suggestions.
+
+**If no codebase, research technical approaches:**
+
+1. Find technical approaches others have used
+2. Identify common implementation patterns
+3. Note known technical challenges and pitfalls
+
+Compile findings with citations and gap analysis.
+
+**Summarize to user:**
+
+> **Technical Context:**
+> - Feasibility: {HIGH/MEDIUM/LOW} because {reason}
+> - Can leverage: {existing patterns/infrastructure}
+> - Key technical risk: {main concern}
+>
+> Any technical constraints I should know about?
+
+**GATE**: Brief pause for user input.
+
+---
+
+## Phase 6: DECISIONS - Scope & Approach
+
+Ask final clarifying questions:
+
+> **Scope & Approach:**
+>
+> 1. **MVP Definition**: What's the absolute minimum to test if this works?
+>
+> 2. **Must Have vs Nice to Have**: What 2-3 things MUST be in v1? What can wait?
+>
+> 3. **Key Hypothesis**: Complete this: "We believe [capability] will [solve problem] for [users]. We'll know we're right when [measurable outcome]."
+>
+> 4. **Out of Scope**: What are you explicitly NOT building (even if users ask)?
+>
+> 5. **Open Questions**: What uncertainties could change the approach?
+
+**GATE**: Wait for user responses before generating.
+
+---
+
+## Phase 7: GENERATE - Write PRD
+
+**Output path**: `.claude/PRPs/prds/{kebab-case-name}.prd.md`
+
+Create directory if needed: `mkdir -p .claude/PRPs/prds`
+
+### PRD Template
+
+```markdown
+# {Product/Feature Name}
+
+## Problem Statement
+
+{2-3 sentences: Who has what problem, and what's the cost of not solving it?}
+
+## Evidence
+
+- {User quote, data point, or observation that proves this problem exists}
+- {Another piece of evidence}
+- {If none: "Assumption - needs validation through [method]"}
+
+## Proposed Solution
+
+{One paragraph: What we're building and why this approach over alternatives}
+
+## Key Hypothesis
+
+We believe {capability} will {solve problem} for {users}.
+We'll know we're right when {measurable outcome}.
+
+## What We're NOT Building
+
+- {Out of scope item 1} - {why}
+- {Out of scope item 2} - {why}
+
+## Success Metrics
+
+| Metric | Target | How Measured |
+|--------|--------|--------------|
+| {Primary metric} | {Specific number} | {Method} |
+| {Secondary metric} | {Specific number} | {Method} |
+
+## Open Questions
+
+- [ ] {Unresolved question 1}
+- [ ] {Unresolved question 2}
+
+---
+
+## Users & Context
+
+**Primary User**
+- **Who**: {Specific description}
+- **Current behavior**: {What they do today}
+- **Trigger**: {What moment triggers the need}
+- **Success state**: {What "done" looks like}
+
+**Job to Be Done**
+When {situation}, I want to {motivation}, so I can {outcome}.
+
+**Non-Users**
+{Who this is NOT for and why}
+
+---
+
+## Solution Detail
+
+### Core Capabilities (MoSCoW)
+
+| Priority | Capability | Rationale |
+|----------|------------|-----------|
+| Must | {Feature} | {Why essential} |
+| Must | {Feature} | {Why essential} |
+| Should | {Feature} | {Why important but not blocking} |
+| Could | {Feature} | {Nice to have} |
+| Won't | {Feature} | {Explicitly deferred and why} |
+
+### MVP Scope
+
+{What's the minimum to validate the hypothesis}
+
+### User Flow
+
+{Critical path - shortest journey to value}
+
+---
+
+## Technical Approach
+
+**Feasibility**: {HIGH/MEDIUM/LOW}
+
+**Architecture Notes**
+- {Key technical decision and why}
+- {Dependency or integration point}
+
+**Technical Risks**
+
+| Risk | Likelihood | Mitigation |
+|------|------------|------------|
+| {Risk} | {H/M/L} | {How to handle} |
+
+---
+
+## Implementation Phases
+
+<!--
+  STATUS: pending | in-progress | complete
+  PARALLEL: phases that can run concurrently (e.g., "with 3" or "-")
+  DEPENDS: phases that must complete first (e.g., "1, 2" or "-")
+  PRP: link to generated plan file once created
+-->
+
+| # | Phase | Description | Status | Parallel | Depends | PRP Plan |
+|---|-------|-------------|--------|----------|---------|----------|
+| 1 | {Phase name} | {What this phase delivers} | pending | - | - | - |
+| 2 | {Phase name} | {What this phase delivers} | pending | - | 1 | - |
+| 3 | {Phase name} | {What this phase delivers} | pending | with 4 | 2 | - |
+| 4 | {Phase name} | {What this phase delivers} | pending | with 3 | 2 | - |
+| 5 | {Phase name} | {What this phase delivers} | pending | - | 3, 4 | - |
+
+### Phase Details
+
+**Phase 1: {Name}**
+- **Goal**: {What we're trying to achieve}
+- **Scope**: {Bounded deliverables}
+- **Success signal**: {How we know it's done}
+
+**Phase 2: {Name}**
+- **Goal**: {What we're trying to achieve}
+- **Scope**: {Bounded deliverables}
+- **Success signal**: {How we know it's done}
+
+{Continue for each phase...}
+
+### Parallelism Notes
+
+{Explain which phases can run in parallel and why}
+
+---
+
+## Decisions Log
+
+| Decision | Choice | Alternatives | Rationale |
+|----------|--------|--------------|-----------|
+| {Decision} | {Choice} | {Options considered} | {Why this one} |
+
+---
+
+## Research Summary
+
+**Market Context**
+{Key findings from market research}
+
+**Technical Context**
+{Key findings from technical exploration}
+
+---
+
+*Generated: {timestamp}*
+*Status: DRAFT - needs validation*
+```
+
+---
+
+## Phase 8: OUTPUT - Summary
+
+After generating, report:
+
+```markdown
+## PRD Created
+
+**File**: `.claude/PRPs/prds/{name}.prd.md`
+
+### Summary
+
+**Problem**: {One line}
+**Solution**: {One line}
+**Key Metric**: {Primary success metric}
+
+### Validation Status
+
+| Section | Status |
+|---------|--------|
+| Problem Statement | {Validated/Assumption} |
+| User Research | {Done/Needed} |
+| Technical Feasibility | {Assessed/TBD} |
+| Success Metrics | {Defined/Needs refinement} |
+
+### Open Questions ({count})
+
+{List the open questions that need answers}
+
+### Recommended Next Step
+
+{One of: user research, technical spike, prototype, stakeholder review, etc.}
+
+### Implementation Phases
+
+| # | Phase | Status | Can Parallel |
+|---|-------|--------|--------------|
+{Table of phases from PRD}
+
+### To Start Implementation
+
+Run: `/prp-plan .claude/PRPs/prds/{name}.prd.md`
+
+This will automatically select the next pending phase and create an implementation plan.
+```
+
+---
+
+## Question Flow Summary
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  INITIATE: "What do you want to build?"                 │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  FOUNDATION: Who, What, Why, Why now, How to measure    │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  GROUNDING: Market research, competitor analysis        │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  DEEP DIVE: Vision, Primary user, JTBD, Constraints     │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  GROUNDING: Technical feasibility, codebase exploration │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  DECISIONS: MVP, Must-haves, Hypothesis, Out of scope   │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│  GENERATE: Write PRD to .claude/PRPs/prds/              │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Integration with ECC
+
+After PRD generation:
+- Use `/prp-plan` to create implementation plans from PRD phases
+- Use `/plan` for simpler planning without PRD structure
+- Use `/save-session` to preserve PRD context across sessions
+
+## Success Criteria
+
+- **PROBLEM_VALIDATED**: Problem is specific and evidenced (or marked as assumption)
+- **USER_DEFINED**: Primary user is concrete, not generic
+- **HYPOTHESIS_CLEAR**: Testable hypothesis with measurable outcome
+- **SCOPE_BOUNDED**: Clear must-haves and explicit out-of-scope
+- **QUESTIONS_ACKNOWLEDGED**: Uncertainties are listed, not hidden
+- **ACTIONABLE**: A skeptic could understand why this is worth building

package/.agent/workflows/python-review.md

@@ -89,7 +89,7 @@ Agent:
 ## Static Analysis Results
 ✓ ruff: No issues
 ✓ mypy: No errors
-⚠️ black: 2 files need reformatting
+WARNING: black: 2 files need reformatting
 ✓ bandit: No security issues
 
 ## Issues Found
@@ -155,7 +155,7 @@ with open("config.json") as f:  # Good
 - HIGH: 1
 - MEDIUM: 2
 
-Recommendation: ❌ Block merge until CRITICAL issue is fixed
+Recommendation: FAIL: Block merge until CRITICAL issue is fixed
 
 ## Formatting Required
 Run: `black app/routes/user.py app/services/auth.py`
@@ -165,9 +165,9 @@ Run: `black app/routes/user.py app/services/auth.py`
 
 | Status | Condition |
 |--------|-----------|
-| ✅ Approve | No CRITICAL or HIGH issues |
-| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
-| ❌ Block | CRITICAL or HIGH issues found |
+| PASS: Approve | No CRITICAL or HIGH issues |
+| WARNING: Warning | Only MEDIUM issues (merge with caution) |
+| FAIL: Block | CRITICAL or HIGH issues found |
 
 ## Integration with Other Commands
 

package/.agent/workflows/refactor-clean.md

@@ -69,7 +69,7 @@ Deleted:   12 unused functions
 Skipped:   2 items (tests failed)
 Saved:     ~450 lines removed
 ──────────────────────────────
-All tests passing ✅
+All tests passing PASS:
 ```
 
 ## Rules

package/.agent/workflows/resume-session.md

@@ -65,9 +65,9 @@ WHAT WE'RE BUILDING:
 [2-3 sentence summary in your own words]
 
 CURRENT STATE:
-✅ Working: [count] items confirmed
-🔄 In Progress: [list files that are in progress]
-🗒️ Not Started: [list planned but untouched]
+PASS: Working: [count] items confirmed
+ In Progress: [list files that are in progress]
+ Not Started: [list planned but untouched]
 
 WHAT NOT TO RETRY:
 [list every failed approach with its reason — this is critical]
@@ -99,10 +99,10 @@ If no next step is defined — ask the user where to start, and optionally sugge
 Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
 
 **Session file references files that no longer exist:**
-Note this during the briefing — "⚠️ `path/to/file.ts` referenced in session but not found on disk."
+Note this during the briefing — "WARNING: `path/to/file.ts` referenced in session but not found on disk."
 
 **Session file is from more than 7 days ago:**
-Note the gap — "⚠️ This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
+Note the gap — "WARNING: This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
 
 **User provides a file path directly (e.g., forwarded from a teammate):**
 Read it and follow the same briefing process — the format is the same regardless of source.
@@ -126,13 +126,13 @@ Register and login endpoints are partially done. Route protection
 via middleware hasn't been started yet.
 
 CURRENT STATE:
-✅ Working: 3 items (register endpoint, JWT generation, password hashing)
-🔄 In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
-🗒️ Not Started: middleware.ts, app/login/page.tsx
+PASS: Working: 3 items (register endpoint, JWT generation, password hashing)
+ In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
+ Not Started: middleware.ts, app/login/page.tsx
 
 WHAT NOT TO RETRY:
-❌ Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
-❌ localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
+FAIL: Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
+FAIL: localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
 
 OPEN QUESTIONS / BLOCKERS:
 - Does cookies().set() work inside a Route Handler or only Server Actions?

package/.agent/workflows/rules-distill.md

@@ -1,11 +1,20 @@
 ---
-description: "Scan skills to extract cross-cutting principles and distill them into rules"
+description: Legacy slash-entry shim for the rules-distill skill. Prefer the skill directly.
 ---
 
-# /rules-distill — Distill Principles from Skills into Rules
+# Rules Distill (Legacy Shim)
 
-Scan installed skills, extract cross-cutting principles, and distill them into rules.
+Use this only if you still invoke `/rules-distill`. The maintained workflow lives in `skills/rules-distill/SKILL.md`.
 
-## Process
+## Canonical Surface
 
-Follow the full workflow defined in the `rules-distill` skill.
+- Prefer the `rules-distill` skill directly.
+- Keep this file only as a compatibility entry point.
+
+## Arguments
+
+`$ARGUMENTS`
+
+## Delegation
+
+Apply the `rules-distill` skill and follow its inventory, cross-read, and verdict workflow instead of duplicating that logic here.