spawn-cli 0.1.10__tar.gz → 0.1.12__tar.gz

{spawn_cli-0.1.10 → spawn_cli-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.10
+Version: 0.1.12
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -181,7 +181,7 @@ 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`.
+> Use the **spawn-ext-bootstrap** skill to bootstrap a new Spawn extension.
 
 Other creator skills (declaring `config.yaml`, skill sources, MCP, verification, etc.) ship under the same extension; see the rendered skill list after install.
 
@@ -189,25 +189,49 @@ Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guid
 
 **Minimal mental model:**
 
-- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, optional `hints`, 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.
+- `extsrc/config.yaml` — `schema`, `version`, stable `name` (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, optional `hints`, 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.
+You can steer agents in two complementary ways that do **not** require an extension: **rule files** under **`spawn/rules/`** (content the agent must or may read), and **short hints** in **`spawn/navigation.yaml`** (reminders merged into rendered skills and IDE entry-point blocks such as **`AGENTS.md`**).
 
-Wire those paths into **`spawn/navigation.yaml`** so mandatory reads stay aligned with what is on disk:
+**After edits** to **`spawn/rules/**` or to rule rows / **`hint`** in **`spawn/navigation.yaml`**, run **`spawn refresh`** so navigation, skills, and entry points stay in sync. **`spawn rules refresh`** only syncs **`spawn/rules/**` into **`navigation.yaml`**—no skill or entry-point updates.
+
+### 1. Rule files
+
+Project-local conventions live as files under **`spawn/rules/`**. 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 reads stay aligned with what is on disk:
 
 ```bash
-spawn rules refresh
+spawn 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.
+**Tiers:** list a rule under **`read-required` → `rules`** (always read) or **`read-contextual` → `rules`** (read when relevant). Use the same row shape (`path`, `description`). A path must not appear in both lists—after you move a row, rerun **`spawn refresh`** (or **`spawn rules refresh`** if you only need YAML). New files discovered on disk are appended to **`read-required` → `rules`** until you relocate them.
+
+**Extension reads:** **`ext:`** blocks are unrelated; repo-local rule paths live only under **`spawn/rules/**`** and the **`rules`** groups in **`spawn/navigation.yaml`**.
+
+### 2. Hints in `spawn/navigation.yaml`
+
+For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+
+Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+
+Example:
+
+```yaml
+read-required:
+  - rules:
+      - path: spawn/rules/team.md
+        description: Team conventions.
+        hint: Prefer British spelling in user-facing copy.
+```
 
-Extension-backed reads (`ext:` entries) are unrelated—you only maintain **`spawn/rules/**`** plus **`spawn rules refresh`** for repo-local rules.
+Then run **`spawn refresh`** so skills and entry points pick up the hint.
 
 ## License
 

spawn_cli-0.1.10/src/spawn_cli.egg-info/PKG-INFO → spawn_cli-0.1.12/README.md

@@ -1,214 +1,221 @@
-Metadata-Version: 2.4
-Name: spawn-cli
-Version: 0.1.10
-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. Optional `hints` add short reminders to rendered skills and the Spawn-managed entry block.
-
-**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, optional `hints`, 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).
+## 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. Optional `hints` add short reminders to rendered skills and the Spawn-managed entry block.
+
+**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.
+
+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, optional `hints`, 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
+
+You can steer agents in two complementary ways that do **not** require an extension: **rule files** under **`spawn/rules/`** (content the agent must or may read), and **short hints** in **`spawn/navigation.yaml`** (reminders merged into rendered skills and IDE entry-point blocks such as **`AGENTS.md`**).
+
+**After edits** to **`spawn/rules/**` or to rule rows / **`hint`** in **`spawn/navigation.yaml`**, run **`spawn refresh`** so navigation, skills, and entry points stay in sync. **`spawn rules refresh`** only syncs **`spawn/rules/**` into **`navigation.yaml`**—no skill or entry-point updates.
+
+### 1. Rule files
+
+Project-local conventions live as files under **`spawn/rules/`**. 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 reads stay aligned with what is on disk:
+
+```bash
+spawn 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).
+
+**Tiers:** list a rule under **`read-required` → `rules`** (always read) or **`read-contextual` → `rules`** (read when relevant). Use the same row shape (`path`, `description`). A path must not appear in both lists—after you move a row, rerun **`spawn refresh`** (or **`spawn rules refresh`** if you only need YAML). New files discovered on disk are appended to **`read-required` → `rules`** until you relocate them.
+
+**Extension reads:** **`ext:`** blocks are unrelated; repo-local rule paths live only under **`spawn/rules/**`** and the **`rules`** groups in **`spawn/navigation.yaml`**.
+
+### 2. Hints in `spawn/navigation.yaml`
+
+For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+
+Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+
+Example:
+
+```yaml
+read-required:
+  - rules:
+      - path: spawn/rules/team.md
+        description: Team conventions.
+        hint: Prefer British spelling in user-facing copy.
+```
+
+Then run **`spawn refresh`** so skills and entry points pick up the hint.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{spawn_cli-0.1.10 → spawn_cli-0.1.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spawn-cli"
-version = "0.1.10"
+version = "0.1.12"
 description = "A minimal installable Python CLI package."
 readme = "README.md"
 requires-python = ">=3.10"

{spawn_cli-0.1.10 → spawn_cli-0.1.12}/src/spawn_cli/core/scripts.py

@@ -66,6 +66,7 @@ def _run_script(
     target_root: Path,
     extension: str,
     script_filename: str,
+    phase: str,
     *,
     ext_layout: Path,
     blocking: bool,
@@ -83,6 +84,10 @@ def _run_script(
     env["SPAWN_EXT_PATH"] = str(ext_layout.resolve())
     env["SPAWN_EXT_VERSION"] = ext_ver
     env["SPAWN_TARGET_VERSION"] = tgt_ver
+    print(
+        f"spawn: running {phase} script: {Path(script_filename).name}",
+        file=sys.stderr,
+    )
     proc = subprocess.run(
         [sys.executable, str(script_path)],
         cwd=str(target_root),
@@ -110,6 +115,7 @@ def run_before_install_scripts(target_root: Path, extension: str, *, ext_layout:
         target_root,
         extension,
         cfg.setup.before_install,
+        "before-install",
         ext_layout=layout,
         blocking=True,
     )
@@ -124,6 +130,7 @@ def run_after_install_scripts(target_root: Path, extension: str, *, ext_layout:
         target_root,
         extension,
         cfg.setup.after_install,
+        "after-install",
         ext_layout=layout,
         blocking=False,
     )
@@ -140,6 +147,7 @@ def run_before_uninstall_scripts(target_root: Path, extension: str, *, ext_layou
         target_root,
         extension,
         cfg.setup.before_uninstall,
+        "before-uninstall",
         ext_layout=layout,
         blocking=True,
     )
@@ -156,6 +164,7 @@ def run_after_uninstall_scripts(target_root: Path, extension: str, *, ext_layout
         target_root,
         extension,
         cfg.setup.after_uninstall,
+        "after-uninstall",
         ext_layout=layout,
         blocking=False,
     )
@@ -191,6 +200,10 @@ def run_after_uninstall_from_snapshot(
     env["SPAWN_EXT_PATH"] = str(ghost_ext.resolve())
     env["SPAWN_EXT_VERSION"] = snap.ext_version
     env["SPAWN_TARGET_VERSION"] = _core_version(target_root)
+    print(
+        f"spawn: running after-uninstall script: {snap.script_path.name}",
+        file=sys.stderr,
+    )
     proc = subprocess.run(
         [sys.executable, str(snap.script_path)],
         cwd=str(target_root),
@@ -211,6 +224,10 @@ def run_healthcheck_scripts(target_root: Path, extension: str, *, ext_layout: Pa
     cfg = _extension_config_at(layout)
     if not cfg.setup or not cfg.setup.healthcheck:
         return True
+    print(
+        f"spawn: running healthcheck script: {Path(cfg.setup.healthcheck).name}",
+        file=sys.stderr,
+    )
     proc = subprocess.run(
         [
             sys.executable,

{spawn_cli-0.1.10 → spawn_cli-0.1.12}/src/spawn_cli/io/lock.py

@@ -17,7 +17,9 @@ def spawn_lock(target_root: Path):
     try:
         lock.acquire(timeout=0)
     except Timeout:
-        raise SpawnError("Операция в процессе (файл lock detected)") from None
+        raise SpawnError(
+            "Another Spawn operation is in progress (repository lock held)"
+        ) from None
     try:
         yield
     finally: