docs: update references from "Supported AI Agents" to "Supported AI T…

AGENTS.md

@@ -107,7 +107,7 @@ Also update any function docstrings, examples, and error messages that list avai
 
 #### 3. Update README Documentation
 
-Update the **Supported AI Agents** section in `README.md` to include the new agent:
+Update the **Supported AI Tools** section in `README.md` to include the new tool:
 
 - Add the new agent to the table with appropriate support level (Full/Partial)
 - Include the agent's official website link

CONTRIBUTING.md

@@ -11,7 +11,7 @@ These are one time installations required to be able to test your changes locall
 1. Install [Python 3.11+](https://www.python.org/downloads/)
 1. Install [uv](https://docs.astral.sh/uv/) for package management
 1. Install [Git](https://git-scm.com/downloads)
-1. Have an [AI coding agent available](README.md#-supported-ai-agents)
+1. Have an [AI coding tool available](README.md#-supported-ai-tools)
 
 <details>
 <summary><b>💡 Hint if you are using <code>VSCode</code> or <code>GitHub Codespaces</code> as your IDE</b></summary>

README.md

@@ -26,7 +26,7 @@
 - [🎨 Community Presets](#-community-presets)
 - [🚶 Community Walkthroughs](#-community-walkthroughs)
 - [🛠️ Community Friends](#️-community-friends)
-- [🤖 Supported AI Agents](#-supported-ai-agents)
+- [🤖 Supported AI Tools](#-supported-ai-tools)
 - [🔧 Specify CLI Reference](#-specify-cli-reference)
 - [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets)
 - [📚 Core Philosophy](#-core-philosophy)
@@ -260,9 +260,9 @@ Community projects that extend, visualize, or build on Spec Kit:
 
 - **[Spec Kit Assistant](https://marketplace.visualstudio.com/items?itemName=rfsales.speckit-assistant)** — A VS Code extension that provides a visual orchestrator for the full SDD workflow (constitution → specification → planning → tasks → implementation) with phase status visualization, an interactive task checklist, DAG visualization, and support for Claude, Gemini, GitHub Copilot, and OpenAI backends. Requires the `specify` CLI in your PATH.
 
-## 🤖 Supported AI Agents
+## 🤖 Supported AI Tools
 
-| Agent                                                                                | Support | Notes                                                                                                                                     |
+| Tool                                                                                 | Support | Notes                                                                                                                                     |
 | ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | [Qoder CLI](https://qoder.com/cli)                                                   | ✅      |                                                                                                                                           |
 | [Kiro CLI](https://kiro.dev/docs/cli/)                                               | ✅      | Use `--ai kiro-cli` (alias: `--ai kiro`)                                                                                                 |
@@ -543,7 +543,7 @@ Our research and experimentation focus on:
 ## 🔧 Prerequisites
 
 - **Linux/macOS/Windows**
-- [Supported](#-supported-ai-agents) AI coding agent.
+- [Supported](#-supported-ai-tools) AI coding tool.
 - [uv](https://docs.astral.sh/uv/) for package management
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)

docs/upgrade.md

@@ -9,7 +9,7 @@
 | What to Upgrade | Command | When to Use |
 |----------------|---------|-------------|
 | **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files |
-| **Project Files** | `specify init --here --force --ai <your-agent>` | Update slash commands, templates, and scripts in your project |
+| **Project Files** | `specify init --here --force --ai <your-tool>` | Update slash commands, templates, and scripts in your project |
 | **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
 
 ---
@@ -73,10 +73,10 @@ The `specs/` directory is completely excluded from template packages and will ne
 Run this inside your project directory:
 
 ```bash
-specify init --here --force --ai <your-agent>
+specify init --here --force --ai <your-tool>
 ```
 
-Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Agents](../README.md#-supported-ai-agents)
+Replace `<your-tool>` with your AI tool. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools)
 
 **Example:**
 

src/specify_cli/__init__.py

@@ -1378,6 +1378,15 @@ def scaffold_from_core_pack(
                     if f.is_file():
                         shutil.copy2(f, tmpl_root / f.name)
 
+                # Copy compact templates subdirectory
+                compact_src = templates_dir / "compact"
+                if compact_src.is_dir():
+                    compact_dst = tmpl_root / "compact"
+                    compact_dst.mkdir(parents=True, exist_ok=True)
+                    for f in compact_src.iterdir():
+                        if f.is_file():
+                            shutil.copy2(f, compact_dst / f.name)
+
             # Scripts (bash/ and powershell/)
             for subdir in ("bash", "powershell"):
                 src = scripts_dir / subdir
@@ -1509,7 +1518,17 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None =
 def ensure_constitution_from_template(project_path: Path, tracker: StepTracker | None = None) -> None:
     """Copy constitution template to memory if it doesn't exist (preserves existing constitution on reinitialization)."""
     memory_constitution = project_path / ".specify" / "memory" / "constitution.md"
-    template_constitution = project_path / ".specify" / "templates" / "constitution-template.md"
+
+    # Choose template based on format preference
+    init_opts = load_init_options(project_path)
+    fmt = init_opts.get("format", "markdown")
+    if fmt == "compact":
+        template_constitution = project_path / ".specify" / "templates" / "compact" / "constitution-template.md"
+        if not template_constitution.exists():
+            # Fallback to standard template
+            template_constitution = project_path / ".specify" / "templates" / "constitution-template.md"
+    else:
+        template_constitution = project_path / ".specify" / "templates" / "constitution-template.md"
 
     # If constitution already exists in memory, preserve it
     if memory_constitution.exists():
@@ -1542,6 +1561,23 @@ def ensure_constitution_from_template(project_path: Path, tracker: StepTracker |
             console.print(f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]")
 
 
+def resolve_template_path(project_path: Path, template_name: str) -> Path:
+    """Resolve a template file path based on the configured format preference.
+
+    When format is 'compact', looks for the template in the compact/ subdirectory
+    first. Falls back to the standard template if compact variant is not found.
+    """
+    init_opts = load_init_options(project_path)
+    fmt = init_opts.get("format", "markdown")
+
+    if fmt == "compact":
+        compact_path = project_path / ".specify" / "templates" / "compact" / template_name
+        if compact_path.exists():
+            return compact_path
+
+    return project_path / ".specify" / "templates" / template_name
+
+
 INIT_OPTIONS_FILE = ".specify/init-options.json"
 
 
@@ -1906,6 +1942,7 @@ def init(
     offline: bool = typer.Option(False, "--offline", help="Use assets bundled in the specify-cli package instead of downloading from GitHub (no network access required). Bundled assets will become the default in v0.6.0 and this flag will be removed."),
     preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"),
     branch_numbering: str = typer.Option(None, "--branch-numbering", help="Branch numbering strategy: 'sequential' (001, 002, ...) or 'timestamp' (YYYYMMDD-HHMMSS)"),
+    template_format: str = typer.Option(None, "--format", help="Template format: 'markdown' (full verbose) or 'compact' (token-efficient minimal format)"),
     integration: str = typer.Option(None, "--integration", help="Use the new integration system (e.g. --integration copilot). Mutually exclusive with --ai."),
 ):
     """
@@ -2019,6 +2056,11 @@ def init(
         console.print(f"[red]Error:[/red] Invalid --branch-numbering value '{branch_numbering}'. Choose from: {', '.join(sorted(BRANCH_NUMBERING_CHOICES))}")
         raise typer.Exit(1)
 
+    TEMPLATE_FORMAT_CHOICES = {"markdown", "compact"}
+    if template_format and template_format not in TEMPLATE_FORMAT_CHOICES:
+        console.print(f"[red]Error:[/red] Invalid --format value '{template_format}'. Choose from: {', '.join(sorted(TEMPLATE_FORMAT_CHOICES))}")
+        raise typer.Exit(1)
+
     if here:
         project_name = Path.cwd().name
         project_path = Path.cwd()
@@ -2375,6 +2417,7 @@ def init(
                 "ai_skills": ai_skills,
                 "ai_commands_dir": ai_commands_dir,
                 "branch_numbering": branch_numbering or "sequential",
+                "format": template_format or "markdown",
                 "here": here,
                 "preset": preset,
                 "offline": offline,

src/specify_cli/agents.py

@@ -171,6 +171,16 @@ class CommandRegistrar:
         }
     }
 
+    @staticmethod
+    def _get_template_format(project_root: Path) -> str:
+        """Read the template format preference from init-options.json."""
+        try:
+            from . import load_init_options
+        except ImportError:
+            return "markdown"
+        opts = load_init_options(project_root)
+        return opts.get("format", "markdown") if isinstance(opts, dict) else "markdown"
+
     @staticmethod
     def parse_frontmatter(content: str) -> tuple[dict, str]:
         """Parse YAML frontmatter from Markdown content.
@@ -490,11 +500,20 @@ def register_commands(
 
         registered = []
 
+        # Determine template format preference from init options
+        template_format = self._get_template_format(project_root)
+
         for cmd_info in commands:
             cmd_name = cmd_info["name"]
             cmd_file = cmd_info["file"]
 
+            # Use compact command template if format is compact and compact variant exists
             source_file = source_dir / cmd_file
+            if template_format == "compact":
+                compact_file = source_dir / "compact" / cmd_file
+                if compact_file.exists():
+                    source_file = compact_file
+
             if not source_file.exists():
                 continue
 

templates/commands/compact/analyze.md

@@ -0,0 +1,54 @@
+---
+description: Non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md.
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
+  ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
+---
+
+## Input
+
+```text
+$ARGUMENTS
+```
+
+Consider user input before proceeding (if not empty).
+
+## Constraints
+
+**READ-ONLY**: Never modify files. Output structured analysis report only.
+**Constitution** (`/memory/constitution.md`) is non-negotiable - conflicts are always CRITICAL.
+
+## Workflow
+
+1. Run `{SCRIPT}`, parse FEATURE_DIR. Derive SPEC, PLAN, TASKS paths. Abort if any missing.
+
+2. **Load** minimal context from each artifact:
+   - spec.md: requirements, success criteria, user stories, edge cases
+   - plan.md: architecture, data model, phases, constraints
+   - tasks.md: IDs, descriptions, phases, [P] markers, file paths
+   - constitution: principles, MUST/SHOULD statements
+
+3. **Build models**: Requirements inventory (FR-###, SC-###), user story/action inventory, task coverage mapping, constitution rule set.
+
+4. **Detection passes** (max 50 findings):
+   - A. **Duplication**: near-duplicate requirements
+   - B. **Ambiguity**: vague terms without metrics, unresolved placeholders
+   - C. **Underspecification**: missing outcomes, unaligned stories, undefined references
+   - D. **Constitution alignment**: MUST principle violations, missing mandated sections
+   - E. **Coverage gaps**: requirements with zero tasks, orphan tasks, unbuildable success criteria
+   - F. **Inconsistency**: terminology drift, entity mismatches, ordering contradictions
+
+5. **Severity**: CRITICAL (constitution violation, zero-coverage blocking req) > HIGH (conflicts, ambiguous security/perf) > MEDIUM (terminology drift, missing NFR tasks) > LOW (style, minor redundancy)
+
+6. **Report** (markdown, no file writes):
+
+   | ID | Category | Severity | Location(s) | Summary | Recommendation |
+   |----|----------|----------|-------------|---------|----------------|
+
+   + Coverage summary table + Constitution issues + Unmapped tasks + Metrics (total reqs, tasks, coverage%, ambiguity/duplication/critical counts)
+
+7. **Next actions**: If CRITICAL → resolve before `/speckit.implement`. If LOW/MEDIUM → may proceed with suggestions.
+
+8. **Offer remediation**: Ask user if they want concrete edit suggestions for top N issues (don't apply automatically).
+
+Context: {ARGS}

templates/commands/compact/checklist.md

@@ -0,0 +1,49 @@
+---
+description: Generate a custom checklist for the current feature - "unit tests for requirements writing".
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json
+  ps: scripts/powershell/check-prerequisites.ps1 -Json
+---
+
+## Input
+
+```text
+$ARGUMENTS
+```
+
+Consider user input before proceeding (if not empty).
+
+## Core Concept
+
+Checklists are **unit tests for requirements** - they validate quality, clarity, and completeness of requirements, NOT implementation behavior.
+
+- YES: "Are visual hierarchy requirements defined?" / "Is 'fast' quantified with metrics?"
+- NO: "Verify button clicks" / "Test error handling works"
+
+## Workflow
+
+1. **Setup**: Run `{SCRIPT}`, parse FEATURE_DIR and AVAILABLE_DOCS.
+
+2. **Clarify intent**: Generate up to 3 contextual questions from user phrasing + spec signals (scope, depth, audience, risk). Skip if already clear from $ARGUMENTS. May ask 2 follow-ups if gaps remain (max 5 total).
+
+3. **Load context**: Read spec.md, plan.md (if exists), tasks.md (if exists) - only relevant portions.
+
+4. **Generate checklist**:
+   - Create `FEATURE_DIR/checklists/[domain].md`
+   - If exists: append continuing from last CHK ID. Never delete existing content.
+   - Group by: Completeness, Clarity, Consistency, Measurability, Coverage, Edge Cases, NFRs, Dependencies, Ambiguities
+   - Each item: question format about requirement quality with [dimension] tag
+   - Include traceability refs: `[Spec §X.Y]`, `[Gap]`, `[Ambiguity]`, `[Conflict]`
+   - Soft cap: 40 items, merge near-duplicates, consolidate low-impact edge cases
+
+5. **Report**: Path, item count, focus areas, whether created or appended.
+
+## Item Format
+
+```
+- [ ] CHK### Are [requirement type] defined/specified for [scenario]? [Dimension, Spec §X.Y]
+```
+
+Patterns: "Are X defined?" / "Is X quantified?" / "Are X consistent between A and B?" / "Can X be measured?" / "Does spec define X?"
+
+Prohibited: "Verify", "Test", "Confirm" + implementation behavior / "Displays correctly" / "Click", "navigate", "render"

templates/commands/compact/clarify.md

@@ -0,0 +1,52 @@
+---
+description: Identify underspecified areas in feature spec, ask up to 5 targeted clarification questions, encode answers back into spec.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+scripts:
+   sh: scripts/bash/check-prerequisites.sh --json --paths-only
+   ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
+---
+
+## Input
+
+```text
+$ARGUMENTS
+```
+
+Consider user input before proceeding (if not empty).
+
+## Workflow
+
+1. Run `{SCRIPT}`, parse FEATURE_DIR and FEATURE_SPEC. Abort if JSON fails.
+
+2. **Scan spec** using taxonomy (mark Clear/Partial/Missing):
+   - Functional scope, domain/data model, UX flow, non-functional (perf/scale/security/observability), integrations, edge cases, constraints, terminology, completion signals, placeholders
+
+3. **Generate max 5 questions** (prioritized by Impact*Uncertainty):
+   - Must be answerable via multiple-choice (2-5 options) or short answer (<=5 words)
+   - Only include if answer materially impacts architecture, testing, UX, or compliance
+   - Balance category coverage
+
+4. **Ask one at a time**:
+   - Multiple-choice: show **Recommended** option with reasoning + options table. User can pick letter, say "yes"/"recommended", or custom answer
+   - Short-answer: show **Suggested** answer. User can accept or provide own
+   - Stop when: all resolved, user signals done, or 5 questions asked
+
+5. **Integrate each answer** immediately:
+   - Add `## Clarifications` > `### Session YYYY-MM-DD` if missing
+   - Append `- Q: <question> → A: <answer>`
+   - Update appropriate spec section (requirements, stories, data model, success criteria, edge cases)
+   - Replace obsolete statements, save after each integration
+
+6. **Validate**: No duplicates, <=5 questions, no lingering placeholders, consistent terminology.
+
+7. **Report**: Questions asked/answered, path to updated spec, sections touched, coverage summary, next command suggestion.
+
+## Rules
+
+- Never exceed 5 questions | Present one at a time | Never reveal future questions
+- If no ambiguities: report "No critical ambiguities" and suggest proceeding
+- If spec missing: instruct to run `/speckit.specify` first
+- Respect early termination ("done", "stop", "proceed")

templates/commands/compact/constitution.md

@@ -0,0 +1,41 @@
+---
+description: Create or update project constitution from interactive or provided principle inputs.
+handoffs: 
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## Input
+
+```text
+$ARGUMENTS
+```
+
+Consider user input before proceeding (if not empty).
+
+## Workflow
+
+1. **Load** `.specify/memory/constitution.md`. Identify all `[PLACEHOLDER]` tokens. Respect user's desired principle count.
+
+2. **Collect values**: From user input, repo context, or inference. Version: semver (MAJOR=breaking, MINOR=additions, PATCH=clarifications). LAST_AMENDED_DATE=today if changes made.
+
+3. **Draft**: Replace all placeholders with concrete text. Each principle: name + non-negotiable rules + rationale. Governance: amendment procedure + versioning + compliance expectations.
+
+4. **Propagate**: Check alignment with plan-template.md, spec-template.md, tasks-template.md, commands/*.md. Update references if needed.
+
+5. **Sync Report**: Add HTML comment at top: version change, modified/added/removed sections, templates needing updates.
+
+6. **Validate**: No unexplained brackets, version matches report, dates ISO, principles are declarative+testable (MUST/SHOULD not vague "should").
+
+7. **Write** to `.specify/memory/constitution.md`.
+
+8. **Report**: Version + bump rationale, files needing follow-up, suggested commit message.
+
+## Rules
+
+- Use exact template heading hierarchy
+- Single blank line between sections
+- If partial updates: still validate and version-decide
+- Missing info: insert `TODO(<FIELD>): explanation`
+- Always operate on existing file, never create new template