[Feature]: add `--allow-model-invocation` flag for agent-orchestrated workflows

[srobroek]

Problem Statement

Since v0.4.5 (#2051), specify init --ai claude installs speckit commands as native skills under .claude/skills/ with disable-model-invocation: true hardcoded in build_skill_frontmatter() (agents.py). This prevents Claude from invoking speckit skills via the Skill tool — only the user can trigger them manually via /speckit-specify, /speckit-plan, etc.

This is a reasonable default for most users (prevents Claude from auto-triggering side-effect-heavy workflow steps). However, it breaks agent-orchestrated speckit workflows where Claude is instructed (via rules/steering files) to invoke speckit skills programmatically as part of a multi-step pipeline.

Currently this only affects --ai claude (the flag is inside an if agent_name == "claude" guard in build_skill_frontmatter()), but other skill-based agents may benefit from the same override if they support model-initiated invocation.

Note: #2081 refactored the injection into _inject_frontmatter_flag() but kept the hardcoded True behavior.

Proposed Solution

Add an --allow-model-invocation flag to specify init that sets disable-model-invocation: false (or omits the key entirely) in generated SKILL.md frontmatter.

Persist the choice in init-options.json so it survives re-init and is respected by specify extension add:

{
  "ai_skills": true,
  "allow_model_invocation": true
}

Implementation sketch:

1. specify init: accept --allow-model-invocation flag, persist to init-options.json
2. build_skill_frontmatter() in agents.py: read the option from init-options.json (via load_init_options()) and conditionally set the flag
3. specify extension add: already calls build_skill_frontmatter() via CommandRegistrar, so it would inherit the behavior automatically if the method reads init-options.json

Affected code:

• build_skill_frontmatter() in src/specify_cli/agents.py — where the flag is hardcoded
• _inject_frontmatter_flag() added in Remove template version info from CLI, fix Claude user-invocable, cleanup dead code #2081 — the shared helper that injects the flag post-setup
• init() in src/specify_cli/__init__.py — to accept and persist the new option
• load_init_options() — already used by resolve_skill_placeholders(), same pattern

Alternatives Considered

Manual sed after every init/extension install:

sed -i '' 's/disable-model-invocation: true/disable-model-invocation: false/' .claude/skills/speckit-*/SKILL.md

This works but must be re-applied after every specify init --force or specify extension add that regenerates skills. Not sustainable across many projects.

Keeping legacy .claude/commands/ alongside skills: Duplicates files and they drift over time.

Component

Specify CLI (initialization, commands)

AI Agent

Claude Code

Use Cases

1. Users who build structured orchestration flows in their Claude Code steering (e.g., rules that map speckit steps 1–17 to specific skills and have Claude invoke them sequentially) cannot use the native skills path — the Skill tool cannot see or invoke skills with disable-model-invocation: true.
2. Teams that want Claude to drive the speckit workflow autonomously (with user approval gates at key steps) while keeping the native skills format.
3. Extension authors who want their extensions to be invocable by the model as part of automated pipelines.

Acceptance Criteria

• specify init --ai claude --allow-model-invocation generates SKILL.md files with disable-model-invocation: false
• The flag is persisted in init-options.json as allow_model_invocation: true
• specify init --force respects the persisted option
• specify extension add respects the persisted option when generating skills
• Default behavior (no flag) remains unchanged (disable-model-invocation: true)
• Documentation is updated

Additional Context

This issue was authored with assistance from Claude Code.