[Bug]: `integration use` drops `ai_skills` from init-options.json for a skills-mode Copilot install

[seiya-koji]

Bug Description

Running specify integration use copilot against a Copilot integration that was installed with --integration-options "--skills" removes "ai_skills": true from .specify/init-options.json.

Steps to Reproduce

# 1. Install Copilot in skills mode
$ specify init proj --integration copilot --integration-options "--skills" --script sh --ignore-agent-tools
$ cd proj

$ cat .specify/init-options.json
{
  "ai": "copilot",
  "ai_skills": true,
  "feature_numbering": "sequential",
  "here": false,
  "integration": "copilot",
  "script": "sh",
  "speckit_version": "0.12.16"
}

$ find .github -type f | sort
.github/skills/speckit-analyze/SKILL.md
.github/skills/speckit-checklist/SKILL.md
...
(10 files total, all SKILL.md under .github/skills/)

# 2. Add an extension as an example — it is installed as skills
$ specify extension add git

$ find .github -type f | sort
.github/skills/speckit-analyze/SKILL.md
...
.github/skills/speckit-git-commit/SKILL.md
.github/skills/speckit-git-feature/SKILL.md
...
(15 files total — the git extension commands were also added as skills)

# 3. Just re-select the same copilot as the default integration
$ specify integration use copilot
✓ Default integration set to copilot.

$ cat .specify/init-options.json
{
  "ai": "copilot",
  "feature_numbering": "sequential",
  "here": false,
  "integration": "copilot",
  "script": "sh",
  "speckit_version": "0.12.16"
}

$ find .github -type f | sort
.github/agents/speckit.git.commit.agent.md
.github/agents/speckit.git.feature.agent.md
...
.github/prompts/speckit.git.commit.prompt.md
.github/prompts/speckit.git.feature.prompt.md
...
.github/skills/speckit-analyze/SKILL.md
.github/skills/speckit-checklist/SKILL.md
...
(the 5 git extension commands were regenerated in the legacy commands layout under agents/ + prompts/, coexisting with the 15 existing skills files)

No switch to another integration is needed — running use copilot alone triggers the bug (a round-trip like use claude → use copilot triggers it as well).

Expected Behavior

use only changes the default integration using the stored configuration, so:

• "ai_skills": true is preserved
• .github keeps its skills layout unchanged

Actual Behavior

• The "ai_skills" key is removed from init-options.json, while integration_settings.copilot.parsed_options in .specify/integration.json still says {"skills": true} — the two files now contradict each other.
• The 5 git extension commands are regenerated as .github/agents/speckit.git.*.agent.md + .github/prompts/speckit.git.*.prompt.md (legacy commands layout), duplicating and coexisting with the existing .github/skills/speckit-git-*/SKILL.md.

Specify CLI Version

0.12.16

AI Agent

GitHub Copilot

Operating System

macOS 26.5.2

Python Version

Python 3.14.3

Error Logs

None

Additional Context

None

[github-actions]

Bug assessment — integration-use-drops-ai-skills: Valid · severity high

---

Bug Assessment: integration use drops ai_skills from init-options.json for a skills-mode Copilot install

• Slug: integration-use-drops-ai-skills
• Created: 2026-07-15T16:02:49Z
• Source: issue [Bug]: integration use drops ai_skills from init-options.json for a skills-mode Copilot install #3550
• Verdict: valid
• Severity: high

Report (summarized)

After initializing a project with specify init --integration copilot --integration-options "--skills" (which records "ai_skills": true in .specify/init-options.json), running specify integration use copilot (even without changing integrations) removes the "ai_skills" key from init-options.json. Additionally, any enabled extensions are re-registered using the legacy .agent.md / .prompt.md layout rather than the skills layout, creating duplicate command files under .github/agents/ and .github/prompts/ alongside the existing .github/skills/ tree.

Symptom

specify integration use copilot silently drops "ai_skills": true from .specify/init-options.json, even though .specify/integration.json still records integration_settings.copilot.parsed_options = {"skills": true}. The two config files are left in a contradictory state, and any subsequent extension re-registration uses the legacy command layout instead of the skills layout.

Reproduction

1. specify init proj --integration copilot --integration-options "--skills" --script sh --ignore-agent-tools
2. cd proj && specify extension add git
3. Confirm cat .specify/init-options.json contains "ai_skills": true and .github/skills/ contains skills files (including git extension skills).
4. Run specify integration use copilot
5. cat .specify/init-options.json — "ai_skills" key is gone.
6. find .github -type f | sort — git extension commands appear as .github/agents/speckit.git.*.agent.md and .github/prompts/speckit.git.*.prompt.md, coexisting with the existing .github/skills/speckit-git-*/SKILL.md files.

Suspected Code Paths

• src/specify_cli/integrations/_helpers.py:281-284 (_update_init_options_for_integration) — checks isinstance(integration, SkillsIntegration) and getattr(integration, "_skills_mode", False), but CopilotIntegration is not a SkillsIntegration subclass and _skills_mode is the class-level default False because setup() was never called during integration use.
• src/specify_cli/integrations/_helpers.py:293-337 (_set_default_integration) — correctly resolves parsed_options = {"skills": True} from stored state (line 231 in _query_commands.py), but does not pass parsed_options into _update_init_options_for_integration, so the skills flag is invisible to that function.
• src/specify_cli/integrations/_query_commands.py:206-251 (integration_use command) — calls _resolve_integration_options(integration, current, key, None) which correctly reads stored parsed_options from .specify/integration.json, but the value is never used to set integration._skills_mode before _update_init_options_for_integration runs.
• src/specify_cli/extensions/__init__.py:1705-1751 (register_enabled_extensions_for_agent) — reads ai_skills from init-options.json to decide skills vs. command layout. Because _update_init_options_for_integration ran first and already dropped ai_skills, the extension re-registration reads False and generates the legacy layout.
• src/specify_cli/integrations/copilot/__init__.py:122 — _skills_mode: bool = False class-level default; only set to True by setup(), which is not invoked during integration use.

Root Cause Hypothesis

_update_init_options_for_integration determines whether to write "ai_skills": true based solely on the runtime integration object (isinstance(integration, SkillsIntegration) or integration._skills_mode). During integration use, the integration object is a freshly retrieved CopilotIntegration() whose _skills_mode is always the class default False — setup() is never called so it is never set to True. Even though parsed_options = {"skills": True} is correctly resolved from the stored integration state and passed through the call chain, it is not forwarded to _update_init_options_for_integration, so the existing ai_skills key is unconditionally removed. The subsequent extension re-registration then reads the now-corrupted init-options.json and picks the wrong (legacy) output layout. Confidence: high — the call graph is unambiguous and the stored parsed_options value is not consulted at the point where ai_skills is written.

Proposed Remediation

Preferred: Pass parsed_options into _update_init_options_for_integration (and thread it through _set_default_integration which already has it). Inside _update_init_options_for_integration, add a third condition:

if (
    isinstance(integration, SkillsIntegration)
    or getattr(integration, "_skills_mode", False)
    or (parsed_options or {}).get("skills")   # ← new
):
    opts["ai_skills"] = True
else:
    opts.pop("ai_skills", None)

This is a minimal, safe change: it only looks at the already-resolved parsed_options dict that the caller derived from stored state, so no extra I/O is needed.

Alternative: Before calling _update_init_options_for_integration, set integration._skills_mode = bool((parsed_options or {}).get("skills")) on the integration instance. This avoids changing _update_init_options_for_integration's signature but mutates the shared integration instance, which is less clean.

Alternative: Add a dedicated helper that reads parsed_options directly from .specify/integration.json inside _update_init_options_for_integration. This avoids signature changes but introduces an extra file read and duplicates the resolution logic already done by the caller.

Files likely to change:

• src/specify_cli/integrations/_helpers.py — primary fix: add parsed_options parameter to _update_init_options_for_integration and update the ai_skills condition; update _set_default_integration to forward parsed_options.
• tests/integrations/test_integration_copilot.py — add regression test: init in skills mode, call integration use copilot, assert ai_skills is still True in init-options.json and no legacy files appear under .github/agents/.

Tests to add or update:

• test_integration_use_preserves_ai_skills_in_skills_mode — call _set_default_integration (or the CLI end-to-end) with a skills-mode copilot integration and parsed_options={"skills": True}; assert init-options.json retains "ai_skills": true.
• test_integration_use_does_not_regenerate_legacy_commands_in_skills_mode — after integration use copilot with a skills-mode project, assert no .agent.md / .prompt.md files exist for installed extension commands.

Risks & Considerations

• The signature change to _update_init_options_for_integration (adding parsed_options) is backwards-compatible — callers that don't supply it default to None (no change to existing non-skills behavior).
• No data migration is needed: projects already broken by this bug can be repaired by re-running specify init or specify integration install copilot --integration-options "--skills". A note in the changelog is advisable.
• The fix does not affect non-Copilot integrations: other integrations do not declare a --skills option, so parsed_options.get("skills") is always falsy for them.
• _CopilotSkillsHelper and SkillsIntegration subclasses continue to work correctly via the existing isinstance branch.

Open Questions

• [NEEDS CLARIFICATION: Should integration use copilot with --force also respect the stored parsed_options, or should --force wipe ai_skills and require the user to explicitly pass --integration-options "--skills" again?]
• [NEEDS CLARIFICATION: The comment in _register_extensions_for_agent (line 393–399) acknowledges that extension skill rendering relies on init-options being updated before the call. Once the ai_skills preservation fix lands, does the ordering guarantee hold, or is an explicit sequencing guard needed?]

Generated by 🐛 Assess Bug from Labeled Issue for issue #3550 · 279.8 AIC · ⌖ 11.3 AIC · ⊞ 31.8K · ◷