AI Workflow Framework

The Problem

Most AI adoption starts with the technology — “we have ChatGPT, where should we use it?” This leads to shallow adoption and misses the workflows where AI creates real leverage. And even when people identify the right workflow, there’s a gap between the idea and making it real — without a repeatable process to follow, they get stuck and stop. The AI Workflow Framework closes that gap: audit your workflows, identify where AI creates the most value, deconstruct those workflows into building blocks, design the architecture, build the components, test them, deploy, and improve over time.

How It Works

The framework is facilitated by seven skills — reusable AI routines that guide you through each step interactively. You don’t need to figure out the right questions to ask or remember the methodology — the skill drives the conversation, probes for details, and produces structured outputs you carry to the next step. You bring the domain knowledge about your work; the AI handles the process.

Step	Skill	What it guides you through
1. Analyze	`analyze`	Identify and prioritize the workflows worth reimagining with AI
2. Deconstruct	`deconstruct`	Map the workflow’s process — or define the goal for an agent system
3. Design	`design`	Architect how AI building blocks will power your workflow
4. Build	`build`	Build the AI building blocks your design specifies
5. Test	`test`	Test your workflow’s output quality and fix what’s not working
6. Run	`run`	Deploy and operationalize your workflow
7. Improve	`improve`	Monitor quality and innovate your workflow over time

Get the skills: See Set Up the Skills for installation instructions across Claude (Chat, Cowork, Code), ChatGPT and Codex, Google Gemini (Spark, Enterprise, CLI), M365 Copilot, Cursor, and more. The plugin name is handsonai.

Run It All at Once: framework-agent

You can run all seven skills step-by-step in separate conversations, or use the framework-agent to orchestrate the full lifecycle end-to-end in a single session.

What it does: Runs the seven skills sequentially — Analyze, Deconstruct, Design, Build, Test, Run, Improve — with file-based handoffs between stages. The agent manages the flow between steps, saves intermediate files to outputs/, and keeps you involved at each stage.

When to use it: Use the agent when you want to go through the entire process in one session. If you prefer to work step-by-step across separate conversations — or want to run a single step standalone (e.g., just Deconstruct, just Improve) — invoke the individual skills instead. Both styles produce the same artifacts.

Example prompts:

"I want to deconstruct my client onboarding workflow"
→ Walks you through all seven steps, asking questions during
  discovery, presenting the analysis for review, and generating
  the build deliverables

"People keep dropping off during enrollment. Help me build
a workflow for that."
→ Starts from a problem description, proposes a candidate
  workflow, then deconstructs and designs it

"Help me figure out which parts of my weekly reporting process
could be automated with AI"
→ Decomposes the reporting process, assesses autonomy, chooses
  an orchestration mechanism, and identifies quick wins

What you’ll get — each workflow gets its own folder under outputs/, named with the workflow name in lowercase using hyphens (for example, outputs/client-onboarding/). Analyze registers each candidate as a backlog Workflow node in your registry/ bundle; every later step updates it — status, mode, and review date in one place — so any session can resume mid-framework by reading the node and seeing which artifacts already exist:

Opportunity Report — outputs/ai-opportunity-report.md (before a workflow is named)
Workflow Requirements — [name]/requirements.md
Design Spec — [name]/design-spec.md
Platform Artifacts — prompts, skills, agents, and configs in the format your platform requires
Test Results — [name]/test-results.md
Run Card — [name]/run-guide.md, plus a run log at [name]/runs.md
Improvement Plan — [name]/improvement-plan.md (when running Improve)

The Framework

Seven steps, each building on the last:

Step 1: Analyze Workflows

Find which workflows are candidates for AI.

Before you can apply AI to anything, you need to know where it fits. Step 1 is a structured audit of your workflows that produces a prioritized list of opportunities classified on two dimensions:

Autonomy — How much decision-making does the AI have? Deterministic (follows fixed rules), Guided (makes bounded decisions within guardrails), or Autonomous (plans and adapts independently)
Human Involvement — Is a human in the loop during execution? Augmented (human reviews and steers) or Automated (AI runs solo)

The audit starts by reading your registry and what the AI already knows about your work, asks which lens to use, then interviews you with lens-specific questions to fill gaps, and produces a classified report with specific opportunities and actionable first steps.

Deliverable: Opportunity Report (outputs/ai-opportunity-report.md) — prioritized opportunities with a Workflow Candidate Summary listing the workflows you’ve chosen to pursue — and one status: backlog Workflow node per chosen candidate in your registry.

Facilitated by the analyze skill. See Analyze Workflows for details and Set Up the Skills for installation on any supported platform.

Step 2: Deconstruct Workflows

Define what the business process does — every step, decision, and handoff — before deciding how to implement it with AI.

Step 2 is the Product Requirements Document (PRD) for your workflow — clear requirements, decision rules, and edge cases that feed directly into Design. There are two paths, chosen by one question at the start: do you know the steps, or just the goal?

Step-driven — You can describe how the work gets done. The model interviews you to refine the steps and surface decision rules, edge cases, and the context each step needs. Each step is captured as Goal / Inputs / Outputs / Rules & Edge Cases / Context.
Goal-driven — You know what “done” looks like, but the work takes different steps depending on what comes in, so you give an agent system a goal and let it figure out the steps at runtime. The model captures the goal, inputs, acceptance criteria, rules, and constraints — without prescribing steps.

Don’t have either yet? Describe the problem you’re trying to solve. The model proposes a candidate workflow and routes you into one of the two paths above.

For step-driven workflows, the model uses the six-question framework as the interview structure to identify what belongs in each step’s requirements block:

Is this step actually multiple steps bundled together?
Are there decision points, branches, or quality gates?
What data flows in and out?
What context, documents, or reference materials does this step need?
What happens when this step fails?
Can the AI access, interpret, and persist the data this step needs?

Two questions run alongside the mapping, whichever path you took:

What is this worth, and how would you know? The business objective it supports, the outcome that changes, what you’d count, and what that number is today. Without today’s number there is nothing to compare the improvement against — and if nobody knows it, the requirements say so plainly rather than guessing.
What must it protect? Where data may travel, who may see the output, what has to be recorded, what the workflow must never do, and which regulation applies. Most workflows need none of this and finish the section in a line; the skill works out which case you’re in from what it already knows about your context, rather than making you fill in a form.

This is purely the what — the workflow’s requirements, with no prescription of how AI will handle it. The how comes in Step 3 (Design).

Deliverable: Workflow Requirements (outputs/[name]/requirements.md) — a PRD-style document. Every Workflow Requirements file contains: Goal, Value & Measurement, Metadata, Context Inventory, Acceptance Criteria, Example Scenarios, Rules & Constraints, Human Gates, and Security, Privacy & Safety. Step-driven workflows add a Steps Overview with per-step requirements; goal-driven workflows add Inputs.

Facilitated by the deconstruct skill. See Deconstruct Workflows for details and Set Up the Skills for installation on any supported platform.

Step 3: Design Your AI Workflow

Decide how the workflow should be built — before you build it.

The Design step takes your Workflow Requirements and produces a complete blueprint for your AI workflow. The skill works through three layers of decisions:

Architecture — confirm your platform, assess the workflow’s autonomy level (Deterministic, Guided, or Autonomous), and recommend how it runs — as a Skill or an Agent (the mechanism is one of Skill | Agent) — with an involvement mode (Augmented or Automated).
Decomposition — classify each step on the autonomy spectrum, map AI building blocks, and identify which steps become reusable skills.
Component blueprints — document the field-level specs for each new skill and agent.

The skill writes the spec as a draft file you can read, then marks it approved when you say so; Build refuses an unapproved spec.

Deliverable: Design Spec (outputs/[name]/design-spec.md) — architecture decisions, autonomy assessment, orchestration mechanism, per-step classifications, skill candidates, agent blueprints, integration options, model recommendation, Data Readiness Summary, implementation order, and a Constraint Conformance table showing, for each protection named in Deconstruct, where the design meets it. References the Workflow Requirements rather than restating it.

Facilitated by the design skill. See Design Your AI Workflow for the full guide with autonomy assessment, orchestration mechanism decision flow, and output format.

Step 4: Build the Components

Generate platform-appropriate artifacts from the approved spec.

The Build step starts with a Prepare Context phase — systematically resolving the context needs identified during Deconstruct and Design. Then the model researches your platform using the platform registry and web search to generate the actual artifacts — context, skills, prompts, agents, MCP connections — in whatever format your platform requires. Only the components your orchestration mechanism needs are built.

Deliverable: Platform artifacts — skills, agents, and configs generated for your specific platform, plus resolved context artifacts (style guides, reference materials, examples).

Facilitated by the build skill. See Build for the Prepare Context phase and platform research details.

Step 5: Test the Workflow

Structured testing against the Acceptance Criteria and Example Scenarios captured in the Workflow Requirements.

Your first run is a test, not a deployment. The Test step walks you through a quick smoke test (does it run at all?), then a full round where you run each Example Scenario from the Workflow Requirements in a fresh conversation and grade the output against your acceptance criteria — every line is met or not met, with evidence. When a line misses, you isolate the building block that caused it. The round that passes becomes your baseline for future comparison.

Most workflows need 2-4 iterations between Build and Test before they produce reliably good output. When something is off, the skill helps you diagnose which building block to fix and sends you back to Build with a clear target.

Deliverable: Test Results (outputs/[name]/test-results.md) — a report card per scenario (each criterion met or not met, with evidence), the diagnosed building block for every miss, and a readiness verdict.

Facilitated by the test skill. See Test for the full evaluation process and troubleshooting guide.

Step 6: Run the Workflow

Deploy and operate your tested workflow.

Once your workflow passes testing, Run puts it into production: you do the first real run on real work with the model watching, and it leaves behind a one-page Run Card — how to start it, what to have ready, what to check before you act on the output — plus a run log and a review date. Scheduling is covered only for workflows designed as Automated. For organizational workflows, Run also covers sharing with your team and setting up ongoing operations.

Deliverable: Run Card (outputs/[name]/run-guide.md) — six fixed sections: your first real run, how to start it, what to have ready, what to check before you act on the output, log the run, and your first review.

Facilitated by the run skill. See Run for run patterns, deployment options, and operationalization guidance.

Step 7: Improve Over Time

Evaluate and evolve running workflows.

Workflows are not something you set up once and forget. Over time, business context changes, new tools become available, and output quality can drift. The Improve step teaches you when and how to revisit a running workflow — watch for quality signals, re-run your report card to see which lines changed, and decide whether the workflow has outgrown its mechanism. Three outcomes: no changes needed, tune it, or go back to Design.

Deliverable: Improvement Plan (outputs/[name]/improvement-plan.md) — which report-card lines changed since the baseline, quality signals, graduation assessment, decision outcome, and specific next actions.

Facilitated by the improve skill. See Improve for the full evaluation and graduation framework.

Key Concepts

Every term, in plain language: Framework Glossary. Quick reference for the core vocabulary:

AI Workflow Design Matrix

Every AI workflow is classified on two dimensions — autonomy and human involvement — producing six archetypes. See the AI Workflow Design Matrix for the full 3x2 matrix with descriptions, examples, and guidance on choosing the right archetype.

Autonomy	Description	Example
Deterministic	AI follows fixed rules — no decisions, no judgment	Formatting reports, processing forms
Guided	AI makes bounded decisions within guardrails	Co-writing, brainstorming, research summaries
Autonomous	AI plans, decides, and adapts independently	Competitor monitoring, research → report pipelines

Involvement	Description
Augmented	Human is in the loop — reviews, steers, or decides at key points
Automated	AI runs solo — human reviews only the final output

Six-Question Framework

Used to decompose each step in a step-driven workflow:

Discrete steps — Is this one step or multiple bundled together?
Decision points — Any if/then branches, quality gates, or judgment calls?
Data flows — What goes in? What comes out? Where from and where to?
Context needs — What documents, files, or reference materials are required?
Failure modes — What happens when this step fails?
Data readiness — Can the AI access, interpret, and persist the data this step needs?

AI Building Blocks

Each workflow step gets mapped to one or more building blocks across three layers — Intelligence (Model, Context, Memory, Project), Orchestration (Prompt, Skill, Agent), and Integration (MCP, API, SDK, CLI). See Agentic Building Blocks for definitions, examples, and cross-platform comparisons.

Six Use Case Primitives

When classifying opportunities from Step 1, it helps to know what type of AI work each one involves. The six use case primitives — Content Creation, Research, Coding, Data Analysis, Ideation & Strategy, and Automation — provide a classification system for the opportunities you identify.

Autonomy Spectrum

Used to classify each workflow step during Design:

Level	Description
Human	Requires human judgment, creativity, or physical action
Deterministic	Follows fixed rules; AI executes reliably with no decisions
Guided	AI makes bounded decisions within guardrails; human reviews at key checkpoints
Autonomous	AI plans and executes end-to-end, including decisions and tool use

The same scale describes the whole workflow during Design’s autonomy assessment — with one difference: Human appears only at the step level (a whole workflow that’s entirely human needs no AI design), so the workflow-level scale runs Deterministic → Guided → Autonomous.

Orchestration Mechanism

The orchestration mechanism answers: who drives the workflow? The right mechanism depends on the workflow’s autonomy level and what it actually needs:

Mechanism	Description	Signals
Skill	You start it by name; it follows the mapped steps, pausing where you said	You trigger the work; same steps each time; decisions are yours at the pauses
Agent	Decides its own path at runtime, uses tools on its judgment, can run unattended	Steps depend on what it finds; scheduled or hands-off runs

Single-agent vs. multi-agent is an architecture detail decided during agent configuration — not a top-level choice.

Getting Started

Analyze Workflows — identify your best AI candidates
Deconstruct the workflow — break it into discrete steps
Design your AI workflow — assess autonomy, choose an orchestration mechanism, classify steps, map building blocks
Build the components your orchestration mechanism requires
Test your workflow against your acceptance criteria and establish a baseline
Run — do the first real run, leave a Run Card and run log, and operationalize
Improve — periodically re-check, catch drift, and decide what to change

Set up your registry first. The framework records every workflow you find and build in your AI Registry — about 25 minutes, once. Analyze reads it so you never describe your business twice, and writes your candidates into it.
See the destination first. The worked example shows every file a complete run produces — the whole project folder for one small workflow taken through all seven steps.
Start small. Make your first workflow starter-sized: 3–5 steps, one tool connection, triggered manually. Build your big opportunity second, once you’ve been through the loop.
Pausing is safe. Every step saves progress to files. In any later session, just say “continue my workflow” — the framework reads your registry’s Workflow node and picks up at the right step.
Plan about a working day, over three to four sessions, for a starter workflow through Steps 1–6 (Improve comes weeks later, at your review date): Analyze 15–20 min, Deconstruct 45–60, Design about 30, Build 30–60, Test about 45 per round (two to four rounds), Run 15–20.

FAQ

Which step should I start with? Start with Step 1 (Analyze) if you’re not sure where AI fits in your work. Browse AI Use Cases to see what types of work AI handles — content creation, research, coding, data analysis, ideation, and automation. Start with Step 2 (Deconstruct) if you already know which workflow you want to automate.

Can I start from a problem instead of a workflow? Yes. Tell the framework-agent about your problem (e.g., “people keep dropping off during enrollment”) and it will propose a candidate workflow for you to refine during discovery. The individual deconstruct skill can do the same.

How many iterations of Build-Test should I expect? Most workflows need 2–4 rounds of Build and Test before they produce reliably good output. Each iteration should be targeted — fix a specific building block, re-test, and measure improvement. If you have been through four iterations and scores are not improving, return to Design (Step 3) to re-examine your architecture decisions.

Where are the example agents and prompts? They’re in the AI Workflow Examples collection — agents for executive writing, editorial review, research, meeting prep, and AI news.

For setup-specific questions (which platforms support the skills, how to handle losing context mid-conversation), see the FAQ on the Set Up the Skills page.