💫 Toolkit to help you get started with SDD or any other process!
fix(claude): stop forking /speckit-analyze to prevent long-session freezes (#3188)
Manfred Riemc49966da4d68
diff --git a/src/specify_cli/integrations/claude/__init__.py b/src/specify_cli/integrations/claude/__init__.pyindex 0df388172..41d5b14b1 100644--- a/src/specify_cli/integrations/claude/__init__.py+++ b/src/specify_cli/integrations/claude/__init__.py@@ -22,13 +22,17 @@ ARGUMENT_HINTS: dict[str, str] = {}# 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"},-}+# subagent context. See https://code.claude.com/docs/en/skills#run-skills-in-a-subagent+#+# This is intentionally empty. ``analyze`` was previously forked (added in+# #2511) on the assumption that its heavy reads collapse to a short summary,+# but in practice ``/speckit-analyze`` returns a 300-500 line report that is+# injected back into the main conversation. In long sessions each subsequent+# fork inherits that growing context, compounding overhead until the chat+# freezes (#3185). Until a command genuinely returns a compact result, no+# command opts into ``context: fork``. The injection mechanism below stays in+# place so a future command can be added here when that holds true.+FORK_CONTEXT_COMMANDS: dict[str, dict[str, str]] = {}class ClaudeIntegration(SkillsIntegration):diff --git a/tests/integrations/test_integration_claude.py b/tests/integrations/test_integration_claude.pyindex c7ecef95d..8f96527b2 100644--- a/tests/integrations/test_integration_claude.py+++ b/tests/integrations/test_integration_claude.py@@ -539,8 +539,16 @@ class TestClaudeDisableModelInvocation: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."""+ def test_no_commands_fork_by_default(self):+ """FORK_CONTEXT_COMMANDS is empty: no command opts into context: fork.++ ``analyze`` was removed (#3185) because its verbose report defeated the+ purpose of forking and compounded context overhead across repeated runs.+ """+ assert FORK_CONTEXT_COMMANDS == {}++ def test_analyze_skill_does_not_fork(self, tmp_path):+ """speckit-analyze must run in the main session, not a forked subagent (#3185)."""i = get_integration("claude")m = IntegrationManifest("claude", tmp_path)i.setup(tmp_path, m, script_type="sh")@@ -549,10 +557,10 @@ class TestClaudeForkContext: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"+ assert "context" not in parsed+ assert "agent" not in parsed- def test_other_skills_do_not_fork(self, tmp_path):+ def test_no_skills_fork(self, tmp_path):"""Skills not in FORK_CONTEXT_COMMANDS must not get context: fork."""i = get_integration("claude")m = IntegrationManifest("claude", tmp_path)@@ -574,60 +582,39 @@ class TestClaudeForkContext: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."""+ def test_post_process_no_fork_for_skills(self):+ """With FORK_CONTEXT_COMMANDS empty, post_process must not add context/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"- 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."""+ for name in ("speckit-analyze", "speckit-plan"):+ content = f'---\nname: "{name}"\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_fork_mechanism_injects_when_configured(self, monkeypatch):+ """The injection mechanism still works for any command added to+ FORK_CONTEXT_COMMANDS, even though none ships enabled by default."""+ import specify_cli.integrations.claude as claude_mod++ monkeypatch.setitem(+ claude_mod.FORK_CONTEXT_COMMANDS,+ "analyze",+ {"context": "fork", "agent": "general-purpose"},+ )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])+ parts = result.split("---", 2)+ parsed = yaml.safe_load(parts[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+ # Flags must land in the frontmatter, not the body.+ assert "context: fork" in parts[1]+ assert "context: fork" not in parts[2]+ # Re-running must not duplicate the injected keys.+ twice = i.post_process_skill_content(result)+ assert result == twiceassert twice.count("context: fork") == 1assert twice.count("agent: general-purpose") == 1