diff --git a/skills/ralph-tui-create-beads-rust/SKILL.md b/skills/ralph-tui-create-beads-rust/SKILL.md index 7aa0c34e..8d655b85 100644 --- a/skills/ralph-tui-create-beads-rust/SKILL.md +++ b/skills/ralph-tui-create-beads-rust/SKILL.md @@ -76,44 +76,19 @@ EOF ## Story Size: The #1 Rule -**Each story must be completable in ONE ralph-tui iteration (~one agent context window).** +Each story must be completable in ONE ralph-tui iteration (~one agent context window). ralph-tui spawns a fresh agent per iteration with no memory of previous work. -ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing. +**Right-sized:** Add a database column + migration. Add a UI component. Update a server action. Add a filter dropdown. -### Right-sized stories: -- Add a database column + migration -- Add a UI component to an existing page -- Update a server action with new logic -- Add a filter dropdown to a list - -### Too big (split these): -- "Build the entire dashboard" → Split into: schema, queries, UI components, filters -- "Add authentication" → Split into: schema, middleware, login UI, session handling -- "Refactor the API" → Split into one story per endpoint or pattern +**Too big (split these):** "Build the entire dashboard" → schema, queries, UI, filters. "Add authentication" → schema, middleware, login UI, sessions. **Rule of thumb:** If you can't describe the change in 2-3 sentences, it's too big. --- -## Story Ordering: Dependencies First - -Stories execute in dependency order. Earlier stories must not depend on later ones. - -**Correct order:** -1. Schema/database changes (migrations) -2. Server actions / backend logic -3. UI components that use the backend -4. Dashboard/summary views that aggregate data - -**Wrong order:** -1. ❌ UI component (depends on schema that doesn't exist yet) -2. ❌ Schema change - ---- - ## Dependencies with `br dep add` -Use the `br dep add` command to specify which beads must complete first: +Stories execute in dependency order (schema → backend → UI → integration). Use `br dep add` to specify which beads must complete first: ```bash # Create the beads first @@ -128,35 +103,15 @@ br dep add ralph-tui-003 ralph-tui-002 # US-003 depends on US-002 **Syntax:** `br dep add ` — the issue depends on (is blocked by) depends-on. -ralph-tui will: -- Show blocked beads as "blocked" until dependencies complete -- Never select a bead for execution while its dependencies are open -- Include dependency context in the prompt when working on a bead - -**Correct dependency order:** -1. Schema/database changes (no dependencies) -2. Backend logic (depends on schema) -3. UI components (depends on backend) -4. Integration/polish (depends on UI) +ralph-tui will show blocked beads as "blocked" until dependencies complete, and include dependency context in the prompt when working on a bead. --- ## Acceptance Criteria: Quality Gates + Story-Specific -Each bead's description should include acceptance criteria with: -1. **Story-specific criteria** from the PRD (what this story accomplishes) -2. **Quality gates** from the PRD's Quality Gates section (appended at the end) - -### Good criteria (verifiable): -- "Add `investorType` column to investor table with default 'cold'" -- "Filter dropdown has options: All, Cold, Friend" -- "Clicking toggle shows confirmation dialog" +Each bead's description should include story-specific acceptance criteria from the PRD, plus quality gates appended from the Quality Gates section. -### Bad criteria (vague): -- ❌ "Works correctly" -- ❌ "User can do X easily" -- ❌ "Good UX" -- ❌ "Handles edge cases" +Criteria must be verifiable: "Add `investorType` column with default 'cold'" is good. "Works correctly" or "Good UX" is bad. --- @@ -164,12 +119,11 @@ Each bead's description should include acceptance criteria with: 1. **Extract Quality Gates** from PRD first 2. **Each user story → one bead** -3. **First story**: No dependencies (creates foundation) -4. **Subsequent stories**: Depend on their predecessors (UI depends on backend, etc.) -5. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog) -6. **All stories**: `status: "open"` -7. **Acceptance criteria**: Story criteria + quality gates appended -8. **UI stories**: Also append UI-specific gates (browser verification) +3. **Dependencies**: Schema/database → backend → UI → integration (use `br dep add` after creating beads) +4. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog) +5. **All stories**: `status: "open"` +6. **Acceptance criteria**: Story criteria + quality gates appended +7. **UI stories**: Also append UI-specific gates (browser verification) --- @@ -329,23 +283,16 @@ ralph-tui run --tracker beads-rust --epic ralph-tui-abc ralph-tui run --tracker beads-rust ``` -ralph-tui will: -1. Work on beads within the specified epic (or select the best available task) -2. Close each bead when complete -3. Close the epic when all children are done -4. Output `COMPLETE` when epic is done +ralph-tui will work on beads, close each when complete, and output `COMPLETE` when the epic is done. --- ## Checklist Before Creating Beads -- [ ] Extracted Quality Gates from PRD (or asked user if missing) -- [ ] Each story is completable in one iteration (small enough) -- [ ] Stories are ordered by dependency (schema → backend → UI) +- [ ] Extracted Quality Gates from PRD +- [ ] Each story is completable in one iteration +- [ ] Stories ordered by dependency (schema → backend → UI) - [ ] Quality gates appended to every bead's acceptance criteria -- [ ] UI stories have browser verification (if specified in Quality Gates) -- [ ] Acceptance criteria are verifiable (not vague) -- [ ] No story depends on a later story (only earlier stories) - [ ] Dependencies added with `br dep add` after creating beads - [ ] Ran `br sync --flush-only` to export for git tracking diff --git a/skills/ralph-tui-create-beads/SKILL.md b/skills/ralph-tui-create-beads/SKILL.md index 63e93287..a22f282a 100644 --- a/skills/ralph-tui-create-beads/SKILL.md +++ b/skills/ralph-tui-create-beads/SKILL.md @@ -76,44 +76,19 @@ EOF ## Story Size: The #1 Rule -**Each story must be completable in ONE ralph-tui iteration (~one agent context window).** +Each story must be completable in ONE ralph-tui iteration (~one agent context window). ralph-tui spawns a fresh agent per iteration with no memory of previous work. -ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing. +**Right-sized:** Add a database column + migration. Add a UI component. Update a server action. Add a filter dropdown. -### Right-sized stories: -- Add a database column + migration -- Add a UI component to an existing page -- Update a server action with new logic -- Add a filter dropdown to a list - -### Too big (split these): -- "Build the entire dashboard" → Split into: schema, queries, UI components, filters -- "Add authentication" → Split into: schema, middleware, login UI, session handling -- "Refactor the API" → Split into one story per endpoint or pattern +**Too big (split these):** "Build the entire dashboard" → schema, queries, UI, filters. "Add authentication" → schema, middleware, login UI, sessions. **Rule of thumb:** If you can't describe the change in 2-3 sentences, it's too big. --- -## Story Ordering: Dependencies First - -Stories execute in dependency order. Earlier stories must not depend on later ones. - -**Correct order:** -1. Schema/database changes (migrations) -2. Server actions / backend logic -3. UI components that use the backend -4. Dashboard/summary views that aggregate data - -**Wrong order:** -1. ❌ UI component (depends on schema that doesn't exist yet) -2. ❌ Schema change - ---- - ## Dependencies with `bd dep add` -Use the `bd dep add` command to specify which beads must complete first: +Stories execute in dependency order (schema → backend → UI → integration). Use `bd dep add` to specify which beads must complete first: ```bash # Create the beads first @@ -128,35 +103,15 @@ bd dep add ralph-tui-003 ralph-tui-002 # US-003 depends on US-002 **Syntax:** `bd dep add ` — the issue depends on (is blocked by) depends-on. -ralph-tui will: -- Show blocked beads as "blocked" until dependencies complete -- Never select a bead for execution while its dependencies are open -- Include dependency context in the prompt when working on a bead - -**Correct dependency order:** -1. Schema/database changes (no dependencies) -2. Backend logic (depends on schema) -3. UI components (depends on backend) -4. Integration/polish (depends on UI) +ralph-tui will show blocked beads as "blocked" until dependencies complete, and include dependency context in the prompt when working on a bead. --- ## Acceptance Criteria: Quality Gates + Story-Specific -Each bead's description should include acceptance criteria with: -1. **Story-specific criteria** from the PRD (what this story accomplishes) -2. **Quality gates** from the PRD's Quality Gates section (appended at the end) - -### Good criteria (verifiable): -- "Add `investorType` column to investor table with default 'cold'" -- "Filter dropdown has options: All, Cold, Friend" -- "Clicking toggle shows confirmation dialog" +Each bead's description should include story-specific acceptance criteria from the PRD, plus quality gates appended from the Quality Gates section. -### Bad criteria (vague): -- ❌ "Works correctly" -- ❌ "User can do X easily" -- ❌ "Good UX" -- ❌ "Handles edge cases" +Criteria must be verifiable: "Add `investorType` column with default 'cold'" is good. "Works correctly" or "Good UX" is bad. --- @@ -164,12 +119,11 @@ Each bead's description should include acceptance criteria with: 1. **Extract Quality Gates** from PRD first 2. **Each user story → one bead** -3. **First story**: No dependencies (creates foundation) -4. **Subsequent stories**: Depend on their predecessors (UI depends on backend, etc.) -5. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog) -6. **All stories**: `status: "open"` -7. **Acceptance criteria**: Story criteria + quality gates appended -8. **UI stories**: Also append UI-specific gates (browser verification) +3. **Dependencies**: Schema/database → backend → UI → integration (use `bd dep add` after creating beads) +4. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog) +5. **All stories**: `status: "open"` +6. **Acceptance criteria**: Story criteria + quality gates appended +7. **UI stories**: Also append UI-specific gates (browser verification) --- @@ -317,21 +271,14 @@ ralph-tui run --tracker beads --epic ralph-tui-abc ralph-tui run --tracker beads ``` -ralph-tui will: -1. Work on beads within the specified epic (or select the best available task) -2. Close each bead when complete -3. Close the epic when all children are done -4. Output `COMPLETE` when epic is done +ralph-tui will work on beads, close each when complete, and output `COMPLETE` when the epic is done. --- ## Checklist Before Creating Beads -- [ ] Extracted Quality Gates from PRD (or asked user if missing) -- [ ] Each story is completable in one iteration (small enough) -- [ ] Stories are ordered by dependency (schema → backend → UI) +- [ ] Extracted Quality Gates from PRD +- [ ] Each story is completable in one iteration +- [ ] Stories ordered by dependency (schema → backend → UI) - [ ] Quality gates appended to every bead's acceptance criteria -- [ ] UI stories have browser verification (if specified in Quality Gates) -- [ ] Acceptance criteria are verifiable (not vague) -- [ ] No story depends on a later story (only earlier stories) - [ ] Dependencies added with `bd dep add` after creating beads diff --git a/skills/ralph-tui-create-json/SKILL.md b/skills/ralph-tui-create-json/SKILL.md index ad783841..ac6916e3 100644 --- a/skills/ralph-tui-create-json/SKILL.md +++ b/skills/ralph-tui-create-json/SKILL.md @@ -165,20 +165,11 @@ Use `"passes": false` for incomplete stories, `"passes": true` for completed. ## Story Size: The #1 Rule -**Each story must be completable in ONE ralph-tui iteration (~one agent context window).** +Each story must be completable in ONE ralph-tui iteration (~one agent context window). Ralph-tui spawns a fresh agent per iteration with no memory of previous work. -Ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing. +**Right-sized:** Add a database column + migration. Add a UI component. Update a server action. Add a filter dropdown. -### Right-sized stories: -- Add a database column + migration -- Add a UI component to an existing page -- Update a server action with new logic -- Add a filter dropdown to a list - -### Too big (split these): -- "Build the entire dashboard" → Split into: schema, queries, UI components, filters -- "Add authentication" → Split into: schema, middleware, login UI, session handling -- "Refactor the API" → Split into one story per endpoint or pattern +**Too big (split these):** "Build the entire dashboard" → schema, queries, UI, filters. "Add authentication" → schema, middleware, login UI, sessions. **Rule of thumb:** If you can't describe the change in 2-3 sentences, it's too big. @@ -186,46 +177,26 @@ Ralph-tui spawns a fresh agent instance per iteration with no memory of previous ## Dependencies with `dependsOn` -Use the `dependsOn` array to specify which stories must complete first: +Use the `dependsOn` array to specify which stories must complete first. Ralph-tui will show stories as "blocked" until dependencies complete. ```json { "id": "US-002", "title": "Create API endpoints", - "dependsOn": ["US-001"], // Won't be selected until US-001 passes + "dependsOn": ["US-001"], ... } ``` -Ralph-tui will: -- Show US-002 as "blocked" until US-001 completes -- Never select US-002 for execution while US-001 is open -- Include "Prerequisites: US-001" in the prompt when working on US-002 - -**Correct dependency order:** -1. Schema/database changes (no dependencies) -2. Backend logic (depends on schema) -3. UI components (depends on backend) -4. Integration/polish (depends on UI) +**Correct dependency order:** Schema/database → backend → UI → integration. --- ## Acceptance Criteria: Quality Gates + Story-Specific -Each story's acceptance criteria should include: -1. **Story-specific criteria** from the PRD (what this story accomplishes) -2. **Quality gates** from the PRD's Quality Gates section (appended at the end) +Each story's acceptance criteria should include story-specific criteria from the PRD, plus quality gates appended from the Quality Gates section. -### Good criteria (verifiable): -- "Add `status` column to tasks table with default 'open'" -- "Filter dropdown has options: All, Open, Closed" -- "Clicking delete shows confirmation dialog" - -### Bad criteria (vague): -- ❌ "Works correctly" -- ❌ "User can do X easily" -- ❌ "Good UX" -- ❌ "Handles edge cases" +Criteria must be verifiable: "Add `status` column with default 'open'" is good. "Works correctly" or "Good UX" is bad. --- @@ -364,23 +335,13 @@ After creating prd.json: ralph-tui run --prd ./tasks/prd.json ``` -Ralph-tui will: -1. Load stories from prd.json -2. Select the highest-priority story with `passes: false` and no blocking dependencies -3. Generate a prompt with story details + acceptance criteria -4. Run the agent to implement the story -5. Mark `passes: true` on completion -6. Repeat until all stories pass - --- ## Checklist Before Saving -- [ ] Extracted Quality Gates from PRD (or asked user if missing) +- [ ] Extracted Quality Gates from PRD - [ ] Each story completable in one iteration - [ ] Stories ordered by dependency (schema → backend → UI) - [ ] `dependsOn` correctly set for each story - [ ] Quality gates appended to every story's acceptance criteria -- [ ] UI stories have browser verification (if specified in Quality Gates) -- [ ] Acceptance criteria are verifiable (not vague) - [ ] No circular dependencies diff --git a/skills/ralph-tui-prd/SKILL.md b/skills/ralph-tui-prd/SKILL.md index a23a04e9..00ca731e 100644 --- a/skills/ralph-tui-prd/SKILL.md +++ b/skills/ralph-tui-prd/SKILL.md @@ -41,12 +41,6 @@ Ask questions one set at a time. Each answer should inform your next questions. B. Increase user retention C. Reduce support burden D. Other: [please specify] - -2. Who is the target user? - A. New users only - B. Existing users only - C. All users - D. Admin users only ``` This lets users respond with "1A, 2C" for quick iteration. @@ -124,11 +118,7 @@ Each story should be small enough to implement in one focused AI agent session. **Note:** Do NOT include quality gate commands in individual story criteria - they are defined once in the Quality Gates section and applied automatically during conversion. -**Important:** -- Acceptance criteria must be verifiable, not vague -- "Works correctly" is bad -- "Button shows confirmation dialog before deleting" is good -- Each story should be independently completable +Acceptance criteria must be verifiable: "Button shows confirmation dialog before deleting" is good. "Works correctly" is bad. ### 5. Functional Requirements Numbered list of specific functionalities: @@ -318,10 +308,7 @@ Before outputting the PRD: - [ ] Asked clarifying questions with lettered options - [ ] Asked about quality gates (REQUIRED) -- [ ] Asked follow-up questions when needed - [ ] Quality Gates section included with project-specific commands - [ ] User stories are small and independently completable -- [ ] User stories do NOT include quality gate commands (they're in the Quality Gates section) -- [ ] Functional requirements are numbered and unambiguous -- [ ] Non-goals section defines clear boundaries +- [ ] User stories do NOT include quality gate commands - [ ] PRD is wrapped in `[PRD]...[/PRD]` markers