agentic-loop 3.9.1 → 3.10.1

package/.claude/commands/tour.md

@@ -25,13 +25,13 @@ Print this exactly:
    - If missing: Say "⚠️ jq not found. Install it: `brew install jq` (macOS) or `apt install jq` (Linux)"
    - If found: ✓ jq installed
 
-2. **Check slash commands:**
+2. **Check slash commands (skills):**
    ```bash
-   test -d .claude/commands && ls .claude/commands/*.md 2>/dev/null | wc -l
+   test -d .claude/skills && ls -d .claude/skills/*/ 2>/dev/null | wc -l
    ```
    - If missing or count is 0: Copy from node_modules:
      ```bash
-     mkdir -p .claude/commands && cp -r node_modules/agentic-loop/.claude/commands/* .claude/commands/
+     mkdir -p .claude/skills && cp -r node_modules/agentic-loop/.claude/skills/* .claude/skills/
      ```
    - Then: ✓ Slash commands installed
 

package/.claude/skills/explain/SKILL.md

@@ -0,0 +1,114 @@
+---
+description: Explain what code does line by line so you can understand and learn from it.
+---
+
+# Explain Code
+
+Explain what code does, line by line, so you can understand and learn from it.
+
+## Instructions
+
+When the user asks you to explain code:
+
+### Step 1: Identify the Code
+
+If the user provides a file path, read that file. If they paste code directly, use that.
+
+If no code is specified, ask:
+> "What code would you like me to explain? Please provide a file path or paste the code."
+
+### Step 2: Provide Overview
+
+Start with a high-level summary:
+- What is the purpose of this code?
+- What problem does it solve?
+- How does it fit into the larger application?
+
+### Step 3: Walk Through Line by Line
+
+For each significant section, explain:
+- **What** it does (literally)
+- **Why** it's needed (purpose)
+- **How** it works (mechanism)
+
+Use this format:
+
+```
+Lines X-Y: [Brief description]
+- This code [what it does]
+- It's needed because [why]
+- It works by [how]
+```
+
+### Step 4: Highlight Key Concepts
+
+Point out important patterns and concepts:
+- Design patterns used
+- Language features that might be unfamiliar
+- Best practices demonstrated
+- Potential gotchas or edge cases
+
+### Step 5: Summarize
+
+End with:
+- Key takeaways
+- What the user should understand now
+- Suggestions for further learning if applicable
+
+## Example Output
+
+```
+## Overview
+
+This is a React custom hook that manages authentication state. It handles
+login, logout, and automatic token refresh.
+
+## Line-by-Line Explanation
+
+### Lines 1-5: Imports
+```typescript
+import { useState, useEffect, useCallback } from 'react';
+import { authApi } from '@/services/api';
+import { User } from '@/types';
+```
+- Imports React hooks for state management and side effects
+- Imports the auth API service for making authentication requests
+- Imports the User type for type safety
+
+### Lines 7-15: Hook Definition and State
+```typescript
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+```
+- Creates a custom hook that can be used in any component
+- `user` state holds the current user (or null if logged out)
+- `loading` state tracks whether we're still checking auth status
+- Starting with `loading: true` prevents flash of unauthenticated content
+
+### Lines 17-30: Auto-refresh Effect
+[... continue explanation ...]
+
+## Key Concepts
+
+1. **Custom Hooks**: Reusable logic extracted from components
+2. **Optimistic Updates**: UI updates before server confirms
+3. **Token Refresh**: Automatic re-authentication before expiry
+
+## Takeaways
+
+- This hook centralizes all auth logic in one place
+- Components just need to call `useAuth()` to access auth state
+- The refresh logic runs automatically in the background
+```
+
+## Tips for Users
+
+Ask me to explain:
+- "Explain this function" (paste code)
+- "Explain src/hooks/useAuth.ts"
+- "Explain lines 50-100 of api.ts"
+- "What does this regex do?"
+- "Why is this pattern used here?"
+
+I'll adjust the depth based on what you ask. For simple code, I'll be brief. For complex code, I'll be thorough.

package/.claude/skills/idea/SKILL.md

@@ -0,0 +1,216 @@
+---
+description: Brainstorm a feature idea, then generate PRDs for Ralph autonomous execution.
+---
+
+# /idea - From Brainstorm to PRD
+
+You are helping the user go from a rough idea to executable PRDs for Ralph.
+
+**CRITICAL: This command does NOT write code. It produces documentation files only.**
+
+## When to Use
+
+| Workflow | Best For |
+|----------|----------|
+| **`/idea`** | Structured brainstorming with guided questions - Claude leads |
+| **Plan mode → save to `docs/ideas/`** | Free-form exploration - you lead the thinking |
+| **`/prd "description"`** | Quick PRD, no docs artifact needed |
+
+**Both `/idea` and plan mode can produce `docs/ideas/*.md` files.** The difference is who drives the conversation:
+- `/idea` asks you structured questions (scope, UX, edge cases, etc.)
+- Plan mode lets you explore freely with Claude's help
+
+Use `/idea` when you want the structured checklist. Use plan mode when you prefer to think through it your way.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Workflow
+
+### Step 1: Start Brainstorming
+
+If `$ARGUMENTS` is empty, ask: "What feature or idea would you like to brainstorm?"
+
+If `$ARGUMENTS` has content, acknowledge it and proceed.
+
+Say: "Let's brainstorm this idea. I'll help you think it through, then we'll create documentation for Ralph to execute."
+
+### Step 2: Explore and Ask Questions
+
+Help the user flesh out the idea through conversation:
+
+1. **Understand the goal** - What problem does this solve? Who benefits?
+2. **Explore the codebase** - Use Glob/Grep/Read to understand what exists and what patterns to follow
+3. **Ask clarifying questions** about:
+
+**Scope & UX:**
+- What's in scope vs out of scope?
+- What does the user see/do? (ask for mockup if UI)
+- What are the edge cases?
+
+**Security (IMPORTANT - ask if feature involves):**
+- Authentication: Who can access this? Login required?
+- Passwords: How stored? (must be hashed, never plain text)
+- User input: What validation needed? (SQL injection, XSS, command injection)
+- Sensitive data: What should NEVER be in API responses?
+- Rate limiting: Should this be rate limited? (login attempts, API calls)
+
+**Scale (IMPORTANT - ask if feature involves lists/data):**
+- How many items expected? (10s, 1000s, millions?)
+- Pagination needed? What's the max per page?
+- Caching needed? How fresh must data be?
+- Database indexes: What will be queried/sorted frequently?
+
+### Step 3: Summarize Before Writing
+
+When you have enough information, summarize what you've learned:
+
+Say: "Here's what I understand about the feature:
+
+**Problem:** [summary]
+**Solution:** [summary]
+**Key decisions:** [list]
+
+Ready to write this to `docs/ideas/{feature-name}.md`? Say **'yes'** or tell me what to adjust."
+
+**STOP and wait for user confirmation before writing any files.**
+
+### Step 4: Write the Idea File
+
+Once the user confirms, write the idea file:
+
+1. Create the directory if needed:
+   ```bash
+   mkdir -p docs/ideas
+   ```
+
+2. Write to `docs/ideas/{feature-name}.md` with this structure:
+   ```markdown
+   # {Feature Name}
+
+   ## Problem
+   What problem does this solve?
+
+   ## Solution
+   High-level description of the solution.
+
+   ## User Stories
+   - As a [user], I want to [action] so that [benefit]
+   - ...
+
+   ## Scope
+   ### In Scope
+   - ...
+
+   ### Out of Scope
+   - ...
+
+   ## Architecture
+   ### Directory Structure
+   - Where new files should go (be specific: `src/components/forms/`, not just `src/`)
+
+   ### Patterns to Follow
+   - Existing components/utilities to reuse
+   - Naming conventions
+
+   ### Do NOT Create
+   - List things that already exist (avoid duplication)
+
+   ## Security Requirements
+   - **Authentication**: Who can access? Login required?
+   - **Password handling**: Must be hashed with bcrypt (cost 10+), never in responses
+   - **Input validation**: What must be validated/sanitized?
+   - **Rate limiting**: What should be rate limited?
+   - **Sensitive data**: What must NEVER appear in logs/responses?
+
+   ## Scale Requirements
+   - **Expected volume**: How many users/items/requests?
+   - **Pagination**: Max items per page (recommend 100)
+   - **Caching**: What can be cached? For how long?
+   - **Database**: What indexes are needed?
+
+   ## UI Mockup (if applicable)
+   ```
+   ┌─────────────────────────────────┐
+   │  [ASCII mockup of the UI]       │
+   └─────────────────────────────────┘
+   ```
+
+   ## Open Questions
+   - Any unresolved decisions
+   ```
+
+3. Say: "I've written the idea to `docs/ideas/{feature-name}.md`.
+
+   Review it and let me know:
+   - **'approved'** - Ready to generate PRD
+   - **'edit [changes]'** - Tell me what to change"
+
+**STOP and wait for user response. Do not proceed until they say 'approved' or 'done'.**
+
+### Step 5: Generate PRD
+
+**Only proceed here after user explicitly approves the idea file.**
+
+Say: "Now I'll generate the PRD from your idea file."
+
+**Use the Skill tool** to invoke `/prd` with the idea file path:
+```
+Skill: prd
+Args: docs/ideas/{feature-name}.md
+```
+
+This hands off to `/prd` which handles:
+- Reading the idea file
+- Splitting into stories
+- Writing `.ralph/prd.json`
+- All PRD schema details (testing, testSteps, MCP tools, etc.)
+
+**DO NOT duplicate the PRD schema or guidelines here - /prd is the single source of truth.**
+
+---
+
+## Error Handling
+
+- If user provides no arguments, ask what they want to brainstorm
+- If user abandons mid-flow, the idea file is still saved for later
+- If /prd fails, check the idea file has enough detail
+
+---
+
+## Guidelines
+
+### Idea File Quality
+
+A good idea file has:
+- **Clear problem statement** - What's broken or missing?
+- **Specific solution** - Not vague ("improve UX") but concrete ("add inline validation")
+- **Scope boundaries** - What's explicitly out of scope?
+- **Architecture hints** - Where do files go? What patterns to follow?
+
+### ASCII Art for UI
+
+If the feature involves UI, include ASCII mockups in the idea file:
+
+```
+┌─────────────────────────────────────┐
+│  Dashboard                    [⚙️]  │
+├─────────────────────────────────────┤
+│                                     │
+│  ┌─────────┐  ┌─────────┐          │
+│  │ Card 1  │  │ Card 2  │          │
+│  │  $1,234 │  │  89%    │          │
+│  └─────────┘  └─────────┘          │
+│                                     │
+│  ┌─────────────────────────────┐   │
+│  │ Recent Activity              │   │
+│  │ • Item 1                     │   │
+│  │ • Item 2                     │   │
+│  └─────────────────────────────┘   │
+└─────────────────────────────────────┘
+```
+
+Ralph will read these from the idea file via `story.contextFiles`.

package/.claude/skills/my-dna/SKILL.md

@@ -0,0 +1,122 @@
+---
+description: Set up your personal DNA - how you like to work and communicate with Claude.
+---
+
+# My DNA - Personal Style Setup
+
+You are helping the user define their DNA - their personal voice and project values. This makes Claude's output match their style.
+
+This updates `CLAUDE.md` in the project root with their values and style.
+
+## Step 1: Introduction
+
+Say: "Let's set up your DNA so I can match your style and values in this project.
+
+Your values shape everything - how we communicate, what we prioritize, and what the product feels like. A few quick questions."
+
+## Step 2: Ask About Core Values
+
+Use AskUserQuestion:
+
+**Question:** "What values should guide this project? Pick any that resonate."
+**Header:** "Core values"
+**multiSelect:** true
+**Options:**
+- **Respect / Kindness** - "Treat people well, in code and communication"
+- **Simplicity / Clarity** - "Avoid jargon, make things understandable"
+- **Sustainability** - "Build things that last, think long-term"
+
+## Step 3: Ask About Their Voice
+
+Use AskUserQuestion:
+
+**Question:** "How would you describe your writing style?"
+**Header:** "Your voice"
+**Options:**
+- **Casual & direct** - "I write like I talk, no fluff"
+- **Friendly & warm** - "Approachable, conversational"
+- **Professional & clear** - "Polished but not stiff"
+- **Minimal & precise** - "Say less, mean more"
+
+## Step 4: Ask About Project Priority
+
+Use AskUserQuestion:
+
+**Question:** "What matters most for this project right now?"
+**Header:** "Priority"
+**Options:**
+- **Ship it** - "Get it working and out the door"
+- **Make it solid** - "Quality and reliability first"
+- **Make it beautiful** - "Design and UX matter most"
+- **Make it scale** - "Building for growth"
+
+## Step 5: Ask About Audience
+
+Use AskUserQuestion:
+
+**Question:** "Who's this for?"
+**Header:** "Audience"
+**Options:**
+- **Developers** - "Technical users who get it"
+- **Everyone** - "Non-technical users, needs to be simple"
+- **Business users** - "Professional, but not coders"
+- **Just me** - "Personal project, I'm the user"
+
+## Step 6: Ask About Product Tone
+
+Use AskUserQuestion:
+
+**Question:** "What vibe should the product have?"
+**Header:** "Product tone"
+**Options:**
+- **Friendly** - "Warm, approachable, maybe playful"
+- **Professional** - "Clean, trustworthy, serious"
+- **Minimal** - "Say less, let the product speak"
+- **Bold** - "Confident, opinionated, distinctive"
+
+## Step 7: Optional Writing Sample
+
+Ask:
+
+"Optional: Paste a writing sample so I can match your voice. Could be anything - an email, a doc, a tweet. Or just say 'skip'."
+
+If they provide a sample, note the patterns and include it. If they skip, move on.
+
+## Step 8: Update CLAUDE.md
+
+Add a DNA section to `CLAUDE.md` in the project root. If CLAUDE.md exists, append. If not, create it.
+
+Use a marker `<!-- my-dna -->` to identify the section. If marker exists, replace that section.
+
+```markdown
+<!-- my-dna -->
+## DNA
+
+### Core Values
+- [List their selected values]
+
+### Voice
+[Their style + any notes from writing sample]
+
+### Project
+- **Priority:** [ship it / solid / beautiful / scale]
+- **Audience:** [developers / everyone / business / just me]
+- **Tone:** [friendly / professional / minimal / bold]
+```
+
+## Step 9: Confirm
+
+Say:
+
+"Done! Added DNA to `CLAUDE.md`.
+
+**Your style:** [One sentence summary, e.g., "Casual and direct, shipping fast for developers with a friendly vibe."]
+
+I'll match this in code, docs, and commits. Run `/my-dna` again anytime to update."
+
+## Notes
+
+- Keep it short - 5 questions max
+- No scanning, just ask
+- If DNA section exists in CLAUDE.md (marker: `<!-- my-dna -->`), replace it
+- The goal is to make Claude's output match their style and values