@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: morph:phase-plan
+description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan with exact file paths, TDD code blocks, and execution strategy analysis. Produces plan.md in 3-plan/. Use after clarify phase to create an actionable implementation plan before task breakdown.
+argument-hint: "[feature-name]"
+disable-model-invocation: true
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.1"
+---
+
+# MORPH Plan — Phase 4
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Generate a detailed implementation plan with exact paths, TDD code, and execution strategy.
+
+## Prerequisites
+
+- [ ] Phase 3 (Clarify) completed
+- [ ] `spec.md` updated with clarifications
+- [ ] `contracts.cs` or `contracts.ts` defined
+
+## Recommended Tools
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Read spec + contracts + decisions | **Read** all outputs | — |
+| Analyze existing codebase | **Glob** + **Grep** patterns | — |
+| Look up library docs | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Dispatch agents for analysis | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS plan` | — |
+| Update state | **Bash** `npx morph-spec state mark-output $ARGUMENTS plan` | — |
+
+**Anti-patterns:**
+- Generating plan without reading contracts (contracts are the source of truth!)
+- Generic paths ("add the file") — always use exact paths
+- Incomplete code in plan ("add validation") — always include complete code
+- Skipping existing codebase analysis (existing patterns guide the plan)
+- Ignoring `config.architecture.style` — VSA and DDD have different structures
+
+---
+
+## Pre-flight
+
+### 0. Ensure plan phase
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Check the `"phase"` field:
+- `"phase": "plan"` → correct phase, proceed
+- any other value → run `npx morph-spec phase advance $ARGUMENTS` and re-check
+
+> **Rule:** Never write to `3-plan/` until the phase is `plan`.
+
+### 1. Read all prerequisites in PARALLEL
+
+```
+Read: .morph/features/{feature}/1-design/spec.md
+    + Read: .morph/features/{feature}/1-design/contracts.cs  (or contracts.ts)
+    + Read: .morph/features/{feature}/1-design/decisions.md
+    + Read: .morph/features/{feature}/1-design/clarifications.md
+    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (if exists)
+    + Read: .morph/config/config.json
+```
+
+---
+
+## Workflow
+
+### Step 1: Analyze Feature for Context
+
+1. **Scan existing codebase** — Glob to find files that will be modified/created
+2. **Identify patterns** — Grep for patterns similar to what will be implemented
+3. **Check library docs** — Context7 for dependency documentation
+4. **Detect architecture:**
+
+```bash
+cat .morph/config/config.json | grep -A3 '"architecture"'
+```
+
+| `config.architecture.style` value | Path structure |
+|------------------------------------|---------------|
+| `"vertical-slice"` | VSA: `Features/{Entity}Feature/{Operation}/` |
+| any other value | DDD by layer |
+
+### Step 2: Determine Execution Strategy
+
+Run the dispatch analysis:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS plan
+```
+
+**Factors for recommendation:**
+
+| Factor | Calculation |
+|--------|-------------|
+| `taskCount` | Number of functional requirements + technical components in spec |
+| `domainCount` | Distinct domains in activeAgents (backend, frontend, infra) |
+| `agentCount` | Total activeAgents |
+| `independence` | % of tasks without cross-domain dependencies |
+
+**Decision:**
+
+| Scenario | Recommendation |
+|----------|----------------|
+| `taskCount < 8` AND `domainCount <= 2` | **Single session** — direct sequential implementation |
+| `taskCount 8-20` AND `domainCount 2-3` | **Subagent-Driven** — one subagent per task group |
+| `taskCount > 20` OR `domainCount > 3` | **Agent Teams** — multi-domain coordination |
+
+### Step 3: Generate `plan.md`
+
+Create `.morph/features/$ARGUMENTS/3-plan/plan.md` with this structure:
+
+```markdown
+# {Feature Name} Implementation Plan
+
+> **For Claude:** Use morph:phase-implement to execute this plan.
+
+**Goal:** {One sentence describing what will be built}
+
+**Architecture:** {2-3 sentences about the approach}
+
+**Tech Stack:** {Key technologies}
+
+**Execution Strategy:** {single | subagents | agent-teams} (Recommended)
+
+---
+
+## GROUP {A} — {Group Name}
+
+{Pattern and context for the group}
+
+### {A1} — {Task Name}
+
+**Files:**
+- Create: `exact/path/to/file.cs`
+- Modify: `exact/path/to/existing.cs:123-145`
+- Test: `tests/exact/path/to/test.cs`
+
+**Step 1: Write the failing test**
+
+(Complete test code)
+
+**Step 2: Run test to verify it fails**
+
+Run: `{exact command}`
+Expected: FAIL with "{message}"
+
+**Step 3: Write minimal implementation**
+
+(Complete implementation code)
+
+**Step 4: Run test to verify it passes**
+
+Run: `{exact command}`
+Expected: PASS
+
+**Step 5: Commit**
+
+git add {files}
+git commit -m "{message}"
+```
+
+**Mandatory rules:**
+- Exact paths ALWAYS (never "add the file somewhere")
+- COMPLETE code in each step (never "add validation later" or "implement here")
+- Exact test commands with expected output (pass/fail message)
+- Each task follows the TDD 5-step cycle above — this is what makes the plan actionable
+- Keep each step to a 2-5 minute action
+
+### Step 4: Update State
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS plan
+```
+
+---
+
+## Mandatory Approval Pause
+
+Use `AskUserQuestion` to capture approval before advancing. This gate prevents task breakdown from starting with an unapproved plan.
+
+```json
+{
+  "questions": [
+    {
+      "header": "Approval",
+      "question": "Implementation plan generated. Approve to start task breakdown?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Approve plan", "description": "Advance to task breakdown phase" },
+        { "label": "I have feedback", "description": "Type what you want to change" }
+      ]
+    },
+    {
+      "header": "Execution",
+      "question": "Which execution strategy for implementation?",
+      "multiSelect": false,
+      "options": [
+        { "label": "{Recommendation} (Recommended)", "description": "{Justification from Step 2 analysis}" },
+        { "label": "{Alternative 1}", "description": "{Description}" },
+        { "label": "{Alternative 2}", "description": "{Description}" }
+      ]
+    }
+  ]
+}
+```
+
+> The first "Execution" option should be the context-aware recommendation from Step 2. Alternatives are the other strategies.
+
+- **"Approve plan"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS plan
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
+
+---
+
+## Phase Outputs
+
+<!-- morph:outputs:plan -->
+| Output | Path |
+|--------|------|
+| `plan` | `.morph/features/{feature}/3-plan/plan.md` |
+<!-- /morph:outputs -->
+
+---
+
+## Advancement Criteria
+
+- [x] `plan.md` created with all groups and tasks
+- [x] Exact paths for all files
+- [x] Complete code in each step
+- [x] Test commands with expected output
+- [x] Execution strategy defined and approved
+- [x] State updated (`mark-output plan`)
+- [x] User approved plan via `AskUserQuestion`
+
+---
+
+After approval: proceed automatically to Phase 5 (Tasks).

package/framework/skills/level-1-workflows/morph-phase-setup/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: morph:phase-setup
+description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents by reading agents.json, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.1"
+---
+
+# MORPH Setup — Phase 1
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Initialize the context and prepare the environment for an approved feature.
+
+## Prerequisites
+
+- [ ] Feature has `proposal.md` created (Phase 0 complete)
+- [ ] Proposal was approved by the user
+- [ ] Agents were detected and registered in state
+
+## Recommended Tools
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Verify state | **Bash** `npx morph-spec state get` | — |
+| Detect agents + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | — |
+| Read project context | **Read** `.morph/context/README.md` | — |
+| Read config | **Read** `.morph/config/config.json` | — |
+| Detect VSA architecture | **Read** `.morph/config/config.json` → check `config.architecture.style` | — |
+| Scan project structure | **Glob** `src/**/*.{ts,tsx,cs}` | — |
+| Repository metadata | **GitHub MCP** `get_repo()` | **Bash** `gh repo view --json` |
+| Update state | **Bash** `npx morph-spec state set` | — |
+
+**MCPs for this phase:** GitHub (optional — repo metadata).
+
+**Anti-patterns:**
+- Do not call a `detect-agents` CLI command (it doesn't exist — read `.morph/framework/agents.json` directly)
+- Do not use a Task agent for inline keyword matching (fast enough to do directly)
+- Do not use WebSearch for local project info (use Read/Glob)
+
+---
+
+## Workflow
+
+### ENTRY CHECKPOINT: Verify Prerequisites
+
+Before proceeding with setup:
+
+- [ ] Does `proposal.md` exist in `.morph/features/$ARGUMENTS/0-proposal/`?
+- [ ] Was the proposal presented and approved by the user?
+- [ ] Is the feature registered in state?
+
+If any checkbox is NOT checked → go back to Phase 0 (Proposal).
+
+---
+
+### Step 1: Load Project Context
+
+Read these files first — they inform all subsequent decisions:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+If the feature doesn't exist in state, go back to Phase 0.
+
+Then read:
+- `.morph/context/README.md` — project overview, tech stack, architecture
+- `.morph/config/config.json` — project configuration
+
+### Step 2: Detect Agents and Load Standards
+
+#### Step 2.0: Detect Architecture Style and Activate Architect
+
+Read `.morph/config/config.json` and check `config.architecture.style`:
+
+| Value | Action |
+|-------|--------|
+| `"vertical-slice"` | `npx morph-spec state add-agent $ARGUMENTS vsa-architect` |
+| absent / any other value | `npx morph-spec state add-agent $ARGUMENTS domain-architect` |
+
+Proceed with normal keyword detection for all other agents. The architect was already added above — skip it during keyword matching to avoid duplication.
+
+#### Step 2.1: Keyword Detection
+
+Read agents.json and match keywords (except `domain-architect` and `vsa-architect` which were handled in Step 2.0):
+
+1. Read `.morph/framework/agents.json` (or `framework/agents.json` in the framework project itself)
+2. Extract the feature title and description from `0-proposal/proposal.md`
+3. For each agent in the JSON (except architects), check if any keyword from the `keywords[]` field appears in the proposal text
+4. Include all agents with `always_active: true` automatically
+5. Add matched agents to state:
+
+```bash
+npx morph-spec state add-agent $ARGUMENTS {agent-id}
+```
+
+**To load standards for detected agents:**
+- For each active agent, read the standards referenced by the `standards[]` field in `agents.json`
+- Standard files are located at `.morph/framework/standards/{path}`
+
+**Standards resolution order:**
+1. `.morph/context/*.md` — project overrides (highest priority)
+2. `.morph/framework/standards/` — standards installed by morph-spec
+3. `framework/standards/` — npm package standards (fallback)
+
+### Step 2.5: Validate MCP Connections
+
+Check that configured MCPs are working before proceeding.
+
+**1. Collect recommended MCPs:**
+- Read `framework/phases.json` → for each phase in the feature's workflow, collect `recommendedMCPs[]`
+- Read `framework/skills/level-0-meta/mcp-registry.json` → get `healthCheck` for each MCP
+
+**2. Identify configured MCPs:**
+- Read `.claude/settings.local.json` → identify which MCPs are in `mcpServers`
+
+**3. For each MCP that is CONFIGURED AND RECOMMENDED:**
+1. Search your available tools for one containing `healthCheck.toolPattern` in the name
+2. If the tool exists → execute the `healthCheck.testCall` with `healthCheck.testParams`
+3. Evaluate the result:
+
+| Result | Action |
+|--------|--------|
+| **Success** | `✓ {MCP} — connection verified` |
+| **Tool not found** | `○ {MCP} — needs restart to activate` |
+| **Error** | → Use `AskUserQuestion` with 3 options (below) |
+
+**On error — ask the user:**
+
+Use `AskUserQuestion` with header `"{MCP}"` and options:
+- **Continue without {MCP}** — show the `fallback` field from the registry and proceed
+- **Reconfigure credentials** — collect new credentials and update `.claude/settings.local.json`
+- **Stop setup** — abort and report what needs to be fixed
+
+**4. For MCPs RECOMMENDED but NOT CONFIGURED:**
+- Print `△ {MCP} — not configured (fallback: {registry.fallback})`
+- Suggestion: `Tip: configure with /morph:init refresh or npx morph-spec mcp setup`
+
+**Summary:** Show a status table for each MCP before proceeding:
+```
+MCP Readiness:
+  ✓ context7 — connection verified
+  ○ playwright — needs restart
+  △ supabase — not configured (fallback: Grep + Read for schema)
+```
+
+---
+
+### Step 3: Confirm Stack
+
+Based on the proposal and context, confirm:
+- Tech stack (Blazor Server, Next.js, .NET API, Node.js CLI, etc.)
+- Applicable architectural patterns
+- Existing reusable components
+
+### Step 4: List Active Agents and Dispatch Preview
+
+Show the agents detected from the proposal:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Parse the JSON and list `activeAgents` with their emojis/icons and responsibilities (look up each agent in `.morph/framework/agents.json` for the `icon` field).
+
+**If there are 2+ specialist agents active**, show the dispatch plan for the next phase:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+This shows which agents will be dispatched in parallel during the design phase and which tasks they'll execute.
+
+> **Important mapping:** `agents[].id` from the dispatch config = `subagent_type` in the `Agent` tool.
+> Example: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert, prompt=agent.taskPrompt)`.
+> Each `id` corresponds to the `name:` field in the frontmatter of the file in `.claude/agents/`.
+
+### Step 5: Update State and Determine Next Phase
+
+Update the feature state:
+
+```bash
+npx morph-spec state set $ARGUMENTS status in_progress
+```
+
+**Determine the next phase** based on active agents:
+
+| Condition | Next Phase |
+|-----------|------------|
+| `ui-designer` is in activeAgents | **uiux** (UI/UX phase) |
+| `ui-designer` is NOT in activeAgents | **design** (skip uiux) |
+
+Announce the next phase clearly to the user.
+
+## Outputs
+
+Present to the user:
+
+1. **Context loaded**:
+   - Project name
+   - Confirmed stack
+   - Applicable standards
+
+2. **Active agents**:
+   - Agent list with emojis/icons and tier
+   - Responsibilities of each agent
+
+3. **Next phase**:
+   - Which phase comes next (uiux or design)
+   - Why (ui-designer presence or absence)
+
+## Advancement Criteria
+
+- [x] Project context loaded
+- [x] Standards identified (framework + project)
+- [x] Stack confirmed
+- [x] Agents listed with icons
+- [x] State updated to in_progress
+- [x] Next phase determined
+
+---
+
+## Superpowers Integration
+
+> Available when the `superpowers` plugin is installed.
+
+| Skill | When to Use | Invocation |
+|-------|-------------|-----------|
+| `using-git-worktrees` | If the feature requires workspace isolation | `Skill(superpowers:using-git-worktrees)` |
+
+---
+
+Continue automatically to the next phase (UI/UX if ui-designer detected, otherwise Design).

package/framework/skills/level-1-workflows/morph-phase-tasks/.morph/logs/activity.json

@@ -0,0 +1,14 @@
+{
+  "sessionId": "",
+  "feature": "",
+  "phase": "",
+  "hooks": [
+    {
+      "name": "set-terminal-title",
+      "event": "UserPromptSubmit",
+      "result": "failed",
+      "ts": "16:38:44"
+    }
+  ],
+  "skills": []
+}