Two files, one repository

bybren-llc/safe-agentic-workflow ships 4 formats across 21 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ CLAUDE.md AGENTS.md ↔ Cursor rules AGENTS.md ↔ GEMINI.md CLAUDE.md ↔ Cursor rules CLAUDE.md ↔ GEMINI.md Cursor rules ↔ GEMINI.md

A · AGENTS.md · 2226 words B · CLAUDE.md · 742 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	1	58	23	1%
Commands	0	5	3	0%
Section tags	6	3	4	46%

What each file covers

Sections

1 shared · 58 only in A · 23 only in B

− SAFe Agent Team Quick Reference
− Documentation
− When to Use Which Agent
− Auto-Loaded Skills
− Success Validation Commands
− Frontend Development
− Backend Development
− Pre-Push Validation
− Database Migration
− SAFe Specs-Driven Workflow
− Planning Phase (BSA)
− Large initiative → Use planning template
− Fill with Epic → Features → Stories → Enablers
− User story → Use spec template
− Fill with implementation details
− Execution Phase (All Agents)
− 1. Read spec for clear goal
− 2. Extract:
− - User story (goal)
− - Acceptance criteria (success)
− - Low-level tasks (steps)
− - Demo script (validation)
− 3. Implement using Simon's loop:
− - Clear goal from spec
− - Pattern discovery (codebase + specs)
− - Iterate until demo script passes
− - Escalate if blocked
− 0. Search Specs Directory (FIRST)
− Find similar implementations in specs
− Review SAFe user stories
− Check patterns from past specs
− 1. Search Codebase
− Search for similar functionality
− Find existing helpers
− Check components
− 2. Search Session History
− Search agent session todos
− Find recent implementation patterns
− 3. Consult Documentation
− 4. Architectural Validation
− Agent Workflow
− Standard Agent Loop (Per Simon Willison)
− No Over-Engineering
− Session Archaeology
− Monitor Concurrent Sessions
− See active sessions
− Check for concurrent work on same files
− Cross-Agent Coordination
− Find related work by another agent
− Discover implementation patterns
− Exit States (vNext Contract)
− Gate Quick Reference
− Role Collapsing ({{TICKET_PREFIX}}-499)
− Agent Teams (Experimental)
− Quick Reference
− Key Documentation
− Agent Files
− Human-in-the-Loop (HITL) Model
+ CLAUDE.md
+ AI Assistant Context for SAFe Multi-Agent Development
+ Quick Start
+ Development Commands
+ Development server
+ Build and production
+ Code Quality
+ Testing
+ Database (if applicable)
+ CI/CD validation (REQUIRED before PR)
+ Architecture Overview
+ Technology Stack
+ Repository Structure
+ SAFe Workflow
+ Metacognitive Tags
+ Project-Specific Implementation Notes
+ Authentication
+ Payments
+ Analytics
+ Database
+ CI/CD Pipeline
+ PR Workflow
+ Branch Protection
Pattern Discovery Protocol (MANDATORY)

Commands

0 shared · 5 only in A · 3 only in B

− npm run type-check && npm run lint && npm run build && echo "FE SUCCESS" || echo "FE FAILED"
− npm run test:integration && echo "BE SUCCESS" || echo "BE FAILED"
− npm run lint:md && echo "DOCS SUCCESS" || echo "DOCS FAILED"
− npm run ci:validate && echo "CI SUCCESS" || echo "CI FAILED"
− npx prisma migrate dev --name migration_name && echo "MIGRATION SUCCESS" || echo "MIGRATION FAILED"
+ git add {{MIGRATIONS_DIR}}/ && git commit -m "feat(db): add feature migration"
+ git rebase origin/{{MAIN_BRANCH}}
+ git push --force-with-lease

Section tags

6 shared · 3 only in A · 4 only in B

− code-style
− api
− docs
+ lint-format
+ security
+ deployment
+ do-not
build
test
architecture
git-pr
database
agent-behaviour

Line diff

+135 added−380 removed70 unchanged15.6% identical

bybren-llc/safe-agentic-workflow · AGENTS.md

@@ −1 @@

1# SAFe Agent Team Quick Reference

3> **Philosophy**: "Search First, Reuse Always, Create Only When Necessary"

5> Pattern discovery is MANDATORY before implementation.

7> **Team Culture**: "We work as a round table team that has 4 pillars of SAFe inscribed on that round table. It means something."

9## Documentation

11**Workflow SOPs:**

13- [Agent Workflow SOP v1.4](./docs/sop/AGENT_WORKFLOW_SOP.md) - vNext contract, Exit States, Role Collapsing ({{TICKET_PREFIX}}-497/499)

14- [Agent Configuration SOP](./docs/sop/AGENT_CONFIGURATION_SOP.md) - Tool restrictions, model selection

15- [ARCHitect-in-CLI Role](./docs/workflow/ARCHITECT_IN_CLI_ROLE.md) - Primary orchestrator definition

17**CI/CD Documentation:**

19- [CI/CD Pipeline Guide](./docs/ci-cd/CI-CD-Pipeline-Guide.md) - Pipeline implementation guide

21**Database SOPs:**

23- [RLS Migration SOP](./docs/database/RLS_DATABASE_MIGRATION_SOP.md) - MANDATORY for Data Engineer

25**Project Standards:**

27- [Harness Whitepapers](./docs/whitepapers/) - Architecture, research alignment, and evidence

28- [Agent Perspective](./docs/whitepapers/CLAUDE-CODE-HARNESS-AGENT-PERSPECTIVE.md) - Why the harness works

29- [SAFe Methodology](https://github.com/{{GITHUB_ORG}}/{{PROJECT_REPO}}) - This repository

31## When to Use Which Agent

34| ------------------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------- |

35| **TDM** (Technical Delivery Manager) | Reactive blocker resolution, Linear updates, evidence tracking (NOT orchestration - see v1.3 SOP) | Blockers resolved, evidence attached, Linear updated | Linear, Confluence |

47## Auto-Loaded Skills

49Skills are loaded progressively—metadata at startup, full content when context triggers.

51| Skill | Trigger | Purpose |

52| ------------------------ | ---------------------- | ------------------------------------------- |

53| `safe-workflow` | Commits, branches, PRs | SAFe format, rebase-first workflow |

54| `safe-ai-dlc` | Multi-issue programs | Bolts, Units of Work, HITL gate |

55| `vault-sync` | Knowledge vault drift | Detect staleness, regenerate, record |

56| `pattern-discovery` | Before writing code | Pattern-first development (MANDATORY) |

57| `rls-patterns` | Database operations | RLS context helpers (withUserContext, etc.) |

58| `frontend-patterns` | UI work | Clerk, shadcn, Next.js patterns |

59| `api-patterns` | API route creation | Route structure, error handling |

60| `testing-patterns` | Writing tests | Jest, Playwright patterns |

61| `orchestration-patterns` | Multi-step work | Agent loop, evidence-based delivery |

62| `agent-coordination` | Multi-agent work | Assignment matrix, escalation patterns |

63| `team-coordination` | Agent Teams spawn | Multi-agent orchestration (experimental) |

65**Note**: `/skills` command has display bug (v2.0.73, GitHub #14733). Skills work but won't show in list. Ask Claude directly: "What skills are available?"

67## Success Validation Commands

69### Frontend Development

71```bash

72npm run type-check && npm run lint && npm run build && echo "FE SUCCESS" || echo "FE FAILED"

73```

75### Backend Development

77```bash

78npm run test:integration && echo "BE SUCCESS" || echo "BE FAILED"

79```

81### Documentation

83```bash

84npm run lint:md && echo "DOCS SUCCESS" || echo "DOCS FAILED"

85```

87### Pre-Push Validation

89```bash

90npm run ci:validate && echo "CI SUCCESS" || echo "CI FAILED"

91```

93### Database Migration

95```bash

96npx prisma migrate dev --name migration_name && echo "MIGRATION SUCCESS" || echo "MIGRATION FAILED"

97```

99## SAFe Specs-Driven Workflow

100

101### Planning Phase (BSA)

102

103```bash

104# Large initiative → Use planning template

105cp specs_templates/planning_template.md specs/{feature}-planning.md

106# Fill with Epic → Features → Stories → Enablers

107

108# User story → Use spec template

109cp specs_templates/spec_template.md specs/{{TICKET_PREFIX}}-XXX-{feature}-spec.md

110# Fill with implementation details

111```

112

113### Execution Phase (All Agents)

114

115```bash

116# 1. Read spec for clear goal

117cat specs/{{TICKET_PREFIX}}-XXX-{feature}-spec.md

118

119# 2. Extract:

120# - User story (goal)

121# - Acceptance criteria (success)

122# - Low-level tasks (steps)

123# - Demo script (validation)

124

125# 3. Implement using Simon's loop:

126# - Clear goal from spec

127# - Pattern discovery (codebase + specs)

128# - Iterate until demo script passes

129# - Escalate if blocked

130```

131

132## Pattern Discovery Protocol (MANDATORY)

133

134### 0. Search Specs Directory (FIRST)

135

136```bash

137# Find similar implementations in specs

138ls specs/*-spec.md | grep "similar_feature"

139

140# Review SAFe user stories

141grep -r "As a.*I want to" specs/

142

143# Check patterns from past specs

144cat specs/XXX-similar-spec.md

145```

146

147### 1. Search Codebase

148

149```bash

150# Search for similar functionality

151grep -r "feature_name|functionality" app/

152

153# Find existing helpers

154ls lib/ && grep -r "helper_pattern" lib/

155

156# Check components

157grep -r "component_pattern" components/

158```

159

160### 2. Search Session History

161

162```bash

163# Search agent session todos

164grep -r "similar_feature|pattern" ~/.claude/todos/ 2>/dev/null

165

166# Find recent implementation patterns

167ls -lt ~/.claude/todos/ | head -20

168```

169

170### 3. Consult Documentation

171

172- `CONTRIBUTING.md` - Workflow and git process

173- `docs/database/DATA_DICTIONARY.md` - Database schema (SINGLE SOURCE OF TRUTH)

174- `docs/database/RLS_IMPLEMENTATION_GUIDE.md` - Row Level Security (MANDATORY for DB ops)

175- `docs/security/SECURITY_FIRST_ARCHITECTURE.md` - Security patterns

176

177### 4. Architectural Validation

178

179- Propose pattern to System Architect

180- Get approval before implementation

181- Document decision in session notes

182

183## Agent Workflow

184

185### Standard Agent Loop (Per Simon Willison)

186

1871. **Clear Goal** - BSA defines with acceptance criteria

1882. **Pattern Discovery** - Search codebase and sessions

1893. **Iterative Problem Solving**:

190 - Implement approach

191 - Run validation command

192 - If fails → analyze error, adjust, repeat

193 - If blocked → escalate to TDM with context

1944. **Evidence Attachment** - Session ID + validation results in Linear

195

196### No Over-Engineering

197

198- ❌ No file locks

199- ❌ No circuit breakers

200- ❌ No arbitrary retry limits

201- ✅ Let agents iterate until success or blocked

202- ✅ Agent decides when to escalate

203

204## Session Archaeology

205

206### Monitor Concurrent Sessions

207

208```bash

209# See active sessions

210ls -lt ~/.claude/todos/*.json | head -10

211

212# Check for concurrent work on same files

213grep -l "file_path" ~/.claude/todos/*.json

214```

215

216### Cross-Agent Coordination

217

218```bash

219# Find related work by another agent

220grep -r "linear_ticket_number" ~/.claude/todos/

221

222# Discover implementation patterns

223grep -r "withUserContext|withAdminContext" ~/.claude/todos/

224```

225

226## Exit States (vNext Contract)

227

228Each agent has explicit exit states that define handoff points:

229

230```

231┌─────────────────┬───────────────────────────────────────────┐

232│ Role │ Exit State │

233├─────────────────┼───────────────────────────────────────────┤

234│ BE-Developer │ "Ready for QAS" │

235│ FE-Developer │ "Ready for QAS" │

236│ Data-Engineer │ "Ready for QAS" │

237│ QAS │ "Approved for RTE" │

238│ RTE │ "Ready for HITL Review" │

239│ System Architect│ "Stage 1 Approved - Ready for ARCHitect" │

240│ HITL │ MERGED │

241└─────────────────┴───────────────────────────────────────────┘

242```

243

244### Gate Quick Reference

245

246```

247┌─────────────────┬─────────────────┬─────────────────────────┐

248│ Gate │ Owner │ Blocking? │

249├─────────────────┼─────────────────┼─────────────────────────┤

250│ Stop-the-Line │ Implementer │ YES - no AC = no work │

251│ QAS Gate │ QAS │ YES - no approval = stop│

252│ Stage 1 Review │ System Architect│ YES - pattern check │

253│ Stage 2 Review │ ARCHitect-CLI │ YES - architecture check│

254│ HITL Merge │ {{AUTHOR_NAME}} │ YES - final authority │

255└─────────────────┴─────────────────┴─────────────────────────┘

256```

257

258### Role Collapsing ({{TICKET_PREFIX}}-499)

259

260- **RTE**: Collapsible (PR creation, CI shepherding can be done by implementer)

261- **QAS**: NOT collapsible (independence gate - spawn subagent for verification)

262- **SecEng**: NOT collapsible (security audit requires independence)

263

264See [Agent Workflow SOP v1.4](./docs/sop/AGENT_WORKFLOW_SOP.md) for details.

265

266### Agent Teams (Experimental)

267

268Agent Teams enable real-time multi-agent orchestration using Claude Code's experimental Agent Teams feature. When enabled, agents are spawned as teammates with shared task lists and SAFe quality gates enforced via task dependencies.

269

270- **Enable**: Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.json`

271- **Skill**: `/team-coordination` — patterns for TeamCreate, SendMessage, shared TaskList

272- **Guide**: See [Agent Teams Guide](docs/onboarding/AGENT-TEAMS-GUIDE.md) and [Optional Features](docs/guides/OPTIONAL-FEATURES.md)

273

274---

275

276## Quick Reference

277

278### Key Documentation

279

280- `CONTRIBUTING.md` - Complete workflow guide (MANDATORY READ)

281- `docs/database/DATA_DICTIONARY.md` - Database schema (SINGLE SOURCE OF TRUTH)

282- `docs/database/RLS_DATABASE_MIGRATION_SOP.md` - Schema changes (ARCHitect approval required)

283- `docs/security/SECURITY_FIRST_ARCHITECTURE.md` - Security patterns

284

285### Agent Files

286

287- `.claude/agents/bsa.md` - Business Systems Analyst

288- `.claude/agents/system-architect.md` - System Architect

289- `.claude/agents/tdm.md` - Technical Delivery Manager

290- `.claude/agents/fe-developer.md` - Frontend Developer

291- `.claude/agents/be-developer.md` - Backend Developer

292- `.claude/agents/data-engineer.md` - Data Engineer

293- `.claude/agents/data-provisioning-eng.md` - Data Provisioning Engineer

294- `.claude/agents/tech-writer.md` - Technical Writer

295- `.claude/agents/qas.md` - Quality Assurance Specialist

296- `.claude/agents/security-engineer.md` - Security Engineer

297- `.claude/agents/rte.md` - Release Train Engineer

298

299## Human-in-the-Loop (HITL) Model

300

301**Product Owner / Product Manager**: {{POPM_NAME}}

302

303- All work requires evidence in Linear before POPM review

304- Swimlane workflow: Backlog → Ready → In Progress → Testing → Ready for Review → Done

305- POPM has final approval on all deliverables

306

307---

308

309## 🎯 Agent Invocation Examples

310

311### Simple Invocation (Direct Mention)

312

313Use `@agent-name` for simple, single-step tasks:

314

315```bash

316# Planning

317@bsa Create a spec for user profile API endpoint

318@system-architect Review the RLS policy for user_profiles table

319

320# Implementation

321@be-developer Implement the GET /api/user/profile endpoint

322@fe-developer Create a UserProfile component with form validation

323@data-engineer Add email_verified column to users table

324

325# Quality & Documentation

326@qas Write integration tests for user profile feature

327@security-engineer Audit RLS policies for user_profiles table

328@tech-writer Document the user profile API in README

329

330# Coordination

331@tdm Coordinate implementation of {{TICKET_PREFIX}}-123 user profile feature

332@rte Create PR for {{TICKET_PREFIX}}-123 and run CI validation

333```

334

335### Task Tool Invocation (Complex Tasks)

336

337Use `Task()` for complex, multi-step tasks with detailed instructions:

338

339```typescript

340// BSA: Create comprehensive spec

341Task({

342 subagent_type: "bsa",

343 description: "Create spec for {{TICKET_PREFIX}}-123",

344 prompt: `Create comprehensive spec for {{TICKET_PREFIX}}-123 user profile feature.

345

346Requirements:

347- User can view and edit their profile

348- Profile includes: name, email, bio, avatar

349- Email verification required

350- Admin can view all profiles

351

352Please:

3531. Search for existing user/profile patterns in patterns_library/

3542. Create user story with acceptance criteria

3553. Define testing strategy (unit, integration, E2E)

3564. Add #EXPORT_CRITICAL tags for security requirements

3575. Reference relevant patterns from pattern library`,

358});

359

360// Backend Developer: Implement with pattern discovery

361Task({

362 subagent_type: "be-developer",

363 description: "Implement {{TICKET_PREFIX}}-123 API",

364 prompt: `Read spec at specs/{{TICKET_PREFIX}}-123-user-profile-spec.md

365

366Implement the user profile API endpoints:

3671. GET /api/user/profile - Get current user's profile

3682. PUT /api/user/profile - Update current user's profile

3693. GET /api/admin/users/:id/profile - Admin view any profile

370

371Requirements:

372- Use withUserContext for user endpoints

373- Use withAdminContext for admin endpoints

374- Follow RLS patterns from patterns_library/database/

375- Validate input with Zod schemas

376- Write unit tests for each endpoint

377

378Pattern discovery is MANDATORY before implementation.`,

379});

380

381// QAS: Execute comprehensive testing

382Task({

383 subagent_type: "qas",

384 description: "Test {{TICKET_PREFIX}}-123 feature",

385 prompt: `Read spec at specs/{{TICKET_PREFIX}}-123-user-profile-spec.md

386

387Execute the testing strategy defined by BSA:

388

3891. Unit Tests:

390 - Test Zod validation schemas

391 - Test RLS context helpers

392 - Test error handling

393

3942. Integration Tests:

395 - Test GET /api/user/profile with user context

396 - Test PUT /api/user/profile with valid/invalid data

397 - Test admin endpoints with admin context

398 - Test RLS isolation (user A cannot see user B's data)

399

4003. E2E Tests:

401 - User can view their profile

402 - User can edit their profile

403 - Admin can view any profile

404 - Unauthorized access is blocked

405

406Validate all acceptance criteria from the spec.`,

407});

408

409// TDM: Reactive blocker resolution (NOT orchestration)

410Task({

411 subagent_type: "tdm",

412 description: "Resolve blocker for {{TICKET_PREFIX}}-123",

413 prompt: `A blocker has been reported for {{TICKET_PREFIX}}-123.

414

415TDM Responsibilities (per v1.3 SOP):

4161. Monitor progress - read session archaeology, Linear, PR comments

4172. Identify blocker details - search for "FAILED|error|blocked"

4183. Escalate to appropriate specialist to resolve

4194. Track evidence - attach session IDs, test results to Linear

4205. Update Linear ticket with resolution

421

422NOTE: TDM is REACTIVE, not an orchestrator.

423ARCHitect-in-CLI is the primary orchestrator.`,

424});

425```

426

427### When to Use Which Invocation Method

428

429| Scenario | Method | Example |

430| ------------------------- | -------------- | --------------------------------------------------- |

431| **Simple question** | Direct mention | `@bsa What patterns exist for user authentication?` |

432| **Single-step task** | Direct mention | `@be-developer Add logging to the login endpoint` |

433| **Multi-step task** | Task tool | BSA creating spec with pattern discovery |

434| **Complex coordination** | Task tool | Multiple agents working on related features |

435| **Detailed requirements** | Task tool | QAS executing comprehensive test strategy |

436| **Blocker resolution** | Task tool | TDM investigating and escalating blockers |

437

438### Pro Tips

439

4401. **Always reference specs**: `Read spec at specs/{{TICKET_PREFIX}}-XXX-spec.md`

4412. **Mandate pattern discovery**: `Pattern discovery is MANDATORY before implementation`

4423. **Check #EXPORT_CRITICAL tags**: `Review #EXPORT_CRITICAL tags in spec first`

4434. **Validate with commands**: Use success validation commands from agent prompts

4445. **Update Linear**: TDM can update Linear with `mcp__{{MCP_LINEAR_SERVER}}__create_comment`

4456. **TDM is reactive**: Don't use TDM for orchestration—use ARCHitect-in-CLI

446

447---

448

449**Quick Start**: Read CONTRIBUTING.md, search codebase, propose to System Architect, validate with test command, attach evidence to Linear.

450

bybren-llc/safe-agentic-workflow · CLAUDE.md

@@ +1 @@

1# CLAUDE.md

3## AI Assistant Context for SAFe Multi-Agent Development

5**Repository**: {{PROJECT_NAME}}

6**Methodology**: SAFe (Scaled Agile Framework) Agentic Workflow

7**Philosophy**: "Round Table" - Equal voice, mutual respect, shared responsibility

9---

11## Quick Start

13This is a **SAFe multi-agent development project** with 11 specialized AI agents working collaboratively. You are part of a team where your input has equal weight with human contributors.

15**Core Principles**:

16- Search for existing patterns before creating new ones ("Search First, Reuse Always")

17- Attach evidence to Linear tickets for all work

18- You have "stop-the-line" authority for architectural/security concerns

19- Follow SAFe methodology: Epic → Feature → Story → Enabler

21**Key Resources**:

22- [AGENTS.md](AGENTS.md) - All 11 agent roles, invocation patterns, capabilities

23- [CONTRIBUTING.md](CONTRIBUTING.md) - Git workflow, commit standards, PR process

24- [docs/onboarding/](docs/onboarding/) - Setup guides and daily workflows

25- [docs/guides/ROUND-TABLE-PHILOSOPHY.md](docs/guides/ROUND-TABLE-PHILOSOPHY.md) - Collaboration principles

26- [patterns_library/](patterns_library/) - Reusable code patterns (18+ patterns, 7 categories)

27- [knowledge-vault/](knowledge-vault/README.md) - Evidence-verified knowledge base. To build this repo's own vault, run [SAW-VAULT-BUILD.md](knowledge-vault/docs/SAW-VAULT-BUILD.md)

29---

31## Development Commands

33```bash

34# Development server

35{{DEV_COMMAND}} # Start development server

37# Build and production

38{{BUILD_COMMAND}} # Build for production

39{{START_COMMAND}} # Start production server

41# Code quality

42{{LINT_COMMAND}} # Run linting

43{{LINT_FIX_COMMAND}} # Auto-fix linting issues

44{{TYPE_CHECK_COMMAND}} # TypeScript validation

45{{FORMAT_CHECK_COMMAND}} # Prettier formatting check

47# Testing

48{{TEST_UNIT_COMMAND}} # Run unit tests

49{{TEST_INTEGRATION_COMMAND}} # Run integration tests

50{{TEST_E2E_COMMAND}} # Run end-to-end tests

52# Database (if applicable)

53{{DB_MIGRATE_COMMAND}} # Run migrations

55# CI/CD validation (REQUIRED before PR)

56{{CI_VALIDATE_COMMAND}} # Run all quality checks

57```

59**Important**: Always run `{{CI_VALIDATE_COMMAND}}` before creating a pull request.

61---

63## Architecture Overview

65### Technology Stack

67- **Frontend**: {{FRONTEND_FRAMEWORK}}

68- **Backend**: {{BACKEND_FRAMEWORK}}

69- **Database**: {{DATABASE_SYSTEM}}

70- **ORM**: {{ORM_TOOL}}

71- **Authentication**: {{AUTH_PROVIDER}}

72- **Payments**: {{PAYMENT_PROVIDER}}

73- **Analytics**: {{ANALYTICS_PROVIDER}}

74- **UI Components**: {{UI_LIBRARY}}

76### Repository Structure

78```

79{{PROJECT_NAME}}/

80├── CLAUDE.md # This file - AI assistant context

81├── AGENTS.md # Agent team quick reference

82├── CONTRIBUTING.md # Git workflow and commit standards

83├── docs/ # Documentation (onboarding, database, security, sop, workflow)

84├── specs/ # SAFe specifications (Epic/Feature/Story)

85├── patterns_library/ # Reusable code patterns (7 categories)

86├── .claude/ # Claude Code harness (hooks, commands, skills, agents)

87├── agent_providers/ # Agent configurations

88└── scripts/ # Utility scripts

89```

91---

93## SAFe Workflow

95All work follows the SAFe hierarchy and specs-driven development:

971. BSA creates spec in `specs/{{TICKET_PREFIX}}-XXX-feature-spec.md`

982. System Architect validates architectural approach

993. Implementation agents execute with pattern discovery

1004. QAS validates against acceptance criteria

1015. Evidence attached to Linear ticket before POPM review

102

103### Metacognitive Tags

104

105Use in specs to highlight critical decisions:

106- `#PATH_DECISION` - Architectural path chosen (document alternatives)

107- `#PLAN_UNCERTAINTY` - Areas requiring validation

108- `#EXPORT_CRITICAL` - Security/compliance requirements

109

110### Pattern Discovery Protocol (MANDATORY)

111

112**Before implementing ANY feature:**

113

1141. Search `patterns_library/` for existing patterns

1152. Search `specs/` for similar specifications

1163. Search codebase for similar implementations

1174. Consult documentation: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/database/](docs/database/), [docs/security/](docs/security/)

1185. Propose to System Architect before implementation

119

120---

121

122## Project-Specific Implementation Notes

123

124*Customize this section for your technology stack.*

125

126### Authentication

127

128**Provider**: {{AUTH_PROVIDER}}

129

130- Environment variables: See `.env.template`

131- Routes: {{AUTH_ROUTES}} / {{PROTECTED_ROUTES}}

132- Patterns: `patterns_library/` + [docs/security/SECURITY_FIRST_ARCHITECTURE.md](docs/security/SECURITY_FIRST_ARCHITECTURE.md)

133

134### Payments

135

136**Provider**: {{PAYMENT_PROVIDER}}

137

138- Webhook endpoints: {{WEBHOOK_ROUTES}}

139- Patterns: `patterns_library/api/webhook-handler.md`

140- Idempotency required for all payment operations

141

142### Analytics

143

144**Provider**: {{ANALYTICS_PROVIDER}}

145

146- Privacy-first: No tracking without explicit consent (GDPR/CCPA)

147- Error boundaries: Analytics failures must not crash the app

148

149### Database

150

151**System**: {{DATABASE_SYSTEM}} | **ORM**: {{ORM_TOOL}}

152

153**Guidelines**:

154- Always use ORM (type safety) with RLS context helpers (`withUserContext`, `withAdminContext`, `withSystemContext`)

155- Always create proper migrations (never `db push` in production)

156- Never use direct SQL or bypass RLS policies

157

158**Schema Docs**: [docs/database/DATA_DICTIONARY.md](docs/database/DATA_DICTIONARY.md) (single source of truth)

159

160**Migration Workflow**:

161```bash

162{{MIGRATION_CREATE_COMMAND}} # Create migration

163{{MIGRATION_TEST_COMMAND}} # Test locally

164git add {{MIGRATIONS_DIR}}/ && git commit -m "feat(db): add feature migration"

165{{MIGRATION_DEPLOY_COMMAND}} # Deploy to production

166```

167

168---

169

170## Code Quality

171

172**Linter**: {{LINTER_TOOL}} | **Config**: {{LINTER_CONFIG_FORMAT}}

173

174```bash

175{{LINT_COMMAND}} # Run linter

176{{LINT_FIX_COMMAND}} # Auto-fix issues

177```

178

179Always run `{{LINT_COMMAND}}` before committing. Consult your linting configuration file for project-specific rules.

180

181---

182

183## CI/CD Pipeline

184

185**MANDATORY**: Read [CONTRIBUTING.md](CONTRIBUTING.md) before any development.

186

187### PR Workflow

188

1891. Create feature branch: `{{TICKET_PREFIX}}-{number}-{description}`

1902. Implement with proper commits: `type(scope): description [{{TICKET_PREFIX}}-XXX]`

1913. Rebase: `git rebase origin/{{MAIN_BRANCH}}`

1924. Validate: `{{CI_VALIDATE_COMMAND}}` (must pass)

1935. Push: `git push --force-with-lease`

1946. Create PR using `.github/pull_request_template.md`

1957. Merge using "Rebase and merge" only

196

197### Branch Protection

198

199- All PRs must be up-to-date with `{{MAIN_BRANCH}}`

200- All CI checks must pass

201- CODEOWNERS reviewers required

202- No direct pushes to `{{MAIN_BRANCH}}`

203

204**Detailed Guides**: [docs/ci-cd/CI-CD-Pipeline-Guide.md](docs/ci-cd/CI-CD-Pipeline-Guide.md) | [docs/workflow/](docs/workflow/)

205

@@ −1 +1 @@

1−# SAFe Agent Team Quick Reference

1+# CLAUDE.md

3−> **Philosophy**: "Search First, Reuse Always, Create Only When Necessary"

4−>

5−> Pattern discovery is MANDATORY before implementation.

6−>

7−> **Team Culture**: "We work as a round table team that has 4 pillars of SAFe inscribed on that round table. It means something."

3+## AI Assistant Context for SAFe Multi-Agent Development

9−## Documentation

5+**Repository**: {{PROJECT_NAME}}

6+**Methodology**: SAFe (Scaled Agile Framework) Agentic Workflow

7+**Philosophy**: "Round Table" - Equal voice, mutual respect, shared responsibility

108

11−**Workflow SOPs:**

9+---

1210

13−- [Agent Workflow SOP v1.4](./docs/sop/AGENT_WORKFLOW_SOP.md) - vNext contract, Exit States, Role Collapsing ({{TICKET_PREFIX}}-497/499)

14−- [Agent Configuration SOP](./docs/sop/AGENT_CONFIGURATION_SOP.md) - Tool restrictions, model selection

15−- [ARCHitect-in-CLI Role](./docs/workflow/ARCHITECT_IN_CLI_ROLE.md) - Primary orchestrator definition

11+## Quick Start

1612

17−**CI/CD Documentation:**

13+This is a **SAFe multi-agent development project** with 11 specialized AI agents working collaboratively. You are part of a team where your input has equal weight with human contributors.

1814

19−- [CI/CD Pipeline Guide](./docs/ci-cd/CI-CD-Pipeline-Guide.md) - Pipeline implementation guide

15+**Core Principles**:

16+- Search for existing patterns before creating new ones ("Search First, Reuse Always")

17+- Attach evidence to Linear tickets for all work

18+- You have "stop-the-line" authority for architectural/security concerns

19+- Follow SAFe methodology: Epic → Feature → Story → Enabler

2020

21−**Database SOPs:**

21+**Key Resources**:

22+- [AGENTS.md](AGENTS.md) - All 11 agent roles, invocation patterns, capabilities

23+- [CONTRIBUTING.md](CONTRIBUTING.md) - Git workflow, commit standards, PR process

24+- [docs/onboarding/](docs/onboarding/) - Setup guides and daily workflows

25+- [docs/guides/ROUND-TABLE-PHILOSOPHY.md](docs/guides/ROUND-TABLE-PHILOSOPHY.md) - Collaboration principles

26+- [patterns_library/](patterns_library/) - Reusable code patterns (18+ patterns, 7 categories)

27+- [knowledge-vault/](knowledge-vault/README.md) - Evidence-verified knowledge base. To build this repo's own vault, run [SAW-VAULT-BUILD.md](knowledge-vault/docs/SAW-VAULT-BUILD.md)

2228

23−- [RLS Migration SOP](./docs/database/RLS_DATABASE_MIGRATION_SOP.md) - MANDATORY for Data Engineer

29+---

2430

25−**Project Standards:**

31+## Development Commands

2632

27−- [Harness Whitepapers](./docs/whitepapers/) - Architecture, research alignment, and evidence

28−- [Agent Perspective](./docs/whitepapers/CLAUDE-CODE-HARNESS-AGENT-PERSPECTIVE.md) - Why the harness works

29−- [SAFe Methodology](https://github.com/{{GITHUB_ORG}}/{{PROJECT_REPO}}) - This repository

33+```bash

34+# Development server

35+{{DEV_COMMAND}} # Start development server

3036

31−## When to Use Which Agent

37+# Build and production

38+{{BUILD_COMMAND}} # Build for production

39+{{START_COMMAND}} # Start production server

3240

34−| ------------------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------- |

35−| **TDM** (Technical Delivery Manager) | Reactive blocker resolution, Linear updates, evidence tracking (NOT orchestration - see v1.3 SOP) | Blockers resolved, evidence attached, Linear updated | Linear, Confluence |

41+# Code quality

42+{{LINT_COMMAND}} # Run linting

43+{{LINT_FIX_COMMAND}} # Auto-fix linting issues

44+{{TYPE_CHECK_COMMAND}} # TypeScript validation

45+{{FORMAT_CHECK_COMMAND}} # Prettier formatting check

4646

47−## Auto-Loaded Skills

47+# Testing

48+{{TEST_UNIT_COMMAND}} # Run unit tests

49+{{TEST_INTEGRATION_COMMAND}} # Run integration tests

50+{{TEST_E2E_COMMAND}} # Run end-to-end tests

4851

49−Skills are loaded progressively—metadata at startup, full content when context triggers.

52+# Database (if applicable)

53+{{DB_MIGRATE_COMMAND}} # Run migrations

5054

51−| Skill | Trigger | Purpose |

52−| ------------------------ | ---------------------- | ------------------------------------------- |

53−| `safe-workflow` | Commits, branches, PRs | SAFe format, rebase-first workflow |

54−| `safe-ai-dlc` | Multi-issue programs | Bolts, Units of Work, HITL gate |

55−| `vault-sync` | Knowledge vault drift | Detect staleness, regenerate, record |

56−| `pattern-discovery` | Before writing code | Pattern-first development (MANDATORY) |

57−| `rls-patterns` | Database operations | RLS context helpers (withUserContext, etc.) |

58−| `frontend-patterns` | UI work | Clerk, shadcn, Next.js patterns |

59−| `api-patterns` | API route creation | Route structure, error handling |

60−| `testing-patterns` | Writing tests | Jest, Playwright patterns |

61−| `orchestration-patterns` | Multi-step work | Agent loop, evidence-based delivery |

62−| `agent-coordination` | Multi-agent work | Assignment matrix, escalation patterns |

63−| `team-coordination` | Agent Teams spawn | Multi-agent orchestration (experimental) |

64−

65−**Note**: `/skills` command has display bug (v2.0.73, GitHub #14733). Skills work but won't show in list. Ask Claude directly: "What skills are available?"

66−

67−## Success Validation Commands

68−

69−### Frontend Development

70−

71−```bash

72−npm run type-check && npm run lint && npm run build && echo "FE SUCCESS" || echo "FE FAILED"

55+# CI/CD validation (REQUIRED before PR)

56+{{CI_VALIDATE_COMMAND}} # Run all quality checks

7357 ```

7458

75−### Backend Development

59+**Important**: Always run `{{CI_VALIDATE_COMMAND}}` before creating a pull request.

7660

77−```bash

78−npm run test:integration && echo "BE SUCCESS" || echo "BE FAILED"

79−```

61+---

8062

81−### Documentation

63+## Architecture Overview

8264

83−```bash

84−npm run lint:md && echo "DOCS SUCCESS" || echo "DOCS FAILED"

85−```

65+### Technology Stack

8666

87−### Pre-Push Validation

67+- **Frontend**: {{FRONTEND_FRAMEWORK}}

68+- **Backend**: {{BACKEND_FRAMEWORK}}

69+- **Database**: {{DATABASE_SYSTEM}}

70+- **ORM**: {{ORM_TOOL}}

71+- **Authentication**: {{AUTH_PROVIDER}}

72+- **Payments**: {{PAYMENT_PROVIDER}}

73+- **Analytics**: {{ANALYTICS_PROVIDER}}

74+- **UI Components**: {{UI_LIBRARY}}

8875

89−```bash

90−npm run ci:validate && echo "CI SUCCESS" || echo "CI FAILED"

91−```

76+### Repository Structure

9277

93−### Database Migration

94−

95−```bash

96−npx prisma migrate dev --name migration_name && echo "MIGRATION SUCCESS" || echo "MIGRATION FAILED"

9778 ```

98−

99−## SAFe Specs-Driven Workflow

100−

101−### Planning Phase (BSA)

102−

103−```bash

104−# Large initiative → Use planning template

105−cp specs_templates/planning_template.md specs/{feature}-planning.md

106−# Fill with Epic → Features → Stories → Enablers

107−

108−# User story → Use spec template

109−cp specs_templates/spec_template.md specs/{{TICKET_PREFIX}}-XXX-{feature}-spec.md

110−# Fill with implementation details

79+{{PROJECT_NAME}}/

80+├── CLAUDE.md # This file - AI assistant context

81+├── AGENTS.md # Agent team quick reference

82+├── CONTRIBUTING.md # Git workflow and commit standards

83+├── docs/ # Documentation (onboarding, database, security, sop, workflow)

84+├── specs/ # SAFe specifications (Epic/Feature/Story)

85+├── patterns_library/ # Reusable code patterns (7 categories)

86+├── .claude/ # Claude Code harness (hooks, commands, skills, agents)

87+├── agent_providers/ # Agent configurations

88+└── scripts/ # Utility scripts

11189 ```

11290

113−### Execution Phase (All Agents)

91+---

11492

115−```bash

116−# 1. Read spec for clear goal

117−cat specs/{{TICKET_PREFIX}}-XXX-{feature}-spec.md

93+## SAFe Workflow

11894

119−# 2. Extract:

120−# - User story (goal)

121−# - Acceptance criteria (success)

122−# - Low-level tasks (steps)

123−# - Demo script (validation)

95+All work follows the SAFe hierarchy and specs-driven development:

12496

125−# 3. Implement using Simon's loop:

126−# - Clear goal from spec

127−# - Pattern discovery (codebase + specs)

128−# - Iterate until demo script passes

129−# - Escalate if blocked

130−```

97+1. BSA creates spec in `specs/{{TICKET_PREFIX}}-XXX-feature-spec.md`

98+2. System Architect validates architectural approach

99+3. Implementation agents execute with pattern discovery

100+4. QAS validates against acceptance criteria

101+5. Evidence attached to Linear ticket before POPM review

131102

132−## Pattern Discovery Protocol (MANDATORY)

103+### Metacognitive Tags

133104

134−### 0. Search Specs Directory (FIRST)

105+Use in specs to highlight critical decisions:

106+- `#PATH_DECISION` - Architectural path chosen (document alternatives)

107+- `#PLAN_UNCERTAINTY` - Areas requiring validation

108+- `#EXPORT_CRITICAL` - Security/compliance requirements

135109

136−```bash

137−# Find similar implementations in specs

138−ls specs/*-spec.md | grep "similar_feature"

110+### Pattern Discovery Protocol (MANDATORY)

139111

140−# Review SAFe user stories

141−grep -r "As a.*I want to" specs/

112+**Before implementing ANY feature:**

142113

143−# Check patterns from past specs

144−cat specs/XXX-similar-spec.md

145−```

114+1. Search `patterns_library/` for existing patterns

115+2. Search `specs/` for similar specifications

116+3. Search codebase for similar implementations

117+4. Consult documentation: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/database/](docs/database/), [docs/security/](docs/security/)

118+5. Propose to System Architect before implementation

146119

147−### 1. Search Codebase

120+---

148121

149−```bash

150−# Search for similar functionality

151−grep -r "feature_name|functionality" app/

122+## Project-Specific Implementation Notes

152123

153−# Find existing helpers

154−ls lib/ && grep -r "helper_pattern" lib/

124+*Customize this section for your technology stack.*

155125

156−# Check components

157−grep -r "component_pattern" components/

158−```

126+### Authentication

159127

160−### 2. Search Session History

128+**Provider**: {{AUTH_PROVIDER}}

161129

162−```bash

163−# Search agent session todos

164−grep -r "similar_feature|pattern" ~/.claude/todos/ 2>/dev/null

130+- Environment variables: See `.env.template`

131+- Routes: {{AUTH_ROUTES}} / {{PROTECTED_ROUTES}}

132+- Patterns: `patterns_library/` + [docs/security/SECURITY_FIRST_ARCHITECTURE.md](docs/security/SECURITY_FIRST_ARCHITECTURE.md)

165133

166−# Find recent implementation patterns

167−ls -lt ~/.claude/todos/ | head -20

168−```

134+### Payments

169135

170−### 3. Consult Documentation

136+**Provider**: {{PAYMENT_PROVIDER}}

171137

172−- `CONTRIBUTING.md` - Workflow and git process

173−- `docs/database/DATA_DICTIONARY.md` - Database schema (SINGLE SOURCE OF TRUTH)

174−- `docs/database/RLS_IMPLEMENTATION_GUIDE.md` - Row Level Security (MANDATORY for DB ops)

175−- `docs/security/SECURITY_FIRST_ARCHITECTURE.md` - Security patterns

138+- Webhook endpoints: {{WEBHOOK_ROUTES}}

139+- Patterns: `patterns_library/api/webhook-handler.md`

140+- Idempotency required for all payment operations

176141

177−### 4. Architectural Validation

142+### Analytics

178143

179−- Propose pattern to System Architect

180−- Get approval before implementation

181−- Document decision in session notes

144+**Provider**: {{ANALYTICS_PROVIDER}}

182145

183−## Agent Workflow

146+- Privacy-first: No tracking without explicit consent (GDPR/CCPA)

147+- Error boundaries: Analytics failures must not crash the app

184148

185−### Standard Agent Loop (Per Simon Willison)

149+### Database

186150

187−1. **Clear Goal** - BSA defines with acceptance criteria

188−2. **Pattern Discovery** - Search codebase and sessions

189−3. **Iterative Problem Solving**:

190− - Implement approach

191− - Run validation command

192− - If fails → analyze error, adjust, repeat

193− - If blocked → escalate to TDM with context

194−4. **Evidence Attachment** - Session ID + validation results in Linear

151+**System**: {{DATABASE_SYSTEM}} | **ORM**: {{ORM_TOOL}}

195152

196−### No Over-Engineering

153+**Guidelines**:

154+- Always use ORM (type safety) with RLS context helpers (`withUserContext`, `withAdminContext`, `withSystemContext`)

155+- Always create proper migrations (never `db push` in production)

156+- Never use direct SQL or bypass RLS policies

197157

198−- ❌ No file locks

199−- ❌ No circuit breakers

200−- ❌ No arbitrary retry limits

201−- ✅ Let agents iterate until success or blocked

202−- ✅ Agent decides when to escalate

158+**Schema Docs**: [docs/database/DATA_DICTIONARY.md](docs/database/DATA_DICTIONARY.md) (single source of truth)

203159

204−## Session Archaeology

205−

206−### Monitor Concurrent Sessions

207−

160+**Migration Workflow**:

208161 ```bash

209−# See active sessions

210−ls -lt ~/.claude/todos/*.json | head -10

211−

212−# Check for concurrent work on same files

213−grep -l "file_path" ~/.claude/todos/*.json

162+{{MIGRATION_CREATE_COMMAND}} # Create migration

163+{{MIGRATION_TEST_COMMAND}} # Test locally

164+git add {{MIGRATIONS_DIR}}/ && git commit -m "feat(db): add feature migration"

165+{{MIGRATION_DEPLOY_COMMAND}} # Deploy to production

214166 ```

215167

216−### Cross-Agent Coordination

217−

218−```bash

219−# Find related work by another agent

220−grep -r "linear_ticket_number" ~/.claude/todos/

221−

222−# Discover implementation patterns

223−grep -r "withUserContext|withAdminContext" ~/.claude/todos/

224−```

225−

226−## Exit States (vNext Contract)

227−

228−Each agent has explicit exit states that define handoff points:

229−

230−```

231−┌─────────────────┬───────────────────────────────────────────┐

232−│ Role │ Exit State │

233−├─────────────────┼───────────────────────────────────────────┤

234−│ BE-Developer │ "Ready for QAS" │

235−│ FE-Developer │ "Ready for QAS" │

236−│ Data-Engineer │ "Ready for QAS" │

237−│ QAS │ "Approved for RTE" │

238−│ RTE │ "Ready for HITL Review" │

239−│ System Architect│ "Stage 1 Approved - Ready for ARCHitect" │

240−│ HITL │ MERGED │

241−└─────────────────┴───────────────────────────────────────────┘

242−```

243−

244−### Gate Quick Reference

245−

246−```

247−┌─────────────────┬─────────────────┬─────────────────────────┐

248−│ Gate │ Owner │ Blocking? │

249−├─────────────────┼─────────────────┼─────────────────────────┤

250−│ Stop-the-Line │ Implementer │ YES - no AC = no work │

251−│ QAS Gate │ QAS │ YES - no approval = stop│

252−│ Stage 1 Review │ System Architect│ YES - pattern check │

253−│ Stage 2 Review │ ARCHitect-CLI │ YES - architecture check│

254−│ HITL Merge │ {{AUTHOR_NAME}} │ YES - final authority │

255−└─────────────────┴─────────────────┴─────────────────────────┘

256−```

257−

258−### Role Collapsing ({{TICKET_PREFIX}}-499)

259−

260−- **RTE**: Collapsible (PR creation, CI shepherding can be done by implementer)

261−- **QAS**: NOT collapsible (independence gate - spawn subagent for verification)

262−- **SecEng**: NOT collapsible (security audit requires independence)

263−

264−See [Agent Workflow SOP v1.4](./docs/sop/AGENT_WORKFLOW_SOP.md) for details.

265−

266−### Agent Teams (Experimental)

267−

268−Agent Teams enable real-time multi-agent orchestration using Claude Code's experimental Agent Teams feature. When enabled, agents are spawned as teammates with shared task lists and SAFe quality gates enforced via task dependencies.

269−

270−- **Enable**: Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.json`

271−- **Skill**: `/team-coordination` — patterns for TeamCreate, SendMessage, shared TaskList

272−- **Guide**: See [Agent Teams Guide](docs/onboarding/AGENT-TEAMS-GUIDE.md) and [Optional Features](docs/guides/OPTIONAL-FEATURES.md)

273−

274168 ---

275169

276−## Quick Reference

170+## Code Quality

277171

278−### Key Documentation

172+**Linter**: {{LINTER_TOOL}} | **Config**: {{LINTER_CONFIG_FORMAT}}

279173

280−- `CONTRIBUTING.md` - Complete workflow guide (MANDATORY READ)

281−- `docs/database/DATA_DICTIONARY.md` - Database schema (SINGLE SOURCE OF TRUTH)

282−- `docs/database/RLS_DATABASE_MIGRATION_SOP.md` - Schema changes (ARCHitect approval required)

283−- `docs/security/SECURITY_FIRST_ARCHITECTURE.md` - Security patterns

284−

285−### Agent Files

286−

287−- `.claude/agents/bsa.md` - Business Systems Analyst

288−- `.claude/agents/system-architect.md` - System Architect

289−- `.claude/agents/tdm.md` - Technical Delivery Manager

290−- `.claude/agents/fe-developer.md` - Frontend Developer

291−- `.claude/agents/be-developer.md` - Backend Developer

292−- `.claude/agents/data-engineer.md` - Data Engineer

293−- `.claude/agents/data-provisioning-eng.md` - Data Provisioning Engineer

294−- `.claude/agents/tech-writer.md` - Technical Writer

295−- `.claude/agents/qas.md` - Quality Assurance Specialist

296−- `.claude/agents/security-engineer.md` - Security Engineer

297−- `.claude/agents/rte.md` - Release Train Engineer

298−

299−## Human-in-the-Loop (HITL) Model

300−

301−**Product Owner / Product Manager**: {{POPM_NAME}}

302−

303−- All work requires evidence in Linear before POPM review

304−- Swimlane workflow: Backlog → Ready → In Progress → Testing → Ready for Review → Done

305−- POPM has final approval on all deliverables

306−

307−---

308−

309−## 🎯 Agent Invocation Examples

310−

311−### Simple Invocation (Direct Mention)

312−

313−Use `@agent-name` for simple, single-step tasks:

314−

315174 ```bash

316−# Planning

317−@bsa Create a spec for user profile API endpoint

318−@system-architect Review the RLS policy for user_profiles table

319−

320−# Implementation

321−@be-developer Implement the GET /api/user/profile endpoint

322−@fe-developer Create a UserProfile component with form validation

323−@data-engineer Add email_verified column to users table

324−

325−# Quality & Documentation

326−@qas Write integration tests for user profile feature

327−@security-engineer Audit RLS policies for user_profiles table

328−@tech-writer Document the user profile API in README

329−

330−# Coordination

331−@tdm Coordinate implementation of {{TICKET_PREFIX}}-123 user profile feature

332−@rte Create PR for {{TICKET_PREFIX}}-123 and run CI validation

175+{{LINT_COMMAND}} # Run linter

176+{{LINT_FIX_COMMAND}} # Auto-fix issues

333177 ```

334178

335−### Task Tool Invocation (Complex Tasks)

179+Always run `{{LINT_COMMAND}}` before committing. Consult your linting configuration file for project-specific rules.

336180

337−Use `Task()` for complex, multi-step tasks with detailed instructions:

181+---

338182

339−```typescript

340−// BSA: Create comprehensive spec

341−Task({

342− subagent_type: "bsa",

343− description: "Create spec for {{TICKET_PREFIX}}-123",

344− prompt: `Create comprehensive spec for {{TICKET_PREFIX}}-123 user profile feature.

183+## CI/CD Pipeline

345184

346−Requirements:

347−- User can view and edit their profile

348−- Profile includes: name, email, bio, avatar

349−- Email verification required

350−- Admin can view all profiles

185+**MANDATORY**: Read [CONTRIBUTING.md](CONTRIBUTING.md) before any development.

351186

352−Please:

353−1. Search for existing user/profile patterns in patterns_library/

354−2. Create user story with acceptance criteria

355−3. Define testing strategy (unit, integration, E2E)

356−4. Add #EXPORT_CRITICAL tags for security requirements

357−5. Reference relevant patterns from pattern library`,

358−});

187+### PR Workflow

359188

360−// Backend Developer: Implement with pattern discovery

361−Task({

362− subagent_type: "be-developer",

363− description: "Implement {{TICKET_PREFIX}}-123 API",

364− prompt: `Read spec at specs/{{TICKET_PREFIX}}-123-user-profile-spec.md

189+1. Create feature branch: `{{TICKET_PREFIX}}-{number}-{description}`

190+2. Implement with proper commits: `type(scope): description [{{TICKET_PREFIX}}-XXX]`

191+3. Rebase: `git rebase origin/{{MAIN_BRANCH}}`

192+4. Validate: `{{CI_VALIDATE_COMMAND}}` (must pass)

193+5. Push: `git push --force-with-lease`

194+6. Create PR using `.github/pull_request_template.md`

195+7. Merge using "Rebase and merge" only

365196

366−Implement the user profile API endpoints:

367−1. GET /api/user/profile - Get current user's profile

368−2. PUT /api/user/profile - Update current user's profile

369−3. GET /api/admin/users/:id/profile - Admin view any profile

197+### Branch Protection

370198

371−Requirements:

372−- Use withUserContext for user endpoints

373−- Use withAdminContext for admin endpoints

374−- Follow RLS patterns from patterns_library/database/

375−- Validate input with Zod schemas

376−- Write unit tests for each endpoint

199+- All PRs must be up-to-date with `{{MAIN_BRANCH}}`

200+- All CI checks must pass

201+- CODEOWNERS reviewers required

202+- No direct pushes to `{{MAIN_BRANCH}}`

377203

378−Pattern discovery is MANDATORY before implementation.`,

379−});

380−

381−// QAS: Execute comprehensive testing

382−Task({

383− subagent_type: "qas",

384− description: "Test {{TICKET_PREFIX}}-123 feature",

385− prompt: `Read spec at specs/{{TICKET_PREFIX}}-123-user-profile-spec.md

386−

387−Execute the testing strategy defined by BSA:

388−

389−1. Unit Tests:

390− - Test Zod validation schemas

391− - Test RLS context helpers

392− - Test error handling

393−

394−2. Integration Tests:

395− - Test GET /api/user/profile with user context

396− - Test PUT /api/user/profile with valid/invalid data

397− - Test admin endpoints with admin context

398− - Test RLS isolation (user A cannot see user B's data)

399−

400−3. E2E Tests:

401− - User can view their profile

402− - User can edit their profile

403− - Admin can view any profile

404− - Unauthorized access is blocked

405−

406−Validate all acceptance criteria from the spec.`,

407−});

408−

409−// TDM: Reactive blocker resolution (NOT orchestration)

410−Task({

411− subagent_type: "tdm",

412− description: "Resolve blocker for {{TICKET_PREFIX}}-123",

413− prompt: `A blocker has been reported for {{TICKET_PREFIX}}-123.

414−

415−TDM Responsibilities (per v1.3 SOP):

416−1. Monitor progress - read session archaeology, Linear, PR comments

417−2. Identify blocker details - search for "FAILED|error|blocked"

418−3. Escalate to appropriate specialist to resolve

419−4. Track evidence - attach session IDs, test results to Linear

420−5. Update Linear ticket with resolution

421−

422−NOTE: TDM is REACTIVE, not an orchestrator.

423−ARCHitect-in-CLI is the primary orchestrator.`,

424−});

425−```

426−

427−### When to Use Which Invocation Method

428−

429−| Scenario | Method | Example |

430−| ------------------------- | -------------- | --------------------------------------------------- |

431−| **Simple question** | Direct mention | `@bsa What patterns exist for user authentication?` |

432−| **Single-step task** | Direct mention | `@be-developer Add logging to the login endpoint` |

433−| **Multi-step task** | Task tool | BSA creating spec with pattern discovery |

434−| **Complex coordination** | Task tool | Multiple agents working on related features |

435−| **Detailed requirements** | Task tool | QAS executing comprehensive test strategy |

436−| **Blocker resolution** | Task tool | TDM investigating and escalating blockers |

437−

438−### Pro Tips

439−

440−1. **Always reference specs**: `Read spec at specs/{{TICKET_PREFIX}}-XXX-spec.md`

441−2. **Mandate pattern discovery**: `Pattern discovery is MANDATORY before implementation`

442−3. **Check #EXPORT_CRITICAL tags**: `Review #EXPORT_CRITICAL tags in spec first`

443−4. **Validate with commands**: Use success validation commands from agent prompts

444−5. **Update Linear**: TDM can update Linear with `mcp__{{MCP_LINEAR_SERVER}}__create_comment`

445−6. **TDM is reactive**: Don't use TDM for orchestration—use ARCHitect-in-CLI

446−

447−---

448−

449−**Quick Start**: Read CONTRIBUTING.md, search codebase, propose to System Architect, validate with test command, attach evidence to Linear.

204+**Detailed Guides**: [docs/ci-cd/CI-CD-Pipeline-Guide.md](docs/ci-cd/CI-CD-Pipeline-Guide.md) | [docs/workflow/](docs/workflow/)

450205

Two files, one repository

Built for the same person as RuleStack