scaffold-runner

What this skill does

# Scaffold Runner

This skill provides an intelligent interactive layer between the user and the `scaffold` CLI. It ensures that decision points embedded in scaffold prompts are surfaced to the user before execution, and manages the full step lifecycle.

## When This Skill Activates

- User says "run scaffold <step>", "scaffold <step>", or "run the next scaffold step"
- User asks "what's next?", "where am I in the pipeline?", or "scaffold status"
- User asks to run any pipeline step by name (e.g., "create the PRD", "set up testing")
- User asks to run multiple steps: "run all reviews", "run phases 5-8", "finish the pipeline", "run the next 5 steps"
- User asks to re-run groups: "re-run all reviews", "redo quality gates", "re-run from user-stories onward"
- User says "start building", "begin implementation", "run agent", "start agent"
- User asks about tools: "bump version", "create a release", "show version"
- User says "what can I build?" or "what tools are available?"
- Working in a project with a `.scaffold/` directory

## Core Workflow: Smart Scaffold Execution

When the user wants to run a scaffold step, follow this exact process:

### Step 1: Check Eligibility

Run `scaffold next` to see what's eligible. If the user named a specific step, verify it appears in the eligible list. If it's not eligible, explain which dependencies are blocking it and suggest the eligible steps instead.

```bash
scaffold next
```

### Step 2: Preview the Assembled Prompt

Capture the assembled prompt WITHOUT executing it yet:

```bash
scaffold run <step> --auto 2>&1
```

Save the output. This is the full 7-section prompt that includes step instructions, knowledge base content, project context, and methodology guidance. **Do not execute the prompt content yet.**

### Step 3: Extract Decision Points

Scan the assembled prompt for user-facing questions. Look for these patterns:

**Explicit question markers:**
- Lines containing `AskUserQuestionTool` or `AskUserQuestion`
- Lines containing "ask the user" or "ask me"
- Lines containing "Use AskUserQuestionTool for these decisions:"

**Common decision categories:**
- **Depth/thoroughness**: "depth level", "how thorough", "exhaustive vs focused"
- **Strictness**: "strict", "moderate", "lenient", "strictness level"
- **Optional sections**: "include [X]?", "optional", "skip if not needed"
- **Architecture choices**: "which pattern", "choose between", "select"
- **Technology preferences**: "framework", "library", "tool choice"
- **Scope decisions**: "MVP or full", "include [feature]?", "defer or include"

**Decision extraction rules:**
- Group related questions together (don't ask one at a time)
- Provide the options mentioned in the prompt text
- Include your recommendation based on the project context
- If the prompt says "use AskUserQuestionTool for these decisions:" followed by a bulleted list, extract each bullet as a separate question

### Step 4: Surface Decisions to the User

Present all extracted decision points to the user using AskUserQuestion. Group them into a single call with up to 4 questions. If there are more than 4, batch them into multiple calls.

For each decision:
- Frame it as a clear choice with concrete options
- Include the default/recommended option based on the project's methodology preset
- Add brief context about the impact of each choice

**Example presentation:**
```
Before running this step, I need a few decisions:

1. Architecture depth: Full specification with detailed data flows, or high-level
   component overview? [Full spec (recommended for depth 5) / High-level overview]

2. Include performance benchmarks section? [Yes / No — skip for MVP]

3. Error handling strategy: Custom error classes with codes, or standard
   try/catch with logging? [Custom classes (recommended) / Standard try/catch]
```

If the assembled prompt has NO decision points (the step is fully automated), skip this step and proceed directly to execution.

### Step 5: Execute the Prompt

Now execute the assembled prompt as your working instructions. This means:

1. Read the assembled prompt output from Step 2
2. Follow its instructions section by section
3. Where the prompt says "ask the user about X", substitute the answer from Step 4
4. Where the prompt says "use AskUserQuestionTool", use the pre-collected answer instead
5. Perform all file operations, artifact creation, and validation the prompt describes

**Critical: Execute the FULL prompt faithfully.** Don't skip sections, don't summarize, don't take shortcuts. The assembled prompt was carefully constructed with knowledge base content and project context — every section matters.

### Step 6: Post-Execution

After the step completes:

1. **Mark completion** — If the step was run via `scaffold run`, it's auto-tracked. If the prompt was captured with `scaffold run --auto` and executed manually, mark it complete:
   ```bash
   scaffold complete <step>
   ```
   Then verify with `scaffold status`.

2. **Show what's next** — Run:
   ```bash
   scaffold next
   ```

3. **Offer continuation** — Tell the user:
   ```
   Step complete. Next eligible: scaffold run <next-step>
   Want me to continue with the next step?
   ```

## Stateless Step Execution

Build phase steps (phase 15) and tools are **stateless** — they don't track completion state. When executing a stateless step, modify the Smart Scaffold Execution workflow:

### Modified Post-Execution (replaces Step 6 for stateless steps)

After executing a stateless step:

1. **Skip** `scaffold complete <step>` — stateless steps have no completion state
2. **Skip** "show what's next" — build steps are always available
3. **Instead**: Show a brief execution summary and offer to run another build step or tool:
   ```
   Step executed. Build phase steps are always available for re-use.
   Run another? single-agent-start | quick-task | new-enhancement | ...
   ```

### Resume Step Visibility

`single-agent-resume` and `multi-agent-resume` are conditionally shown — only offer them when evidence of prior agent activity exists:
- Feature branches (e.g., `bd-*` branches) in git
- In-progress tasks (Beads `bd list` shows in_progress, or implementation plan tasks marked started)
- Open PRs from previous agent work

If no prior activity is detected, suggest `single-agent-start` or `multi-agent-start` instead.

## Tool Execution

Tools (version-bump, release, version, update, dashboard, prompt-pipeline, session-analyzer, review-code, review-pr, post-implementation-review) are utility commands orthogonal to the pipeline.

### Differences from Pipeline Steps

- **No eligibility check** — tools are always available, regardless of pipeline progress
- **No state tracking** — tools don't appear in `scaffold next` or `scaffold status`
- **Argument passthrough** — tools support CLI arguments: `scaffold run release --dry-run`, `scaffold run version-bump patch`

### Tool Execution Flow

1. **Skip eligibility** — don't run `scaffold next` to check
2. **Preview** — `scaffold run <tool> --auto 2>&1` (same as pipeline steps)
3. **Extract decisions** — same process as pipeline steps
4. **Execute** — follow the assembled prompt faithfully
5. **No completion** — skip `scaffold complete`, skip "what's next"

### Accessing Tools

- `scaffold run <tool-name>` — run a specific tool
- `scaffold list --section tools` — show available tools (compact)
- `scaffold list --section tools --verbose` — show with argument hints
- `scaffold list --section tools --format json` — machine-readable output

## Tool Listing

When the user asks "what tools are available?", "what can I build?", or "show me the tools":

1. Run `scaffold list --section tools --format json`
2. Parse the JSON: `data.tools.build` (build phase steps) and `data.tools.utility` (utility tools)
3. Render as two grouped sections:

**Build Phase (Phase 15)**
> These are stateless pipeline steps — they appear in `scaffold next` once Phase 14 is complete and can be run repeatedly.

| Command | When to Use