spawn-cli 0.1.3__tar.gz → 0.1.5__tar.gz

spawn_cli-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spawn-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spawn_cli-0.1.5/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: spawn-cli
+Version: 0.1.5
+Summary: A minimal installable Python CLI package.
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ruamel.yaml>=0.18
+Requires-Dist: filelock>=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Dynamic: license-file
+
+## What is Spawn?
+
+Spawn is a framework for building **AIDD** (AI-driven development) methodologies. It supports both **authoring** methodologies and **applying** them in a project. Within a single repository you can use **several** AIDD methodologies in a coherent way—shared navigation, skills, rules, and tooling stay aligned instead of competing ad hoc setups.
+
+## What is spawn-cli?
+
+**spawn-cli** is the utility that manages methodologies installed in your project. In Spawn terminology those packs are **extensions**: versioned content that usually lives in a **Git** repository. The CLI **instantiates** instruction files, process descriptions, rules, agent skills, and wires their behavior together (navigation, IDE-facing outputs, optional lifecycle hooks). Extensions can also declare **MCP servers**, **agent-ignore** patterns, **git-ignore** entries, and similar integration points—see [`spec/design/extension-author-guide.md`](spec/design/extension-author-guide.md).
+
+### How spawn-cli keeps methodologies coherent
+
+Several methodologies in one repo stay aligned because Spawn maintains **one shared navigation index**: [`spawn/navigation.yaml`](spec/design/data-structure.md) aggregates mandatory and contextual reads from **every installed extension** plus local [`spawn/rules/`](spec/design/user-guide.md) (refreshed with `spawn rules refresh`). Agents are steered through that file instead of chasing disconnected README fragments.
+
+On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other.
+
+**Example:** [**spawn-ext-spectask**](https://github.com/noant/spawn-ext-spectask) (Spec-Tasks methodology: spec layout, skills, design index) and [**spawn-ext-creator**](https://github.com/noant/spawn-ext-creator) (authoring flows, including agent-guided extension bootstrap) can be installed in the **same** repository and still share that single index and merged IDE outputs.
+
+## How to install spawn-cli
+
+**Recommended:** install `spawn` on your `PATH` with **uv**:
+
+```bash
+uv tool install spawn-cli && spawn --help
+```
+
+Run once without installing (ephemeral **uvx**):
+
+```bash
+uvx --from spawn-cli spawn --help
+```
+
+**Upgrade** the persistent uv tool:
+
+```bash
+uv tool upgrade spawn-cli && spawn --help
+```
+
+Force a fresh resolver for a one-shot run:
+
+```bash
+uvx --refresh --from spawn-cli spawn --help
+```
+
+Additional installers (**pip**, **pipx**, local checkout) and upgrade notes: **[spec/design/user-guide.md](spec/design/user-guide.md#other-installation-options)**.
+
+## How spawn-cli works
+
+Run commands from the **root of the repository** you are configuring. Almost every command requires `spawn init` first (it creates the `spawn/` tree). Only one Spawn process should touch a repo at a time (file lock).
+
+### Initialize a repo
+
+```bash
+spawn init
+```
+
+### IDE adapters
+
+For each **supported IDE** adapter, show whether it **looks used in the current repository** and what it can render (e.g. skills, MCP, agent-ignore):
+
+```bash
+spawn ide list-supported-ides
+```
+
+Register or drop IDE keys for **this** repo (examples: `cursor`, `codex`):
+
+```bash
+spawn ide add cursor
+spawn ide add cursor codex
+spawn ide remove codex
+spawn ide list
+```
+
+### Extensions
+
+Add from a Git URL, optional branch (also supports ZIP paths and local directories/archives):
+
+```bash
+spawn extension add https://github.com/noant/spawn-ext-spectask
+spawn extension add https://github.com/noant/spawn-ext-spectask --branch main
+```
+
+Maintain installed packs:
+
+```bash
+spawn extension list
+spawn extension update spectask
+spawn extension reinstall spectask
+spawn extension remove spectask
+spawn extension healthcheck spectask
+```
+
+Authoring helpers (run inside or next to an extension project):
+
+```bash
+spawn extension init ./my-ext --name my-ext
+spawn extension check ./my-ext
+spawn extension check ./my-ext --strict
+spawn extension from-rules ./repo-with-spawn-rules --name my-ext --output ./out
+```
+
+### Navigation from repo rules
+
+After editing files under `spawn/rules/`, refresh mandatory reads in `spawn/navigation.yaml`:
+
+```bash
+spawn rules refresh
+```
+
+### Batch install from a build manifest
+
+`spawn build list` / `spawn build install` take a **build source** (positional argument; there is no implicit default):
+
+- **Local directory** whose root contains **`extensions.yaml`**. Spawn resolves the path (e.g. `.` → current working directory) and reads **`<that-directory>/extensions.yaml`** — not a path to the YAML file itself.
+- Otherwise a **Git URL**, **ZIP URL**, or **local path** to a repository tree: Spawn stages it, then looks for **`extensions.yaml`** at that root or, if there is exactly one top-level subdirectory, under that folder (`extensions.yaml not found` if neither applies).
+
+Each manifest entry is an extension source; optional per-entry `branch` overrides the CLI default for that row.
+
+Minimal `extensions.yaml`:
+
+```yaml
+extensions:
+  - path: https://github.com/org/extension-one.git
+    branch: main
+  - path: https://github.com/org/extension-two.git
+```
+
+Dry-run (prints resolved entries as YAML), then install:
+
+```bash
+# Manifest at ./extensions.yaml (cwd is usually your initialized target repo if you keep it there)
+spawn build list .
+spawn build install .
+
+spawn build install /path/to/methodology-bundle
+spawn build install https://github.com/org/team-methodology.git --branch main
+```
+
+The **`--branch`** flag applies when the **build source** is Git (clone revision). Entries that omit `branch` fall back to that value.
+
+### Example extension
+
+[spawn-ext-spectask](https://github.com/noant/spawn-ext-spectask) is a concrete extension you can install with `spawn extension add` as shown above.
+
+---
+
+- **Python:** 3.10+ (see `pyproject.toml`).
+- **Deep dives:** [spec/design/user-guide.md](spec/design/user-guide.md) and [spec/design/utility.md](spec/design/utility.md).
+
+## How to create an extension
+
+An extension can be a **full** AIDD methodology, **team** conventions (review rules, codestyle), **scaffolds** for projects that default to AIDD-friendly layouts, **skill-only** bundles, or anything else you can express as declarative files plus optional setup hooks—anything that fits the `extsrc/` layout described in the author guide.
+
+**Bootstrap with the creator extension** (install like any other extension after `spawn init`):
+
+```bash
+spawn extension add https://github.com/noant/spawn-ext-creator
+```
+
+**Scaffold an empty extension** with the CLI (requires `spawn init` in the repo you run from — same as other subcommands). This lays out `extsrc/` with a starter `config.yaml`, plus empty `skills/`, `files/`, and `setup/`:
+
+```bash
+spawn extension init --name my-extension
+spawn extension init ./my-extension --name my-extension
+```
+
+**Agent-guided scaffold** with **[spawn-ext-creator](https://github.com/noant/spawn-ext-creator)** (install the extension above, then `spawn ide add <ide>` so skills render into your IDE): invoke the **`spawn-ext-bootstrap`** skill so the agent lays out a fuller extension repo than the bare CLI skeleton—for example:
+
+> Use the **spawn-ext-bootstrap** skill to bootstrap a new Spawn extension with stable id `my-extension` under `./my-extension`.
+
+Other creator skills (declaring `config.yaml`, skill sources, MCP, verification, etc.) ship under the same extension; see the rendered skill list after install.
+
+Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guide.md)** for the full model: required `extsrc/config.yaml`, mapping files under `extsrc/files/`, optional `skills/`, `mcp.json`, `agent-ignore`, `setup/` scripts, and how static vs artifact content is updated on `spawn extension update`.
+
+**Minimal mental model:**
+
+- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, etc.
+- `**extsrc/files/**` — template tree mirrored into the target repo according to `files:` entries.
+- `**spawn extension check . --strict**` — validate before publishing or tagging a release.
+
+## How to add rules without creating an extension
+
+Project-local conventions can live under **`spawn/rules/`** without packaging them as an extension. After **`spawn init`**, add any files there (for example `spawn/rules/team.md`); Spawn discovers **every file** under that directory tree.
+
+Wire those paths into **`spawn/navigation.yaml`** so mandatory reads stay aligned with what is on disk:
+
+```bash
+spawn rules refresh
+```
+
+That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`** group inside **`read-required`** (default description **`Local rule file.`** until you edit it), and drops stale entries whose files were deleted (you may see a warning).
+
+Rule files can be **mandatory** (**`read-required`**) or **contextual** (**`read-contextual`**). **`spawn rules refresh`** only auto-adds **new** paths into **`read-required` → `rules`**. To keep a rule **contextual**, declare it under **`read-contextual` → `rules`** in **`spawn/navigation.yaml`** with the same shape (`path`, `description`)—once a path appears in either rules list, refresh will not duplicate it into the other tier. You can move entries between **`read-required`** and **`read-contextual`** by editing **`spawn/navigation.yaml`**, then run **`spawn rules refresh`** so both lists stay consistent with files on disk.
+
+Extension-backed reads (`ext:` entries) are unrelated—you only maintain **`spawn/rules/**`** plus **`spawn rules refresh`** for repo-local rules.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

spawn_cli-0.1.5/README.md

@@ -0,0 +1,197 @@
+## What is Spawn?
+
+Spawn is a framework for building **AIDD** (AI-driven development) methodologies. It supports both **authoring** methodologies and **applying** them in a project. Within a single repository you can use **several** AIDD methodologies in a coherent way—shared navigation, skills, rules, and tooling stay aligned instead of competing ad hoc setups.
+
+## What is spawn-cli?
+
+**spawn-cli** is the utility that manages methodologies installed in your project. In Spawn terminology those packs are **extensions**: versioned content that usually lives in a **Git** repository. The CLI **instantiates** instruction files, process descriptions, rules, agent skills, and wires their behavior together (navigation, IDE-facing outputs, optional lifecycle hooks). Extensions can also declare **MCP servers**, **agent-ignore** patterns, **git-ignore** entries, and similar integration points—see [`spec/design/extension-author-guide.md`](spec/design/extension-author-guide.md).
+
+### How spawn-cli keeps methodologies coherent
+
+Several methodologies in one repo stay aligned because Spawn maintains **one shared navigation index**: [`spawn/navigation.yaml`](spec/design/data-structure.md) aggregates mandatory and contextual reads from **every installed extension** plus local [`spawn/rules/`](spec/design/user-guide.md) (refreshed with `spawn rules refresh`). Agents are steered through that file instead of chasing disconnected README fragments.
+
+On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other.
+
+**Example:** [**spawn-ext-spectask**](https://github.com/noant/spawn-ext-spectask) (Spec-Tasks methodology: spec layout, skills, design index) and [**spawn-ext-creator**](https://github.com/noant/spawn-ext-creator) (authoring flows, including agent-guided extension bootstrap) can be installed in the **same** repository and still share that single index and merged IDE outputs.
+
+## How to install spawn-cli
+
+**Recommended:** install `spawn` on your `PATH` with **uv**:
+
+```bash
+uv tool install spawn-cli && spawn --help
+```
+
+Run once without installing (ephemeral **uvx**):
+
+```bash
+uvx --from spawn-cli spawn --help
+```
+
+**Upgrade** the persistent uv tool:
+
+```bash
+uv tool upgrade spawn-cli && spawn --help
+```
+
+Force a fresh resolver for a one-shot run:
+
+```bash
+uvx --refresh --from spawn-cli spawn --help
+```
+
+Additional installers (**pip**, **pipx**, local checkout) and upgrade notes: **[spec/design/user-guide.md](spec/design/user-guide.md#other-installation-options)**.
+
+## How spawn-cli works
+
+Run commands from the **root of the repository** you are configuring. Almost every command requires `spawn init` first (it creates the `spawn/` tree). Only one Spawn process should touch a repo at a time (file lock).
+
+### Initialize a repo
+
+```bash
+spawn init
+```
+
+### IDE adapters
+
+For each **supported IDE** adapter, show whether it **looks used in the current repository** and what it can render (e.g. skills, MCP, agent-ignore):
+
+```bash
+spawn ide list-supported-ides
+```
+
+Register or drop IDE keys for **this** repo (examples: `cursor`, `codex`):
+
+```bash
+spawn ide add cursor
+spawn ide add cursor codex
+spawn ide remove codex
+spawn ide list
+```
+
+### Extensions
+
+Add from a Git URL, optional branch (also supports ZIP paths and local directories/archives):
+
+```bash
+spawn extension add https://github.com/noant/spawn-ext-spectask
+spawn extension add https://github.com/noant/spawn-ext-spectask --branch main
+```
+
+Maintain installed packs:
+
+```bash
+spawn extension list
+spawn extension update spectask
+spawn extension reinstall spectask
+spawn extension remove spectask
+spawn extension healthcheck spectask
+```
+
+Authoring helpers (run inside or next to an extension project):
+
+```bash
+spawn extension init ./my-ext --name my-ext
+spawn extension check ./my-ext
+spawn extension check ./my-ext --strict
+spawn extension from-rules ./repo-with-spawn-rules --name my-ext --output ./out
+```
+
+### Navigation from repo rules
+
+After editing files under `spawn/rules/`, refresh mandatory reads in `spawn/navigation.yaml`:
+
+```bash
+spawn rules refresh
+```
+
+### Batch install from a build manifest
+
+`spawn build list` / `spawn build install` take a **build source** (positional argument; there is no implicit default):
+
+- **Local directory** whose root contains **`extensions.yaml`**. Spawn resolves the path (e.g. `.` → current working directory) and reads **`<that-directory>/extensions.yaml`** — not a path to the YAML file itself.
+- Otherwise a **Git URL**, **ZIP URL**, or **local path** to a repository tree: Spawn stages it, then looks for **`extensions.yaml`** at that root or, if there is exactly one top-level subdirectory, under that folder (`extensions.yaml not found` if neither applies).
+
+Each manifest entry is an extension source; optional per-entry `branch` overrides the CLI default for that row.
+
+Minimal `extensions.yaml`:
+
+```yaml
+extensions:
+  - path: https://github.com/org/extension-one.git
+    branch: main
+  - path: https://github.com/org/extension-two.git
+```
+
+Dry-run (prints resolved entries as YAML), then install:
+
+```bash
+# Manifest at ./extensions.yaml (cwd is usually your initialized target repo if you keep it there)
+spawn build list .
+spawn build install .
+
+spawn build install /path/to/methodology-bundle
+spawn build install https://github.com/org/team-methodology.git --branch main
+```
+
+The **`--branch`** flag applies when the **build source** is Git (clone revision). Entries that omit `branch` fall back to that value.
+
+### Example extension
+
+[spawn-ext-spectask](https://github.com/noant/spawn-ext-spectask) is a concrete extension you can install with `spawn extension add` as shown above.
+
+---
+
+- **Python:** 3.10+ (see `pyproject.toml`).
+- **Deep dives:** [spec/design/user-guide.md](spec/design/user-guide.md) and [spec/design/utility.md](spec/design/utility.md).
+
+## How to create an extension
+
+An extension can be a **full** AIDD methodology, **team** conventions (review rules, codestyle), **scaffolds** for projects that default to AIDD-friendly layouts, **skill-only** bundles, or anything else you can express as declarative files plus optional setup hooks—anything that fits the `extsrc/` layout described in the author guide.
+
+**Bootstrap with the creator extension** (install like any other extension after `spawn init`):
+
+```bash
+spawn extension add https://github.com/noant/spawn-ext-creator
+```
+
+**Scaffold an empty extension** with the CLI (requires `spawn init` in the repo you run from — same as other subcommands). This lays out `extsrc/` with a starter `config.yaml`, plus empty `skills/`, `files/`, and `setup/`:
+
+```bash
+spawn extension init --name my-extension
+spawn extension init ./my-extension --name my-extension
+```
+
+**Agent-guided scaffold** with **[spawn-ext-creator](https://github.com/noant/spawn-ext-creator)** (install the extension above, then `spawn ide add <ide>` so skills render into your IDE): invoke the **`spawn-ext-bootstrap`** skill so the agent lays out a fuller extension repo than the bare CLI skeleton—for example:
+
+> Use the **spawn-ext-bootstrap** skill to bootstrap a new Spawn extension with stable id `my-extension` under `./my-extension`.
+
+Other creator skills (declaring `config.yaml`, skill sources, MCP, verification, etc.) ship under the same extension; see the rendered skill list after install.
+
+Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guide.md)** for the full model: required `extsrc/config.yaml`, mapping files under `extsrc/files/`, optional `skills/`, `mcp.json`, `agent-ignore`, `setup/` scripts, and how static vs artifact content is updated on `spawn extension update`.
+
+**Minimal mental model:**
+
+- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, etc.
+- `**extsrc/files/**` — template tree mirrored into the target repo according to `files:` entries.
+- `**spawn extension check . --strict**` — validate before publishing or tagging a release.
+
+## How to add rules without creating an extension
+
+Project-local conventions can live under **`spawn/rules/`** without packaging them as an extension. After **`spawn init`**, add any files there (for example `spawn/rules/team.md`); Spawn discovers **every file** under that directory tree.
+
+Wire those paths into **`spawn/navigation.yaml`** so mandatory reads stay aligned with what is on disk:
+
+```bash
+spawn rules refresh
+```
+
+That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`** group inside **`read-required`** (default description **`Local rule file.`** until you edit it), and drops stale entries whose files were deleted (you may see a warning).
+
+Rule files can be **mandatory** (**`read-required`**) or **contextual** (**`read-contextual`**). **`spawn rules refresh`** only auto-adds **new** paths into **`read-required` → `rules`**. To keep a rule **contextual**, declare it under **`read-contextual` → `rules`** in **`spawn/navigation.yaml`** with the same shape (`path`, `description`)—once a path appears in either rules list, refresh will not duplicate it into the other tier. You can move entries between **`read-required`** and **`read-contextual`** by editing **`spawn/navigation.yaml`**, then run **`spawn rules refresh`** so both lists stay consistent with files on disk.
+
+Extension-backed reads (`ext:` entries) are unrelated—you only maintain **`spawn/rules/**`** plus **`spawn rules refresh`** for repo-local rules.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{spawn_cli-0.1.3 → spawn_cli-0.1.5}/pyproject.toml

@@ -4,9 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spawn-cli"
-version = "0.1.3"
+version = "0.1.5"
 description = "A minimal installable Python CLI package."
+readme = "README.md"
 requires-python = ">=3.10"
+license = { text = "MIT" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+]
 dependencies = [
     "pydantic>=2.0",
     "ruamel.yaml>=0.18",
@@ -19,6 +24,9 @@ dependencies = [
 [project.scripts]
 spawn = "spawn_cli.cli:main"
 
+[tool.setuptools]
+license-files = ["LICENSE"]
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

{spawn_cli-0.1.3 → spawn_cli-0.1.5}/src/spawn_cli/core/high_level.py

@@ -9,7 +9,7 @@ from spawn_cli.core import download as dl
 from spawn_cli.core import low_level as ll
 from spawn_cli.core import scripts
 from spawn_cli.core.errors import SpawnError, SpawnWarning
-from spawn_cli.ide.registry import get as ide_get
+from spawn_cli.ide.registry import IdeCapabilities, get as ide_get
 from spawn_cli.io.json_io import load_json
 from spawn_cli.io.paths import ensure_dir, safe_path
 from spawn_cli.io.yaml_io import load_yaml, save_yaml
@@ -21,6 +21,37 @@ Read every file listed under `read-required`.
 Inspect `read-contextual` descriptions and read only files relevant to the current task.
 """
 
+MCP_MERGED_NOTICE = (
+    "MCP was merged for this workspace; you may need to press Enable in your IDE MCP UI."
+)
+
+
+def _any_extension_has_skill_files(target_root: Path) -> bool:
+    return any(ll.list_skills(target_root, ext) for ext in ll.list_extensions(target_root))
+
+
+def _any_extension_has_mcp_servers(target_root: Path) -> bool:
+    return any(ll.list_mcp(target_root, ext).servers for ext in ll.list_extensions(target_root))
+
+
+def _warn_capability_gaps(
+    ide_key: str,
+    caps: IdeCapabilities,
+    *,
+    needs_skill_render: bool,
+    needs_mcp_merge: bool,
+) -> None:
+    if needs_skill_render and caps.skills == "unsupported":
+        warnings.warn(
+            f"IDE {ide_key!r} does not support skills; skills were skipped",
+            SpawnWarning,
+        )
+    if needs_mcp_merge and caps.mcp in ("unsupported", "external"):
+        warnings.warn(
+            f"IDE {ide_key!r} has limited MCP support ({caps.mcp})",
+            SpawnWarning,
+        )
+
 
 def _require_init(target_root: Path) -> None:
     if not (target_root / "spawn").is_dir():
@@ -85,6 +116,16 @@ def refresh_skills(target_root: Path, ide: str, extension: str) -> None:
     ll.save_skills_rendered(target_root, ide, extension, rendered)
 
 
+def _refresh_skills_all_extensions_for_ide(target_root: Path, ide: str) -> None:
+    """Re-render every extension's skills on *ide*.
+
+    Skill metadata merges global reads from all installed extensions; peers must
+    be rebuilt when any extension's global read set changes.
+    """
+    for ext in ll.list_extensions(target_root):
+        refresh_skills(target_root, ide, ext)
+
+
 def remove_skills(target_root: Path, ide: str, extension: str) -> None:
     _require_init(target_root)
     prior = ll.get_rendered_skills(target_root, ide, extension)
@@ -92,7 +133,20 @@ def remove_skills(target_root: Path, ide: str, extension: str) -> None:
     ll.save_skills_rendered(target_root, ide, extension, [])
 
 
-def refresh_mcp(target_root: Path, ide: str, extension: str) -> None:
+def refresh_mcp(
+    target_root: Path,
+    ide: str,
+    extension: str,
+    *,
+    emit_mcp_merged_notice: bool = True,
+) -> list[str]:
+    """Merge extension MCP into the IDE project config.
+
+    Persisted rendered server names from ``adapter.add_mcp`` are returned.
+    When ``emit_mcp_merged_notice`` is true and that list is non-empty, prints
+    ``MCP_MERGED_NOTICE`` once to stdout (callers that batch refreshes, e.g.
+    ``add_ide``, should pass ``emit_mcp_merged_notice=False`` and print once).
+    """
     _require_init(target_root)
     prior = ll.get_rendered_mcp(target_root, ide, extension)
     ll.validate_rendered_identity(target_root)
@@ -101,6 +155,9 @@ def refresh_mcp(target_root: Path, ide: str, extension: str) -> None:
     adapter.remove_mcp(target_root, prior)
     new_names = adapter.add_mcp(target_root, nm)
     ll.save_mcp_rendered(target_root, ide, extension, new_names)
+    if new_names and emit_mcp_merged_notice:
+        print(MCP_MERGED_NOTICE)
+    return new_names
 
 
 def remove_mcp(target_root: Path, ide: str, extension: str) -> None:
@@ -116,8 +173,24 @@ def refresh_entry_point(target_root: Path, ide: str) -> None:
 
 
 def refresh_extension_for_ide(target_root: Path, ide: str, extension: str) -> None:
+    """Merge *extension* MCP on *ide* and re-render skills for every extension.
+
+    Mandatory reads in rendered skills are merged from all extensions'
+    ``globalRead`` metadata, so updating one extension can require re-rendering
+    skills owned by other extensions even when only this extension's MCP changed.
+    """
+    needs_skill = _any_extension_has_skill_files(target_root)
+    needs_mcp = bool(ll.list_mcp(target_root, extension).servers)
+    adapter = ide_get(ide)
+    dr = adapter.detect(target_root)
+    _warn_capability_gaps(
+        ide,
+        dr.capabilities,
+        needs_skill_render=needs_skill,
+        needs_mcp_merge=needs_mcp,
+    )
     refresh_mcp(target_root, ide, extension)
-    refresh_skills(target_root, ide, extension)
+    _refresh_skills_all_extensions_for_ide(target_root, ide)
     refresh_agent_ignore(target_root, ide)
 
 
@@ -150,9 +223,19 @@ def refresh_rules_navigation(target_root: Path) -> None:
 
 
 def _refresh_extension_core(target_root: Path, extension: str) -> None:
+    needs_skill = _any_extension_has_skill_files(target_root)
+    needs_mcp = bool(ll.list_mcp(target_root, extension).servers)
+    for ide in ll.list_ides(target_root):
+        adapter = ide_get(ide)
+        _warn_capability_gaps(
+            ide,
+            adapter.detect(target_root).capabilities,
+            needs_skill_render=needs_skill,
+            needs_mcp_merge=needs_mcp,
+        )
     for ide in ll.list_ides(target_root):
         refresh_mcp(target_root, ide, extension)
-        refresh_skills(target_root, ide, extension)
+        _refresh_skills_all_extensions_for_ide(target_root, ide)
     for ide in ll.list_ides(target_root):
         refresh_agent_ignore(target_root, ide)
     refresh_gitignore(target_root)
@@ -194,6 +277,8 @@ def remove_extension(target_root: Path, extension: str) -> None:
     for ide in ll.list_ides(target_root):
         refresh_agent_ignore(target_root, ide)
         refresh_entry_point(target_root, ide)
+    for ide in ll.list_ides(target_root):
+        _refresh_skills_all_extensions_for_ide(target_root, ide)
     scripts.run_after_uninstall_from_snapshot(target_root, extension, after_spec)
 
 
@@ -397,21 +482,21 @@ def add_ide(target_root: Path, ide: str) -> None:
     ll.add_ide_to_list(target_root, ide)
     adapter = ide_get(ide)
     dr = adapter.detect(target_root)
-    caps = dr.capabilities
-    if caps.skills == "unsupported":
-        warnings.warn(
-            f"IDE {ide!r} does not support skills; skills were skipped",
-            SpawnWarning,
-        )
-    if caps.mcp in ("unsupported", "external"):
-        warnings.warn(
-            f"IDE {ide!r} has limited MCP support ({caps.mcp})",
-            SpawnWarning,
-        )
+    _warn_capability_gaps(
+        ide,
+        dr.capabilities,
+        needs_skill_render=_any_extension_has_skill_files(target_root),
+        needs_mcp_merge=_any_extension_has_mcp_servers(target_root),
+    )
     refresh_entry_point(target_root, ide)
+    merged_any = False
     for ext in ll.list_extensions(target_root):
-        refresh_mcp(target_root, ide, ext)
-        refresh_skills(target_root, ide, ext)
+        new_names = refresh_mcp(target_root, ide, ext, emit_mcp_merged_notice=False)
+        if new_names:
+            merged_any = True
+    _refresh_skills_all_extensions_for_ide(target_root, ide)
+    if merged_any:
+        print(MCP_MERGED_NOTICE)
     refresh_agent_ignore(target_root, ide)
 
 
@@ -435,6 +520,7 @@ def install_extension(target_root: Path, path: str, branch: str | None = None) -
 
 
 __all__ = [
+    "MCP_MERGED_NOTICE",
     "SPAWN_ENTRY_POINT_PROMPT",
     "_refresh_extension_core",
     "add_ide",

spawn_cli-0.1.5/src/spawn_cli.egg-info/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: spawn-cli
+Version: 0.1.5
+Summary: A minimal installable Python CLI package.
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ruamel.yaml>=0.18
+Requires-Dist: filelock>=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Dynamic: license-file
+
+## What is Spawn?
+
+Spawn is a framework for building **AIDD** (AI-driven development) methodologies. It supports both **authoring** methodologies and **applying** them in a project. Within a single repository you can use **several** AIDD methodologies in a coherent way—shared navigation, skills, rules, and tooling stay aligned instead of competing ad hoc setups.
+
+## What is spawn-cli?
+
+**spawn-cli** is the utility that manages methodologies installed in your project. In Spawn terminology those packs are **extensions**: versioned content that usually lives in a **Git** repository. The CLI **instantiates** instruction files, process descriptions, rules, agent skills, and wires their behavior together (navigation, IDE-facing outputs, optional lifecycle hooks). Extensions can also declare **MCP servers**, **agent-ignore** patterns, **git-ignore** entries, and similar integration points—see [`spec/design/extension-author-guide.md`](spec/design/extension-author-guide.md).
+
+### How spawn-cli keeps methodologies coherent
+
+Several methodologies in one repo stay aligned because Spawn maintains **one shared navigation index**: [`spawn/navigation.yaml`](spec/design/data-structure.md) aggregates mandatory and contextual reads from **every installed extension** plus local [`spawn/rules/`](spec/design/user-guide.md) (refreshed with `spawn rules refresh`). Agents are steered through that file instead of chasing disconnected README fragments.
+
+On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other.
+
+**Example:** [**spawn-ext-spectask**](https://github.com/noant/spawn-ext-spectask) (Spec-Tasks methodology: spec layout, skills, design index) and [**spawn-ext-creator**](https://github.com/noant/spawn-ext-creator) (authoring flows, including agent-guided extension bootstrap) can be installed in the **same** repository and still share that single index and merged IDE outputs.
+
+## How to install spawn-cli
+
+**Recommended:** install `spawn` on your `PATH` with **uv**:
+
+```bash
+uv tool install spawn-cli && spawn --help
+```
+
+Run once without installing (ephemeral **uvx**):
+
+```bash
+uvx --from spawn-cli spawn --help
+```
+
+**Upgrade** the persistent uv tool:
+
+```bash
+uv tool upgrade spawn-cli && spawn --help
+```
+
+Force a fresh resolver for a one-shot run:
+
+```bash
+uvx --refresh --from spawn-cli spawn --help
+```
+
+Additional installers (**pip**, **pipx**, local checkout) and upgrade notes: **[spec/design/user-guide.md](spec/design/user-guide.md#other-installation-options)**.
+
+## How spawn-cli works
+
+Run commands from the **root of the repository** you are configuring. Almost every command requires `spawn init` first (it creates the `spawn/` tree). Only one Spawn process should touch a repo at a time (file lock).
+
+### Initialize a repo
+
+```bash
+spawn init
+```
+
+### IDE adapters
+
+For each **supported IDE** adapter, show whether it **looks used in the current repository** and what it can render (e.g. skills, MCP, agent-ignore):
+
+```bash
+spawn ide list-supported-ides
+```
+
+Register or drop IDE keys for **this** repo (examples: `cursor`, `codex`):
+
+```bash
+spawn ide add cursor
+spawn ide add cursor codex
+spawn ide remove codex
+spawn ide list
+```
+
+### Extensions
+
+Add from a Git URL, optional branch (also supports ZIP paths and local directories/archives):
+
+```bash
+spawn extension add https://github.com/noant/spawn-ext-spectask
+spawn extension add https://github.com/noant/spawn-ext-spectask --branch main
+```
+
+Maintain installed packs:
+
+```bash
+spawn extension list
+spawn extension update spectask
+spawn extension reinstall spectask
+spawn extension remove spectask
+spawn extension healthcheck spectask
+```
+
+Authoring helpers (run inside or next to an extension project):
+
+```bash
+spawn extension init ./my-ext --name my-ext
+spawn extension check ./my-ext
+spawn extension check ./my-ext --strict
+spawn extension from-rules ./repo-with-spawn-rules --name my-ext --output ./out
+```
+
+### Navigation from repo rules
+
+After editing files under `spawn/rules/`, refresh mandatory reads in `spawn/navigation.yaml`:
+
+```bash
+spawn rules refresh
+```
+
+### Batch install from a build manifest
+
+`spawn build list` / `spawn build install` take a **build source** (positional argument; there is no implicit default):
+
+- **Local directory** whose root contains **`extensions.yaml`**. Spawn resolves the path (e.g. `.` → current working directory) and reads **`<that-directory>/extensions.yaml`** — not a path to the YAML file itself.
+- Otherwise a **Git URL**, **ZIP URL**, or **local path** to a repository tree: Spawn stages it, then looks for **`extensions.yaml`** at that root or, if there is exactly one top-level subdirectory, under that folder (`extensions.yaml not found` if neither applies).
+
+Each manifest entry is an extension source; optional per-entry `branch` overrides the CLI default for that row.
+
+Minimal `extensions.yaml`:
+
+```yaml
+extensions:
+  - path: https://github.com/org/extension-one.git
+    branch: main
+  - path: https://github.com/org/extension-two.git
+```
+
+Dry-run (prints resolved entries as YAML), then install:
+
+```bash
+# Manifest at ./extensions.yaml (cwd is usually your initialized target repo if you keep it there)
+spawn build list .
+spawn build install .
+
+spawn build install /path/to/methodology-bundle
+spawn build install https://github.com/org/team-methodology.git --branch main
+```
+
+The **`--branch`** flag applies when the **build source** is Git (clone revision). Entries that omit `branch` fall back to that value.
+
+### Example extension
+
+[spawn-ext-spectask](https://github.com/noant/spawn-ext-spectask) is a concrete extension you can install with `spawn extension add` as shown above.
+
+---
+
+- **Python:** 3.10+ (see `pyproject.toml`).
+- **Deep dives:** [spec/design/user-guide.md](spec/design/user-guide.md) and [spec/design/utility.md](spec/design/utility.md).
+
+## How to create an extension
+
+An extension can be a **full** AIDD methodology, **team** conventions (review rules, codestyle), **scaffolds** for projects that default to AIDD-friendly layouts, **skill-only** bundles, or anything else you can express as declarative files plus optional setup hooks—anything that fits the `extsrc/` layout described in the author guide.
+
+**Bootstrap with the creator extension** (install like any other extension after `spawn init`):
+
+```bash
+spawn extension add https://github.com/noant/spawn-ext-creator
+```
+
+**Scaffold an empty extension** with the CLI (requires `spawn init` in the repo you run from — same as other subcommands). This lays out `extsrc/` with a starter `config.yaml`, plus empty `skills/`, `files/`, and `setup/`:
+
+```bash
+spawn extension init --name my-extension
+spawn extension init ./my-extension --name my-extension
+```
+
+**Agent-guided scaffold** with **[spawn-ext-creator](https://github.com/noant/spawn-ext-creator)** (install the extension above, then `spawn ide add <ide>` so skills render into your IDE): invoke the **`spawn-ext-bootstrap`** skill so the agent lays out a fuller extension repo than the bare CLI skeleton—for example:
+
+> Use the **spawn-ext-bootstrap** skill to bootstrap a new Spawn extension with stable id `my-extension` under `./my-extension`.
+
+Other creator skills (declaring `config.yaml`, skill sources, MCP, verification, etc.) ship under the same extension; see the rendered skill list after install.
+
+Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guide.md)** for the full model: required `extsrc/config.yaml`, mapping files under `extsrc/files/`, optional `skills/`, `mcp.json`, `agent-ignore`, `setup/` scripts, and how static vs artifact content is updated on `spawn extension update`.
+
+**Minimal mental model:**
+
+- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, etc.
+- `**extsrc/files/**` — template tree mirrored into the target repo according to `files:` entries.
+- `**spawn extension check . --strict**` — validate before publishing or tagging a release.
+
+## How to add rules without creating an extension
+
+Project-local conventions can live under **`spawn/rules/`** without packaging them as an extension. After **`spawn init`**, add any files there (for example `spawn/rules/team.md`); Spawn discovers **every file** under that directory tree.
+
+Wire those paths into **`spawn/navigation.yaml`** so mandatory reads stay aligned with what is on disk:
+
+```bash
+spawn rules refresh
+```
+
+That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`** group inside **`read-required`** (default description **`Local rule file.`** until you edit it), and drops stale entries whose files were deleted (you may see a warning).
+
+Rule files can be **mandatory** (**`read-required`**) or **contextual** (**`read-contextual`**). **`spawn rules refresh`** only auto-adds **new** paths into **`read-required` → `rules`**. To keep a rule **contextual**, declare it under **`read-contextual` → `rules`** in **`spawn/navigation.yaml`** with the same shape (`path`, `description`)—once a path appears in either rules list, refresh will not duplicate it into the other tier. You can move entries between **`read-required`** and **`read-contextual`** by editing **`spawn/navigation.yaml`**, then run **`spawn rules refresh`** so both lists stay consistent with files on disk.
+
+Extension-backed reads (`ext:` entries) are unrelated—you only maintain **`spawn/rules/**`** plus **`spawn rules refresh`** for repo-local rules.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{spawn_cli-0.1.3 → spawn_cli-0.1.5}/src/spawn_cli.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 README.md
 pyproject.toml
 src/spawn_cli/__init__.py

spawn_cli-0.1.3/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.4
-Name: spawn-cli
-Version: 0.1.3
-Summary: A minimal installable Python CLI package.
-Requires-Python: >=3.10
-Requires-Dist: pydantic>=2.0
-Requires-Dist: ruamel.yaml>=0.18
-Requires-Dist: filelock>=3.12
-Requires-Dist: httpx>=0.27
-Requires-Dist: tomli>=2.0; python_version < "3.11"
-Requires-Dist: tomli-w>=1.0

spawn_cli-0.1.3/README.md

@@ -1,114 +0,0 @@
-# spawn-cli
-
-Installable CLI **`spawn`** for initializing and managing Spawn metadata (extensions, IDE adapters, navigation) in a repository.
-
-## Quick start (uv)
-
-Install `spawn` on your `PATH` (persistent **uv** tool environment):
-
-```bash
-uv tool install spawn-cli && spawn --help
-```
-
-Run once without installing a tool (ephemeral **uvx**):
-
-```bash
-uvx --from spawn-cli spawn --help
-```
-
-## Upgrade (uv)
-
-Upgrade the persistent tool:
-
-```bash
-uv tool upgrade spawn-cli && spawn --help
-```
-
-Latest resolver result for a one-shot run:
-
-```bash
-uvx --refresh --from spawn-cli spawn --help
-```
-
----
-
-- **Python:** 3.10+ (see `pyproject.toml`).
-- **Usage:** run from the **root of the repository** you configure; most commands need `spawn init` first.
-
-## Install
-
-The PyPI package name is **`spawn-cli`**; the console script is **`spawn`**.
-
-### From PyPI
-
-```bash
-pip install spawn-cli
-spawn --help
-```
-
-Isolated install:
-
-```bash
-pipx install spawn-cli
-spawn --help
-```
-
-With **uv** (tool on `PATH`):
-
-```bash
-uv tool install spawn-cli
-spawn --help
-```
-
-One-shot without installing into an environment:
-
-```bash
-uvx --from spawn-cli spawn --help
-```
-
-### From a local checkout
-
-```bash
-cd /path/to/spawn-cli
-uv sync
-uv run spawn --help
-```
-
-Or editable install with **pip**:
-
-```bash
-cd /path/to/spawn-cli
-pip install -e .
-spawn --help
-```
-
-## Upgrade
-
-Use the same installer you used for the initial install. **If you use uv only, see [Upgrade (uv)](#upgrade-uv) at the top.**
-
-**pip** (current environment):
-
-```bash
-pip install --upgrade spawn-cli
-spawn --help
-```
-
-**pipx**:
-
-```bash
-pipx upgrade spawn-cli
-spawn --help
-```
-
-**Local checkout:** pull changes, then reinstall so the editable install sees updates:
-
-```bash
-cd /path/to/spawn-cli
-git pull
-uv sync
-# or: pip install -e .
-```
-
-## More
-
-Design and command details: `spec/design/user-guide.md` and `spec/design/utility.md`.

spawn_cli-0.1.3/src/spawn_cli.egg-info/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.4
-Name: spawn-cli
-Version: 0.1.3
-Summary: A minimal installable Python CLI package.
-Requires-Python: >=3.10
-Requires-Dist: pydantic>=2.0
-Requires-Dist: ruamel.yaml>=0.18
-Requires-Dist: filelock>=3.12
-Requires-Dist: httpx>=0.27
-Requires-Dist: tomli>=2.0; python_version < "3.11"
-Requires-Dist: tomli-w>=1.0