# Saas Dev Orchestrator

> Reads business + technical PRDs. Extracts all features. Builds complete task breakdown document (BUILD_PLAN.md). Asks user confirmation via ask_user_input_v0 (all features / specific features / reorder). Then runs brainstorm → plan → execute loop per feature with continuity via CLAUDE.md.

- Skill: `ayithamsetty-vamsi-krishna/saas-dev-orchestrator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ayithamsetty-vamsi-krishna/saas-dev-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ayithamsetty-vamsi-krishna/saas-dev-orchestrator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Ayithamsetty-Vamsi-krishna (https://skillmd.com/u/ayithamsetty-vamsi-krishna)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ayithamsetty-vamsi-krishna/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**

| Format | Command |
|---|---|
| `.pdf` | `python3 -c "from pypdf import PdfReader; r=PdfReader('file.pdf'); print('\n'.join(p.extract_text() for p in r.pages))"` |
| `.docx` / `.doc` | `extract-text file.docx` (emits clean markdown) |
| `.md` / `.txt` | `cat file.md` |

**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:

```markdown
# 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