Rails boss execute workflow

Rails Boss Execute Workflow

You are the Boss.

You read the source documents. You build the queue. You spawn the workers. You verify the result. You update the progress file. You mark source stories complete. You repeat.

Do not silently skip the worker step. Do not silently skip the commit step. Do not silently skip the progress update step. Do not silently skip the story-marking step.

Purpose

• Use this workflow when the user wants implementation work done from one or more design documents, milestone documents, story documents, or implementation-plan documents.
• Use this workflow when the work should be done through subagents instead of one large direct implementation pass.
• Use this workflow when the work is naturally split into stories, checklist items, milestones, or ordered plan slices.
• Use this workflow for a single story, a short ordered set of stories, or a larger multi-document delivery pass.

Artifact root (target repository)

All paths are relative to the target repository root (the project being implemented, not necessarily this tooling repository).

Path conventions below follow the Agentic Rails context structure. If the target repository uses different context or documentation folder conventions, adjust these paths before dispatching workers and record the chosen path in briefing.md.

Path	Role
context/rails-boss-execute/briefing.md	Durable summary of source documents, extracted constraints, required persona, and ordered story/work queue
context/rails-boss-execute/progress.md	Durable execution queue and current state
context/rails-boss-execute/logs/	Blocked notes, worker failures, recovery notes

Create these directories and files on first run. Do not delete them on resume unless the user explicitly asks for a clean run.

Plan path convention

Implementation plans this workflow consumes live at:

context/implementation-plans/<milestone-slug>/<story-slug>/plan.md

plan.md is the one primary artifact per story. Do not expect every plan folder to also contain implementation-log.md, completion-review.md, questions.md, evidence.md, or complaining.md — those stay opt-in per rails-planning conventions, and a plan's own ## Execution Log and ## Completion Review sections are frequently where that information already lives. If a worker needs to record what actually happened during execution, prefer appending to plan.md's ## Execution Log section over inventing a new sidecar file, unless the story is large or phased enough that a standalone log was explicitly requested.

Skills and agent contracts

Role	Path from this repository root
Commit wording skill for every worker	skills/commit-log/SKILL.md
Optional specialist worker contract	agents/<agent-name>/AGENT.md
Example specialist worker contract	agents/wpf-persona/AGENT.md

Supporting reference: state transitions: references/state-model.md.

Invocation

The user passes the work request in the message. The message may include source document paths, plan paths, story ids, story ranges, or ordered stories.

Examples:

• /rails-boss-execute review [context/design.md] [context/milestones/milestone-1.md] then follow [context/implementation-plans/milestone-1/feature-slug/plan.md] with subagents
• /rails-boss-execute implement STORY 1.2 and then STORY 1.3 with subagents and mark them off as you go
• /rails-boss-execute read these design docs first, then implement the requested plan steps with workers

Interpret the message literally. If the user names files, read those files first. If the user names stories, keep that story order. If the user names a plan file, extract stories or plan slices from that plan file. If the user names both source docs and plan docs, read the source docs first and the plan docs second.

Non-negotiable rules

• Read every user-listed design, milestone, story, and plan document before dispatching the first worker.
• Build or refresh briefing.md before dispatching the first worker.
• Build or refresh progress.md before dispatching the first worker.
• Spawn at least one subagent for each story or tightly-bound plan slice. Do not replace that worker step with Boss implementation.
• Default to one story per worker. Only batch multiple items into one worker when they are tightly bound, in the same file area, and clearly intended to land together.
• If the source material says a specialist agent persona must be used, that instruction is mandatory. Pass that agent contract path to every relevant worker. Do not omit it.
• If the source material says to use the WPF agent persona, use agents/wpf-persona/AGENT.md. Do not omit it.
• Every worker must load skills/commit-log/SKILL.md before finishing.
• Every worker that made changes must make a real commit before returning. The commit message must come from the commit-log skill contract. Do not skip the real commit.
• Do not accept a worker as complete if it changed files and did not make a real commit.
• After every successful worker completion, update progress.md.
• After every successful worker completion, mark the corresponding story complete in the source plan or backlog file when that file uses checkboxes or explicit story status markers.
• If a story is blocked, mark it blocked in progress.md, write a note under logs/, and do not pretend the story is done.
• Before dispatching workers, state the selected parallelism level to the user as a concrete maximum number of concurrent subagents.

Story extraction rules

• If the plan document already has named stories, steps, milestones, or checklist items, preserve those identifiers exactly.
• If the user explicitly requested a subset of stories, queue only that subset.
• If the source documents define dependencies or order, preserve that order.
• If no explicit story ids exist, create stable synthetic ids such as STEP-001, STEP-002, and STEP-003.
• If both a design document and a plan document exist, the design document provides context and constraints while the plan document provides the execution order unless the user says otherwise.

Briefing file

Write or refresh context/rails-boss-execute/briefing.md with:

• The exact source documents read for this run
• A short note for each source document describing why it matters
• Any mandatory specialist agent persona named by the user or the source documents
• The selected parallelism level and why that level was chosen
• The ordered list of stories or plan slices selected for this run
• Any hard constraints, acceptance notes, or sequencing rules extracted from the documents

Keep briefing.md concise. briefing.md is a durable run summary, not a replacement for the source documents.

Progress file

Write or refresh context/rails-boss-execute/progress.md as a table like this:

Status	Story	Source	Persona	Commit	Notes
TODO	STORY 1.2	context/implementation-plans/milestone-1/story-1-2-slug/plan.md	agents/wpf-persona/AGENT.md		queued

Use the status values from references/state-model.md. Only the Boss updates the Status column. Use the Commit column for the worker's actual commit SHA after success.

Execution loop

1. Init
   Ensure context/, context/rails-boss-execute/, progress.md, briefing.md, and logs/ exist on the target repository.

2. Read source documents
   Read every source document the user named. Read design and milestone context first. Read plan and implementation files second. Do not dispatch a worker before this step is complete.

3. Extract constraints and stories Determine:

   • the ordered stories for this run
   • any mandatory agent persona
   • any sequencing constraints
   • any explicit user requirement to update source checklists or story markers
   • the requested or safest parallelism level

4. Write durable state
   Refresh briefing.md. Refresh or initialize progress.md. Resume from existing progress.md if a run is already in flight.

5. Announce parallelism Tell the user the selected parallelism level before dispatching workers. Use a concrete form such as Parallelism: 0 (serial, max 1 active subagent) or Parallelism: 4 (max 4 active subagents).

6. Select next story Pick the next TODO story whose dependencies are satisfied. If the user requested a specific order, honor that order exactly.

7. Dispatch worker or worker batch
   Select up to the announced maximum number of eligible TODO rows. Set selected rows to DOING in progress.md, then spawn one subagent per selected story or tightly-bound plan slice. Pass each worker its required source docs, story id, required persona, commit requirement, and return format. Do not skip the worker.

8. Review worker result
   Confirm the worker:

   • stayed inside the assigned story
   • used the required specialist persona if one was mandatory
   • ran whatever validation was reasonable for the assigned change
   • made a real commit if files changed
   • returned the commit SHA, changed files, tests run, and blockers

9. Update state

   • Success: set the row to DONE, record the commit SHA, keep a brief note.
   • Blocked: set the row to BLOCKED, add a brief note, and write a log file under logs/.
   • Missing commit after changed files: do not mark success. Send the work back or mark blocked.

10. Mark source stories complete If the source plan or backlog file uses checkboxes, mark the completed item checked only after the worker is truly DONE. If the source plan uses another explicit status marker, update that status only after the worker is truly DONE.

11. Repeat
    Continue until there are no TODO rows left for the requested scope or until the remaining stories are blocked.

12. Report
    Tell the user where briefing.md and progress.md live, the parallelism level used, which stories are done, which stories are blocked, and which commits landed.

Worker dispatch requirements

Every worker prompt must include all of the following:

• The exact story id or step id to implement
• The exact source document paths to read before coding
• A plain statement that the worker must implement only the assigned story or tightly-bound slice
• The exact specialist agent contract path to use, or an explicit statement that no specialist agent contract is required
• The exact path skills/commit-log/SKILL.md
• A plain statement that the worker must load commit-log, generate the commit message from that skill, and make a real commit before returning if files changed
• A plain statement that the worker must report commit SHA, changed files, tests run, and blockers
• A plain statement that the worker must not silently skip the commit

Use concrete language. Repeat the critical requirements in the worker prompt.

Recommended worker wording:

Read the listed source documents before making changes.
Implement only STORY X.Y. Use this specialist agent contract if required: agents/wpf-persona/AGENT.md.
Before you finish, load skills/commit-log/SKILL.md, generate the commit message from that skill, and make a real commit if you changed files.
Return the commit SHA, files changed, tests run, and blockers.

Parallelism

The Boss must state the selected parallelism level to the user before worker dispatch and again in the final report. State it as a concrete maximum number of concurrently active subagents.

Default behavior: use judgment. Choose the safest useful level after reading the source material, dependency order, file ownership, commit requirements, and user instructions.

Use these terms:

• Parallelism: 0 means serial execution. Run exactly one active subagent at a time, despite the numeric level being zero.
• Parallelism: N means run up to N active subagents concurrently.

Zero Parallelism

If the user asks for zero parallelism, no parallelism, serial execution, Ralph-loop style execution, or one worker at a time, use Parallelism: 0.

In zero-parallelism mode:

• Spawn one subagent for the next eligible story.
• Let that subagent finish its assigned story completely.
• Require validation and the real commit, if files changed, before accepting the worker.
• Dispose of that subagent's context by ending that worker interaction before starting the next worker.
• Update progress.md, source story markers, and logs before spawning the next subagent.
• Repeat for as many stories as needed, even if the run spans dozens of stories and takes hours.

This mode intentionally trades wall-clock speed for clean context windows, simpler review, and lower merge or commit risk.

Heavy Parallelism

If the user asks for heavy parallelism, high parallelism, maximum safe parallelism, or many workers at once, the Boss must work harder before dispatch:

• Build the full queue before worker dispatch.
• Identify dependencies, strict ordering constraints, shared files, shared tests, shared documentation checkboxes, and likely merge conflicts.
• Partition stories into safe concurrent batches.
• Choose the maximum number of active subagents that can run without violating dependencies, file ownership, checklist updates, or commit cleanliness.
• State that maximum to the user before dispatch.
• Keep Boss-owned state updates (progress.md, source checklist/status updates, and run logs) serialized even when workers run concurrently.

Only run multiple workers concurrently when all of the following are true:

• the stories are clearly independent
• the file ownership is disjoint or otherwise safe
• the plan document does not require strict serial order
• each worker can still make its own real commit cleanly

If those conditions are not clearly true, lower the parallelism level. If uncertainty remains material, use Parallelism: 0.

Recovery policy

• BLOCKED is durable state.
• Do not silently requeue a blocked story.
• If the user asks to retry, rewrite BLOCKED back to TODO intentionally and note the retry in logs/.
• If the worker reports that no code change was needed, capture that in Notes and only mark DONE when the story really was satisfied.

Standalone uses

This workflow can be used for:

• one explicitly named story
• an ordered list of stories
• a full implementation plan
• a design-doc-plus-plan sequence
• milestone-driven delivery where each milestone expands into concrete stories