ralphflow 0.2.0 → 0.4.0

package/src/templates/code-implementation/loops/00-story-loop/prompt.md

@@ -1,18 +1,30 @@
 # Story Loop — Break Stories into Structured Tasks
 
-Read `.ralph-flow/00-story-loop/tracker.md` FIRST to determine where you are.
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/00-story-loop/tracker.md` FIRST to determine where you are.
 
 > **Describe the destination, not the route.** Focus on what the user will experience, not how you'll build it. Surface anything that could go wrong — broken flows, overlooked edge cases, data at risk.
 
-> **READ-ONLY FOR SOURCE CODE.** Only write to: `01-tasks-loop/tasks.md`, `01-tasks-loop/tracker.md`, `00-story-loop/tracker.md`, `00-story-loop/stories.md`.
+> **READ-ONLY FOR SOURCE CODE.** Only write to: `.ralph-flow/{{APP_NAME}}/01-tasks-loop/tasks.md`, `.ralph-flow/{{APP_NAME}}/01-tasks-loop/tracker.md`, `.ralph-flow/{{APP_NAME}}/00-story-loop/tracker.md`, `.ralph-flow/{{APP_NAME}}/00-story-loop/stories.md`.
 
 **Pipeline:** `stories.md → YOU → tasks.md → 01-tasks-loop → code`
 
 ---
 
+## State Machine (3 stages per story)
+
+**FIRST — Check completion.** Read the tracker. If the Stories Queue has entries
+AND every entry is `[x]`, write `<promise>ALL STORIES PROCESSED</promise>` to
+the bottom of the tracker and `kill -INT $PPID`. Do NOT collect new stories.
+
+Pick the lowest-numbered `ready` story. NEVER process a `blocked` story.
+
+---
+
 ## No Stories? Collect Them
 
-If `stories.md` has no unprocessed stories and the tracker queue is empty/all done:
+If `stories.md` has no stories at all (first run, empty queue with no entries):
 1. Tell the user: *"No stories queued. Tell me what you want to build — describe features, problems, or goals in your own words."*
 2. Use `AskUserQuestion` to prompt: "What do you want to build or fix next?" (open-ended)
 3. As the user narrates, capture each distinct idea as a `## STORY-{N}: {Title}` in `stories.md` with description and `**Depends on:** None` (or dependencies if mentioned)
@@ -21,10 +33,6 @@ If `stories.md` has no unprocessed stories and the tracker queue is empty/all do
 
 ---
 
-## State Machine (3 stages per story)
-
-Pick the lowest-numbered `ready` story. NEVER process a `blocked` story. If none are `ready`: `<promise>ALL STORIES PROCESSED</promise>`.
-
 ```
 ANALYZE   → Read story, explore codebase, map scope → stage: clarify
 CLARIFY   → Ask user up to 20 questions (5 at a time) → stage: decompose
@@ -63,11 +71,11 @@ If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` he
 5. **Sanity-check:** Do NOT embed specific file paths in tasks — describe *what* changes, not *where*. The tasks loop will explore the codebase itself.
 6. Append to `01-tasks-loop/tasks.md` (format below)
 7. **Update `01-tasks-loop/tracker.md` (with lock protocol):**
-   1. Acquire `.ralph-flow/01-tasks-loop/.tracker-lock`:
+   1. Acquire `.ralph-flow/{{APP_NAME}}/01-tasks-loop/.tracker-lock`:
       - Exists + < 60s old → sleep 2s, retry up to 5 times
       - Exists + ≥ 60s old → stale, delete it
       - Not exists → continue
-      - Write lock: `echo "story-loop $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/01-tasks-loop/.tracker-lock`
+      - Write lock: `echo "story-loop $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/{{APP_NAME}}/01-tasks-loop/.tracker-lock`
       - Sleep 500ms, re-read lock, verify `story-loop` is in it
    2. Add new Task Groups to `## Task Groups`
    3. Add new tasks to `## Tasks Queue` with multi-agent metadata:
@@ -78,7 +86,7 @@ If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` he
    4. Add dependency entries to `## Dependencies` section (for tasks with dependencies only):
       - Example: `- TASK-15: [TASK-12]`
       - Tasks with `Depends on: None` are NOT added to Dependencies
-   5. Release lock: `rm .ralph-flow/01-tasks-loop/.tracker-lock`
+   5. Release lock: `rm .ralph-flow/{{APP_NAME}}/01-tasks-loop/.tracker-lock`
 8. Mark done in tracker: check off queue, completed mapping, `active_story: none`, `stage: analyze`, update Dependency Graph, log
 9. Exit: `kill -INT $PPID`
 
@@ -132,4 +140,4 @@ If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` he
 
 ---
 
-Read `.ralph-flow/00-story-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/00-story-loop/tracker.md` now and begin.

package/src/templates/code-implementation/loops/01-tasks-loop/prompt.md

@@ -1,10 +1,12 @@
 # Tasks Loop — Implement Tasks
 
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
 **You are agent `{{AGENT_NAME}}`.** Multiple agents may work in parallel.
 Coordinate via `tracker.md` — the single source of truth.
 *(If you see the literal text `{{AGENT_NAME}}` above — i.e., it was not substituted — treat your name as `agent-1`.)*
 
-Read `.ralph-flow/01-tasks-loop/tracker.md` FIRST to determine where you are.
+Read `.ralph-flow/{{APP_NAME}}/01-tasks-loop/tracker.md` FIRST to determine where you are.
 
 > **PROJECT CONTEXT.** Read `CLAUDE.md` for architecture, stack, conventions, commands, and URLs.
 
@@ -16,20 +18,20 @@ Read `.ralph-flow/01-tasks-loop/tracker.md` FIRST to determine where you are.
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
 
-**Lock file:** `.ralph-flow/01-tasks-loop/.tracker-lock`
+**Lock file:** `.ralph-flow/{{APP_NAME}}/01-tasks-loop/.tracker-lock`
 
 ### Acquire Lock
 1. Check if `.tracker-lock` exists
    - Exists AND file is < 60 seconds old → sleep 2s, retry (up to 5 retries)
    - Exists AND file is ≥ 60 seconds old → stale lock, delete it (agent crashed mid-write)
    - Does not exist → continue
-2. Write lock: `echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/01-tasks-loop/.tracker-lock`
+2. Write lock: `echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/{{APP_NAME}}/01-tasks-loop/.tracker-lock`
 3. Sleep 500ms (`sleep 0.5`)
 4. Re-read `.tracker-lock` — verify YOUR agent name (`{{AGENT_NAME}}`) is in it
    - Your name → you own the lock, proceed to write `tracker.md`
    - Other name → you lost the race, retry from step 1
 5. Write your changes to `tracker.md`
-6. Delete `.tracker-lock` immediately: `rm .ralph-flow/01-tasks-loop/.tracker-lock`
+6. Delete `.tracker-lock` immediately: `rm .ralph-flow/{{APP_NAME}}/01-tasks-loop/.tracker-lock`
 7. Never leave a lock held — if your write fails, delete the lock in your error handler
 
 ### When to Lock
@@ -159,4 +161,4 @@ If Tasks Queue in tracker is empty: read `tasks.md`, scan `## TASK-{N}:` headers
 
 ---
 
-Read `.ralph-flow/01-tasks-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/01-tasks-loop/tracker.md` now and begin.

package/src/templates/code-implementation/loops/02-delivery-loop/prompt.md

@@ -1,6 +1,8 @@
 # Delivery Loop — Present Completed Stories for Feedback
 
-Read `.ralph-flow/02-delivery-loop/tracker.md` FIRST to determine where you are.
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/02-delivery-loop/tracker.md` FIRST to determine where you are.
 
 > **You are a service delivery agent. The user is your client.** Your job is to present completed work, gather structured feedback, and resolve it. Small bugs are fixed on the spot. Everything else becomes a new story.
 
@@ -102,4 +104,4 @@ After resolving all feedback:
 
 ---
 
-Read `.ralph-flow/02-delivery-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/02-delivery-loop/tracker.md` now and begin.

package/src/templates/research/loops/00-discovery-loop/prompt.md

@@ -1,6 +1,8 @@
 # Discovery Loop — Identify Research Topics
 
-Read `.ralph-flow/00-discovery-loop/tracker.md` FIRST to determine where you are.
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/00-discovery-loop/tracker.md` FIRST to determine where you are.
 
 > **Map the territory before exploring it.** Your job is to take a broad research brief and decompose it into specific, researchable topics. Each topic should be independently investigable and contribute to the overall research goal.
 
@@ -66,17 +68,17 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE.
    - Tagged with priority (high/medium/low) and estimated depth
 3. Append to `00-discovery-loop/topics.md` (format below)
 4. **Seed `01-research-loop/tracker.md`:**
-   1. Acquire `.ralph-flow/01-research-loop/.tracker-lock`:
+   1. Acquire `.ralph-flow/{{APP_NAME}}/01-research-loop/.tracker-lock`:
       - Exists + < 60s old → sleep 2s, retry up to 5 retries
       - Exists + ≥ 60s old → stale, delete it
       - Not exists → continue
-      - Write lock: `echo "discovery-loop $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/01-research-loop/.tracker-lock`
+      - Write lock: `echo "discovery-loop $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/{{APP_NAME}}/01-research-loop/.tracker-lock`
       - Sleep 500ms, re-read lock, verify `discovery-loop` is in it
    2. Add topics to `## Topics Queue` with metadata:
       - `{agent: -, status: pending}` for topics with no dependencies
       - `{agent: -, status: blocked}` for topics that depend on other topics
    3. Add dependency entries to `## Dependencies` section
-   4. Release lock: `rm .ralph-flow/01-research-loop/.tracker-lock`
+   4. Release lock: `rm .ralph-flow/{{APP_NAME}}/01-research-loop/.tracker-lock`
 5. Update own tracker: mark complete, `stage: scope`, log entry
 6. Exit: `kill -INT $PPID`
 
@@ -116,4 +118,4 @@ If all topics have been discovered and queue is empty: `<promise>ALL TOPICS DISC
 
 ---
 
-Read `.ralph-flow/00-discovery-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/00-discovery-loop/tracker.md` now and begin.

package/src/templates/research/loops/01-research-loop/prompt.md

@@ -1,10 +1,12 @@
 # Research Loop — Investigate Topics
 
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
 **You are agent `{{AGENT_NAME}}`.** Multiple agents may work in parallel.
 Coordinate via `tracker.md` — the single source of truth.
 *(If you see the literal text `{{AGENT_NAME}}` above — i.e., it was not substituted — treat your name as `agent-1`.)*
 
-Read `.ralph-flow/01-research-loop/tracker.md` FIRST to determine where you are.
+Read `.ralph-flow/{{APP_NAME}}/01-research-loop/tracker.md` FIRST to determine where you are.
 
 > **Go deep, stay focused.** Each topic is a specific research question. Your job is to investigate thoroughly and produce structured findings. Use web search, file reading, and any available tools to gather evidence.
 
@@ -16,20 +18,20 @@ Read `.ralph-flow/01-research-loop/tracker.md` FIRST to determine where you are.
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
 
-**Lock file:** `.ralph-flow/01-research-loop/.tracker-lock`
+**Lock file:** `.ralph-flow/{{APP_NAME}}/01-research-loop/.tracker-lock`
 
 ### Acquire Lock
 1. Check if `.tracker-lock` exists
    - Exists AND file is < 60 seconds old → sleep 2s, retry (up to 5 retries)
    - Exists AND file is ≥ 60 seconds old → stale lock, delete it (agent crashed mid-write)
    - Does not exist → continue
-2. Write lock: `echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/01-research-loop/.tracker-lock`
+2. Write lock: `echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/{{APP_NAME}}/01-research-loop/.tracker-lock`
 3. Sleep 500ms (`sleep 0.5`)
 4. Re-read `.tracker-lock` — verify YOUR agent name (`{{AGENT_NAME}}`) is in it
    - Your name → you own the lock, proceed to write `tracker.md`
    - Other name → you lost the race, retry from step 1
 5. Write your changes to `tracker.md`
-6. Delete `.tracker-lock` immediately: `rm .ralph-flow/01-research-loop/.tracker-lock`
+6. Delete `.tracker-lock` immediately: `rm .ralph-flow/{{APP_NAME}}/01-research-loop/.tracker-lock`
 7. Never leave a lock held — if your write fails, delete the lock in your error handler
 
 ### When to Lock
@@ -179,4 +181,4 @@ If Topics Queue in tracker is empty: read `topics.md`, scan `## TOPIC-{N}:` head
 
 ---
 
-Read `.ralph-flow/01-research-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/01-research-loop/tracker.md` now and begin.

package/src/templates/research/loops/02-story-loop/prompt.md

@@ -1,6 +1,8 @@
 # Story Loop — Condense Findings into Narratives
 
-Read `.ralph-flow/02-story-loop/tracker.md` FIRST to determine where you are.
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/02-story-loop/tracker.md` FIRST to determine where you are.
 
 > **Turn research into readable stories.** Your job is to take raw findings and synthesize them into coherent, well-structured narrative stories. Each story should stand on its own while contributing to the overall research picture.
 
@@ -106,4 +108,4 @@ If all stories written: `<promise>ALL STORIES WRITTEN</promise>`
 
 ---
 
-Read `.ralph-flow/02-story-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/02-story-loop/tracker.md` now and begin.

package/src/templates/research/loops/03-document-loop/prompt.md

@@ -1,6 +1,8 @@
 # Document Loop — Compile Stories into Final Output
 
-Read `.ralph-flow/03-document-loop/tracker.md` FIRST to determine where you are.
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine where you are.
 
 > **This is an on-demand loop.** Unlike discovery, research, and story loops, this loop runs once to produce the final document. It reads all completed stories and compiles them into the requested output format.
 
@@ -119,4 +121,4 @@ Read `.ralph-flow/03-document-loop/tracker.md` FIRST to determine where you are.
 
 ---
 
-Read `.ralph-flow/03-document-loop/tracker.md` now and begin.
+Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` now and begin.