Skip to content

Campaign Brain: Claude Code Agent Guide

GitHub Issue Management & Cross-Project Coordination

Version: 1.0
Last Updated: December 2025

Overview

Campaign Brain is built across four interconnected modules, each in its own GitHub repository. This guide establishes the rules of engagement for Claude Code agents working on any of these projects.

The Four Pillars

Module Repo Name Purpose
SYSTEM Nominate-AI/system Infrastructure, deployment, DevOps
CBTENANT Nominate-AI/cbtenant Multi-tenant management, provisioning
CBAPP Nominate-AI/cbapp Main web application (FastHTML)
CBWORKFLOW Nominate-AI/cbworkflow CRM workflow engine (FastAPI)

Label System

All repositories use a consistent labeling scheme. Always apply appropriate labels when creating or updating issues.

Module Labels (module:*)

Use these to indicate cross-project dependencies or when work touches multiple modules:

  • module:system — Infrastructure/deployment concerns
  • module:tenant — Tenant management functionality
  • module:app — Main web application
  • module:workflow — Workflow engine functionality

Example: An issue in CBAPP that requires API changes in CBWORKFLOW should have both module:app and module:workflow labels.

Type Labels (type:*)

Every issue must have exactly one type label:

Label When to Use
type:feature New functionality or user-facing enhancement
type:bug Something is broken or not working as expected
type:chore Maintenance, refactoring, documentation, dependencies
type:spike Research, investigation, or proof-of-concept
type:debt Technical debt that needs addressing

Priority Labels (priority:*)

Apply based on urgency and impact:

Label Meaning Response Time
priority:critical Production down, security issue, blocker Immediate
priority:high Significant impact, next in queue Within 24h
priority:normal Standard work item This sprint
priority:low Nice to have, no deadline Backlog

Status Labels (status:*)

Use to communicate workflow state beyond GitHub's open/closed:

Label When to Apply
status:blocked Cannot proceed due to external dependency
status:needs-review Ready for code review or feedback
status:in-progress Actively being worked (claim the issue)
status:ready Groomed and ready to be picked up

Scope Labels (scope:*)

Indicate which part of the codebase is affected:

  • scope:api — API endpoints, contracts, serialization
  • scope:ui — User interface, templates, styling
  • scope:data — Data models, storage, migrations
  • scope:docs — Documentation updates
  • scope:tests — Test coverage additions/fixes
  • scope:config — Configuration, environment, settings

Issue Management Commands

Creating Issues

# Basic issue creation
gh issue create --repo OWNER/REPO --title "Title" --body "Description"

# With labels (ALWAYS include type and priority)
gh issue create --repo OWNER/REPO \
  --title "Add user authentication to tenant API" \
  --body "## Description\n\nImplement JWT-based auth...\n\n## Acceptance Criteria\n- [ ] ..." \
  --label "type:feature" \
  --label "priority:high" \
  --label "module:tenant" \
  --label "scope:api"

# Assign to yourself
gh issue create --repo OWNER/REPO \
  --title "Fix workflow state transition bug" \
  --body "..." \
  --label "type:bug,priority:critical,module:workflow" \
  --assignee "@me"

Viewing Issues

# List open issues in current repo
gh issue list

# List issues with specific labels
gh issue list --label "type:bug" --label "priority:high"

# List issues across all CB repos (run from any CB repo directory)
gh issue list --repo OWNER/campaign-brain-system
gh issue list --repo OWNER/campaign-brain-tenant
gh issue list --repo OWNER/campaign-brain-app
gh issue list --repo OWNER/campaign-brain-workflow

# View specific issue details
gh issue view 42
gh issue view 42 --repo OWNER/campaign-brain-workflow

Updating Issues

# Add labels to existing issue
gh issue edit 42 --add-label "status:in-progress"

# Remove labels
gh issue edit 42 --remove-label "status:ready"

# Add comment
gh issue comment 42 --body "Started work on this. ETA: end of day."

# Assign/unassign
gh issue edit 42 --add-assignee "@me"
gh issue edit 42 --remove-assignee "username"

Closing Issues

# Close with comment
gh issue close 42 --comment "Fixed in commit abc123"

# Close as not planned
gh issue close 42 --reason "not planned" --comment "Descoped from v1"

# Reopen if needed
gh issue reopen 42

Cross-Project Workflow

Referencing Issues Across Repos

When an issue in one repo relates to work in another, use full issue URLs:

This depends on OWNER/campaign-brain-workflow#42

Blocked by: https://github.com/OWNER/campaign-brain-system/issues/15

Related: OWNER/campaign-brain-app#28

Creating Linked Issues

When you discover work needed in another module:

  1. Create the issue in the appropriate repo
  2. Add cross-module labels to both issues
  3. Reference the related issue in the body
  4. Add status:blocked to the dependent issue if applicable

Example workflow:

# You're working on CBAPP and realize you need a new API endpoint in CBWORKFLOW

# 1. Create the upstream issue
gh issue create --repo OWNER/campaign-brain-workflow \
  --title "Add bulk contact import endpoint" \
  --body "Needed by OWNER/campaign-brain-app#55\n\n## Requirements\n..." \
  --label "type:feature,priority:high,module:workflow,module:app,scope:api"

# 2. Update the downstream issue
gh issue edit 55 --repo OWNER/campaign-brain-app \
  --add-label "status:blocked,module:workflow"

gh issue comment 55 --repo OWNER/campaign-brain-app \
  --body "Blocked on OWNER/campaign-brain-workflow#72 for API support"

Issue Templates

Feature Request

## Description
[Clear description of the feature]

## User Story
As a [type of user], I want [goal] so that [benefit].

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Notes
[Any implementation considerations]

## Dependencies
[Links to related issues or external dependencies]

Bug Report

## Bug Description
[What's happening vs. what should happen]

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
[What should happen]

## Actual Behavior
[What's actually happening]

## Environment
- Module: [SYSTEM/CBTENANT/CBAPP/CBWORKFLOW]
- Version/Commit: [hash or version]
- OS: [if relevant]

## Logs/Screenshots
[Attach relevant logs or screenshots]

Spike/Research

## Question to Answer
[What are we trying to learn?]

## Context
[Why do we need to know this?]

## Timebox
[How long should this investigation take?]

## Success Criteria
- [ ] Document findings in [location]
- [ ] Recommendation for next steps
- [ ] Identify any new issues to create

## Related Issues
[Links to issues that prompted this spike]

Best Practices

DO ✅

  • Always label issues — At minimum: one type:* and one priority:*
  • Update status labels — Move from ready → in-progress → close
  • Cross-reference liberally — Link related issues across repos
  • Comment on blockers — Explain what you're waiting for
  • Close issues with context — Reference the commit/PR that resolves it
  • Keep titles concise but descriptive — "Fix auth bug" ❌ → "Fix JWT token expiration not refreshing on CBAPP login" ✅

DON'T ❌

  • Create issues without labels — Makes triage impossible
  • Leave issues in limbo — Update status or close stale issues
  • Duplicate issues — Search first, link if related
  • Use vague titles — "Update stuff" tells us nothing
  • Forget cross-repo dependencies — If it touches multiple modules, label it

Quick Reference Card

┌─────────────────────────────────────────────────────────────────┐
│  CAMPAIGN BRAIN - GITHUB ISSUE QUICK REFERENCE                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  CREATE ISSUE (with labels):                                    │
│  gh issue create -R OWNER/REPO -t "Title" -b "Body" \          │
│    -l "type:feature,priority:normal"                           │
│                                                                 │
│  LIST BY LABEL:                                                 │
│  gh issue list -l "type:bug" -l "priority:high"                │
│                                                                 │
│  ADD LABEL:                                                     │
│  gh issue edit 42 --add-label "status:in-progress"             │
│                                                                 │
│  COMMENT:                                                       │
│  gh issue comment 42 -b "Update message"                       │
│                                                                 │
│  CLOSE:                                                         │
│  gh issue close 42 -c "Fixed in abc123"                        │
│                                                                 │
│  CROSS-REPO VIEW:                                               │
│  gh issue view 42 -R OWNER/campaign-brain-workflow             │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  REQUIRED LABELS: type:* + priority:*                          │
│  OPTIONAL: module:* scope:* status:*                           │
└─────────────────────────────────────────────────────────────────┘

Module-Specific Notes

SYSTEM (Nominate-AI/system)

  • Infrastructure as code, deployment scripts
  • CI/CD pipeline configurations
  • Environment management
  • Issues here often block other modules

CBTENANT (Nominate-AI/cbtenant)

  • Tenant provisioning and lifecycle
  • Multi-tenancy isolation
  • Tenant-level configuration
  • Depends on SYSTEM for infrastructure

CBAPP (Nominate-AI/cbapp)

  • FastHTML web application
  • User-facing features
  • UI components (follow style guide!)
  • Depends on CBWORKFLOW for backend logic

CBWORKFLOW (Nominate-AI/cbworkflow)

  • FastAPI workflow engine
  • Contact management
  • Workflow state machines
  • Core business logic — changes here ripple everywhere

Escalation

If you encounter:

  • Security issues → Create with priority:critical, notify maintainers directly
  • Cross-cutting blockers → Tag all affected modules, add status:blocked
  • Unclear ownership → Default to SYSTEM repo, will be triaged

This guide should be included in each repository's CONTRIBUTING.md or linked from the README.