convertible-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-05-28
+
+### Added
+
+- Layered per-model config: AGENTS instructions (`AGENTS.md` -> `AGENTS.convertible.md` -> `AGENTS.convertible.<model>.md` at the repo root, with a `~/.convertible/` fallback) and skills (`.convertible/skills/*.md` -> `.convertible/<model>/skills/*.md`) compose into the engine system prompt via `convertible/layers.py`
+- `convertible agents` and `convertible skills` introspection nouns (list + overview, `--json`, `--model`)
+- `Engine.system_prompt()` base-class helper injects the layered prompt for every engine (all-engines rule)
+
+### Changed
+
+- Both engines (mock, vllm-openai) now pass a model-specific `system_prompt` to the loop; behavior is byte-identical when no AGENTS/skills files exist
+
+## [0.5.0] - 2026-05-27
+
+### Changed
+
+- Bare `convertible` (no subcommand) now opens the interactive harness (the `session` palette) when run at a terminal — the natural "get in and drive" gesture. Piped, redirected, or otherwise non-interactive, it still prints usage, preserving the discoverable surface for scripts and agents. `-h/--help` is unaffected.
+- Reframed `convertible drive` help and `explain` text to lead with the goal/instruction ("drive toward a goal") rather than "run a repo task"; the repo is the target, not the headline. No behavior change.
+
 ## [0.4.0] - 2026-05-27
 
 ### Added

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/CLAUDE.md

@@ -34,6 +34,16 @@ The car metaphor *is* the architecture:
   code path, no daemon.
 - **Config resolution** — `convertible/configdir.py`: repo-level
   `.convertible/` overrides user-level `~/.convertible/`.
+- **Layered per-model config** — `convertible/layers.py`: AGENTS instructions
+  (`AGENTS.md` → `AGENTS.convertible.md` → `AGENTS.convertible.<model>.md`, at
+  the repo root with a `~/.convertible/` fallback) and skills
+  (`.convertible/skills/*.md` → `.convertible/<model>/skills/*.md`) compose into
+  the engine system prompt. Resolution builds exact paths for the current model
+  and never globs sibling models — per-model isolation is structural. Injected
+  once on the `Engine` base class (`system_prompt()`), so every engine inherits
+  it (all-engines rule). Surfaced via the `agents` / `skills` introspection
+  nouns. **MCP layering is not built** — convertible reads no `mcp.json` and has
+  no `mcp` verb; a live MCP client is a re-spec (see scope below).
 
 The buildable spec and plan this implementation converged from live in
 [`docs/specs/`](docs/specs/) and [`docs/plans/`](docs/plans/) (authored via the
@@ -43,14 +53,20 @@ The buildable spec and plan this implementation converged from live in
 
 In scope: the chassis, the entry-point wheel contract, exactly two engines
 (`mock`, `vllm-openai`), the git/PR handoff, command templates, lifecycle
-hooks, and the foreground interactive palette.
+hooks, the foreground interactive palette, and layered per-model AGENTS/skills
+config (`convertible/layers.py`).
 
 **Out of scope for v0** — do not add without re-speccing: a multi-engine
 router/policy "gearbox", an execution sandbox, a daemon/server mode,
-Codex/Claude/Gemini drivers, and a per-repo hook trust gate / `--no-hooks`
+Codex/Claude/Gemini drivers, a per-repo hook trust gate / `--no-hooks`
 escape hatch (planned follow-up hardening — not yet built; document this gap
-honestly, never invent a `--no-hooks` flag). Adding an excluded feature means
-scope crept.
+honestly, never invent a `--no-hooks` flag), and an **MCP execution runtime**
+(a live MCP client — stdio/socket transport, tool discovery, dynamic tool
+registration). The layered config ships AGENTS + skills only; `mcp.json` is
+**not** read and there is no `mcp` verb. A live MCP client would breach the
+no-deps / no-socket / no-daemon conventions and needs its own spec — document
+this gap honestly, never invent an `mcp` surface. Adding an excluded feature
+means scope crept.
 
 ## The all-engines rule
 

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convertible-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
 Project-URL: Homepage, https://github.com/agentculture/convertible
 Project-URL: Issues, https://github.com/agentculture/convertible/issues
@@ -17,6 +17,27 @@ Description-Content-Type: text/markdown
 
 # convertible
 
+```text
+                      ,"^,::,:::::I::::::^                             
+                     ^!'`       `"^,.    ::`                           
+ `,;;i;,,'  .!^'`",. "<,"  "              ;,^                          
+ ^       '"^";"^```,":::','"'^`"."'.,:^,i::,"".                        
+.I.   '    I-l '",I;!ii,I.,,l;;IlIl:i!:::::,,,^^;",,'                  
+ '^ ""::``':.        .`";,"```"^..                  '^^'":,''.         
+   ::,`;!"..^..'^"^    .'  ..""   ..`"^                    ..`"`'"".   
+    ;;l!i:' ^        '^"`.       `"`..   ',^..                   `` '^ 
+     :i>I!lII".        .' .''^`       '`^'    .`".             ^. :;lI.
+     ",l!`;"':l;,,`.   .'       '",'.      ^...'^`'"...^l'":;Ii!!l:!';.
+      ^''^., '`^^`:l;"^"',!~ .^^^,""..'`^. .^l,I''^.:l!;;;i>|+,!IlI::^ 
+                  `;. :>i":` "`, ',^^"     ";  I.'. :::"^:;iil;'":^; '"
+                      '^"'"IlI,.:,::;:'  .`;"!l:``,,"``',,,^,,:ll!,,l^ 
+                           ":^:,I^:"!;::  :I>l:::"`""::,:I>!<i^ " ;.   
+                              ",;"Il;i^:  ',":;"`'`'^,   ><[il```'     
+                              " ;;I"l:^.^;^''lI"   :^::",:,'           
+                               ,`:;,I.^ ''                             
+                                `.   " "                               
+```
+
 > Convertible CLI is a swappable coder-agent harness that turns different models
 > into repo workers behind one shared task contract.
 >
@@ -106,10 +127,13 @@ engine, so it binds equally to `mock`, `vllm-openai`, and any future wheel.
 uv sync
 uv run pytest -n auto                          # full suite, no network needed
 
+# Open the interactive harness (the session palette) at a terminal:
+uv run convertible
+
 # Discover the engines installed in this environment:
 uv run convertible wheels list
 
-# Drive a task with the deterministic mock engine (no model, no network):
+# Drive toward a goal with the deterministic mock engine (no model, no network):
 uv run convertible drive "add a CONTRIBUTING.md stub" --repo . --engine mock --no-pr
 ```
 
@@ -297,10 +321,54 @@ loop, hooks, and artifact — no parallel code path):
 uv run convertible session --repo /path/to/repo --engine vllm-openai
 ```
 
+Running `convertible` with no arguments **at a terminal** opens this same palette
+(with the default engine and repo) — the natural "get in and drive" gesture.
+Piped, redirected, or otherwise non-interactive, bare `convertible` prints usage
+instead, so scripts and agents keep a discoverable surface.
+
 The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
 
+## Per-model instructions & skills
+
+Convertible composes a model-specific **system prompt** for every drive from two
+layered families, resolved *relative to the model currently driving*. Strict
+per-model isolation: driving model X reads only X's overlay plus the shared base
+— it never even opens model Y's files (isolation is structural, built from exact
+paths, not filtered).
+
+**AGENTS instructions** cascade from the **repo root** (the cross-tool standard
+location — sibling agent tools read `AGENTS.md` there too), general → specific,
+with a `~/.convertible/` user-level fallback:
+
+```text
+AGENTS.md                       # shared base
+AGENTS.convertible.md           # convertible overlay
+AGENTS.convertible.<model>.md   # model overlay
+```
+
+**Skills** are markdown capability docs under `.convertible/`, folded into the
+prompt as a compact name + one-line-summary catalog (a skill is instructional
+text only — there is no skill *execution* in v0):
+
+```text
+.convertible/skills/*.md            # base
+.convertible/<model>/skills/*.md    # model overlay (shadows base by stem)
+```
+
+`<model>` is sanitized to a filename-safe token (e.g. `Qwen/Qwen3-32B` →
+`Qwen-Qwen3-32B`). Inspect what resolves for a model:
+
+```bash
+uv run convertible agents list --model Qwen/Qwen3-32B --repo .
+uv run convertible skills list --model Qwen/Qwen3-32B --repo .
+```
+
+> **MCP layering is not built yet.** Convertible does not read `mcp.json` or
+> connect to any MCP server today; a live MCP client needs its own spec. There
+> is no `mcp` verb — don't rely on a non-existent surface.
+
 ## ⚠ Security: repo-shipped hooks run by default
 
 > **This is a code-execution risk. Read before driving an untrusted repo.**
@@ -333,12 +401,16 @@ rely on a non-existent flag.
 
 | Verb | What it does |
 |------|--------------|
-| `drive <instruction>` | Run a repo task through a coder engine; write the artifact; hand off. |
+| `drive <goal>` | Drive toward a goal/instruction: work autonomously through a coder engine; write the artifact; hand off. |
 | `drive --command <name> [args…]` | Expand a saved command template and drive it. |
 | `commands list` | List discovered command templates for a repo. |
 | `commands overview` | Describe the commands surface. |
 | `hooks list` | List configured hook entries for a repo. |
 | `hooks overview` | Describe the hooks surface. |
+| `agents list` | List resolved AGENTS instruction layers for a model. |
+| `agents overview` | Describe the agents surface. |
+| `skills list` | List resolved skill docs for a model. |
+| `skills overview` | Describe the skills surface. |
 | `session` | Open a foreground interactive palette. |
 | `wheels list` | List discovered engine wheels (the garage). |
 | `whoami` | Report this agent's nick, version, backend, and model. |

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/README.md

@@ -1,5 +1,26 @@
 # convertible
 
+```text
+                      ,"^,::,:::::I::::::^                             
+                     ^!'`       `"^,.    ::`                           
+ `,;;i;,,'  .!^'`",. "<,"  "              ;,^                          
+ ^       '"^";"^```,":::','"'^`"."'.,:^,i::,"".                        
+.I.   '    I-l '",I;!ii,I.,,l;;IlIl:i!:::::,,,^^;",,'                  
+ '^ ""::``':.        .`";,"```"^..                  '^^'":,''.         
+   ::,`;!"..^..'^"^    .'  ..""   ..`"^                    ..`"`'"".   
+    ;;l!i:' ^        '^"`.       `"`..   ',^..                   `` '^ 
+     :i>I!lII".        .' .''^`       '`^'    .`".             ^. :;lI.
+     ",l!`;"':l;,,`.   .'       '",'.      ^...'^`'"...^l'":;Ii!!l:!';.
+      ^''^., '`^^`:l;"^"',!~ .^^^,""..'`^. .^l,I''^.:l!;;;i>|+,!IlI::^ 
+                  `;. :>i":` "`, ',^^"     ";  I.'. :::"^:;iil;'":^; '"
+                      '^"'"IlI,.:,::;:'  .`;"!l:``,,"``',,,^,,:ll!,,l^ 
+                           ":^:,I^:"!;::  :I>l:::"`""::,:I>!<i^ " ;.   
+                              ",;"Il;i^:  ',":;"`'`'^,   ><[il```'     
+                              " ;;I"l:^.^;^''lI"   :^::",:,'           
+                               ,`:;,I.^ ''                             
+                                `.   " "                               
+```
+
 > Convertible CLI is a swappable coder-agent harness that turns different models
 > into repo workers behind one shared task contract.
 >
@@ -89,10 +110,13 @@ engine, so it binds equally to `mock`, `vllm-openai`, and any future wheel.
 uv sync
 uv run pytest -n auto                          # full suite, no network needed
 
+# Open the interactive harness (the session palette) at a terminal:
+uv run convertible
+
 # Discover the engines installed in this environment:
 uv run convertible wheels list
 
-# Drive a task with the deterministic mock engine (no model, no network):
+# Drive toward a goal with the deterministic mock engine (no model, no network):
 uv run convertible drive "add a CONTRIBUTING.md stub" --repo . --engine mock --no-pr
 ```
 
@@ -280,10 +304,54 @@ loop, hooks, and artifact — no parallel code path):
 uv run convertible session --repo /path/to/repo --engine vllm-openai
 ```
 
+Running `convertible` with no arguments **at a terminal** opens this same palette
+(with the default engine and repo) — the natural "get in and drive" gesture.
+Piped, redirected, or otherwise non-interactive, bare `convertible` prints usage
+instead, so scripts and agents keep a discoverable surface.
+
 The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
 
+## Per-model instructions & skills
+
+Convertible composes a model-specific **system prompt** for every drive from two
+layered families, resolved *relative to the model currently driving*. Strict
+per-model isolation: driving model X reads only X's overlay plus the shared base
+— it never even opens model Y's files (isolation is structural, built from exact
+paths, not filtered).
+
+**AGENTS instructions** cascade from the **repo root** (the cross-tool standard
+location — sibling agent tools read `AGENTS.md` there too), general → specific,
+with a `~/.convertible/` user-level fallback:
+
+```text
+AGENTS.md                       # shared base
+AGENTS.convertible.md           # convertible overlay
+AGENTS.convertible.<model>.md   # model overlay
+```
+
+**Skills** are markdown capability docs under `.convertible/`, folded into the
+prompt as a compact name + one-line-summary catalog (a skill is instructional
+text only — there is no skill *execution* in v0):
+
+```text
+.convertible/skills/*.md            # base
+.convertible/<model>/skills/*.md    # model overlay (shadows base by stem)
+```
+
+`<model>` is sanitized to a filename-safe token (e.g. `Qwen/Qwen3-32B` →
+`Qwen-Qwen3-32B`). Inspect what resolves for a model:
+
+```bash
+uv run convertible agents list --model Qwen/Qwen3-32B --repo .
+uv run convertible skills list --model Qwen/Qwen3-32B --repo .
+```
+
+> **MCP layering is not built yet.** Convertible does not read `mcp.json` or
+> connect to any MCP server today; a live MCP client needs its own spec. There
+> is no `mcp` verb — don't rely on a non-existent surface.
+
 ## ⚠ Security: repo-shipped hooks run by default
 
 > **This is a code-execution risk. Read before driving an untrusted repo.**
@@ -316,12 +384,16 @@ rely on a non-existent flag.
 
 | Verb | What it does |
 |------|--------------|
-| `drive <instruction>` | Run a repo task through a coder engine; write the artifact; hand off. |
+| `drive <goal>` | Drive toward a goal/instruction: work autonomously through a coder engine; write the artifact; hand off. |
 | `drive --command <name> [args…]` | Expand a saved command template and drive it. |
 | `commands list` | List discovered command templates for a repo. |
 | `commands overview` | Describe the commands surface. |
 | `hooks list` | List configured hook entries for a repo. |
 | `hooks overview` | Describe the hooks surface. |
+| `agents list` | List resolved AGENTS instruction layers for a model. |
+| `agents overview` | Describe the agents surface. |
+| `skills list` | List resolved skill docs for a model. |
+| `skills overview` | Describe the skills surface. |
 | `session` | Open a foreground interactive palette. |
 | `wheels list` | List discovered engine wheels (the garage). |
 | `whoami` | Report this agent's nick, version, backend, and model. |

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/convertible/cli/__init__.py

@@ -61,7 +61,19 @@ def _argv_has_json(argv: list[str] | None) -> bool:
     return any(t == "--json" or t.startswith("--json=") for t in tokens)
 
 
+def _stdio_is_interactive() -> bool:
+    """Whether stdin and stdout are both interactive terminals.
+
+    Bare ``convertible`` opens the interactive harness only at a real terminal;
+    isolated as a module function so tests can force the interactive branch
+    without a TTY (mirrors :func:`convertible.cli._banner._isatty`). Both streams
+    must be a TTY: the palette reads from stdin and renders its chrome to stdout.
+    """
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
 def _build_parser() -> argparse.ArgumentParser:
+    from convertible.cli._commands import agents as _agents_group
     from convertible.cli._commands import cli as _cli_group
     from convertible.cli._commands import commands as _commands_group
     from convertible.cli._commands import doctor as _doctor_cmd
@@ -71,6 +83,7 @@ def _build_parser() -> argparse.ArgumentParser:
     from convertible.cli._commands import learn as _learn_cmd
     from convertible.cli._commands import overview as _overview_cmd
     from convertible.cli._commands import session as _session_cmd
+    from convertible.cli._commands import skills as _skills_group
     from convertible.cli._commands import wheels as _wheels_group
     from convertible.cli._commands import whoami as _whoami_cmd
 
@@ -99,6 +112,9 @@ def _build_parser() -> argparse.ArgumentParser:
     # Extensibility layer: command templates + lifecycle hooks.
     _commands_group.register(sub)
     _hooks_group.register(sub)
+    # Layered per-model config: AGENTS instructions + skills.
+    _agents_group.register(sub)
+    _skills_group.register(sub)
     # Interactive foreground palette (c28/R8).
     _session_cmd.register(sub)
 
@@ -136,6 +152,14 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     if args.command is None:
+        # Bare `convertible` opens the interactive harness at a terminal; piped /
+        # redirected / non-interactive it prints usage so scripts and agents keep
+        # a discoverable surface. `-h/--help` is handled by argparse before here,
+        # so the help surface (and the teken rubric, which probes --help) stay
+        # available either way. Re-parsing ["session"] reuses the session
+        # subparser's defaults and func wiring — no parallel code path.
+        if _stdio_is_interactive():
+            return _dispatch(parser.parse_args(["session"]))
         parser.print_help()
         return 0
 

convertible_cli-0.6.0/convertible/cli/_commands/agents.py

@@ -0,0 +1,109 @@
+"""``convertible agents`` — inspect layered AGENTS instruction files.
+
+``agents list`` resolves the AGENTS instruction cascade for a model
+(``AGENTS.md`` -> ``AGENTS.convertible.md`` -> ``AGENTS.convertible.<model>.md``;
+repo root with a ``~/.convertible/`` fallback) and reports the layers that
+exist, in general -> specific order. ``agents overview`` describes the noun
+(satisfying the agent-first rubric: any noun with action-verbs must also expose
+``overview``).
+
+These layers are composed (with the engine default and the skills catalog) into
+the system prompt every drive sends — so what ``agents list`` reports for a model
+is exactly what that model is instructed with. Per-model isolation is structural:
+only the named model's overlay is read, never a sibling model's.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from convertible.cli._commands.overview import emit_overview
+from convertible.cli._output import emit_result
+from convertible.config import EngineConfig
+from convertible.layers import resolve_agents
+
+
+def _agents_sections() -> list[dict[str, object]]:
+    return [
+        {
+            "title": "What it does",
+            "items": [
+                "Resolves AGENTS instruction layers for the current model",
+                "Cascade (general -> specific): AGENTS.md, AGENTS.convertible.md, "
+                "AGENTS.convertible.<model>.md",
+                "Read from the repo root, with a ~/.convertible/ user-level fallback",
+                "Composed into the system prompt every drive sends to the engine",
+            ],
+        },
+        {
+            "title": "Per-model isolation",
+            "items": [
+                "<model> is sanitized (e.g. 'Qwen/Qwen3-32B' -> 'Qwen-Qwen3-32B')",
+                "Only the named model's overlay is read — never a sibling model's",
+                "MCP layering is not built yet (no mcp.json reader); tracked separately",
+            ],
+        },
+        {
+            "title": "Verbs",
+            "items": [
+                "agents list [--model M] [--repo PATH] — list resolved AGENTS layers",
+                "agents overview — describe the agents surface (this command)",
+            ],
+        },
+    ]
+
+
+def cmd_agents_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "convertible agents",
+        _agents_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def cmd_agents_list(args: argparse.Namespace) -> int:
+    repo = Path(getattr(args, "repo", ".")).expanduser()
+    model = getattr(args, "model", None) or EngineConfig.resolve().model
+    json_mode = bool(getattr(args, "json", False))
+
+    layers = resolve_agents(repo, model)
+
+    if json_mode:
+        items = [{"scope": layer.scope, "path": str(layer.path)} for layer in layers]
+        emit_result({"model": model, "agents": items}, json_mode=True)
+    elif not layers:
+        emit_result("(no AGENTS layers found)", json_mode=False)
+    else:
+        lines = [f"{layer.scope}\t{layer.path}" for layer in layers]
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    return cmd_agents_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "agents",
+        help="Inspect layered AGENTS instruction files (see 'convertible agents overview').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=_no_verb, json=False)
+    noun_sub = p.add_subparsers(dest="agents_command", parser_class=type(p))
+
+    lst = noun_sub.add_parser("list", help="List resolved AGENTS instruction layers.")
+    lst.add_argument("--repo", default=".", help="Path to the target repository (default: cwd).")
+    lst.add_argument(
+        "--model",
+        default=None,
+        help="Model to resolve layers for (default: the resolved engine model).",
+    )
+    lst.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    lst.set_defaults(func=cmd_agents_list)
+
+    ov = noun_sub.add_parser("overview", help="Describe the agents surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_agents_overview)

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/convertible/cli/_commands/drive.py

@@ -224,7 +224,10 @@ def cmd_drive(args: argparse.Namespace) -> int:
 def register(sub: argparse._SubParsersAction) -> None:
     p = sub.add_parser(
         "drive",
-        help="Run a repo task through a coder engine and hand off the result.",
+        help=(
+            "Drive toward a goal: work autonomously on a request or instruction "
+            "through a coder engine, then hand off the result."
+        ),
     )
     # ``instruction`` is now zero-or-more positional tokens (nargs="*") so
     # ``--command`` can be the sole input without argparse raising an error.
@@ -232,7 +235,7 @@ def register(sub: argparse._SubParsersAction) -> None:
         "instruction",
         nargs="*",
         help=(
-            "What the engine should do in the repo.  "
+            "A goal or instruction to pursue autonomously.  "
             "Mutually exclusive with --command.  "
             "When --command is used, any positional tokens are passed as template arguments."
         ),

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/convertible/cli/_commands/overview.py

@@ -27,6 +27,8 @@ _ARTIFACTS = [
 _VERBS = [
     "drive <instruction> — run a repo task through a coder engine",
     "wheels list — list discovered engine wheels",
+    "agents list — inspect layered AGENTS instruction files for a model",
+    "skills list — inspect layered skill docs for a model",
     "whoami — identity probe (nick, version, backend, model)",
     "learn — structured self-teaching prompt",
     "explain <path> — markdown docs for a topic",

convertible_cli-0.6.0/convertible/cli/_commands/skills.py

@@ -0,0 +1,107 @@
+"""``convertible skills`` — inspect layered skill docs.
+
+``skills list`` resolves the skill docs for a model — ``.convertible/skills/*.md``
+(base) overlaid by ``.convertible/<model>/skills/*.md`` (model overlay shadows
+base by stem) — and reports them with their winning scope. ``skills overview``
+describes the noun (satisfying the agent-first rubric).
+
+A skill is purely instructional: convertible folds a compact name +
+one-line-summary catalog of the resolved skills into the system prompt every
+drive sends. There is no skill *execution* model (an execution sandbox is out of
+v0 scope); invokable skills are a tracked follow-up.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from convertible.cli._commands.overview import emit_overview
+from convertible.cli._output import emit_result
+from convertible.config import EngineConfig
+from convertible.layers import resolve_skills
+
+
+def _skills_sections() -> list[dict[str, object]]:
+    return [
+        {
+            "title": "What it does",
+            "items": [
+                "Resolves skill docs for the current model",
+                "base: .convertible/skills/*.md",
+                "model overlay: .convertible/<model>/skills/*.md (shadows base by stem)",
+                "Folded into the system prompt as a name + one-line-summary catalog",
+            ],
+        },
+        {
+            "title": "Scope",
+            "items": [
+                "A skill is instructional text only — no execution model in v0",
+                "<model> is sanitized; only the named model's overlay is read",
+                "Invokable skills (skills as procedures) are a tracked follow-up",
+            ],
+        },
+        {
+            "title": "Verbs",
+            "items": [
+                "skills list [--model M] [--repo PATH] — list resolved skills",
+                "skills overview — describe the skills surface (this command)",
+            ],
+        },
+    ]
+
+
+def cmd_skills_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "convertible skills",
+        _skills_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def cmd_skills_list(args: argparse.Namespace) -> int:
+    repo = Path(getattr(args, "repo", ".")).expanduser()
+    model = getattr(args, "model", None) or EngineConfig.resolve().model
+    json_mode = bool(getattr(args, "json", False))
+
+    skills = resolve_skills(repo, model)
+    ordered = [skills[name] for name in sorted(skills)]
+
+    if json_mode:
+        items = [{"name": s.name, "scope": s.scope} for s in ordered]
+        emit_result({"model": model, "skills": items}, json_mode=True)
+    elif not ordered:
+        emit_result("(no skills found)", json_mode=False)
+    else:
+        lines = [f"{s.scope}\t{s.name}" for s in ordered]
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    return cmd_skills_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "skills",
+        help="Inspect layered skill docs (see 'convertible skills overview').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=_no_verb, json=False)
+    noun_sub = p.add_subparsers(dest="skills_command", parser_class=type(p))
+
+    lst = noun_sub.add_parser("list", help="List resolved skill docs.")
+    lst.add_argument("--repo", default=".", help="Path to the target repository (default: cwd).")
+    lst.add_argument(
+        "--model",
+        default=None,
+        help="Model to resolve skills for (default: the resolved engine model).",
+    )
+    lst.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    lst.set_defaults(func=cmd_skills_list)
+
+    ov = noun_sub.add_parser("overview", help="Describe the skills surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_skills_overview)

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/convertible/engine.py

@@ -36,3 +36,21 @@ class Engine(abc.ABC):
         same result shape regardless of the model underneath.
         """
         raise NotImplementedError
+
+    def system_prompt(self, task: Task, config: EngineConfig) -> str | None:
+        """Compose the model-specific system prompt (AGENTS + skills layers).
+
+        Resolved here on the base class — not in each ``drive`` — so *every*
+        engine wheel inherits the layered instruction injection for free (the
+        all-engines rule), mirroring how hooks are inherited via the loop.
+        Subclasses pass the return value as ``system_prompt=`` to
+        :func:`convertible.loop.run`. Returns ``None`` when no AGENTS/skills
+        layers exist for ``config.model``, so the loop falls back to its own
+        default and behavior is byte-identical to a layer-free run.
+        """
+        # Imported lazily to keep this module's import surface minimal and avoid
+        # pulling the whole loop in at engine import time.
+        from convertible.layers import system_prompt_for
+        from convertible.loop import _DEFAULT_SYSTEM
+
+        return system_prompt_for(task.repo_path, config.model, base=_DEFAULT_SYSTEM)

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/convertible/engines/mock.py

@@ -51,4 +51,9 @@ class MockEngine(Engine):
     name = "mock"
 
     def drive(self, task: Task, config: EngineConfig) -> TaskResult:
-        return run(_script(task), task, max_steps=config.max_steps)
+        return run(
+            _script(task),
+            task,
+            max_steps=config.max_steps,
+            system_prompt=self.system_prompt(task, config),
+        )

{convertible_cli-0.4.0 → convertible_cli-0.6.0}/convertible/engines/vllm_openai.py

@@ -94,4 +94,9 @@ class VllmOpenAIEngine(Engine):
         return complete
 
     def drive(self, task: Task, config: EngineConfig) -> TaskResult:
-        return run(self._make_complete(config), task, max_steps=config.max_steps)
+        return run(
+            self._make_complete(config),
+            task,
+            max_steps=config.max_steps,
+            system_prompt=self.system_prompt(task, config),
+        )