@polymorphism-tech/morph-spec 4.11.1 → 4.13.0

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

@@ -1,256 +0,0 @@
----
-name: morph-phase-clarify
-description: MORPH-SPEC Phase 3 (Clarify). Iterative clarification loop driven by a satisfaction score (0-100). Generates targeted questions per round, always presents "End Clarify" as exit option, and stops when score >= 85 or user exits. Use after design approval to eliminate spec ambiguities before task breakdown begins.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
----
-
-# MORPH Clarify — Phase 3
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Eliminate spec ambiguities through an iterative question loop until the spec has sufficient quality to generate tasks.
-
-## Prerequisites
-
-- [ ] Phase 2 (Design) completed
-- [ ] `spec.md` approved by user
-- [ ] `contracts.cs` (or `contracts.ts`) defined
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
-> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Read spec + contracts | **Read** all design outputs | — |
-| Verify technical feasibility | **Context7 MCP** `query_docs()` | **WebSearch** |
-| Check external issues/limitations | **GitHub MCP** `search_issues()` | — |
-| Ask clarifying questions | **AskUserQuestion** (never plain text) | — |
-| Update spec with clarifications | **Edit** spec.md | — |
-| Create clarifications.md | **Write** | — |
-| Update state | **Bash** `morph-spec state mark-output $ARGUMENTS clarifications` | — |
-
----
-
-## Satisfaction Scoring System
-
-Before each round, calculate the **Satisfaction Score (0-100)** by evaluating the current spec:
-
-| Dimension | Pts | Maximum Score Criteria |
-|-----------|-----|----------------------|
-| **Functional completeness** | 25 | All requirements have measurable acceptance criteria (no vague "should", "may", "generally") |
-| **Failure coverage** | 20 | All error paths have defined behavior (invalid input, not found, timeout, unauthorized) |
-| **Edge cases** | 20 | Boundaries, concurrent states, empty/extreme inputs documented |
-| **Definitional clarity** | 20 | No critical term undefined, no "TBD", no "to be defined" |
-| **Integration contracts** | 15 | External dependencies have payload format, errors, and retry policy defined |
-
-**Thresholds:**
-
-| Score | Action |
-|-------|--------|
-| >= 85 | Satisfied. Present results and offer "End Clarify" as the primary option |
-| 70-84 | Continue. Focus questions on the lowest-scoring dimensions |
-| < 70 | Continue. Broad questions covering the largest gaps |
-
-> The score rises as answers are incorporated. There's no fixed maximum rounds — the loop ends when score >= 85 **or** the user chooses to end.
-
----
-
-## Workflow
-
-### Initialization
-
-**Step 0 (BEFORE any writing) — Ensure clarify phase:**
-
-```bash
-morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field in the output:
-
-**If `"phase": "clarify"`** → correct phase, proceed.
-
-**If `"phase": "design"`** → run in sequence:
-1. `morph-spec approve $ARGUMENTS design`
-2. `morph-spec phase advance $ARGUMENTS` (→ clarify)
-
-**Any other value** → STOP — inconsistent state, report to user.
-
-> **Rule:** Never write `clarifications.md` or update `spec.md` until the phase is `clarify`.
-
----
-
-Read the base files in PARALLEL:
-
-```
-Read: .morph/features/$ARGUMENTS/1-design/spec.md
-    + Read: .morph/features/$ARGUMENTS/1-design/contracts.cs  (or contracts.ts for TypeScript)
-    + Read: .morph/features/$ARGUMENTS/1-design/schema-analysis.md  (if exists)
-```
-
-Calculate the initial score. Track accumulated answers from prior rounds to avoid repeating already-answered questions.
-
-## MANDATORY: Session Tasks
-
-> **BEFORE starting clarification work**, analyze the spec quality and create session tasks.
->
-> **Rules:** Minimum 2 tasks, typically 2-4. Mark `in_progress` before starting, `completed` after.
-> For the clarification loop, update the task `subject` with round and score progress.
->
-> **Typical tasks:** initial score calculation, clarification rounds (iterative), output generation
-
----
-
-### Main Loop
-
-**Repeat until: score >= 85 OR user chooses to end.**
-
-#### A. Calculate Current Round Score
-
-Score each dimension based on the spec + accumulated answers. Note which dimensions are weakest — they guide this round's questions.
-
-#### B. Identify New Questions
-
-Analyze only what **hasn't been answered yet**. Categorize by dimension:
-
-| Category | Example Questions |
-|----------|-------------------|
-| **Validation** | Field limits, accepted formats, business rules |
-| **Behavior** | What happens when X fails? Empty state? Loading state? |
-| **Priority** | Must-have vs nice-to-have? MVP vs v2? |
-| **Integration** | Webhook vs polling? Retry policy? Timeout? |
-| **Performance** | Expected volume? Response SLA? |
-| **UX** | Error message shown to user? Visual feedback? |
-
-#### C. Present Questions via `AskUserQuestion`
-
-**Why this matters:** AskUserQuestion gives structured options the user can click — far better UX than walls of text. It also captures answers programmatically for the clarifications.md output.
-
-**Rules:**
-
-1. Use `AskUserQuestion` — **NEVER list questions as plain text**
-2. Maximum **4 questions per call** (tool limit)
-3. If there are more than 3 new questions, make sequential calls — the **exit option always appears in the last call of each round**
-4. **Always include the following question as the last in the final batch of each round:**
-
-```json
-{
-  "header": "End Clarify?",
-  "question": "End the Clarify phase now or continue refining the spec?",
-  "multiSelect": false,
-  "options": [
-    {
-      "label": "Continue refining",
-      "description": "There are still open questions identified in this round"
-    },
-    {
-      "label": "End Clarify",
-      "description": "Proceed to Plan phase with the spec in its current state"
-    }
-  ]
-}
-```
-
-> If score >= 85, adjust the first option label to: `"Continue (optional)"` with description: `"Score ${score}/100 — spec is satisfactory, but you can refine further"`
-
-#### D. Wait and Incorporate Answers
-
-**Do not proceed before receiving all responses.**
-
-After receiving answers:
-1. Check if the answer is consistent with `contracts.cs` and `schema-analysis.md`
-2. If any answer is ambiguous or contradictory → ask for clarification before updating
-3. Update `spec.md` with:
-   - Section `## Clarifications (Phase 3)` with structured Q&A
-   - Updates to affected functional sections
-   - New edge cases in `## Edge Cases`
-
-#### E. Check Exit Condition
-
-- User chose **"End Clarify"** → exit loop
-- Score >= 85 AND no new questions identified → exit loop
-- Otherwise → return to A
-
----
-
-### Post-Loop: Generate Outputs
-
-**Step 1: Create `clarifications.md`**
-
-Write to `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
-
-```markdown
-# Clarifications — {Feature Name}
-
-**Phase:** Clarify (Phase 3)
-**Rounds completed:** {N}
-**Final score:** {score}/100
-**Status:** Resolved — incorporated into spec.md
-
----
-
-## Questions & Answers
-
-### Q{N}: {Title}
-**Question:** {question}
-**Answer:** {user's answer}
-**Spec Updates:** {which sections were updated}
-**Priority:** High/Medium/Low
-**Resolved:** Yes
-
----
-
-## Edge Cases
-
-### EC{N}: {Name}
-**Scenario:** {when it happens}
-**Expected Behavior:** {how the system reacts}
-**Implementation Notes:** {tips}
-
----
-
-## Summary
-
-| | Count |
-|---|---|
-| Questions Answered | {N} |
-| Edge Cases Documented | {N} |
-| Spec Sections Updated | {N} |
-| Final Score | {score}/100 |
-```
-
-**Step 2: Update State**
-
-```bash
-morph-spec state mark-output $ARGUMENTS clarifications
-```
-
----
-
-## Phase Outputs
-
-<!-- morph-outputs:clarify -->
-| Output | Path |
-|--------|------|
-| `clarifications` | `.morph/features/{feature}/1-design/clarifications.md` |
-<!-- /morph-outputs -->
-
-## Advancement Criteria
-
-- [x] Satisfaction score >= 85 OR user opted to end
-- [x] All answers are consistent with `contracts.cs`
-- [x] `spec.md` updated with clarifications and edge cases
-- [x] `clarifications.md` created with Q&A and final score
-- [x] State updated (`mark-output clarifications`)
-
----
-
-```bash
-morph-spec phase advance $ARGUMENTS
-```
-
-Continue automatically to Phase 4 (Plan) after clarifications.md is generated.

package/framework/skills/level-1-workflows/morph-phase-clarify/references/clarifications-example.md

@@ -1,117 +0,0 @@
-# Clarifications - Photo Processing Pipeline
-
-> Example of a well-structured clarifications.md. Filled-in reference — not a template.
-> Each Q&A is concise: question raised during design review → answer → spec update.
-
-**Feature**: photo-processing
-**Phase**: CLARIFY (Phase 3)
-**Status**: Resolved — all items incorporated into spec.md
-
----
-
-## Questions & Answers
-
-### Q1: File size limit — 10MB for all users or tiered?
-
-**Question:** The spec says max 10MB but the proposal mentioned "higher for pro users." Should we implement tiered limits now?
-
-**Answer:** Free tier: 10MB. Pro tier: 50MB. Enforce via `[Authorize]` + claims check in the upload endpoint. YAGNI — don't build a generic tier system, just check the plan claim directly.
-
-**Spec Updates:**
-- Updated `spec.md` FR1 to specify tiered limits
-- Added `CanUploadLargeFile` policy to Security section
-- Updated `UploadPhotoCommand` to accept `userPlan` claim
-
-**Priority:** High — affects contracts
-**Resolved:** ✅ Yes
-
----
-
-### Q2: Processed photo retention — indefinite or expiring?
-
-**Question:** Should processed photos in Blob Storage be kept forever, or do they expire?
-
-**Answer:** Auto-delete after 30 days via Blob lifecycle policy (no code needed, configured in Azure). Free tier: 7 days. Pro tier: 30 days. This is infrastructure-only — `ProcessingJob.ProcessedPhotoUrl` stays in DB but becomes a dead link after expiry.
-
-**Spec Updates:**
-- Added ADR-003 (Blob lifecycle policy over code-based cleanup)
-- Added note to `AzureBlobStorageService` about lifecycle dependency
-
-**Priority:** Low — no code change
-**Resolved:** ✅ Yes
-
----
-
-### Q3: AI API — async webhook or polling?
-
-**Question:** spec.md assumed Hangfire polls job completion, but the AI vendor docs mention a webhook callback option.
-
-**Answer:** Use fire-and-forget HTTP call + Hangfire continuation (not webhook). The AI API's webhook requires a public URL we don't have in dev. Fire-and-forget is simpler and testable. If the vendor SLA changes, we can swap to webhook via `IPhotoProcessingJob` interface — no consumer changes needed.
-
-**Spec Updates:**
-- Clarified Processing Flow in spec.md to show fire-and-forget + await pattern
-- Added to Risks: "AI API webhook migration path if needed"
-
-**Priority:** High — affects job implementation
-**Resolved:** ✅ Yes
-
----
-
-## Edge Cases
-
-### EC1: Upload during Hangfire downtime
-
-**Scenario:** User uploads successfully but Hangfire server is stopped — job never executes.
-
-**Expected Behavior:** Job stays in `Pending` indefinitely. On next Hangfire server start, job auto-resumes (Hangfire persistent storage).
-
-**Solution:** No code change. Add monitoring alert if job stays Pending > 10 minutes.
-
-**Acceptance Criteria:**
-- [ ] `ProcessingJob` with status `Pending` survives Hangfire restart
-- [ ] Hangfire picks up orphaned jobs on startup (built-in behavior, covered by docs)
-
----
-
-### EC2: Concurrent uploads of same file
-
-**Scenario:** User double-clicks Upload button, sending two identical requests simultaneously.
-
-**Expected Behavior:** Two separate `ProcessingJob` records created. Both process independently. No deduplication (not required at MVP scale).
-
-**Solution:** No code change. Each request gets a fresh GUID. If deduplication becomes needed, add idempotency key header in v2.
-
----
-
-## Business Rules Clarified
-
-### BR1: Only the uploading user can download their processed photo
-
-**Rule:** `GET /api/download/{jobId}` must check `job.UserId == currentUserId`. Return 403 if mismatch.
-
-**Rationale:** Users might guess sequential GUIDs (they can't since we use random GUIDs, but defense in depth).
-
-**Implementation:** Add `[Authorize]` + ownership check to download endpoint. Already in Security section of spec.md.
-
----
-
-## Summary
-
-| | Count |
-|---|---|
-| Questions Answered | 3 / 3 |
-| Edge Cases Documented | 2 |
-| Business Rules Clarified | 1 |
-| Spec Updates Made | 6 |
-
-## Next Steps
-
-1. [x] All questions resolved
-2. [x] `spec.md` updated with all clarifications
-3. [x] `contracts.cs` updated (`UploadPhotoCommand` + plan claim)
-4. [x] Stakeholder approval received
-5. [ ] Advance to Phase 4 (Tasks)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

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

@@ -1,269 +0,0 @@
----
-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.11.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** `morph-spec state get` | — |
-| Detect agents + standards | **Bash** `morph-spec detect-agents $ARGUMENTS --json` → parse → **Bash** `morph-spec state add-agent` | **Read** agents.json manually |
-| 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** `morph-spec state set` | — |
-
-**MCPs for this phase:** GitHub (optional — repo metadata).
-
-**Anti-patterns:**
-- Do not read agents.json manually for keyword matching — use `morph-spec detect-agents` CLI
-- Do not use a Task agent for agent detection (CLI is faster and consistent)
-- 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).
-
----
-
-## MANDATORY: Session Tasks
-
-> **BEFORE starting any setup work**, analyze the steps below and create session tasks.
->
-> **Rules:** Minimum 2 tasks, typically 3-5. Mark `in_progress` before starting, `completed` after.
->
-> **Typical tasks:** agent detection, MCP validation, stack confirmation, state configuration
-
----
-
-### Step 1: Load Project Context
-
-Read these files first — they inform all subsequent decisions:
-
-```bash
-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"` | `morph-spec state add-agent $ARGUMENTS vsa-architect` |
-| absent / any other value | `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
-
-Use the `detect-agents` CLI to match agent keywords against the proposal (excludes architects already handled in Step 2.0):
-
-```bash
-morph-spec detect-agents $ARGUMENTS --exclude domain-architect,vsa-architect --json
-```
-
-This reads the proposal from `.morph/features/$ARGUMENTS/0-proposal/proposal.md` and agents.json, returning JSON with `detected[]` and `skipped[]` arrays. Agents with `active_phases: ['*']` are always included.
-
-Parse the JSON output and add each detected agent to state:
-
-```bash
-morph-spec state add-agent $ARGUMENTS {agent-id}
-```
-
-Run `add-agent` once per detected agent ID from the `detected[]` array.
-
-**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 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 2.9: Check for Missing Agents
-
-Run a quick check to verify all expected agents are installed for this project's stack:
-
-```bash
-morph-spec doctor 2>&1 | grep -A 1 "agents completeness"
-```
-
-If the output shows **missing agents**, inform the user:
-
-> ⚠ Some agents for your stack are not installed. Run `morph-spec setup-infra` to install them.
-
-Use `AskUserQuestion` with header `"Agents"` and options:
-- **Install now** — run `morph-spec setup-infra` to reinstall with current stack tags
-- **Continue without** — proceed with available agents (may lack specialized support)
-
-If "Install now" is selected, run the command and continue.
-
----
-
-### 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
-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
-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
-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
-
----
-
-## Worktree Note
-
-Worktree isolation is handled automatically by `/morph-proposal` Step 0 and `/morph-apply` Step 0.
-If a worktree is active, all file operations MUST use the worktree path (injected in session context as `WORKTREE_PATH`).
-
----
-
-Continue automatically to the next phase (UI/UX if ui-designer detected, otherwise Design).