Skip to content

Commit eface71

Browse files
ryaneggzryaneggz
committed
Lets go try this
1 parent e7b2c82 commit eface71

7 files changed

Lines changed: 251 additions & 4 deletions

File tree

‎.claude/commands/ralph/ticket.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ SUBAGENTS: $ARGUMENTS.subagents (default: 3)
149149

150150
11. _LAUNCH_ Ralph autonomous implementation loop:
151151
- _REPORT_ "Starting Ralph autonomous loop for <N> user stories..."
152-
- RUN `cd ./.worktrees/<prefix>-<number> && bash ../../.ralph/ralph.sh` to execute Ralph
152+
- RUN `cd ./.worktrees/<prefix>-<number> && bash ../../.ralph/ralph.sh 200` to execute Ralph
153153
- Ralph will:
154154
- Read `.ralph/prd.json` for user stories (resolved via SCRIPT_DIR at repo root)
155155
- Pick highest priority story with `passes: false`
@@ -164,7 +164,13 @@ SUBAGENTS: $ARGUMENTS.subagents (default: 3)
164164
- Exit 0: All stories completed
165165
- Exit 1: Max iterations reached (partial completion)
166166

167-
12. _REPORT_ workflow completion:
167+
12. _PUSH_ changes to remote branch:
168+
- _REGARDLESS_ of Ralph exit status (COMPLETE or PARTIAL), push all committed work to remote
169+
- RUN `cd ./.worktrees/<prefix>-<number> && git push -u origin <branch-name>` to push branch to remote
170+
- _IF_ push fails: _REPORT_ error and provide manual push command
171+
- _REPORT_ "Pushed <branch-name> to origin"
172+
173+
13. _REPORT_ workflow completion:
168174
- Issue processed: #<number> - <title>
169175
- Worktree location: `./.worktrees/<prefix>-<number>`
170176
- Spec folder: `.claude/specs/<prefix>-<number>-<short-name>/`
@@ -179,7 +185,7 @@ SUBAGENTS: $ARGUMENTS.subagents (default: 3)
179185
- Ralph progress: `.ralph/progress.txt`
180186
- Ralph status: <COMPLETE | PARTIAL>
181187
- _IF_ COMPLETE:
182-
- Next steps: Push branch and create PR: `cd ./.worktrees/<prefix>-<number> && git push -u origin <branch-name> && gh pr create --base development --title "<issue-title>"`
188+
- Next steps: Create PR: `cd ./.worktrees/<prefix>-<number> && gh pr create --base development --title "<issue-title>"`
183189
- _IF_ PARTIAL:
184190
- Stories completed: <N> of <M>
185191
- Next steps: Review `.ralph/progress.txt`, fix blockers, resume with `cd ./.worktrees/<prefix>-<number> && bash ../../.ralph/ralph.sh`
@@ -195,6 +201,7 @@ SUBAGENTS: $ARGUMENTS.subagents (default: 3)
195201
- **branchName mismatch**: _REPORT_ "prd.json branchName does not match worktree branch. Update .ralph/prd.json branchName to match <branch-name>."
196202
- **Ralph loop failure**: _REPORT_ "Ralph encountered an error. Check .ralph/progress.txt for status. Resume with `bash ../../.ralph/ralph.sh`"
197203
- **Ralph partial completion**: _REPORT_ "Ralph completed <N> of <M> stories. Resume with `bash ../../.ralph/ralph.sh` or complete remaining stories manually."
204+
- **Push failure**: _REPORT_ "Failed to push branch. Try manually: `cd ./.worktrees/<prefix>-<number> && git push -u origin <branch-name>`"
198205

199206
## Example Invocations
200207

@@ -217,4 +224,5 @@ Confirm workflow completion with:
217224
- PRD generated: `tasks/prd-<feature-slug>.md`
218225
- Ralph config: `.ralph/prd.json` with <N> user stories
219226
- Ralph execution status: COMPLETE or PARTIAL (<N> of <M> stories)
220-
- Next steps: Push branch and create PR (if COMPLETE), or resume Ralph (if PARTIAL)
227+
- Branch pushed to remote
228+
- Next steps: Create PR (if COMPLETE), or resume Ralph (if PARTIAL)

‎.specs/ticket-ralph-loop-integration/PROPOSAL_DEVEX_GUARDIAN.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Proposal: DEVEX_GUARDIAN
2+
3+
See council review for synthesized approach. Key contributions:
4+
- Comprehensive error handling for all new failure modes
5+
- Detailed report format with COMPLETE/PARTIAL/FAILED states
6+
- branchName analysis: worktree branch works without ralph/ prefix
7+
- Recommended removing PR creation from automated flow (user handles it)

‎.specs/ticket-ralph-loop-integration/PROPOSAL_HANDOFF_ARCHITECT.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Proposal: HANDOFF_ARCHITECT
2+
3+
See council review for synthesized approach. Key contributions:
4+
- Detailed data flow analysis: REVIEW.md → PRD → prd.json mapping
5+
- Story sizing rules for Ralph compatibility (1-3 files per story, split by layer)
6+
- Identified concurrent execution constraint (one Ralph run at a time)
7+
- Recommended explicit sizing instructions in PRD generation prompt

‎.specs/ticket-ralph-loop-integration/PROPOSAL_WORKFLOW_ORCHESTRATOR.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Proposal: WORKFLOW_ORCHESTRATOR
2+
3+
See council review for synthesized approach. Key contributions:
4+
- Identified ralph.sh SCRIPT_DIR path resolution (prd.json lives at repo root, not worktree)
5+
- Proposed symlink approach (rejected by council — not needed since ralph.sh handles paths correctly)
6+
- Recommended letting /team run fully and ignoring P4-5 (council chose explicit P0-3 instruction instead)
7+
- Detailed PR body adaptation for Ralph's iterative commits

‎.specs/ticket-ralph-loop-integration/REVIEW.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Council Review: ticket.md Ralph Loop Integration
2+
3+
## Feature Under Review
4+
5+
Modify `.claude/commands/ralph/ticket.md` to initiate the Ralph autonomous loop after AI council produces REVIEW.md, TASKS.md, and USER_STORIES.md, instead of executing direct implementation (Phases 4-5).
6+
7+
## Proposal Comparison Matrix
8+
9+
| Aspect | WORKFLOW_ORCHESTRATOR | HANDOFF_ARCHITECT | DEVEX_GUARDIAN | Council Verdict |
10+
|--------|----------------------|-------------------|----------------|-----------------|
11+
| Architecture | Let /team run fully, ignore P4-5 | Manual phases or modify /team | Manual phases or modify /team | Rewrite ticket.md instructions for P0-3 only |
12+
| branchName | Use worktree branch, pass to ralph skill | Use worktree branch, validate | Use worktree branch, auto-fix mismatch | Use worktree branch, validate before launch |
13+
| Ralph path | Symlink .ralph into worktree | Keep at repo root | Run from worktree with ../../ path | Keep at repo root (ralph.sh uses SCRIPT_DIR) |
14+
| PR creation | Keep, adapt to Ralph commits | Keep as Step 13 | Remove, report only | Remove PR creation, Ralph + user handles it |
15+
| Error handling | Basic exit code check | Medium detail | Comprehensive | Comprehensive per DEVEX_GUARDIAN |
16+
17+
## Consensus Points
18+
19+
1. **Steps 1-7 unchanged** — issue extraction, worktree, user stories all stay
20+
2. **Step 8 becomes council-only** — Phases 0-3, no implementation
21+
3. **New bridging steps** — PRD generation, prd.json conversion, ralph.sh launch
22+
4. **branchName = worktree branch** — no `ralph/` prefix needed
23+
5. **Ralph handles implementation** — iterative commits, quality checks per story
24+
6. **PR creation deferred** — not part of this automated flow (Ralph doesn't create PRs)
25+
26+
## Divergence Resolution
27+
28+
### Q1: How to limit /team to Phases 0-3?
29+
30+
**Decision:** Rewrite ticket.md Step 8 instructions to explicitly say "execute Phases 0-3 only." The `/team` command is a markdown instruction file — the executing agent reads and follows it. We instruct it to stop after Phase 3. No code changes to team.md needed.
31+
32+
### Q2: Where does prd.json live?
33+
34+
**Decision:** At repo root `.ralph/prd.json`. ralph.sh uses `SCRIPT_DIR` to resolve paths, so prd.json is always at `.ralph/prd.json` regardless of working directory. The worktree is just where git operations happen. No symlinks needed.
35+
36+
### Q3: Should ticket.md create the PR?
37+
38+
**Decision:** Remove PR creation from ticket.md. Ralph commits iteratively but doesn't push or create PRs. After Ralph completes, the user reviews and creates the PR manually (or runs a separate command). This keeps ticket.md focused on the automation pipeline.
39+
40+
### Q4: Story sizing from council output?
41+
42+
**Decision:** The PRD generation step must include explicit sizing instructions. Council TASKS.md may produce tasks that are too large for one Ralph iteration. The PRD command must instruct splitting large tasks.
43+
44+
## Unified Implementation Plan
45+
46+
### Modified ticket.md Structure
47+
48+
```
49+
Steps 1-7: [UNCHANGED] Issue → worktree → user stories → team query
50+
Step 8: [MODIFIED] Invoke /team Phases 0-3 only → REVIEW.md, TASKS.md, PROPOSAL_*.md
51+
Step 9: [NEW] Generate PRD from council outputs → tasks/prd-<feature>.md
52+
Step 10: [NEW] Convert PRD to .ralph/prd.json (branchName = worktree branch)
53+
Step 11: [NEW] Launch ralph.sh as subagent
54+
Step 12: [MODIFIED] Report completion status (no PR creation)
55+
```
56+
57+
### Critical Requirements
58+
59+
1. Step 9 query must include: "Archive previous prd.json & progress.txt THEN load the prd skill and create a PRD for [feature]"
60+
2. Step 10 query must include: "Load the ralph skill and convert tasks/prd-[feature].md to .ralph/prd.json"
61+
3. Step 10 must override branchName to match worktree branch
62+
4. Step 11 runs `bash .ralph/ralph.sh` from worktree directory
63+
5. Error handling at each step with clear recovery instructions
64+
65+
## Risk Consolidation
66+
67+
| Risk | Severity | Mitigation |
68+
|------|----------|------------|
69+
| ralph.sh path resolution | LOW | Uses SCRIPT_DIR, works correctly from any cwd |
70+
| branchName mismatch | MEDIUM | Validate after prd.json generation |
71+
| Story sizing | MEDIUM | Explicit sizing rules in PRD generation prompt |
72+
| Ralph incomplete | MEDIUM | Report partial completion, provide resume command |
73+
| Council output incomplete | LOW | Verify artifacts exist before proceeding |
74+
75+
## Final Verdict
76+
77+
**GO** — No modifications needed to existing systems (/team, ralph.sh, skills). Only ticket.md needs rewriting. Low risk, clear rollback path (revert ticket.md).
78+
79+
**Confidence Level:** High

‎.specs/ticket-ralph-loop-integration/TASKS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Implementation Tasks: ticket.md Ralph Loop Integration
2+
3+
## Core Implementation
4+
5+
- [ ] Task 1: Rewrite ticket.md Steps 8-11 to replace /team Phases 4-5 with Ralph loop
6+
- Files: `.claude/commands/ralph/ticket.md`
7+
- Changes:
8+
- Step 8: Constrain to Phases 0-3 only (council analysis, no implementation)
9+
- Step 9: NEW - Generate PRD from council outputs using prd skill
10+
- Step 10: NEW - Convert PRD to .ralph/prd.json using ralph skill, override branchName
11+
- Step 11: NEW - Launch `bash .ralph/ralph.sh` as subagent
12+
- Step 12: MODIFIED - Report workflow status (remove PR creation)
13+
- Acceptance: ticket.md contains steps 1-12 with Ralph loop integration
14+
15+
- [ ] Task 2: Update error handling section to cover new failure modes
16+
- Files: `.claude/commands/ralph/ticket.md`
17+
- Changes: Add error cases for PRD generation failure, prd.json conversion failure, Ralph loop failure/partial completion
18+
- Acceptance: Error handling section covers all new steps
19+
20+
- [ ] Task 3: Update report section and example invocations
21+
- Files: `.claude/commands/ralph/ticket.md`
22+
- Changes: Report reflects Ralph loop output instead of direct implementation. Examples unchanged.
23+
- Acceptance: Report section lists Ralph-specific artifacts
24+
25+
## Verification
26+
27+
- [ ] Task 4: Review final ticket.md for completeness and consistency
28+
- Acceptance: All step numbers are sequential, all variable references are consistent, error handling covers all steps

‎tasks/prd-ticket-ralph-loop.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# PRD: ticket.md Ralph Loop Integration
2+
3+
## Introduction
4+
5+
Modify `.claude/commands/ralph/ticket.md` so that after the AI council produces its planning artifacts (REVIEW.md, TASKS.md, USER_STORIES.md via Phases 0-3 of `/team`), the workflow generates a PRD, converts it to `.ralph/prd.json`, and launches the Ralph autonomous loop for iterative implementation — replacing the current direct implementation approach (Phases 4-5).
6+
7+
## Goals
8+
9+
- Replace direct implementation (team Phases 4-5) with Ralph autonomous loop
10+
- Bridge council outputs to Ralph's prd.json format
11+
- Ensure branchName in prd.json matches the worktree branch (no `ralph/` prefix)
12+
- Provide clear error handling and reporting for the new workflow steps
13+
- Maintain all existing Steps 1-7 (issue extraction, worktree, user stories)
14+
15+
## User Stories
16+
17+
### US-001: Rewrite Step 8 to constrain /team to Phases 0-3 only
18+
**Description:** As a developer running `/ticket`, I want the team workflow to stop after council analysis so that implementation is handled by Ralph instead.
19+
20+
**Acceptance Criteria:**
21+
- [ ] Step 8 in ticket.md explicitly instructs to execute only Phases 0-3 of /team
22+
- [ ] Step 8 includes verification that REVIEW.md and TASKS.md exist before proceeding
23+
- [ ] Phase 4 (implementation) and Phase 5 (validation) are NOT referenced as expected outputs
24+
- [ ] Typecheck passes
25+
26+
### US-002: Add Step 9 — Generate PRD from council outputs
27+
**Description:** As a developer running `/ticket`, I want a PRD generated from the council's REVIEW.md, TASKS.md, and USER_STORIES.md so that Ralph has a structured input.
28+
29+
**Acceptance Criteria:**
30+
- [ ] Step 9 reads council artifacts from the spec folder
31+
- [ ] Step 9 composes a PRD generation query that includes council context and Ralph sizing rules
32+
- [ ] Step 9 saves PRD to `tasks/prd-<feature-slug>.md`
33+
- [ ] Step 9 verifies the PRD file was created
34+
- [ ] Typecheck passes
35+
36+
### US-003: Add Step 10 — Convert PRD to .ralph/prd.json
37+
**Description:** As a developer running `/ticket`, I want the PRD converted to Ralph's JSON format with the correct branch name so Ralph can execute.
38+
39+
**Acceptance Criteria:**
40+
- [ ] Step 10 invokes the ralph skill to convert the PRD to `.ralph/prd.json`
41+
- [ ] Step 10 explicitly instructs setting branchName to the worktree branch (not `ralph/` prefix)
42+
- [ ] Step 10 validates that prd.json branchName matches the worktree branch
43+
- [ ] Step 10 handles mismatch by fixing branchName before proceeding
44+
- [ ] Typecheck passes
45+
46+
### US-004: Add Step 11 — Launch Ralph autonomous loop
47+
**Description:** As a developer running `/ticket`, I want Ralph launched automatically so implementation proceeds without manual intervention.
48+
49+
**Acceptance Criteria:**
50+
- [ ] Step 11 runs `bash ../../.ralph/ralph.sh` from the worktree directory
51+
- [ ] Step 11 monitors for Ralph's completion signal (`<promise>COMPLETE</promise>`)
52+
- [ ] Step 11 captures exit status (0 = complete, 1 = partial)
53+
- [ ] Step 11 reports Ralph execution status
54+
- [ ] Typecheck passes
55+
56+
### US-005: Update Step 12 — Report workflow completion with Ralph status
57+
**Description:** As a developer running `/ticket`, I want a clear report showing council artifacts, Ralph status, and next steps.
58+
59+
**Acceptance Criteria:**
60+
- [ ] Step 12 lists all council artifacts (USER_STORIES.md, PROPOSAL_*.md, REVIEW.md, TASKS.md)
61+
- [ ] Step 12 lists Ralph artifacts (prd.json, progress.txt)
62+
- [ ] Step 12 reports COMPLETE or PARTIAL status with story counts
63+
- [ ] Step 12 provides next steps (push + PR if complete, resume if partial)
64+
- [ ] Old PR creation steps are removed (user handles PR manually)
65+
- [ ] Typecheck passes
66+
67+
### US-006: Update error handling section for new failure modes
68+
**Description:** As a developer running `/ticket`, I want clear error messages and recovery steps when any new step fails.
69+
70+
**Acceptance Criteria:**
71+
- [ ] Error handling covers: council incomplete, PRD generation failure, prd.json conversion failure, branchName mismatch, Ralph loop failure, Ralph partial completion
72+
- [ ] Each error case provides a specific recovery command or instruction
73+
- [ ] Typecheck passes
74+
75+
## Functional Requirements
76+
77+
- FR-1: ticket.md Steps 1-7 remain unchanged
78+
- FR-2: Step 8 must explicitly stop after Phase 3 (no implementation or validation phases)
79+
- FR-3: Step 9 must archive previous prd.json/progress.txt before generating new PRD
80+
- FR-4: Step 9 must include Ralph story sizing rules (1-3 files per story, split by layer)
81+
- FR-5: Step 10 must set prd.json branchName to match the worktree branch exactly
82+
- FR-6: Step 11 must run ralph.sh from the worktree directory using `../../.ralph/ralph.sh` path
83+
- FR-7: Step 12 must NOT include automatic PR creation (deferred to user)
84+
- FR-8: Error handling must cover all 6 new failure modes with recovery instructions
85+
86+
## Non-Goals
87+
88+
- No modifications to `/team` command (team.md unchanged)
89+
- No modifications to `ralph.sh` or `prompt.md`
90+
- No modifications to the prd or ralph skills
91+
- No automatic PR creation after Ralph completes
92+
- No concurrent Ralph execution support (one ticket at a time)
93+
94+
## Technical Considerations
95+
96+
- ralph.sh resolves paths relative to SCRIPT_DIR (`.ralph/` at repo root), so prd.json always lives at `.ralph/prd.json` regardless of working directory
97+
- The worktree branch (e.g., `feat/707-ticket-md-ralph-loop`) does NOT use `ralph/` prefix, but ralph.sh's archival logic handles this gracefully
98+
- Ralph auto-archives previous runs when branchName changes (ralph.sh lines 14-37)
99+
- Only one Ralph run can execute at a time (shared `.ralph/prd.json` state)
100+
101+
## Success Metrics
102+
103+
- `/ticket` command successfully bridges from council analysis to Ralph loop without manual intervention
104+
- Ralph executes at least one user story autonomously from council-derived prd.json
105+
- Error states produce actionable recovery instructions
106+
- Workflow completion report accurately reflects Ralph's execution status
107+
108+
## Open Questions
109+
110+
- Should max iterations for ralph.sh be configurable via ticket.md arguments?
111+
- Should ticket.md support a `--no-ralph` flag to fall back to direct implementation?

0 commit comments

Comments
 (0)