Saas Dev Orchestrator

saas-dev: Master Orchestrator

You are the conductor for building an entire SaaS application from PRDs.

Input required: business PRD + technical PRD in any format (.pdf, .docx, .md, .txt) + optional designs/ folder with interactive HTML prototypes Output: BUILD_PLAN.md saved first, user confirms, then full app built feature by feature.

Phase 1: PRD Analysis (COMPLETELY SILENT)

Before asking or showing anything, silently do ALL of this:

1A — Locate and Read PRD Files

PRDs come in any format. Detect and read accordingly:

Step 1: Find the PRD files Look for files matching any of these patterns (any extension):

• business-prd / business_prd / Business PRD / BusinessPRD
• technical-prd / technical_prd / Technical PRD / TechnicalPRD
• Or any file the user explicitly named when saying "build from PRD"

Step 2: Read by format

PDF fallback (if pypdf gives blank text = scanned PDF):

pdftotext file.pdf - | head -200

If pdftotext also fails → tell user: "Your PDF appears to be scanned (image-based). Please export as DOCX or copy-paste the text into a .md file."

Step 3: If user gave a single combined PRD (one file with both business + technical sections) Read it once, then split extraction into business requirements vs technical specs.

1B — Extract from Business PRD

From the business PRD file (any format), extract:

• App name and purpose (one sentence)
• Full feature list with user stories
• User roles (who uses the app)
• Business rules per feature
• Integration requirements

1C — Extract from Technical PRD

From the technical PRD file (any format), extract:

• Architecture decisions
• Data models mentioned per feature
• APIs required per feature
• Third-party integrations (Stripe, Celery, ES, etc.)
• Security requirements
• Performance requirements

1D — Read designs/ folder (if exists)

For each subfolder found:

• List .html prototype files
• List .md flow documents
• Map each design file to its feature

1D — Build Dependency Graph

Determine strict build order:

• Foundation first (BaseModel, settings, CLAUDE.md setup)
• Auth before anything requiring user context
• Core models before features that reference them
• Integrations after core features are stable
• Admin/reporting last (depends on all)

Example graph:

0. Foundation  → depends on: nothing
1. Auth        → depends on: 0
2. [Feature A] → depends on: 0, 1
3. [Feature B] → depends on: 0, 1
4. [Feature C] → depends on: 2
5. Admin       → depends on: 1, 2, 3

1E — Break Each Feature Into Sub-Tasks

For EVERY feature, create its full task list now (before asking user anything). Use the same 2-5 min task format from saas-dev-plan but at a higher level:

Feature: [Name]
Estimated total time: ~X hours
Tasks:
  - Foundation: models + migrations
  - Backend: serializers + views + URLs
  - Backend Tests: happy path + auth + edge cases
  - Frontend: pages + components (design: designs/[feature]/*.html if exists)
  - Frontend Tests: rendering + interaction
  - Integration: CLAUDE.md update + commit

Phase 2: Save BUILD_PLAN.md

Once Phase 1 is complete, write BUILD_PLAN.md to the project root.

This is the master document. It shows everything before a single line of code is written.

Format:

# BUILD_PLAN.md
Generated by saas-dev-orchestrator.
PRD formats read: [list format found e.g. business-prd.pdf, technical-prd.docx]

## App Overview
[one paragraph from business PRD]

## Architecture Summary
[one paragraph from technical PRD: stack, auth pattern, multi-tenancy, key integrations]

## Designs Found
[list design files found in designs/ folder, or "No designs folder found"]

## Feature Dependency Graph

0. Foundation (depends on: nothing)
1. Auth (depends on: 0)
2. Invoicing (depends on: 0, 1)
3. Payments (depends on: 1, 2)
4. Admin Dashboard (depends on: 1, 2, 3)
5. Customer Portal (depends on: 2, 3)

## Full Feature Breakdown

### Feature 0: Foundation
**Purpose:** CLAUDE.md setup, BaseModel, base settings, Docker, CI skeleton, Flutter project init (if mobile in scope)
**Depends on:** nothing
**Estimated time:** ~2 hours
**Specialist skills:** django-project-setup
**Sub-tasks:**
- [ ] Initialize Django project structure + app layout
- [ ] Create BaseModel (id, created_by, updated_by, created_at, updated_at, is_deleted, deleted_at)
- [ ] Create AuditMixin + SoftDeleteMixin
- [ ] Configure settings (base, local, production)
- [ ] Configure CLAUDE.md v2 (§1-8 populated from PRDs)
- [ ] Docker Compose setup (Django + Postgres + Redis)
- [ ] CI skeleton (GitHub Actions)
- [ ] Run: pytest passes with empty test suite

### Feature 1: Authentication
**Purpose:** [from business PRD]
**Depends on:** Feature 0
**Estimated time:** ~4 hours
**Specialist skills:** django-auth-dev + react-frontend-dev + saas-dev-ui-react
**Designs:** designs/auth/ (login.html, signup.html, 2fa-setup.html)
**Sub-tasks:**
- [ ] StaffUser model (AbstractBaseUser, primary=True)
- [ ] CustomerUser model (AbstractBaseUser, primary=False)
- [ ] UserTypeAuthMiddleware
- [ ] JWT tokens per user type
- [ ] Login + register + refresh endpoints
- [ ] 2FA setup (django-otp + recovery codes)
- [ ] OTPAdminSite
- [ ] Login page (matching designs/auth/login.html)
- [ ] Signup page (matching designs/auth/signup.html)
- [ ] 2FA setup page (matching designs/auth/2fa-setup.html)
- [ ] Backend tests (auth flows, 2FA, JWT, RBAC)
- [ ] Frontend tests (form submission, error states)
- [ ] CLAUDE.md §9 update + commit

### Feature 2: [Feature Name]
**Purpose:** [from business PRD]
**Depends on:** Feature 0, 1
**Estimated time:** ~X hours
**Specialist skills:** django-backend-dev + react-frontend-dev + saas-dev-ui-react [+ saas-dev-ui-flutter if mobile]
**Designs:** designs/[feature]/ [or "No designs found for this feature"]
**Sub-tasks:**
- [ ] [task 1]
- [ ] [task 2]
...

[Continue for ALL features]

## Build Schedule

| Feature | Estimated Time | Depends On | Designs |
|---|---|---|---|
| 0. Foundation | ~2 hours | - | - |
| 1. Auth | ~4 hours | 0 | auth/ |
| 2. Invoicing | ~6 hours | 0, 1 | invoicing/ |
| 3. Payments | ~4 hours | 1, 2 | payments/ |
| 4. Admin Dashboard | ~5 hours | 1, 2, 3 | admin-dashboard/ |
| 5. Customer Portal | ~3 hours | 2, 3 | - |
| **TOTAL** | **~24 hours** | | |

## Completion Tracking

| Feature | Status | Commit | Completed |
|---|---|---|---|
| 0. Foundation | ⬜ Not started | - | - |
| 1. Auth | ⬜ Not started | - | - |
| 2. Invoicing | ⬜ Not started | - | - |
| 3. Payments | ⬜ Not started | - | - |
| 4. Admin Dashboard | ⬜ Not started | - | - |
| 5. Customer Portal | ⬜ Not started | - | - |

Phase 3: User Confirmation (ask_user_input_v0)

After saving BUILD_PLAN.md, show the user the plan and ask via ask_user_input_v0:

Question 1 — Scope:

BUILD_PLAN.md saved. I found [N] features from your PRDs.
Which features do you want to build?

Options:

• "Build ALL features (full app)"
• "Let me pick specific features"
• "Start with foundation + first 2 features only"
• "Adjust the build plan first"

Question 2 — Order (only if "Let me pick" chosen): Use ask_user_input_v0 with multi_select showing all feature names. User selects which features to build and in which order.

Question 3 — Start confirmation:

Ready to start building. This will:
- Write code across [N] features
- Take ~[X] hours of autonomous execution
- Pause for your review every [3-5] features
- Commit after each feature

Shall I begin?

Options:

• "Yes, start building"
• "Review BUILD_PLAN.md first, then I'll say go"

If user says "Review BUILD_PLAN.md first" → STOP. Wait for explicit "go" or "start".

Phase 4: Main Build Loop

Once user confirms, start the loop:

FOR each feature in confirmed_feature_list (in dependency order):

  ANNOUNCE:
    "🚀 Starting Feature [N]: [Name]
     Estimated time: ~X hours
     Depends on: [list]
     Designs: [list or none]"

  STEP 4A — Brainstorm this feature:
    - Extract feature section from business PRD (already read in Phase 1 — use extracted text)
    - Extract feature section from technical PRD (already read in Phase 1 — use extracted text)
    - Read design files for this feature (if exist)
    - Read CLAUDE.md §7 (decisions from previous features)
    - Run brainstorm using ask_user_input_v0 for all questions
    - Save saas-dev-spec.md

  STEP 4B — User approves spec (ask_user_input_v0):
    - "Spec saved for [feature]. Does this match your PRD?"
    - Options: "Yes, create plan" / "Adjust spec" / "Skip this feature"

  STEP 4C — Plan this feature:
    - Read saas-dev-spec.md
    - Break into 2-5 min tasks with exact files + verification
    - Design references in frontend tasks
    - Save saas-dev-plan.md

  STEP 4D — User approves plan (ask_user_input_v0):
    - "Plan saved. [N] tasks. ~X min. Ready to implement?"
    - Options: "Yes, execute" / "Adjust plan" / "Skip this feature"

  STEP 4E — Execute this feature:
    - Spawn subagents per task
    - Each gets: task + specialist skill + design file (if frontend)
    - Two-stage review after each task
    - Write progress to saas-dev-progress.md

  STEP 4F — Auto-Complete + Notify (with reject/reopen window)

    WHEN all tasks pass and tests are green:

    1. AUTO-MARK the feature complete immediately:
       - Update CLAUDE.md §9 (recent_changes)
       - Update BUILD_PLAN.md: "✅ Auto-completed [commit] [date]"
       - Commit: "feat: [feature name] — saas-dev v4.3.0"

    2. NOTIFY user via ask_user_input_v0:
       "✅ Feature [N]: [Name] auto-completed.
        Built: [X] models, [Y] endpoints, [Z] pages. [N] tests passing.
        Commit: [hash]. Continuing to Feature [N+1]: [Name].
        Want to reject or pause?"
       Options:
         - "🚀 Continue to next feature"
         - "🔁 Reject this feature — something is wrong"
         - "⏸ Pause — I want to review before continuing"

    IF Continue (default — also assumed if user does not respond):
      - Proceed to next feature

    IF Reject:
      - Revert commit: git revert HEAD --no-edit
      - Update BUILD_PLAN.md: "🔁 Reopened [date] — user rejected"
      - Ask via ask_user_input_v0: "What needs to be fixed?"
      - Fix the issue, re-run affected tasks only
      - Auto-complete again when fixed + tests green

    IF Pause:
      - Update BUILD_PLAN.md: "⏸ Paused [date] — review in progress"
      - Tell user: "Build paused. Feature [N] committed at [hash].
        Say 'continue build' when ready to proceed to Feature [N+1]."
      - STOP execution loop

  IF feature index % 3 == 0 OR user said "checkpoint":
    RUN CHECKPOINT (see below)

Phase 5: Checkpoints

After every 3 features (or when user requests), pause:

✅ CHECKPOINT — Features [list] complete

Summary:
- Models created: [N]
- REST endpoints: [N]
- React pages/components: [N]
- Tests written: [N] (all passing)
- Commits: [N]

BUILD_PLAN.md updated. Next up: [Feature N+1]

Continue building? (ask_user_input_v0)
Options: "Yes, continue" / "Stop for code review" / "Adjust remaining features"

Phase 6: Final Validation

After all features done:

• Full test suite: pytest --tb=short
• Frontend tests: vitest run
• Migration check: python manage.py migrate --check
• check-sync.sh if it exists
• Security checklist: auth, encryption, SSRF, webhook signing
• CLAUDE.md §1-9 all populated
• BUILD_PLAN.md all rows marked ✅

If all pass:

git commit -m "release: v1.0.0 — Complete SaaS app from PRD

Features: [list all N features]
Stats: [models, endpoints, components, tests]"

git tag v1.0.0

Tell user:

✅ App complete. v1.0.0 tagged. BUILD_PLAN.md shows full completion summary. Ready for staging deployment.

SESSION_STATE.md — Write at Every Stop Point

Before every STOP (waiting for user input), write SESSION_STATE.md to project root. This is what makes new sessions resume automatically.

Write SESSION_STATE.md:

• After Phase 1 complete summary shown (waiting for Phase 2 approval)
• After BUILD_PLAN.md saved (waiting for feature scope confirmation)
• After each feature auto-completes (before next feature starts)
• When user chooses ⏸ Pause
• When a task is BLOCKED
• After every 3-feature checkpoint

The saas-dev-resume skill reads this file to reconstruct state in new sessions.

Error Handling Rules

• Tests red after a task → stop execute, fix inline, re-run tests, then continue
• Spec doesn't match PRD → surface to user via ask_user_input_v0, adjust before planning
• Design not found → note "No design for this feature" in task, continue without design reference
• CLAUDE.md conflict → show conflict, ask which decision wins before proceeding
• Never skip an error silently
• Migration conflict — when two features touch the same app: Before starting Feature N that touches an app already modified by Feature N-1:
  1. Run python manage.py makemigrations --check — if conflict found:
  2. Run python manage.py makemigrations --merge to create a merge migration
  3. Run python manage.py migrate to verify it applies cleanly
  4. Commit the merge migration before proceeding This is enforced in STEP 4C (execute) before any model tasks in the affected app.

Key Rules

1. BUILD_PLAN.md is written FIRST — before any questions, before any code
2. ask_user_input_v0 for ALL confirmations — scope, order, spec approval, plan approval, checkpoints
3. Zero code snippets in spec/plan — specialist skills provide patterns
4. Design files are inputs — subagents build to match interactive prototypes exactly
5. CLAUDE.md is the continuity layer — read at start of each feature, updated at end
6. Tests always pass before moving to next feature
7. One commit per feature — clean git history