---
description: "{{PROJECT_SHORTNAME}}-specific patterns, workflows, and learnings"
globs:
alwaysApply: true
---

# Project Patterns for {{PROJECT_SHORTNAME}}

{{PROJECT_SHORTNAME}}-specific patterns, workflows, and accumulated learnings.

## Git Workflow

**NEVER push directly to main.**

**Branch strategy:**
- `main` - Production releases only
- `dev` - Active development branch (default target)
- `feature/*` - Feature branches (merge to `dev`)
- `hotfix/*` - Emergency fixes (merge to `main` + `dev`)

**Pull request workflow:**
1. Create feature branch from `dev`
2. Implement with tests (TDD)
3. Create PR targeting `dev`
4. After approval, merge to `dev`
5. `dev` → `main` only for releases

**All GitHub operations use API** - See `03-github.mdc`

---

## Release-to-Spec Linking (MANDATORY)

**All releases (minor or major) MUST be mapped to a spec.**

**Optional but recommended:**
- BRD (business requirements)
- PRD (product requirements)

**Structure:**
- Releases: `releases/current/`, `releases/planned/`, `releases/past/`
- Specs: `context/specs/FEATURE-NAME.md`
- BRDs: `context/brds/FEATURE-NAME.md`
- PRDs: `context/prds/FEATURE-NAME.md`

**In release file:**
```markdown
## Related Specs
- Spec: `context/specs/FEATURE-NAME.md`
- BRD: `context/brds/FEATURE-NAME.md` (if applicable)
- PRD: `context/prds/FEATURE-NAME.md` (if applicable)
```

**Purpose:** Requirements traceability, clear scope definition.

---

## GitHub Issue Hierarchy (MANDATORY)

**All releases must link to epics, epics must link to child issues.**

**Templates (always use these):**
- Release: `templates/{{PROJECT_SHORTNAME}}/release.template.md`
- Epic: `templates/{{PROJECT_SHORTNAME}}/epic.template.md`
- Enhancement: `templates/{{PROJECT_SHORTNAME}}/enhancement.template.md`

**Hierarchy structure:**
```
Release (v1.0.0)
  ├─ Epic #1
  │   ├─ Enhancement #10
  │   ├─ Enhancement #11
  │   └─ Enhancement #12
  └─ Epic #2
      └─ Enhancement #13
```

**Linking requirements:**
- Releases link to epics (parent → children)
- Epics link to enhancements (parent → children)
- Use GitHub issue references: `#1`, `#10`
- Always use templates (never freeform issues)

**Purpose:** Traceability, rollup tracking, impact analysis.

---

## Spec-Driven Workflow

**8-stage workflow drives everything:**

1. ANALYSIS → Understand requirements
2. PLANNING → Design approach
3. RELEASE → Define release scope
4. IMPLEMENTATION → Build features
5. CODE ANALYSIS → Review quality
6. TESTING → Validate behavior
7. PUBLISHING → Deploy changes
8. VALIDATION → Confirm success

**Commands automate this workflow:**
- Located in: `.cursor/commands/01-analysis/` through `.cursor/commands/08-validation/`
- Each stage has dedicated commands
- Run commands to execute workflow steps

**Each stage has explicit outputs** (docs, code, tests).

Specs are NOT optional - they're the contract between PM and AI.

---

## Template System

**All templates use {{VARIABLES}} for customer substitution.**

**Never:**
- Hardcode customer-specific values in templates
- Create custom template formats
- Skip variable substitution

**Always:**
- Use generic examples: `{{PROJECT_NAME}}`, not "{{PROJECT_SHORTNAME}}"
- Document all {{VARIABLES}} in template
- Test templates with substitute values

**Template locations:**
- Development: `templates/{{PROJECT_SHORTNAME}}/`
- Published: `.{{PROJECT_SHORTNAME}}/templates/` (in customer projects)

---

## Configuration Management

**No hardcoded runtime values.**

**Externalize all configuration:**
- Environment variables (`.env`)
- Config files (project-specific)
- Never commit secrets or API keys

---

## Known Gotchas

**Publishing:**
- Dual approach: File sync (production) + GitHub API (CI/CD)
- File sync: Fast and reliable
- GitHub API: Rate limit handling required (1s delays between batches)
- See `08-publishing.mdc` for details

**Deployment Modes:**
- Check `09-mode-routing.mdc` for decision tree
- Submodule mode is primary (customers control updates)

**Testing:**
- Always validate RED before implementing (proves test works)
- Profile before optimizing (measure first)

---

## Related Specifications

- **GitHub API:** `03-github.mdc` — API policy and best practices
- **Deployment Modes:** `09-mode-routing.mdc` — Mode decision tree
- **Release Templates:** `templates/{{PROJECT_SHORTNAME}}/release.template.md`
- **Epic Templates:** `templates/{{PROJECT_SHORTNAME}}/epic.template.md`