fix(claude): create CLAUDE.md after constitution, not during setup()

The previous placement called ensure_claude_md() from
ClaudeIntegration.setup(), which runs BEFORE
ensure_constitution_from_template() in the init() flow. Since the
creation is gated on the constitution file existing, CLAUDE.md was
silently skipped on a fresh `specify init --ai claude` — the exact
scenario this PR is meant to fix.

The previous tests masked this bug by pre-creating the constitution
file before invoking setup() or the CLI, so they never exercised the
real ordering.

Fix:
- Add a generic `ensure_context_file(project_root, manifest)` hook on
  IntegrationBase (default no-op) that runs after the constitution is
  in place. Integrations needing a root context file (e.g. CLAUDE.md)
  override it.
- Move the CLAUDE.md creation from ClaudeIntegration.setup() into
  ClaudeIntegration.ensure_context_file(), which also records the file
  in the integration manifest.
- Call resolved_integration.ensure_context_file(...) from init()
  immediately after ensure_constitution_from_template(...), and
  re-save the manifest if a file was created.

Tests:
- Rewrite the CLI end-to-end test to start from a truly empty project
  (no pre-created constitution) so it fails if the ordering regresses.
  It now asserts that BOTH the constitution and CLAUDE.md exist.
- Add a test proving setup() alone does NOT create CLAUDE.md.
- Update the three unit tests to call ensure_context_file directly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: arun-gupta

src/specify_cli/__init__.py

@@ -1191,6 +1191,12 @@ def init(
 
             ensure_constitution_from_template(project_path, tracker=tracker)
 
+            # Post-constitution hook: let the integration create its root
+            # context file (e.g. CLAUDE.md) now that the constitution exists.
+            context_file = resolved_integration.ensure_context_file(project_path, manifest)
+            if context_file is not None:
+                manifest.save()
+
             if not no_git:
                 tracker.start("git")
                 git_messages = []

src/specify_cli/integrations/base.py

@@ -89,6 +89,21 @@ def options(cls) -> list[IntegrationOption]:
         """Return options this integration accepts. Default: none."""
         return []
 
+    def ensure_context_file(
+        self,
+        project_root: Path,
+        manifest: "IntegrationManifest",
+    ) -> Path | None:
+        """Post-constitution hook: create the agent's root context file.
+
+        Called from ``init()`` after ``ensure_constitution_from_template``
+        has run, so the constitution is guaranteed to exist when this is
+        invoked. Default: no-op. Integrations that need a root file
+        (e.g. ``CLAUDE.md``) should override this. Returns the created
+        path (to be recorded in the manifest) or ``None``.
+        """
+        return None
+
     # -- Primitives — building blocks for setup() -------------------------
 
     def shared_commands_dir(self) -> Path | None:

src/specify_cli/integrations/claude/__init__.py

@@ -148,21 +148,26 @@ def _inject_frontmatter_flag(content: str, key: str, value: str = "true") -> str
             out.append(line)
         return "".join(out)
 
-    @classmethod
-    def ensure_claude_md(cls, project_root: Path) -> Path | None:
-        """Create a minimal root context file (``CLAUDE.md``) if missing.
-
-        Claude Code expects ``context_file`` at the project root; this file
-        acts as a bridge to the constitution at ``CONSTITUTION_REL_PATH``.
-        Returns the path if created, ``None`` otherwise.
+    def ensure_context_file(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+    ) -> Path | None:
+        """Create a minimal root ``CLAUDE.md`` if missing.
+
+        Called from ``init()`` AFTER ``ensure_constitution_from_template``
+        so the constitution file is guaranteed to exist at this point.
+        This file acts as a bridge to the constitution at
+        ``CONSTITUTION_REL_PATH``. Returns the created path or ``None``
+        (existing file, or prerequisites not met).
         """
         from specify_cli import CONSTITUTION_REL_PATH
 
-        if cls.context_file is None:
+        if self.context_file is None:
             return None
 
         constitution = project_root / CONSTITUTION_REL_PATH
-        context_file = project_root / cls.context_file
+        context_file = project_root / self.context_file
         if context_file.exists() or not constitution.exists():
             return None
 
@@ -185,6 +190,7 @@ def ensure_claude_md(cls, project_root: Path) -> Path | None:
             "Do not infer. Do not proceed.\n\n"
         )
         context_file.write_text(content, encoding="utf-8")
+        self.record_file_in_manifest(context_file, project_root, manifest)
         return context_file
 
     def setup(
@@ -194,15 +200,9 @@ def setup(
         parsed_options: dict[str, Any] | None = None,
         **opts: Any,
     ) -> list[Path]:
-        """Install Claude skills, create CLAUDE.md, then inject frontmatter flags and argument-hints."""
+        """Install Claude skills, then inject user-invocable, disable-model-invocation, and argument-hint."""
         created = super().setup(project_root, manifest, parsed_options, **opts)
 
-        # Create root CLAUDE.md pointing to the constitution
-        claude_md = self.ensure_claude_md(project_root)
-        if claude_md is not None:
-            created.append(claude_md)
-            self.record_file_in_manifest(claude_md, project_root, manifest)
-
         # Post-process generated skill files
         skills_dir = self.skills_dest(project_root).resolve()
 

tests/integrations/test_integration_claude.py

@@ -304,35 +304,36 @@ def test_claude_preset_creates_new_skill_without_commands_dir(self, tmp_path):
 
 
 class TestClaudeMdCreation:
-    """Verify that CLAUDE.md is created during setup when constitution exists."""
+    """Verify that CLAUDE.md is created after the constitution is in place."""
 
-    def test_setup_creates_claude_md_when_constitution_exists(self, tmp_path):
+    def test_ensure_context_file_creates_claude_md_when_constitution_exists(self, tmp_path):
         integration = get_integration("claude")
         constitution = tmp_path / ".specify" / "memory" / "constitution.md"
         constitution.parent.mkdir(parents=True, exist_ok=True)
         constitution.write_text("# Constitution\n", encoding="utf-8")
 
         manifest = IntegrationManifest("claude", tmp_path)
-        created = integration.setup(tmp_path, manifest, script_type="sh")
+        created = integration.ensure_context_file(tmp_path, manifest)
 
         claude_md = tmp_path / "CLAUDE.md"
         assert claude_md.exists()
+        assert created == claude_md
         content = claude_md.read_text(encoding="utf-8")
         assert ".specify/memory/constitution.md" in content
-        assert claude_md in created
         for section in EXPECTED_CLAUDE_MD_SECTIONS:
             assert section in content, f"missing section header: {section}"
         for command in EXPECTED_CLAUDE_MD_COMMANDS:
             assert f"`{command}`" in content, f"missing command: {command}"
 
-    def test_setup_skips_claude_md_when_constitution_missing(self, tmp_path):
+    def test_ensure_context_file_skips_when_constitution_missing(self, tmp_path):
         integration = get_integration("claude")
         manifest = IntegrationManifest("claude", tmp_path)
-        integration.setup(tmp_path, manifest, script_type="sh")
+        result = integration.ensure_context_file(tmp_path, manifest)
 
+        assert result is None
         assert not (tmp_path / "CLAUDE.md").exists()
 
-    def test_setup_preserves_existing_claude_md(self, tmp_path):
+    def test_ensure_context_file_preserves_existing_claude_md(self, tmp_path):
         integration = get_integration("claude")
         constitution = tmp_path / ".specify" / "memory" / "constitution.md"
         constitution.parent.mkdir(parents=True, exist_ok=True)
@@ -342,37 +343,50 @@ def test_setup_preserves_existing_claude_md(self, tmp_path):
         claude_md.write_text("# Custom content\n", encoding="utf-8")
 
         manifest = IntegrationManifest("claude", tmp_path)
-        integration.setup(tmp_path, manifest, script_type="sh")
+        result = integration.ensure_context_file(tmp_path, manifest)
 
+        assert result is None
         assert claude_md.read_text(encoding="utf-8") == "# Custom content\n"
 
-    def test_init_cli_creates_claude_md(self, tmp_path):
+    def test_setup_does_not_create_claude_md_without_constitution(self, tmp_path):
+        """``setup()`` alone must not create CLAUDE.md — that's the context-file hook's job,
+        and it only runs after the constitution exists."""
+        integration = get_integration("claude")
+        manifest = IntegrationManifest("claude", tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+        assert not (tmp_path / "CLAUDE.md").exists()
+
+    def test_init_cli_creates_claude_md_on_fresh_project(self, tmp_path):
+        """End-to-end: a fresh ``specify init --ai claude`` must produce
+        BOTH the constitution AND CLAUDE.md, proving the init-flow ordering
+        is correct (context file created after constitution)."""
         from typer.testing import CliRunner
         from specify_cli import app
 
         project = tmp_path / "claude-md-test"
         project.mkdir()
 
-        # Pre-create constitution so ensure_claude_md has something to gate on
-        constitution = project / ".specify" / "memory" / "constitution.md"
-        constitution.parent.mkdir(parents=True, exist_ok=True)
-        constitution.write_text("# Constitution\n", encoding="utf-8")
-
         old_cwd = os.getcwd()
         try:
             os.chdir(project)
             runner = CliRunner()
             result = runner.invoke(
                 app,
-                ["init", "--here", "--force", "--ai", "claude", "--script", "sh", "--no-git", "--ignore-agent-tools"],
+                ["init", "--here", "--ai", "claude", "--script", "sh", "--no-git", "--ignore-agent-tools"],
                 catch_exceptions=False,
             )
         finally:
             os.chdir(old_cwd)
 
         assert result.exit_code == 0, result.output
+
+        # Constitution must have been created by the init flow (not pre-seeded)
+        constitution = project / ".specify" / "memory" / "constitution.md"
+        assert constitution.exists(), "init did not create the constitution"
+
+        # CLAUDE.md must exist and point at the constitution
         claude_md = project / "CLAUDE.md"
-        assert claude_md.exists()
+        assert claude_md.exists(), "init did not create CLAUDE.md"
         content = claude_md.read_text(encoding="utf-8")
         assert ".specify/memory/constitution.md" in content
         for section in EXPECTED_CLAUDE_MD_SECTIONS: