amhuppert/sdd-to-ralph

SDD to Ralph Bridge

Convert completed CCSDD (cc-sdd) spec artifacts into Ralph execution artifacts for autonomous implementation.

• Input: .kiro/specs/<feature>/ — requirements.md, design.md, tasks.md
• Output: .ralph/PROMPT.md, .ralph/fix_plan.md, updated .ralphrc, .ralph/specs/

Prerequisites

Verify both systems are installed before proceeding:

1. Ralph enabled: .ralph/ directory and .ralphrc file exist
   • If missing: instruct user to run ralph-enable
2. CCSDD installed: .kiro/ directory exists with at least one spec
   • If missing: instruct user to run npx cc-sdd@latest --claude

If either prerequisite fails, stop and report the issue.

Step 1: Detect and Select Feature Spec

Glob for .kiro/specs/*/spec.json to find available specs.

If 0 specs found:

• Error: "No CCSDD specs found in .kiro/specs/"
• Instruct: "Run /kiro:spec-init <description> to create a feature spec first"
• Stop

If 1 spec found:

• Read spec.json, extract feature_name
• Confirm: "Found spec: <feature_name>. Proceeding."

If multiple specs found:

• Read each spec.json to get feature names and phases
• Use AskUserQuestion to present the list with phase status:
  • Header: "Feature"
  • Question: "Which CCSDD spec should be bridged to Ralph?"
  • Options: list each feature with its current phase (e.g., "auth-system (tasks-generated)")

Step 2: Validate Spec Completeness

Read the selected .kiro/specs/<feature>/spec.json and check:

1. approvals.requirements.generated is true
2. approvals.design.generated is true
3. approvals.tasks.generated is true

If all phases complete: proceed to Step 3.

If incomplete phases detected:

• List missing phases with suggested commands:
  • Requirements missing → /kiro:spec-requirements <feature>
  • Design missing → /kiro:spec-design <feature>
  • Tasks missing → /kiro:spec-tasks <feature>
• Use AskUserQuestion:
  • Header: "Incomplete"
  • Question: "Spec has incomplete phases. Proceed anyway?"
  • Options: "Proceed" (continue with available artifacts), "Stop" (exit to complete phases)

Step 3: Read CCSDD Artifacts

Read all available artifacts from .kiro/specs/<feature>/:

1. requirements.md — EARS-format requirements
2. design.md — technical design
3. tasks.md — implementation tasks with parallel markers

Read steering docs if they exist (for additional project context):

1. .kiro/steering/product.md — project vision
2. .kiro/steering/tech.md — technology stack
3. .kiro/steering/structure.md — directory conventions

Read Ralph configuration:

1. .ralphrc — current settings

If a file doesn't exist, note it and proceed with what's available. At minimum, tasks.md must exist (it provides the fix_plan content).

<critical> If `tasks.md` does not exist or is empty, stop and report: "Cannot generate fix_plan.md without tasks. Run `/kiro:spec-tasks <feature>` first." </critical>

Step 4: Generate PROMPT.md

Create .ralph/PROMPT.md with two parts.

Part 1: Project-Specific Content

Synthesize from the CCSDD artifacts read in Step 3:

# Ralph Development Instructions

## Context

[2-3 sentences from design.md overview/summary section describing what is being built]

You are Ralph, building [brief description].

## Technology Stack

[Extract from design.md "Technology Stack" section or .kiro/steering/tech.md]
[Include version numbers when available]

- [Language] [version]
- [Framework] [version]
- [Library] [version] - [purpose]

## Key Principles

[Extract top 5 design decisions/principles from design.md]

- [Principle 1]
- [Principle 2]

## Current Objectives

[Extract high-level requirement titles from requirements.md — NOT full EARS criteria]

1. [Requirement group title] - [brief description]
2. [Requirement group title] - [brief description]

## Requirements Summary

[Numbered list with brief descriptions — point to full specs for detail]

1. [Requirement name] ([N] acceptance criteria)
   - [Key criteria summary]
2. [Requirement name] ([N] acceptance criteria)
   - [Key criteria summary]

Full EARS-format requirements: `.ralph/specs/requirements.md`

## Design Reference

[Key architecture decisions from design.md, ~500 words max]
[Include architecture diagram if present (Mermaid syntax)]

Full technical design: `.ralph/specs/design.md`

## Quality Standards

[Extract testing/quality requirements from design.md or requirements.md]

- [Standard 1]
- [Standard 2]

<guidelines type="prompt-context"> - Summarize, don't dump — Ralph reads PROMPT.md every loop, so it must be concise - Full specs are in `.ralph/specs/` for reference when Ralph needs detail - Include version numbers for all technologies - Make principles actionable — things Claude can verify - Keep Requirements Summary to titles and key criteria only - Design Reference should focus on architecture decisions that affect implementation </guidelines>

Part 2: Ralph Operational Instructions

Read references/ralph-operational-instructions.md and append the content block (everything inside the ```markdown fence, lines 8-139) to the end of the generated PROMPT.md.

<critical> The operational instructions section is MANDATORY. Without it: - Claude won't output the RALPH_STATUS block that Ralph parses for exit signals - Claude won't know when to set EXIT_SIGNAL: true vs false - Ralph will either never exit or exit prematurely - The circuit breaker and response analyzer depend on structured status output </critical>

Write the complete PROMPT.md to .ralph/PROMPT.md.

Step 5: Generate fix_plan.md

Convert CCSDD's tasks.md into Ralph's fix_plan.md using /kiro:spec-impl commands.

Conversion Algorithm

1. Parse tasks.md — extract all checkbox items (- [ ] or - [x])
2. Identify leaf tasks — tasks with no sub-tasks (e.g., 1.1, 1.2, 2.3). Skip parent-only tasks (e.g., 1. if it has 1.1, 1.2 children)
3. Extract task IDs — the numeric prefix of each leaf task (e.g., 1.1, 2.3)
4. Generate spec-impl commands — one per leaf task, in order
5. Add closing task — /kiro:validate-impl as final item
6. Add standard sections: Completed, Discovered

Output Format

# Fix Plan - <feature-name>

## Tasks

- [ ] /kiro:spec-impl <feature-name> 1.1
- [ ] /kiro:spec-impl <feature-name> 1.2
- [ ] /kiro:spec-impl <feature-name> 1.3
- [ ] /kiro:spec-impl <feature-name> 2.1
- [ ] /kiro:spec-impl <feature-name> 2.2
- [ ] /kiro:validate-impl <feature-name>

## Completed

## Discovered

<!-- Ralph will add discovered tasks here -->

<guidelines type="fix-plan"> - Only include leaf tasks — parent tasks are organizational groupings, not implementable units - Preserve the task ordering from tasks.md (respects dependency structure via P0/P1/P2 ordering) - The /kiro:validate-impl task is always last — it closes the spec→implementation→validation loop </guidelines>

Write the complete fix_plan.md to .ralph/fix_plan.md.

Step 6: Update .ralphrc

Read .ralphrc and update project-specific fields. Preserve all other settings.

Update PROJECT_NAME:

• Set to feature_name from spec.json

Detect and update PROJECT_TYPE:

• Scan design.md tech stack for keywords:
  • "TypeScript", "Node.js", "npm", "React", "Next.js" → typescript
  • "Python", "FastAPI", "Django", "Flask" → python
  • "Rust", "Cargo" → rust
  • "Go", "golang" → go
  • No match → leave as current value

Update ALLOWED_TOOLS based on PROJECT_TYPE:

| Project Type | Add to ALLOWED_TOOLS | | ------------ | ---------------------------------------------- | | typescript | Bash(npm *),Bash(npx *) | | python | Bash(pip *),Bash(python *),Bash(pytest) | | rust | Bash(cargo *) | | go | Bash(go *) | | All types | Write,Read,Edit,Bash(git *) (always include) |

Do NOT modify: MAX_CALLS_PER_HOUR, CLAUDE_TIMEOUT_MINUTES, SESSION_CONTINUITY, SESSION_EXPIRY_HOURS, circuit breaker thresholds, or any other existing settings.

Write updated .ralphrc.

Step 7: Copy Spec Files to Ralph

Create .ralph/specs/ directory if it doesn't exist. Copy CCSDD spec files so Ralph can reference them during implementation:

1. .kiro/specs/<feature>/requirements.md → .ralph/specs/requirements.md
2. .kiro/specs/<feature>/design.md → .ralph/specs/design.md
3. .kiro/specs/<feature>/research.md → .ralph/specs/research.md (if exists)

Step 8: Verify Generated Files

Read back generated files and verify:

PROMPT.md checks

1. Contains ---RALPH_STATUS--- (exact string)
2. Contains EXIT_SIGNAL examples
3. Contains project-specific context sections (Context, Technology Stack, Current Objectives)
4. Is at least 100 lines (both parts present)

fix_plan.md checks

1. Has ## Tasks section
2. Has at least one - [ ] /kiro:spec-impl item
3. Has ## Completed section
4. Has ## Discovered section
5. Contains /kiro:validate-impl as final task item

If any check fails: report the specific failure but do NOT delete files. Suggest re-running or manual fix.

Step 9: Present Summary

Display results to the user:

Successfully bridged CCSDD spec to Ralph!

Feature: <feature-name>

Tasks: N spec-impl commands + validation
  /kiro:spec-impl <feature-name> 1.1
  /kiro:spec-impl <feature-name> 1.2
  ...
  /kiro:validate-impl <feature-name>

Files Generated:
  .ralph/PROMPT.md
  .ralph/fix_plan.md
  .ralph/specs/requirements.md
  .ralph/specs/design.md

Configuration Updated:
  .ralphrc PROJECT_NAME = "<feature-name>"
  .ralphrc PROJECT_TYPE = "<type>"

[Any warnings about incomplete phases, etc.]

Next Steps:
  1. Review .ralph/PROMPT.md and .ralph/fix_plan.md
  2. Run: ralph --monitor

Error Handling

No .ralph/ directory:

• "Ralph is not enabled. Run ralph-enable first."

No .kiro/ directory:

• "CCSDD is not installed. Run npx cc-sdd@latest --claude first."

Empty or missing tasks.md:

• "No tasks found. Run /kiro:spec-tasks <feature> to generate tasks."

Missing steering docs:

• Warning only. Extract context from design.md alone.

Tasks without parallel markers:

• Infer from parent or position. Log in Notes section.

Corrupted spec.json:

• Show parse error. Suggest manual inspection.