Configuration System

AgileFlow's configuration system provides a unified script for setting up, customizing, and verifying every aspect of your development workflow. Access it through /agileflow:configure.

Quick Start

Copy# Interactive wizard - guides you through all options
/agileflow:configure
 
# Detect current configuration
/agileflow:configure --detect
 
# Enable specific features
/agileflow:configure --enable=damage-control,status-line,archival
 
# Upgrade to latest versions
/agileflow:configure --upgrade

Configuration Features

AgileFlow's configuration system includes 12 configurable features that can be enabled/disabled individually or through preset profiles:

Setup Profiles

Choose a preset profile to configure multiple features at once:

Full Profile (Recommended for Active Development)

Enables all features including experimental Stop hooks:

Copy/agileflow:configure --profile=full

Includes: SessionStart, PreCompact, RalphLoop, SelfImprove, Archival, StatusLine, AskUserQuestion, TmuxAutoSpawn

Basic Profile (Recommended for New Projects)

Essential hooks + archival:

Copy/agileflow:configure --profile=basic

Includes: SessionStart, PreCompact, Archival, AskUserQuestion, TmuxAutoSpawn

Minimal Profile (Safety First)

No automation - full manual control:

Copy/agileflow:configure --profile=minimal

Includes: AskUserQuestion, TmuxAutoSpawn

None Profile

No hooks at all:

Copy/agileflow:configure --profile=none

Recommended Setup Order

If configuring features manually:

Phase 1: Safety (5 min)
├─ DamageControl      → Protect codebase first
└─ Validate settings

Phase 2: Foundation (10 min)
├─ SessionStart       → Enable basic automation
├─ PreCompact        → Preserve context
└─ AskUserQuestion   → Enable user interactions

Phase 3: Productivity (10 min)
├─ Archival          → Manage status.json
├─ StatusLine        → Real-time visibility
└─ ShellAliases      → Install quick-access commands

Phase 4: Advanced (5 min, optional)
├─ RalphLoop         → Autonomous story processing
├─ SelfImprove       → Auto-update expertise
└─ AutoUpdate        → Check for updates

Feature Configuration Details

SessionStart Hook

Purpose: Run scripts when Claude Code session begins

What it does:

• Displays welcome message with project info
• Shows current git branch and active story
• Lists any blocked stories
• Runs archival if enabled

Controlled by:

Copy/agileflow:configure --enable=sessionstart
/agileflow:configure --disable=sessionstart

Script: scripts/agileflow-welcome.js

PreCompact Hook

Purpose: Preserve critical context when Claude Code compresses conversation

Benefits:

• Project rules survive compression
• Current story and WIP status maintained
• Active commands preserved
• Long conversations stay focused

Controlled by:

Copy/agileflow:configure --enable=precompact
/agileflow:configure --disable=precompact

Script: scripts/precompact-context.sh

RalphLoop (Stop Hook)

Purpose: Autonomous story processing - advance to next story after tests pass

When to use:

• Large epics with clear acceptance criteria
• Well-tested projects
• Batch processing overnight

Controlled by:

Copy/agileflow:configure --enable=ralphloop
/agileflow:configure --disable=ralphloop

Script: scripts/ralph-loop.js

Related: Loop Mode

SelfImprove (Stop Hook)

Purpose: Automatically update agent expertise files based on changes made

When to use:

• Domain agents that build expertise
• Projects using expertise-based agents
• Long-running agent coordination

Controlled by:

Copy/agileflow:configure --enable=selfimprove
/agileflow:configure --disable=selfimprove

Script: scripts/auto-self-improve.js

Related: Agent Expertise System

Archival

Purpose: Automatically clean up completed stories from status.json

Why it matters:

• status.json can exceed 25k tokens
• Archival keeps it lean and fast
• Completed stories moved to monthly archives

Threshold options:

Copy/agileflow:configure --archival-days=30   # Default
/agileflow:configure --archival-days=14   # Fast-moving projects
/agileflow:configure --archival-days=7    # Large teams

Archive structure:

docs/09-agents/
├── status.json           # Active work
└── archive/
    ├── 2025-01.json      # Monthly archives
    └── 2025-02.json

Script: scripts/archive-completed-stories.sh

StatusLine

Purpose: Display project status bar in Claude Code

Shows:

• Current story ID and title
• WIP count vs limit
• Git branch
• Epic progress

Available components:

Copy# List available components
/agileflow:configure --list-statusline-components
 
# Set specific components
/agileflow:configure --statusline=story,branch,wip

Script: scripts/agileflow-statusline.sh

DamageControl

Purpose: Block dangerous commands before execution

What it protects:

• Destructive deletions (rm -rf /)
• Force git operations (git push --force)
• Database destruction (DROP TABLE)
• Cloud CLI deletes (aws delete)

Enable/disable:

Copy/agileflow:configure --enable=damagecontrol
/agileflow:configure --disable=damagecontrol

Scripts:

• scripts/damage-control-bash.js
• scripts/damage-control-edit.js
• scripts/damage-control-write.js

Related: Damage Control

AskUserQuestion

Purpose: Enable interactive user prompts

When enabled:

• Agents use AskUserQuestion tool for confirmations
• Smart Detection recommends features via prompts
• Users choose from options when ambiguous

Controlled by:

Copy/agileflow:configure --enable=askuserquestion
/agileflow:configure --disable=askuserquestion

TmuxAutoSpawn

Purpose: Automatically create tmux sessions for Claude Code

When enabled:

• af command creates/reattaches tmux session
• Session named based on directory
• All Claude Code in tmux windows

Controlled by:

Copy/agileflow:configure --enable=tmuxautospawn
/agileflow:configure --disable=tmuxautospawn

ShellAliases

Purpose: Install af/agileflow shell aliases

What it does:

• Adds af alias (shorthand for agileflow)
• Adds agileflow as full command
• Works with .bashrc, .zshrc, .config/fish/config.fish

Enable:

Copy/agileflow:configure --enable=shellaliases

AutoUpdate

Purpose: Check for AgileFlow updates automatically

When enabled:

• SessionStart checks for new version
• Notifies if updates available
• Manual upgrade via /agileflow:update

Controlled by:

Copy/agileflow:configure --enable=autoupdate
/agileflow:configure --disable=autoupdate

CLAUDE.md Reinforcement

Purpose: Enforce project rules during context compression

When enabled:

• PreCompact preserves CLAUDE.md critical sections
• Project rules never forgotten during long sessions
• Babysit rules always active

Controlled by:

Copy/agileflow:configure --enable=claudemdreinforcement

File Organization

project/
├── .github/workflows/ci.yml          # GitHub Actions
├── .claude/
│   ├── settings.json                 # Hooks & status line (committed)
│   ├── settings.local.json           # User overrides (gitignored)
│   └── settings.local.example.json   # Template for team
├── .agileflow/
│   ├── config/
│   │   └── damage-control-patterns.yaml
│   └── scripts/
│       └── ...
├── scripts/
│   ├── agileflow-welcome.js
│   ├── agileflow-statusline.sh
│   └── precompact-context.sh
├── CLAUDE.md                         # Project guidelines
└── docs/00-meta/
    └── agileflow-metadata.json       # Configuration metadata

Gitignore Rules

Committed (team configuration):

• .claude/settings.json
• .claude/settings.local.example.json
• .github/workflows/
• CLAUDE.md
• scripts/
• .agileflow/

Gitignored (user-specific):

• .claude/settings.local.json
• .claude/prompt-log.txt
• .claude/*.log

Token Reference

GitHub Token (ghp_xxx)

• Location: .claude/settings.local.json
• Scopes needed: repo, workflow
• Create at: https://github.com/settings/tokens/new

GitLab Token (glpat_xxx)

• Location: .claude/settings.local.json
• Scopes needed: api, read_repository, write_repository
• Create at: https://gitlab.com/-/profile/personal_access_tokens

CircleCI Token

• Location: .claude/settings.local.json
• Create at: https://app.circleci.com/settings/user/tokens

Troubleshooting

Restart Requirement

These features require Claude Code restart:

• SessionStart
• PreCompact
• RalphLoop
• DamageControl

Copy# Complete quit (not just closing window)
Cmd+Q (Mac) or Ctrl+Q (Windows/Linux)
# Wait 5 seconds, then reopen

Checking Configuration Status

View current configuration:

Copy/agileflow:configure --detect

This shows:

• Which features are enabled/disabled
• Profile in use (full, basic, minimal, none)
• Archival threshold (days)
• Version information

Rollback

Copy# Restore from git
git checkout .claude/settings.json
 
# Remove specific hook
jq 'del(.hooks.HookName)' .claude/settings.json > tmp.json && mv tmp.json .claude/settings.json
 
# Disable all hooks
jq 'del(.hooks)' .claude/settings.json > tmp.json && mv tmp.json .claude/settings.json

Common Scenarios

Fresh Project Setup

Copy# Apply basic profile (recommended)
/agileflow:configure --profile=basic
 
# Or build custom setup
/agileflow:configure --enable=sessionstart,precompact,archival,damagecontrol

Minimal Setup (Safety First)

Copy/agileflow:configure --profile=minimal

Full Setup (All Features)

Copy/agileflow:configure --profile=full

Optimize for Large Projects

Copy/agileflow:configure --archival-days=7
/agileflow:configure --enable=statusline,ralphloop

Team Setup (with shared config)

Copy# Setup project config
git add .claude/settings.json
git commit -m "chore: configure AgileFlow for team"
 
# Create template for developers
cp .claude/settings.local.json .claude/settings.local.example.json
git add .claude/settings.local.example.json
git commit -m "docs: add settings template for team members"