richfrem/subagent-driven-prototyping

Architectural patterns adapted from obra/superpowers (MIT)

Dashboard Intercept

Before doing anything else, silently check for exploration/exploration-dashboard.md.

• If the file EXISTS: Read it silently and check the **Status:** line.

  • If **Status:** Complete → the prior session has ended. Proceed with this skill's standalone flow as normal.
  • Otherwise → an active session is in progress. Stop immediately. Do not continue here. Announce to the user:

    "It looks like you have an active Exploration Session in progress. Let me take you back to your session dashboard so we can keep your progress on track." Return to the orchestrator. Use the Skill tool: skill: "exploration-workflow". After invoking it, stop generating output from this skill — do not continue below.

• If the file does NOT exist: Proceed with this skill's standalone flow as normal.

<example> <commentary>Demonstrates the skill being invoked by prototype-builder after layout has been confirmed by visual-companion.</commentary> User: [dispatched by prototype-builder after layout confirmed] Agent: Verifies the Discovery Plan and layout direction files exist, announces the number of components and their plain-language names, then builds each one in order — announcing each start, checking it against the plan on completion, and reporting each as done before moving to the next. </example> <example> <commentary>Demonstrates a user triggering the skill directly after plan approval.</commentary> User: Let's build it Agent: Checks for the required Discovery Plan and layout direction files. If both exist, announces the build plan in plain language and begins building each component one at a time with progress updates. </example>

Orchestrator Context

If dispatched by exploration-workflow, the Discovery Plan and layout direction have already been approved by the SME. The Required Inputs Check below is a verification step only — do not re-present these artifacts for re-approval. Proceed directly to Component Decomposition once inputs are confirmed present.

Execution Discipline (powered by orba/superpowers)

Required: The orba/superpowers plugin must be installed.

This skill invokes superpowers execution discipline skills during the build loop.

Isolation

Before building, check if a worktree/feature branch was set up by the orchestrator. If not, and the session type is brownfield or greenfield, invoke superpowers:using-git-worktrees now to create one.

Dispatch Strategy

Read the **Dispatch Strategy:** field from the dashboard. Use it to determine how to dispatch component implementation:

• copilot-cli: Use copilot-cli-agent skill. Simple components → gpt-5-mini (free). Complex/multi-file components → claude-sonnet-4-6 (batch into one dense request — charged per request, not per token).
• claude-subagents: Use the Agent tool. Mechanical components → model: "haiku". Complex components → model: "sonnet".
• direct: Build each component directly in this session.

Two-Stage Review (per component)

After each component is built, invoke superpowers:requesting-code-review twice:

1. Plan alignment check — reviewer sub-agent verifies component matches the Discovery Plan
2. Quality check — reviewer sub-agent checks code quality and codebase conventions

For copilot-cli and claude-subagents dispatch: use a separate sub-agent for each review. For direct mode: self-review both stages before proceeding.

Validation

Even prototypes must be verified against the Discovery Plan — the prototype is the evidence that exploration captured the right thing. Unverified prototypes lead to flawed handoffs and wrong specs.

For code-producing sessions, invoke superpowers:test-driven-development for each component: write a failing test that verifies a Discovery Plan requirement → verify failure → implement → refactor.

Finishing

After all components are built, invoke superpowers:finishing-a-development-branch: verify tests pass, then present merge/PR options to the SME.

Required Inputs Check

Before doing anything else, verify the following:

1. Discovery Plan (required): At least one .md file in exploration/discovery-plans/. If missing, stop and report what needs to happen first.
2. Layout direction (conditional): Check the dashboard — if Phase 2 is marked [~] (skipped), layout-direction.md will not exist, and that is correct. Proceed without it, using the Discovery Plan's success criteria to guide visual decisions. Only if Phase 2 was enabled ([x] or [ ]) is exploration/captures/layout-direction.md required.

Session Mode Detection

Read exploration/exploration-dashboard.md and check the **Session Type:** field:

• Greenfield (Type 1): Build a standalone prototype in exploration/prototype/. Follow the standard Build Loop below.
• Brownfield (Type 2): Build directly into the existing codebase. Before starting, read the project structure to understand existing patterns (component conventions, file locations, styling, API patterns). Match them. Write documentation of what was built to exploration/prototype/components/ as .md files for tracking.
• If the session type field is missing, blank, or unrecognized: Ask the SME: "Should I build a standalone prototype, or add this directly into your existing codebase?"

Agent Plugin Build Mode Detection

⚠️ HARD CONSTRAINT — read before touching any file.

Before entering the Build Loop, check the Discovery Plan's Intervention Type field:

• If the output is described as an "Agent Plugin", "Claude Plugin", "agentic plugin", or "plugin" with skills/agents/commands — this is Agent Plugin Mode.

If Agent Plugin Mode is detected:

1. Redirect the build path away from exploration/prototype/. Build to plugins/[plugin-name]/ at the project root — NOT exploration/prototype/. Announce: "Since we're building an Agent Plugin, I'll scaffold it into plugins/[plugin-name]/ using the standard plugin structure."

2. MUST use the ecosystem scaffolding tools — no raw mkdir, no hand-crafted markdown. You are prohibited from creating plugin directories or skill files with raw bash commands (mkdir, manual file writes). Instead, invoke the .agents/skills/create-plugin and .agents/skills/create-skill skills from the local agent-scaffolders plugin:

   Skill: create-plugin
   Skill: create-skill
   

   These enforce eval harnesses, directory templates, frontmatter standards, and plugin.json registration. Bypassing them produces non-compliant plugins that will fail audit.

3. After the create-plugin scaffold is complete, ensure every generated skill and agent is wired into .claude-plugin/plugin.json. See the plugin.json Binding Check in the Assembly section below.

4. After all components are built, run: /agent-scaffolders:audit-plugin to verify structural compliance before marking Phase 3 complete.

If NOT Agent Plugin Mode: Follow the standard Greenfield or Brownfield build path below.

Component Decomposition

Based on the Discovery Plan and layout direction (if available), identify 3–6 logical components. Use plain-language names the SME will understand (e.g., "top navigation bar", "summary panel", "request form", "approval confirmation screen") — not technical terms.

Announce:

"I'll put this together in [N] parts. I'll check each one before moving to the next to make sure it matches our plan."

List the components by name so the SME knows what is being built.

For Brownfield sessions, also announce:

"I'll build these directly into your existing codebase, matching the patterns I see in [framework/stack]."

Build Loop

For each component, in order:

1. Announce start: "Working on: [plain-language component name]..."
2. Build the component.
   • Greenfield: Write to exploration/prototype/components/[descriptive-name].[ext]
   • Brownfield: Write to the appropriate location in the existing codebase. Also write a brief .md summary to exploration/prototype/components/[descriptive-name].md documenting what was built and where.
3. Self-review: Read the completed component against the Discovery Plan requirements and layout direction. Check that it serves the stated user groups and success criteria. For brownfield, also check that it follows the existing codebase conventions.
4. Assign a status:
   • COMPLETE — component matches the plan and is ready
   • BLOCKED — something is preventing completion (missing data, contradictory requirements, etc.)
   • NEEDS_CONTEXT — a specific question must be answered before the component can be finished
5. If BLOCKED: Stop. Explain the problem in plain language. Ask the SME to resolve it before continuing.
6. If NEEDS_CONTEXT: Stop. Ask the specific question needed. Wait for the SME's answer before continuing.
7. Only advance to the next component when the current one has status COMPLETE.

Report each completed component to the user:

"Done — [component name] is done."

Assembly

After all components reach COMPLETE status:

Greenfield:

1. Assemble into exploration/prototype/index.html (or an equivalent entry point that links all components together)
2. Write exploration/prototype/README.md with run instructions in plain language

Brownfield:

1. Verify the feature works within the existing app (build succeeds, no type errors in new files)
2. Write exploration/prototype/README.md documenting:
   • All new files created (with paths)
   • All existing files modified (with paths)
   • How to test the feature (which URL, which command, etc.)

Agent Plugin Mode — plugin.json Binding Check (MANDATORY before completion):

1. Read .claude-plugin/plugin.json in the built plugin directory.
2. For every skill directory under skills/, verify its entry appears in the skills list in plugin.json.
3. For every agent file under agents/, verify its entry appears in the agents list in plugin.json.
4. For every command file under commands/, verify its entry appears in the commands list in plugin.json.
5. For every hook file under hooks/, verify its entry appears in the hooks list in plugin.json.
6. If any component is missing from plugin.json: Add it now. Do NOT wait for the SME to notice.
7. Report: "All plugin components are registered in plugin.json. ✅" or list any additions made.

This check is non-optional. A plugin with unregistered components is a broken plugin.

Completion Report

Announce: "Your prototype is ready — Phase 3 is complete."

Completion — Return to Orchestrator

If operating within an active Exploration Session (i.e., exploration/exploration-dashboard.md exists and **Status:** is not Complete):

1. Say to the user:

   "Your prototype is ready for review. Please click the index.html link above to test it." "Once you approve the layout and logic, you must push us to the next phase to generate your formal User Stories and API Specs." "Please reply with exactly: 'Return to dashboard and start Phase 4 Handoff'"

2. Immediately stop. Do not attempt an automated skill switch. You must wait for the user to explicitly type the confirmation phrase to ensure they have actually reviewed the prototype before Phase 4 automation begins.

After the user provides the confirmation phrase, output this machine-readable block:

## HANDOFF_BLOCK
PHASE: 3
STATUS: COMPLETE
OUTPUT: exploration/prototype/index.html
SESSION_TYPE: [Greenfield / Brownfield / Agent Plugin]
COMPONENTS_BUILT: [count]
WORKTREE: [branch name if worktree was created, or "none"]

If operating standalone (no dashboard file, or **Status:** Complete), the skill is complete. Report back to prototype-builder: all components are built, the entry point is at exploration/prototype/index.html, and the prototype is ready for the SME walkthrough.

Gotchas

• Worktree setup not idempotent: If superpowers:using-git-worktrees was already called by the orchestrator, calling it again creates a nested worktree. Check if a worktree branch already exists before invoking the setup skill.
• Brownfield build leaves orphaned prototype/ directory: For brownfield sessions, the actual code changes go into the real codebase but .md tracking files go to exploration/prototype/components/. If the session is later revisited, these stale .md files may describe code that has since been refactored. Mark tracking files with the build date.
• Agent Plugin Mode detection is order-sensitive: The Discovery Plan Intervention Type check happens BEFORE Component Decomposition. If the model reads "plugin" in a different context (e.g., "we'll use the WordPress plugin ecosystem"), it may incorrectly trigger Agent Plugin Mode. The trigger condition is "Agent Plugin" or "agentic plugin" as the PRIMARY output type, not any mention of "plugin".
• plugin.json Binding Check must run before completion, not after: The check is listed in the Assembly section but agents sometimes defer it to "after the build loop". Run the binding check as part of Agent Plugin Mode assembly, not as a post-completion step.
• Two-stage review skipped for direct mode: In direct mode the self-review is supposed to run twice (plan alignment + quality). In practice only one pass is done. Explicitly label and separate the two review purposes when self-reviewing.

Persona Enforcement

Throughout this skill, always use plain language in user-facing text:

• Say "build" — not "scaffold", "generate", or "create"
• Say "set up" — not "initialize" or "instantiate"
• Say "put together" — not "spin up"
• Say "check" — not "validate" or "verify" (in user-facing messages)
• Keep all progress updates brief and plain: one sentence per update