docs: update references from "Supported AI Agents" to "Supported AI T… by MUHAMMEDHAFEEZ · Pull Request #1987 · github/spec-kit

MUHAMMEDHAFEEZ · 2026-03-26T21:08:39Z

Claude Code, Cursor, Gemini CLI, and similar entries in the table are AI coding tools/assistants, not autonomous agents. Renaming the section to "Supported AI Tools" is more accurate.

Updated files:

README.md: section header, TOC link, and table column header
AGENTS.md: reference to the README section
docs/upgrade.md: anchor link (#-supported-ai-agents → #-supported-ai-tools)

Description

Testing

Tested locally with uv run specify --help
Ran existing tests with uv sync && uv run pytest
Tested with a sample project (if applicable)

…ools" Claude Code, Cursor, Gemini CLI, and similar entries in the table are AI coding tools/assistants, not autonomous agents. Renaming the section to "Supported AI Tools" is more accurate. Updated files: - README.md: section header, TOC link, and table column header - AGENTS.md: reference to the README section - docs/upgrade.md: anchor link (#-supported-ai-agents → #-supported-ai-tools)

Copilot

Pull request overview

Renames documentation references from “Supported AI Agents” to “Supported AI Tools” to better reflect that the integrations listed are coding tools/assistants rather than autonomous agents.

Changes:

Updated README section title, TOC entry, and table column header to use “Supported AI Tools”.
Updated docs/upgrade.md to link to the new README anchor.
Updated AGENTS.md instructions to reference the renamed README section.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/upgrade.md	Updates the upgrade guide link text/anchor to “Supported AI Tools”.
README.md	Renames the “Supported AI Agents” section and table header to “Supported AI Tools”, and updates the TOC entry accordingly.
AGENTS.md	Updates contributor instructions to refer to the renamed “Supported AI Tools” section in README.

Comments suppressed due to low confidence (1)

AGENTS.md:112

This step now refers to “Supported AI Tools”, but the bullet points below still say “agent” (and the surrounding instructions in this step are about adding a new agent). Please make the terminology consistent (either keep everything as “agent” or update the bullets to “tool” to match the renamed section).

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
- Add any relevant notes about the agent's implementation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

docs/upgrade.md

MUHAMMEDHAFEEZ

.

MUHAMMEDHAFEEZ · 2026-03-26T22:40:31Z

@mnriem

Introduce compact page templates (~74% smaller) Introduce compact command templates (~78% smaller) Add --format option to specify init (supports compact and markdown) Implement resolve_template_path() to handle format-based template selection Add _get_template_format() in agents to auto-load correct command templates Persist selected format in .specify/init-options.json Enable automatic usage of compact templates across scaffold and commands Token usage reduced from 105.9KB → 23.1KB (~78% reduction) Usage: specify init <project> --ai claude --format compact Default remains markdown

specify init <project> --ai claude --format compact Default remains markdown

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

AGENTS.md:112

This section was renamed to “Supported AI Tools”, but the bullets immediately below still refer to “agent” (e.g., “Add the new agent to the table…”). Update the bullets to consistently use “tool” terminology.

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
- Add any relevant notes about the agent's implementation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T21:42:03Z

src/specify_cli/__init__.py

+    # 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"


ensure_constitution_from_template() chooses the compact template based on .specify/init-options.json, but init() calls ensure_constitution_from_template() before save_init_options() writes that file. On a fresh init, load_init_options() returns {}, so the compact constitution template will never be selected even when --format compact was passed. Consider passing the selected template_format into ensure_constitution_from_template() (or saving init options earlier) so the first init honors the CLI flag; adding a regression test would help.

@copilot apply changes based on this feedback

Copilot · 2026-03-31T21:42:03Z

docs/upgrade.md

 ```

-Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Agents](../README.md#-supported-ai-agents)
+Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools)


The placeholder name is inconsistent: the command examples now use <your-tool> but the following sentence still says Replace <your-agent>.... Update this to match the new placeholder (<your-tool>) and terminology (tool vs agent) to avoid confusion.

Suggested change

Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools)

Replace `<your-tool>` with your AI tool. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools)

Copilot · 2026-03-31T21:42:03Z

src/specify_cli/__init__.py

    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)"),
 ):


The PR title/description indicate a docs-only rename (“Supported AI Agents” → “Supported AI Tools”), but this change introduces a new --format init option and template-format selection logic (plus new compact templates/commands). Consider updating the PR title/description to reflect the functional change, or splitting the format feature into a separate PR for easier review/release notes.

@copilot apply changes based on this feedback

src/specify_cli/__init__.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

MUHAMMEDHAFEEZ · 2026-03-31T21:44:14Z

@copilot apply changes based on the comments in this thread

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (2)

AGENTS.md:112

The section header was renamed to “Supported AI Tools”, but the follow-up bullets still refer to “agent” (e.g., “Add the new agent to the table…”). Update these bullets to consistently use “tool” terminology.

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
- Add any relevant notes about the agent's implementation

README.md:525

This bullet list was updated to say “AI coding tool”, but the next sentence still says “If you encounter issues with an agent…”. For consistency with the rename, update that sentence to refer to the AI tool/assistant instead of “agent”.

- **Linux/macOS/Windows**
- [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)

If you encounter issues with an agent, please open an issue so we can refine the integration.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T21:51:23Z

src/specify_cli/__init__.py

+    # 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"


ensure_constitution_from_template() selects the compact template by reading .specify/init-options.json, but init() writes that file later (after this function is called). On a fresh init with --format compact, load_init_options() will return {} and the compact constitution template will not be used. Consider passing the chosen template_format into this function (or saving init options before calling it) so first-time initialization honors the CLI flag.

Copilot · 2026-03-31T21:51:23Z

src/specify_cli/__init__.py

                    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)


In scaffold_from_core_pack(), compact page templates are copied into tmp/templates/compact/, but compact command templates (templates/commands/compact/) are never copied into the temp repo layout (only top-level files under templates/commands/ are copied). This means offline scaffolding can’t generate/include the compact command variants even when projects later request them via init-options format=compact. Consider also copying commands_dir/compact into tmp/templates/commands/compact during the offline scaffolding setup.

Copilot · 2026-03-31T21:51:23Z

src/specify_cli/__init__.py

    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)"),
 ):


The PR title/description are about a docs-only rename (“Supported AI Agents” → “Supported AI Tools”), but this change adds a new --format init option and introduces compact template selection logic. This is a functional change that likely needs to be reflected in the PR metadata/release notes, or split into a separate PR to keep the docs change isolated.

Copilot · 2026-03-31T21:51:23Z

templates/commands/compact/tasks.md

+   - Extract tech stack/structure from plan.md, user stories (P1,P2,P3) from spec.md
+   - Map entities from data-model.md and contracts to user stories
+   - Organize by user story for independent implementation/testing
+   - Use `templates/tasks-template.md` structure


This compact command template still instructs the agent to use templates/tasks-template.md, which is the verbose template path. If the intent is to generate compact artifacts when --format compact is selected, this should point at the compact variant (templates/compact/tasks-template.md) or otherwise use the same template-resolution logic the CLI uses.

Suggested change

- Use `templates/tasks-template.md` structure

- Use `templates/compact/tasks-template.md` structure

Copilot · 2026-03-31T21:51:24Z

templates/commands/compact/specify.md

+
+2. **Create feature branch**: Run script with `--short-name` and `--json`. Check `.specify/init-options.json` for `branch_numbering` - add `--timestamp` if "timestamp". Never pass `--number`. Run script only once. Parse BRANCH_NAME and SPEC_FILE from JSON output.
+
+3. **Load** `templates/spec-template.md` for structure.


This compact specify command still says to load templates/spec-template.md (the verbose template). If compact mode is meant to drive compact specs, consider referencing templates/compact/spec-template.md (or using a format-aware template resolver) so the generated spec matches the selected format.

Suggested change

3. **Load** `templates/spec-template.md` for structure.

3. **Load** `templates/compact/spec-template.md` for structure.

Copilot · 2026-03-31T21:51:24Z

src/specify_cli/__init__.py

+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


resolve_template_path() is introduced here but doesn’t appear to be used anywhere in src/ (only its definition exists). If this is intended for upcoming work, consider either wiring it into the places now doing format-specific template selection (e.g., ensure_constitution_from_template) or removing it until there’s a call site, to avoid carrying unused API surface.

Copilot AI review requested due to automatic review settings March 26, 2026 21:08

MUHAMMEDHAFEEZ requested a review from mnriem as a code owner March 26, 2026 21:08

Copilot started reviewing on behalf of MUHAMMEDHAFEEZ March 26, 2026 21:09 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

README.md Show resolved Hide resolved

docs/upgrade.md Show resolved Hide resolved

docs: update references from "AI coding agent" to "AI coding tool"

2048790

MUHAMMEDHAFEEZ commented Mar 26, 2026

View reviewed changes

MUHAMMEDHAFEEZ added 2 commits March 31, 2026 23:35

Usage:

f4c4525

specify init <project> --ai claude --format compact Default remains markdown

Copilot AI review requested due to automatic review settings March 31, 2026 21:35

Copilot started reviewing on behalf of MUHAMMEDHAFEEZ March 31, 2026 21:36 View session

Delete .claude directory

c7f382a

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Update src/specify_cli/__init__.py

6f71c10

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 31, 2026 21:44

Copilot started reviewing on behalf of MUHAMMEDHAFEEZ March 31, 2026 21:44 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

	Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools)
	Replace `<your-tool>` with your AI tool. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools)

	- Use `templates/tasks-template.md` structure
	- Use `templates/compact/tasks-template.md` structure


		2. Create feature branch: Run script with `--short-name` and `--json`. Check `.specify/init-options.json` for `branch_numbering` - add `--timestamp` if "timestamp". Never pass `--number`. Run script only once. Parse BRANCH_NAME and SPEC_FILE from JSON output.

		3. Load `templates/spec-template.md` for structure.

	3. Load `templates/spec-template.md` for structure.
	3. Load `templates/compact/spec-template.md` for structure.

Conversation

MUHAMMEDHAFEEZ commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

MUHAMMEDHAFEEZ left a comment

Choose a reason for hiding this comment

Uh oh!

MUHAMMEDHAFEEZ commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

MUHAMMEDHAFEEZ Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

MUHAMMEDHAFEEZ Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MUHAMMEDHAFEEZ commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MUHAMMEDHAFEEZ commented Mar 26, 2026 •

edited

Loading