@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

package/framework/hooks/shared/worktree-helpers.js

@@ -1,75 +0,0 @@
-/**
- * Shared helpers for worktree-related hook logic.
- * Pure functions — no side effects, easy to test.
- */
-
-/**
- * Parse JSON output from `morph-spec worktree setup`.
- * Finds the last line starting with '{' to skip chalk-colored output.
- * @param {string} stdout - Raw stdout from the command
- * @returns {Object|null}
- */
-export function parseWorktreeResult(stdout) {
-  if (!stdout || typeof stdout !== 'string') return null;
-  try {
-    const trimmed = stdout.trim();
-    if (!trimmed) return null;
-    const lines = trimmed.split('\n');
-    for (let i = lines.length - 1; i >= 0; i--) {
-      const line = lines[i].trim();
-      if (line.startsWith('{')) {
-        return JSON.parse(line);
-      }
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Build context line(s) to inject based on worktree setup result.
- * Outputs MANDATORY instructions for Claude to work inside the worktree.
- * @param {Object|null} result - Parsed result from parseWorktreeResult
- * @returns {string} Context lines to inject, or '' to skip injection
- */
-export function buildWorktreeContextLine(result) {
-  if (!result) return '';
-  if (result.error) return '';
-
-  const path = result.path;
-  const feature = result.feature || '';
-
-  if (result.created || result.alreadyExists) {
-    return [
-      `🪴 WORKTREE ACTIVE — branch: ${result.branch}`,
-      `   WORKTREE_PATH: ${path}`,
-      `   MANDATORY: ALL work for feature '${feature}' MUST happen inside the worktree:`,
-      `   • Bash: run \`cd ${path}\` first (CWD persists for subsequent commands)`,
-      `   • Read/Write/Edit: use ${path} as base for ALL file paths`,
-      `   • Glob/Grep: set path parameter to ${path}`,
-      `   DO NOT write files to the main project directory.`,
-    ].join('\n');
-  }
-
-  return '';
-}
-
-/**
- * Build worktree context from state metadata (for resume sessions).
- * @param {Object} worktreeMeta - { path, branch } from state.features[name].worktree
- * @param {string} featureName - Feature name
- * @returns {string} Context lines or ''
- */
-export function buildWorktreeResumeContext(worktreeMeta, featureName) {
-  if (!worktreeMeta?.path) return '';
-  return [
-    `🪴 WORKTREE ACTIVE — branch: ${worktreeMeta.branch}`,
-    `   WORKTREE_PATH: ${worktreeMeta.path}`,
-    `   MANDATORY: ALL work for feature '${featureName}' MUST happen inside the worktree:`,
-    `   • Bash: run \`cd ${worktreeMeta.path}\` first (CWD persists for subsequent commands)`,
-    `   • Read/Write/Edit: use ${worktreeMeta.path} as base for ALL file paths`,
-    `   • Glob/Grep: set path parameter to ${worktreeMeta.path}`,
-    `   DO NOT write files to the main project directory.`,
-  ].join('\n');
-}

package/framework/skills/level-0-meta/README.md

@@ -1,7 +0,0 @@
-# Level 0: Meta-Skills
-
-High-level orchestration skills and user-facing commands.
-
-**Purpose:** Skills that orchestrate multiple workflows or provide top-level guidance.
-
-**Examples:** morph-checklist, simulation-checklist, code-review

package/framework/skills/level-0-meta/morph-agent-teams/SKILL.md

@@ -1,472 +0,0 @@
----
-name: morph-agent-teams
-description: Guide for orchestrating Claude Code Agent Teams within MORPH-SPEC workflows. Covers team setup, parallel implementation patterns, architecture debate teams, and integration with MORPH phases and validation gates. Use when a feature has 3+ independent modules that benefit from parallel development.
-user-invocable: true
-argument-hint: "[feature-name]"
-allowed-tools: Read, Bash, Glob, Grep, Edit, Write, AskUserQuestion
----
-
-# Agent Teams Workflow - Claude Code Integration
-
-> Orchestrate multiple Claude Code instances as a coordinated team for parallel development workflows within MORPH-SPEC.
-
-**Status:** EXPERIMENTAL - Enable via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
-
----
-
-## Overview
-
-**Agent Teams** are a Claude Code feature that coordinates multiple independent Claude instances working together on complex tasks. Unlike subagents (which run within a single context and only report back), Agent Teams members can communicate directly with each other, share findings, challenge each other's approaches, and coordinate through a shared task list.
-
-### Core Architecture
-
-| Component | Role |
-|-----------|------|
-| **Team Lead** | Main Claude session that creates the team, spawns teammates, coordinates work |
-| **Teammates** | Independent Claude Code instances, each with own context window |
-| **Shared Task List** | Coordinated work items with dependencies and state (pending/in-progress/completed) |
-| **Mailbox** | Direct messaging system between agents |
-
-**Storage:**
-- Team config: `~/.claude/teams/{team-name}/config.json`
-- Task list: `~/.claude/tasks/{team-name}/`
-
----
-
-## Agent Teams vs Subagents
-
-| Aspect | Subagents | Agent Teams |
-|--------|-----------|-------------|
-| **Context** | Own context, results return to caller | Fully independent contexts |
-| **Communication** | Report back to main agent only | Direct inter-teammate messaging + broadcast |
-| **Coordination** | Main agent manages all work | Shared task list with self-claiming |
-| **Best for** | Focused research, verification, isolated tasks | Complex work requiring discussion & collaboration |
-| **Token cost** | Lower (results summarized) | Higher (each teammate = separate Claude instance) |
-| **Use in MORPH** | Quick analysis, validation, isolated research | Parallel feature implementation, multi-module refactoring |
-
----
-
-## When to Use Agent Teams in MORPH-SPEC
-
-### Strong Use Cases
-
-1. **Parallel Feature Implementation (Phase 5 - Implement)**
-   - Multiple independent features in the same release
-   - Each teammate owns 1-2 modules (e.g., Auth, Payments, Reporting)
-   - No file conflicts (each module has distinct files)
-
-2. **Architecture Review & Debugging**
-   - Multiple teammates investigate competing hypotheses
-   - Each applies different lens (security, performance, maintainability)
-   - Teams debate and converge on best solution
-
-3. **Cross-Stack Coordination**
-   - Frontend teammate (Next.js + shadcn/ui)
-   - Backend teammate (API + .NET VSA)
-   - Infrastructure teammate (EasyPanel + Neon)
-   - Testing teammate (unit + integration)
-
-4. **Research & Standards Validation (Phases 0-3)**
-   - Investigate multiple integration options (Neon Auth vs custom JWT vs Passkeys)
-   - Compare UI patterns (shadcn/ui component composition strategies)
-   - Validate architecture patterns (CQRS vs simple Repository)
-
-### Not Recommended
-
-- Single-file edits or small bug fixes
-- Sequential tasks with many dependencies
-- Same-file modifications by multiple teammates (causes conflicts)
-- Routine tasks where coordination overhead > benefit
-
----
-
-## Setup & Configuration
-
-### 1. Enable Agent Teams
-
-Add to `.claude/settings.local.json` (or env variable):
-
-```json
-{
-  "env": {
-    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
-  },
-  "teammateMode": "auto"
-}
-```
-
-**Display Modes:**
-- `"auto"`: Split panes if in tmux, otherwise in-process
-- `"in-process"`: All teammates in main terminal (Shift+Up/Down to switch)
-- `"tmux"`: Each teammate in separate pane (requires tmux or iTerm2)
-
-### 2. Start a Team
-
-**Natural Language Request:**
-```
-Create an agent team to implement the scheduled-reports feature.
-Spawn 3 teammates:
-- Backend engineer: .NET VSA endpoints + Hangfire jobs (uses dotnet-senior, hangfire-orchestrator skills)
-- Frontend engineer: Dashboard + report viewer (uses nextjs-expert, ui-designer skills)
-- Testing engineer: Unit + integration tests (uses dotnet-senior skill)
-
-Require plan approval for each teammate before implementation.
-```
-
-**What Claude Does:**
-1. Creates team config in `~/.claude/teams/scheduled-reports/`
-2. Spawns 3 independent Claude instances
-3. Each teammate loads project context (CLAUDE.md, MCP servers, skills)
-4. Lead assigns initial tasks from shared task list
-5. Teammates work in plan mode until lead approves
-6. After approval, teammates implement independently
-
-### 3. Control the Team
-
-**Delegate Mode** (Lead focuses on coordination only):
-```
-Press Shift+Tab to cycle into delegate mode
-```
-- Lead can't use code tools (Edit/Write/Bash)
-- Only coordination tools: spawn, message, task management
-
-**Direct Teammate Communication:**
-- In-process mode: Shift+Up/Down to select, type to message
-- Split-pane mode: Click teammate pane to interact directly
-
-**Task Management:**
-```
-# Lead assigns task
-Assign task T003 (implement report scheduler) to the backend engineer
-
-# Teammate self-claims next available task
-After completing T001, backend engineer claims T004 (add report repository)
-```
-
-**Shutdown:**
-```
-Ask the backend teammate to shut down gracefully
-```
-
----
-
-## MORPH-SPEC Integration Patterns
-
-### Pattern 1: Parallel Feature Implementation (Implement Phase)
-
-**Scenario:** Multi-module feature with independent components
-
-```bash
-# 1. Complete phases 0-4 normally (proposal -> design -> tasks)
-morph-spec state set scheduled-reports phase implement
-
-# 2. Claude creates agent team based on tasks.json structure
-# Example tasks.json with module grouping:
-{
-  "tasks": [
-    { "id": "T001", "module": "backend", "title": "Create ReportDefinition entity" },
-    { "id": "T002", "module": "backend", "title": "Implement Hangfire scheduler" },
-    { "id": "T003", "module": "frontend", "title": "Create report dashboard page" },
-    { "id": "T004", "module": "frontend", "title": "Add report preview component" },
-    { "id": "T005", "module": "infra", "title": "Configure Neon database branch for reports" },
-    { "id": "T006", "module": "tests", "title": "Unit tests for scheduler", "dependsOn": ["T002"] }
-  ]
-}
-```
-
-**Team Structure:**
-- **Lead:** Standards Architect (coordinates, validates contracts, syncs decisions.md)
-- **Backend Teammate:** .NET Senior + Hangfire Orchestrator
-- **Frontend Teammate:** Next.js Expert + UI Designer
-- **Infra Teammate:** Infra Architect (EasyPanel + Neon)
-- **Testing Teammate:** (Handled by backend or frontend teammate)
-
-**Workflow:**
-1. Lead assigns tasks by module
-2. Each teammate implements their tasks independently
-3. Teammates run `morph-spec task done {feature} {task-id}` after each task
-4. Validation pipeline runs automatically (contract compliance, decisions constraints)
-5. Lead synthesizes recap.md after all tasks complete
-
-### Pattern 2: Architecture Decision Debate (Design Phase)
-
-**Scenario:** Multiple valid approaches for complex problem
-
-```
-Create an agent team to decide on the authentication architecture.
-Spawn 3 debate teammates:
-- Pro-Neon-Auth: Argue for Neon Auth (database-native, no external deps, branch isolation, Better Auth)
-- Pro-NextAuth: Argue for NextAuth.js (flexible providers, community ecosystem, self-hosted)
-- Pro-Custom: Argue for custom JWT + Passkeys (full control, no vendor lock-in)
-
-Have them debate, challenge each other's assumptions, and document pros/cons.
-Update decisions.md with consensus.
-```
-
-**Output:** Structured ADR in `decisions.md` with all perspectives considered
-
-### Pattern 3: Code Review by Concern (Post-Implementation)
-
-**Scenario:** Thorough review before production deployment
-
-```
-Create an agent team to review the scheduled-reports implementation.
-Spawn 4 reviewers:
-- Security reviewer: Auth, SQL injection, XSS, secrets management
-- Performance reviewer: Query efficiency, caching, background job overhead
-- Standards reviewer: Next.js patterns, .NET VSA best practices, contract compliance
-- UX reviewer: Accessibility, responsive design, error handling
-
-Each reviewer reports findings to the lead, then synthesize into review.md
-```
-
----
-
-## Best Practices for MORPH-SPEC
-
-### 1. Size Tasks Appropriately
-
-**Good task granularity (5-6 tasks per teammate):**
-```json
-{
-  "id": "T003",
-  "title": "Implement report scheduling service",
-  "module": "backend",
-  "files": ["Features/Reports/ScheduleReport/Endpoint.cs", "Jobs/GenerateReportJob.cs"],
-  "estimatedHours": 2
-}
-```
-
-**Too small (coordination overhead > benefit):**
-```json
-{ "id": "T001", "title": "Add using statement" }
-```
-
-**Too large (teammate works too long without check-ins):**
-```json
-{ "id": "T099", "title": "Implement entire authentication system" }
-```
-
-### 2. Prevent File Conflicts
-
-**Design task ownership to avoid overlapping edits:**
-
-**Bad (conflict risk):**
-- Backend teammate modifies `Program.cs` for DI
-- Frontend teammate modifies `next.config.ts` for redirects
-
-**Good (isolated ownership):**
-- Backend teammate: `Features/`, `Jobs/`, `Infrastructure/`
-- Frontend teammate: `app/`, `components/`, `lib/`
-- Lead handles shared files (`Program.cs`, `next.config.ts`) after review
-
-### 3. Leverage Shared Context
-
-**All teammates automatically load:**
-- `CLAUDE.md` (MORPH-SPEC instructions)
-- `.claude/skills/` (all available skills)
-- `.morph/config.json` (project configuration)
-- `framework/standards/` + `.morph/framework/standards/`
-
-**Pass task-specific context in spawn prompt:**
-```
-Spawn backend teammate with prompt: "Implement scheduled reports feature.
-Active agents: dotnet-senior, hangfire-orchestrator.
-Read .morph/features/scheduled-reports/2-design/spec.md and contracts.
-All background jobs MUST use scoped DI and follow VSA endpoint patterns."
-```
-
-### 4. Use Hooks for Quality Gates
-
-**Enforce validation before task completion:**
-
-```json
-// .claude/hooks.json
-{
-  "TaskCompleted": {
-    "command": "morph-spec validate-task ${MORPH_FEATURE} ${TASK_ID}",
-    "exitCode2Feedback": "Task validation failed. Fix violations before marking complete."
-  },
-  "TeammateIdle": {
-    "command": "morph-spec check-teammate-progress ${TEAMMATE_ID}",
-    "exitCode2Feedback": "Teammate has incomplete work. Continue implementation."
-  }
-}
-```
-
-### 5. Monitor Token Usage
-
-**Agent Teams = High Token Cost:**
-- Each teammate = separate Claude instance with full context
-- 4 teammates on a 2-hour task = 4x token usage vs single session
-
-**When worth it:**
-- Parallel implementation of 3+ independent modules
-- Complex architecture decisions requiring debate
-- Time-sensitive features where parallel work reduces calendar time
-
-**When NOT worth it:**
-- Single-module features
-- Sequential refactoring
-- Simple bug fixes
-
----
-
-## Troubleshooting
-
-### Issue: Lead Implements Instead of Delegating
-
-**Symptom:** Lead starts coding tasks instead of waiting for teammates
-
-**Solution:**
-```
-Wait for your teammates to complete their tasks before proceeding.
-Use delegate mode to restrict yourself to coordination only.
-```
-Then press `Shift+Tab` to cycle into delegate mode.
-
-### Issue: Task Not Marked Complete
-
-**Symptom:** Teammate finished work but task still shows "in_progress"
-
-**Solution:**
-```
-# Check if validation passed
-morph-spec state get {feature}
-
-# If validation failed, teammate must fix violations
-Tell the frontend teammate to check validation output and fix contract violations
-
-# If validation passed but task stuck, manually mark complete
-morph-spec task done {feature} {task-id}
-```
-
-### Issue: Orphaned tmux Sessions
-
-**Symptom:** `tmux ls` shows team sessions after cleanup
-
-**Solution:**
-```bash
-tmux kill-session -t scheduled-reports-team
-rm -rf ~/.claude/teams/scheduled-reports
-```
-
-### Issue: Permission Prompts Spam
-
-**Symptom:** Too many permission requests for teammates
-
-**Solution:** Pre-approve common operations in `settings.local.json`:
-```json
-{
-  "dangerouslySkipPermissions": {
-    "allowedPaths": [".morph/features/**"],
-    "allowedCommands": ["morph-spec task done", "morph-spec validate-*"]
-  }
-}
-```
-
----
-
-## Integration with MORPH Workflows
-
-### Full MORPH (9 phases) + Agent Teams
-
-| Phase | Team Usage |
-|-------|------------|
-| **0 PROPOSAL** | Single session (detect-agents) |
-| **1 SETUP** | Single session |
-| **1.5 UI/UX** | Optional: Spawn UI/UX designer teammate for mockup generation |
-| **2 DESIGN** | Optional: Spawn debate team for DECISION POINTS |
-| **3 CLARIFY** | Single session |
-| **4 PLAN** | Single session |
-| **5 TASKS** | Single session (generate tasks.json) |
-| **6 IMPLEMENT** | **Primary use case:** Spawn implementation team by module |
-| **7 SYNC** | Single session (lead synthesizes decisions.md) |
-
----
-
-## Limitations
-
-- **No session resumption:** `/resume` doesn't restore in-process teammates
-- **Task status can lag:** Manual nudge may be needed
-- **One team per session:** Clean up before starting new team
-- **No nested teams:** Teammates can't spawn their own teams
-- **Split panes require tmux/iTerm2:** Not available in VS Code terminal, Windows Terminal, Ghostty
-
----
-
-## Example: Full MORPH Workflow with Agent Team
-
-```bash
-# Phases 0-5: Single Claude session
-/morph-proposal scheduled-reports
-# ... proposal approved, design approved, tasks generated ...
-
-# Phase 6: Create agent team
-morph-spec state set scheduled-reports phase implement
-```
-
-```
-Create an agent team to implement scheduled-reports.
-
-Team structure based on tasks.json modules:
-- Backend teammate (T001-T005): .NET VSA endpoints, Hangfire jobs, repositories
-- Frontend teammate (T006-T010): Next.js pages, shadcn/ui components, CSS
-- Infra teammate (T011-T012): EasyPanel config + Neon database setup
-
-Require plan approval for each teammate.
-Use delegate mode so I only coordinate.
-```
-
-**Claude creates team, spawns 3 teammates, each works independently:**
-
-```bash
-# Backend teammate
-morph-spec task start scheduled-reports T001
-# ... implements ReportDefinition entity + VSA endpoint ...
-morph-spec task done scheduled-reports T001
-# Validation runs: contract-compliance
-# Task T001 completed
-
-# Frontend teammate (parallel)
-morph-spec task start scheduled-reports T006
-# ... implements report dashboard with shadcn/ui DataTable ...
-morph-spec task done scheduled-reports T006
-# Validation runs: css-validator, contrast-checker
-# Task T006 completed
-```
-
-**After all tasks complete, lead synthesizes:**
-```bash
-morph-spec generate recap scheduled-reports
-# Pulls data from state.json, validation results, contracts
-# Generates comprehensive recap.md
-
-morph-spec phase advance scheduled-reports
-# Validates implement phase -> advances -> shows next steps
-```
-
----
-
-## Summary
-
-**Agent Teams enable MORPH-SPEC to:**
-- Implement multi-module features in parallel (reduces calendar time)
-- Debate architecture decisions with multiple perspectives
-- Conduct thorough reviews across security/performance/standards
-
-**Use when:**
-- 3+ independent modules/components
-- Complex architecture decisions
-- Cross-stack coordination (backend + frontend + infra)
-
-**Avoid when:**
-- Single-module features
-- Sequential workflows
-- Same-file modifications needed
-
-**Key insight:** Agent Teams amplify MORPH-SPEC's strengths (structured workflows, spec-driven development, validation pipeline) by parallelizing implementation while maintaining quality gates and coordination.
-
----
-
-*MORPH-SPEC by Polymorphism Tech - Integrated with Claude Code Agent Teams*