spawn-cli 0.1.7__tar.gz → 0.1.9__tar.gz

{spawn_cli-0.1.7/src/spawn_cli.egg-info → spawn_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.7
+Version: 0.1.9
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -27,7 +27,7 @@ Spawn is a framework for building **AIDD** (AI-driven development) methodologies
 
 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.
+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.
 
@@ -189,7 +189,7 @@ 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, etc.
+- `**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.
 

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/README.md

@@ -10,7 +10,7 @@ Spawn is a framework for building **AIDD** (AI-driven development) methodologies
 
 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.
+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.
 
@@ -172,7 +172,7 @@ 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, etc.
+- `**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.
 

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/pyproject.toml

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

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/src/spawn_cli/cli.py

@@ -44,8 +44,8 @@ def build_parser() -> argparse.ArgumentParser:
         "refresh",
         help="Sync core config from defaults and rebuild IDE renders",
         description=(
-            "Merge bundled defaults into spawn/.core/config.yaml, then refresh skills, MCP, "
-            "agent ignore, navigation, gitignore metadata, and IDE entry points."
+            "Replace spawn/.core/config.yaml with bundled default core config, then refresh "
+            "skills, MCP, agent ignore, navigation, gitignore metadata, and IDE entry points."
         ),
     )
 

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/src/spawn_cli/core/high_level.py

@@ -169,7 +169,17 @@ def remove_mcp(target_root: Path, ide: str, extension: str) -> None:
 
 def refresh_entry_point(target_root: Path, ide: str) -> None:
     _require_init(target_root)
-    ide_get(ide).rewrite_entry_point(target_root, SPAWN_ENTRY_POINT_PROMPT)
+    rollup = ll.rollup_hints_for_agents(target_root)
+    ll.warn_if_agents_hints_exceed_measurement(rollup)
+    if rollup:
+        prompt = (
+            f"{SPAWN_ENTRY_POINT_PROMPT}\nHints:\n"
+            + "\n".join(f"- {h}" for h in rollup)
+            + "\n"
+        )
+    else:
+        prompt = SPAWN_ENTRY_POINT_PROMPT
+    ide_get(ide).rewrite_entry_point(target_root, prompt)
 
 
 def refresh_extension_for_ide(target_root: Path, ide: str, extension: str) -> None:
@@ -192,6 +202,7 @@ def refresh_extension_for_ide(target_root: Path, ide: str, extension: str) -> No
     refresh_mcp(target_root, ide, extension)
     _refresh_skills_all_extensions_for_ide(target_root, ide)
     refresh_agent_ignore(target_root, ide)
+    refresh_navigation(target_root)
 
 
 def remove_extension_for_ide(target_root: Path, ide: str, extension: str) -> None:
@@ -223,9 +234,9 @@ def refresh_rules_navigation(target_root: Path) -> None:
 
 
 def refresh_repository(target_root: Path) -> None:
-    """Sync core config from package defaults and rebuild all IDE-facing metadata."""
+    """Overwrite core config from bundled defaults, then rebuild all IDE-facing metadata."""
     _require_init(target_root)
-    ll.merge_core_config_from_defaults(target_root)
+    ll.sync_core_config_from_defaults(target_root)
     needs_skill = _any_extension_has_skill_files(target_root)
     needs_mcp = _any_extension_has_mcp_servers(target_root)
     for ide in ll.list_ides(target_root):

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/src/spawn_cli/core/low_level.py

@@ -130,6 +130,182 @@ def _load_ext_config(target_root: Path, extension: str) -> ExtensionConfig:
     return ExtensionConfig.model_validate(raw)
 
 
+_EXTENSION_NAV_HINT_MAX_CODEPOINTS = 512
+_SKILL_HINT_SECTION_COMBINED_MAX_CHARS = 4096
+
+
+def _optional_ext_config(target_root: Path, extension: str) -> ExtensionConfig | None:
+    path = _config_path(target_root, extension)
+    if not path.is_file():
+        return None
+    raw = load_yaml(path)
+    if not raw:
+        return None
+    return ExtensionConfig.model_validate(raw)
+
+
+def _normalized_extension_global_hints_for_navigation(cfg: ExtensionConfig) -> list[str]:
+    """Strip, drop empties, dedupe (first wins), warn + truncate to codepoint limit for persisted navigation."""
+
+    raw_list: list[str] = []
+    if cfg.hints is not None:
+        raw_list.extend(cfg.hints.global_)
+    seen: set[str] = set()
+    out: list[str] = []
+    for h in raw_list:
+        s = h.strip()
+        if not s:
+            continue
+        if s in seen:
+            continue
+        seen.add(s)
+        if len(s) > _EXTENSION_NAV_HINT_MAX_CODEPOINTS:
+            warnings.warn(
+                "Extension navigation hint exceeds 512 Unicode code points and was truncated.",
+                SpawnWarning,
+            )
+            s = s[:_EXTENSION_NAV_HINT_MAX_CODEPOINTS]
+        out.append(s)
+    return out
+
+
+def _truncate_hint_codepoints(text: str, max_codepoints: int) -> tuple[str, bool]:
+    if len(text) <= max_codepoints:
+        return text, False
+    return text[:max_codepoints], True
+
+
+def _merge_hint_streams_ordered(streams: list[list[str]]) -> list[str]:
+    """Dedupe stripped strings with first occurrence winning; earlier streams dominate later ones."""
+
+    seen: set[str] = set()
+    out: list[str] = []
+    for stream in streams:
+        for h in stream:
+            s = h.strip()
+            if not s or s in seen:
+                continue
+            seen.add(s)
+            out.append(s)
+    return out
+
+
+def _navigation_read_required_rule_hints_ordered(target_root: Path) -> list[str]:
+    """Plain-text hints from maintainer-authored read-required ``rules`` rows only (YAML order).
+
+    Hint fields on ``read-contextual`` rules are ignored here.
+    """
+    path = _spawn(target_root) / "navigation.yaml"
+    raw = load_yaml(path)
+    if not isinstance(raw, dict):
+        return []
+    rr = raw.get("read-required")
+    if not isinstance(rr, list):
+        return []
+    out: list[str] = []
+    for grp in rr:
+        if not isinstance(grp, dict):
+            continue
+        rules_raw = grp.get("rules")
+        if not isinstance(rules_raw, list):
+            continue
+        for entry in rules_raw:
+            if not isinstance(entry, dict):
+                continue
+            hint_val = entry.get("hint")
+            if isinstance(hint_val, str):
+                out.append(hint_val)
+    return out
+
+
+def _finalize_hints_for_skill_metadata(merged_hints: list[str]) -> list[str]:
+    """512 codepoints per hint + 4096 char ``Hints:`` section (terminal ``- ...`` when clipped)."""
+
+    trimmed: list[str] = []
+    for h in merged_hints:
+        t, clipped = _truncate_hint_codepoints(h, _EXTENSION_NAV_HINT_MAX_CODEPOINTS)
+        if clipped:
+            warnings.warn(
+                "Skill hint exceeds 512 Unicode code points and was truncated for skill metadata.",
+                SpawnWarning,
+            )
+        trimmed.append(t)
+
+    header = "Hints:\n"
+    warn_combined = (
+        "Skill hints truncated to fit combined 4096 character budget for the Hints section; "
+        "shorten hints and/or split skills."
+    )
+
+    def build_block(strings: list[str], with_ellipsis: bool) -> str:
+        lines = [f"- {s}" for s in strings]
+        if with_ellipsis:
+            lines.append("- ...")
+        if not lines:
+            return ""
+        return header + "\n".join(lines)
+
+    fitted: list[str] = []
+    need_ellipsis = False
+
+    for s in trimmed:
+        plain = build_block(fitted + [s], False)
+        if len(plain) <= _SKILL_HINT_SECTION_COMBINED_MAX_CHARS:
+            fitted.append(s)
+            continue
+        with_el = build_block(fitted + [s], True)
+        if len(with_el) <= _SKILL_HINT_SECTION_COMBINED_MAX_CHARS:
+            fitted.append(s)
+            need_ellipsis = True
+            warnings.warn(warn_combined, SpawnWarning)
+            break
+        need_ellipsis = True
+        warnings.warn(warn_combined, SpawnWarning)
+        break
+
+    if need_ellipsis:
+        fitted.append("...")
+    return fitted
+
+
+def _extension_global_hint_streams_ordered(target_root: Path) -> list[list[str]]:
+    """One hint list per extension, in ``list_extensions`` order (sorted ext ids)."""
+
+    streams: list[list[str]] = []
+    for ext in list_extensions(target_root):
+        cfg = _load_ext_config(target_root, ext)
+        streams.append(list(cfg.hints.global_) if cfg.hints else [])
+    return streams
+
+
+def rollup_hints_for_agents(target_root: Path) -> list[str]:
+    """Deduped ordered hints for ``AGENTS.md``: every extension ``hints.global``, then maintainer."""
+
+    streams = _extension_global_hint_streams_ordered(target_root)
+    streams.append(_navigation_read_required_rule_hints_ordered(target_root))
+    return _merge_hint_streams_ordered(streams)
+
+
+def warn_if_agents_hints_exceed_measurement(hints: list[str]) -> None:
+    """Warn when thresholds are exceeded without mutating hints (full text still written)."""
+
+    if any(len(h) > _EXTENSION_NAV_HINT_MAX_CODEPOINTS for h in hints):
+        warnings.warn(
+            "AGENTS.md hints contain at least one hint over 512 Unicode code points "
+            "(full text retained); shorten hints and/or reduce installed extensions.",
+            SpawnWarning,
+        )
+    block = ""
+    if hints:
+        block = "Hints:\n" + "\n".join(f"- {h}" for h in hints)
+    if hints and len(block) > _SKILL_HINT_SECTION_COMBINED_MAX_CHARS:
+        warnings.warn(
+            "AGENTS.md hints exceed combined 4096 character measurement "
+            "(full text retained); shorten hints and/or reduce installed extensions.",
+            SpawnWarning,
+        )
+
+
 def _file_refs_for_global(extension: ExtensionConfig, flag_required: bool) -> list[SkillFileRef]:
     out: list[SkillFileRef] = []
     for path_str, ent in extension.files.items():
@@ -294,26 +470,82 @@ def _norm_read_path(path_str: str) -> str:
     return Path(path_str).as_posix().replace("\\", "/")
 
 
+def _navigation_rules_refs_from_section(section: Any) -> list[SkillFileRef]:
+    out: list[SkillFileRef] = []
+    if not isinstance(section, list):
+        return out
+    for grp in section:
+        if not isinstance(grp, dict):
+            continue
+        rules_raw = grp.get("rules")
+        if not isinstance(rules_raw, list):
+            continue
+        for entry in rules_raw:
+            if not isinstance(entry, dict):
+                continue
+            path_raw = entry.get("path")
+            if not isinstance(path_raw, str) or not path_raw.strip():
+                continue
+            desc_raw = entry.get("description")
+            desc = "" if desc_raw is None else str(desc_raw)
+            out.append(SkillFileRef(file=path_raw.strip(), description=desc))
+    return out
+
+
+def _navigation_yaml_rules_refs(target_root: Path) -> tuple[list[SkillFileRef], list[SkillFileRef]]:
+    """Return (read-required rules, read-contextual rules) from merged navigation.yaml."""
+    path = _spawn(target_root) / "navigation.yaml"
+    raw = load_yaml(path)
+    if not isinstance(raw, dict):
+        return [], []
+    rr = raw.get("read-required")
+    cq = raw.get("read-contextual")
+    return (
+        _navigation_rules_refs_from_section(rr if isinstance(rr, list) else []),
+        _navigation_rules_refs_from_section(cq if isinstance(cq, list) else []),
+    )
+
+
 def _required_read_description_for_path(
-    p: str, merged_global: list[SkillFileRef], local_req: list[SkillFileRef], cfg_ext: ExtensionConfig
+    p: str,
+    merged_global: list[SkillFileRef],
+    local_req: list[SkillFileRef],
+    cfg_ext: ExtensionConfig,
+    nav_rules_required: list[SkillFileRef] | None = None,
 ) -> str:
+    nk = _norm_read_path(p)
+    if nav_rules_required:
+        for r in nav_rules_required:
+            if _norm_read_path(r.file) == nk and r.description:
+                return r.description
     for r in merged_global:
-        if r.file == p and r.description:
+        if _norm_read_path(r.file) == nk and r.description:
             return r.description
     for r in local_req:
-        if r.file == p and r.description:
+        if _norm_read_path(r.file) == nk and r.description:
             return r.description
     return _describe_path(cfg_ext, p)
 
 
 def generate_skills_metadata(target_root: Path, extension: str) -> list[SkillMetadata]:
     cfg_ext = _load_ext_config(target_root, extension)
+    maintainer_hints = _navigation_read_required_rule_hints_ordered(target_root)
+    global_streams = _extension_global_hint_streams_ordered(target_root)
+    local_raw = list(cfg_ext.hints.local) if cfg_ext.hints else []
+    merged_for_skill = _merge_hint_streams_ordered(
+        [*global_streams, local_raw, maintainer_hints]
+    )
+    skill_hints = (
+        _finalize_hints_for_skill_metadata(merged_for_skill) if merged_for_skill else []
+    )
+
     merged_global_required = _flatten_global_refs_ordered(
         target_root, get_required_read_global_all(target_root)
     )
     merged_global_auto = _flatten_global_refs_ordered(target_root, get_auto_read_global_all(target_root))
     local_required = get_required_read_ext_local(target_root, extension)
     local_auto = get_auto_read_local(target_root, extension)
+    nav_rules_required, nav_rules_contextual = _navigation_yaml_rules_refs(target_root)
 
     metas: list[SkillMetadata] = []
     for skill_path in list_skills(target_root, extension):
@@ -331,10 +563,19 @@ def generate_skills_metadata(target_root: Path, extension: str) -> list[SkillMet
                     continue
                 seen_norm.add(nk)
                 required_paths.append(fp)
+        for ref in nav_rules_required:
+            nk = _norm_read_path(ref.file)
+            if nk in seen_norm:
+                continue
+            seen_norm.add(nk)
+            required_paths.append(ref.file)
+
         required_out = [
             SkillFileRef(
                 file=p,
-                description=_required_read_description_for_path(p, merged_global_required, local_required, cfg_ext),
+                description=_required_read_description_for_path(
+                    p, merged_global_required, local_required, cfg_ext, nav_rules_required
+                ),
             )
             for p in required_paths
         ]
@@ -355,12 +596,19 @@ def generate_skills_metadata(target_root: Path, extension: str) -> list[SkillMet
                 continue
             seen_auto.add(key)
             auto_out.append(ar)
+        for ar in nav_rules_contextual:
+            key = _norm_read_path(ar.file)
+            if key in required_key_set or key in seen_auto:
+                continue
+            seen_auto.add(key)
+            auto_out.append(ar)
 
         metas.append(
             SkillMetadata(
                 name=raw.name,
                 description=raw.description,
                 content=raw.content,
+                hints=list(skill_hints),
                 required_read=required_out,
                 auto_read=auto_out,
             )
@@ -458,12 +706,11 @@ def get_core_agent_ignore(target_root: Path) -> list[str]:
     return list(core.agent_ignore)
 
 
-def merge_core_config_from_defaults(target_root: Path) -> None:
-    """Merge bundled default core config into ``spawn/.core/config.yaml``.
+def sync_core_config_from_defaults(target_root: Path) -> None:
+    """Overwrite ``spawn/.core/config.yaml`` with bundled default ``CoreConfig``.
 
-    ``version`` becomes the bundled default. ``agent-ignore`` is the bundled
-    list (in resource order) followed by any existing patterns not present in
-    the default set.
+    Validates that an existing repo file parses as ``CoreConfig`` before
+    replacing it so corrupted files are not silently clobbered.
     """
     path = _spawn(target_root) / ".core" / "config.yaml"
     if not path.is_file():
@@ -487,16 +734,10 @@ def merge_core_config_from_defaults(target_root: Path) -> None:
             "spawn/.core/config.yaml is empty or invalid; restore it or run spawn init again."
         )
     try:
-        current = CoreConfig.model_validate(raw_existing)
+        CoreConfig.model_validate(raw_existing)
     except Exception as e:
         raise SpawnError(f"invalid spawn/.core/config.yaml: {e}") from e
-    default_set = set(default_core.agent_ignore)
-    merged_ignore = list(default_core.agent_ignore)
-    for g in current.agent_ignore:
-        if g not in default_set:
-            merged_ignore.append(g)
-    out = CoreConfig(version=default_core.version, agent_ignore=merged_ignore)
-    save_yaml(path, out.model_dump(by_alias=True))
+    save_yaml(path, default_core.model_dump(by_alias=True))
 
 
 def get_ext_agent_ignore(target_root: Path, extension: str) -> list[str]:
@@ -778,7 +1019,13 @@ def save_extension_navigation(
     _strip_ext_sections_inplace(rr, extension)
     _strip_ext_sections_inplace(rc, extension)
     if read_required_files:
-        rr.append({"ext": extension, "files": _nav_refs_to_files(read_required_files)})
+        block: dict[str, Any] = {"ext": extension, "files": _nav_refs_to_files(read_required_files)}
+        cfg_opt = _optional_ext_config(target_root, extension)
+        if cfg_opt is not None:
+            hints_nav = _normalized_extension_global_hints_for_navigation(cfg_opt)
+            if hints_nav:
+                block["hints"] = hints_nav
+        rr.append(block)
     if read_contextual_files:
         req_norm = {_norm_read_path(r.file) for r in read_required_files}
         contextual_only = [
@@ -852,7 +1099,14 @@ def save_rules_navigation(target_root: Path) -> None:
             rk = posix_norm(str(entry['path']))
             exists = rk in paths_on_disk and (Path(target_root) / Path(rk)).is_file()
             if exists:
-                out.append({'path': rk, 'description': str(entry.get('description') or 'Local rule file.')})
+                row: dict[str, Any] = {
+                    'path': rk,
+                    'description': str(entry.get('description') or 'Local rule file.'),
+                }
+                hint_val = entry.get('hint')
+                if isinstance(hint_val, str):
+                    row['hint'] = hint_val
+                out.append(row)
             else:
                 warnings.warn(
                     f"Removed missing rule path from navigation: {rk}",
@@ -929,7 +1183,7 @@ __all__ = [
     "list_ides",
     "list_mcp",
     "list_skills",
-    "merge_core_config_from_defaults",
+    "sync_core_config_from_defaults",
     "METADATA_TEMP_MAX_AGE_SECONDS",
     "normalize_skill_name",
     "prune_metadata_temp",
@@ -937,6 +1191,7 @@ __all__ = [
     "remove_from_global_gitignore",
     "remove_ide_metadata_dir",
     "remove_ide_from_list",
+    "rollup_hints_for_agents",
     "save_agent_ignore_list",
     "save_extension_navigation",
     "save_git_ignore_list",
@@ -945,5 +1200,6 @@ __all__ = [
     "save_skills_rendered",
     "supported_ide_keys",
     "validate_rendered_identity",
+    "warn_if_agents_hints_exceed_measurement",
 ]
 

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/src/spawn_cli/ide/_helpers.py

@@ -36,7 +36,8 @@ def _mandatory_reads_for_render(skill: SkillMetadata) -> list[SkillFileRef]:
 
 def render_skill_md(skill: SkillMetadata) -> str:
     """Render normalized skill to Markdown with frontmatter, skill body,
-    mandatory reads (navigation path last), and contextual reads."""
+    hints (stable order from metadata), mandatory reads (navigation path last),
+    and contextual reads."""
     lines = [
         "---",
         f"name: {skill.name}",
@@ -45,8 +46,13 @@ def render_skill_md(skill: SkillMetadata) -> str:
         "",
         skill.content,
         "",
-        "Mandatory reads:",
     ]
+    if skill.hints:
+        lines += ["Hints:"]
+        for h in skill.hints:
+            lines += [f"- {h}"]
+        lines += [""]
+    lines += ["Mandatory reads:"]
     for ref in _mandatory_reads_for_render(skill):
         lines += [f"- `{ref.file}` - {ref.description}"]
     lines += [""]

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/src/spawn_cli/models/config.py

@@ -40,6 +40,15 @@ class SkillEntry(BaseModel):
     required_read: list[str] = Field(default_factory=list, alias="required-read")
 
 
+class ExtensionHints(BaseModel):
+    """Optional extension-authored hints (plain strings only)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    global_: list[str] = Field(default_factory=list, alias="global")
+    local: list[str] = Field(default_factory=list)
+
+
 class SetupConfig(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
 
@@ -62,6 +71,7 @@ class ExtensionConfig(BaseModel):
     git_ignore: list[str] = Field(default_factory=list, alias="git-ignore")
     skills: dict[str, SkillEntry] = Field(default_factory=dict)
     setup: Optional[SetupConfig] = None
+    hints: Optional[ExtensionHints] = None
 
 
 class CoreConfig(BaseModel):

{spawn_cli-0.1.7 → spawn_cli-0.1.9}/src/spawn_cli/models/skill.py

@@ -25,5 +25,6 @@ class SkillMetadata(BaseModel):
     name: str
     description: str
     content: str
+    hints: list[str] = Field(default_factory=list)
     required_read: list[SkillFileRef] = Field(default_factory=list)
     auto_read: list[SkillFileRef] = Field(default_factory=list)

{spawn_cli-0.1.7 → spawn_cli-0.1.9/src/spawn_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.7
+Version: 0.1.9
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -27,7 +27,7 @@ Spawn is a framework for building **AIDD** (AI-driven development) methodologies
 
 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.
+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.
 
@@ -189,7 +189,7 @@ 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, etc.
+- `**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.