fete/.ralph/speckit-migration/instructions.md

# Ralph Loop — Migrate project artifacts to spec-kit format

Ralph migrates existing project documentation from `spec/`, `docs/agents/`, and `CLAUDE.md` into the spec-kit directory structure. Cross-cutting project knowledge goes to `.specify/memory/`. Feature-specific docs go to `specs/[feature-name]/` with `spec.md`, `research.md`, and `plan.md` files following the spec-kit templates.

Each iteration migrates exactly ONE file. No batching.

## CRITICAL RULE: One Task Per Iteration

You MUST perform exactly ONE task per iteration. Not two, not "a few small ones", not "all remaining items". ONE.

After completing your single task:
1. Append a short summary of what you did to `{{RUN_DIR}}/progress.txt`.
2. Stop. Do not look for more work. Do not "while I'm at it" anything.

The only exception: if the single task you perform reveals that the work is complete, you may additionally output `<promise>COMPLETE</promise>`.

## Startup: Read Project State

At the start of every iteration, read these files in order:

1. `{{RUN_DIR}}/progress.txt` — what previous iterations did (your memory across iterations).
2. `{{RUN_DIR}}/chief-wiggum.md` — notes from Chief Wiggum. Items under `## Action Required` have highest priority.
3. `{{RUN_DIR}}/answers.md` — check if the human answered any open questions.
4. `{{RUN_DIR}}/questions.md` — open and resolved questions.
5. `CLAUDE.md` — project statutes and principles.
6. `.specify/memory/constitution.md` — the project constitution (already migrated).
7. `.specify/templates/spec-template.md` — target format for feature specs.

Do NOT read all source files upfront. Only read the specific source file needed for the current task.

## Task Selection (Priority Order)

Pick the FIRST applicable task from this list. Do that ONE task, then stop.

### Priority 1: Chief Wiggum action items
If `{{RUN_DIR}}/chief-wiggum.md` has items under `## Action Required`, address the FIRST one that hasn't been addressed yet (check `{{RUN_DIR}}/progress.txt`). Do NOT modify `{{RUN_DIR}}/chief-wiggum.md`.

### Priority 2: Process answers
If `{{RUN_DIR}}/answers.md` contains an answer, process it. Remove the processed entry from `{{RUN_DIR}}/answers.md`.

### Priority 3: Execute next migration task
Check `{{RUN_DIR}}/progress.txt` to see which tasks are already done. Find the first task from the Migration Task List (below) that has NOT been logged as completed in progress.txt. Execute that one task, then stop.

### Priority 4: Update CLAUDE.md references
After all migration tasks are complete, update path references in `CLAUDE.md` to point to the new locations. Specifically:
- Change `spec/design-system.md` references to `.specify/memory/design-system.md`
- Change `spec/` references to `specs/` or `.specify/memory/` as appropriate
- Change `docs/agents/research/` and `docs/agents/plan/` references to `specs/[feature]/`
- Update the "Agent Documentation" section to reflect the new structure
- Do NOT change project statutes, build commands, or anything not related to file paths

### Priority 5: Cleanup
After CLAUDE.md is updated, delete the now-empty old directories and migrated files:
- Remove `Ideen.md` (migrated to `.specify/memory/ideen.md`)
- Remove `spec/` directory (all content has been migrated)
- Remove `docs/agents/` directory (all content has been migrated)
- Do NOT remove `docs/` itself if other content exists there

### Priority 6: Complete
If all migration tasks, CLAUDE.md update, and cleanup are done:
Output `<promise>COMPLETE</promise>` and stop.

---

## Migration Task List

Execute these in order, one per iteration. For each task, read the source file, transform it to the target format, and write the result.

### Phase A: Cross-cutting project docs to `.specify/memory/`

These files contain project-level knowledge that isn't specific to one feature. Copy them to `.specify/memory/` with minimal reformatting. Preserve all content — do not summarize or cut.

**A0** — `Ideen.md` -> `.specify/memory/ideen.md`
Copy as-is. This is the original brainstorming/founding document of the project (in German). Preserve completely.

**A1** — `spec/personas.md` -> `.specify/memory/personas.md`
Copy as-is. No format changes needed.

**A2** — `spec/design-system.md` -> `.specify/memory/design-system.md`
Copy as-is. No format changes needed.

**A3** — `spec/implementation-phases.md` -> `.specify/memory/implementation-phases.md`
Copy as-is. No format changes needed.

### Phase B: Cross-cutting research to `.specify/memory/research/`

These research docs cover topics that apply across multiple features. Move them with date prefix removed from filename.

**B1** — `docs/agents/research/2026-03-04-backpressure-agentic-coding.md` -> `.specify/memory/research/backpressure-agentic-coding.md`
Copy as-is.

**B2** — `docs/agents/research/2026-03-04-api-first-approach.md` -> `.specify/memory/research/api-first-approach.md`
Copy as-is.

**B3** — `docs/agents/research/2026-03-04-datetime-best-practices.md` -> `.specify/memory/research/datetime-best-practices.md`
Copy as-is.

**B4** — `docs/agents/research/2026-03-04-rfc9457-problem-details.md` -> `.specify/memory/research/rfc9457-problem-details.md`
Copy as-is.

**B5** — `docs/agents/research/2026-03-04-sans-serif-fonts.md` -> `.specify/memory/research/sans-serif-fonts.md`
Copy as-is.

**B6** — `docs/agents/research/2026-03-04-openapi-validation-pipeline.md` -> `.specify/memory/research/openapi-validation-pipeline.md`
Copy as-is.

**B7** — `docs/agents/research/2026-03-05-e2e-testing-playwright-vue3.md` -> `.specify/memory/research/e2e-testing-playwright.md`
Copy as-is.

### Phase C: Cross-cutting plans to `.specify/memory/plans/`

**C1** — `docs/agents/plan/2026-03-04-backpressure-agentic-coding.md` -> `.specify/memory/plans/backpressure-agentic-coding.md`
Copy as-is.

**C2** — `docs/agents/plan/2026-03-05-e2e-testing-playwright-setup.md` -> `.specify/memory/plans/e2e-testing-playwright-setup.md`
Copy as-is.

### Phase D: Setup tasks — extract specs + relocate research/plans

Each setup task from `spec/setup-tasks.md` becomes its own feature directory under `specs/`. Read the setup-tasks.md file, extract the section for the specific task, and reformat it into a `spec.md` following the spec-kit template structure. Then relocate the corresponding research and plan docs.

For the spec.md conversion: map the existing acceptance criteria to the spec-kit "User Scenarios & Testing" section as acceptance scenarios. Map the task description to "Requirements". Keep all checkmark states (completed criteria). Add a note at the top indicating this is a setup task (infrastructure), not a user-facing feature.

**D1** — Extract T-1 from `spec/setup-tasks.md` -> `specs/t-01-monorepo-setup/spec.md`
Read `spec/setup-tasks.md`, extract the T-1 section, reformat to spec-kit spec template.

**D2** — `docs/agents/research/2026-03-04-t1-monorepo-setup.md` -> `specs/t-01-monorepo-setup/research.md`
Copy as-is.

**D3** — `docs/agents/plan/2026-03-04-t1-monorepo-setup.md` -> `specs/t-01-monorepo-setup/plan.md`
Copy as-is.

**D4** — Extract T-2 from `spec/setup-tasks.md` -> `specs/t-02-docker-deployment/spec.md`

**D5** — `docs/agents/research/2026-03-04-spa-springboot-docker-patterns.md` -> `specs/t-02-docker-deployment/research.md`
Copy as-is.

**D6** — `docs/agents/plan/2026-03-04-t2-docker-deployment.md` -> `specs/t-02-docker-deployment/plan.md`
Copy as-is.

**D7** — Extract T-3 from `spec/setup-tasks.md` -> `specs/t-03-cicd-pipeline/spec.md`

**D8** — `docs/agents/research/2026-03-04-t3-cicd-pipeline.md` -> `specs/t-03-cicd-pipeline/research.md`
Copy as-is.

**D9** — `docs/agents/plan/2026-03-04-t3-cicd-pipeline.md` -> `specs/t-03-cicd-pipeline/plan.md`
Copy as-is.

**D10** — Extract T-4 from `spec/setup-tasks.md` -> `specs/t-04-dev-infrastructure/spec.md`

**D11** — `docs/agents/research/2026-03-04-t4-development-infrastructure.md` -> `specs/t-04-dev-infrastructure/research.md`
Copy as-is.

**D12** — `docs/agents/plan/2026-03-04-t4-development-infrastructure.md` -> `specs/t-04-dev-infrastructure/plan.md`
Copy as-is.

**D13** — Extract T-5 from `spec/setup-tasks.md` -> `specs/t-05-jpa-database/spec.md`
T-5 may not have research/plan docs yet. Only create the spec.md.

### Phase E: User stories — extract specs

Each user story from `spec/userstories.md` becomes its own feature directory. Read the userstories.md file, extract the section for the specific user story, and reformat it into a `spec.md` following the spec-kit template structure. Map acceptance criteria to acceptance scenarios. Map the story description to requirements. Preserve all checkmark states.

**E1** — Extract US-1 from `spec/userstories.md` -> `specs/us-01-create-event/spec.md`

**E2** — `docs/agents/research/2026-03-04-us1-create-event.md` -> `specs/us-01-create-event/research.md`
Copy as-is.

**E3** — `docs/agents/plan/2026-03-04-us1-create-event.md` -> `specs/us-01-create-event/plan.md`
Copy as-is.

**E4** — `docs/agents/plan/2026-03-05-us1-review-fixes.md` -> `specs/us-01-create-event/plan-review-fixes.md`
Copy as-is. This is a supplementary plan doc for US-1.

**E5** — `docs/agents/plan/2026-03-05-us1-post-review-fixes.md` -> `specs/us-01-create-event/plan-post-review-fixes.md`
Copy as-is. This is a supplementary plan doc for US-1.

**E6** — Extract US-2 from `spec/userstories.md` -> `specs/us-02-view-event/spec.md`

**E7** — Extract US-3 from `spec/userstories.md` -> `specs/us-03-rsvp/spec.md`

**E8** — Extract US-4 from `spec/userstories.md` -> `specs/us-04-guest-list/spec.md`

**E9** — Extract US-5 from `spec/userstories.md` -> `specs/us-05-edit-event/spec.md`

**E10** — Extract US-6 from `spec/userstories.md` -> `specs/us-06-calendar-export/spec.md`

**E11** — Extract US-7 from `spec/userstories.md` -> `specs/us-07-local-event-overview/spec.md`

**E12** — Extract US-8 from `spec/userstories.md` -> `specs/us-08-comments/spec.md`

**E13** — Extract US-9 from `spec/userstories.md` -> `specs/us-09-reminders/spec.md`

**E14** — Extract US-10a from `spec/userstories.md` -> `specs/us-10a-organizer-updates/spec.md`

**E15** — Extract US-10b from `spec/userstories.md` -> `specs/us-10b-guest-notifications/spec.md`

**E16** — Extract US-11 from `spec/userstories.md` -> `specs/us-11-qr-code/spec.md`

**E17** — Extract US-12 from `spec/userstories.md` -> `specs/us-12-recurring-events/spec.md`

**E18** — Extract US-13 from `spec/userstories.md` -> `specs/us-13-plus-one/spec.md`

**E19** — Extract US-14 from `spec/userstories.md` -> `specs/us-14-waitlist/spec.md`

**E20** — Extract US-15 from `spec/userstories.md` -> `specs/us-15-color-themes/spec.md`

**E21** — Extract US-16 from `spec/userstories.md` -> `specs/us-16-header-image/spec.md`

**E22** — Extract US-17 from `spec/userstories.md` -> `specs/us-17-dark-mode/spec.md`

**E23** — Extract US-18 from `spec/userstories.md` -> `specs/us-18-cancel-event/spec.md`

**E24** — Extract US-19 from `spec/userstories.md` -> `specs/us-19-delete-event/spec.md`

---

## Spec Conversion Guidelines

When converting a user story or setup task to a spec-kit `spec.md`, use this structure:

```markdown
# Feature Specification: [Title]

**Feature**: `[id-kebab-case]`
**Created**: 2026-03-06
**Status**: [Draft | Approved | Implemented]
**Source**: Migrated from spec/userstories.md (or spec/setup-tasks.md)

## User Scenarios & Testing

### User Story 1 - [Title] (Priority: P1)

[Story description from the original]

**Acceptance Scenarios**:

1. **Given** ..., **When** ..., **Then** ...
[Map each acceptance criterion to a Given/When/Then scenario]

### Edge Cases

[Extract from original if present, otherwise mark as [NEEDS EXPANSION]]

## Requirements

### Functional Requirements

[Map the story's requirements and acceptance criteria to FR-XXX items]

## Success Criteria

[Derive from acceptance criteria. Mark as [NEEDS EXPANSION] if not obvious]
```

For setup tasks that are already completed (all criteria checked off), set Status to `Implemented`.
For user stories not yet started, set Status to `Draft`.
For US-1 (in progress), set Status to `Approved`.

## File Ownership

Respect these boundaries strictly:

| File | Owner | You may... |
|------|-------|------------|
| `{{RUN_DIR}}/progress.txt` | Ralph | Read and append |
| `{{RUN_DIR}}/questions.md` | Ralph | Read and write |
| `{{RUN_DIR}}/answers.md` | Human | **Read only.** Only remove entries you have already processed. |
| `{{RUN_DIR}}/chief-wiggum.md` | Chief Wiggum | **Read only.** Never modify. |
| `CLAUDE.md` | Ralph (Priority 4 only) | Read always. Write ONLY during Priority 4 (update references). |
| `Ideen.md` | Source | **Read only.** Never modify original. |
| `spec/*` | Source | **Read only.** Never modify originals. |
| `docs/agents/**` | Source | **Read only.** Never modify originals. |
| `.specify/memory/**` | Ralph | Read and write (create new files). |
| `.specify/templates/**` | System | **Read only.** |
| `specs/**` | Ralph | Read and write (create new files). |

## Handling Uncertainty

If you encounter ambiguity (e.g. a user story doesn't map cleanly to the spec-kit template, or you're unsure where a cross-cutting research doc belongs), add a question to `{{RUN_DIR}}/questions.md` in this format:

```markdown
## Open

### Q[N]: [Short question]
**Context**: [What you were trying to do]
**Options**: [A] ... [B] ...
```

Then skip that task and move to the next one. Come back to skipped tasks after the question is answered.

## Rules

- NEVER delete or modify source files (`spec/`, `docs/agents/`). Only create new files. Cleanup happens in Priority 5 after everything is verified.
- NEVER invent content. If the original doesn't have enough detail for a section, mark it `[NEEDS EXPANSION]`.
- ALWAYS preserve acceptance criteria checkmark states (`- [x]` vs `- [ ]`).
- Keep file content in English (project statute).
- Do not add emojis.