feat: add /speckit-delta — constitution-driven vision-gap analysis

README.md

@@ -173,6 +173,7 @@ Additional commands for enhanced quality and validation:
 | `/speckit.clarify`   | `speckit-clarify`      | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`)                                                |
 | `/speckit.analyze`   | `speckit-analyze`      | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`)                             |
 | `/speckit.checklist` | `speckit-checklist`    | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
+| `/speckit.delta`     | `speckit-delta`        | Compute the gap between the constitution's Vision and current repo state, then recommend the next feature to specify                 |
 
 ## 🔧 Specify CLI Reference
 

src/specify_cli/__init__.py

@@ -433,6 +433,7 @@ def _print_cli_warning(
     "clarify": "Structured clarification workflow for underspecified requirements.",
     "constitution": "Create or update project governing principles and development guidelines.",
     "checklist": "Generate custom quality checklists for validating requirements completeness and clarity.",
+    "delta": "Compute the gap between the constitution's Vision and current repo state to recommend the next feature.",
     "taskstoissues": "Convert tasks from tasks.md into GitHub issues.",
 }
 

src/specify_cli/extensions.py

@@ -32,6 +32,7 @@
     "analyze",
     "clarify",
     "constitution",
+    "delta",
     "implement",
     "plan",
     "checklist",

src/specify_cli/integrations/claude/__init__.py

@@ -21,6 +21,7 @@
     "clarify": "Optional areas to clarify in the spec",
     "constitution": "Principles or values for the project constitution",
     "checklist": "Domain or focus area for the checklist",
+    "delta": "Optional focus hint for the next feature recommendation",
     "taskstoissues": "Optional filter or label for GitHub issues",
 }
 

templates/commands/constitution.md

@@ -73,8 +73,15 @@ Follow this execution flow:
 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 the **Vision & Direction** section is populated with:
+     - A single, durable **North Star** statement (1–2 sentences).
+     - **Target Users & Value** — who the project serves and the enduring value delivered.
+     - **Long-Term Objectives** — 3–7 outcome-oriented, observable objectives (not feature lists). Each must be phrased so progress against it can be assessed by inspecting repo state (`__SPECKIT_COMMAND_DELTA__` depends on this).
+     - **Non-Goals** — explicit out-of-scope statements that bound the project.
+     If user input does not supply Vision content, infer it from `README.md`, existing docs, and the prior constitution. If still indeterminate, mark with `TODO(VISION): ...` and include in the Sync Impact Report — do **not** leave bracketed placeholders.
    - 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.
+   - Vision amendments are governed by the same Governance rules: changes to **North Star** or **Long-Term Objectives** are MAJOR bumps; adding/removing **Non-Goals** or refining **Target Users & Value** is MINOR; wording polish is PATCH.
 
 4. Consistency propagation checklist (convert prior checklist into active validations):
    - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.

templates/commands/delta.md

@@ -0,0 +1,200 @@
+---
+description: Compute the gap between the constitution's Vision & Direction and the current repo state (code + specs) to recommend the next feature.
+handoffs:
+  - label: Specify Next Feature
+    agent: speckit.specify
+    prompt: Specify the next feature recommended by the delta report. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+User input is optional. When provided, treat it as a focus hint (e.g., a specific
+Long-Term Objective to prioritize, a constraint like "no infra work this cycle",
+or a candidate feature to evaluate against the Vision).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before delta)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_delta` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+The `__SPECKIT_COMMAND_DELTA__` command pairs with the Vision & Direction section
+of the constitution. `__SPECKIT_COMMAND_SPECIFY__` adds work *incrementally*;
+this command answers the orthogonal question: **given everything we have shipped
+so far, what should we build next to close the gap to the Vision?**
+
+It is a read-only analysis (plus a single write to `.specify/memory/delta.md`).
+Do **not** create specs, branches, plans, or tasks here.
+
+Follow this execution flow:
+
+1. **Load the Vision**:
+   - Read `.specify/memory/constitution.md`.
+   - Extract the **Vision & Direction** section: North Star, Target Users & Value,
+     **Long-Term Objectives** (the primary unit of comparison), and **Non-Goals**.
+   - If the section is missing or still contains bracketed placeholders, abort with
+     an error instructing the user to run `__SPECKIT_COMMAND_CONSTITUTION__` first.
+
+2. **Inventory cumulative work** (what has been built so far):
+   - List every directory under `specs/` (skip `_delta/` if present). For each:
+     - Read `spec.md` (title, primary requirement, success criteria).
+     - Read `plan.md` if present (technical approach, scope).
+     - Read `tasks.md` if present and count completed vs total tasks (look for
+       `- [x]` vs `- [ ]` markers, or whatever convention the project uses).
+   - This is the **spec-side** view of cumulative work.
+
+3. **Inspect repo state** (what is actually in the code):
+   - Use `git log --oneline -n 50` to sample recent activity.
+   - Read top-level `README.md` and any `docs/` index for the project's
+     self-described capabilities.
+   - Walk the primary source tree (e.g., `src/`, `app/`, `lib/`, or whatever the
+     repo uses) at one level deep to identify shipped modules/packages.
+   - Read `CHANGELOG.md` if it exists — this is often the highest-signal source.
+   - This is the **reality-side** view; it catches drift between specs and code.
+
+4. **Compute the delta** — for each Long-Term Objective, classify status:
+   - **Met** — clear evidence in code + specs that the objective holds today.
+   - **Partial** — some progress, with specific gaps (name them).
+   - **Untouched** — no meaningful progress.
+   - **Drift** — code has diverged from what specs claim, or the objective has
+     been undermined by recent work.
+
+   For each Partial / Untouched objective, identify the smallest concrete
+   feature that would move it forward. Cross-check candidates against
+   **Non-Goals** and drop any that violate them.
+
+5. **Rank candidate next features** by:
+   - **Leverage** — how many objectives the feature advances at once.
+   - **Unblocking** — does it unlock other roadmap items?
+   - **Cost/risk** — rough size, and whether it sits in a fragile area.
+   - **Sequencing** — does it depend on something not yet shipped?
+
+   Pick the top 1 as the **primary recommendation** and keep up to 2 alternates.
+   If the user supplied a focus hint in `$ARGUMENTS`, bias ranking accordingly
+   and note the bias in the report.
+
+6. **Write the delta report** to `.specify/memory/delta.md` (overwrite). Use this
+   structure exactly:
+
+   ```markdown
+   # Delta Report
+
+   **Generated**: YYYY-MM-DD
+   **Constitution Version**: <version line from constitution.md>
+   **Focus Hint**: <verbatim $ARGUMENTS, or "none">
+
+   ## Vision Snapshot
+   - **North Star**: <one line>
+   - **Long-Term Objectives**: <bullet list, verbatim from constitution>
+
+   ## Cumulative Build
+   <Per-feature table or list summarizing specs/ — name, status, primary outcome.
+   Include a one-line summary of repo-level capabilities derived from code inspection.>
+
+   ## Objective Status
+   | Objective | Status | Evidence | Gap |
+   |-----------|--------|----------|-----|
+   | <obj 1>   | Met / Partial / Untouched / Drift | <spec or code pointer> | <what is missing> |
+   ...
+
+   ## Recommended Next Feature
+   **Title**: <short imperative phrase>
+   **Why now**: <which objectives it advances; leverage rationale>
+   **Scope sketch**: <2–4 bullets — enough to feed into `__SPECKIT_COMMAND_SPECIFY__`>
+   **Non-Goals respected**: <which non-goals this avoids violating>
+   **Estimated size**: S / M / L
+   **Dependencies**: <prior specs or external prerequisites, or "none">
+
+   ## Alternates
+   1. <Title> — <one-line rationale>
+   2. <Title> — <one-line rationale>
+
+   ## Drift & Risks
+   <Anything noticed during inspection that does NOT belong in the next feature
+   but should be flagged: spec/code divergence, Non-Goal violations in flight,
+   stalled features.>
+   ```
+
+7. **Report completion** to the user with:
+   - Path: `.specify/memory/delta.md`
+   - One-line summary of the recommended next feature.
+   - Count of objectives at each status (Met / Partial / Untouched / Drift).
+   - Suggested next command: `__SPECKIT_COMMAND_SPECIFY__ <the recommended feature>`.
+
+## Constraints
+
+- **Read-mostly**: the only file this command writes is `.specify/memory/delta.md`.
+  Do not create spec directories, branches, or modify the constitution.
+- **No new objectives**: if you believe the Vision itself is wrong or stale,
+  surface it in the *Drift & Risks* section and recommend the user run
+  `__SPECKIT_COMMAND_CONSTITUTION__` — do not silently invent objectives here.
+- **Respect Non-Goals**: a recommendation that violates a stated Non-Goal is a
+  bug in this command, not a feature.
+- **Honest "Untouched"**: do not pad evidence to make objectives look further
+  along than they are. The value of this command is calibration, not optimism.
+
+## Post-Execution Checks
+
+**Check for extension hooks (after delta)**:
+Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_delta` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

templates/constitution-template.md

@@ -1,6 +1,54 @@
 # [PROJECT_NAME] Constitution
 <!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
 
+## Vision & Direction
+<!--
+  The Vision is the stable, fixed objective for the project. It does not change
+  with every feature. It answers: WHY this project exists, WHO it serves, and
+  WHERE it is heading in the long term. Individual features added via
+  `__SPECKIT_COMMAND_SPECIFY__` are incremental steps toward this Vision; the
+  `__SPECKIT_COMMAND_DELTA__` command computes the gap between this Vision and
+  current repo state to suggest the next feature.
+
+  Keep this section terse, declarative, and durable — amendments here should be
+  rare and follow the Governance procedure below.
+-->
+
+### North Star
+<!-- One or two sentences. The single, enduring purpose of the project. -->
+[NORTH_STAR_STATEMENT]
+<!-- Example: Make spec-driven development the default way teams ship reliable software. -->
+
+### Target Users & Value
+<!-- Who this serves and the durable value delivered to them. -->
+[TARGET_USERS_AND_VALUE]
+<!-- Example: Engineering teams who want auditable, reproducible feature delivery; value = traceable path from intent to code. -->
+
+### Long-Term Objectives
+<!--
+  A small set (3–7) of durable, outcome-oriented objectives. These are NOT a
+  feature list — they describe *states the project should reach*. Each must be
+  observable so `__SPECKIT_COMMAND_DELTA__` can assess progress against the
+  current repo state.
+-->
+- [OBJECTIVE_1]
+- [OBJECTIVE_2]
+- [OBJECTIVE_3]
+<!-- Example:
+- Every shipped feature is traceable to a spec, a plan, and a verifiable test.
+- Onboarding a new contributor to a workflow takes under 30 minutes.
+- The framework supports at least three coding-agent integrations without core changes.
+-->
+
+### Non-Goals
+<!-- Explicit statements of what the project will NOT pursue, to bound scope. -->
+- [NON_GOAL_1]
+- [NON_GOAL_2]
+<!-- Example:
+- Becoming a general-purpose project management tool.
+- Replacing human review in the spec → implementation pipeline.
+-->
+
 ## Core Principles
 
 ### [PRINCIPLE_1_NAME]

templates/plan-template.md

@@ -42,6 +42,31 @@
 
 [Gates determined based on constitution file]
 
+## Vision Alignment Check
+
+*GATE: Must pass before Phase 0 research. Independent of Constitution Check —
+Constitution gates evaluate **principles** (HOW we build); this gates the feature
+against **Vision & Direction** (WHY and WHERE we are heading).*
+
+Read `.specify/memory/constitution.md` → `Vision & Direction` section. For each
+item, record a one-line judgement:
+
+| Vision Element | Verdict | Notes |
+|----------------|---------|-------|
+| North Star — does this feature move toward it? | Aligned / Neutral / Misaligned | <why> |
+| Target Users & Value — does this serve the stated users with the stated value? | Yes / Partial / No | <which user, which value> |
+| Long-Term Objective(s) advanced | List the specific objective IDs/titles | <how this advances them> |
+| Non-Goals — does this respect every stated Non-Goal? | Pass / Violation | <which non-goal, and why this still respects it> |
+
+**Pass criteria** (all must hold):
+- At least one Long-Term Objective is materially advanced.
+- No Non-Goal is violated.
+- North Star verdict is Aligned (Neutral is acceptable only with explicit justification in the Complexity Tracking section).
+
+**On failure**: stop. Either narrow the feature scope until it passes, or run
+`__SPECKIT_COMMAND_DELTA__` to identify a better-aligned next feature, or run
+`__SPECKIT_COMMAND_CONSTITUTION__` if the Vision itself needs amendment.
+
 ## Project Structure
 
 ### Documentation (this feature)

tests/integrations/test_integration_base_markdown.py

@@ -254,7 +254,7 @@ def test_init_options_includes_context_file(self, tmp_path):
 
     COMMAND_STEMS = [
         "agent-context.update",
-        "analyze", "clarify", "constitution", "implement",
+        "analyze", "clarify", "constitution", "delta", "implement",
         "plan", "checklist", "specify", "tasks", "taskstoissues",
     ]
 

tests/integrations/test_integration_base_skills.py

@@ -100,7 +100,7 @@ def test_skill_directory_structure(self, tmp_path):
         skill_files = [f for f in created if "scripts" not in f.parts]
 
         expected_commands = {
-            "analyze", "clarify", "constitution", "implement",
+            "analyze", "clarify", "constitution", "delta", "implement",
             "plan", "checklist", "specify", "tasks", "taskstoissues",
         }
 
@@ -393,7 +393,7 @@ def test_options_include_skills_flag(self):
     # -- Complete file inventory ------------------------------------------
 
     _SKILL_COMMANDS = [
-        "analyze", "clarify", "constitution", "implement",
+        "analyze", "clarify", "constitution", "delta", "implement",
         "plan", "checklist", "specify", "tasks", "taskstoissues",
     ]
 

tests/integrations/test_integration_base_toml.py

@@ -486,6 +486,7 @@ def test_init_options_includes_context_file(self, tmp_path):
         "analyze",
         "clarify",
         "constitution",
+        "delta",
         "implement",
         "plan",
         "checklist",

tests/integrations/test_integration_base_yaml.py

@@ -365,6 +365,7 @@ def test_init_options_includes_context_file(self, tmp_path):
         "analyze",
         "clarify",
         "constitution",
+        "delta",
         "implement",
         "plan",
         "checklist",