petrogurcak/fullstack-orchestrator

Fullstack Orchestrator

Overview

This skill orchestrates fullstack application development by coordinating existing workflow skills. It does NOT implement workflows itself - it detects the tech stack and calls the appropriate backend + frontend skills.

Philosophy:

Orchestrator = Conductor
Workflow Skills = Musicians

The conductor doesn't play instruments, but coordinates who plays when.

Announce: "I'm using the fullstack-orchestrator to coordinate backend and frontend development."

When to Use

USE this skill:

• New fullstack project (setting up both layers)
• Feature requiring backend API + frontend UI
• API contract changes (endpoint change → frontend update)
• Unsure if change affects both layers

DON'T use this skill:

• Pure backend work → use backend workflow skill directly
• Pure frontend work → use frontend workflow skill directly
• Bug fix in single layer
• Refactoring without API contract change

Trigger phrases:

"Create an application..."        → Orchestrator
"Add feature with UI..."          → Orchestrator
"Need endpoint + page"            → Orchestrator
"Change API and update frontend"  → Orchestrator

"Add endpoint..."                 → Backend skill directly
"Update component..."             → Frontend skill directly
"Fix bug in API..."               → Backend skill directly

Stack Detection

Step 1: Check for existing configuration

Is there .claude/fullstack.yaml?
├─ YES → Use stored stack config
└─ NO  → Continue to Step 2

Step 2: Autodetect from project files

| File/Pattern | Detected Technology | Skill | | ----------------------------------------- | ------------------- | ------------------- | | requirements.txt contains fastapi | FastAPI backend | fastapi-workflow | | composer.json contains nette | Nette backend | nette-workflow | | package.json contains alpinejs | Alpine frontend | frontend-workflow | | package.json contains expo | Expo mobile | expo-workflow | | pubspec.yaml | Flutter mobile | flutter-workflow | | package.json contains react (no expo) | React frontend | no skill - warn |

Detection commands:

# Backend detection
grep -l "fastapi" requirements.txt 2>/dev/null && echo "fastapi"
grep -l "nette" composer.json 2>/dev/null && echo "nette"

# Frontend detection
grep -l "alpinejs" package.json 2>/dev/null && echo "alpine"
grep -l "expo" package.json 2>/dev/null && echo "expo"
test -f pubspec.yaml && echo "flutter"

Step 3: Parse from user prompt

If autodetection fails, look for keywords in user's request:

Keywords → Stack mapping

"fastapi", "python backend", "python api" → fastapi-workflow
"nette", "php", "latte" → nette-workflow
"alpine", "tailwind frontend", "vite" → frontend-workflow
"expo", "react native" → expo-workflow
"flutter", "dart" → flutter-workflow

Step 4: Ask if unclear

If still unclear, ask:

I need to know your tech stack. Please specify:

**Backend:**
A) FastAPI (Python)
B) Nette (PHP)
C) None / API already exists

**Frontend:**
A) Vite + TypeScript + Tailwind + Alpine.js (Web)
B) Expo + React Native (Mobile)
C) Flutter (Mobile)
D) None / No frontend needed

Step 5: Store configuration

After detection, create .claude/fullstack.yaml:

# Fullstack project configuration
# Generated by fullstack-orchestrator

stack:
  backend: fastapi # fastapi | nette | none
  frontend: alpine # alpine | expo | flutter | none

skills:
  backend: fastapi-workflow
  frontend: frontend-workflow
  specs: openspec-workflow

# Optional: custom skill mappings
# custom_skills:
#   database: my-database-skill

Skill Integration

Skills this orchestrator calls:

fullstack-orchestrator
        │
        ├── project-setup.skill      (initial setup, TDD principles)
        │
        ├── openspec-workflow        (specs, proposals, tasks)
        │
        ├── Backend skill (one of):
        │   ├── fastapi-workflow.skill
        │   └── nette-workflow.skill
        │
        └── Frontend skill (one of):
            ├── frontend-workflow.skill
            ├── expo-workflow.skill
            └── flutter-workflow.skill

How to invoke skills:

When orchestrator needs backend work:

"I'm now using fastapi-workflow for backend implementation."

When orchestrator needs frontend work:

"I'm now using frontend-workflow for frontend implementation."

When orchestrator needs specs:

"I'm now using openspec-workflow to create specifications."

Fullstack Feature Workflow

Phase 1: Specification (openspec-workflow)

For any fullstack feature, first create specs:

User: "Add user authentication with login page"
                    ↓
Create OpenSpec proposal with:
- Backend requirements (endpoints, auth logic)
- Frontend requirements (UI components, state)
- API Contract (request/response schemas)
                    ↓
Get user approval before implementation

API Contract format (in proposal or separate file):

## API Contract

### POST /auth/login

**Request:**

```json
{
  "email": "string",
  "password": "string"
}
```

Response (200):

{
  "token": "string",
  "user": {
    "id": "number",
    "email": "string",
    "name": "string"
  }
}

Errors:

• 401: Invalid credentials
• 422: Validation error

### Phase 2: Implementation Order

Ask or determine implementation order:

| Approach | When to use |
|----------|-------------|
| **Backend first** | API-driven design, frontend consumes finished API |
| **Frontend first** | UI mockup exists, backend adapts to UI needs |
| **Parallel** | Clear contract, both can proceed simultaneously |

Default: **Backend first** (most common for API-driven apps)

### Phase 3: Backend Implementation

Invoke backend workflow skill:

For each backend task from specs:

1. Announce: "Using [backend-skill] for: [task description]"
2. The skill handles:
   • MANDATORY docs fetching
   • TDD (test first)
   • Implementation
   • Verification
3. Endpoint MUST match API contract

### Phase 4: Frontend Implementation

Invoke frontend workflow skill:

For each frontend task from specs:

1. Announce: "Using [frontend-skill] for: [task description]"
2. The skill handles:
   • MANDATORY docs fetching
   • Component implementation
   • API calls matching contract
3. API calls MUST match contract defined in Phase 1

### Phase 5: Integration Verification

After both layers implemented:

```bash
# Start backend
cd backend && [start command from stack]

# Start frontend
cd frontend && [start command from stack]

# Verify integration
# - Frontend can reach backend
# - API calls succeed
# - E2E flow works

Verification checklist:

☐ Backend server starts without errors
☐ Frontend server starts without errors
☐ Frontend can call backend API
☐ Authentication flow works (if applicable)
☐ Data flows correctly between layers
☐ Error handling works (backend errors show in frontend)

Decision Logic

When to orchestrate vs direct skill:

User request arrives
        ↓
┌─ Affects only backend? ─┐
│                         │
YES                       NO
↓                         ↓
Use backend          ┌─ Affects only frontend? ─┐
skill directly       │                          │
                    YES                         NO
                     ↓                          ↓
                Use frontend          FULLSTACK FEATURE!
                skill directly               ↓
                                    1. OpenSpec specs
                                    2. API contract
                                    3. Backend impl
                                    4. Frontend impl
                                    5. Integration test

Keywords indicating fullstack work:

• "...with UI" / "...se stránkou"
• "...and frontend" / "...a frontend"
• "endpoint + page" / "endpoint + stránka"
• "full feature" / "kompletní feature"
• "user-facing" / "pro uživatele"
• "login page", "dashboard", "form"

New Project Setup

When starting a new fullstack project:

Step 1: Detect or ask for stack

Follow Stack Detection process above.

Step 2: Create project structure

# Create directories
mkdir -p backend frontend

# Create config
mkdir -p .claude

Step 3: Initialize each layer

Backend:
- Use project-setup skill with detected backend variant
- Creates CLAUDE.md, .claude/ in backend/

Frontend:
- Use project-setup skill with detected frontend variant
- Creates CLAUDE.md, .claude/ in frontend/

Root:
- Create .claude/fullstack.yaml with stack config

Step 4: Inform user

✅ Fullstack project initialized!

Stack:
- Backend: [detected] → [skill]
- Frontend: [detected] → [skill]

Structure:
project/
├── .claude/
│   └── fullstack.yaml    # Stack configuration
├── backend/
│   ├── CLAUDE.md
│   └── .claude/          # Backend principles
└── frontend/
    ├── CLAUDE.md
    └── .claude/          # Frontend principles

Ready! Try: "Add user authentication with login page"

Missing Skill Handling

If technology detected but no skill exists:

⚠️ No workflow skill found for: React frontend

Options:
A) Continue without docs-first workflow
   (I'll use general best practices, but won't fetch current docs)

B) Switch to supported frontend
   - Alpine.js (frontend-workflow)
   - Expo (expo-workflow)
   - Flutter (flutter-workflow)

C) Add custom skill
   (Create your own react-workflow.skill)

Which option?

Configuration Reference

.claude/fullstack.yaml

# Required
stack:
  backend: fastapi | nette | none
  frontend: alpine | expo | flutter | none

# Auto-populated based on stack
skills:
  backend: fastapi-workflow | nette-workflow | null
  frontend: frontend-workflow | expo-workflow | flutter-workflow | null
  specs: openspec-workflow

# Optional overrides
custom_skills:
  backend: my-custom-backend-skill
  frontend: my-custom-frontend-skill

# Optional project-specific settings
settings:
  implementation_order: backend-first | frontend-first | parallel
  api_contract_location: openspec/contracts/ # where to store contracts

Examples

Example 1: New FastAPI + Alpine project

User: "Create a task management app with FastAPI and Alpine frontend"

Orchestrator:
1. Detected stack: fastapi + alpine
2. Created .claude/fullstack.yaml
3. Initialized backend/ with project-setup (FastAPI variant)
4. Initialized frontend/ with project-setup (Frontend variant)
5. Ready for features

Example 2: Fullstack feature

User: "Add task creation with form"

Orchestrator:
1. Read .claude/fullstack.yaml → fastapi + alpine
2. This is fullstack (backend endpoint + frontend form)
3. Create OpenSpec proposal:
   - POST /tasks endpoint
   - Task creation form component
   - API contract
4. After approval:
   - "Using fastapi-workflow for POST /tasks endpoint"
   - "Using frontend-workflow for task form component"
5. Integration verification

Example 3: Backend-only change

User: "Add pagination to /tasks endpoint"

Orchestrator:
1. This is backend-only (no new UI mentioned)
2. Direct to: "Using fastapi-workflow for pagination"
3. No orchestration needed

Verification Checklist

Before considering fullstack work complete:

PROJECT SETUP:
☐ Stack detected/configured
☐ .claude/fullstack.yaml exists
☐ Both layers have CLAUDE.md and .claude/

FEATURE IMPLEMENTATION:
☐ OpenSpec proposal created and approved
☐ API contract defined
☐ Backend implemented with TDD (via backend skill)
☐ Frontend implemented (via frontend skill)
☐ API calls match contract

INTEGRATION:
☐ Both servers start without errors
☐ Frontend successfully calls backend
☐ Error handling works across layers
☐ E2E flow verified

Summary

Fullstack Orchestrator:

1. Detects tech stack (auto/prompt/ask)
2. Stores config in .claude/fullstack.yaml
3. Coordinates specs via openspec-workflow
4. Calls backend skill for API work
5. Calls frontend skill for UI work
6. Verifies integration between layers

Key principle: One change in workflow skill = benefit for all fullstack projects using it.

No duplication: Orchestrator is just "glue" - all real work happens in specialized workflow skills.