Configuration

Customize AgileFlow to match your team's workflow and preferences.

Configuration File

AgileFlow is configured via .agileflow/config.json:

{
  "version": "1.0.0",
  "projectName": "My Project",
  "sprintDuration": 14,
  "velocityTracking": true,
  "defaultStoryPoints": 3,
  "git": {
    "enabled": true,
    "autoCommit": false,
    "conventionalCommits": true
  },
  "agents": {
    "defaultOwner": "unassigned",
    "autoAssign": false
  },
  "notifications": {
    "blockers": true,
    "sprintEnd": true
  }
}

Core Settings

Project Information

{
  "projectName": "My Project",
  "version": "1.0.0",
  "description": "Project description"
}

Setting	Type	Default	Description
`projectName`	string	Required	Your project name
`version`	string	`"1.0.0"`	AgileFlow config version
`description`	string	`""`	Project description

Sprint Configuration

{
  "sprintDuration": 14,
  "velocityTracking": true,
  "defaultStoryPoints": 3,
  "sprintGoalRequired": false
}

Setting	Type	Default	Description
`sprintDuration`	number	`14`	Sprint length in days
`velocityTracking`	boolean	`true`	Track team velocity
`defaultStoryPoints`	number	`3`	Default estimate for new stories
`sprintGoalRequired`	boolean	`false`	Require goal for sprint planning

Story Configuration

{
  "storyPrefix": "AF",
  "storyIdFormat": "sequential",
  "requireAcceptanceCriteria": true,
  "requireStoryPoints": false,
  "defaultStatus": "backlog"
}

Setting	Type	Default	Description
`storyPrefix`	string	`"AF"`	Prefix for story IDs (AF-001)
`storyIdFormat`	string	`"sequential"`	ID format: sequential, timestamp, uuid
`requireAcceptanceCriteria`	boolean	`true`	Must have acceptance criteria
`requireStoryPoints`	boolean	`false`	Must have story points
`defaultStatus`	string	`"backlog"`	Initial status for new stories

Git Integration

Basic Git Settings

{
  "git": {
    "enabled": true,
    "autoCommit": false,
    "conventionalCommits": true,
    "branchNaming": "AF-{id}-{slug}",
    "commitFormat": "{type}({scope}): {message}"
  }
}

Setting	Type	Default	Description
`enabled`	boolean	`true`	Enable git integration
`autoCommit`	boolean	`false`	Auto-commit story changes
`conventionalCommits`	boolean	`true`	Use conventional commit format
`branchNaming`	string	`"AF-{id}-{slug}"`	Branch name template
`commitFormat`	string	See default	Commit message format

Branch Protection

{
  "git": {
    "protectedBranches": ["main", "production"],
    "requirePR": true,
    "requireReview": true
  }
}

Agent Configuration

Default Agent Settings

{
  "agents": {
    "defaultOwner": "unassigned",
    "autoAssign": false,
    "agentPreferences": {
      "backend": "agileflow-api",
      "frontend": "agileflow-ui",
      "testing": "agileflow-testing"
    }
  }
}

Setting	Type	Default	Description
`defaultOwner`	string	`"unassigned"`	Default story owner
`autoAssign`	boolean	`false`	Auto-assign based on story type
`agentPreferences`	object	`{}`	Preferred agents by task type

Agent Routing

Configure which agent handles which types of work:

{
  "agents": {
    "routing": {
      "api": "agileflow-api",
      "ui": "agileflow-ui",
      "database": "agileflow-database",
      "testing": "agileflow-testing",
      "docs": "agileflow-documentation"
    }
  }
}

Workflow Configuration

Story Workflow States

{
  "workflow": {
    "states": [
      "backlog",
      "ready",
      "in-progress",
      "review",
      "done"
    ],
    "transitions": {
      "backlog": ["ready"],
      "ready": ["in-progress", "backlog"],
      "in-progress": ["review", "blocked"],
      "review": ["done", "in-progress"],
      "blocked": ["in-progress"],
      "done": []
    }
  }
}

Custom States

Add custom workflow states:

{
  "workflow": {
    "states": [
      "backlog",
      "ready",
      "in-progress",
      "code-review",
      "qa-testing",
      "staging",
      "done"
    ]
  }
}

Changing workflow states requires updating story transitions.

Notifications

Notification Settings

{
  "notifications": {
    "enabled": true,
    "channels": ["console", "file"],
    "events": {
      "blockers": true,
      "sprintEnd": true,
      "velocityChange": false,
      "storyComplete": false
    }
  }
}

Event	Description
`blockers`	Notify about blocked stories
`sprintEnd`	Notify 1 day before sprint ends
`velocityChange`	Notify on significant velocity changes
`storyComplete`	Notify when story is completed

Templates

Story Template

Customize the story template:

{
  "templates": {
    "story": {
      "sections": [
        "title",
        "description",
        "acceptanceCriteria",
        "storyPoints",
        "dependencies",
        "technicalNotes"
      ],
      "customFields": {
        "priority": ["high", "medium", "low"],
        "component": "string"
      }
    }
  }
}

ADR Template

Customize ADR structure:

{
  "templates": {
    "adr": {
      "sections": [
        "title",
        "status",
        "context",
        "decision",
        "consequences",
        "alternatives"
      ],
      "statusOptions": [
        "proposed",
        "accepted",
        "deprecated",
        "superseded"
      ]
    }
  }
}

IDE Integration

Claude Code

{
  "ide": {
    "type": "claude-code",
    "commandPrefix": "/AgileFlow:",
    "agentMention": "@agileflow-",
    "shortcuts": {
      "createStory": "Ctrl+Shift+S",
      "viewBoard": "Ctrl+Shift+B"
    }
  }
}

Cursor / Windsurf

{
  "ide": {
    "type": "cursor",
    "commandPrefix": "/af:",
    "agentMention": "@af-"
  }
}

Advanced Settings

Performance

{
  "performance": {
    "cacheEnabled": true,
    "cacheDuration": 3600,
    "maxConcurrentAgents": 3
  }
}

Debug Mode

{
  "debug": {
    "enabled": false,
    "logLevel": "info",
    "logFile": ".agileflow/logs/agileflow.log",
    "verboseCommands": false
  }
}

Feature Flags

{
  "features": {
    "aiGeneration": true,
    "autoEstimation": true,
    "dependencyDetection": true,
    "velocityForecasting": true
  }
}

Environment-Specific Config

Use environment-specific overrides:

{
  "environment": "development",
  "debug": {
    "enabled": true,
    "logLevel": "debug"
  },
  "git": {
    "autoCommit": true
  }
}

Configuration Validation

Validate your configuration:

/AgileFlow:diagnose

Shows:

## Configuration Validation
 
✅ Config file exists
✅ Valid JSON format
✅ All required fields present
✅ Git integration configured
⚠️  Sprint duration is very short (7 days)
❌ Invalid agent in routing: agileflow-unknown
 
## Recommendations
- Increase sprint duration to 10-14 days
- Remove or fix invalid agent references

Best Practices

1. Start with Defaults

Don't over-configure initially:

{
  "projectName": "My Project",
  "sprintDuration": 14
}

Add settings as needed.

2. Version Control Config

Commit .agileflow/config.json:

git add .agileflow/config.json
git commit -m "chore: add AgileFlow configuration"

3. Document Custom Settings

Add comments in config.md:

# AgileFlow Configuration
 
## Custom Settings
 
- **sprintDuration**: 10 days (Mon-Fri, 2 weeks)
- **storyPrefix**: PROJ (project requirement)
- **autoAssign**: false (manual assignment preferred)

4. Environment Variables

Use env vars for sensitive data:

{
  "integrations": {
    "github": {
      "token": "${GITHUB_TOKEN}"
    }
  }
}

Troubleshooting

Config Not Loading

Check file exists: .agileflow/config.json
Validate JSON syntax
Check file permissions
Run /AgileFlow:diagnose

Invalid Settings

/AgileFlow:diagnose

Shows validation errors and suggestions.

Reset to Defaults

/AgileFlow:setup --reset-config

This will overwrite your current configuration. Backup first!

Next Steps

Review Commands affected by configuration
Check Agents routing settings
Explore Concepts for workflow understanding

Configuration

On this page