Bob the Builder

Workshop materials for building software with LLM agents from a clear idea, through a Product Requirements Document (PRD), into an implementation-ready spec and a sequence of small build loops.

The repo currently packages the setup, skills, and agent profiles copied from pdbe-bioskills and wraps them in a local bobthebuilder installer. The source material is still intentionally close to the original PDBe workflow; later workshop passes can generalise or rename individual skills once the workshop shape is settled.

Workshop Goals

Participants will learn how to:

1. Turn a vague project idea into a PRD that an LLM can reason about and execute from.
2. Separate product intent from implementation detail, so the PRD stays useful and the spec becomes buildable.
3. Break the work into Ralph Loops: small, inspectable, confidence-sized implementation cycles.
4. Install agent skills and profiles for Claude Code and Codex/OpenAI-style workflows.
5. Build a proof-of-principle prototype from their own idea during the hands-on session.

Repository Layout

.
├── src/bobthebuilder/
│   ├── cli.py                 # installer CLI
│   ├── discovery.py           # auto-discovers skills and profiles
│   ├── installer.py           # writes Claude/Codex skill files
│   ├── skills/                # copied LLM skill packs
│   └── profiles/              # copied agent profiles
├── pyproject.toml             # Python package metadata
└── README.md

Install the Workshop CLI

From this repo:

python3 -m pip install -e .

Then check what is available:

bobthebuilder list

Install Skills Into a Project

Run these commands from the project directory where you want the workshop agents to operate.

Install everything for Claude Code:

bobthebuilder install --all --claude

Install everything for Codex:

bobthebuilder install --all --codex

Install both targets:

bobthebuilder install --all --claude --codex

Install only the core lifecycle skills most relevant to the workshop:

bobthebuilder install --claude \
  idea-scoping-interview \
  scoping-decision-capture \
  concept-to-prd \
  sdd-constitution \
  sdd-specify \
  sdd-clarify \
  sdd-plan \
  sdd-tasks \
  sdd-analyze \
  sdd-implement

The same selection can be installed for Codex with --codex.

Installing any sdd-* skill also installs the Spec Kit-derived project scaffold:

.specify/
  memory/constitution.md
  templates/
  scripts/bash/

If you want the notebook continuation path as well, add:

bobthebuilder install --claude \
  prd-to-notebook-spec \
  notebook-spec-review \
  notebook-ux-contract \
  fixture-selection \
  notebook-from-spec \
  notebook-execution-validation \
  notebook-review

You can also install relevant agent profiles by name. For example:

bobthebuilder install --claude \
  lifecycle-orchestrator \
  scientific-product-manager \
  spec-reviewer \
  coding

Where Files Go

Flag	Destination
--claude	Skills to .claude/commands/<name>.md, agents to .claude/agents/<name>.md
--codex	Skills to .codex/skills/<name>/, agents appended to .codex/AGENTS.md
any sdd-* skill	Also installs the shared SDD scaffold to .specify/
--global	Uses $HOME instead of the current project directory
--dir PATH	Uses a custom install base directory

Core Workshop Flow

Use the lifecycle as a sequence of gates. Do not jump straight from a rough idea to "build me an app" unless the work is intentionally exploratory. The point of the workshop is to make each agent step small enough that you can inspect, correct, and continue with confidence.

1. Idea to PRD

Start with a rough idea and use the scoping skills to clarify:

• target user
• problem and context
• desired outcome
• non-goals
• constraints
• success criteria
• open questions

Relevant copied skills:

• idea-scoping-interview
• scoping-decision-capture
• concept-to-prd

The main PRD template currently lives at:

src/bobthebuilder/skills/concept-to-prd/assets/PRD-TEMPLATE.md

Recommended first prompt:

Use $idea-scoping-interview.

I want to explore a new workshop project idea:
<idea>

Do not write a PRD yet.
Interview me until the target user, the problem, the expected outcome, and the rough product shape are clear.

Expected outcome:

• stable problem statement
• target user
• expected artifact or application outcome
• obvious risks and unknowns
• judgment about whether the idea is ready for PRD drafting

2. Optional Advisory Review

Once the idea is stable enough to say this is for X user to solve Y problem with Z outcome, you can ask for role-specific critique before writing the PRD.

This is useful when the idea has meaningful domain, product, technical, data, design, or evaluation risk.

Recommended prompt:

Spawn parallel advisory subagents for this stable idea:
<stable idea statement>

Use relevant roles from the installed agent profiles. Good defaults:
- product/project manager
- domain specialist
- software engineer
- data or evaluation specialist
- UX or visualization specialist, if the user experience matters

Have each subagent return:
- key opportunities
- highest-risk assumptions
- blocking questions
- concrete recommendations
- whether this is ready for $scoping-decision-capture

Expected outcome:

• role-specific critique
• surfaced blockers
• better-defined scope boundaries
• clear recommendation on whether to proceed

For a short workshop exercise, you can skip this step and keep the critique in the main thread.

3. Capture Decisions

Use:

$scoping-decision-capture

Ask the agent:

Use $scoping-decision-capture to synthesize the ideation discussion into a structured decision capture.
Do not write the PRD yet.

Expected output:

• core problem statement
• scope decisions
• user journey summary
• open questions
• success and stop signals

This is the bridge between exploratory discussion and a PRD. It should preserve the decisions and tradeoffs, not prematurely design every implementation detail.

4. Convert the Concept to a PRD

Use:

$concept-to-prd

Ask the agent:

Use $concept-to-prd to turn this scoped concept into a workshop PRD:
<decision capture or approved scoped concept>

Expected output:

prd/<feature>.md

The PRD should define:

• target user and problem
• goals and non-goals
• in-scope and out-of-scope workflows
• success criteria
• assumptions and risks
• constraints
• expected artifact, app, notebook, automation, analysis, or workflow

Keep the PRD focused on what should exist and why. Do not overload it with file-by-file implementation plans, task checklists, cell blueprints, or framework-specific decisions unless those are genuine product constraints.

5. Create SDD Artifacts

The PRD explains what should exist and why. The SDD artifacts turn that product intent into executable development context:

.specify/memory/constitution.md
specs/<feature>/
  spec.md
  checklists/requirements.md
  plan.md
  research.md
  data-model.md
  contracts/
  quickstart.md
  tasks.md

Relevant SDD skills:

• sdd-constitution
• sdd-specify
• sdd-clarify
• sdd-plan
• sdd-tasks
• sdd-analyze
• sdd-implement

Use sdd-constitution once per project when the workshop participant knows the quality bar for their prototype:

Use $sdd-constitution.

Create project principles for this PRD:
prd/<feature>.md

Emphasize spec-first development, independently testable user-story slices, small Ralph Loops, explicit validation, and safe handling of secrets or external services.

Then create the feature spec:

Recommended prompt:

Use $sdd-specify.

Convert prd/<feature>.md into a Spec Kit-style feature specification.
Keep the spec focused on what users need and why.
Do not choose the tech stack or write implementation tasks yet.

Expected output:

specs/<feature>/
  spec.md
  checklists/requirements.md

.specify/feature.json

Clarify the spec before planning:

Use $sdd-clarify.

Review specs/<feature>/spec.md for high-impact ambiguity.
Ask only the questions that materially affect scope, UX, data, security, or validation.
Write accepted answers back into the spec.

Create the technical plan:

Use $sdd-plan.

Use specs/<feature>/spec.md and this technical direction:
<language, framework, storage, constraints, local run expectation>

Expected planning output:

specs/<feature>/
  plan.md
  research.md
  data-model.md
  contracts/
  quickstart.md

Break the plan into implementation loops:

Use $sdd-tasks.

Generate tasks from specs/<feature>/spec.md and specs/<feature>/plan.md.
Organize them by independently testable user story.
Make each task small enough for one Ralph Loop and include exact file paths.

Before building, run a read-only consistency pass:

Use $sdd-analyze.

Review specs/<feature>/spec.md, plan.md, and tasks.md for implementation readiness.
Block implementation if requirements, acceptance criteria, tasks, interfaces, validation, or unresolved questions are too vague.

Only start Ralph Loops after this handoff is true:

• specs/<feature>/spec.md has no unresolved [NEEDS CLARIFICATION] markers.
• specs/<feature>/plan.md names the technical approach, target files, and project structure.
• specs/<feature>/quickstart.md defines the commands or manual checks that prove the prototype works.
• specs/<feature>/tasks.md exists, is grouped by independently testable user story, and each implementation task has an exact file path.
• Each next task is small enough for one Ralph Loop and has objective verification.
• $sdd-analyze reports no critical or high findings. Medium findings are accepted explicitly as workshop risk before implementation starts.

If any of these are missing, go back to $sdd-clarify, $sdd-plan, or $sdd-tasks before asking an agent to build. Ralph Loops should execute reviewed tasks; they should not invent missing requirements, choose unapproved architecture, or guess the verification path.

6. Ralph Loops

A Ralph Loop is a small agent build cycle with a clear input, output, and verification step.

Each loop should include:

• one bounded task
• the exact files or modules in scope
• the relevant spec section
• expected behaviour
• how to verify the result
• what to do if verification fails

This avoids the common failure mode where a long "build me X" prompt causes the model to drift, invent requirements, or bury bugs under a large diff.

Recommended Ralph Loop prompt:

Use $sdd-implement.

Run one Ralph Loop from specs/<feature>/tasks.md.

Task:
<one bounded task>

Scope:
- files/modules allowed to change
- files/modules to read for context
- spec sections to follow

Expected behaviour:
<observable behaviour>

Verification:
<tests, commands, screenshots, manual checks, or review criteria>

Stop and report if the spec is ambiguous or if this task requires changing scope.

Good Ralph Loops are small enough that a human can review the diff and the verification evidence before continuing.

Examples:

• scaffold the project structure and empty routes
• implement one API endpoint and its tests
• build one screen state
• add one parser and fixture
• wire one form to local state
• add validation for one data contract
• replace placeholder output with real computation
• run the app and fix only startup errors

Claude Code Ralph Wiggum Plugin

Claude Code has a Ralph Wiggum plugin that automates the loop inside one Claude session. It uses a Stop hook: when Claude tries to finish, the hook can feed the same prompt back into the session until Claude prints an exact completion promise or hits the iteration limit.

Install it from inside Claude Code:

/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@anthropics-claude-code
/reload-plugins

If direct install fails, run /plugin, open the Discover tab, find ralph-wiggum from the anthropics/claude-code marketplace, and install it interactively. If /plugin is unavailable, update Claude Code first.

Use it only after sdd-analyze passes and the next task has objective verification:

/ralph-loop "Run one Ralph Loop from specs/<feature>/tasks.md.

Task:
<task ID and text>

Scope:
- allowed files/modules
- relevant spec and plan sections

Verification:
<test, lint, build, screenshot, or manual check>

Rules:
- implement only this task
- run verification every iteration
- if blocked, document the blocker and stop changing files
- when complete, mark the task [X] in tasks.md
- output COMPLETE only when verification passes" --completion-promise "COMPLETE" --max-iterations 10

Always set --max-iterations. The completion promise is exact string matching, so use one success phrase such as COMPLETE and rely on the iteration limit as the safety stop.

Codex Ralph Loops

Codex does not need the Claude Stop-hook plugin to run workshop-sized Ralph Loops. The simplest Codex setup is to keep using $sdd-implement one task at a time:

Use $sdd-implement.

Run task T012 from specs/<feature>/tasks.md as one Ralph Loop.
Stop after verification and report changed files, evidence, and remaining risks.

For unattended Codex runs, use the same prompt shape with codex exec from the project root and keep the loop outside Codex in the shell or task runner. That is easier to reason about than emulating Claude's Stop hook, because each Codex run starts with a fresh prompt and the repo diff is the durable state.

Codex /goal

Codex also has an experimental /goal feature for longer-running work. Use it when you want Codex to keep working toward one durable objective instead of stopping after one normal turn. It works best when the objective has a clear target, a validation loop, and enough room for Codex to make progress without you steering every step.

For workshop SDD, /goal is useful after sdd-analyze has passed and tasks.md already defines a verifiable build path:

/goal Complete the MVP user story from specs/<feature>/tasks.md without stopping until:
- all tasks for User Story 1 are marked [X]
- the verification in quickstart.md passes
- no files outside the planned scope are changed
- remaining risks are summarized

You can check the current goal with:

/goal

Control a run with:

/goal pause
/goal resume
/goal clear

Enable /goal from inside the Codex terminal UI:

/experimental

Use the menu to toggle experimental features, including Goals, then restart Codex if prompted.

If /experimental does not activate /goal, edit your Codex config directly. On macOS/Linux this is usually:

~/.config/codex/config.toml

Add or update:

[features]
goals = true
apps = true

Restart Codex after changing the config. For workshop use, keep /goal bounded to one user story, one migration, or one verified task group rather than an open-ended backlog.

Read more in the OpenAI Codex guide: https://developers.openai.com/codex/use-cases/follow-goals.

7. Building Apps and Other Artifacts

For an app, CLI, automation, dashboard, or analysis workflow, use the reviewed spec as the implementation contract. The agent should build one loop at a time and should verify each loop before continuing.

Recommended app-build prompt:

Use $sdd-implement.

Use the reviewed SDD artifacts in specs/<feature>/ to build this project in Ralph Loops.

Start with the smallest runnable proof of principle.
For each loop:
1. state the task and files in scope
2. implement only that task
3. run the agreed verification
4. report changed files, evidence, and remaining risks
5. stop before starting the next loop unless I ask you to continue

For app ideas, the spec usually needs:

• first screen or first command
• primary user journey
• state model
• data model or file format
• external services and secrets policy
• error states
• loading and empty states
• accessibility and responsiveness expectations, where relevant
• tests or manual verification plan
• deployment or local-run instructions

For non-app ideas, adapt the same structure:

• for a script, specify inputs, outputs, flags, failure modes, and examples
• for a data workflow, specify sources, schemas, transformations, validation, and provenance
• for an automation, specify trigger, permissions, side effects, rollback, and logs
• for an analysis, specify assumptions, methods, figures, reproducibility, and review criteria

8. Notebook Direction, If Relevant

The copied skills include a strong notebook lifecycle from the source project. This is one possible direction after the PRD and spec stages, not the default workshop path.

Use the notebook-specific stages when the participant's idea is genuinely a Jupyter notebook or scientific analysis notebook:

prd-to-notebook-spec
  -> notebook-spec-review
  -> fixture-selection
  -> notebook-from-spec
  -> notebook-execution-validation
  -> notebook-review

Notebook projects should usually produce:

specs/<feature>/
  spec-pack-overview.md
  requirements.md
  notebook-ux-contract.md
  notebook-design.md
  cell-blueprint.md
  traceability-matrix.md
  data-contracts.md
  fixture-manifest.md
  validation.md
  tasks.md
  docs-plan.md

notebooks/<feature>.ipynb

Recommended notebook-build prompt:

Act as the notebook builder and use $notebook-from-spec.

Build the notebook described in specs/<feature>/ only if the spec review passed and fixtures are ready.
Do not claim the notebook is validated until $notebook-execution-validation has run.

This notebook path remains available when a participant's idea is genuinely a notebook. The default workshop path is now: idea, PRD, SDD spec, plan, tasks, analysis, Ralph Loops, verification.

9. Agent-Assisted Build

Once the spec is reviewed, participants can run an agent-assisted implementation in Claude Code, Codex, or another compatible workflow.

The copied installer supports both:

• Claude Code command and agent directories
• Codex-style skills and AGENTS.md

The repo does not yet claim feature parity between Claude and Codex/OpenAI workflows. That comparison is a workshop discussion point and will be refined as the materials evolve.

Useful Starting Files

Key skills to inspect first:

src/bobthebuilder/skills/idea-scoping-interview/SKILL.md
src/bobthebuilder/skills/scoping-decision-capture/SKILL.md
src/bobthebuilder/skills/concept-to-prd/SKILL.md
src/bobthebuilder/skills/sdd-constitution/SKILL.md
src/bobthebuilder/skills/sdd-specify/SKILL.md
src/bobthebuilder/skills/sdd-clarify/SKILL.md
src/bobthebuilder/skills/sdd-plan/SKILL.md
src/bobthebuilder/skills/sdd-tasks/SKILL.md
src/bobthebuilder/skills/sdd-analyze/SKILL.md
src/bobthebuilder/skills/sdd-implement/SKILL.md
src/bobthebuilder/sdd_scaffold/templates/spec-template.md
src/bobthebuilder/sdd_scaffold/templates/plan-template.md
src/bobthebuilder/sdd_scaffold/templates/tasks-template.md

Key profiles to inspect first:

src/bobthebuilder/profiles/lifecycle-orchestrator/AGENTS.md
src/bobthebuilder/profiles/scientific-product-manager/AGENTS.md
src/bobthebuilder/profiles/spec-reviewer/AGENTS.md
src/bobthebuilder/profiles/notebook-builder/AGENTS.md
src/bobthebuilder/profiles/coding/AGENTS.md

Next Material To Add

Planned workshop additions:

• a general, non-notebook PRD template
• example participant project repo
• Claude Code setup guide
• Codex/OpenAI setup guide
• facilitator notes for the two-hour hands-on session

Acknowledgement

The initial skills, profiles, and installer structure were copied from the local pdbe-bioskills repository and adapted into the bobthebuilder package namespace for this workshop.

The SDD scaffold and templates are derived from the local spec-kit repository and adapted into workshop skills that install alongside the existing .codex/skills and .claude/commands conventions.