💫 Toolkit to help you get started with SDD or any other process!
feat(claude): run /analyze in a forked subagent (#2511)
Ed Harrod98ee02a98b44
diff --git a/src/specify_cli/integrations/claude/__init__.py b/src/specify_cli/integrations/claude/__init__.pyindex 6a7d483db..0df388172 100644--- a/src/specify_cli/integrations/claude/__init__.py+++ b/src/specify_cli/integrations/claude/__init__.py@@ -2,11 +2,9 @@from __future__ import annotations-from pathlib import Pathfrom typing import Anyfrom ..base import SkillsIntegration-from ..manifest import IntegrationManifestfrom ..._utils import dump_frontmatter# Mapping of command template stem → argument-hint text shown inline@@ -23,6 +21,15 @@ ARGUMENT_HINTS: dict[str, str] = {"taskstoissues": "Optional filter or label for GitHub issues",}+# Per-command frontmatter overrides for skills that should run in a forked+# subagent context. Read-only analysis commands are good candidates: the+# heavy reads (spec/plan/tasks artefacts) collapse to a short summary,+# so isolating them keeps the main conversation context clean.+# See https://code.claude.com/docs/en/skills#run-skills-in-a-subagent+FORK_CONTEXT_COMMANDS: dict[str, dict[str, str]] = {+ "analyze": {"context": "fork", "agent": "general-purpose"},+}+class ClaudeIntegration(SkillsIntegration):"""Integration for Claude Code skills."""@@ -148,50 +155,47 @@ class ClaudeIntegration(SkillsIntegration):out.append(line)return "".join(out)- def post_process_skill_content(self, content: str) -> str:- """Inject Claude-specific frontmatter flags and hook notes."""- updated = super().post_process_skill_content(content)- updated = self._inject_frontmatter_flag(updated, "user-invocable")- updated = self._inject_frontmatter_flag(updated, "disable-model-invocation", "false")- return updated+ @staticmethod+ def _skill_stem_from_content(content: str) -> str | None:+ """Derive the command stem (e.g. ``analyze``) from a skill's frontmatter.- def setup(- self,- project_root: Path,- manifest: IntegrationManifest,- parsed_options: dict[str, Any] | None = None,- **opts: Any,- ) -> list[Path]:- """Install Claude skills, then inject argument-hints."""- created = super().setup(project_root, manifest, parsed_options, **opts)-- skills_dir = self.skills_dest(project_root).resolve()-- for path in created:- # Only touch SKILL.md files under the skills directory- try:- path.resolve().relative_to(skills_dir)- except ValueError:- continue- if path.name != "SKILL.md":+ Reads the ``name:`` field of the first frontmatter block and strips+ the ``speckit-`` prefix. Returns ``None`` when no name is present.+ """+ dash_count = 0+ for line in content.splitlines():+ stripped = line.rstrip("\r\n")+ if stripped == "---":+ dash_count += 1+ if dash_count == 2:+ breakcontinue+ if dash_count == 1 and stripped.startswith("name:"):+ name = stripped[len("name:"):].strip().strip('"').strip("'")+ if name.startswith("speckit-"):+ return name[len("speckit-"):]+ return name or None+ return None- content_bytes = path.read_bytes()- content = content_bytes.decode("utf-8")+ def post_process_skill_content(self, content: str) -> str:+ """Inject Claude-specific frontmatter flags, hook notes, and any+ per-command frontmatter.- updated = content+ Applied by every skill-generation path (setup, presets, extensions),+ so command-specific frontmatter (argument-hint, fork context) stays+ consistent however the SKILL.md was produced.+ """+ updated = super().post_process_skill_content(content)+ updated = self._inject_frontmatter_flag(updated, "user-invocable")+ updated = self._inject_frontmatter_flag(updated, "disable-model-invocation", "false")- # Inject argument-hint if available for this skill- skill_dir_name = path.parent.name # e.g. "speckit-plan"- stem = skill_dir_name- if stem.startswith("speckit-"):- stem = stem[len("speckit-"):]+ stem = self._skill_stem_from_content(updated)+ if stem:hint = ARGUMENT_HINTS.get(stem, "")if hint:updated = self.inject_argument_hint(updated, hint)-- if updated != content:- path.write_bytes(updated.encode("utf-8"))- self.record_file_in_manifest(path, project_root, manifest)-- return created+ fork_config = FORK_CONTEXT_COMMANDS.get(stem)+ if fork_config:+ for key, value in fork_config.items():+ updated = self._inject_frontmatter_flag(updated, key, value)+ return updateddiff --git a/tests/integrations/test_integration_claude.py b/tests/integrations/test_integration_claude.pyindex e8350114a..c7ecef95d 100644--- a/tests/integrations/test_integration_claude.py+++ b/tests/integrations/test_integration_claude.py@@ -10,7 +10,7 @@ import yamlfrom specify_cli.integrations import INTEGRATION_REGISTRY, get_integrationfrom specify_cli.integrations.base import IntegrationBase, SkillsIntegration-from specify_cli.integrations.claude import ARGUMENT_HINTS+from specify_cli.integrations.claude import ARGUMENT_HINTS, FORK_CONTEXT_COMMANDSfrom specify_cli.integrations.manifest import IntegrationManifest@@ -536,6 +536,102 @@ class TestClaudeDisableModelInvocation:assert agy.post_process_skill_content(content) == content+class TestClaudeForkContext:+ """Verify context: fork is injected only for commands listed in FORK_CONTEXT_COMMANDS."""++ def test_analyze_skill_runs_in_forked_subagent(self, tmp_path):+ """speckit-analyze must opt into context: fork + agent."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ i.setup(tmp_path, m, script_type="sh")+ analyze_skill = tmp_path / ".claude/skills/speckit-analyze/SKILL.md"+ assert analyze_skill.exists()+ content = analyze_skill.read_text(encoding="utf-8")+ parts = content.split("---", 2)+ parsed = yaml.safe_load(parts[1])+ assert parsed.get("context") == "fork"+ assert parsed.get("agent") == "general-purpose"++ def test_other_skills_do_not_fork(self, tmp_path):+ """Skills not in FORK_CONTEXT_COMMANDS must not get context: fork."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ created = i.setup(tmp_path, m, script_type="sh")+ skill_files = [f for f in created if f.name == "SKILL.md"]+ for f in skill_files:+ stem = f.parent.name+ if stem.startswith("speckit-"):+ stem = stem[len("speckit-"):]+ if stem in FORK_CONTEXT_COMMANDS:+ continue+ content = f.read_text(encoding="utf-8")+ parts = content.split("---", 2)+ parsed = yaml.safe_load(parts[1])+ assert "context" not in parsed, (+ f"{f.parent.name}: must not have context frontmatter"+ )+ assert "agent" not in parsed, (+ f"{f.parent.name}: must not have agent frontmatter"+ )++ def test_fork_flags_inside_frontmatter(self, tmp_path):+ """context/agent must appear in the frontmatter, not in the body."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ i.setup(tmp_path, m, script_type="sh")+ analyze_skill = tmp_path / ".claude/skills/speckit-analyze/SKILL.md"+ content = analyze_skill.read_text(encoding="utf-8")+ parts = content.split("---", 2)+ assert len(parts) >= 3+ frontmatter = parts[1]+ body = parts[2]+ assert "context: fork" in frontmatter+ assert "agent: general-purpose" in frontmatter+ assert "context: fork" not in body+ assert "agent: general-purpose" not in body++ def test_fork_injection_idempotent(self, tmp_path):+ """Re-running setup must not duplicate the fork frontmatter keys."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ i.setup(tmp_path, m, script_type="sh")+ i.setup(tmp_path, m, script_type="sh")+ analyze_skill = tmp_path / ".claude/skills/speckit-analyze/SKILL.md"+ content = analyze_skill.read_text(encoding="utf-8")+ assert content.count("context: fork") == 1+ assert content.count("agent: general-purpose") == 1++ def test_fork_context_injected_via_post_process(self):+ """Preset/extension generators call post_process_skill_content directly,+ bypassing setup(); fork context must be injected there too."""+ i = get_integration("claude")+ content = '---\nname: "speckit-analyze"\ndescription: "x"\n---\n\nBody\n'+ result = i.post_process_skill_content(content)+ parsed = yaml.safe_load(result.split("---", 2)[1])+ assert parsed.get("context") == "fork"+ assert parsed.get("agent") == "general-purpose"+ assert parsed.get("argument-hint") == ARGUMENT_HINTS["analyze"]++ def test_post_process_no_fork_for_other_skills(self):+ """Skills not in FORK_CONTEXT_COMMANDS must not gain context/agent."""+ i = get_integration("claude")+ content = '---\nname: "speckit-plan"\ndescription: "x"\n---\n\nBody\n'+ result = i.post_process_skill_content(content)+ parsed = yaml.safe_load(result.split("---", 2)[1])+ assert "context" not in parsed+ assert "agent" not in parsed++ def test_post_process_fork_idempotent(self):+ """Re-running post_process must not duplicate fork frontmatter keys."""+ i = get_integration("claude")+ content = '---\nname: "speckit-analyze"\ndescription: "x"\n---\n\nBody\n'+ once = i.post_process_skill_content(content)+ twice = i.post_process_skill_content(once)+ assert once == twice+ assert twice.count("context: fork") == 1+ assert twice.count("agent: general-purpose") == 1++class TestClaudeHookCommandNote:"""Verify dot-to-hyphen normalization note is injected in hook sections."""