File Structure

Fulcrum uses a single source of truth in ai-tools/ that generates vendor-specific configuration files. Understanding this structure is key to customizing and maintaining your setup.

Directory Overview

your-project/
├── ai-tools/              # ✏️ EDIT HERE - Canonical source
│   ├── config.json        # Main configuration
│   ├── agents/            # Agent definitions
│   ├── commands/          # Slash command docs
│   ├── skills/            # Skill definitions
│   └── prompts/           # System prompts
│
├── .claude/               # 🔄 GENERATED - Claude Code
├── .cursorrules           # 🔄 GENERATED - Cursor
├── .windsurf/             # 🔄 GENERATED - Windsurf
├── .gemini/               # 🔄 GENERATED - Gemini CLI
│
├── agent_docs/            # ✏️ EDIT HERE - Memory Bank
│   ├── projectBrief.md
│   ├── productContext.md
│   └── ...
│
└── .beads/                # 🔄 MANAGED - Work tracking
    ├── index.json
    └── items/

ai-tools/ (Canonical Source)

This is your single source of truth. All customizations go here.

ai-tools/
├── config.json              # Configuration (vendors, agents, presets)
│
├── agents/
│   ├── core/                # Built-in agents
│   │   ├── work-orchestrator.md
│   │   ├── product-manager.md
│   │   ├── tech-lead.md
│   │   ├── frontend-engineer.md
│   │   ├── backend-engineer.md
│   │   ├── database-engineer.md
│   │   ├── ai-engineer.md
│   │   ├── devops-engineer.md
│   │   ├── firmware-engineer.md
│   │   ├── qa-backend.md
│   │   ├── qa-frontend.md
│   │   ├── qa-firmware.md
│   │   └── domain-expert.md
│   │
│   └── custom/              # Your custom agents
│       ├── auth-specialist.md
│       └── graphql-expert.md
│
├── commands/
│   ├── start.md             # /start command
│   ├── execute-work.md      # /execute-work command
│   ├── plan-execution.md    # /plan-execution command
│   ├── create-work-item.md
│   ├── start-work-item.md
│   ├── update-work-item.md
│   ├── close-work-item.md
│   ├── handoff-work-item.md
│   ├── request-review.md
│   ├── setup-fulcrum.md
│   ├── setup-beads.md
│   ├── generate-agent.md
│   ├── manage-agents.md
│   └── sync-handbook.md
│
├── skills/
│   ├── project/             # Project-level skills
│   │   ├── code-reviewer.md
│   │   ├── test-engineer.md
│   │   └── pr-creator.md
│   │
│   └── user/                # User-level skills
│       ├── brainstorming.md
│       ├── systematic-debugging.md
│       └── test-driven-development.md
│
└── prompts/
    ├── system.md            # Base system prompt
    ├── rules.md             # Core rules and guidelines
    └── workflows/           # Workflow-specific prompts
        ├── inception.md
        └── execution.md

What to Edit

.claude/ (Claude Code)

Generated configuration for Claude Code (formerly Claude Dev).

.claude/
├── settings.json            # Claude workspace settings
├── commands/                # Slash commands as Claude commands
│   ├── start.md
│   ├── execute-work.md
│   └── ...
├── agents/                  # Agent personas
│   ├── work-orchestrator.md
│   └── ...
└── CLAUDE.md                # Main instructions file

Key Files

.cursorrules (Cursor)

A single file containing all rules and agent personas for Cursor.

.cursorrules                 # Single file with all configuration
# Contains:
# - System prompt and rules
# - Agent personas (as sections)
# - Coding guidelines
# - Project-specific instructions

.windsurf/ (Windsurf)

Generated configuration for Windsurf's Cascade feature.

.windsurf/
├── cascade.json             # Cascade configuration
├── rules/                   # Rule definitions
│   ├── system.md
│   └── agents/
│       ├── work-orchestrator.md
│       └── ...
└── workflows/               # Workflow templates

.gemini/ (Gemini CLI)

Generated configuration for Google's Gemini CLI.

.gemini/
├── config.json              # Gemini workspace config
├── instructions.md          # Main instructions
└── agents/                  # Agent definitions
    ├── work-orchestrator.md
    └── ...

agent_docs/ (Memory Bank)

The Memory Bank stores persistent project knowledge that survives across sessions.

agent_docs/
├── projectBrief.md          # Project overview and goals
├── productContext.md        # Product requirements and user needs
├── systemPatterns.md        # Architecture patterns and decisions
├── techContext.md           # Technical stack and constraints
├── activeContext.md         # Current work and focus areas
├── progress.md              # Development progress log
│
├── specs/                   # Feature specifications
│   ├── auth-system.md
│   └── payment-integration.md
│
├── decisions/               # Architecture Decision Records
│   ├── 001-database-choice.md
│   └── 002-api-design.md
│
└── learnings/               # Project-specific learnings
    ├── performance-gotchas.md
    └── testing-patterns.md

Core Files

.beads/ (Work Tracking)

The Beads distributed issue tracker for work item management.

.beads/
├── index.json               # Work item index
├── config.json              # Beads configuration
│
├── items/                   # Individual work items
│   ├── bd-auth.1.json       # Feature: Add OAuth
│   ├── bd-auth.2.json       # Task: Backend API
│   ├── bd-auth.3.json       # Task: Frontend UI
│   └── bd-bug.1.json        # Bug: Token refresh
│
├── projects/                # Project definitions
│   └── auth.json
│
└── mail/                    # Agent async communication
    ├── inbox/
    └── outbox/

Work Item Structure

// .beads/items/bd-auth.1.json
{
  "id": "bd-auth.1",
  "title": "Add OAuth integration",
  "type": "feature",
  "status": "in_progress",
  "priority": "P1",
  "assignee": "backend-engineer",
  "dependencies": [],
  "children": ["bd-auth.2", "bd-auth.3"],
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-15T14:22:00Z"
}

.gitignore Recommendations

What to commit vs ignore:

# COMMIT these (shared team configuration)
ai-tools/
.claude/
.cursorrules
.windsurf/
.gemini/
agent_docs/

# IGNORE these (local/runtime state)
.beads/mail/           # Agent communication (ephemeral)

# CONSIDER (depends on team workflow)
.beads/items/          # Commit if you want issue history in git
.beads/index.json      # Commit if you want issue state shared

Edit → Generate → Commit

The standard workflow for configuration changes:

# 1. Edit the canonical source
vim ai-tools/config.json

# 2. Regenerate vendor files
npm run fulcrum:generate

# 3. Review changes
git diff

# 4. Commit everything
git add ai-tools/ .claude/ .cursorrules .windsurf/ .gemini/
git commit -m "chore: update Fulcrum configuration"

Monorepo Structure

For monorepos, Fulcrum supports per-package configuration:

monorepo/
├── ai-tools/                # Root-level shared config
│   ├── config.json
│   └── agents/
│
├── packages/
│   ├── web-app/
│   │   └── ai-tools/        # Package-specific overrides
│   │       └── config.json
│   │
│   └── api-server/
│       └── ai-tools/
│           └── config.json
│
├── .claude/                 # Generated from root
└── agent_docs/              # Shared Memory Bank

Troubleshooting