Getting Started with AIWF

Welcome to AIWF (AI Workflow Framework)! This guide will help you get up and running quickly with AIWF and Claude Code.

Prerequisites
Quick Start
Your First Project
Understanding the Structure
Essential Commands
Working with Claude Code
Best Practices
Next Steps

Prerequisites

Before you begin, ensure you have:

Node.js version 14.0.0 or higher

node --version  # Should output v14.0.0 or higher

npm (comes with Node.js)
```
npm --version
```
Git for version control
```
git --version
```
Claude Code access (claude.ai/code)

Quick Start

1. Install AIWF

# Install globally (if not already installed)
npm install -g aiwf

# Navigate to your project directory
cd my-project

# Initialize AIWF in your project
aiwf install

2. Choose Your Language

During installation, you'll be prompted to select a language:

? Select your preferred language:
❯ English
  한국어 (Korean)

3. Verify Installation

# Check that AIWF directories were created
ls -la .aiwf/
ls -la .claude/commands/aiwf/

You should see:

.aiwf/ - Project management directory
.claude/commands/aiwf/ - Claude Code commands
.cursor/rules/ - Cursor IDE rules (if using Cursor)
.windsurf/rules/ - Windsurf IDE rules (if using Windsurf)

Your First Project

Let's create a simple task management application to demonstrate AIWF workflow.

Step 1: Initialize the Project

Open your project in Claude Code and run:

/project:aiwf:initialize

Claude will help you set up the project structure and create initial documentation.

Step 2: Define Your Project Vision

/project:aiwf:aiwf_create_prd "Task Manager" "A simple task management app with CRUD operations"

This creates:

Project manifest in .aiwf/00_PROJECT_MANIFEST.md
Project documentation in .aiwf/01_PROJECT_DOCS/

Step 3: Plan Your First Milestone

/project:aiwf:aiwf_create_milestone_plan "Basic Task Management"

Claude will guide you through:

Defining milestone objectives
Breaking down into features
Setting acceptance criteria
Estimating timeline

Example milestone structure:

## M01: Basic Task Management

### Objectives
- Create, read, update, delete tasks
- Mark tasks as complete
- Filter tasks by status
- Basic UI for task management

### Timeline: 2 weeks

Step 4: Generate Sprints

/project:aiwf:create_sprints_from_milestone M01

This automatically creates sprint directories:

S01_M01_backend_setup/ - API and database setup
S02_M01_frontend_development/ - UI implementation
S03_M01_integration_testing/ - Testing and polish

Step 5: Start Your First Task

# List tasks in current sprint
/project:aiwf:list_tasks S01

# Start a specific task
/project:aiwf:do_task T01_S01

Claude will:

Load task requirements
Suggest implementation approach
Help you write code
Track progress

Understanding the Structure

Directory Layout

my-project/
├── .aiwf/                          # AIWF project management
│   ├── 00_PROJECT_MANIFEST.md      # Central tracking document
│   ├── 01_PROJECT_DOCS/            # Project documentation
│   │   └── OVERVIEW.md
│   ├── 02_REQUIREMENTS/            # Milestone definitions
│   │   └── M01_Basic_Task_Management/
│   ├── 03_SPRINTS/                 # Sprint execution
│   │   ├── S01_M01_backend_setup/
│   │   ├── S02_M01_frontend_development/
│   │   └── S03_M01_integration_testing/
│   ├── 04_GENERAL_TASKS/           # Non-sprint tasks
│   ├── 05_ARCHITECTURAL_DECISIONS/  # ADRs
│   └── 99_TEMPLATES/               # Reusable templates
├── .claude/commands/aiwf/          # Claude commands
├── src/                            # Your source code
└── package.json                    # Node.js project file

File Naming Conventions

Milestones: M01_, M02_, etc.
Sprints: S01_M01_, S02_M01_, etc.
Tasks: T01_S01_, T02_S01_, etc.
Features: FL001, FL002, etc.
Completed items: Prefix with X (e.g., XT01_S01_)

Essential Commands

Project Management

Command	Description
`/project:aiwf:initialize`	Initialize AIWF in your project
`/project:aiwf:status`	View project status
`/project:aiwf:review`	Comprehensive project review

Milestone & Sprint Management

Command	Description
`/project:aiwf:aiwf_create_milestone_plan`	Create a new milestone
`/project:aiwf:create_sprints_from_milestone`	Generate sprints
`/project:aiwf:sprint_status`	Check sprint progress

Task Management

Command	Description
`/project:aiwf:create_task`	Create a new task
`/project:aiwf:do_task`	Work on a specific task
`/project:aiwf:list_tasks`	List tasks in sprint
`/project:aiwf:complete_task`	Mark task as done

GitHub Integration

Command	Description
`/project:aiwf:aiwf_issue_create`	Create GitHub issue
`/project:aiwf:aiwf_pr_create`	Create pull request

AI Personas

AIWF includes an AI Persona system that optimizes Claude Code's behavior for different development tasks:

Command	Description
`/project:aiwf:aiwf_persona_architect`	System design and architecture
`/project:aiwf:aiwf_persona_security`	Security-focused development
`/project:aiwf:aiwf_persona_frontend`	Frontend development
`/project:aiwf:aiwf_persona_backend`	Backend development
`/project:aiwf:aiwf_persona_data_analyst`	Data analysis and insights

Core Workflow Commands

Command	Description
`/project:aiwf:aiwf_yolo`	Autonomous task execution
`/project:aiwf:aiwf_code_review`	Automated code review
`/project:aiwf:aiwf_test`	Run project tests
`/project:aiwf:aiwf_validate_state`	Validate workflow state

See the AI Personas Guide for detailed information.

Context Management

Command	Description
`/project:aiwf:compress_context:aggressive`	Maximum compression
`/project:aiwf:compress_context:balanced`	Balanced compression
`/project:aiwf:compress_context:conservative`	Minimal compression

Working with Claude Code

1. Effective Communication

Be Specific:

# Good
/project:aiwf:do_task T01_S01
"Implement the POST /api/tasks endpoint with validation"

# Less effective
"Make the API"

2. Use Personas Appropriately

AIWF's AI Persona system helps Claude Code focus on specific aspects of development:

# For design decisions
/project:aiwf:ai_persona:architect
"Design the database schema for tasks"

# For bug fixing
/project:aiwf:ai_persona:debugger
"Fix the issue where completed tasks still appear as active"

# For documentation
/project:aiwf:ai_persona:documenter
"Create API documentation for the task endpoints"

# For performance optimization
/project:aiwf:ai_persona:optimizer
"Optimize the task query performance"

# For code review
/project:aiwf:ai_persona:reviewer
"Review the authentication module for security issues"

Auto-Detection Feature:

# Enable automatic persona switching
/project:aiwf:ai_persona:auto on

# Claude will automatically switch personas based on your task
"Debug the login error"  # → Automatically switches to debugger persona

Check Persona Performance:

# View current session metrics
/project:aiwf:ai_persona:status

# Generate performance report
/project:aiwf:ai_persona:report

# Check specific persona statistics
/project:aiwf:ai_persona:stats debugger

3. Manage Context Efficiently

For large codebases:

# Start with overview
/project:aiwf:compress_context:aggressive
"Show me the overall project structure"

# Then focus on specifics
/project:aiwf:compress_context:balanced
"Now let's work on the user authentication module"

4. Track Progress

# Regular status checks
/project:aiwf:status

# Detailed sprint review
/project:aiwf:sprint_status S01

# Feature progress
/project:aiwf:feature_status FL001

Best Practices

1. Commit Conventions

Always reference features in commits:

git commit -m "feat(FL001): add task creation endpoint"
git commit -m "fix(FL001): validate task title length"
git commit -m "docs(FL001): update API documentation"

2. Task Breakdown

Keep tasks small and focused:

✅ "Implement GET /api/tasks endpoint"
✅ "Add pagination to task list"
❌ "Build entire API" (too large)

3. Regular Reviews

# Daily
/project:aiwf:sprint_status

# Weekly
/project:aiwf:review

# Per milestone
/project:aiwf:milestone_review M01

4. Documentation

Document as you go:

# After implementing a feature
/project:aiwf:ai_persona:documenter
"Document the task API endpoints we just created"

# Update architecture decisions
/project:aiwf:create_adr "Use PostgreSQL for task storage"

Next Steps

1. Explore Advanced Features

Feature-Git Integration:

# Link commits to features automatically
/project:aiwf:install_git_hooks

Performance Monitoring:

// Use built-in performance tools
import { PerformanceBenchmark } from '@aiwf/performance';

Team Collaboration:

# Generate team reports
/project:aiwf:team_status_report

# Create shared documentation
/project:aiwf:export_project_docs

2. Learn More

Read the Commands Guide for all available commands
Check out Examples for real-world scenarios
Review API Reference for programmatic usage
See Troubleshooting if you encounter issues

3. Join the Community

GitHub: github.com/moonklabs/aiwf
Discord: discord.gg/aiwf
Discussions: Share your experiences and learn from others

4. Customize for Your Workflow

Create custom templates:

# Add your own templates
cp my-template.md .aiwf/99_TEMPLATES/

# Customize personas
echo "Custom rules" > .aiwf/personas/custom.json

Quick Reference Card

# Start new task
/project:aiwf:aiwf_create_general_task "Feature Name"  # → T001
git checkout -b feature/T001-feature-name

# Work on tasks
/project:aiwf:list_tasks S01
/project:aiwf:do_task T01_S01

# Switch personas
/project:aiwf:ai_persona:architect    # Design
/project:aiwf:ai_persona:developer     # Code
/project:aiwf:ai_persona:debugger      # Debug
/project:aiwf:ai_persona:reviewer      # Review
/project:aiwf:ai_persona:documenter    # Document
/project:aiwf:ai_persona:optimizer     # Optimize

# Persona management
/project:aiwf:ai_persona:auto on      # Enable auto-detection
/project:aiwf:ai_persona:status        # Check current persona
/project:aiwf:ai_persona:report        # Performance report

# Manage context
/project:aiwf:compress_context:aggressive    # Overview
/project:aiwf:compress_context:balanced      # Normal work
/project:aiwf:compress_context:conservative  # Detailed work

# Track progress
/project:aiwf:status                   # Overall
/project:aiwf:sprint_status S01        # Sprint
/project:aiwf:feature_status FL001     # Feature

Congratulations! 🎉

You now have the foundation to effectively use AIWF with Claude Code. Remember:

Start small - Begin with simple tasks and gradually take on more complex features
Use the right tools - Leverage personas and compression modes appropriately
Stay organized - Follow the naming conventions and project structure
Collaborate - Share your learnings with the community

Happy coding with AIWF! 🚀

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History