Configuration

ai-tools/config.json reference and all configuration options

Fulcrum's configuration lives in ai-tools/config.json. This file controls which AI vendors are enabled, which agents are active, and how your team is configured.

💡 Key principle: Edit ai-tools/config.json, then run npm run fulcrum:generate to propagate changes to all vendor files.

Config Structure

Here's the complete structure of config.json:

{
  "version": "6.2.0",
  "vendors": {
    "enabled": ["claude", "cursor", "windsurf"],
    "primary": "claude"
  },
  "agents": {
    "preset": "all",
    "selected": [
      "product-manager",
      "tech-lead",
      "domain-expert",
      "frontend-engineer",
      "backend-engineer",
      "database-engineer",
      "ai-engineer",
      "devops-engineer",
      "firmware-engineer",
      "qa-backend",
      "qa-frontend",
      "qa-firmware",
      "work-orchestrator"
    ]
  },
  "installedAt": "2024-01-15T10:30:00.000Z"
}

version

Property	Type	Description
`version`	string	Fulcrum version. Used for migration detection.

The version field is automatically updated when you upgrade Fulcrum. It's used to detect when migrations are needed and to ensure compatibility.

vendors

Controls which AI vendors receive generated configuration files.

Property	Type	Description
`vendors.enabled`	string[]	Array of enabled vendor identifiers.
`vendors.primary`	string	Primary vendor for orchestration features.

Available Vendors

Vendor ID	Output Location	Features
`claude`	`.claude/`	Full orchestration, parallel agents, Beads integration
`cursor`	`.cursorrules`	Rules-based guidance, agent personas
`windsurf`	`.windsurf/`	Cascade integration, agent rules
`gemini`	`.gemini/`	Gemini CLI integration, workspace rules

// Enable multiple vendors
{
  "vendors": {
    "enabled": ["claude", "cursor", "windsurf", "gemini"],
    "primary": "claude"
  }
}

// Single vendor setup
{
  "vendors": {
    "enabled": ["cursor"],
    "primary": "cursor"
  }
}

📝 Note: The primary vendor gets additional orchestration capabilities. Claude is recommended as primary for full parallel execution support.

agents

Controls which agents are active in your AI team.

Property	Type	Description
`agents.preset`	string	Preset configuration for agent selection.
`agents.selected`	string[]	Explicit list of enabled agent IDs.

Presets

Preset	Description	Agents Included
`all`	All 13 agents enabled	Full team: PM, TL, all engineers, all QA
`web`	Web development focus	Frontend, Backend, Database, QA-Frontend, QA-Backend
`backend`	Backend/API focus	Backend, Database, DevOps, QA-Backend
`fullstack`	Full-stack applications	Frontend, Backend, Database, DevOps, QA-Frontend, QA-Backend
`embedded`	Firmware/embedded systems	Firmware Engineer, QA-Firmware, DevOps
`minimal`	Lightweight setup	Work Orchestrator, Tech Lead only
`custom`	Manual selection	Only agents in `selected` array

// Use a preset
{
  "agents": {
    "preset": "web",
    "selected": []  // Ignored when preset is not "custom"
  }
}

// Custom selection
{
  "agents": {
    "preset": "custom",
    "selected": [
      "work-orchestrator",
      "tech-lead",
      "frontend-engineer",
      "backend-engineer"
    ]
  }
}

Available Agents

Category	Agent ID	Role
Strategy	`work-orchestrator`	Coordinates work, delegates tasks
	`product-manager`	Requirements, PRDs, user stories
	`tech-lead`	Architecture, technical decisions
Engineering	`frontend-engineer`	UI implementation, React/Vue/CSS
	`backend-engineer`	APIs, server logic, performance
	`database-engineer`	Schema, queries, migrations
	`ai-engineer`	ML pipelines, model integration
	`devops-engineer`	CI/CD, infrastructure, deployment
	`firmware-engineer`	Embedded systems, C/C++
QA	`qa-backend`	API testing, integration tests
	`qa-frontend`	E2E testing, UI testing
	`qa-firmware`	Hardware-in-loop testing
Domain	`domain-expert`	Business logic, domain knowledge

Adding/Removing Agents

Using /manage-agents

The easiest way to modify your agent team:

# Interactive agent management
/manage-agents

# Opens a menu to:
# - List current agents
# - Add agents from available pool
# - Remove agents
# - Switch presets

Manual Configuration

Edit config.json directly:

// 1. Set preset to "custom"
{
  "agents": {
    "preset": "custom",
    "selected": [
      "work-orchestrator",
      "tech-lead",
      "frontend-engineer",
      "backend-engineer",
      "qa-backend"
    ]
  }
}

// 2. Regenerate vendor files
npm run fulcrum:generate

⚠️ Always regenerate: After editing config.json, run npm run fulcrum:generate to update all vendor configuration files.

Custom Agents

Add custom agents created with /generate-agent:

{
  "agents": {
    "preset": "custom",
    "selected": [
      "work-orchestrator",
      "tech-lead",
      "frontend-engineer",
      "custom-auth-specialist",    // Custom agent
      "custom-graphql-expert"      // Custom agent
    ]
  }
}

Custom agent files live in ai-tools/agents/custom/ and follow the same format as built-in agents.

Environment Variables

Fulcrum respects these environment variables:

Variable	Description	Default
`FULCRUM_CONFIG_PATH`	Custom path to config.json	`./ai-tools/config.json`
`FULCRUM_VERBOSE`	Enable verbose logging	`false`
`FULCRUM_DRY_RUN`	Preview changes without writing	`false`
`BEADS_ROOT`	Custom path to Beads directory	`./.beads`

# Custom config location
FULCRUM_CONFIG_PATH=./config/fulcrum.json npm run fulcrum:generate

# Dry run to preview changes
FULCRUM_DRY_RUN=true npm run fulcrum:generate

# Verbose output for debugging
FULCRUM_VERBOSE=true npm run fulcrum:generate

Regenerating Vendor Files

After any configuration change, regenerate vendor files:

# Standard regeneration
npm run fulcrum:generate

# What this does:
# 1. Reads ai-tools/config.json
# 2. Processes ai-tools/ canonical files
# 3. Generates vendor-specific output:
#    - .claude/ for Claude Code
#    - .cursorrules for Cursor
#    - .windsurf/ for Windsurf
#    - .gemini/ for Gemini CLI

💡 Commit the output: Generated vendor files should be committed to your repository so team members get the same configuration.

Validating Configuration

Check your configuration is valid:

# Check Fulcrum status
/status

# Or use the CLI
npm run fulcrum:validate

Common validation errors:

Error	Cause	Solution
Unknown agent ID	Typo in agent name	Check agent ID spelling
Unknown vendor	Invalid vendor in enabled list	Use: claude, cursor, windsurf, gemini
Primary not in enabled	Primary vendor not in enabled list	Add primary vendor to enabled array
Invalid preset	Unknown preset name	Use: all, web, backend, fullstack, embedded, minimal, custom

Example Configurations

Web Startup

{
  "version": "6.2.0",
  "vendors": {
    "enabled": ["claude", "cursor"],
    "primary": "claude"
  },
  "agents": {
    "preset": "fullstack",
    "selected": []
  }
}

Enterprise Backend

{
  "version": "6.2.0",
  "vendors": {
    "enabled": ["claude"],
    "primary": "claude"
  },
  "agents": {
    "preset": "custom",
    "selected": [
      "work-orchestrator",
      "tech-lead",
      "backend-engineer",
      "database-engineer",
      "devops-engineer",
      "qa-backend",
      "domain-expert"
    ]
  }
}

IoT/Embedded

{
  "version": "6.2.0",
  "vendors": {
    "enabled": ["claude", "cursor"],
    "primary": "claude"
  },
  "agents": {
    "preset": "custom",
    "selected": [
      "work-orchestrator",
      "tech-lead",
      "firmware-engineer",
      "backend-engineer",
      "devops-engineer",
      "qa-firmware"
    ]
  }
}