Welcome to Claude Code Harness for Multi-Agent Team Workflows! This guide covers everything you need to know to contribute effectively, whether you're a human developer, Claude Code, or an AI remote agent.
For Human Developers: Follow the complete setup process below For AI Agents: Focus on AI Agent Guidelines and Workflow Process
- Prerequisites & Setup
- AI Agent Guidelines
- Branch Naming Conventions
- Commit Message Guidelines
- Workflow Process
- Pull Request Process
- CI/CD Pipeline
- Local Development
- Troubleshooting
-
Install Dependencies:
# Install Node.js 18+ node --version # Should be 18+ npm --version # Bundled with Node.js
-
Clone and Setup:
git clone https://github.com/bybren-llc/a-safe-pulse.git cd a-safe-pulse npm install -
Environment Setup:
cp .env.template .env # Fill in your environment variables -
Database Setup:
docker-compose up -d # Start PostgreSQL # Migrations are raw SQL files in src/db/migrations/ # They run automatically on application startup
-
CI/CD Setup (First time only):
chmod +x scripts/setup-ci-cd.sh ./scripts/setup-ci-cd.sh
AI agents (Claude Code, Augment agents) should:
- Read this entire document before starting work
- Follow all workflow processes exactly as human developers
- Use the PR template at
.github/pull_request_template.md - Run local validation with
npm test && npm run buildbefore pushing - Reference Linear tickets in all commits and PRs
✅ MUST DO:
- Follow the exact branch naming convention:
ASP-{number}-{description} - Use SAFe commit message format with Linear ticket references
- Run
npm test && npm run buildbefore pushing any code - Use the comprehensive PR template completely
- Follow rebase-first workflow (never create merge commits)
- Reference the Linear ticket in all commits and PR title
- Implementation Tickets: Follow ready-to-implement tickets in
docs/technical-improvements/07-implementation-roadmap.md#immediate-implementation-tickets
❌ NEVER DO:
- Skip the CI/CD validation steps
- Create branches without Linear ticket numbers
- Use merge commits (always rebase)
- Push without running local validation
- Ignore failing CI checks
Skills now support fine-grained invocation control via YAML frontmatter fields: disable-model-invocation, user-invocable, context: fork, allowed-tools, and argument-hint. See the Skill Authoring Guide for details.
Agent Teams is an experimental feature for real-time multi-agent orchestration. See the Agent Teams Guide.
# 1. Start work (always from latest dev)
git checkout dev && git pull origin dev
git checkout -b ASP-123-implement-feature
# 2. Make changes and commit with SAFe format
git commit -m "feat(scope): implement feature [ASP-123]"
# 3. Before pushing - ALWAYS validate locally
npm test && npm run build
# 4. Rebase and push
git fetch origin && git rebase origin/dev
git push --force-with-lease origin ASP-123-implement-feature
# 5. Create PR using template at .github/pull_request_template.mdReady-to-Implement Tickets: See docs/technical-improvements/07-implementation-roadmap.md#immediate-implementation-tickets
For each implementation ticket:
- Check Acceptance Criteria: Ensure all requirements are clearly defined
- Verify Dependencies: Confirm prerequisite tickets are completed
- Follow Effort Estimates: Most tickets are < 1 hour for quick wins
- Test Verification: Use provided verification steps before PR
- Separate PRs: Keep scope tight (one ticket = one PR for easier review)
Example Implementation Tickets:
- Remove unused dependencies (15 min)
- Add health endpoints (45 min)
- Wire Slack alerting (2 hours)
- Documentation cleanup (5 min)
REQUIRED FORMAT: ASP-{number}-{short-description}
ASP-42-add-user-authenticationASP-57-fix-profile-image-uploadASP-123-implement-oauth-flow
feature/add-dark-mode(missing ticket number)fix/broken-login-form(missing ticket number)john-new-feature(personal naming)WIP(not descriptive)
- MUST start with
ASP-{number}(Linear ticket reference) - Use lowercase letters and hyphens for description
- Keep description short but descriptive (max 50 chars total)
- Never include personal names or dates
- Make sure the name reflects the actual work being done
Note: The CI/CD pipeline will automatically reject branches that don't follow this format.
REQUIRED FORMAT: SAFe methodology with Linear ticket reference
type(scope): description [ASP-XXX]
feat- New featurefix- Bug fixdocs- Documentation changesstyle- Code formatting (no logic changes)refactor- Code restructuring (no feature/bug changes)test- Adding or updating testschore- Maintenance tasks, dependenciesci- CI/CD pipeline changes
safe- SAFe framework changesauth- Authentication featurescli- CLI tool changesapi- API routes and backenddb- Database changes
✅ Correct:
feat(auth): add Confluence OAuth integration [ASP-42]
fix(auth): resolve login redirect issue [ASP-57]
docs: update API documentation [ASP-123]
❌ Incorrect:
add new feature (missing ticket reference)
feat: add checkout (missing ticket reference)
WIP: working on stuff (not descriptive)
Note: The CI/CD pipeline will automatically reject commits that don't follow this format.
CRITICAL: This project uses a rebase-first workflow enforced by CI/CD automation.
# ALWAYS start from latest dev
git checkout dev
git pull origin dev
# Create feature branch with Linear ticket number
git checkout -b ASP-{number}-{description}# Make changes and commit with SAFe format
git add .
git commit -m "feat(scope): description [ASP-XXX]"
# Keep branch updated (rebase, never merge)
git fetch origin
git rebase origin/dev# REQUIRED: Run local validation
npm test && npm run build
# This runs:
# - Jest test suite
# - TypeScript compilation (production build)
# Fix any issues before proceeding# ALWAYS use force-with-lease after rebase
git push --force-with-lease origin ASP-{number}-{description}- Use the template at
.github/pull_request_template.md - Fill out ALL sections completely
- Reference Linear ticket in title:
feat(scope): description [ASP-XXX] - Request appropriate reviewers (auto-assigned via CODEOWNERS)
The automated pipeline will check:
- ✅ Branch naming format
- ✅ Commit message format
- ✅ Rebase status (no merge commits)
- ✅ All tests passing
- ✅ Code quality (ESLint, TypeScript)
- ✅ Build verification
If checks fail: Fix issues and push again (pipeline re-runs automatically)
- ONLY use "Rebase and merge" (maintains linear history)
- NEVER use "Squash and merge" or "Create merge commit"
- Auto-merge available with
auto-mergelabel (if all checks pass)
Each agent role has explicit exit states that define handoff points in the workflow:
┌─────────────────┬───────────────────────────────────────────┐
│ Role │ Exit State │
├─────────────────┼───────────────────────────────────────────┤
│ BE-Developer │ "Ready for QAS" │
│ FE-Developer │ "Ready for QAS" │
│ Data-Engineer │ "Ready for QAS" │
│ QAS │ "Approved for RTE" │
│ RTE │ "Ready for HITL Review" │
│ System Architect│ "Stage 1 Approved - Ready for ARCHitect" │
│ HITL │ MERGED │
└─────────────────┴───────────────────────────────────────────┘
┌─────────────────┬─────────────────┬─────────────────────────┐
│ Gate │ Owner │ Blocking? │
├─────────────────┼─────────────────┼─────────────────────────┤
│ Stop-the-Line │ Implementer │ YES - no AC = no work │
│ QAS Gate │ QAS │ YES - no approval = stop│
│ Stage 1 Review │ System Architect│ YES - pattern check │
│ Stage 2 Review │ ARCHitect-CLI │ YES - architecture check│
│ HITL Merge │ Scott Graham │ YES - final authority │
└─────────────────┴─────────────────┴─────────────────────────┘
- RTE: Collapsible (PR creation can be done by implementer)
- QAS: NOT collapsible (independence gate - spawn subagent)
- SecEng: NOT collapsible (security audit requires independence)
See Agent Workflow SOP v1.4 for complete details.
MUST USE: .github/pull_request_template.md (comprehensive template)
Required Sections:
- 📋 Summary with Linear ticket link
- 🎯 Changes Made (detailed list)
- 🧪 Testing (coverage and results)
- 📊 Impact Analysis (files changed, breaking changes)
- 🔄 Multi-Team Coordination (rebase status, dependencies)
- ✅ Pre-merge Checklist (quality, security, SAFe compliance)
The CI/CD pipeline automatically validates:
-
Structure Validation 🔍
- Branch naming:
ASP-{number}-{description} - PR title includes Linear ticket:
[ASP-XXX] - Linear ticket exists and is valid
- Branch naming:
-
Rebase Status Check 🔄
- Branch is up-to-date with
dev - No merge commits (linear history maintained)
- Auto-comments with rebase instructions if needed
- Branch is up-to-date with
-
Comprehensive Testing 🧪
- Unit tests (fast feedback)
- Integration tests (API/database)
-
Quality & Security 🔍
- ESLint + TypeScript validation
- Security audit and secret detection
- Code formatting (Prettier)
-
Build Verification 🏗️
- TypeScript production build
- Build artifact validation
-
Conflict Detection 🚨
- High-risk file monitoring (
.env.template,config.ts,package.json) - Team notification triggers
- Extra review requirements for sensitive changes
- High-risk file monitoring (
Automatic Assignment: Based on CODEOWNERS file
- Core config files → cheddarfox (ARCHitect-in-the-IDE)
- Payment features → @payments-team cheddarfox
- Authentication → @auth-team cheddarfox
- Database schema → @backend-team cheddarfox
Review Requirements:
- At least 1 required reviewer approval
- All CI checks must pass
- No merge conflicts
- Linear history maintained
# Run all quality checks (REQUIRED before pushing)
npm test && npm run build
# Individual checks
npm test # Jest test suite (unit + integration)
npm run build # TypeScript production build
npm run build:dev # TypeScript build including tests- Structure Validation → Validates branch/PR format
- Rebase Status Check → Ensures linear history
- Comprehensive Testing → All test suites
- Quality & Security → Code quality and security
- Build Verification → Production build test
- Conflict Detection → High-risk file monitoring
- No merge conflicts between teams (rebase enforcement)
- Automatic quality gates (no broken code reaches
dev) - Team coordination (automatic notifications and assignments)
- Parallel development (teams work simultaneously safely)
# Database (PostgreSQL via Docker)
docker-compose up -d
# Environment variables
cp .env.template .env
# Edit .env with your values
# Database migrations (raw SQL in src/db/migrations/)
# Migrations run automatically on application startup
# To add a new migration, create a SQL file in src/db/migrations/
# and register it in src/db/migrations/index.ts
# RLS Security Setup (Important!)
# The database now uses Row Level Security for data protection
# Use cheddarfox_app_user for proper RLS enforcement in development
# See docs/database/RLS_IMPLEMENTATION_GUIDE.md for details# Start development server
npm run dev
# Database management
# Connect directly via psql:
# docker exec -it cheddarfox-team-postgres-1 psql -U cheddarfox_app_user -d linear_agent
# Migrations are raw SQL files in src/db/migrations/
# Testing
npm test # All tests (Jest)
# Build
npm run build # Production build (TypeScript)
npm run build:dev # Development build (includes tests)
# RLS Security Testing
node scripts/test-rls-phase3-simple.js # Basic RLS functionality test
# Run comprehensive security validation:
# cat scripts/rls-phase4-final-validation.sql | docker exec -i cheddarfox-team-postgres-1 psql -U cheddarfox_app_user -d linear_agentThe a-safe-pulse application uses Row Level Security (RLS) for database-level data protection. This is critical for preventing cross-user data access.
🚨 CURRENT STATUS:
- RLS lint is warn-only temporarily; migrate to withRLS()
- DB migrations are manual-only with ARCHitect approval
✅ MUST DO when working with database operations:
- Use
withUserContext(),withAdminContext(), orwithSystemContext()helpers - Test with
cheddarfox_app_userrole (notpostgressuperuser) - Validate user data isolation in your tests
- Check RLS context is properly set before database queries
❌ NEVER DO:
- Bypass RLS context setting for user operations
- Use
postgres(superuser) for application testing - Trust session variables for role validation
- Assume users can access data without proper context
# Test basic RLS functionality
node scripts/test-rls-phase3-simple.js
# Run comprehensive security validation
cat scripts/rls-phase4-final-validation.sql | docker exec -i cheddarfox-team-postgres-1 psql -U cheddarfox_app_user -d linear_agent
# Test user isolation manually
docker exec cheddarfox-team-postgres-1 psql -U cheddarfox_app_user -d linear_agent -c "
SET app.current_user_id = 'your_test_user';
SELECT COUNT(*) FROM user; -- Should see only your test user's data
"// User operation - automatic context setting
const userTokens = await withUserContext(pool, userId, async (client) => {
const result = await client.query(
'SELECT * FROM linear_tokens WHERE user_id = $1 ORDER BY created_at DESC',
[userId]
);
return result.rows;
});
// Admin operation - requires admin role
const webhookEvents = await withAdminContext(pool, userId, async (client) => {
const result = await client.query('SELECT * FROM webhook_events');
return result.rows;
});
// System operation - for background tasks
const systemData = await withSystemContext(
pool,
"webhook",
async (client) => {
const result = await client.query(
'INSERT INTO webhook_events (event_type, payload) VALUES ($1, $2) RETURNING *',
[eventType, JSON.stringify(webhookData)]
);
return result.rows[0];
},
);- Implementation Guide:
docs/database/RLS_IMPLEMENTATION_GUIDE.md - Troubleshooting:
docs/guides/RLS_TROUBLESHOOTING.md - Security Scripts:
scripts/rls-*.sql
Branch Name Rejected:
# Rename branch to correct format
git branch -m ASP-{number}-{description}
git push origin -u ASP-{number}-{description}
git push origin --delete old-branch-nameRebase Required:
git fetch origin
git rebase origin/dev
# Resolve any conflicts
git push --force-with-lease origin your-branchCommit Message Format Error:
# Amend last commit message
git commit --amend -m "feat(scope): description [ASP-XXX]"
git push --force-with-lease origin your-branchCI Validation Failures:
# Run local validation to see specific issues
npm test && npm run build
# Fix issues and commit
git add .
git commit -m "fix: resolve CI validation issues [ASP-XXX]"- Documentation: CI/CD Pipeline Guide
- Implementation Guide:
docs/CI-CD-Pipeline-Guide.md - Team Workflow:
docs/a-safe-pulse-Multi-Team-Git-Workflow-Guide.md - Quick Setup:
docs/ci-cd-implementation-checklist.md
- Database Schema:
docs/database/DATA_DICTIONARY.md(SINGLE SOURCE OF TRUTH - AI Context) - Database Security:
docs/database/RLS_DATABASE_MIGRATION_SOP.md(MANDATORY for schema changes) - Security Architecture:
docs/guides/SECURITY_FIRST_ARCHITECTURE.md(REQUIRED for new services) - Technical Improvements Strategy:
docs/technical-improvements/(Complete implementation roadmap) - Implementation Tickets:
docs/technical-improvements/07-implementation-roadmap.md#immediate-implementation-tickets - CI/CD Setup:
scripts/setup-ci-cd.sh - Pipeline Guide:
docs/CI-CD-Pipeline-Guide.md - Team Workflow:
docs/a-safe-pulse-Multi-Team-Git-Workflow-Guide.md - Implementation Checklist:
docs/ci-cd-implementation-checklist.md - TypeScript Cleanup:
docs/archive/asp-139-typescript-cleanup-status.md(ASP-139)
This document is maintained by the a-safe-pulse development team and reflects our current CI/CD pipeline implementation.
Last Updated: 2025-12-23 Version: 2.1 (vNext Workflow Contract - ASP-497/499) Maintained by: a-safe-pulse Development Team + ARCHitect-in-the-IDE (Auggie)