@pageai/ralph-loop 1.0.0

package/.agent/skills/prd-creator/PRD.md

@@ -0,0 +1,196 @@
+# PRD Creation Through Structured Questioning
+
+Help beginner-level developers transform software ideas into comprehensive PRD.md files through structured questioning.
+
+## Conversation Flow
+
+1. Introduce yourself briefly and explain you'll ask clarifying questions before creating a PRD
+2. Ask questions one at a time conversationally
+3. Focus 70% on understanding the concept, 30% on educating about options
+4. Keep tone friendly and supportive, use plain language
+5. Track assumptions throughout - they'll go in the PRD
+
+## Topics to Cover
+
+Gather information on these aspects:
+
+1. Core features and functionality
+2. Target audience
+3. Platform (web, mobile, desktop)
+4. User flows (how users move through the app)
+5. UI/UX concepts
+6. Data storage and management
+7. Authentication (if relevant) and security
+8. Third-party integrations (if relevant)
+9.  [optional] Wireframes or diagrams
+10. [optional] Competitive landscape
+11. Dependencies
+
+## Questioning Patterns
+
+- Start broad: "Tell me about your app idea at a high level"
+- Core features: "What are the 3-5 core features that make this valuable?"
+- Priorities: "Which features are must-haves for the initial version?"
+- User journeys: "Walk me through what a user does from opening the app to completing their main goal"
+- Competition: "What similar products exist? What should yours do differently?"
+- Assumptions: "What are you assuming about your users, technology, or market?"
+- Wireframes: "Can you explain the flow and what happens when users interact with each screen?"
+- Reflective: "So if I understand correctly, you're building [summary]. Is that accurate?"
+
+## Technology Discussions
+
+- Provide 3-4 options with pros/cons
+- Give your best recommendation with brief reasoning
+- Stay conceptual, not deeply technical
+- Proactively suggest technologies the idea requires
+- If the user provides technology preferences, use them to guide your recommendations
+- Use AskUserQuestion tool to ask about a11y
+  *NB:* only include a11y tasks if the user request it. Keep in mind what they build might not have a UI or be a prototype.
+- Use AskUserQuestion tool to ask about performance considerations
+  *NB:* only include performance tasks if the user request it. Keep in mind what they build might not have a UI or be a prototype.
+
+**Example**: "For this app, you could use React Native (cross-platform, faster development) or native development (better performance, device integration). Given your need for camera integration and offline support, I'd recommend native development."
+
+## PRD Creation Workflow
+
+**CRITICAL**: Don't create the PRD until you have all necessary information, including needed libraries, frameworks, 3rd party integrations, etc. Use AskUserQuestion tool multiple times to clarify specs, technology choices, and requirements.
+
+Copy and track progress through these steps:
+
+```
+PRD Progress:
+- [ ] Gather all required information via questioning
+- [ ] Create executive summary for user validation
+- [ ] Get user confirmation to proceed
+- [ ] Research competitive landscape (if not done)
+- [ ] Generate comprehensive PRD
+- [ ] Present and gather feedback
+- [ ] Iterate based on feedback
+```
+
+### Step 1: Gather Information
+
+Use AskUserQuestion tool repeatedly to clarify:
+- Core features that are unclear
+- Technology options and user preferences
+- Priorities between conflicting requirements
+- Any assumptions that could significantly impact the PRD
+
+Ask related questions per tool call for efficiency. Provide 3-4 clear options per question with trade-off descriptions. Mark recommended options with "(Recommended)".
+
+### Step 2: Executive Summary Validation
+
+Before writing the full PRD:
+1. Summarize in 2-3 paragraphs: problem solved, target users, core value proposition, key features, key user flows
+2. List main assumptions you're making
+3. Ask: "Does this accurately capture your vision? Should I proceed with the full PRD?"
+4. **Only continue after confirmation**
+
+### Step 3: Competitive Research
+
+If this is a commercial app with a potential revenue model, you should research the competitive landscape to identify differentiators and opportunities.
+
+Use WebSearch to:
+- Find similar products: "[app category] apps 2026", "best [problem space] tools"
+- Identify differentiators
+- Use the findings to further refine the PRD
+- For each identified differentiator, use the AskUserQuestion tool to clarify if it should be included in the PRD
+
+### Step 4: Generate PRD
+
+Create PRD containing all identified requirements and use an ID to track each requirement, formatted as `TASK-${ID}`.
+
+Include the following sections:
+- App overview, objectives and success criteria
+- Short summary of target audience
+- (for commercial apps): Competitive landscape and differentiation
+- Core features and functionality
+- Key user flows and journeys
+- Technical stack recommendations
+- Conceptual data model
+- UI design principles (include wireframe analysis if provided)
+- Security considerations
+- Development phases/milestones
+- Assumptions and dependencies
+- Potential challenges and solutions
+- Future expansion possibilities
+
+Save as: `PROJECT_ROOT/.agent/prd/PRD.md`
+
+### Step 5: Iterate
+
+Ask specific questions about sections rather than general feedback. Use Sequential Thinking for systematic feedback processing. Present revised version with change explanations.
+
+## Developer Handoff Guidelines
+
+Optimize for handoff to engineers (human or AI):
+
+- Include implementation details without prescriptive code
+- Define clear acceptance criteria per feature
+- Use terminology mappable to code components
+- Structure data models with explicit field names, types, relationships
+- Specify technical constraints and API integration points
+- Organize features in logical sprint groupings
+- Include pseudocode for complex features
+- Link to relevant technology documentation
+
+## Specification Examples
+
+**Feature Specification:**
+```
+User Authentication Feature:
+- Support email/password and OAuth 2.0 (Google, Apple) login methods
+- Implement JWT token-based session management
+- Required user profile fields: email (string, unique), name (string), avatar (image URL)
+- Acceptance criteria: Users can create accounts, log in via both methods, recover passwords, and maintain persistent sessions across app restarts
+```
+
+**User Flow:**
+```
+Content Creation Flow:
+1. User clicks 'Create' button on dashboard
+2. User selects content type (text post, image, video)
+3. User fills in content details (title, description, tags)
+4. User previews content before publishing
+5. User clicks 'Publish' → Content appears in their profile feed
+6. User can share via native share sheet (iOS/Android) or copy link (Web)
+- Error states: Handle upload failures, size limits exceeded, network timeouts
+```
+
+## Wireframe Analysis
+
+When users provide wireframes or mockups:
+
+1. Use Read tool to view image files
+2. For each screen, identify:
+   - UI components (buttons, forms, navigation)
+   - User interactions (taps, swipes, submissions)
+   - State changes on interaction
+   - Navigation flow between screens
+   - Data sources
+3. Ask clarifying questions via AskUserQuestion tool:
+   - "What happens when the user clicks [element]?"
+   - "Where does [data/content] come from?"
+   - "What error states should we handle?"
+4. Include insights in PRD's "UI Design Principles" section
+5. Map to user flows in "Key User Flows" section
+
+## After PRD Completion
+
+Once the PRD is complete and approved, inform the user:
+"Your PRD is complete and saved. Would you like me to proceed to the next step and generate implementation tasks for developers? See [JSON.md](JSON.md)."
+
+**CRITICAL**: Make the plan extremely concise. Sacrifice grammar for the sake of concision.
+
+---
+
+## Checklist
+
+Before saving the PRD:
+
+- [ ] Asked clarifying questions with lettered options
+- [ ] Incorporated user's answers
+- [ ] User stories are small and specific
+- [ ] Functional requirements are numbered and unambiguous
+- [ ] Non-goals section defines clear boundaries
+- [ ] Saved to `PROJECT_ROOT/.agent/prd/PRD.md`

package/.agent/skills/prd-creator/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: prd-creator
+description: Guides creation of comprehensive Product Requirement Documents (PRDs) for software projects through structured questioning and validation, then generates implementation task lists in JSON format. Use when users want to document a software idea, create specifications for development, plan a new application feature/bug, or break down requirements into actionable tasks. Transforms ideas into implementation-ready documents with verifiable pass criteria.
+---
+
+# PRD Creation Assistant
+
+Transform software ideas into comprehensive PRDs and actionable implementation tasks through a two-part process.
+
+## Overview
+
+This skill helps beginner-level developers.
+
+1. Receive an implementation description from the user
+2. Create detailed PRD documents through structured questioning
+3. Generate implementation task lists in JSON format for developers
+4. Write an overall description of the project. An executive summary that gives a high level overview of the app and its main features.
+
+### Part 1: Implementation Description
+
+You will receive a lacking implementation description from the user.
+The main goal is to comprehend the intent and think about the larger architecture and a robust way to implement it, filling in the gaps.
+
+### Part 2: PRD Creation
+
+**File**: [PRD.md](PRD.md)
+
+You will need to ask clarifying questions to get a clear understanding of the implementation.
+
+**When to use**: User wants to document a software idea or create feature specifications
+
+**What it does**:
+- Guides structured questioning to gather all requirements
+- Creates executive summary for validation
+- Researches competitive landscape
+- Generates comprehensive PRD.md with:
+  - App overview and objectives
+  - Target audience
+  - Success metrics and KPIs
+  - Competitive analysis
+  - Core features and user flows
+  - Technical stack recommendations
+  - Security considerations
+  - Assumptions and dependencies
+
+**Process**:
+1. Ask clarifying questions using `AskUserQuestion` tool
+2. Create executive summary for user approval
+3. Research competition via WebSearch
+4. Generate complete PRD
+5. Iterate based on feedback
+
+**Read [PRD.md](PRD.md) for complete instructions.**
+
+---
+
+### Part 3: Implementation Task Generation
+
+**File**: [JSON.md](JSON.md)
+
+You will need to analyze the completed PRD and generate a comprehensive task list in JSON format.
+
+**When to use**: After PRD is complete and approved, or user requests task breakdown
+
+**What it does**:
+- Analyzes the completed PRD
+- Generates a complete list of implementation tasks in JSON format, covering all features and requirements from the PRD
+- Keeps the tasks small and manageable
+- Categorizes tasks by type (functional, ui-ux, api-endpoint, security, etc.)
+- Defines verification ('pass') steps for each task
+- Creates developer-ready checklist
+
+**IMPORTANT**:
+- Each task should be simple enough to be completed in maximum 10 minutes.
+- If a task is too complex, it should be split into smaller tasks.
+
+**Read [JSON.md](JSON.md) for complete instructions.**
+
+## Part 4: Overall Description
+
+You will need to read the completed PRD and generate an overall description of the project in `PROJECT_ROOT/.agent/prd/SUMMARY.md`.
+
+The description should be short, concise and contain:
+- An overall description of the project
+- The main features of the app
+- Key user flows
+- A short list of key requirements
+
+## Quick Start
+
+**If user wants to create a PRD:**
+1. Read [PRD.md](PRD.md)
+2. Follow the PRD creation workflow
+3. If needed, update the overall description [SUMMARY.md](SUMMARY.md)
+4. After PRD completion, ask: "Would you like me to generate implementation tasks? See Part 2."
+
+**If user wants implementation tasks for an existing PRD:**
+1. Read [JSON.md](JSON.md)
+2. Read the PRD file
+3. Generate comprehensive task list in JSON format
+4. Save as `tasks.json`
+
+**If user wants both:**
+1. Complete PRD creation first [PRD.md](PRD.md)
+2. Get user approval on PRD
+3. If needed, update the overall description [SUMMARY.md](SUMMARY.md)
+4. Proceed to generate implementation tasks [JSON.md](JSON.md)
+
+**If a user want to update the PRD:**
+1. Read [PRD.md](PRD.md)
+2. Update the PRD
+3. Save as `PRD.md`
+4. If needed, update the overall description [SUMMARY.md](SUMMARY.md)
+5. Ask user if they want to generate implementation tasks
+
+**If a user want to update the implementation tasks:**
+1. Read [JSON.md](JSON.md)
+2. Update the implementation tasks
+3. Save as `tasks.json`
+4. Ask user if they want to update the PRD again
+
+**If user wants to update both the PRD and the implementation tasks:**
+1. Update the PRD first [PRD.md](PRD.md)
+2. If needed, update the overall description [SUMMARY.md](SUMMARY.md)
+3. Update the implementation tasks [JSON.md](JSON.md)
+4. Save as `PRD.md` and `tasks.json`
+
+## After completion
+
+Ensure the required files are present:
+- PROJECT_ROOT/.agent/prd/PRD.md
+- PROJECT_ROOT/.agent/prd/SUMMARY.md
+- PROJECT_ROOT/.agent/tasks.json
+
+If they are not present, warn the user and ask if they would like to create any of them.
+
+## Important Constraints
+
+- Do not generate code - focus on documentation and task specification
+- Use AskUserQuestion extensively in Part 1 to clarify requirements
+- In Part 2, generate comprehensive task lists (50-200+ tasks for typical projects)
+- Always initialize tasks with `"passes": false` - never mark tasks complete during generation
+- Use available tools: AskUserQuestion, WebSearch, Sequential Thinking, Read