create-hq 5.0.0

package/template/knowledge/Ralph/05-specifications.md

@@ -0,0 +1,210 @@
+# Specifications & PRDs
+
+## The Role of Specifications
+
+Specifications are the "fuel" for the Ralph loop. They define what needs to be built and how success is measured.
+
+> "I don't write my specs. I generate them. Then I review them and edit them by hand. And then I just let it rip with Ralph."
+> — Geoffrey Huntley
+
+## PRD Structure (Product Requirements Document)
+
+Anthropic recommends a JSON-based PRD format:
+
+```json
+{
+  "project": "video-editor",
+  "version": "1.0",
+  "features": [
+    {
+      "id": "feature-001",
+      "title": "Beat Display",
+      "description": "Display beat markers as visual indicators on clips",
+      "user_story": "As a video editor, I want to see beat markers on my clips so I can align edits to music",
+      "acceptance_criteria": [
+        "Three orange ellipses dots appear below clips with beats",
+        "Dots are visible in both light and dark mode",
+        "Dots update when beats are modified"
+      ],
+      "priority": "high",
+      "passes": false
+    },
+    {
+      "id": "feature-002",
+      "title": "Beat Animation",
+      "description": "Animate beat markers on playback",
+      "acceptance_criteria": [
+        "Dots pulse on beat during playback",
+        "Animation is smooth at 60fps",
+        "Animation respects reduced-motion preferences"
+      ],
+      "priority": "medium",
+      "passes": false
+    }
+  ]
+}
+```
+
+### Key Fields
+
+| Field | Purpose |
+|-------|---------|
+| `id` | Unique identifier for tracking |
+| `title` | Human-readable name |
+| `description` | What the feature does |
+| `user_story` | Who benefits and why |
+| `acceptance_criteria` | Testable requirements |
+| `priority` | Order of implementation |
+| `passes` | Whether the feature is complete |
+
+## The `passes` Flag
+
+The `passes` boolean is critical:
+
+> "Each one of these items in this PRD has a passes flag on it. This tells the LLM whether this is actually passing or not in the application code. So this forms not only a product requirements document but also a test harness."
+> — Matt Pocock
+
+When Ralph runs:
+1. It reads the PRD
+2. Finds items where `passes: false`
+3. Picks ONE item to implement
+4. Implements and verifies
+5. Updates `passes: true` if successful
+
+## Generating Specifications
+
+### Forward Generation (Building New)
+
+1. Start with high-level requirements
+2. Use AI to expand into detailed specs
+3. Review and refine manually
+4. Load into PRD format
+
+Example prompt:
+```
+Generate detailed user stories for a video editing application.
+Include acceptance criteria that can be automatically verified.
+Format as JSON with id, title, description, acceptance_criteria, and passes fields.
+```
+
+### Reverse Generation (Clean Room)
+
+> "Run Ralph in reverse to create a clean room specification."
+> — Geoffrey Huntley
+
+1. Point at existing codebase or product
+2. AI generates specifications from behavior
+3. Review for completeness
+4. Use specs to build clean implementation
+
+This enables:
+- Product cloning (legally)
+- Documentation generation
+- Understanding legacy systems
+- Competitive analysis
+
+## Specification Quality
+
+### Good Specifications
+
+```json
+{
+  "id": "auth-001",
+  "title": "User Login",
+  "description": "Secure user authentication with email/password",
+  "acceptance_criteria": [
+    "Login form has email and password fields",
+    "Password field masks input",
+    "Submit button is disabled until both fields have content",
+    "Invalid credentials show error message",
+    "Successful login redirects to dashboard",
+    "JWT token is stored in httpOnly cookie"
+  ],
+  "passes": false
+}
+```
+
+Characteristics:
+- Specific and measurable
+- Independently testable
+- Small enough to complete in one iteration
+- Clear success criteria
+
+### Bad Specifications
+
+```json
+{
+  "id": "auth-001",
+  "title": "Authentication System",
+  "description": "Build the entire auth system",
+  "acceptance_criteria": [
+    "Users can log in",
+    "It works well",
+    "It's secure"
+  ],
+  "passes": false
+}
+```
+
+Problems:
+- Too broad
+- Vague criteria
+- Not independently testable
+- Impossible to verify "works well"
+
+## Iterating on Specifications
+
+Specifications should evolve:
+
+```
+Initial Spec → AI Expands → Human Reviews → AI Implements →
+Human Verifies → Adjust Spec → Repeat
+```
+
+> "I do a loop by hand... if it doesn't seem right, I go back, I update the specs, I try it again. Prototypes are now free, they're now cheap."
+> — Geoffrey Huntley
+
+## Integration with agents.md
+
+Your `agents.md` should reference the PRD:
+
+```markdown
+# Task Management
+
+When implementing features:
+1. Read `plans/prd.json` for current tasks
+2. Select ONE item where `passes: false`
+3. Implement the feature
+4. Run all tests
+5. If tests pass, update `passes: true`
+6. Commit with message referencing the feature id
+
+# PRD Format
+
+Features are defined in JSON with these fields:
+- id: Unique identifier
+- title: Feature name
+- acceptance_criteria: List of verifiable requirements
+- passes: Boolean indicating completion status
+```
+
+## The Progress File
+
+Alongside the PRD, maintain a progress file:
+
+```
+# progress.txt
+
+[2026-01-13 10:30:15] Starting feature: feature-001 (Beat Display)
+[2026-01-13 10:32:45] Implemented BeatIndicator component
+[2026-01-13 10:33:12] Tests passing: 5/5
+[2026-01-13 10:33:18] Committed: a1b2c3d "feat: add beat display indicators"
+[2026-01-13 10:33:20] Updated PRD: feature-001.passes = true
+[2026-01-13 10:33:25] Starting feature: feature-002 (Beat Animation)
+```
+
+This provides:
+- Audit trail
+- Context for subsequent runs
+- Human oversight capability
+- Debugging information

package/template/knowledge/Ralph/06-agents-md.md

@@ -0,0 +1,222 @@
+# agents.md Guide
+
+## What is agents.md?
+
+`agents.md` (also known as `CLAUDE.md`, `AGENTS.md`, or project-specific names) is a configuration file that provides context and instructions to AI coding agents. It's the "brain" that guides how the agent behaves in your project.
+
+> "We're going to go into the realm of agents.md. We're going to go into the history of agents.md, how it came to be. We're going to look into the problems of agents.md."
+> — Geoffrey Huntley
+
+## History
+
+The concept evolved from:
+1. README files providing project context
+2. .editorconfig for editor settings
+3. Cursor rules and similar tool-specific configs
+4. Standardized agent instructions
+
+## Common Problems
+
+### 1. Over-Specification
+
+Loading too much into agents.md causes context bloat:
+
+> "I typically... if I'm looking at this because I've co-generated this, I would delete the specifications completely because when I'm routing I essentially malloc those specifications myself. I want high control of that mallocing."
+> — Geoffrey Huntley
+
+**Solution**: Keep agents.md minimal. Load specs separately.
+
+### 2. Conflicting Instructions
+
+Multiple ways to do things confuse the agent:
+
+> "Here I have essentially two different ways to build the application, one for Rust, one for web. I don't like this to be honest."
+> — Geoffrey Huntley
+
+**Solution**: One clear path for each action.
+
+### 3. Static Context
+
+agents.md loaded once at start becomes stale.
+
+**Solution**: Use dynamic loading and routing.
+
+### 4. Too Much History
+
+Including change logs and old patterns:
+
+**Solution**: Focus on current state and patterns.
+
+## Structure of a Good agents.md
+
+```markdown
+# Project: [Name]
+
+## Overview
+[1-2 sentences about what this project does]
+
+## Tech Stack
+- Language: TypeScript
+- Framework: React
+- Testing: Jest + React Testing Library
+- Build: Vite
+
+## Directory Structure
+```
+src/
+  components/    # React components
+  hooks/         # Custom hooks
+  utils/         # Utility functions
+  types/         # TypeScript types
+tests/           # Test files
+```
+
+## Commands
+- `npm run dev` - Start development server
+- `npm run build` - Production build
+- `npm test` - Run tests
+- `npm run lint` - Run linter
+- `npm run typecheck` - Type check
+
+## Coding Standards
+- Use functional components with hooks
+- All components must have tests
+- Use TypeScript strict mode
+- Maximum file length: 300 lines
+
+## When Making Changes
+1. Create a new branch
+2. Make changes
+3. Run `npm test`
+4. Run `npm run lint`
+5. Run `npm run typecheck`
+6. Commit with conventional commit message
+
+## Do NOT
+- Modify package.json without approval
+- Delete existing tests
+- Use `any` type
+- Skip type checking
+```
+
+## Mallocing vs. Static Loading
+
+Geoffrey emphasizes controlled "mallocing" of context:
+
+### Static Loading (Traditional)
+```
+Load agents.md → Use for entire session
+```
+
+Problems:
+- Context rot over long sessions
+- Irrelevant context for specific tasks
+- Wasted context window space
+
+### Dynamic Mallocing (Ralph)
+```
+Start task → Load only relevant specs → Complete → Clear → Repeat
+```
+
+Benefits:
+- Fresh context per task
+- Relevant information only
+- Maximum context for actual work
+
+## Integration with Ralph
+
+In Ralph, agents.md provides:
+1. **Base context** - Project structure, commands, standards
+2. **Routing instructions** - How to pick and process tasks
+3. **Back pressure commands** - How to verify work
+
+Example Ralph-optimized agents.md:
+
+```markdown
+# agents.md for Ralph
+
+## Project
+Video editor built with TypeScript/React
+
+## Task Loop
+1. Read `plans/prd.json`
+2. Find first item with `passes: false`
+3. Implement ONLY that feature
+4. Run: `npm test && npm run lint && npm run typecheck`
+5. If all pass: commit and set `passes: true`
+6. If any fail: fix and retry
+7. Write progress to `progress.txt`
+
+## Verification Commands
+```bash
+npm test           # Must pass
+npm run lint       # Must have 0 warnings
+npm run typecheck  # Must have 0 errors
+npm run build      # Must succeed
+```
+
+## Commit Format
+```
+feat(scope): description
+
+- Detail 1
+- Detail 2
+
+Implements: feature-id
+```
+
+## Important
+- ONE feature per iteration
+- ALWAYS run verification before commit
+- NEVER skip tests
+- NEVER modify multiple features at once
+```
+
+## Per-Task Context Loading
+
+For larger projects, use task-specific context:
+
+```
+specs/
+  feature-001.md    # Detailed spec for feature 1
+  feature-002.md    # Detailed spec for feature 2
+  ...
+agents.md           # Base instructions (minimal)
+```
+
+Then instruct the agent:
+```markdown
+## Context Loading
+When working on a feature:
+1. Read `specs/{feature-id}.md` for detailed requirements
+2. Do NOT load other spec files
+3. Focus only on current task
+```
+
+## Anti-Patterns
+
+### 1. Everything in agents.md
+Don't put all specs, examples, and documentation in one file.
+
+### 2. Contradictory Instructions
+Don't say "use functional components" then show class examples.
+
+### 3. Outdated Information
+Don't include deprecated patterns or old APIs.
+
+### 4. Too Verbose
+Don't write paragraphs when bullets suffice.
+
+### 5. No Verification Steps
+Don't skip specifying how to verify changes work.
+
+## Evolving agents.md
+
+> "Approach it from a first principles point of view. Just lop it off, destroy it and create it again."
+> — Geoffrey Huntley
+
+Don't be precious about agents.md. Iterate:
+1. Start minimal
+2. Add as needed
+3. Remove what doesn't work
+4. Keep refining