# MORPH-SPEC - Claude Code Instructions

> by Polymorphism Tech

Spec-driven development system. Specialized agent hub for multi-stack projects with Infrastructure as Code.

---

## CRITICAL RULES

### NEVER:
- Skip to code without a specification
- Implement without design approval
- Ignore standards in `.morph/standards/`
- Create infrastructure manually
- Generate code without defined contracts

### ALWAYS:
- Follow the 5 mandatory phases
- Generate outputs in `.morph/project/outputs/{feature}/`
- Document decisions in `decisions.md`
- Checkpoint every 3 implemented tasks
- Use Infrastructure as Code

---

## WORKFLOW (5 Phases)

| Phase | Trigger | Actions | Output | Pause? |
|-------|---------|---------|--------|--------|
| **1. SETUP** | Feature request | Read project context, identify stack, activate agents, create folder | proposal.md | No |
| **2. DESIGN** | Setup done | Spec + contracts + decisions + costs | spec.md, contracts, decisions.md | **Yes** |
| **3. CLARIFY** | Design approved | Ambiguities, questions, edge cases | Updated spec | No |
| **4. TASKS** | Clarifications resolved | Break into tasks, ordering, checkpoints, dependencies | tasks.md | **Yes** |
| **5. IMPLEMENT** | Tasks approved | Task by task, checkpoint every 3, recap | Code + recap.md | No |

---

## PROJECT STRUCTURE

```
project/
├── CLAUDE.md
├── .morph/
│   ├── config/                     # config.json, agents.json
│   ├── standards/                  # coding, architecture, stack-specific
│   ├── templates/                  # Output templates
│   ├── project/
│   │   ├── context/                # detection-log.md, project.md
│   │   ├── standards/              # inferred.md, overrides.md
│   │   └── outputs/{feature}/     # Features in development
│   │       ├── proposal.md, spec.md, tasks.md
│   │       ├── contracts, decisions.md, recap.md
└── .claude/commands/               # Slash commands
```

---

## AGENTS

### Tier 1 — Orchestrators (Always Active)

| Agent | Responsibilities |
|-------|-----------------|
| **Standards Architect** | Standards, naming, review, cross-cutting concerns |
| **AI System Architect** | Agent systems, AI integrations, LLM orchestration |
| **Thread Orchestrator** | Parallel execution, thread management, context optimization |

### Tier 2 — Domain Leaders

| Agent | Responsibilities |
|-------|-----------------|
| **Tech Lead** | Architecture decisions, code quality, task breakdown |
| **DevOps Engineer** | CI/CD, deployment pipelines, infrastructure |
| **QA Lead** | Test strategies, validation, quality gates |

### Tier 3 — Specialists (Activated by keywords)

| Agent | Keywords |
|-------|---------|
| **Next.js Expert** | nextjs, react, frontend, app router, pages |
| **Blazor Builder** | blazor, razor, mudblazor, fluent ui |
| **API Designer** | api, endpoint, rest, openapi, swagger |
| **.NET Senior** | dotnet, csharp, minimal api, ef core |
| **EF Modeler** | entity framework, migrations, dbcontext |
| **Azure Architect** | azure, container apps, bicep, app service |
| **Bicep Architect** | bicep, iac, arm template, azure resources |
| **Azure Deploy Specialist** | deploy, ci/cd, github actions, azure devops |
| **Container Specialist** | docker, dockerfile, compose, kubernetes |
| **Supabase Expert** | supabase, postgresql, rls, realtime, pgvector |
| **Azure Identity** | auth, authentication, entra id, jwt, oauth |
| **Clerk Auth** | clerk, auth0, authentication, social login |
| **Asaas Financial** | payment, billing, subscription, asaas |
| **Resend Email** | email, resend, smtp, notifications |
| **Hangfire Orchestrator** | background jobs, queue, scheduling, hangfire |
| **MS Agent Expert** | semantic kernel, microsoft agents, ai pipeline |
| **UI/UX Designer** | design, ux, wireframe, mockup, figma |
| **SEO Growth Hacker** | seo, performance, analytics, lighthouse |
| **PO/PM Advisor** | product, roadmap, requirements, user stories |
| **Prompt Engineer** | prompts, system prompts, llm, few-shot |
| **Context Optimizer** | context window, token optimization, chunking |
| **Vector Search Expert** | vector db, embeddings, semantic search, rag |
| **Observability Expert** | logging, tracing, metrics, opentelemetry |
| **Code Analyzer** | refactor, analysis, code review, complexity |
| **Testing Specialist** | tests, coverage, tdd, bdd, vitest, jest, xunit |

### Tier 4 — Validators

| Agent | Responsibilities |
|-------|-----------------|
| **Contract Compliance Validator** | Ensures implementation matches spec contracts |

---

## TEMPLATES

> ALWAYS use `morph-spec template render` to render. NEVER fill placeholders manually.

### Placeholders: `{{PLACEHOLDER}}`

| Placeholder | Example |
|-------------|---------|
| `{{FEATURE_NAME}}` | `scheduled-reports` |
| `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
| `{{FEATURE_NAME_CAMEL}}` | `scheduledReports` |
| `{{STACK}}` | `blazor-azure` or `nextjs-supabase` |
| `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |

---

## COMMANDS

| Command | Action |
|---------|--------|
| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, auto-continuation with pauses) |
| `/morph-apply {feature}` | Implement feature (phase 5) |
| `/morph-status` | Dashboard |
| `/morph-archive {feature}` | Archive completed feature |
| `/morph-infra {action}` | Manage infrastructure |
| `/morph-preflight` | Pre-deploy validation |
| `/morph-troubleshoot {error}` | Error troubleshooting |

---

## REFERENCES

- `.morph/config/config.json` — Project configuration
- `.morph/config/agents.json` — Full agent definitions
- `.morph/standards/` — Coding, architecture, stack-specific standards
- `.morph/project/context/` — Detection log, project context
- `.morph/project/standards/inferred.md` — Auto-detected project standards

---

*MORPH-SPEC v4.3.0 by Polymorphism Tech*
