37 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is DocuSeal - an open-source document filling and signing platform built with Ruby on Rails. The codebase is a brownfield Rails 7 application that provides secure digital document signing with PDF form building, multi-signer workflows, and API/webhook integrations.

Tech Stack

Backend:

Ruby 3.4.2, Rails 7.x
PostgreSQL/MySQL/SQLite (via DATABASE_URL)
Sidekiq for background jobs
Devise for authentication with 2FA support
Cancancan for authorization
HexaPDF for PDF generation and signing

Frontend:

Vue.js 3 with Composition API
TailwindCSS 3.4.17 + DaisyUI 3.9.4
Shakapacker 8.0 (Webpack)
Hotwire Turbo for Rails UJS

Storage:

Active Storage with S3, Google Cloud, Azure, or local disk
Supports multiple storage backends simultaneously

Common Commands

Development

# Start development server
bin/rails server

# Start with foreman (includes Sidekiq)
bundle exec foreman start -f Procfile.dev

# Run specific test
bundle exec rspec spec/path/to/spec.rb:line_number

# Run all tests
bundle exec rspec

# Lint Ruby
bundle exec rubocop -A

# Lint JavaScript/Vue
yarn eslint app/javascript/**/*.{js,vue} --fix

# Run database migrations
bin/rails db:migrate

# Setup database from scratch
bin/rails db:setup

Git Commit Guidelines

IMPORTANT: When committing changes, follow these rules:

# ✅ CORRECT - Simple commit message
git commit -m "Add Story 1.1: Database Schema Extension"

# ❌ INCORRECT - Do NOT add Co-Authored-By
git commit -m "Add Story 1.1: Database Schema Extension

Co-Authored-By: Claude <noreply@anthropic.com>"

Rules:

✅ Use simple, descriptive commit messages
✅ Format: git commit -m "Add Story X.X: [Story Title]"
✅ Include story summary in commit body (optional)
❌ NEVER add Co-Authored-By: Claude <noreply@anthropic.com> or similar
❌ NEVER add AI assistant attribution in commit messages
✅ One story per commit for traceability

Production

# Precompile assets
bin/rails assets:precompile

# Start production server
bundle exec puma -C config/puma.rb

# With Docker
docker run --name docuseal -p 3000:3000 -v.:/data docuseal/docuseal

Architecture

Core Models Hierarchy

Account (Tenant/Organization)
├── Users (Devise authentication)
├── Templates (Document templates with form fields)
│   ├── TemplateDocuments (PDF files)
│   └── TemplateFolders (Organization)
├── Submissions (Completed document workflows)
│   ├── Submitters (Signers/participants)
│   ├── CompletedDocuments (Final PDFs)
│   └── SubmissionEvents (Audit trail)
└── AccountConfig (Settings)

Key Concepts

Templates:

WYSIWYG PDF form builder with 12 field types (Signature, Date, File, Checkbox, etc.)
Supports PDF upload or HTML-based template creation
Multiple submitters per template
Field tagging system for dynamic content

Submissions:

Multi-signer document workflows
State tracking (pending → completed)
Email notifications and reminders
Document generation and signing

Submitters:

Individual participants in a submission
Can fill and sign specific fields
Receive email invitations and reminders
Support for 2FA and identity verification

Directory Structure

app/models/ - Core business logic

submission.rb, submitter.rb, template.rb - Main entities
user.rb, account.rb - Authentication and multi-tenancy
All models inherit from ApplicationRecord with strip_attributes

app/controllers/ - Request handling

RESTful controllers for templates, submissions, submitters
API controllers under app/controllers/api/
Settings controllers for user/account configuration

app/javascript/ - Frontend code

application.js - Main entry point with Vue app initialization
template_builder/ - PDF form builder UI
elements/ - Custom web components (Web Components + Vue)
submission_form/ - Multi-step signing interface

lib/ - Utility modules

submissions.rb, submitters.rb - Business logic helpers
pdf_utils.rb, pdfium.rb - PDF processing
send_webhook_request.rb - Webhook handling

config/ - Rails configuration

routes.rb - Main routing (includes API routes)
database.yml - Database configuration
shakapacker.yml - Webpack configuration

Authentication & Authorization

Authentication:

Devise with modules: database_authenticatable, registerable, recoverable, rememberable, validatable, omniauthable, two_factor_authenticatable
JWT tokens for API access
OAuth support via omniauth

Authorization:

Cancancan with Ability class
Role-based access control via AccountAccess model
Template and submission sharing via TemplateSharing

PDF Processing

HexaPDF is used for:

PDF generation from templates
Form field rendering
Digital signature embedding
Signature verification

PDFium provides:

PDF rendering and preview
Document manipulation
Multi-page handling

API Structure

Base URL: /api/v1/

Key Endpoints:

POST /templates - Create template
POST /submissions - Start submission workflow
GET /submissions/:id - Get submission status
POST /submitters/:id/complete - Complete submitter workflow
POST /webhooks - Webhook events

Authentication: Bearer token in Authorization header

Webhooks

Events:

submission.created - New submission started
submission.completed - All signers finished
submitter.completed - Individual signer finished
template.created - New template

Delivery: POST to configured URLs with JSON payload, retry with exponential backoff

Background Jobs (Sidekiq)

Queues:

default - General tasks
mailers - Email delivery
webhooks - Webhook delivery
pdf - PDF generation

Key Jobs:

SubmissionEmailJob - Send submission invitations
ReminderJob - Send reminder emails
WebhookDeliveryJob - Deliver webhook events
DocumentGenerationJob - Generate final PDFs

Database Schema

Core Tables:

accounts - Multi-tenancy root
users - Devise authentication
templates - Document templates
submissions - Document workflows
submitters - Signers/participants
completed_documents - Final signed PDFs
template_documents - Template PDF files

Supporting Tables:

account_access - User permissions
template_sharing - Template sharing links
submission_events - Audit trail
webhook_events - Webhook delivery tracking
email_events - Email delivery tracking

Configuration

Environment Variables:

DATABASE_URL - Database connection
SECRET_KEY_BASE - Rails secrets
AWS_*, GOOGLE_*, AZURE_* - Storage configs
SMTP_* - Email delivery
REDIS_URL - Sidekiq backend

Feature Flags:

Docuseal.multitenant? - Multi-tenant mode
Docuseal.pro? - Pro features enabled

Testing

RSpec with:

spec/models/ - Model specs
spec/requests/ - API/request specs
spec/system/ - System/feature specs
spec/factories/ - FactoryBot factories

Helpers:

signing_form_helper.rb - Form signing utilities
rails_helper.rb - Rails test configuration

BMAD Core Integration

This repository uses BMAD Core for AI-assisted development:

Configuration: .bmad-core/core-config.yaml
Tasks: .bmad-core/tasks/ (e.g., create-doc.md, document-project.md)
Templates: .bmad-core/templates/ (e.g., brownfield-prd-tmpl.yaml, story-tmpl.yaml)
Agents: .bmad-core/agent-teams/

Slash Commands:

/BMad:agents:pm - Product Manager agent
/BMad:agents:dev - Developer agent

Story Creation Workflow:

Story Template: .bmad-core/templates/story-tmpl.yaml - Defines story structure
Story Task: .bmad-core/tasks/create-next-story.md - Automated story creation
Usage: Use /sm *draft to create next story following the template
Output: Stories created in docs/stories/ with full context from architecture docs

FloDoc Enhancement (Current Work)

Context: Transforming DocuSeal into a 3-portal cohort management system for training institutions.

Key Changes:

New models: Cohort, CohortEnrollment, Institution, Sponsor
Three portals: Admin, Student, Sponsor
Workflow: Admin creates cohort → Students enroll → Admin verifies → Sponsor signs → Admin finalizes
Excel export for cohort data (FR23)
Custom UI/UX (not DaisyUI)

Documentation Structure (Sharded):

PRD: docs/prd.md (main) + docs/prd/ (sections)
Architecture: docs/architecture/ (sharded files)
- index.md - Architecture overview
- tech-stack.md - Technology stack
- data-models.md - Database schemas and models
- api-design.md - API specifications
- project-structure.md - File organization
- security.md - Security requirements
- coding-standards.md - Code conventions
- testing-strategy.md - Testing approach
- infrastructure.md - Deployment setup
Stories: docs/stories/ - Individual story files (created via *draft)

Story Creation:

Use /sm *draft to create next story
Stories auto-populated from PRD + Architecture docs
Follows .bmad-core/templates/story-tmpl.yaml structure
Each story is a complete, self-contained implementation guide

Important Files

README.md - Project overview and deployment
SECURITY.md - Security policy
Gemfile - Ruby dependencies
package.json - JavaScript dependencies
config/routes.rb - All routes including API
app/models/user.rb - Authentication model
app/javascript/application.js - Frontend entry point

Gotchas

Multi-tenancy: Check Docuseal.multitenant? before assuming single-account mode
Storage: Active Storage configs in config/storage.yml and lib/load_active_storage_configs.rb
PDF Processing: HexaPDF requires proper license for commercial use
Sidekiq: Requires Redis connection, configured via REDIS_URL
Devise 2FA: Requires devise-two-factor setup per user
Vue + Rails: Uses Shakapacker, not standard Webpack config
Email Templates: Stored in app/views/mailers/, use ERB variables

Common Issues

Database errors: Run bin/rails db:setup or check DATABASE_URL Asset compilation: Run bin/rails assets:precompile for production Sidekiq not processing: Check Redis connection and config/sidekiq.yml PDF generation fails: Verify HexaPDF installation and PDF permissions Webhook delivery fails: Check network access and SSL certificates

FloDoc Enhancement - Current Development Workflow

Completed Task: create-brownfield-prd - Comprehensive PRD for 3-portal cohort management system

PRD Status: ✅ COMPLETE

Location: docs/prd.md
Sections: 6 sections following BMAD brownfield-prd-tmpl.yaml
Stories: 21 stories across 7 phases (Phases 1-7 complete, Phase 8 with 2 infrastructure stories)
Commits: Stories 8.0 and 8.0.1 committed to git

Workflow Progress:

✅ Section 1: Intro Analysis & Context - Complete
✅ Section 2: Requirements (FR1-FR24) - Complete
✅ Section 3: Technical Constraints & Integration (TC1-TC10) - Complete
✅ Section 4: UI Enhancement Goals (UI1-UI10) - Complete
✅ Section 5: Epic & Story Structure (5.1-5.8) - Complete
✅ Section 6: Epic Details (6.1-6.7) - Complete
✅ Section 6.8: Phase 8 - Deployment & Documentation - Complete (Stories 8.0, 8.0.1)

Current Phase: ✅ VALIDATION PHASE (PO Agent)

Next Agent: PO (Product Owner) Agent

Task: po-master-checklist - Validate all artifacts for integration safety
Purpose: Verify story completeness, security, integration requirements, and BMAD compliance
Action: PO will review docs/prd.md and flag any issues requiring updates

After PO Validation:

If issues found → Return to PM/Dev to fix
If approved → Move to story sharding (optional for IDE)
Then → Story implementation with Dev/QA agents

Key Principles Followed:

✅ No code changes until PRD complete
✅ Each story approved before committing
✅ Strict Story 4.6 structure compliance
✅ Advanced elicitation for every section
✅ Single institution model (not multi-tenant)
✅ Ad-hoc access pattern (no account creation for students/sponsors)
✅ Local Docker infrastructure (no production dependencies)

Deferred Stories (Production Infrastructure):

Story 8.1: Production Infrastructure Setup (AWS)
Story 8.2: Deployment Automation & CI/CD
Story 8.3: Monitoring & Alerting
Story 8.4: Documentation & Training

Reason for Deferral: Management wants to validate FloDoc system locally first before investing in production infrastructure.

Next Steps for FloDoc Enhancement

PO Validation - Run po-master-checklist on complete PRD
Address PO Feedback - Fix any flagged issues
Story Sharding ✅ COMPLETE - docs/prd/ and docs/architecture/ sharded
Story Creation - Use /sm *draft to create Story 1.1 (Database Schema Extension)
QA Pre-Analysis - Run *risk and *design on each story before development
Story Implementation - Dev agent implements stories with QA gates
Management Demo - Run demo scripts to validate system

Brownfield PRD Story Structure

When writing stories in docs/prd.md during brownfield mode, STRICTLY adhere to Story 4.6 structure:

#### Story X.X: [Descriptive Title]

**Status**: Draft/Pending
**Priority**: High/Medium/Low
**Epic**: [Epic Name]
**Estimated Effort**: [X days]
**Risk Level**: Low/Medium/High

##### User Story

**As a** [role],
**I want** [action],
**So that** [benefit].

##### Background

[Context, requirements, and rationale for this story]

##### Technical Implementation Notes

**Vue 3 Component Structure:**
```vue
<!-- app/javascript/[portal]/views/[Component].vue -->
<template>
  <!-- Component markup -->
</template>

<script setup>
// Component logic
</script>

<style scoped>
/* Component styles */
</style>

Pinia Store:

// app/javascript/[portal]/stores/[store].ts
import { defineStore } from 'pinia'

export const use[Store]Store = defineStore('[store]', {
  state: () => ({
    // State properties
  }),
  actions: {
    // Async actions
  },
  getters: {
    // Computed properties
  }
})

API Layer:

// app/javascript/[portal]/api/[resource].ts
export const [Resource]API = {
  async get[Resource](token: string): Promise<[Type]> {
    // API implementation
  }
}

Type Definitions:

export interface [Type] {
  // Type properties
}

Design System Compliance:

Per FR28, all components must use design system assets from:

@.claude/skills/frontend-design/SKILL.md
@.claude/skills/frontend-design/design-system/

Specifically: colors, icons, typography, and layout patterns from the design system.

Acceptance Criteria

Functional:

✅ [Functional requirement]
✅ [Functional requirement]

UI/UX:

✅ [UI/UX requirement]
✅ [UI/UX requirement]

Integration:

✅ [Integration requirement]
✅ [Integration requirement]

Security:

✅ [Security requirement]
✅ [Security requirement]

Quality:

✅ [Quality requirement]
✅ [Quality requirement]

Integration Verification (IV1-4)

IV1: API Integration

[Verification steps]

IV2: Pinia Store

[Verification steps]

IV3: Getters

[Verification steps]

IV4: Token Routing

[Verification steps]

Test Requirements

Component Specs:

// spec/javascript/[portal]/views/[Component].spec.js
import { mount, flushPromises } from '@vue/test-utils'
import [Component] from '@/[portal]/views/[Component].vue'
import { createPinia, setActivePinia } from 'pinia'

describe('[Component]', () => {
  beforeEach(() => {
    setActivePinia(createPinia())
  })

  it('[test description]', async () => {
    // Test implementation
  })
})

Integration Tests:

[Integration test requirements]

E2E Tests:

[E2E test requirements]

Rollback Procedure

If [failure scenario]:

[Rollback step]
[Rollback step]

Data Safety: [Explanation of atomic operations]

Risk Assessment

[Risk Level] because:

[Risk reason 1]
[Risk reason 2]

Specific Risks:

[Risk Name]: [Risk description]
[Risk Name]: [Risk description]

Mitigation:

[Mitigation strategy 1]
[Mitigation strategy 2]

Success Metrics

[Metric 1]
[Metric 2]
[Metric 3]


**Key Rules:**
1. **Always** use `#####` (H5) for all story subsections (User Story, Background, etc.)
2. **Always** include Status, Priority, Epic, Estimated Effort, Risk Level
3. **Always** include Integration Verification section (IV1-4)
4. **Always** include Test Requirements with code examples
5. **Always** include Rollback Procedure
6. **Always** include Risk Assessment with specific risks and mitigations
7. **Always** include Success Metrics
8. **Never** embed Acceptance Criteria inside User Story - use separate `##### Acceptance Criteria` section
9. **Always** use code blocks for Vue components, Pinia stores, API layers, and type definitions
10. **Always** reference design system compliance per FR28

**Story Creation Workflow (NEW):**

**MANDATORY WORKFLOW:** `create → review → approve → commit`

1. **Create**: SM creates story using `/sm *draft`
   - Story written to `docs/stories/` directory
   - Follows `.bmad-core/templates/story-tmpl.yaml` structure
   - Populated from PRD + Architecture docs

2. **Review**: User reviews the created story draft
   - Check for completeness, accuracy, and template compliance
   - Verify all sections present (User Story, Background, Tasks, Acceptance Criteria, etc.)
   - Confirm technical details match PRD requirements

3. **Approve**: User provides explicit approval
   - **CRITICAL**: Do NOT commit until user says "approved" or similar
   - User may request changes - return to step 1

4. **Commit**: After explicit approval only
   ```bash
   git add docs/stories/1.1.database-schema-extension.md
   git commit -m "Add Story 1.1: Database Schema Extension"

Commit message format: git commit -m "Add Story X.X: [Story Title]"
Purpose: Preserve each story independently, allow rollback, clear git history

Key Rules:

✅ NEVER commit without explicit user approval
✅ Stories go in docs/stories/, NOT in docs/prd.md
✅ One story per commit for traceability
✅ If user requests changes, edit and re-submit for review

Example Session:

# 1. Create story
@sm *draft
# Story created at docs/stories/1.1.database-schema-extension.md

# 2. User reviews (reads the file)

# 3. User provides feedback or approval
# "Looks good, approved" → Proceed to commit
# "Change X in section Y" → Edit and re-submit for review

# 4. Commit ONLY after approval
git add docs/stories/1.1.database-schema-extension.md
git commit -m "Add Story 1.1: Database Schema Extension"

Enhanced IDE Development Workflow (STRICT BMAD CORE CYCLE)

MANDATORY: All FloDoc development MUST follow the BMad Core Development Cycle from .bmad-core/user-guide.md. This is SUPER CRITICAL for brownfield projects.

🚨 CRITICAL WORKFLOW RULES

Violating these rules will result in broken code in master:

NEVER commit story implementation files until QA approves
ALWAYS create a git branch for each story after PO approval
QA must approve story implementation with >80% test pass rate
Only merge to master after QA approval
Delete branch after successful merge
Repeat cycle for each new story

The BMad Core Development Cycle (MANDATORY)

Source: .bmad-core/user-guide.md - "The Core Development Cycle (IDE)" diagram

┌─────────────────────────────────────────────────────────────┐
│  1. SM: Reviews Previous Story Dev/QA Notes                 │
│  2. SM: Drafts Next Story from Sharded Epic + Architecture  │
│  3. QA: *risk + *design (for brownfield/high-risk)          │
│  4. PO: Validate Story Draft (Optional)                     │
│  5. User: APPROVE STORY                                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  6. DEV: Create Story Branch (YOUR REQUIREMENT)             │
│     git checkout -b story/1.1-database-schema               │
│     ⚠️ BRANCH CREATED ONLY AFTER USER APPROVAL              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  7. DEV: Implement Tasks + Write Tests                      │
│     - Use subtasks as TODO list                             │
│     - Mark [ ] → [x] in story file after each subtask       │
│     - Update Dev Agent Record with progress                 │
│  8. DEV: Run All Validations (rspec, lint, etc.)            │
│     - Must achieve >80% test pass rate                      │
│  9. DEV: Mark Ready for Review + Add Notes                  │
│     - Update story Status to "Ready for Review"             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  10. User Verification                                      │
│      └─ Request QA Review?                                  │
│         ├─ YES → Go to Step 11                              │
│         └─ NO → Skip to Step 12 (Verify tests yourself)     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  11. QA: Test Architect Review + Quality Gate              │
│      - *review: Comprehensive assessment                    │
│      - Requirements traceability                            │
│      - Test coverage analysis                               │
│      - Active refactoring (when safe)                       │
│      - Quality Gate Decision                                │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  12. QA Decision:                                          │
│      ├─ PASS → Continue to Step 13                          │
│      ├─ CONCERNS → Team review, decide                      │
│      ├─ FAIL → Return to Dev (Step 7)                       │
│      └─ WAIVED → Document reasoning                         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  13. IMPORTANT: Verify All Regression Tests and Linting    │
│      Are Passing (>80% pass rate required)                  │
│      ⚠️ CRITICAL: NO COMMIT WITHOUT QA APPROVAL             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  14. IMPORTANT: COMMIT YOUR CHANGES BEFORE PROCEEDING!     │
│      git add .                                              │
│      git commit -m "Add Story 1.1: Database Schema Extension"│
│      git push origin story/1.1-database-schema              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  15. Gate Update Needed?                                    │
│      └─ YES → QA: *gate to Update Status                    │
│      └─ NO → Continue                                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  16. MERGE TO MASTER (Your Requirement)                     │
│      git checkout master                                    │
│      git merge story/1.1-database-schema                    │
│      git push origin master                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  17. DELETE BRANCH (Your Requirement)                       │
│      git branch -d story/1.1-database-schema                │
│      git push origin --delete story/1.1-database-schema     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  18. Mark Story as Done                                     │
│  19. SM: Start Next Story Cycle                             │
│      Compact conversation, begin fresh                      │
└─────────────────────────────────────────────────────────────┘

Key Points from Core Cycle:

Step H (User Verification): User decides if QA review is needed
Step M: Verify all tests pass BEFORE commit
Step N: COMMIT happens AFTER QA approval
Step K: Mark story as done, then loop back

Your Additions:

Step 6: Branch creation (not in core diagram)
Step 16: Merge to master (not in core diagram)
Step 17: Delete branch (not in core diagram)
Step 7.1: Mark subtasks in story file
Step 7.2: Update Dev Agent Record
Step 8.1: >80% test pass rate required

Branch Management Workflow

For Each Story:

# After PO approves story draft:
git checkout -b story/1.1-database-schema

# ... development work ...

# After QA approves implementation:
git add .
git commit -m "Add Story 1.1: Database Schema Extension"
git push origin story/1.1-database-schema

# Merge to master (via PR or direct):
git checkout master
git merge story/1.1-database-schema
git push origin master

# Delete branch:
git branch -d story/1.1-database-schema
git push origin --delete story/1.1-database-schema

Dev Agent Task Management (CRITICAL)

During story implementation, Dev agent MUST:

Use story subtasks as TODO list
- Read all subtasks from Tasks / Subtasks section
- Treat each subtask as a development task to complete

Mark subtasks complete in story file

When subtask is done: [ ] → [x]
Update story file immediately after completing each subtask

Example:

- [x] Create migration file
- [x] Create institutions table
- [x] Create cohorts table
- [x] Create cohort_enrollments table

Track progress in Dev Agent Record
- Add completion notes for each major subtask
- Update File List with all created/modified files
- Log any issues or blockers in Debug Log References
Update story Status
- Change from "Draft" → "In Progress" when dev starts
- Change to "Ready for Review" when all tasks complete and tests pass

Story File Update Rules:

✅ ALLOWED: Tasks/Subtasks checkboxes, Dev Agent Record sections, Status
❌ NOT ALLOWED: User Story, Background, Acceptance Criteria, Testing sections

Example Dev Agent Record Update:

### Dev Agent Record

### Agent Model Used
James (Full Stack Developer)

### Debug Log References
- Migration created successfully
- All foreign keys validated

### Completion Notes List
- [x] Subtask 1.1: Created migration file
- [x] Subtask 1.2: Created institutions table schema
- [x] Subtask 1.3: Created cohorts table schema
- [x] Subtask 1.4: Created cohort_enrollments table schema
- [x] Subtask 1.5: Added all indexes
- [x] Subtask 1.6: Added all foreign keys

### File List
- db/migrate/20260114000001_create_flo_doc_tables.rb
- spec/migrations/20260114000001_create_flo_doc_tables_spec.rb
- spec/integration/cohort_workflow_spec.rb

### Change Log
| Date | Action | Author |
|------|--------|--------|
| 2026-01-14 | Created migration and tests | James |

Test Architect Command Reference

Stage	Command	Purpose	Output	When to Use
After PO Approval	`*risk`	Identify integration & regression risks	`docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`	REQUIRED for brownfield
	`*design`	Create test strategy for dev	`docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`	REQUIRED for brownfield
During Development	`*trace`	Verify test coverage	`docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`	Recommended
	`*nfr`	Validate quality attributes	`docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`	Recommended
After Dev Complete	`*review`	COMPREHENSIVE ASSESSMENT	QA Results + Gate file	MANDATORY - NO COMMIT WITHOUT THIS
Post-Review	`*gate`	Update quality decision	Updated gate file	If issues found

Quality Gate Decisions (BLOCKING)

Status	Meaning	Action Required	Can Commit?
PASS	All critical requirements met, >80% tests pass	None	✅ YES
CONCERNS	Non-critical issues found	Team review recommended	⚠️ With approval
FAIL	Critical issues (security, missing P0 tests, <80% pass)	MUST FIX	❌ NO - BLOCKED
WAIVED	Issues acknowledged and accepted	Document reasoning + approval	⚠️ With approval

FloDoc-Specific Requirements

For FloDoc Enhancement (Brownfield), ALWAYS:

After PO approves story: Run @qa *risk and @qa *design BEFORE writing code
During development: Run @qa *trace to verify coverage
Before commit: Run @qa *review - MANDATORY
Test pass rate: Must be >80% for QA approval
Branch per story: Create story/{number}-{slug} branch
Delete after merge: Clean up branches after successful merge

Why Strict Compliance Matters for FloDoc:

Brownfield changes risk breaking existing DocuSeal functionality
3-portal integration complexity requires thorough validation
Security is critical (POPIA, sponsor portal access)
Performance must be maintained (NFR1: <20% degradation)
Management demo depends on working system

Complete Example: Story 1.1 Implementation

# === PHASE 1: STORY CREATION ===
# 1. SM creates story
@sm *draft
# Creates: docs/stories/1.1.database-schema-extension.md

# 2. User reviews story
cat docs/stories/1.1.database-schema-extension.md

# 3. User approves story
# User says: "Story 1.1 approved"

# === PHASE 2: QA PRE-ANALYSIS (REQUIRED) ===
# 4. QA risk assessment
@qa *risk Story-1.1
# Creates: docs/qa/assessments/flodoc.1.1-risk-20260114.md

# 5. QA test design
@qa *design Story-1.1
# Creates: docs/qa/assessments/flodoc.1.1-test-design-20260114.md

# === PHASE 3: BRANCH CREATION ===
# 6. Dev creates story branch (AFTER PO APPROVAL)
git checkout -b story/1.1-database-schema

# === PHASE 4: IMPLEMENTATION ===
# 7. Dev implements story
# - Create migration: db/migrate/20260114000001_create_flo_doc_tables.rb
# - Write migration spec: spec/migrations/20260114000001_create_flo_doc_tables_spec.rb
# - Write integration spec: spec/integration/cohort_workflow_spec.rb

# 8. Dev runs tests
bundle exec rspec
# Must achieve >80% pass rate

# 9. Dev runs QA mid-dev check (optional but recommended)
@qa *trace Story-1.1
# Verifies: All acceptance criteria have tests

# 10. Dev marks ready for review
# Adds notes: "All tasks complete, tests written, ready for QA review"

# === PHASE 5: QA REVIEW (MANDATORY) ===
# 11. QA comprehensive review
@qa *review Story-1.1
# Creates: docs/qa/gates/flodoc.1.1-database-schema.yml
# Adds: QA Results section to story file

# 12. QA Decision:
# - PASS → Continue to commit
# - CONCERNS → Review with team
# - FAIL → Return to implementation

# === PHASE 6: ADDRESS ISSUES (IF NEEDED) ===
# 13. If QA found issues:
# - Fix the issues
# - Re-run tests
# - Request QA to update gate: @qa *gate Story-1.1

# === PHASE 7: COMMIT & MERGE (ONLY AFTER QA APPROVAL) ===
# 14. QA approves (>80% tests pass)
# User says: "QA approved, ready to commit"

# 15. Commit changes
git add .
git commit -m "Add Story 1.1: Database Schema Extension"

# 16. Push to branch
git push origin story/1.1-database-schema

# 17. Merge to master
git checkout master
git merge story/1.1-database-schema
git push origin master

# 18. Delete branch
git branch -d story/1.1-database-schema
git push origin --delete story/1.1-database-schema

# === PHASE 8: NEXT STORY ===
# 19. Compact conversation
# 20. Start next story cycle

Common Pitfalls to Avoid

❌ DON'T:

Commit before QA approval
Skip *risk and *design for brownfield stories
Merge without >80% test pass rate
Delete branch before successful merge
Skip branch creation and commit directly to master

✅ DO:

Wait for explicit QA approval
Create branch per story
Run all required QA commands
Verify tests pass before commit
Clean up branches after merge

Documentation & Audit Trail

All QA activities create permanent records:

docs/qa/assessments/
  └── flodoc.1.1-risk-20260114.md
  └── flodoc.1.1-test-design-20260114.md
  └── flodoc.1.1-trace-20260114.md
  └── flodoc.1.1-nfr-20260114.md

docs/qa/gates/
  └── flodoc.1.1-database-schema.yml

docs/stories/
  └── 1.1.database-schema-extension.md (with QA Results section)

Success Metrics

The strict workflow ensures:

✅ Zero regression defects in master
✅ 100% requirements coverage with tests
✅ Clear quality gates for go/no-go decisions
✅ Documented risk acceptance
✅ Consistent test quality
✅ Clean git history with per-story branches
✅ Management demo ready at all times

Emergency Rollback

If something breaks in master:

# 1. Identify the problematic story
git log --oneline

# 2. Revert the merge commit
git revert <merge-commit-hash>

# 3. Push the revert
git push origin master

# 4. Re-open the story for fix
# Create new branch from master
git checkout -b story/1.1-fix
# Fix and re-run full QA cycle

Remember: The workflow is SUPER CRITICAL. Violating it risks breaking the FloDoc enhancement project.

37 KiB Raw Blame History

CLAUDE.md

Overview

Tech Stack

Common Commands

Development

Git Commit Guidelines

Production

Architecture

Core Models Hierarchy

Key Concepts

Directory Structure

Authentication & Authorization

PDF Processing

API Structure

Webhooks

Background Jobs (Sidekiq)

Database Schema

Configuration

Testing

BMAD Core Integration

FloDoc Enhancement (Current Work)

Important Files

Gotchas

Common Issues

FloDoc Enhancement - Current Development Workflow

Next Steps for FloDoc Enhancement

Brownfield PRD Story Structure

Acceptance Criteria

Integration Verification (IV1-4)

Test Requirements

Rollback Procedure

Risk Assessment

Success Metrics

Enhanced IDE Development Workflow (STRICT BMAD CORE CYCLE)

🚨 CRITICAL WORKFLOW RULES

The BMad Core Development Cycle (MANDATORY)

Branch Management Workflow

Dev Agent Task Management (CRITICAL)

Test Architect Command Reference

Quality Gate Decisions (BLOCKING)

FloDoc-Specific Requirements

Complete Example: Story 1.1 Implementation

Common Pitfalls to Avoid

Documentation & Audit Trail

Success Metrics

Emergency Rollback

37 KiB

Raw Blame History