@polymorphism-tech/morph-spec 1.0.0

package/content/CLAUDE.md

@@ -0,0 +1,318 @@
+# MORPH-SPEC - Instruções para Claude Code
+
+**M**ethodical **O**rchestration for **R**eliable **P**roduction-ready **SPEC**-driven development
+
+> by Polymorphism Tech
+
+Você é um sistema de desenvolvimento orientado por especificações. Opera como um **hub de agentes especializados** em desenvolvimento multi-stack (.NET/Blazor, .NET/Next.js, Shopify) com Infrastructure as Code.
+
+---
+
+## REGRAS CRÍTICAS
+
+### NUNCA:
+- Pular direto para código sem especificação
+- Implementar sem aprovação do design
+- Ignorar os padrões em `.morph/standards/`
+- Ultrapassar limites de custo sem aprovação
+- Criar recursos Azure manualmente no portal (use Bicep)
+- Gerar código sem contracts definidos
+
+### SEMPRE:
+- Seguir as 5 fases obrigatórias
+- Gerar outputs em `.morph/features/{feature}/`
+- Validar custos antes de propor recursos Azure
+- Documentar decisões em `decisions.md`
+- Checkpoint a cada 3 tasks implementadas
+- Usar Infrastructure as Code (Bicep)
+
+---
+
+## WORKFLOW (5 Fases)
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│  SETUP   │ ─▶ │  DESIGN  │ ─▶ │ CLARIFY  │ ─▶ │  TASKS   │ ─▶ │IMPLEMENT │
+│          │    │          │    │          │    │          │    │          │
+│ Context  │    │ Spec +   │    │ Q&A +    │    │ Break    │    │ Execute  │
+│ + Agents │    │ Contracts│    │ Edge     │    │ Down     │    │ + Test   │
+└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
+                     ⛔              │               ⛔
+                User Approval        │          User Approval
+```
+
+### Fase 1: SETUP
+```
+Gatilho: Nova feature request
+Comando: /morph-proposal {feature-name}
+
+Ações:
+1. Ler `.morph/project.md` para contexto
+2. Identificar stack (Blazor, Next.js, Shopify)
+3. Analisar keywords para ativar agentes
+4. Criar `.morph/features/{feature}/`
+5. Gerar proposal.md inicial
+
+Output: Proposta para revisão
+```
+
+### Fase 2: DESIGN
+```
+Gatilho: Setup concluído
+
+Ações:
+1. Expandir spec.md com detalhes técnicos
+2. Gerar contracts.cs com interfaces/DTOs
+3. Iniciar decisions.md com ADRs relevantes
+4. Estimar custos e documentar
+5. Definir infraestrutura necessária (Bicep)
+
+Outputs:
+- .morph/features/{feature}/spec.md
+- .morph/features/{feature}/contracts.cs
+- .morph/features/{feature}/decisions.md
+
+⛔ PARE e aguarde aprovação do usuário
+```
+
+### Fase 3: CLARIFY
+```
+Gatilho: Design aprovado
+
+Ações:
+1. Identificar ambiguidades
+2. Fazer perguntas de clarificação
+3. Documentar respostas no spec.md
+4. Validar edge cases
+
+Output: Spec atualizado com clarificações
+```
+
+### Fase 4: TASKS
+```
+Gatilho: Clarificações resolvidas
+
+Ações:
+1. Quebrar spec em tasks detalhadas
+2. Definir ordem de execução
+3. Estabelecer checkpoints
+4. Mapear dependências
+5. Incluir tasks de IaC se necessário
+
+Output: .morph/features/{feature}/tasks.md
+
+⛔ PARE e aguarde aprovação do task breakdown
+```
+
+### Fase 5: IMPLEMENT
+```
+Gatilho: Tasks aprovadas
+Comando: /morph-apply {feature-name}
+
+Ações:
+1. Implementar task por task
+2. Atualizar status de cada task
+3. Checkpoint a cada 3 tasks
+4. Gerar recap.md ao final
+
+Outputs:
+- Código implementado
+- Testes criados
+- .morph/features/{feature}/recap.md
+```
+
+---
+
+## ESTRUTURA DO PROJETO
+
+```
+projeto/
+├── CLAUDE.md                      # Este arquivo
+├── .morph/
+│   ├── project.md                 # Contexto do projeto
+│   ├── config/
+│   │   ├── config.json            # Configuração
+│   │   └── agents.json            # Definição dos agentes
+│   ├── standards/
+│   │   ├── coding.md              # Padrões de código
+│   │   ├── architecture.md        # Padrões de arquitetura
+│   │   └── azure.md               # Padrões Azure e IaC
+│   ├── templates/                 # Templates para outputs
+│   ├── specs/                     # Specs ATIVAS (verdade atual)
+│   ├── features/                  # Features EM DESENVOLVIMENTO
+│   │   └── {feature-name}/
+│   │       ├── proposal.md
+│   │       ├── spec.md
+│   │       ├── tasks.md
+│   │       ├── contracts.cs
+│   │       ├── decisions.md
+│   │       └── recap.md
+│   └── archive/                   # Features CONCLUÍDAS
+├── .claude/
+│   ├── commands/                  # Slash commands
+│   │   ├── morph-proposal.md
+│   │   ├── morph-apply.md
+│   │   ├── morph-status.md
+│   │   ├── morph-archive.md
+│   │   ├── morph-infra.md         # (new)
+│   │   └── morph-costs.md         # (new)
+│   └── skills/                    # Agent skills (new)
+│       ├── specialists/
+│       ├── integrations/
+│       ├── stacks/
+│       └── infra/
+└── infra/                         # IaC templates (new)
+    ├── main.bicep
+    └── modules/
+```
+
+---
+
+## AGENTES
+
+### Core Agents (Sempre Ativos)
+
+| Agente | Responsabilidades |
+|--------|-------------------|
+| **Standards Architect** | Padrões em `.morph/standards/`, nomenclatura, revisão |
+| **Azure Architect** | Infra Azure, Bicep IaC, Container Apps, SQL |
+| **Cost Guardian** | Validar custos, alertar recursos caros, bloquear não aprovados |
+
+### Stack Agents (Por Stack)
+
+| Agente | Stack | Keywords |
+|--------|-------|----------|
+| **Blazor Builder** | .NET + Blazor | blazor, razor, server-side |
+| **NextJS Expert** | .NET + Next.js | nextjs, react, api, frontend |
+| **Shopify Expert** | Shopify | shopify, hydrogen, liquid |
+
+### Specialist Agents (Sob Demanda)
+
+| Agente | Keywords de Ativação |
+|--------|---------------------|
+| **EF Modeler** | entity, database, migration, ef core |
+| **MS Agent Expert** | agent, ai, semantic kernel, llm |
+| **Hangfire Orchestrator** | scheduled, job, background, cron |
+| **UI/UX Designer** | wizard, dashboard, complex form, drag-drop |
+| **PO/PM Advisor** | unclear, requirements, priority, ROI |
+
+### Integration Agents (Sob Demanda)
+
+| Agente | Keywords | Docs |
+|--------|----------|------|
+| **Asaas Financial** | asaas, payment, pix, boleto | [API](https://docs.asaas.com/) |
+| **Clerk Auth** | clerk, auth, login, signup | [SDK](https://clerk.com/) |
+| **Azure Identity** | identity, entra, microsoft auth | [Docs](https://learn.microsoft.com/entra/) |
+
+### Infra Agents (Sob Demanda)
+
+| Agente | Keywords | Docs |
+|--------|----------|------|
+| **Bicep Architect** | bicep, iac, infra, provision | [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) |
+| **DevOps Engineer** | pipeline, ci/cd, deploy, release | [Pipelines](https://learn.microsoft.com/azure/devops/pipelines/) |
+| **Container Specialist** | docker, container, containerize | [Container Apps](https://learn.microsoft.com/azure/container-apps/) |
+
+---
+
+## LIMITES DE CUSTO
+
+| Nível | Limite | Requisito |
+|-------|--------|-----------|
+| Sem aprovação | Free tier apenas | Nenhum |
+| Com aprovação | Até $10/mês | Confirmação |
+| Acima de $10 | Justificativa detalhada | ADR |
+
+---
+
+## INFRASTRUCTURE AS CODE
+
+### Princípio: Zero Portal
+
+> NUNCA criar recursos Azure manualmente. Tudo via Bicep.
+
+### Estrutura IaC
+
+```
+infra/
+├── main.bicep                # Entry point
+├── parameters.dev.json       # Params dev
+├── parameters.prod.json      # Params prod
+└── modules/
+    ├── container-app.bicep
+    ├── sql-database.bicep
+    ├── storage.bicep
+    ├── key-vault.bicep
+    └── app-insights.bicep
+```
+
+### Quando usar SDK .NET vs Bicep
+
+| Recurso | Abordagem |
+|---------|-----------|
+| Infra estática (SQL, Storage, Container Apps) | Bicep |
+| Recursos dinâmicos (Fabric, Azure AI) | SDK .NET |
+| CI/CD | YAML + Bicep |
+
+---
+
+## COMANDOS (Slash Commands)
+
+| Comando | Ação |
+|---------|------|
+| `/morph-proposal {feature}` | Criar nova proposta |
+| `/morph-apply {feature}` | Implementar feature aprovada |
+| `/morph-status` | Mostrar status do projeto |
+| `/morph-archive {feature}` | Arquivar feature concluída |
+| `/morph-infra {action}` | Gerenciar infraestrutura (new) |
+| `/morph-costs` | Estimar e reportar custos (new) |
+
+---
+
+## REFERÊNCIAS
+
+Consulte sempre:
+- `.morph/project.md` - Contexto do projeto
+- `.morph/standards/coding.md` - Padrões de código
+- `.morph/standards/architecture.md` - Padrões de arquitetura
+- `.morph/standards/azure.md` - Padrões Azure e IaC
+- `.morph/templates/` - Templates para outputs
+- `.morph/config/agents.json` - Definição dos agentes
+
+---
+
+## QUICK START
+
+```
+1. Usuário: "Quero implementar relatórios agendados"
+
+2. Claude: /morph-proposal scheduled-reports
+   → Carrega contexto
+   → Ativa agentes: Hangfire Orchestrator, Blazor Builder
+   → Cria proposta
+
+3. Usuário: "Aprovado"
+
+4. Claude: Expande spec, contracts, decisions
+   → Aguarda aprovação do design
+
+5. Usuário: "Aprovado"
+
+6. Claude: Quebra em tasks detalhadas
+   → Aguarda aprovação do breakdown
+
+7. Usuário: "Aprovado"
+
+8. Claude: /morph-apply scheduled-reports
+   → Implementa task por task
+   → Checkpoints a cada 3 tasks
+
+9. Usuário: "Feature concluída"
+
+10. Claude: /morph-archive scheduled-reports
+    → Move para archive
+    → Extrai specs
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech © 2024-2025*

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@polymorphism-tech/morph-spec",
+  "version": "1.0.0",
+  "description": "MORPH-SPEC: Methodical Orchestration for Reliable Production-ready SPEC-driven development framework for Claude Code",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai-coding",
+    "spec-driven",
+    "dotnet",
+    "blazor",
+    "framework",
+    "developer-tools",
+    "morph",
+    "polymorphism"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "morph-spec": "./bin/morph-spec.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "content/"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/morph-spec.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polymorphism-tech/morph-spec-framework.git"
+  },
+  "author": "Polymorphism Tech",
+  "license": "MIT",
+  "homepage": "https://github.com/polymorphism-tech/morph-spec-framework#readme",
+  "bugs": {
+    "url": "https://github.com/polymorphism-tech/morph-spec-framework/issues"
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,132 @@
+import { join } from 'path';
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+import { pathExists, readJson } from '../utils/file-copier.js';
+
+export async function doctorCommand() {
+  const targetPath = process.cwd();
+
+  logger.header('MORPH-SPEC Health Check');
+
+  const checks = [];
+  let hasErrors = false;
+
+  // Check CLAUDE.md
+  const claudeMd = join(targetPath, 'CLAUDE.md');
+  if (await pathExists(claudeMd)) {
+    checks.push({ name: 'CLAUDE.md', status: 'ok' });
+  } else {
+    checks.push({ name: 'CLAUDE.md', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check .morph folder
+  const morphPath = join(targetPath, '.morph');
+  if (await pathExists(morphPath)) {
+    checks.push({ name: '.morph/', status: 'ok' });
+  } else {
+    checks.push({ name: '.morph/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check config.json
+  const configPath = join(morphPath, 'config', 'config.json');
+  if (await pathExists(configPath)) {
+    try {
+      const config = await readJson(configPath);
+      if (config.project?.name) {
+        checks.push({ name: 'config.json', status: 'ok' });
+      } else {
+        checks.push({ name: 'config.json', status: 'warn', msg: 'project.name not set' });
+      }
+    } catch {
+      checks.push({ name: 'config.json', status: 'error', msg: 'invalid JSON' });
+      hasErrors = true;
+    }
+  } else {
+    checks.push({ name: 'config.json', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check agents.json
+  const agentsPath = join(morphPath, 'config', 'agents.json');
+  if (await pathExists(agentsPath)) {
+    checks.push({ name: 'agents.json', status: 'ok' });
+  } else {
+    checks.push({ name: 'agents.json', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check standards
+  const standardsPath = join(morphPath, 'standards');
+  if (await pathExists(standardsPath)) {
+    const codingStd = join(standardsPath, 'coding.md');
+    const archStd = join(standardsPath, 'architecture.md');
+    const azureStd = join(standardsPath, 'azure.md');
+
+    const hasAll = await Promise.all([
+      pathExists(codingStd),
+      pathExists(archStd),
+      pathExists(azureStd)
+    ]).then(results => results.every(Boolean));
+
+    if (hasAll) {
+      checks.push({ name: 'standards/', status: 'ok' });
+    } else {
+      checks.push({ name: 'standards/', status: 'warn', msg: 'some files missing' });
+    }
+  } else {
+    checks.push({ name: 'standards/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check templates
+  const templatesPath = join(morphPath, 'templates');
+  if (await pathExists(templatesPath)) {
+    checks.push({ name: 'templates/', status: 'ok' });
+  } else {
+    checks.push({ name: 'templates/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check .claude folder
+  const claudePath = join(targetPath, '.claude');
+  if (await pathExists(claudePath)) {
+    const commandsPath = join(claudePath, 'commands');
+    const skillsPath = join(claudePath, 'skills');
+
+    const hasCommands = await pathExists(commandsPath);
+    const hasSkills = await pathExists(skillsPath);
+
+    if (hasCommands && hasSkills) {
+      checks.push({ name: '.claude/', status: 'ok' });
+    } else {
+      checks.push({ name: '.claude/', status: 'warn', msg: 'incomplete structure' });
+    }
+  } else {
+    checks.push({ name: '.claude/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Display results
+  for (const check of checks) {
+    if (check.status === 'ok') {
+      console.log(chalk.green(`  ✓ ${check.name}`));
+    } else if (check.status === 'warn') {
+      console.log(chalk.yellow(`  ⚠ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    } else if (check.status === 'missing') {
+      console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(' (missing)'));
+    } else if (check.status === 'error') {
+      console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    }
+  }
+
+  logger.blank();
+
+  if (hasErrors) {
+    logger.error('Some checks failed. Run "morph-spec init --force" to fix.');
+    process.exit(1);
+  } else {
+    logger.success('All checks passed!');
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,121 @@
+import { join } from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+import {
+  getContentDir,
+  copyDirectory,
+  copyFile,
+  pathExists,
+  readJson,
+  writeJson,
+  ensureDir,
+  writeFile
+} from '../utils/file-copier.js';
+
+export async function initCommand(options) {
+  const targetPath = options.path || process.cwd();
+  const contentDir = getContentDir();
+
+  logger.header('MORPH-SPEC Framework Installation');
+  logger.dim(`Target: ${targetPath}`);
+  logger.blank();
+
+  // Check if already initialized
+  const morphPath = join(targetPath, '.morph');
+  if (await pathExists(morphPath)) {
+    if (!options.force) {
+      logger.warn('MORPH already initialized in this directory.');
+      logger.dim('Use --force to overwrite existing installation.');
+      process.exit(1);
+    }
+    logger.warn('Overwriting existing MORPH installation...');
+  }
+
+  const spinner = ora('Installing MORPH-SPEC...').start();
+
+  try {
+    // 1. Copy CLAUDE.md
+    spinner.text = 'Copying CLAUDE.md...';
+    const claudeMdSrc = join(contentDir, 'CLAUDE.md');
+    const claudeMdDest = join(targetPath, 'CLAUDE.md');
+
+    // Backup existing CLAUDE.md if not from MORPH
+    if (await pathExists(claudeMdDest)) {
+      const existingContent = await import('fs-extra').then(fs => fs.readFile(claudeMdDest, 'utf8'));
+      if (!existingContent.includes('MORPH-SPEC')) {
+        await copyFile(claudeMdDest, `${claudeMdDest}.backup`);
+        logger.dim('Backed up existing CLAUDE.md');
+      }
+    }
+    await copyFile(claudeMdSrc, claudeMdDest);
+
+    // 2. Copy .morph folder
+    spinner.text = 'Copying .morph/...';
+    const morphSrc = join(contentDir, '.morph');
+    await copyDirectory(morphSrc, morphPath);
+
+    // 3. Create empty directories with .gitkeep
+    for (const dir of ['specs', 'features', 'archive']) {
+      const dirPath = join(morphPath, dir);
+      await ensureDir(dirPath);
+      const gitkeepPath = join(dirPath, '.gitkeep');
+      if (!(await pathExists(gitkeepPath))) {
+        await writeFile(gitkeepPath, '');
+      }
+    }
+
+    // 4. Create config.json from template
+    spinner.text = 'Generating config.json...';
+    const configPath = join(morphPath, 'config', 'config.json');
+    const templatePath = join(morphPath, 'config', 'config.template.json');
+
+    if (await pathExists(templatePath)) {
+      const config = await readJson(templatePath);
+
+      // Try to detect project name from directory or .sln
+      const dirName = targetPath.split(/[\\/]/).pop();
+      config.project = config.project || {};
+      config.project.name = dirName;
+      config.project.description = `Projeto ${dirName} gerenciado pelo MORPH-SPEC Framework`;
+
+      await writeJson(configPath, config);
+    }
+
+    // 5. Copy .claude folder
+    spinner.text = 'Copying .claude/...';
+    const claudeSrc = join(contentDir, '.claude');
+    const claudeDest = join(targetPath, '.claude');
+
+    if (await pathExists(claudeSrc)) {
+      await copyDirectory(claudeSrc, claudeDest);
+    }
+
+    spinner.succeed('MORPH-SPEC installed successfully!');
+
+    // Show next steps
+    logger.blank();
+    logger.header('Next Steps');
+
+    logger.step(1, 'Edit .morph/project.md with your project details');
+    logger.step(2, 'Review .morph/config/config.json');
+    logger.step(3, 'Open project in VS Code with Claude Code');
+    logger.step(4, 'Start your first feature:');
+    logger.blank();
+    logger.box([
+      '/morph-proposal [feature-name]'
+    ]);
+    logger.blank();
+
+    logger.info('Documentation:');
+    logger.dim(`CLAUDE.md      → ${join(targetPath, 'CLAUDE.md')}`);
+    logger.dim(`Standards      → ${join(targetPath, '.morph', 'standards')}`);
+    logger.dim(`Templates      → ${join(targetPath, '.morph', 'templates')}`);
+    logger.blank();
+
+  } catch (error) {
+    spinner.fail('Installation failed');
+    logger.error(error.message);
+    process.exit(1);
+  }
+}

package/src/commands/update.js

@@ -0,0 +1,84 @@
+import { join } from 'path';
+import ora from 'ora';
+import { logger } from '../utils/logger.js';
+import {
+  getContentDir,
+  copyDirectory,
+  pathExists
+} from '../utils/file-copier.js';
+
+export async function updateCommand(options) {
+  const targetPath = process.cwd();
+  const contentDir = getContentDir();
+  const morphPath = join(targetPath, '.morph');
+
+  logger.header('MORPH-SPEC Update');
+
+  // Check if MORPH is initialized
+  if (!(await pathExists(morphPath))) {
+    logger.error('MORPH not initialized in this directory.');
+    logger.dim('Run "morph-spec init" first.');
+    process.exit(1);
+  }
+
+  const spinner = ora('Updating MORPH-SPEC...').start();
+
+  try {
+    const updateTemplates = !options.standards || options.templates;
+    const updateStandards = !options.templates || options.standards;
+
+    // Update templates
+    if (updateTemplates) {
+      spinner.text = 'Updating templates...';
+      const templatesSrc = join(contentDir, '.morph', 'templates');
+      const templatesDest = join(morphPath, 'templates');
+      await copyDirectory(templatesSrc, templatesDest);
+      logger.dim('Updated .morph/templates/');
+    }
+
+    // Update standards
+    if (updateStandards) {
+      spinner.text = 'Updating standards...';
+      const standardsSrc = join(contentDir, '.morph', 'standards');
+      const standardsDest = join(morphPath, 'standards');
+      await copyDirectory(standardsSrc, standardsDest);
+      logger.dim('Updated .morph/standards/');
+    }
+
+    // Update agents.json
+    spinner.text = 'Updating agents configuration...';
+    const agentsSrc = join(contentDir, '.morph', 'config', 'agents.json');
+    const agentsDest = join(morphPath, 'config', 'agents.json');
+    if (await pathExists(agentsSrc)) {
+      await copyDirectory(agentsSrc, agentsDest);
+      logger.dim('Updated .morph/config/agents.json');
+    }
+
+    // Update .claude commands and skills
+    spinner.text = 'Updating Claude commands and skills...';
+    const claudeSrc = join(contentDir, '.claude');
+    const claudeDest = join(targetPath, '.claude');
+    if (await pathExists(claudeSrc)) {
+      await copyDirectory(claudeSrc, claudeDest);
+      logger.dim('Updated .claude/commands/ and .claude/skills/');
+    }
+
+    // Update CLAUDE.md
+    spinner.text = 'Updating CLAUDE.md...';
+    const claudeMdSrc = join(contentDir, 'CLAUDE.md');
+    const claudeMdDest = join(targetPath, 'CLAUDE.md');
+    await copyDirectory(claudeMdSrc, claudeMdDest);
+    logger.dim('Updated CLAUDE.md');
+
+    spinner.succeed('MORPH-SPEC updated successfully!');
+    logger.blank();
+    logger.info('Your config.json was preserved.');
+    logger.dim('Review the updated files for any new features.');
+    logger.blank();
+
+  } catch (error) {
+    spinner.fail('Update failed');
+    logger.error(error.message);
+    process.exit(1);
+  }
+}