diff --git a/skills/agent-review/SKILL.md b/skills/agent-review/SKILL.md index fd182306c..912985adc 100644 --- a/skills/agent-review/SKILL.md +++ b/skills/agent-review/SKILL.md @@ -10,6 +10,13 @@ description: >- # Judge Autoform work as an agent +There is no `autoform` on `PATH` in a Lean project. Run every `autoform` +command, from the project under review, as +`uv run --project "" autoform` followed by its arguments, +where `` is the absolute plugin root: the directory that +holds this skill's `skills/` folder, along with `pyproject.toml` and +`autoform_cli/`. Give a subagent that root and this prefix with its task. + Select the rubric from the artifact under review. - For a roadmap or blueprint, read [roadmap quality](references/roadmap-quality.md), diff --git a/skills/formalize/SKILL.md b/skills/formalize/SKILL.md index 14a8b2ca5..4d940ab2f 100644 --- a/skills/formalize/SKILL.md +++ b/skills/formalize/SKILL.md @@ -8,10 +8,16 @@ description: >- # Formalize the Markdown roadmap -Treat `blueprint/roadmap/**/*.md` as the sole durable work graph. Resolve the -absolute installed plugin root and run commands through the invocation contract -in the [CLI reference](../../autoform_cli/README.md#commands), from the Lean -project. `` is the absolute path of the checkout being edited; for a +There is no `autoform` on `PATH` in a Lean project. Run every `autoform` +command, from the Lean project, as +`uv run --project "" autoform` followed by its arguments, +where `` is the absolute plugin root: the directory that +holds this skill's `skills/` folder, along with `pyproject.toml` and +`autoform_cli/`. Give a subagent that root and this prefix with its task. + +Treat `blueprint/roadmap/**/*.md` as the sole durable work graph. The +[CLI reference](../../autoform_cli/README.md#commands) documents the commands. +`` is the absolute path of the checkout being edited; for a subagent, that is its own worktree. Start by running `autoform work list --lean-root --json` and inspect a selected leaf with `autoform work context --lean-root --json`. The diff --git a/skills/human-review/SKILL.md b/skills/human-review/SKILL.md index 00c8f105e..69acc151a 100644 --- a/skills/human-review/SKILL.md +++ b/skills/human-review/SKILL.md @@ -15,6 +15,14 @@ existing Autoform vault and site configuration; hand missing infrastructure to Setup. Keep the Markdown vault as the source of truth and regenerate only derived review views. +There is no `autoform` on `PATH` in a Lean project. Run every `autoform` and +`autoform-visualize` command, from ``, as +`uv run --project "" autoform` followed by its arguments +(with `autoform-visualize` in place of `autoform` for the graph), where +`` is the absolute plugin root: the directory that holds +this skill's `skills/` folder, along with `pyproject.toml` and `autoform_cli/`. +Give a subagent that root and this prefix with its task. + Regenerate the review views from ``: validate the blueprint, refresh the Mermaid graph with `autoform-visualize` so Obsidian shows current dependencies, render the site source, then strict-build the site. Follow the diff --git a/skills/roadmap/SKILL.md b/skills/roadmap/SKILL.md index a906cabf0..1e29b249f 100644 --- a/skills/roadmap/SKILL.md +++ b/skills/roadmap/SKILL.md @@ -17,6 +17,13 @@ syntax or CLI usage is needed, and the [worked example](references/cabannes-thesis-roadmap.md) only when a concrete source-to-DAG pattern would help. +There is no `autoform` on `PATH` in a Lean project. Run every `autoform` +command, from the Lean project root, as +`uv run --project "" autoform` followed by its arguments, +where `` is the absolute plugin root: the directory that +holds this skill's `skills/` folder, along with `pyproject.toml` and +`autoform_cli/`. Give a subagent that root and this prefix with its task. + ## Own the whole pass Honor a request explicitly limited to inspection, audit, status, or diff --git a/tests/test_skill_examples.py b/tests/test_skill_examples.py index 021ee02c8..69b880698 100644 --- a/tests/test_skill_examples.py +++ b/tests/test_skill_examples.py @@ -1174,20 +1174,25 @@ def test_cli_reference_documents_only_commands_that_exist(repo_root: Path) -> No assert exit_info.value.code == 0, f"reference documents unknown command: {' '.join(invocation)}" +_LAUNCHER = 'uv run --project "" autoform`' + + def test_skills_delegate_the_command_line_to_the_reference(repo_root: Path) -> None: """Skills state intent and link to the reference; they do not restate flags. Duplicated invocations are what let the CLI move underneath the agent's instructions, so a skill that needs the command line must cite the - reference instead of copying it. + reference instead of copying it. The bare launcher is not a flag, so a skill + may state it once. """ citing = 0 for skill in sorted((repo_root / "skills").glob("*/SKILL.md")): - text = skill.read_text(encoding="utf-8") + text = " ".join(skill.read_text(encoding="utf-8").split()) if skill.parent.name == "setup": assert text.count("uv run --project") == 3 else: - assert "uv run --project" not in text, ( + invocations = re.findall(r"uv run --project[^`]*`", text) + assert invocations in ([], [_LAUNCHER]), ( f"{skill.relative_to(repo_root)} restates a CLI invocation; " "link to autoform_cli/README.md#commands instead" ) @@ -1196,6 +1201,31 @@ def test_skills_delegate_the_command_line_to_the_reference(repo_root: Path) -> N assert citing >= 3 +def test_skills_that_run_the_cli_state_how_to_launch_it(repo_root: Path) -> None: + """A consumer project has no `autoform` on `PATH`. + + Agents that read a bare `autoform work list` run `which autoform` and then + guess; in trials every fresh Roadmap and Formalize session did, and some + never reached the CLI. So every skill whose instructions or references name + a command states the launcher once, names the plugin root without relying + on how a host presents the skill, and hands both to its subagents. Setup + spells out its own full invocations; Develop Plugin works inside the plugin + checkout, where `uv run autoform` already resolves. + """ + running = { + skill.name + for skill in (repo_root / "skills").iterdir() + if any(re.search(r"`autoform[ -][a-z]", path.read_text(encoding="utf-8")) for path in skill.rglob("*.md")) + } + assert {"roadmap", "formalize", "agent-review", "human-review"} <= running + for name in sorted(running - {"setup", "develop-plugin"}): + flat = " ".join((repo_root / "skills" / name / "SKILL.md").read_text(encoding="utf-8").split()) + assert f"`{_LAUNCHER}" in flat, f"{name} does not state the launcher" + assert "no `autoform` on `PATH`" in flat + assert "the directory that holds this skill's `skills/` folder, along with `pyproject.toml`" in flat + assert "Give a subagent that root and this prefix with its task." in flat + + def test_skill_links_into_the_cli_reference_land_on_a_section(repo_root: Path) -> None: """A skill that cites a reference section must not point at a renamed one.