Initialize the agile workflow framework in an existing project and verify everything works
⏱ ~10 min · Hands-on
By the end of this tutorial, your project will have a fully configured agile workflow with auto-detected conventions, populated memory files, and a clean health check.
You've just started working on TaskFlow — a Node.js/Express REST API backed by PostgreSQL with Jest for testing. The codebase exists but has no structured workflow. You want to bring in the agile framework so your AI assistant understands the project's architecture, conventions, and can help you ship features efficiently.
The agile workflow lives inside a .claude/ directory at your project root. Copy the framework files there:
cp -r agile/* your-project/.claude/This gives you the command definitions, memory templates, and workflow protocols. The memory files start as templates — the next step fills them in automatically.
The .claude/ directory contains: command definitions (setup, sprint, story, code, ship, memory), empty memory templates, and the workflow engine configuration. No project files are modified.
This is the most important command. It scans your entire codebase and populates all memory files with real information about your project.
/agile-setup-initThe AI analyzes your project and produces output like this:
🔍 Scanning project structure...
Detected stack:
Runtime: Node.js 20.x
Framework: Express 4.18
Database: PostgreSQL 15 (via pg + knex)
Testing: Jest 29 + supertest
Linting: ESLint + Prettier
CI/CD: GitHub Actions
Detected patterns:
Architecture: Controller → Service → Repository (3-layer)
API style: RESTful, versioned (/api/v1/*)
Auth: JWT with refresh tokens
Error handling: Centralized middleware (errorHandler.js)
📝 Populating memory files...
✅ .memory/semantic/project.md — name, description, tech stack
✅ architecture.md — 3-layer architecture, data flow
✅ conventions.md — naming, imports, error patterns
✅ .memory/semantic/codebase.md — 47 files mapped across 12 directories
✅ testing.md — Jest config, coverage thresholds
✅ deployment.md — GitHub Actions → AWS ECS
✅ .memory/semantic/conventions.md — naming, imports, error patterns, commit conventions
✅ .memory/semantic/domain/api.md — 14 endpoints documented
✅ .memory/semantic/domain/database.md — 8 tables, relationships mapped
✅ Setup complete — 10 memory files populated.The AI read every file in your project — source code, configs, package.json, Dockerfiles, CI configs, SQL migrations — and extracted structured knowledge into memory files. This is how it "understands" your project without you explaining everything manually.
Open .memory/MEMORY_INDEX.md to see the summary of all memory files:
## Memory Index
| File | Summary | Last Verified |
|------|---------|---------------|
| .memory/semantic/project.md | TaskFlow: REST API for task management. Node/Express/PostgreSQL. | 2026-04-04 |
| .memory/semantic/architecture.md | 3-layer (Controller→Service→Repository). JWT auth. Centralized errors. | 2026-04-04 |
| .memory/semantic/conventions.md | camelCase, ESM imports, async/await, Prettier enforced. GitFlow branch strategy. Conventional commits. | 2026-04-04 |
| .memory/semantic/codebase.md | 47 files. src/{controllers,services,repositories,middleware,utils}. | 2026-04-04 |
| .memory/semantic/testing.md | Jest 29. Unit + integration. 80% coverage threshold. | 2026-04-04 |
| .memory/semantic/deployment.md | GitHub Actions → Docker → AWS ECS. Staging + production. | 2026-04-04 |
| .memory/episodic/decisions.md | ADR-001: chose Knex over Prisma. ADR-002: JWT over sessions. | 2026-04-04 |Every future command reads from these memory files. When the AI plans a feature, it knows your architecture. When it writes code, it follows your conventions. When it creates a PR, it uses your branch strategy. Keep memory files accurate.
This command generates project-specific coding rules from your codebase patterns:
/agile-setup-onboard📋 Generating project conventions...
Naming:
Variables/functions: camelCase
Classes: PascalCase
Files: kebab-case.js
DB columns: snake_case
Import order:
1. Node built-ins (path, fs, crypto)
2. External packages (express, knex, joi)
3. Internal modules (relative paths)
Error handling:
Pattern: async/await with try-catch
Errors: Extend AppError base class
HTTP codes: Mapped via errorHandler middleware
Testing:
Unit tests: *.test.js next to source
Integration tests: __tests__/integration/
Naming: describe('ClassName') → it('should_do_thing')
✅ Conventions saved to .memory/semantic/conventions.mdWithout onboarding, the AI might write code using different patterns than your team uses — wrong naming, wrong file locations, wrong error handling. After onboarding, every generated line of code matches your existing style.
Verify everything is configured correctly with a health check:
/agile-setup-health🏥 Agile Workflow Health Check
═══════════════════════════════
Memory Files:
✅ .memory/semantic/project.md — current (verified today)
✅ .memory/semantic/architecture.md — current (verified today)
✅ .memory/semantic/conventions.md — current (verified today)
✅ .memory/semantic/codebase.md — current (verified today)
✅ .memory/semantic/testing.md — current (verified today)
✅ .memory/semantic/deployment.md — current (verified today)
✅ .memory/episodic/decisions.md — current (verified today)
Framework:
✅ All command files present (43/43)
✅ Workflow definitions intact
✅ No orphaned memory references
Overall: ✅ HEALTHY — All systems operational.If you see a ⚠️ stale warning (file not verified in 30+ days) or a ❌ missing file, re-run /agile-setup-init to refresh. After major refactors, always run /agile-setup-health to catch drift between code and memory.
What is the first command to run after copying the framework into your project?