ac-framework 1.5.0 → 1.6.0

package/bin/postinstall.js

@@ -5,8 +5,24 @@ const isWin = process.platform === 'win32';
 console.log();
 console.log('  ✓ ac-framework installed successfully!');
 console.log();
-console.log('  Get started:');
-console.log('    acfm init');
+console.log('  Available commands:');
+console.log();
+console.log('    Core');
+console.log('      acfm init                Install modules into your project');
+console.log('      acfm init --latest       Download latest from GitHub');
+console.log('      acfm update              Update installed modules');
+console.log();
+console.log('    Spec-Driven Workflow');
+console.log('      acfm spec init           Bootstrap openspec/ directory');
+console.log('      acfm spec new <name>     Create a new change');
+console.log('      acfm spec status         View change status');
+console.log('      acfm spec list           List active changes');
+console.log('      acfm spec instructions   Get artifact instructions');
+console.log('      acfm spec validate       Validate change structure');
+console.log('      acfm spec archive        Archive a completed change');
+console.log('      acfm spec schemas        List workflow schemas');
+console.log();
+console.log('    Tip: Add --json to any spec command for machine-readable output.');
 console.log();
 
 if (isWin) {

package/framework/.agent/skills/openspec-apply-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-apply-change
 description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -20,13 +20,13 @@ Implement tasks from an OpenSpec change.
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run `acfm spec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
 
    Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
 
 2. **Check status to understand the schema**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
@@ -35,7 +35,7 @@ Implement tasks from an OpenSpec change.
 3. **Get apply instructions**
 
    ```bash
-   openspec instructions apply --change "<name>" --json
+   acfm spec instructions apply --change "<name>" --json
    ```
 
    This returns:

package/framework/.agent/skills/openspec-archive-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-archive-change
 description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -17,7 +17,7 @@ Archive a completed change in the experimental workflow.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -26,7 +26,7 @@ Archive a completed change in the experimental workflow.
 
 2. **Check artifact completion status**
 
-   Run `openspec status --change "<name>" --json` to check artifact completion.
+   Run `acfm spec status --change "<name>" --json` to check artifact completion.
 
    Parse the JSON to understand:
    - `schemaName`: The workflow being used
@@ -106,7 +106,7 @@ All artifacts complete. All tasks complete.
 
 **Guardrails**
 - Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
+- Use artifact graph (acfm spec status --json) for completion checking
 - Don't block archive on warnings - just inform and confirm
 - Preserve .openspec.yaml when moving to archive (it moves with the directory)
 - Show clear summary of what happened

package/framework/.agent/skills/openspec-bulk-archive-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-bulk-archive-change
 description: Archive multiple completed changes at once. Use when archiving several parallel changes.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -19,7 +19,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
 1. **Get active changes**
 
-   Run `openspec list --json` to get all active changes.
+   Run `acfm spec list --json` to get all active changes.
 
    If no active changes exist, inform user and stop.
 
@@ -36,7 +36,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
    For each selected change, collect:
 
-   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+   a. **Artifact status** - Run `acfm spec status --change "<name>" --json`
       - Parse `schemaName` and `artifacts` list
       - Note which artifacts are `done` vs other states
 

package/framework/.agent/skills/openspec-continue-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-continue-change
 description: Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -17,7 +17,7 @@ Continue working on a change by creating the next artifact.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Run `acfm spec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name
@@ -31,7 +31,7 @@ Continue working on a change by creating the next artifact.
 
 2. **Check current status**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to understand current state. The response includes:
    - `schemaName`: The workflow schema being used (e.g., "spec-driven")
@@ -54,7 +54,7 @@ Continue working on a change by creating the next artifact.
    - Pick the FIRST artifact with `status: "ready"` from the status output
    - Get its instructions:
      ```bash
-     openspec instructions <artifact-id> --change "<name>" --json
+     acfm spec instructions <artifact-id> --change "<name>" --json
      ```
    - Parse the JSON. The key fields are:
      - `context`: Project background (constraints for you - do NOT include in output)
@@ -79,7 +79,7 @@ Continue working on a change by creating the next artifact.
 
 4. **After creating an artifact, show progress**
    ```bash
-   openspec status --change "<name>"
+   acfm spec status --change "<name>"
    ```
 
 **Output**

package/framework/.agent/skills/openspec-explore/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-explore
 description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -83,7 +83,7 @@ You have full context of the OpenSpec system. Use it naturally, don't force it.
 
 At the start, quickly check what exists:
 ```bash
-openspec list --json
+acfm spec list --json
 ```
 
 This tells you:

package/framework/.agent/skills/openspec-ff-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-ff-change
 description: Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -26,13 +26,13 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
 2. **Create the change directory**
    ```bash
-   openspec new change "<name>"
+   acfm spec new "<name>"
    ```
    This creates a scaffolded change at `openspec/changes/<name>/`.
 
 3. **Get the artifact build order**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to get:
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
@@ -47,7 +47,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
    a. **For each artifact that is `ready` (dependencies satisfied)**:
       - Get instructions:
         ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
+        acfm spec instructions <artifact-id> --change "<name>" --json
         ```
       - The instructions JSON includes:
         - `context`: Project background (constraints for you - do NOT include in output)
@@ -62,7 +62,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
       - Show brief progress: "✓ Created <artifact-id>"
 
    b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - After creating each artifact, re-run `acfm spec status --change "<name>" --json`
       - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
       - Stop when all `applyRequires` artifacts are done
 
@@ -72,7 +72,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
 5. **Show final status**
    ```bash
-   openspec status --change "<name>"
+   acfm spec status --change "<name>"
    ```
 
 **Output**
@@ -85,7 +85,7 @@ After completing all artifacts, summarize:
 
 **Artifact Creation Guidelines**
 
-- Follow the `instruction` field from `openspec instructions` for each artifact type
+- Follow the `instruction` field from `acfm spec instructions` for each artifact type
 - The schema defines what each artifact should contain - follow it
 - Read dependency artifacts for context before creating new ones
 - Use `template` as the structure for your output file - fill in its sections

package/framework/.agent/skills/openspec-new-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-new-change
 description: Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -30,20 +30,20 @@ Start a new change using the experimental artifact-driven approach.
 
    **Use a different schema only if the user mentions:**
    - A specific schema name → use `--schema <name>`
-   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
+   - "show workflows" or "what workflows" → run `acfm spec schemas --json` and let them choose
 
    **Otherwise**: Omit `--schema` to use the default.
 
 3. **Create the change directory**
    ```bash
-   openspec new change "<name>"
+   acfm spec new "<name>"
    ```
    Add `--schema <name>` only if the user requested a specific workflow.
    This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
 
 4. **Show the artifact status**
    ```bash
-   openspec status --change "<name>"
+   acfm spec status --change "<name>"
    ```
    This shows which artifacts need to be created and which are ready (dependencies satisfied).
 
@@ -51,7 +51,7 @@ Start a new change using the experimental artifact-driven approach.
    The first artifact depends on the schema (e.g., `proposal` for spec-driven).
    Check the status output to find the first artifact with status "ready".
    ```bash
-   openspec instructions <first-artifact-id> --change "<name>"
+   acfm spec instructions <first-artifact-id> --change "<name>"
    ```
    This outputs the template and context for creating the first artifact.
 

package/framework/.agent/skills/openspec-onboard/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-onboard
 description: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -18,11 +18,11 @@ Guide the user through their first complete OpenSpec workflow cycle. This is a t
 Before starting, check if OpenSpec is initialized:
 
 ```bash
-openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+acfm spec status --json 2>&1 || echo "NOT_INITIALIZED"
 ```
 
 **If not initialized:**
-> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`.
+> OpenSpec isn't set up in this project yet. Run `acfm spec init` first, then come back to `/opsx:onboard`.
 
 Stop here if not initialized.
 
@@ -168,7 +168,7 @@ Let me create one for our task.
 
 **DO:** Create the change with a derived kebab-case name:
 ```bash
-openspec new change "<derived-name>"
+acfm spec new "<derived-name>"
 ```
 
 **SHOW:**
@@ -237,7 +237,7 @@ Does this capture the intent? I can adjust before we save it.
 
 After approval, save the proposal:
 ```bash
-openspec instructions proposal --change "<name>" --json
+acfm spec instructions proposal --change "<name>" --json
 ```
 Then write the content to `openspec/changes/<name>/proposal.md`.
 
@@ -423,7 +423,7 @@ Archived changes become your project's decision history—you can always find th
 
 **DO:**
 ```bash
-openspec archive "<name>"
+acfm spec archive "<name>"
 ```
 
 **SHOW:**

package/framework/.agent/skills/openspec-sync-specs/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-sync-specs
 description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -19,7 +19,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show changes that have delta specs (under `specs/` directory).
 

package/framework/.agent/skills/openspec-verify-change/SKILL.md

@@ -2,7 +2,7 @@
 name: openspec-verify-change
 description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires acfm CLI (bundled).
 metadata:
   author: openspec
   version: "1.0"
@@ -17,7 +17,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
    Show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.
@@ -27,7 +27,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
 2. **Check status to understand the schema**
    ```bash
-   openspec status --change "<name>" --json
+   acfm spec status --change "<name>" --json
    ```
    Parse the JSON to understand:
    - `schemaName`: The workflow being used (e.g., "spec-driven")
@@ -36,7 +36,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 3. **Get the change directory and load artifacts**
 
    ```bash
-   openspec instructions apply --change "<name>" --json
+   acfm spec instructions apply --change "<name>" --json
    ```
 
    This returns the change directory and context files. Read all available artifacts from `contextFiles`.

package/framework/.agent/skills/performance-optimizer/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: performance-optimizer
+description: Transform the agent into a performance engineer. Apply methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage).
+---
+
+# Performance Optimization
+
+## Overview
+
+Use this skill to analyze and improve the performance of the codebase. Focus on measurable improvements, not premature optimization.
+
+## Workflow
+
+1.  **Measure First**:
+    *   Never optimize without a baseline.
+    *   Use profiling tools or simple timing logs to identify bottlenecks.
+    *   "What gets measured, gets managed."
+
+2.  **Analyze and Hypothesize**:
+    *   Identify the root cause: CPU, Memory, I/O, or Network?
+    *   Look for common culprits: N+1 queries, unoptimized loops, large payload sizes, unnecessary re-renders (frontend).
+
+3.  **Optimize**:
+    *   **Algorithmic**: Improve Big-O complexity (e.g., O(n^2) -> O(n)).
+    *   **Caching**: Implement caching strategies (in-memory, Redis, HTTP caching).
+    *   **Database**: Add indexes, optimize queries, use batching.
+    *   **Frontend**: Lazy loading, memoization, code splitting, asset optimization.
+
+4.  **Verify**:
+    *   Run the measurements again.
+    *   Confirm the improvement.
+    *   Ensure no regression in functionality.
+
+## Techniques & Patterns
+
+*   **Database**: Explain Analyze, Indexing, Connection Pooling.
+*   **Backend**: Async processing, Caching layers, Load balancing.
+*   **Frontend**: Virtualization for long lists, Debouncing/Throttling events.
+
+## Output
+
+*   Create a brief report of findings and improvements.
+*   Update code with optimized solution.

package/framework/.agent/skills/project-constitution/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: project-constitution
+description: Manage the project's core principles and ensuring alignment. Create or update the project constitution from interactive or provided principle inputs.
+---
+
+# Project Constitution Management
+
+## Overview
+
+You are updating the project constitution at `.specify/memory/constitution.md` (or `.specify/.specify/memory/constitution.md` if the user's structure differs). This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If the constitution file does not exist yet, it should have been initialized from a template during project setup. If it's missing, copy the template first (check `.specify/templates/constitution-template.md`).
+
+## Execution Flow
+
+1.  **Load the existing constitution**.
+    *   Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+    *   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2.  **Collect/derive values for placeholders**:
+    *   If user input (conversation) supplies a value, use it.
+    *   Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+    *   For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+    *   `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+        *   MAJOR: Backward incompatible governance/principle removals or redefinitions.
+        *   MINOR: New principle/section added or materially expanded guidance.
+        *   PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+    *   If version bump type ambiguous, propose reasoning before finalizing.
+
+3.  **Draft the updated constitution content**:
+    *   Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+    *   Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+    *   Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+    *   Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4.  **Consistency propagation checklist**:
+    *   Check if `.specify/templates/plan-template.md`, `.specify/templates/spec-template.md`, and any other templates align with the updated constitution.
+    *   Update runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`) if they reference changed principles.
+
+5.  **Produce a Sync Impact Report** (prepend as an HTML comment at top of the constitution file after update):
+    *   Version change: old → new
+    *   List of modified principles (old title → new title if renamed)
+    *   Added/Removed sections
+    *   Templates requiring updates (✅ updated / ⚠ pending) with file paths
+    *   Follow-up TODOs.
+
+6.  **Validation before final output**:
+    *   No remaining unexplained bracket tokens.
+    *   Version line matches report.
+    *   Dates ISO format YYYY-MM-DD.
+    *   Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7.  **Write the completed constitution** back to the file (overwrite).
+
+8.  **Output a final summary**:
+    *   New version and bump rationale.
+    *   Any files flagged for manual follow-up.
+    *   Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+## Formatting & Style Requirements
+
+*   Use Markdown headings exactly as in the template.
+*   Wrap long rationale lines to keep readability (<100 chars ideally).
+*   Keep a single blank line between sections.
+*   Avoid trailing whitespace.
+*   If critical info missing, insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report.

package/framework/.agent/skills/requirement-checklist/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: requirement-checklist
+description: Generate comprehensive checklists to validate requirements quality (Unit Tests for Specs). Critically examine the spec for clarity, completeness, and consistency before implementation starts.
+---
+
+# Requirement Checklist Generation
+
+## Overview
+
+Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing implementation**:
+*   ❌ NOT "Verify the button clicks correctly"
+*   ❌ NOT "Test error handling works"
+*   ❌ NOT "Confirm the API returns 200"
+*   ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+*   ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+*   ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+*   ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+*   ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+*   ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+## Execution Steps
+
+1.  **Setup**:
+    *   Parse feature directory and available docs list.
+    *   Identify the target feature spec (`spec.md`, `plan.md`, `tasks.md`).
+
+2.  **Clarify intent (dynamic)**:
+    *   Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+        *   Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+        *   Only ask about information that materially changes checklist content
+    *   Generation algorithm:
+        1.  Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+        2.  Cluster signals into candidate focus areas (max 4) ranked by relevance.
+        3.  Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+        4.  Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+
+3.  **Generate checklist - Create "Unit Tests for Requirements"**:
+    *   Create a checklist file in the feature directory (e.g., `checklists/[domain].md`).
+    *   Format: `[domain].md` (e.g., `ux.md`, `api.md`, `security.md`).
+    *   Number items sequentially starting from CHK001.
+    *   Each run creates a NEW file (never overwrites existing checklists unless explicitly told).
+
+    **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+    Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+    *   **Completeness**: Are all necessary requirements present?
+    *   **Clarity**: Are requirements unambiguous and specific?
+    *   **Consistency**: Do requirements align with each other?
+    *   **Measurability**: Can requirements be objectively verified?
+    *   **Coverage**: Are all scenarios/edge cases addressed?
+
+    **Category Structure**:
+    *   Requirement Completeness
+    *   Requirement Clarity
+    *   Requirement Consistency
+    *   Acceptance Criteria Quality
+    *   Scenario Coverage
+    *   Edge Case Coverage
+    *   Non-Functional Requirements
+    *   Dependencies & Assumptions
+    *   Ambiguities & Conflicts
+
+4.  **Structure Reference**:
+    *   Generate the checklist following a markdown template: Title, Purpose, Category Headings, `##` sections, `- [ ] CHK### <requirement item>` lines.
+
+5.  **Report**:
+    *   Output full path to created checklist, item count, and remind user that each run creates a new file.
+    *   Summarize focus areas selected, depth level, and valid user must-haves.
+
+## Checklist Item Guidelines
+
+**Example Checklist Items**:
+
+*   **UX**: "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+*   **API**: "Are error response formats specified for all failure scenarios? [Completeness]"
+*   **Performance**: "Are performance requirements quantified with specific metrics? [Clarity]"
+*   **Security**: "Are authentication requirements specified for all protected resources? [Coverage]"
+
+**Avoid Implementation Tests**:
+*   ❌ "Verify landing page displays 3 episode cards"
+*   ❌ "Test hover states work correctly on desktop"
+*   ❌ "Confirm logo click navigates to home page"
+
+**Use Quality Checks**:
+*   ✅ "Are the exact number and layout of featured episodes specified?" [Completeness]
+*   ✅ "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+*   ✅ "Are hover state requirements consistent across all interactive elements?" [Consistency]

package/framework/.agent/skills/spec-analysis/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spec-analysis
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md. Identifying inconsistencies, duplications, ambiguities, and underspecified items.
+---
+
+# Specification & Planning Analysis
+
+## Overview
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation.
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan.
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable**.
+
+## Execution Steps
+
+1.  **Initialize Analysis Context**:
+    *   Load `FEATURE_DIR/spec.md` (or `specs/spec.md`).
+    *   Load `FEATURE_DIR/plan.md` (or `specs/plan.md`).
+    *   Load `FEATURE_DIR/tasks.md` (or `specs/tasks.md`).
+    *   Ensure all files exist; if not, report which are missing (though tasks might not exist yet if only planning).
+
+2.  **Load Artifacts (Progressive Disclosure)**:
+    *   Load only necessary portions relevant to the feature.
+    *   Load `.specify/memory/constitution.md` for validation.
+
+3.  **Build Semantic Models**:
+    *   **Requirements inventory**: Functional + non-functional requirements.
+    *   **User story/action inventory**: User actions + acceptance criteria.
+    *   **Task coverage mapping**: Map task to requirement/story.
+    *   **Constitution rule set**: Principle names and MUST statements.
+
+4.  **Detection Passes**:
+    *   **Duplication**: Near-duplicate requirements.
+    *   **Ambiguity**: Vague adjectives ("fast", "robust") without metrics. Unresolved placeholders (TODO, ???).
+    *   **Underspecification**: Verbs missing objects/outcomes. User stories missing acceptance criteria.
+    *   **Constitution Alignment**: Conflict with MUST principles. Missing mandated sections.
+    *   **Coverage Gaps**: Requirements with zero tasks. Tasks with no mapped requirement.
+    *   **Inconsistency**: Terminology drift. Data entities in plan but absent in spec. Task order contradictions.
+
+5.  **Severity Assignment**:
+    *   **CRITICAL**: Violates constitution, missing core artifact, blocking requirement with zero coverage.
+    *   **HIGH**: Duplicate/conflicting requirement, ambiguous security/performance, untestable AC.
+    *   **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case.
+    *   **LOW**: Style/wording improvements.
+
+6.  **Produce Compact Analysis Report**:
+    *   Output a Markdown report with a findings table: | ID | Category | Severity | Location | Summary | Recommendation |
+    *   **Coverage Summary Table**: Requirement Key | Has Task? | Task IDs | Notes
+    *   **Metrics**: Total Requirements, Total Tasks, Coverage %, Ambiguity Count.
+
+7.  **Provide Next Actions**:
+    *   Recommend resolving CRITICAL issues before implementation.
+    *   Provide explicit suggestions (e.g., "Refine spec", "Adjust plan").
+
+8.  **Offer Remediation**:
+    *   Ask if the user wants concrete remediation edits for top N issues.
+
+## Operating Principles
+
+*   **Context Efficiency**: Focus on actionable findings.
+*   **NEVER modify files** automatically (read-only analysis).
+*   **NEVER hallucinate missing sections**.
+*   **Prioritize constitution violations**.