Configuration

Introduction

The Claude Workflow system uses configuration files in .claude/config/ to store project details, credentials, and integration settings. This document explains how to set up configuration files for your project.

Important: Configuration files contain sensitive information and should be customized per project and never committed to version control.

Quick Setup

Step 1: Run Setup Command

npm run setup:claude

What this does:

• Copies all templates from core/ai-workflow/claude/ to .claude/
• Creates configuration directory structure
• Copies example files (.example.md, .example.json)

Files that get replaced on every run:

• ✅ All *.example.* files (always updated from core)
• ✅ Agent definitions (agents/*.md)
• ✅ Command definitions (commands/*.md)
• ✅ Tool documentation (tools/**)
• ✅ Session templates (sessions/templates/)

Files NEVER touched (your customizations are safe):

• 🔒 .claude/config/agents.md (your credentials)
• 🔒 .claude/config/workflow.md (your workflow)
• 🔒 .claude/config/settings.local.json (your settings)
• 🔒 .claude/sessions/[your-sessions]/ (your work)

Important: You can run npm run setup:claude anytime to update templates from core without losing your configurations.

Step 2: Create Your Configuration

# Copy example files to create your configs
cp .claude/config/agents.example.md .claude/config/agents.md
cp .claude/config/workflow.example.md .claude/config/workflow.md
cp .claude/config/settings.local.example.json .claude/config/settings.local.json

Step 3: Configure ClickUp (Optional)

Edit .claude/config/agents.md with your details:

• ClickUp API token
• Workspace, Space, List IDs
• User ID for assignments

Skip this if not using ClickUp - the workflow works with session files only.

---

Configuration File Structure

.claude/config/
├── agents.example       # Template for agents.md
├── agents.md           # Actual configuration (git-ignored)
├── workflow.example    # Template for workflow.md
└── workflow.md         # Actual workflow docs (git-ignored)

Configuration vs Documentation

• agents.md - Contains sensitive data (credentials, IDs, API keys)
• workflow.md - Contains workflow documentation (can be project-specific)

Initial Setup

Step 1: Copy Example Files

# From project root
cd .claude/config

# Copy templates
cp agents.example agents.md
cp workflow.example workflow.md

Step 2: Edit Configuration

Open agents.md and update with your project details:

# Open in your editor
code .claude/config/agents.md

Configuration Sections

1. Project Details

Purpose: Identifies the project type for agent context

## Project Details

Project: Saas Boilerplate
Is Core: True

Options:

• Project Name: Your project name
• Is Core: True for boilerplate development, False for client projects

Usage: Agents use this to determine which ClickUp board to use and whether to follow core patterns.

2. QA & Testing Credentials

Purpose: Test user accounts for QA automation

## QA & Testing Credentials

### Member
user: user@cypress.com
pass: Testing1234

### Admin
user: admin@cypress.com
pass: AdminPass123

### Superadmin
user: superadmin@cypress.com
pass: Pandora1234

### Super Admin API Key
API_KEY="sk_test_xxxxx..."

Customization:

• Use your actual test accounts
• Create accounts with different permission levels
• Update API keys for API testing

Security:

• Never commit these credentials
• Use separate test database
• Rotate keys periodically

3. ClickUp Configuration (Optional)

Purpose: Integration with ClickUp project management

## ClickUp Configuration

**API token:** pk_XXXXXXX
**Workspace ID:** 90132320273
**Space:** Boilerplate (ID: 90139892186)
**Default List:** Product Backlog (ID: 901318980252)
**Core Space:** Boilerplate (ID: 90139892186)
**Core List:** Product Backlog (ID: 901318980252)
**User:** Pablo Capello (ID: 3020828)
**Notifications Channel:** Claude Notifications (ID: 2ky4w40h-533)

How to Get These Values:

1. API Token:

   ClickUp → Settings → Apps → API Token → Generate Token
   

2. Workspace ID:

   ClickUp → Settings → Workspace → Copy ID from URL
   

3. Space ID:

   Open Space → Copy ID from URL: /space/[SPACE_ID]/
   

4. List ID:

   Open List → Copy ID from URL: /list/[LIST_ID]/
   

5. User ID:

   ClickUp API: GET /user → id field
   

6. Channel ID (Chat notifications):

   ClickUp → Chat → Channel Settings → Copy ID
   

If Not Using ClickUp:

• Leave this section empty
• Agents will skip ClickUp interactions
• Use local session files only

4. Workflow Documentation Reference

## Workflows

**Complete Development Workflow:** See `.claude/config/workflow.md`

Purpose: Links to detailed workflow documentation

5. Agent Definitions Reference

## Agent Definitions

All agent definitions are in `.claude/agents/`:
- product-manager.md
- architecture-supervisor.md
- frontend-developer.md
- backend-developer.md
- qa-tester.md
- code-reviewer.md
- dev-plugin.md

Purpose: Lists available agents for quick reference

Security Best Practices

Protect Sensitive Data

1. Git Ignore Configuration:

Verify .gitignore includes:

# Claude workflow config
.claude/config/agents.md
.claude/config/workflow.md
.claude/sessions/

2. Never Commit:

• API tokens
• Test credentials
• User IDs
• API keys

3. Use Environment Variables (Alternative):

Instead of hardcoding in config file:

# .env (git-ignored)
CLICKUP_API_TOKEN=pk_xxx
CLICKUP_WORKSPACE_ID=xxx
CLICKUP_SPACE_ID=xxx
CLICKUP_LIST_ID=xxx

Update agents to read from environment:

const clickupToken = process.env.CLICKUP_API_TOKEN

Team Configuration

For Teams:

1. Share Example Files - Commit .example files only
2. Individual Setup - Each developer creates their own agents.md
3. Shared Workflow - Optionally commit workflow.md if not sensitive
4. Document Process - Create team setup guide

Team-Specific Settings:

## Team Configuration

### Development Team
- **Lead:** [Name] (ClickUp ID: xxx)
- **Frontend:** [Name] (ClickUp ID: xxx)
- **Backend:** [Name] (ClickUp ID: xxx)
- **QA:** [Name] (ClickUp ID: xxx)

### Assignment Rules
- PM assigns to: [Lead]
- QA creates bugs assigned to: [Original developer]

Validation

Verify Configuration

1. Check File Exists:

ls -la .claude/config/agents.md

2. Verify Structure:

# Should contain all sections
grep "## Project Details" .claude/config/agents.md
grep "## ClickUp Configuration" .claude/config/agents.md

3. Test ClickUp Connection (if using):

# Using curl
curl -H "Authorization: YOUR_TOKEN" \
  https://api.clickup.com/api/v2/user

# Should return your user details

Common Issues

Problem: "Cannot find configuration file"

Solution:

# Ensure file exists
cp .claude/config/agents.example .claude/config/agents.md

Problem: "Invalid ClickUp API token"

Solution:

• Verify token in ClickUp settings
• Check for extra spaces in config file
• Regenerate token if expired

Problem: "Workspace/Space not found"

Solution:

• Verify IDs are numbers (not names)
• Check you have access to the workspace
• Ensure IDs are copied correctly from URLs

Environment-Specific Configuration

Development

## Environment: Development

- **Database:** Local PostgreSQL (docker)
- **Base URL:** http://localhost:3000
- **ClickUp:** Use "Development" list

Staging

## Environment: Staging

- **Database:** Staging DB (supabase)
- **Base URL:** https://staging.example.com
- **ClickUp:** Use "Staging" list

Production

## Environment: Production

- **Database:** Production DB
- **Base URL:** https://app.example.com
- **ClickUp:** Use "Production Issues" list

Usage: Agents can read environment to determine behavior.

Customization Examples

Example 1: GitHub Issues Instead of ClickUp

## GitHub Configuration

**Repository:** owner/repo
**Token:** ghp_xxxxx
**Project:** "Development Board"
**Label Schema:**
- feature
- bug
- enhancement
- documentation

Example 2: Simplified Solo Developer

## Solo Developer Config

**Name:** John Doe
**Focus:** Backend development only

**Agents Used:**
- architecture-supervisor (planning)
- backend-developer (implementation)

**Skipped:**
- product-manager (write requirements manually)
- qa-tester (manual testing)
- code-reviewer (self-review)

Example 3: Agency Multi-Project

## Agency Configuration

**Active Projects:**
- Project A: Client X (Space ID: xxx, List ID: xxx)
- Project B: Client Y (Space ID: yyy, List ID: yyy)
- Core: Internal (Space ID: zzz, List ID: zzz)

**Assignment Rules:**
- Client projects: Assign to PM
- Core improvements: Assign to tech lead

Configuration Updates

When to Update

• New team members join
• ClickUp workspace reorganization
• New test accounts created
• API tokens expire
• Project phase changes

Update Process

1. Edit agents.md
2. Verify changes don't break existing sessions
3. Update documentation if structure changes
4. Notify team of configuration changes

Next Steps

• Agents - Learn about available agents
• Development Workflow - Understand the workflow
• ClickUp Integration - Detailed ClickUp setup