@zenuml/core 3.47.9 → 3.48.1

package/.agents/skills/ship-branch/SKILL.md

@@ -1,105 +0,0 @@
----
-name: ship-branch
-description: Ship the current branch from local validation through to npm release. Orchestrates validate-branch, submit-branch, babysit-pr, and land-pr in sequence. Use when the user says "ship", "ship it", "ship this branch", "ship to production", "release this", "get this to npm", or wants to go from local branch to published npm package in one command. Stops at the first failure with a clear report.
----
-
-# Ship Branch
-
-Orchestrate the full path from local branch to npm release. This skill composes four sub-skills in sequence, stopping at the first failure.
-
-## Flow
-
-```
-rebase on origin/main → CONFLICT → stop, report
-     | CLEAN
-validate-branch → FAIL → stop, report
-     | PASS
-submit-branch → FAIL → stop, report
-     | PR ready
-babysit-pr → EXHAUSTED → stop, "CI blocked"
-     | GREEN
-land-pr → BLOCKED → stop, report
-     | MERGED
-land-pr → PUBLISH FAIL → alert, stop
-     | PUBLISHED
-     done
-```
-
-## Steps
-
-### Step 0: Rebase on remote main
-
-Fetch and rebase onto `origin/main` to ensure the branch is up to date before validating.
-
-```bash
-git fetch origin main
-git rebase origin/main
-```
-
-If the rebase has conflicts, stop immediately and report. The developer must resolve conflicts manually before shipping.
-
-### Step 1: Validate locally
-
-Invoke `/validate-branch`. If it reports FAIL, stop and show the failure. The developer needs to fix locally before shipping.
-
-### Step 2: Submit as PR
-
-Invoke `/submit-branch`. If it reports FAILED, stop and show what went wrong (dirty worktree, push conflict, etc.).
-
-On success, note the PR number and URL.
-
-### Step 3: Get CI green
-
-Invoke `/babysit-pr` with the PR number from Step 2. If it exhausts all 3 retry attempts, stop and report "CI blocked" with the babysit report.
-
-On success, the PR is green and ready to merge.
-
-### Step 4: Land and verify release
-
-Merging to main triggers an npm publish — this is irreversible. To prevent the orchestrator from skipping the land-pr skill's merge strategy logic (which has happened before), **spawn an Agent** for this step:
-
-```
-Spawn an Agent with this prompt:
-"Use the Skill tool to invoke the land-pr skill, then follow it to land PR #<PR_NUMBER>
-on mermaid-js/zenuml-core. Follow every step including the merge strategy evaluation.
-Report back the merge SHA and npm version, or the reason it was blocked."
-```
-
-Replace `<PR_NUMBER>` with the actual PR number from Step 2.
-
-Do NOT run `gh pr merge` directly from the main conversation — the land-pr skill contains merge strategy decision logic that must be evaluated by the Agent.
-
-If merge succeeds but npm publish fails, alert immediately with the failure details. Do NOT auto-rollback.
-
-On full success, report the new npm version.
-
-## Rules
-
-- **Each step is a hard boundary.** No step reaches back to retry a previous step.
-- **No auto-rollback.** Stop and report on any failure. The developer decides next steps.
-- **Only this skill calls babysit-pr.** Sub-skills never cross-call each other.
-- **Confirm before merge.** Since merge = npm release, pause and confirm with the user before Step 4 unless they explicitly said "ship it" (indicating full automation is intended).
-
-## Output
-
-Final report:
-
-```
-## Ship Report: <branch-name>
-- Validation: PASS
-- PR: #<number> (<url>)
-- CI: GREEN (attempt <N>)
-- Merge: <SQUASHED|MERGED> into main (<sha>)
-- npm: @zenuml/core@<version> published
-```
-
-Or on failure:
-
-```
-## Ship Report: <branch-name>
-- Validation: PASS
-- PR: #<number>
-- CI: BLOCKED after 3 attempts
-- Stopped at: babysit-pr
-- Details: <failure summary>
-```

package/.agents/skills/submit-branch/SKILL.md

@@ -1,76 +0,0 @@
----
-name: submit-branch
-description: Push the current branch and create or reuse a PR on mermaid-js/zenuml-core. Use when the user says "submit", "create PR", "push and PR", "open a pull request", "submit branch", or wants to publish their work as a PR without merging. Does not fix CI or merge — those are separate skills.
----
-
-# Submit Branch
-
-Publish the current branch as a pull request on `mermaid-js/zenuml-core`. Reuses an existing PR if one already exists for this branch.
-
-## Preconditions
-
-The worktree must be in a committable state:
-
-- **Clean worktree** — nothing to commit, just push. This is the ideal case.
-- **Scoped changes** — all modified files relate to the current work. Stage and commit them.
-- **Mixed/unrelated changes** — modified files include unrelated work. **Stop and ask the user** which files to include. Never auto-commit a mixed worktree.
-
-To check: `git status` and review the file list. If in doubt, ask.
-
-## Steps
-
-### 1. Check worktree state
-
-```bash
-git status
-```
-
-If dirty, evaluate whether changes are scoped (all related to the branch's purpose) or mixed. If mixed, stop and ask.
-
-If scoped, stage the relevant files and commit with a descriptive message. Follow the repo's commit conventions (one-line message, Co-Authored-By trailer).
-
-### 2. Push
-
-```bash
-git push -u origin <branch-name>
-```
-
-Use regular push — never force-push. If push fails due to upstream changes, report the conflict and stop.
-
-### 3. Create or reuse PR
-
-Check if a PR already exists:
-
-```bash
-gh pr view --json number,title,url 2>/dev/null
-```
-
-If a PR exists, report its URL and stop — nothing more to do.
-
-If no PR exists, create one:
-
-```bash
-gh pr create --title "<concise title>" --body "$(cat <<'EOF'
-## Summary
-<bullet points>
-
-## Test plan
-<what was tested>
-EOF
-)"
-```
-
-The PR targets `main` on `mermaid-js/zenuml-core`.
-
-## Output
-
-Report:
-
-- **SUBMITTED** — PR number, URL, and branch name
-- **FAILED** — what went wrong (dirty worktree, push conflict, gh error)
-
-## Does NOT
-
-- Run tests or lint (use `/validate-branch` for that)
-- Fix CI failures (use `/babysit-pr` for that)
-- Merge the PR (use `/land-pr` for that)

package/.agents/skills/validate-branch/SKILL.md

@@ -1,72 +0,0 @@
----
-name: validate-branch
-description: Run local validation checks on the current branch before shipping. Use when the user says "validate", "check branch", "am I good", "run tests", "preflight", "is this ready", or wants to verify their branch passes all checks before pushing or creating a PR. Also use as a precondition check before invoking submit-branch or ship-branch.
----
-
-# Validate Branch
-
-Verify the current branch passes all local checks. This is the "am I good?" skill — run it anytime before shipping, or just to check your work.
-
-## Why this order matters
-
-Checks run fastest-first so you get feedback quickly. Lint catches syntax issues in seconds. Unit tests catch logic errors in a few seconds. Playwright E2E is slowest (~1-2 min) and catches integration regressions. No point waiting for E2E if lint fails.
-
-## Steps
-
-Run from the `zenuml-core` directory. Stop on first failure.
-
-### 1. Lint
-
-```bash
-bun eslint
-```
-
-If lint fails, report the errors and stop. These are usually quick fixes.
-
-### 2. Unit tests
-
-```bash
-bun run test
-```
-
-Do NOT use `bun test` — it picks up Playwright files and gives false failures. If tests fail, report the failing test names and stop.
-
-### 3. Playwright E2E
-
-Before running Playwright, make sure port `8080` is either free or owned by a dev server started from **this repo**. `playwright.config.ts` uses `reuseExistingServer`, so an unrelated Vite server on `8080` will cause false results.
-
-```bash
-PORT="${PORT:-8080}"
-THIS_REPO="$(pwd -P)"
-LISTENER_PID="$(lsof -tiTCP:${PORT} -sTCP:LISTEN 2>/dev/null | head -n1 || true)"
-
-if [ -n "$LISTENER_PID" ]; then
-  LISTENER_CMD="$(ps -p "$LISTENER_PID" -o command=)"
-  if [[ "$LISTENER_CMD" != *"$THIS_REPO"* ]]; then
-    echo "Port ${PORT} is owned by another repo; killing PID ${LISTENER_PID}"
-    kill "$LISTENER_PID"
-  fi
-fi
-```
-
-If you killed a different repo's server, do **not** start Vite manually. `bun pw` will launch the correct dev server from this folder via Playwright's `webServer` config.
-
-```bash
-bun pw
-```
-
-If snapshot tests fail, check whether the changes are intentional (rendering code changed) or unexpected. Report which snapshots failed.
-
-## Output
-
-Report one of:
-
-- **PASS** — all 3 checks passed, branch is ready
-- **FAIL** — which check failed, the error output, and a one-line suggestion
-
-## Gotchas
-
-- `bun run test` not `bun test` — critical difference, the latter runs E2E too
-- Playwright needs browsers installed (`bun pw:install` if missing)
-- Before `bun pw`, verify any existing `8080` listener belongs to this repo; otherwise kill it and let Playwright start the right server
-- HTML Playwright snapshot failures are a hard stop — never update HTML snapshots without understanding why they changed

package/.claude/commands/README.md

@@ -1,162 +0,0 @@
-# 🔧 Command Templates
-
-Orchestration templates that enable Claude Code to coordinate multi-agent workflows for different development tasks.
-
-## Overview
-
-After reading the [main kit documentation](../README.md), you'll understand how these commands fit into the integrated system. Each command:
-
-- **Auto-loads** the appropriate documentation tier for its task
-- **Spawns specialized agents** based on complexity 
-- **Integrates MCP servers** when external expertise helps
-- **Maintains documentation** to keep AI context current
-
-### 🚀 Automatic Context Injection
-
-All commands benefit from automatic context injection via the `subagent-context-injector.sh` hook:
-
-- **Core documentation auto-loaded**: Every command and sub-agent automatically receives `@/docs/CLAUDE.md`, `@/docs/ai-context/project-structure.md`, and `@/docs/ai-context/docs-overview.md`
-- **No manual context loading**: Sub-agents spawned by commands automatically have access to essential project documentation
-- **Consistent knowledge**: All agents start with the same foundational understanding
-
-## Available Commands
-
-### 📊 `/full-context`
-**Purpose**: Comprehensive context gathering and analysis when you need deep understanding or plan to execute code changes.
-
-**When to use**:
-- Starting work on a new feature or bug
-- Need to understand how systems interconnect
-- Planning architectural changes
-- Any task requiring thorough analysis before implementation
-
-**How it works**: Adaptively scales from direct analysis to multi-agent orchestration based on request complexity. Agents read documentation, analyze code, map dependencies, and consult MCP servers as needed.
-
-### 🔍 `/code-review` 
-**Purpose**: Get multiple expert perspectives on code quality, focusing on high-impact findings rather than nitpicks.
-
-**When to use**:
-- After implementing new features
-- Before merging important changes
-- When you want security, performance, and architecture insights
-- Need confidence in code quality
-
-**How it works**: Spawns specialized agents (security, performance, architecture) that analyze in parallel. Each agent focuses on critical issues that matter for production code.
-
-### 🧠 `/gemini-consult` *(Requires Gemini MCP Server)*
-**Purpose**: Engage in deep, iterative conversations with Gemini for complex problem-solving and architectural guidance.
-
-**When to use**:
-- Tackling complex architectural decisions
-- Need expert guidance on implementation approaches
-- Debugging intricate issues across multiple files
-- Exploring optimization strategies
-- When you need a thinking partner for difficult problems
-
-**How it works**: Creates persistent conversation sessions with Gemini, automatically attaching project context and MCP-ASSISTANT-RULES.md. Supports iterative refinement through follow-up questions and implementation feedback.
-
-**Key features**:
-- Context-aware problem detection when no arguments provided
-- Persistent sessions maintained throughout problem lifecycle
-- Automatic attachment of foundational project documentation
-- Support for follow-up questions with session continuity
-
-### 📝 `/update-docs`
-**Purpose**: Keep documentation synchronized with code changes, ensuring AI context remains current.
-
-**When to use**:
-- After modifying code
-- After adding new features
-- When project structure changes
-- Following any significant implementation
-
-**How it works**: Analyzes what changed and updates the appropriate CLAUDE.md files across all tiers. Maintains the context that future AI sessions will rely on.
-
-### 📄 `/create-docs`
-**Purpose**: Generate initial documentation structure for existing projects that lack AI-optimized documentation.
-
-**When to use**:
-- Adopting the framework in an existing project
-- Starting documentation from scratch
-- Need to document legacy code
-- Setting up the 3-tier structure
-
-**How it works**: Analyzes your project structure and creates appropriate CLAUDE.md files at each tier, establishing the foundation for AI-assisted development.
-
-### ♻️ `/refactor`
-**Purpose**: Intelligently restructure code while maintaining functionality and updating all dependencies.
-
-**When to use**:
-- Breaking up large files
-- Improving code organization
-- Extracting reusable components
-- Cleaning up technical debt
-
-**How it works**: Analyzes file structure, maps dependencies, identifies logical split points, and handles all import/export updates across the codebase.
-
-### 🤝 `/handoff`
-**Purpose**: Preserve context when ending a session or when the conversation becomes too long.
-
-**When to use**:
-- Ending a work session
-- Context limit approaching
-- Switching between major tasks
-- Supplementing `/compact` with permanent storage
-
-**How it works**: Updates the handoff documentation with session achievements, current state, and next steps. Ensures smooth continuation in future sessions.
-
-## Integration Patterns
-
-### Typical Workflow
-```bash
-/full-context "implement user notifications"    # Understand
-# ... implement the feature ...
-/code-review "review notification system"       # Validate  
-/update-docs "document notification feature"    # Synchronize
-/handoff "completed notification system"        # Preserve
-```
-
-### Quick Analysis
-```bash
-/full-context "why is the API slow?"           # Investigate
-# ... apply fixes ...
-/update-docs "document performance fixes"       # Update context
-```
-
-### Major Refactoring
-```bash
-/full-context "analyze authentication module"   # Understand current state
-/refactor "@auth/large-auth-file.ts"          # Restructure
-/code-review "review refactored auth"          # Verify quality
-/update-docs "document new auth structure"     # Keep docs current
-```
-
-### Complex Problem Solving
-```bash
-/gemini-consult "optimize real-time data pipeline" # Start consultation
-# ... implement suggested approach ...
-/gemini-consult                                    # Follow up with results
-/update-docs "document optimization approach"      # Capture insights
-```
-
-## Customization
-
-Each command template can be adapted:
-
-- **Adjust agent strategies** - Modify how many agents spawn and their specializations
-- **Change context loading** - Customize which documentation tiers load
-- **Tune MCP integration** - Adjust when to consult external services
-- **Modify output formats** - Tailor results to your preferences
-
-Commands are stored in `.claude/commands/` and can be edited directly.
-
-## Key Principles
-
-1. **Commands work together** - Each command builds on others' outputs
-2. **Documentation stays current** - Commands maintain their own context
-3. **Complexity scales naturally** - Simple tasks stay simple, complex tasks get sophisticated analysis
-4. **Context is continuous** - Information flows between sessions through documentation
-
----
-
-*For detailed implementation of each command, see the individual command files in this directory.*

package/.claude/commands/analyze.md

@@ -1,101 +0,0 @@
----
-description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
----
-
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
-
-User input:
-
-$ARGUMENTS
-
-Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
-
-STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
-
-Constitution Authority: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
-
-Execution steps:
-
-1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
-   - SPEC = FEATURE_DIR/spec.md
-   - PLAN = FEATURE_DIR/plan.md
-   - TASKS = FEATURE_DIR/tasks.md
-   Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
-
-2. Load artifacts:
-   - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).
-   - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
-   - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.
-   - Load constitution `.specify/memory/constitution.md` for principle validation.
-
-3. Build internal semantic models:
-   - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).
-   - User story/action inventory.
-   - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).
-   - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.
-
-4. Detection passes:
-   A. Duplication detection:
-      - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation.
-   B. Ambiguity detection:
-      - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria.
-      - Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.).
-   C. Underspecification:
-      - Requirements with verbs but missing object or measurable outcome.
-      - User stories missing acceptance criteria alignment.
-      - Tasks referencing files or components not defined in spec/plan.
-   D. Constitution alignment:
-      - Any requirement or plan element conflicting with a MUST principle.
-      - Missing mandated sections or quality gates from constitution.
-   E. Coverage gaps:
-      - Requirements with zero associated tasks.
-      - Tasks with no mapped requirement/story.
-      - Non-functional requirements not reflected in tasks (e.g., performance, security).
-   F. Inconsistency:
-      - Terminology drift (same concept named differently across files).
-      - Data entities referenced in plan but absent in spec (or vice versa).
-      - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note).
-      - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).
-
-5. Severity assignment heuristic:
-   - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality.
-   - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion.
-   - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case.
-   - LOW: Style/wording improvements, minor redundancy not affecting execution order.
-
-6. Produce a Markdown report (no file writes) with sections:
-
-   ### Specification Analysis Report
-   | ID | Category | Severity | Location(s) | Summary | Recommendation |
-   |----|----------|----------|-------------|---------|----------------|
-   | A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
-   (Add one row per finding; generate stable IDs prefixed by category initial.)
-
-   Additional subsections:
-   - Coverage Summary Table:
-     | Requirement Key | Has Task? | Task IDs | Notes |
-   - Constitution Alignment Issues (if any)
-   - Unmapped Tasks (if any)
-   - Metrics:
-     * Total Requirements
-     * Total Tasks
-     * Coverage % (requirements with >=1 task)
-     * Ambiguity Count
-     * Duplication Count
-     * Critical Issues Count
-
-7. At end of report, output a concise Next Actions block:
-   - If CRITICAL issues exist: Recommend resolving before `/implement`.
-   - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions.
-   - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'".
-
-8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
-
-Behavior rules:
-- NEVER modify files.
-- NEVER hallucinate missing sections—if absent, report them.
-- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.
-- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.
-- If zero issues found, emit a success report with coverage statistics and proceed recommendation.
-
-Context: $ARGUMENTS

package/.claude/commands/clarify.md

@@ -1,158 +0,0 @@
----
-description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
----
-
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
-
-User input:
-
-$ARGUMENTS
-
-Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
-
-Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
-
-Execution steps:
-
-1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
-   - `FEATURE_DIR`
-   - `FEATURE_SPEC`
-   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
-   - If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment.
-
-2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
-
-   Functional Scope & Behavior:
-   - Core user goals & success criteria
-   - Explicit out-of-scope declarations
-   - User roles / personas differentiation
-
-   Domain & Data Model:
-   - Entities, attributes, relationships
-   - Identity & uniqueness rules
-   - Lifecycle/state transitions
-   - Data volume / scale assumptions
-
-   Interaction & UX Flow:
-   - Critical user journeys / sequences
-   - Error/empty/loading states
-   - Accessibility or localization notes
-
-   Non-Functional Quality Attributes:
-   - Performance (latency, throughput targets)
-   - Scalability (horizontal/vertical, limits)
-   - Reliability & availability (uptime, recovery expectations)
-   - Observability (logging, metrics, tracing signals)
-   - Security & privacy (authN/Z, data protection, threat assumptions)
-   - Compliance / regulatory constraints (if any)
-
-   Integration & External Dependencies:
-   - External services/APIs and failure modes
-   - Data import/export formats
-   - Protocol/versioning assumptions
-
-   Edge Cases & Failure Handling:
-   - Negative scenarios
-   - Rate limiting / throttling
-   - Conflict resolution (e.g., concurrent edits)
-
-   Constraints & Tradeoffs:
-   - Technical constraints (language, storage, hosting)
-   - Explicit tradeoffs or rejected alternatives
-
-   Terminology & Consistency:
-   - Canonical glossary terms
-   - Avoided synonyms / deprecated terms
-
-   Completion Signals:
-   - Acceptance criteria testability
-   - Measurable Definition of Done style indicators
-
-   Misc / Placeholders:
-   - TODO markers / unresolved decisions
-   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
-
-   For each category with Partial or Missing status, add a candidate question opportunity unless:
-   - Clarification would not materially change implementation or validation strategy
-   - Information is better deferred to planning phase (note internally)
-
-3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
-    - Maximum of 5 total questions across the whole session.
-    - Each question must be answerable with EITHER:
-       * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
-       * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
-   - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
-   - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
-   - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
-   - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
-   - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
-
-4. Sequential questioning loop (interactive):
-    - Present EXACTLY ONE question at a time.
-    - For multiple‑choice questions render options as a Markdown table:
-
-       | Option | Description |
-       |--------|-------------|
-       | A | <Option A description> |
-       | B | <Option B description> |
-       | C | <Option C description> | (add D/E as needed up to 5)
-       | Short | Provide a different short answer (<=5 words) | (Include only if free-form alternative is appropriate)
-
-    - For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
-    - After the user answers:
-       * Validate the answer maps to one option or fits the <=5 word constraint.
-       * If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
-       * Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
-    - Stop asking further questions when:
-       * All critical ambiguities resolved early (remaining queued items become unnecessary), OR
-       * User signals completion ("done", "good", "no more"), OR
-       * You reach 5 asked questions.
-    - Never reveal future queued questions in advance.
-    - If no valid questions exist at start, immediately report no critical ambiguities.
-
-5. Integration after EACH accepted answer (incremental update approach):
-    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
-    - For the first integrated answer in this session:
-       * Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
-       * Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
-    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
-    - Then immediately apply the clarification to the most appropriate section(s):
-       * Functional ambiguity → Update or add a bullet in Functional Requirements.
-       * User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
-       * Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
-       * Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
-       * Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
-       * Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
-    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
-    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
-    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
-    - Keep each inserted clarification minimal and testable (avoid narrative drift).
-
-6. Validation (performed after EACH write plus final pass):
-   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
-   - Total asked (accepted) questions ≤ 5.
-   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
-   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
-   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
-   - Terminology consistency: same canonical term used across all updated sections.
-
-7. Write the updated spec back to `FEATURE_SPEC`.
-
-8. Report completion (after questioning loop ends or early termination):
-   - Number of questions asked & answered.
-   - Path to updated spec.
-   - Sections touched (list names).
-   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
-   - If any Outstanding or Deferred remain, recommend whether to proceed to `/plan` or run `/clarify` again later post-plan.
-   - Suggested next command.
-
-Behavior rules:
-- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
-- If spec file missing, instruct user to run `/specify` first (do not create a new spec here).
-- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
-- Avoid speculative tech stack questions unless the absence blocks functional clarity.
-- Respect user early termination signals ("stop", "done", "proceed").
- - If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
- - If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
-
-Context for prioritization: $ARGUMENTS