ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/docs/learn/module-14-agentic-development/tutorial-14.md

8.2 KiB
Raw Blame History

Tutorial 14: Your First Agentic Session

Hands-on guide to running a complete agentic development loop

Overview

This tutorial walks you through a complete agentic development session — creating an Agent Dialog, building from specification, evaluating results, and handling a stuck moment.

Time: 45-60 minutes Prerequisites: Design system completed (Module 13) Agent: Idunn (or Freya for design exploration) What you'll create: Working prototype with documented Agent Dialog

Before You Start

You'll need:

  • A page specification from your project
  • Your design tokens (if applicable)
  • Access to your AI coding assistant

The agent will help you:

  • Create the Agent Dialog
  • Build step by step
  • Track decisions
  • Handle problems

Step 1: Start the Agent Dialog (5 min)

Give the agent your specification:

You say:

"I want to build a working prototype of the signup form from spec P02-signup-form.md. Start by creating an Agent Dialog with scope, tasks, requirements, and test protocol."

The agent creates the dialog:

# Agent Dialog: Signup Form Prototype

## Meta
- Date: 2026-02-10
- Input: P02-signup-form.md
- Agent: Idunn
- Status: In Progress

## Scope
Build the signup form as a working HTML/CSS prototype.
Includes: form layout, validation states, error states, loading state.
Excludes: backend integration, actual form submission.

## Tasks
1. [ ] Create form layout with all fields
2. [ ] Style with design tokens
3. [ ] Add validation behavior
4. [ ] Implement error states
5. [ ] Add loading state on submit
6. [ ] Responsive adjustments
7. [ ] Accessibility check

## Requirements
- Match specification P02 exactly
- Inter font, primary #0066FF
- Mobile-first, max-width 400px
- WCAG AA contrast compliance
- All states from spec must be present

## Test Protocol
- [ ] All text matches spec word-for-word
- [ ] Form renders correctly on mobile
- [ ] Tab navigation reaches all fields
- [ ] Error messages appear on blur
- [ ] Loading spinner shows on submit
- [ ] Touch targets 44px minimum

Review the plan. Does it cover everything? Adjust before proceeding.

Step 2: Execute First Step (5 min)

Build the form layout:

The agent builds:

<div class="signup-form">
  <h1>Start in 2 minutes</h1>
  <p class="subheadline">No credit card required. Cancel anytime.</p>
  <form>
    <div class="form-field">
      <label for="email">Email</label>
      <input type="email" id="email" placeholder="you@example.com">
    </div>
    <div class="form-field">
      <label for="password">Password</label>
      <input type="password" id="password">
      <span class="helper">At least 8 characters</span>
    </div>
    <button type="submit">Create Free Account</button>
  </form>
  <p class="terms">By continuing, you agree to our Terms and Privacy Policy</p>
  <p class="login-link">Already have an account? Log in</p>
</div>

The agent logs the step:

## Log

### Step 1: Form layout (completed)
- Created semantic HTML form structure
- All elements from spec present
- Decision: Used form-field wrapper for consistent spacing

Step 3: Evaluate and Give Feedback (5 min)

Compare to spec:

Check each element:

Element Spec Output Status
Headline "Start in 2 minutes" Match Pass
Subheadline "No credit card..." Match Pass
Email field With placeholder Present Pass
Password field With helper text Present Pass
Submit button "Create Free Account" Match Pass
Terms text Present Present Pass
Login link Present Present Pass

Give feedback:

"Layout looks correct. All elements match spec. One issue: the password field is missing the show/hide toggle from the spec. Add that before moving to step 2."

Agent fixes and updates log:

### Step 1: Form layout (completed, revised)
- Added password show/hide toggle
- All elements from spec now present

Step 4: Continue Building (15 min)

Execute steps 2-5:

Work through each step in the plan:

Step 2: Styling

"Apply the design tokens. Primary #0066FF, Inter font, 16px base, 8px spacing scale."

Evaluate: Does it match the visual direction? Adjust tokens if needed.

Step 3: Validation

"Add blur-based validation. Email: check format. Password: check 8+ characters."

Evaluate: Does validation trigger correctly? Are messages clear?

Step 4: Error states

"Add error states per spec: red border, error message below field."

Evaluate: Do errors show and clear correctly?

Step 5: Loading

"Add loading spinner on submit. Disable button and fields during load."

Evaluate: Is the loading state clear? Can the user still interact with anything they shouldn't?

Step 5: Handle a Stuck Moment (5 min)

A common issue:

The loading spinner shows, but the button text doesn't change. You ask the agent to fix it. It changes the button text but now the spinner disappears.

Recognize the loop. You've gone back and forth twice.

Apply the strategy:

"Let's approach this differently. I want both: the spinner AND the text 'Creating account...' inside the button. Here's the exact HTML I want:

<button disabled>
  <span class="spinner"></span>
  Creating account...
</button>

Make the spinner 16px, inline with the text, with 8px gap."

Concrete example breaks the loop.

Step 6: Update the Plan (3 min)

Review and adjust:

After building, your plan has evolved:

## Tasks
1. [x] Create form layout with all fields
2. [x] Style with design tokens
3. [x] Add validation behavior
4. [x] Implement error states
5. [x] Add loading state on submit
6. [ ] Fix password toggle animation       ← ADDED (toggle feels sluggish)
7. [ ] Responsive adjustments
8. [ ] Accessibility check

New task emerged from building. That's normal.

Step 7: Run the Test Protocol (5 min)

Verify everything:

Go through the test protocol from the Agent Dialog:

## Test Protocol
- [x] All text matches spec word-for-word
- [x] Form renders correctly on mobile
- [x] Tab navigation reaches all fields
- [x] Error messages appear on blur
- [x] Loading spinner shows on submit
- [ ] Touch targets 44px minimum          ← ISSUE: Submit button is 40px

Fix the issue:

"Submit button touch target is 40px, needs to be 44px. Increase padding."

Update log:

### Test Protocol Check
- All pass except touch target on submit button
- Fixed: increased button padding from 12px to 14px (48px total height)
- All tests pass

Step 8: Finalize the Dialog (5 min)

Complete the Agent Dialog:

## Meta
- Date: 2026-02-10
- Input: P02-signup-form.md
- Agent: Idunn
- Status: Complete

## Summary
Built working signup form prototype matching specification.
7 steps completed, 1 task added during development.
1 stuck moment resolved with concrete HTML example.
1 test failure fixed (touch target sizing).
All tests passing.

Save the dialog:

docs/F-Agent-Dialogs/
└── 2026-02-10-signup-form/
    └── dialog.md

What You've Created

  • Working prototype matching your specification
  • Complete Agent Dialog with plan, log, decisions, and test results
  • Reusable context for future sessions or handoff

Tips for Success

DO:

  • Always start with an Agent Dialog
  • Evaluate after every step
  • Give specific, numbered feedback
  • Update the plan as you learn
  • Log everything

DON'T:

  • Jump in without a plan
  • Let the agent build everything before reviewing
  • Give vague feedback ("make it better")
  • Fight the same issue more than 3 times
  • Skip the test protocol

You've Completed Module 14!

You can now run agentic development sessions. You know how to:

  • Structure work with Agent Dialogs
  • Evaluate and give effective feedback
  • Handle stuck moments
  • Keep plans alive and updated

Next Module

Module 15: Visual Design →

Add soul and visual polish to your prototypes.

← Back to Lesson 5 | Back to Module Overview

Part of Module 14: Agentic Development