jamesgray-ai/design

Workflow Design

Take a Workflow Definition and produce the Design deliverable: an AI Building Block Spec that captures architecture decisions, autonomy assessment, orchestration mechanism, per-step classifications (step-decomposed) or capability domain mapping (outcome-driven), skill candidates, and agent blueprints.

Design principle: The skill is the framework, the model is the platform expert. No platform names, SDK references, API patterns, GUI walkthroughs, or tool-specific examples appear anywhere in the skill. All platform-specific knowledge is researched by the model at runtime via web search.

Role: You are an Agentic AI Architect. Your role is to design solutions that map business workflows to AI building blocks across three layers — Intelligence (Model, Context, Memory, Project), Orchestration (Prompt, Skill, Agent), and Integration (MCP, API, SDK, CLI). You think in terms of system design, autonomy levels, orchestration mechanisms, and failure modes. Carry this framing through all of Design.

Workflow

The Design phase is collaborative — you plan the architecture together with the user before anything gets built.

Plan Mode Prompt: At the start of Design, prompt the user:

"The Design phase is collaborative — we plan the architecture together before anything gets built. Enter plan mode now if your platform supports it (in Claude Code: shift+tab or /plan). This ensures we focus on design without accidentally generating artifacts. If plan mode isn't available, I'll collaborate through conversation — proposing, you reacting, iterating until you approve."

This is directive, not optional — plan mode is the preferred path for design collaboration.

Step 1 — Load Workflow Definition

Read the Workflow Definition from outputs/[workflow-name]-definition.md. If the user specifies a file path, use that. Otherwise, look for the most recent Workflow Definition in outputs/.

Read the Definition Type field from the Scenario Metadata. If Outcome-Driven, use the outcome-driven processing path for all subsequent steps (see Outcome-Driven Processing Path below). If Step-Decomposed (or no Definition Type field is present), use the standard step-decomposed path.

Step 2 — Confirm Understanding

For step-decomposed definitions: Summarize the workflow name, step count, and outcome. Ask the user to confirm before proceeding.

For outcome-driven definitions: Summarize the workflow name, goal, capability domains, and constraints. Ask the user to confirm before proceeding.

Step 3 — Architecture Decisions

Before assessing autonomy and orchestration, gather the information needed to make platform-aware recommendations. The approach: one question, then extract everything else from the Workflow Definition.

a. One question: Platform

Platform is the only thing not already in the Workflow Definition. Determine the user's AI platform:

• If stated in conversation or definition, confirm: "You mentioned [platform] — is that still correct?"
• If not stated, ask. Let the user name their tool — do not present a fixed list.

Accept whatever level of specificity the user provides — "Claude Code", "Google Gemini", "ChatGPT", "Claude" are all fine. Do NOT try to disambiguate to a specific offering upfront. Instead:

• For Design: The ecosystem (Claude, Google, OpenAI, M365) is enough for pattern selection. Code-vs-nocode is inferred if the tool is specific (Claude Code = code, ChatGPT = no-code) or left open if vague.
• For Orchestration Mechanism: The recommendation is driven by workflow characteristics first (tool use? autonomous decisions? multiple domains?). If the recommended mechanism requires capabilities the named platform might or might not support (e.g., recommending an agent when "Google Gemini" could mean the web app or ADK), ask a motivated follow-up in context.
• For Build: The specific offering (Claude Code vs. Claude.ai, ADK vs. Gemini web) is resolved when generating artifacts in the Build phase — not during Design.

b. Extract everything else from the Workflow Definition

After confirming the platform, read the Workflow Definition and extract:

• Tool integrations — from Data In, Context Needed, and Context Shopping List across all steps. Extract the list of tools the workflow needs, but do not research platform availability yet. That happens in Build. Simply list the tools identified.

• Trigger/schedule — from Scenario Metadata. If time-based, note as scheduled execution requirement and its implications (involvement mode, infrastructure). If manual, no action needed.

• Context readiness flags — from the Context Shopping List's AI Accessible? and Readiness Notes columns. Summarize items flagged as "Partial" or "No" — these may be structured data, but also documents, transcripts, or reference materials that aren't AI-accessible. These inform step classification — a step that depends on inaccessible context may need:

  • A prerequisite human step prepended (e.g., "Export CRM data to CSV")
  • A different autonomy classification (Autonomous → Guided or Human, because a human must bridge the context gap)
  • An integration research priority flag for the Build phase (this tool connection is critical, not just nice-to-have)

• Browser access — deferred to Build. If any step's Data In references a web portal, CRM login, or authenticated website, flag it during step classification (Step 6) as a "requires browser access" note on that step. Do not ask about it here.

• Shareability — deferred to Build. The model asks about team sharing when generating artifacts in the Build phase, not during Design.

c. Present architecture analysis for confirmation

Present a single confirmation block:

"Here's what I found in your Workflow Definition:

• Platform: [confirmed platform]
• Tools needed: [extracted list]
• Trigger: [extracted trigger] → [implications for involvement mode]
• [Any flags: e.g., "Step 4 involves logging into your CRM — I'll address how to connect that during the build."]
• Context readiness: [count] of [total] context items are not directly AI-accessible. [Brief summary of gaps — may include structured data, documents, transcripts, or reference materials]. These gaps may affect step autonomy and will need resolution before or during Build.
• [Organizational lens: stakeholder implications — different platform access levels, notification needs for handoffs, shareability defaults to "yes"]

Integration availability on [platform] will be researched during the Build phase.

Anything I missed or got wrong?"

d. Downstream propagation — architecture decisions gate subsequent steps:

• No-code platform + no built-in connectors → cap at Skill-Powered Prompt
• Scheduled trigger + platform doesn't support unattended runs → flag infrastructure needed
• State which extracted facts influenced the autonomy assessment and orchestration mechanism recommendation

Step 4 — Autonomy Assessment

Before choosing an orchestration mechanism, assess where the whole workflow sits on the autonomy spectrum. This is the same spectrum used for per-step classification (Step 6), applied at the workflow level.

The autonomy spectrum:

Human ———— Deterministic ———————— Guided ———————— Autonomous
(human-performed)  (fixed path)       (bounded decisions)     (context-driven path)

| Level | Signals | Orchestration implications | |-------|---------|--------------------------| | Deterministic | Steps always execute in the same order, no branching on output quality, failure = stop or retry same step | Prompt or skill-powered prompt likely sufficient | | Guided | Some steps involve bounded AI judgment, human steers at checkpoints, sequence is mostly fixed but with bounded flexibility | Skill-powered prompt or agent | | Autonomous | Executor backtracks, re-invokes based on feedback, adjusts approach on failure, human checkpoints can redirect flow | Agent required |

Present as a confident assessment: "This workflow is [level] because [1-2 sentence reasoning]." If the user disagrees, discuss and adjust.

Step 5 — Orchestration Mechanism

Based on the autonomy assessment and architecture decisions, recommend who drives the workflow and how humans are involved. Analyze internally and present a confident recommendation — do NOT walk through decision questions.

Orchestration mechanism (who drives the workflow):

| Mechanism | Description | Signals | |-----------|-------------|---------| | Prompt | Human follows structured instructions step by step, all logic inline | Sequential steps, human provides inputs and makes decisions | | Skill-Powered Prompt | Human invokes reusable skills in a defined sequence | Repeatable sub-routines, moderate complexity, steps that recur across workflows | | Agent | Agent orchestrates the flow, invoking skills and making sequencing decisions | Tool use required, autonomous decisions, multi-step reasoning |

Single-agent vs. multi-agent is an architecture detail decided during Agent Configuration (Step 8) if "Agent" is selected — not a top-level choice here.

Human Involvement — Determine the involvement mode from architecture decisions and include it in the recommendation:

| Mode | Description | Determined by | |------|-------------|---------------| | Augmented | Human is in the loop — reviews, steers, or decides at key points during the run. | Web/desktop deployment, no scheduled execution | | Automated | AI runs solo — executes end-to-end without human involvement during the run. | Scheduled/unattended execution, CLI |

Platform sub-choice for agent mechanism: When the orchestration mechanism is Agent, the platform choice determines the implementation path. Some platforms have multiple agent offerings (e.g., Claude Code has sub-agents via markdown files vs. Claude Agent SDK in TypeScript/Python). If the platform has multiple agent offerings, ask the user which offering they want to use — this determines whether the Build phase generates markdown files, Python code, TypeScript code, or GUI configuration steps. For non-agent mechanisms (Prompt, Skill-Powered Prompt), no sub-choice is needed — artifacts are always markdown files.

Present as a confident recommendation: "Based on your workflow's [autonomy level] autonomy and [key architecture signals], I recommend [mechanism] with [involvement mode] because [2-3 sentence reasoning]." If the user pushes back, explain alternatives and discuss.

Ask the user to confirm the mechanism, involvement mode, and platform sub-choice (if applicable).

Fast-track for complete definitions: If the Workflow Definition + conversation context provide enough information to resolve ALL architecture dimensions, the autonomy level, AND the orchestration mechanism, present the entire Design analysis as a single confirmation block instead of stepping through questions one at a time.

For step-decomposed definitions:

"Based on your workflow definition, here's my design analysis:

• Platform: [platform] ([surface])
• Autonomy level: [level] — [brief rationale]
• Orchestration mechanism: [mechanism] ([involvement mode])
• Tools needed: [list — availability to be researched during Build]
• Steps classified: [summary table]
• Skill candidates: [list]
• Agent blueprints: [summary]

Does this look right, or would you like to adjust anything?"

For outcome-driven definitions:

"Based on your outcome-driven workflow definition, here's my design analysis:

• Platform: [platform] ([surface])
• Autonomy level: Autonomous (by definition — agent determines its own execution path)
• Orchestration mechanism: Agent ([involvement mode])
• Tools needed: [list — availability to be researched during Build]
• Capability domains mapped: [summary table]
• Skill candidates: [list]
• Agent blueprint: [summary]

Does this look right, or would you like to adjust anything?"

Only drop into the question-by-question flow when genuinely missing information.

Step 6 — Classify Each Step

For every refined step, classify across all three building-block layers plus autonomy and role.

Per-step classification dimensions:

• Autonomy level: Human / Deterministic / Guided / Autonomous — use only these four canonical terms. Previous terms like "Semi-Autonomous", "AI-Assist", "AI-Deterministic", or compound forms are retired per the Workflow Design Matrix.
• Orchestration layer: Prompt / Skill / Agent
• Integration layer: Which integration block(s) apply, with use/build tags
• Intelligence layer: Model capability, context sources, memory needs, project scope
• Human-in-the-loop gates: Where human review is recommended
• Role (organizational lens): Who performs this step — which role owns it

Integration layer blocks:

| Block | Description | Tag | |-------|-------------|-----| | MCP | Model Context Protocol server | Use existing / Build new | | API | REST, GraphQL, or other web API | Use existing | | SDK | Client library / framework | Use existing / Build new (rare) | | CLI | Command-line tool | Use existing |

Most integration blocks are "use existing." "Build new" applies primarily to MCP (custom data sources) and rarely to SDKs.

Intelligence layer blocks:

| Block | Description | Per-step classification | |-------|-------------|----------------------| | Model | Which model capability | Reasoning-heavy / Fast / Vision | | Context | Files, docs, libraries needed | List specific sources | | Memory | Persistent state across runs | Yes / No + what's stored | | Project | Workspace or project scope | Yes / No |

Per-step classification table format:

| Step | Orchestration | Integration (use/build) | Intelligence | Human Gate | |------|--------------|------------------------|--------------|------------| | Pull calendar events | Skill | MCP: Google Calendar (use) | Model: fast | No | | Generate coaching questions | Agent | — | Model: reasoning; Context: powerful-questions.md | Yes | | Save prep notes | Skill | CLI: git (use) | Model: fast | No |

Each row captures one step. The Orchestration column shows the block from that layer. The Integration column lists block(s) with use/build tags, or "—" if the step needs no external tool access. The Intelligence column lists applicable blocks with their per-step classification values.

Additionally, for each step record the autonomy level and role (these appear in the full spec output but are omitted from the compact table above for readability).

If a step's inputs include items flagged as "No" or "Partial" in the Context Shopping List, note this in the classification. A step classified as Autonomous but dependent on inaccessible data should be flagged: "Autonomy contingent on resolving data access for [item]."

Present the mapping as a clear table. Walk through reasoning for non-obvious classifications. Ask if the user wants to adjust anything.

Integration Discovery

After classifying every step, recommend available integration options for each tool need identified in the Integration layer. This helps students who don't know what CLIs, APIs, MCP servers, or SDKs exist for a given tool.

Discovery process (4-part chain):

1. Curated tool catalog — Fetch the curated-tools section from the remote platform registry JSON (https://raw.githubusercontent.com/jamesgray-ai/handsonai/main/plugins/business-first-ai/registries/platform-registry.json). Match workflow tool needs against each entry's integrations field. Curated tools are instructor-vetted recommendations — present them first, marked as recommended.

2. Model knowledge — Supplement with additional integration options the model knows about. For well-known integrations (Google Calendar, Gmail, Slack, GitHub, etc.), skip web search — model knowledge is sufficient.

3. Integration registries — Fetch the integration-registries list from the same remote registry JSON. For each cataloged source, search for integrations matching the tool need:

   {
     "integration-registries": [
       {
         "name": "Context7",
         "type": "mcp",
         "tool": "query-docs",
         "notes": "Library docs, API references, SDK docs via MCP"
       },
       {
         "name": "context-hub",
         "type": "local",
         "check": "context-hub --version",
         "notes": "Community-maintained integration registry (CLI)"
       },
       {
         "name": "MCP Registry",
         "type": "web-search",
         "url": "https://mcpregistry.dev",
         "notes": "MCP server directory"
       }
     ]
   }
   

   MCP tool availability: Before querying an MCP-type registry source (e.g., Context7), check the user's configured MCP servers. If the required MCP server is not configured, skip it and proceed to the next source in the chain.

4. Web search (validation + fallback) — For less common tools, when uncertain, or when no match is found in prior steps, search the web to verify existence and find current docs. Catches new releases and uncataloged tools. Batch searches when multiple tool needs are identified to avoid latency.

   Latency management: Use judgment about when web search adds value. Well-known integrations (Google Calendar, Gmail, Slack, GitHub) don't need validation searches. Reserve web search for new or niche tools.

   Precedence rule: When web search results contradict model knowledge (e.g., model proposes an MCP server that web search reveals was deprecated), web search takes precedence. Flag the discrepancy and present only verified options.

Matching semantics: Matching is model-driven, not exact string matching. The model reads the workflow's tool needs (e.g., "Google Calendar access" from the step classification) and matches them against the integrations array values (e.g., "google-calendar") using semantic understanding. This allows natural language tool needs to match standardized integration tags without requiring exact normalization.

Presentation format:

For step-decomposed: **[Tool] access needed (Steps N, M):** For outcome-driven: **[Tool] access needed (Domains: X, Y):**

[Tool] access needed ([Steps N, M / Domains: X, Y]):

Curated (recommended): | Block | Option | Trade-off | |-------|--------|-----------| | MCP | [Name] MCP | Easiest — plug-and-play | | CLI | [Name] CLI | Good for automation/scripting |

Also available: | Block | Option | Trade-off | |-------|--------|-----------| | API | [Name] REST API | Most flexible, more code | | SDK | [Name] Client Library | Best DX for code-heavy builds |

Recommendation: [block] for [rationale]

Step 6b — Skill Discovery

For every step classified as needing a Skill in Step 6, search for existing skills before assuming one needs to be built.

Search order:

1. Local skills — Search the user's own .claude/skills/, plugin skills directories, and any project-level skill directories. These are pre-vetted and can be recommended directly.

2. External registries — Fetch the skill-registries list from the remote platform registry:

   https://raw.githubusercontent.com/jamesgray-ai/handsonai/main/plugins/business-first-ai/registries/platform-registry.json

   The registry JSON is fetched once per session and cached. Both Skill Discovery (Step 6b) and Integration Discovery use the same cached copy.

   This provides a curated, always-current list of sites to search. For each registry, search for skills matching the step's requirements.

   {
     "skill-registries": [
       {
         "name": "skills.sh",
         "type": "web-search",
         "url": "https://skills.sh",
         "notes": "Community skill marketplace"
       },
       {
         "name": "Context7",
         "type": "mcp",
         "tool": "query-docs",
         "notes": "Library docs and skills via MCP"
       }
     ]
   }
   

   New registries are added by pushing to the JSON file — all users get them immediately, no plugin upgrade needed.

3. Web search fallback — If no match found in cataloged registries, or if the registry fetch fails, search the web for community skills that could fulfill the step. This also catches new skill registries not yet in the catalog.

4. User approval gate — Present all discovered skills as candidates, clearly separated into:

   • Local (pre-vetted): Skills the user already has installed. Can be included in the spec with a confirmation.
   • External (requires vetting): Community skills from registries or web search. Flag security implications — these run with the model's permissions and should be reviewed before adoption. User must explicitly approve each external skill candidate before it's included.

Presentation format:

For each step (or capability domain, for outcome-driven definitions) that needs a skill, present candidates in a table:

[Step 3 / Domain: Research] needs a skill: "Format coaching prep notes" | Source | Skill | Status | |--------|-------|--------| | Local | coaching-prep-notes-assembly (your plugin) | Pre-vetted — include? | | skills.sh | markdown-document-builder by @community | Requires review — [link] | | Web search | doc-formatter on GitHub | Requires review — [link] | | None found | Build new | Fallback |

External skills run with model permissions. Review source code before approving.

If no suitable existing skill is found for a step, tag that step as "build new" — it flows into Step 7 (Identify Skill Candidates).

Step 7 — Identify Skill Candidates

For steps where Skill Discovery (Step 6b) found an existing skill, skip to the next step.

This step only applies to steps tagged "build new" in Step 6b. Tag those steps that should become skills. For each skill candidate, document:

• Purpose (one sentence)
• Covers steps / domains (which step numbers or capability domains this skill spans)
• Inputs (what data the skill receives)
• Outputs (what the skill produces)
• Decision logic (key rules, criteria, frameworks)
• Failure modes (what happens when inputs are missing or unexpected)
• Required tools (which integration blocks the skill needs at runtime — e.g., MCP: Notion)
• Depends on (other skills or artifacts that must exist before this skill can function)

Step 8 — Agent Configuration

(When orchestration mechanism is Agent.) For each agent the workflow needs, document:

| Component | What to specify | |-----------|----------------| | Name | Unique agent name | | Purpose | When this agent should be invoked (trigger conditions) | | Instructions | Mission, responsibilities, behavior, goals, tone & style, output format | | Model | Recommended capability tier: reasoning-heavy / fast / vision | | Tools | External tools the agent needs (from Integration Options) | | Skills | Which skill candidates this agent should have access to | | Trigger Examples | 2-3 example scenarios showing when/how the agent is invoked |

The build skill maps these to platform-specific fields at runtime (e.g., "reasoning-heavy" → opus on Claude Code, trigger examples → <example> blocks).

For multi-agent: orchestration pattern, agent handoffs, human review gates.

Step 8b — Evaluation Criteria

Before generating the spec, gather evaluation criteria from the user. These feed directly into Step 5 (Test) where the workflow is evaluated against them, and Step 7 (Improve) where iteration decisions reference the quality bar established here.

For step-decomposed definitions:

Prompt the user:

"Before generating the spec, I need to understand what good output looks like for this workflow. This feeds directly into Step 5 (Test) where you'll evaluate the workflow against these criteria."

Then ask these four questions, one at a time:

1. "Describe what a great output from this workflow looks like — not format, but quality. What would make you say 'this is exactly right'?"
2. "Which dimensions matter most? For example: accuracy, completeness, tone, specificity, timeliness, format consistency."
3. "Give me 3-5 real or realistic scenarios you'd run this on — different enough to test the workflow's range. For each, briefly describe the input and what you'd look for in the output."
4. "What's your minimum bar? What quality level is acceptable vs. needs more work?"

Capture the answers for the Evaluation Criteria section of the spec.

For outcome-driven definitions:

The Workflow Definition already includes Quality Criteria from the Deconstruct interview. Carry these forward rather than asking from scratch:

"Your Workflow Definition includes these quality criteria: [list from definition]. These feed directly into Step 5 (Test). Anything to add or adjust?"

Then ask only the supplementary questions not already covered:

• If test scenarios are missing: "Give me 3-5 real or realistic scenarios you'd run this on."
• If minimum bar is missing: "What's your minimum bar? What quality level is acceptable vs. needs more work?"

Step 9 — Generate AI Building Block Spec

Write to outputs/[workflow-name]-building-block-spec.md using the template below. Every section is mandatory unless marked (optional). Do not add, remove, rename, or reorder sections.

Before writing, run the Build Skill Needs Checklist (at the end of this step) to verify all required data has been captured.

---

Template:

# [Workflow Name] — AI Building Block Spec

## Execution Pattern

**[Mechanism]** — [1-2 sentence rationale for why this mechanism was chosen over alternatives].

## Architecture Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Lens | Individual / Organizational | [reason] |
| Platform | [name] | [reason] |
| Platform Mode | code / guided | [inferred from platform or confirmed] |
| Orchestration | Prompt / Skill-Powered Prompt / Agent | [reason] |
| Involvement | Augmented / Automated | [reason] |
| Trigger | [trigger description] | [implications for involvement, infrastructure] |

## Scenario Summary

| Field | Value |
|---|---|
| **Workflow Name** | [name] |
| **Description** | [full description] |
| **Outcome** | [what a successful run produces] |
| **Trigger** | [when/how it starts] |
| **Type** | Augmented / Automated |
| **Business Process** | [functional category] |
| **Owner** | [person or role] |

## Step-by-Step Decomposition

| Step | Name | Phase | Autonomy | Orchestration | Integration (use/build) | Intelligence | Skill Candidate? | Human Gate? |
|------|------|-------|----------|---------------|------------------------|--------------|-------------------|-------------|

Column definitions:
- **Autonomy**: Human / Deterministic / Guided / Autonomous (canonical terms only)
- **Orchestration**: Prompt / Skill / Agent
- **Integration**: Block + tool + action tag (e.g., "MCP: Notion (use)") or "—" if none
- **Intelligence**: Model class + context sources + memory flag (e.g., "Model: fast" or "Model: reasoning; Context: pillar-definitions")
- **Skill Candidate?**: Skill name (if new), "Exists: [name]" (if pre-built), or "No"
- **Human Gate?**: Yes / No

### Autonomy Spectrum Summary

Group steps by autonomy level. For each group, explain WHY those steps have that classification.

## Skill Candidates

For each skill candidate (steps tagged with a new skill name above):

### [skill-name] (Step N)

| Dimension | Detail |
|---|---|
| **Purpose** | [one sentence] |
| **Covers Steps / Domains** | [list of step numbers, or capability domain names for outcome-driven] |
| **Inputs** | [name (type, default)] |
| **Outputs** | [what the skill produces] |
| **Decision Logic** | [key rules, criteria, evaluation frameworks — multiline OK] |
| **Failure Modes** | [condition → action, one per line] |
| **Required Tools** | [block: tool (action) — e.g., MCP: Notion (use)] |
| **Depends On** | [other skills or artifacts that must exist first, or "None"] |

## Agent Configuration (optional — only when orchestration = Agent)

For each agent:

### [agent-name]

| Component | Detail |
|---|---|
| **Name** | [lowercase-hyphenated] |
| **Purpose** | [when this agent should be invoked] |
| **Instructions** | [mission, responsibilities, behavior, goals, tone, output format] |
| **Model** | [capability tier: reasoning-heavy / fast / vision] |
| **Tools** | [external tools needed, from Integration Options] |
| **Skills** | [skill candidates this agent should have access to] |
| **Trigger Examples** | [2-3 scenarios: situation → user message → agent response] |

For multi-agent: orchestration pattern, agent handoffs, human review gates.

## Step Sequence and Dependencies

\`\`\`
[ASCII diagram showing parallel and sequential paths]
\`\`\`

**Parallel:** [which steps can run concurrently]
**Sequential:** [which steps must run in order]
**Critical path:** [longest dependency chain]

## Prerequisites

1. [Numbered list of requirements that must be in place before the workflow can run]

## Context Inventory

| # | Artifact | Type | Used By | Status | Location | Key Contents |
|---|---|---|---|---|---|---|

Column definitions:
- **Type**: MCP Data Source / Context / External
- **Status**: Exists / Create
- **Location**: File path, URL, database name, or "Create as [path]" / "Create inline in prompt"

## Data Readiness Summary

Items NOT fully AI-accessible. If all items are accessible, state: "All context items are AI-accessible. No data readiness actions required."

| Context Item | Current State | Required Action | Affects Steps |
|---|---|---|---|
| [item] | AI-Accessible / Partial / No | [action needed] | [step numbers] |

## Integration Options

For each tool identified in the Integration column of the Step-by-Step Decomposition (or Capability Domain Mapping for outcome-driven):

### [Tool Name] (Steps N, M / Domains: X, Y)

**Curated (recommended):**

| Block | Option | Source URL | Trade-off |
|-------|--------|-----------|-----------|
| [MCP/API/SDK/CLI] | [name] | [URL] | [trade-off] |

**Also available:**

| Block | Option | Source URL | Trade-off |
|-------|--------|-----------|-----------|
| [MCP/API/SDK/CLI] | [name] | [URL] | [trade-off] |

*Recommendation: [block] for [rationale]*

## Model Recommendation

**Default:** [reasoning-heavy / fast / vision] — [rationale]

**Per-step overrides** (optional):
- Steps N, M: [different model class] — [rationale]

## Recommended Implementation Order

### Quick Wins (implement first)
1. **[name]** — [rationale]

### Core (implement second)
1. **[name]** — [rationale]

### Future Enhancement (optional)
1. **[name]** — [rationale]

## Where to Run

**[Platform]** with [setup requirements]. [Recommendation for frequent use.]

## Evaluation Criteria

### What good output looks like
[Concrete description in plain language — what would make you say "this is exactly right"?]

### Quality dimensions
[Which dimensions matter for this workflow — e.g., accuracy, completeness, tone, format, timeliness, specificity]

### Test scenarios
[3-5 representative inputs that exercise the workflow's range — real or realistic examples]

| # | Scenario | Input description | What to look for |
|---|----------|-------------------|------------------|

### Minimum quality bar
[What's acceptable vs. what needs iteration — in plain terms, not a numeric threshold]

## Stakeholders (optional — only for Organizational lens)

[Role swimlane diagram and stakeholder details]

---

Build Skill Needs Checklist

Before saving the spec, verify every item. If any is missing, go back and add it:

• [ ] Architecture Decisions table has Platform, Platform Mode, Orchestration, and Involvement rows
• [ ] Every step in the decomposition table has separate Orchestration, Integration, and Intelligence columns (not collapsed into a single "Building Block(s)" column)
• [ ] Every step uses canonical autonomy terms: Human / Deterministic / Guided / Autonomous
• [ ] Every Integration column entry includes the block type, tool name, and use/build tag
• [ ] Every skill candidate has all 8 fields: Purpose, Covers Steps, Inputs, Outputs, Decision Logic, Failure Modes, Required Tools, Depends On
• [ ] Every "Exists" item in Context Inventory has a Location value
• [ ] Every tool in the Integration column has a matching entry in Integration Options with at least one Source URL
• [ ] Model Recommendation section is present with a default class
• [ ] Data Readiness Summary is present (even if "all accessible")
• [ ] Agent Configuration is present if orchestration = Agent (with Skills and Trigger Examples fields)
• [ ] Evaluation Criteria section is present with at least 3 test scenarios

Step 10 — Spec Approval Gate

This is a hard gate. Do not proceed without explicit approval.

Present a summary of the Building Block Spec:

"Here's the Building Block Spec summary:

• Autonomy: [level] (for outcome-driven: Autonomous)
• Mechanism: [orchestration mechanism] ([involvement mode])
• Structure: [count] steps, [count] skill candidates, [count] agents (for outcome-driven: [count] capability domains, [count] skill candidates, [count] agents)
• Integration options: [count] tools with recommended integration approaches
• Implementation order: [brief summary]

The full spec is saved to outputs/[workflow-name]-building-block-spec.md.

Do you approve this spec? I won't generate any artifacts until you confirm. If you want changes, tell me what to adjust and I'll revise."

Loop if the user requests changes — revise the spec and re-present for approval.

After the user approves, instruct them to exit plan mode if they entered it at the start of Design:

"Spec approved. Exit plan mode now (in Claude Code: shift+tab or /plan) so artifacts can be generated in the Build phase."

"To build the workflow, run /business-first-ai:build (or say 'Build the workflow from my Building Block Spec')."

Outcome-Driven Processing Path

When the Workflow Definition has Definition Type: Outcome-Driven, the following modifications apply to the standard workflow:

Step 3 (Architecture Decisions): Same as standard — extract tools from the Capability Domains and Tools/Data sections instead of from step data flows.

Step 4 (Autonomy Assessment): State as fact: "This is an outcome-driven workflow — autonomy is Autonomous by definition. The agent system determines its own execution path."

Step 5 (Orchestration Mechanism): State as fact: "Orchestration is Agent." Still determine the involvement mode (Augmented/Automated) from the definition's Human Gates section and trigger type. Still ask the platform sub-choice if the platform has multiple agent offerings.

Step 6 (Classify Each Step) → Capability Domain Mapping: Replace per-step classification with capability domain mapping. For each capability domain from the definition:

| Domain | Integration Needs | Intelligence Requirements | Reusable Skill? | |--------|-------------------|--------------------------|-----------------| | [domain] | Tools/connectors needed | Model class, context sources | Yes/No + rationale |

Same Integration Discovery and Skill Discovery processes apply, operating on capability domains instead of steps.

Step 7 (Skill Candidates): Same — identify which capability domains should become skills.

Step 8 (Agent Configuration): This becomes the primary section. Agent Configuration is mandatory for outcome-driven definitions. Document the agent(s) with all standard fields, drawing instructions from the definition's Goal, Constraints, and Expected Outputs.

Step 8b (Evaluation Criteria): Carry forward from the definition's Quality Criteria — see above.

Step 9 (Generate Spec): Use the modified template sections below. The spec uses the same filename pattern. Conditional sections replace Step-by-Step Decomposition with Capability Domain Mapping, and Autonomy Spectrum Summary with a brief Autonomous statement.

Outcome-driven spec template modifications:

Replace the ## Step-by-Step Decomposition section with:

## Capability Domain Mapping

| Domain | Description | Integration (use/build) | Intelligence | Reusable Skill? |
|--------|-------------|------------------------|--------------|-----------------|

### Autonomy Statement

This is an outcome-driven workflow. Autonomy is Autonomous — the agent system determines its own execution path based on the goal, inputs, and constraints.

Replace the ## Skill Candidates section header with capability-domain-based skill candidates (same field structure, keyed by domain instead of step number).

The ## Agent Configuration section is mandatory (not optional) for outcome-driven specs.

All other spec sections remain the same, except Step Sequence and Dependencies is omitted for outcome-driven specs — the agent determines its own execution path, so there is no fixed step sequence to document.

Build Skill Needs Checklist modifications for outcome-driven:

• [ ] Architecture Decisions table has Platform, Platform Mode, Orchestration (Agent), and Involvement rows
• [ ] Capability Domain Mapping table is present with Integration and Intelligence columns
• [ ] Every Integration column entry includes block type, tool name, and use/build tag
• [ ] Every skill candidate has all 8 fields: Purpose, Covers Steps / Domains, Inputs, Outputs, Decision Logic, Failure Modes, Required Tools, Depends On
• [ ] Every "Exists" item in Context Inventory has a Location value
• [ ] Every tool in the Integration column has a matching entry in Integration Options with at least one Source URL
• [ ] Model Recommendation section is present with a default class
• [ ] Data Readiness Summary is present (even if "all accessible")
• [ ] Agent Configuration is present with Skills and Trigger Examples fields
• [ ] Evaluation Criteria section is present with at least 3 test scenarios
• [ ] Quality criteria carried forward from Workflow Definition

Outputs

outputs/[workflow-name]-building-block-spec.md — AI Building Block Spec

Uses the mandatory template defined in Step 9. For step-decomposed definitions: Execution Pattern, Architecture Decisions, Scenario Summary, Step-by-Step Decomposition (with separate Orchestration/Integration/Intelligence columns), Autonomy Spectrum Summary, Skill Candidates (8 fields each), Agent Configuration (optional, with Skills and Trigger Examples), Step Sequence and Dependencies, Prerequisites, Context Inventory (with Location column), Data Readiness Summary, Integration Options (with Source URLs), Model Recommendation, Recommended Implementation Order, Where to Run, Evaluation Criteria (with test scenarios), Stakeholders (optional).

For outcome-driven definitions: Execution Pattern, Architecture Decisions, Scenario Summary, Capability Domain Mapping (with Integration/Intelligence columns), Autonomy Statement, Skill Candidates (8 fields each, keyed by domain), Agent Configuration (mandatory, with Skills and Trigger Examples), Prerequisites, Context Inventory, Data Readiness Summary, Integration Options, Model Recommendation, Recommended Implementation Order, Where to Run, Evaluation Criteria (with test scenarios carried forward from definition), Stakeholders (optional).

Guidelines

• Use plain language; avoid jargon unless the user introduced it
• After writing the spec, tell the user: "AI Building Block Spec saved to outputs/[name]-building-block-spec.md."
• Do not proceed past the Spec Approval Gate (Step 10) without explicit user approval
• Do not research integration availability — that happens in the Build phase
• Do not generate platform artifacts — that happens in the Build phase