Lesson 01

Getting Started

What the framework is, how it works, who does what, and how to set it up in any project.

10 Roles 43 Commands Memory System Boot Loader Solo / Team Mode Technology Agnostic

What Is This Framework?

A portable agile delivery system that turns your intent into shipped software through Scrum ceremonies, 10 specialized AI roles, engineering standards (SOLID, TDD, Clean Code), and a persistent memory system.

🚫 What This Framework Is NOT

It is not a magic prompt that writes code for you. You drive every decision. You describe what you want to build. You choose the technology. You approve the architecture. The framework structures your decisions through proven engineering practices and specialized roles — but without YOUR input, nothing happens.

How It Works

👤

You Describe what to build

📋

@po Structures into stories

⌨️

@dev Builds with TDD

👨‍💻

@lead Reviews for quality

You provide the requirements. The 10 roles structure, build, review, test, secure, and deploy.

The 10 Roles

The framework simulates a full Scrum team. In solo mode, the AI plays all roles as needed. In team mode, humans fill primary roles and the AI augments.

Role	Badge	What They Own	What They Do NOT Own
`@po`	📋	What to build, priorities, acceptance criteria, backlog	How to build it
`@sm`	🔄	Sprint ceremonies, process health, impediment removal	Technical decisions
`@arch`	🏗️	System structure, components, patterns, infrastructure, ADRs	Code-level quality
`@lead`	👨‍💻	Code quality (SOLID/Clean Code), PR reviews, tactical decisions	System architecture
`@dev`	⌨️	Implementation, TDD, feature branches, commits	Approving own code
`@qa`	🧪	Test strategy, coverage, exploratory testing, quality advocacy	Implementation
`@devops`	🚀	CI/CD pipeline, deployment, environments, infrastructure	Business logic
`@sec`	🛡️	OWASP audits, CVE scanning, auth review, security hardening	Feature development
`@ux`	🎨	Frontend implementation, WCAG accessibility, responsive design	Backend logic
`@dba`	🗄️	Schema design, migrations, indexes, query optimization	Application logic

💡 @arch vs @lead

@arch = system-level: "Should we use a message queue?" / "What components does the system need?"
@lead = code-level: "Is this class following SRP?" / "Should this be a method or a separate function?"
@lead escalates system questions TO @arch. @arch delegates code enforcement TO @lead.

How Commands Work

The framework has 43 slash commands organized in 8 categories. Every command needs your input to work.

⚠️ Commands Need YOUR Input

Commands are not magic buttons. Each one requires context from you:

/agile-story-create needs you to describe the feature you want — @po then structures it into a proper story
/agile-explore-brainstorm needs you to describe the problem — @arch then evaluates approaches
/agile-code-tdd needs a story with acceptance criteria — @dev then writes tests and code
/agile-security-audit needs code to scan — @sec then checks against OWASP Top 10

Without your requirements, the AI has nothing to structure, build, or review.

The 8 Command Categories

Category	Commands	Purpose
🔧 Setup (3)	`init`, `onboard`, `health`	Initialize project, generate rules, check health
🔄 Sprint (6)	`planning`, `daily`, `status`, `review`, `retro`, `refine`	Sprint ceremonies and tracking
📋 Story (7)	`create`, `estimate`, `split`, `plan`, `implement`, `dod`, `accept`	Story lifecycle from idea to accepted
⌨️ Code (12)	`branch`, `tdd`, `ci`, `commit`, `pr`, `pr-review`, `review`, `refactor`, `pair`, `debug`, `perf`, `merge`	Development lifecycle with GitFlow
🚀 Ship (5)	`release`, `deploy`, `hotfix`, `rollback`, `changelog`	Release, deploy, and recover
🔍 Explore (3)	`brainstorm`, `spike`, `audit`	Investigate before building
🛡️ Security (4)	`audit`, `scan`, `review`, `threat-model`	OWASP, CVE, STRIDE
🧠 Memory (3)	`remember`, `recall`, `learn`	Persistent project knowledge

All commands use the /agile-[category]-[name] pattern. Type /agile- in Claude Code and autocomplete shows all 43.

The Complete Story Loop

Every feature, bug fix, and improvement follows this loop. This is the core of the framework.

📋

Create@po structures
your requirement

🎯

Estimate@dev sizes
the story

📝

Plan@lead designs
implementation

🌿

Branch@dev creates
feature branch

🔴🟢🔵

TDD@dev writes
test → code → refactor

⚙️

CI@devops runs
build+test+lint

🔀

PR + Review@lead checks
SOLID + Clean Code

🔗

Merge@dev squash
merges to develop

✅

DoD@qa verifies
Definition of Done

📋

Accept@po verifies
acceptance criteria

As Commands

/agile-story-create "your feature description"
  → /agile-story-estimate
  → /agile-story-plan
  → /agile-code-branch
  → /agile-code-tdd
  → /agile-code-ci
  → /agile-code-commit
  → /agile-code-pr
  → /agile-code-pr-review
  → /agile-code-merge
  → /agile-story-dod
  → /agile-story-accept

System Architecture

The framework is organized into layers. Each layer has a clear responsibility.

🚀

CLAUDE.md (Boot Loader) ~120 lines. Routes your task to the right workflow, roles, and memory.

Manifesto 3 files: values, principles, charter

Roles 10 agents + dispatch matrix

Ceremonies 5 sprint events

Standards SOLID, Clean Code, GitFlow, DoD...

Practices TDD, code review, CI, PR...

Workflows Feature, bugfix, hotfix, release...

🧠

Memory Semantic + Episodic, lazy loaded

⚡

Commands 43 slash commands in 8 categories

Layer Details

Layer	Folder	What's Inside
Manifesto	`manifesto/`	Agile values (4), principles (12), team charter
Roles	`roles/`	10 role definitions: @po, @sm, @arch, @lead, @dev, @qa, @devops, @sec, @ux, @dba
Ceremonies	`ceremonies/`	Sprint Planning, Daily Standup, Sprint Review, Retrospective, Backlog Refinement
Standards	`standards/`	SOLID, Clean Code, OOP, Design Patterns, Testing Pyramid, GitFlow, CI/CD, Definition of Done, Security
Practices	`practices/`	14 files: TDD, code review, pair programming, CI, commit, PR, release, hotfix, deploy, brainstorm, spike, refactoring, user story, backlog refinement
Workflows	`workflows/`	Feature sprint, bugfix, hotfix, release, tech spike, refactor, new project, autonomous
Memory	`memory/`	Semantic (project, architecture, conventions, codebase, testing, deployment, domain) + Episodic (decisions, incidents, learnings, context, sprints) + Backlog (product, sprint)
Commands	`commands/`	43 slash commands across 8 categories (setup, sprint, story, code, ship, explore, security, memory)
Prompts	`prompts/`	Visual system (markers, badges), chain of thought, decomposition, structured output, self-verification

The Boot Loader

CLAUDE.md is the entry point. Claude Code reads it automatically from .claude/CLAUDE.md. It does NOT load everything — it routes to only what's needed for the current task.

👤

You say: "Add user authentication"

🚀

CLAUDE.md reads task → routes to feature sprint workflow

🧠

Memory .memory/semantic/architecture.md
.memory/semantic/conventions.md

📋

Workflow workflows/
feature_sprint.md

🤖

Roles @dev, @lead,
@sec, @dba

What Gets Loaded Per Task

Task	Memory Files Loaded	Roles Activated
Any task	`.memory/MEMORY_INDEX.md` (always, ~30 lines)	—
Coding	`.memory/semantic/conventions.md`, `.memory/semantic/codebase.md`	@dev, @lead
Architecture	`.memory/semantic/architecture.md`, `.memory/episodic/decisions.md`	@arch
Backend API	+ `.memory/semantic/domain/api.md`, `.memory/semantic/domain/database.md`	@dev, @dba
Frontend	+ `.memory/semantic/domain/design.md`	@dev, @ux
DevOps	`.memory/semantic/deployment.md`	@devops
Sprint work	`.memory/backlog/sprint.md`, `.memory/episodic/context.md`, `.memory/episodic/learnings.md`	@sm, @po
Planning	`.memory/backlog/product.md`, `.memory/backlog/sprint.md`	@po, @sm
Debugging	`.memory/episodic/incidents.md`, `.memory/semantic/codebase.md`	@dev, @qa
Retrospective	`.memory/episodic/learnings.md`, `.memory/episodic/sprints/sprint_NNN.md`	@sm, @po

✅ Why This Matters

The boot loader keeps AI context efficient. A bug fix loads .memory/semantic/codebase.md and .memory/episodic/incidents.md — it doesn't need deployment config or design specs. This is lazy loading for AI context.

Memory System

The AI remembers your project across conversations. Two types of memory, lazy loaded:

Semantic Memory — What the project IS

Stable knowledge that rarely changes. Loaded on demand.

`.memory/semantic/project.md`	Project name, type, language, runtime, dependencies
`.memory/semantic/architecture.md`	System structure, components, data flow, patterns
`.memory/semantic/conventions.md`	Naming rules, import ordering, error patterns, formatting
`.memory/semantic/codebase.md`	Directory structure, key files, module responsibilities
`.memory/semantic/testing.md`	Test framework, coverage goals, testing patterns
`.memory/semantic/deployment.md`	CI/CD config, environments, deploy process
`.memory/semantic/domain/*.md`	Domain-specific: API docs, database schema, design system, integrations

Episodic Memory — What HAPPENED

Event log bounded to current sprint. Sprint-scoped, archived at sprint boundaries.

`.memory/episodic/decisions.md`	Architecture Decision Records (ADRs)
`.memory/episodic/incidents.md`	Production incidents and post-mortems
`.memory/episodic/learnings.md`	Sprint retrospective insights
`.memory/episodic/context.md`	Current working context (not version controlled)
`.memory/episodic/sprints/sprint_NNN.md`	Historical sprint summaries (loaded on demand)

Backlog

`.memory/backlog/product.md`	All user stories, prioritized by @po
`.memory/backlog/sprint.md`	Current sprint stories, status, burndown

Only .memory/MEMORY_INDEX.md loads at conversation start (~30 lines of summaries). Everything else loads on demand when relevant.

Setting It Up

Step 1: Copy the framework

cp -r agile/* your-project/.claude/

That's it. Claude Code reads .claude/CLAUDE.md automatically and discovers all /agile-* commands.

Step 2: Initialize

New project (empty repo)

/agile-setup-init --new

Creates empty memory templates. Memory fills up as you work — the AI saves conventions, decisions, and architecture as it discovers them.

Existing project

/agile-setup-init

Scans your codebase and auto-populates memory: detects language, framework, test tools, directory structure, naming conventions, CI config. Reports confidence per file.

Step 3: Generate coding rules

/agile-setup-onboard

Reads your codebase conventions and generates enforceable coding rules specific to YOUR project.

Step 4: Verify

/agile-setup-health

Checks that memory is populated, commands are discoverable, and the project is ready for sprint work.

💡 What /agile-setup-init Actually Does

It scans your project files and populates memory. For example, if it finds package.json with Jest, it writes to .memory/semantic/testing.md: "Test framework: Jest, Runner: npm test". If it finds .github/workflows/, it writes to .memory/semantic/deployment.md: "CI: GitHub Actions". Every detection cites the specific file that proves it — nothing is guessed.

Solo Mode vs Team Mode

Solo Mode (1 developer + AI)

The AI simulates all 10 Scrum roles. Ceremonies still happen but are abbreviated:

📋 @po: AI structures your features into stories, verifies acceptance at the end
🔄 @sm: AI runs sprint planning and retro (simplified), tracks velocity
👨‍💻 @lead: AI reviews every PR against SOLID and Clean Code standards
⌨️ @dev: AI implements with TDD — or assists YOU while you code
🧪 @qa: AI verifies Definition of Done and test coverage
🏗️ @arch: AI evaluates architecture options when you ask
🛡️ @sec: AI scans for OWASP vulnerabilities and CVEs

Team Mode (2+ developers + AI)

Humans fill primary roles. AI augments with specialized analysis:

👤 Human PO writes stories → AI @po helps with INVEST validation and Given/When/Then formatting
👤 Human developers code → AI @lead provides automated code review on every PR
🤖 AI @sec runs security scans automatically
🤖 AI @dba reviews schema changes and migration safety
🧠 Shared memory ensures all team members have consistent project context

Technology Agnostic

The framework works for any technology, architecture, or platform. It never forces a specific stack.

🌐 Web apps (React, Vue, Angular, vanilla)
🖥️ Desktop apps (Electron, Tauri, native)
📱 Mobile apps (React Native, Flutter, Swift, Kotlin)
⌨️ CLI tools (Commander, Click, Cobra)
📦 Libraries and SDKs
☁️ Microservices, monoliths, serverless — any architecture

When you need to choose a technology, /agile-explore-brainstorm evaluates options with a scoring matrix. @arch presents data — you make the decision.

🧠 Knowledge Check

What does /agile-story-create need from you to work?

🧠 Knowledge Check

What does the CLAUDE.md boot loader do?

🧠 Knowledge Check

Who decides the technology stack for your project?

← All Lessons Lesson 02: The Agile Manifesto →