---
description: "Deployment Modes & AI Decision Routing"
globs: ["**/*"]
alwaysApply: true
---

# Deployment Modes & AI Decision Routing

This rule defines three deployment modes for {{PROJECT_SHORTNAME}} and helps AI decide which context to enter.

---

## Three Deployment Modes

### Mode 1: Submodule (Primary Mode)

**When to use:** Customer projects installing {{PROJECT_SHORTNAME}} via git submodule

**Structure:**
```
customer-project/
├─ .{{PROJECT_SHORTNAME}}/        ← Git submodule (points to {{PUBLIC_REPO_NAME}})
│  ├─ commands/
│  ├─ dist/
│  ├─ templates/
│  └─ rules/
├─ .cursor/
│  └─ commands → symlink to .{{PROJECT_SHORTNAME}}/commands/
├─ context/                ← Customer's specs & epics
├─ ai-context.yml          ← Customer customized
└─ (customer code)
```

**Command locations:**
- Development: `.cursor/commands/`
- Published: `.{{PROJECT_SHORTNAME}}/commands/`

**Rule locations:**
- Development: `rules/` (published to `.{{PROJECT_SHORTNAME}}/rules/`)
- Customer: `.{{PROJECT_SHORTNAME}}/rules/` (read-only)

**Template locations:**
- Development: `templates/{{PROJECT_SHORTNAME}}/`
- Customer: `.{{PROJECT_SHORTNAME}}/templates/`

**Validation:** Check for `.{{PROJECT_SHORTNAME}}/` directory with `commands/`, `templates/`, `dist/`

---

### Mode 2: Multi-Repo (Enterprise)

**When to use:** Multiple repositories managed together with shared configuration

**Structure:**
```
master-project/
├─ config/
│  └─ repos.yml          ← Central configuration
├─ repo-1/
│  ├─ .cursor/commands/
│  └─ context/specs/
├─ repo-2/
│  ├─ .cursor/commands/
│  └─ context/specs/
└─ shared/
   └─ templates/
```

**Command locations:**
- Each repo: `.cursor/commands/` (local to that repo)

**Rule locations:**
- Master: `config/repos.yml` references shared rules
- Each repo: Can override with local `.cursor/rules/`

**Template locations:**
- Shared: `shared/templates/`
- Or centralized via `config/repos.yml`

**Validation:** Check for `config/repos.yml` listing all repos

---

### Mode 3: Standalone (Legacy)

**When to use:** {{PROJECT_SHORTNAME}} integrated directly into a single repo (not recommended)

**Structure:**
```
project/
├─ commands/             ← Commands at root
├─ templates/            ← Templates at root
├─ rules/                ← Rules at root
├─ dist/
└─ (project code)
```

**Command locations:**
- Root: `commands/`

**Rule locations:**
- Root: `rules/`

**Template locations:**
- Root: `templates/`

**Validation:** Check for `commands/`, `templates/`, `rules/` at repo root

---

## AI Decision Tree: Mode Routing

**Answer these questions in order:**

### Question 1: Where is `.{{PROJECT_SHORTNAME}}/` directory?

**YES** → Submodule Mode (Mode 1)
- Commands: `.{{PROJECT_SHORTNAME}}/commands/`
- Rules: `.{{PROJECT_SHORTNAME}}/rules/`
- Templates: `.{{PROJECT_SHORTNAME}}/templates/`
- **Action:** ENTER SUBMODULE MODE

**NO** → Continue to Question 2

### Question 2: Does `config/repos.yml` exist?

**YES** → Multi-Repo Mode (Mode 2)
- Commands: `.cursor/commands/` (per repo)
- Config: `config/repos.yml` (central)
- **Action:** ENTER MULTI-REPO MODE

**NO** → Continue to Question 3

### Question 3: Do `commands/`, `templates/`, `rules/` exist at root?

**YES** → Standalone Mode (Mode 3)
- Commands: `commands/`
- Rules: `rules/`
- Templates: `templates/`
- **Action:** ENTER STANDALONE MODE

**NO** → Unrecognized mode
- **Action:** Log error, ask PM for clarification

---

## Three AI Execution Contexts

### Context 1: Template Development

**When to enter:**
- File path contains `templates/` OR
- Editing files matching `.template*` pattern OR
- Running `/create-template` command

**Rules to apply:**
- `00-project-context.mdc` (project scope)
- `04-coding-standards.mdc` (code quality)
- `02-memory-bank.mdc` (documentation reference)

**Critical constraints:**
- ⚠️ **Preserve all {{VARIABLES}}** — Changes affect ALL customers
- ⚠️ Never hardcode customer-specific values
- Use only generic examples: `{{PROJECT_NAME}}`, not "{{PROJECT_SHORTNAME}}"
- Validate all {{VARIABLES}} are defined

**Validation checklist:**
- [ ] Every custom value is {{VARIABLE}}
- [ ] Examples are generic (not hardcoded names/paths)
- [ ] Template tested with substitute values

---

### Context 2: Feature Implementation

**When to enter:**
- File NOT in `templates/`
- Writing production code (TypeScript, tests)
- Running `/implement` command

**Rules to apply:**
- `00-project-context.mdc` (project scope)
- `04-coding-standards.mdc` (code quality, TDD, JSDoc)
- `03-github.mdc` (if using GitHub API)
- `02-memory-bank.mdc` (development patterns)

**Critical constraints:**
- ⚠️ **TDD required:** Test → Red → Green → Refactor
- ⚠️ **Never skip tests** for "trivial" code
- Epic must link to spec
- All functions must have explicit return types

**Validation checklist:**
- [ ] Test written first (RED state)
- [ ] Minimal code passes test (GREEN state)
- [ ] Code refactored (REFACTOR state)
- [ ] Tests pass
- [ ] Epic linked in PR

---

### Context 3: First-Time Onboarding

**When to enter:**
- New to project
- Setting up environment
- Running `/onboard` command

**Loading sequence (in order):**
1. **`.cursor/rules/00-project-context.mdc`** (5 min)
   - What: Project role and current status
   - Why: Foundation for all work
   - Contains: Repository links, deployment modes, critical paths

2. **`memory-bank/projectbrief.md`** (5 min)
   - What: Scope and core requirements
   - Why: Understand what {{PROJECT_SHORTNAME}} is
   - Contains: Philosophy, core features, success criteria

3. **`memory-bank/productContext.md`** (5 min)
   - What: Why {{PROJECT_SHORTNAME}} exists and problems it solves
   - Why: Know the motivation and user goals
   - Contains: Problems, solutions, user personas

4. **`memory-bank/techContext.md`** (3 min)
   - What: Technology stack overview
   - Why: Understand tech decisions
   - Contains: Languages, frameworks, tools, CI/CD

5. **`memory-bank/activeContext.md`** (5 min)
   - What: Product vision and strategy
   - Why: Understand long-term goals
   - Contains: Vision, success metrics, roadmap

6. **`memory-bank/systemPatterns.md`** (10 min)
   - What: System architecture and design patterns
   - Why: Understand how it's built
   - Contains: Architecture, decisions, components, patterns

**Estimated time:** 15-20 minutes

**After onboarding:**
- ✅ Know project purpose and current phase
- ✅ Understand deployment mode
- ✅ Know where to find documentation
- ✅ Ready to start first task

---

## Summary: Quick Reference

| Mode | Directory | Commands | Rules | Decision |
|------|-----------|----------|-------|----------|
| Submodule | `.{{PROJECT_SHORTNAME}}/` | `.{{PROJECT_SHORTNAME}}/commands/` | `.{{PROJECT_SHORTNAME}}/rules/` | Check `.{{PROJECT_SHORTNAME}}/` exists |
| Multi-Repo | `config/` | `.cursor/commands/` (per-repo) | `config/repos.yml` | Check `config/repos.yml` |
| Standalone | Root | `commands/` | `rules/` | Check root dirs exist |

| Context | When | Key Constraint | Duration |
|---------|------|---|---|
| Template Dev | Editing `templates/` | Preserve {{VARIABLES}} | Variable |
| Feature Impl | Writing code | TDD mandatory | Variable |
| Onboarding | New to project | Load in sequence | 15-20 min |

---

## Related Configuration

- **Project Context:** `00-project-context.mdc` — Repository structure
- **Mode Implementation:** `.{{PROJECT_SHORTNAME}}/` directory (Submodule), `config/repos.yml` (Multi-Repo), `commands/` (Standalone)
- **Onboarding Sequence:** `memory-bank/` files in hierarchical order

---

**Last Updated:** November 3, 2025