ralphctl 0.8.3 → 0.8.4

package/dist/prompts/detect-scripts/template.md

@@ -1,19 +1,29 @@
-# Repository Script Detection Protocol
-
+<role>
 You are a senior engineer inventorying a single repository so the harness can run the right shell
-commands at sprint start (setup) and after every task (verification). For any repo that has a
-manifest or a coding-agent context file, you should typically emit both tags — silence is reserved
-for repos where the project itself is silent on those topics.
-
-1. **`<setup-script>`** — one shell line the harness runs **once** before each sprint to prepare
-   the working tree (typically dependency install via whichever package manager / build tool the
-   project actually uses). Omit only when the project itself documents no setup step.
-2. **`<verify-script>`** — one shell line the harness runs as the **post-task gate**. Chain the
-   typecheck / lint / test commands the project actually exposes using `&&` so the harness sees
-   the first failure. Omit only when the project documents no such commands at all.
+commands at sprint start (setup) and after every task (verification). This is a single-shot,
+read-only extraction — no code changes, no file writes except `signals.json`.
+</role>
 
 {{HARNESS_CONTEXT}}
 
+<goal>
+Inspect the repository at `{{REPOSITORY_PATH}}` and propose a single-line setup script and a
+single-line verify script by writing `signals.json` to the output directory.
+</goal>
+
+<success_criteria>
+
+- Every proposed command is traceable to a file in the repository (context file or manifest).
+- Each script is a single shell line — no here-docs, no multi-line bodies.
+- Setup and verify commands reflect the project's own documented contract, not inferred guesses.
+- If no evidence exists for a script class, that signal is absent rather than fabricated.
+
+</success_criteria>
+
+<inputs>
+<repository_path>{{REPOSITORY_PATH}}</repository_path>
+</inputs>
+
 <constraints>
 
 **This invocation is read-only.** Do not modify the working tree, do not create files, do not run
@@ -45,8 +55,8 @@ or vendored directories.
 
 **Emit when documented, omit when silent.** When the manifest or context files name a class of
 commands, emit the tag — even when multiple candidates exist, pick the one most consistent with
-what the project documented. Omit a tag only when the project's own files are silent on that class
-entirely.
+what the project documented. Omit a signal only when the project's own files are silent on that
+class entirely.
 
 **Script safety.** Reject pipe-to-shell shapes (`curl … | sh`, `wget -O- … | bash`), `eval`, and
 `rm -rf`. One shell line per script — multi-line bodies, sub-shells, and heredocs are out of
@@ -63,39 +73,94 @@ project's docs name them as part of the verification gate.
 
 </constraints>
 
+<output_contract>
+
+{{OUTPUT_CONTRACT_SECTION}}
+
+Emit only `setup-script`, `verify-script`, and `note` signals — no other signal kinds. If you
+cannot determine an appropriate command for a script class, omit that signal rather than guessing.
+If you cannot make any determination at all (e.g. the repository is empty or entirely undocumented),
+emit a single `note` signal with a brief explanation and stop — do not invent commands.
+
+</output_contract>
+
 <example>
 When `CLAUDE.md` (or equivalent) contains "Verification: `<tool> typecheck && <tool> lint &&
-<tool> test`" and `package.json` (or equivalent manifest) declares those scripts:
-
-```
-<setup-script><tool> install</setup-script>
-<verify-script><tool> typecheck && <tool> lint && <tool> test</verify-script>
-<note>Commands lifted verbatim from CLAUDE.md.</note>
+`<tool> test`" and the manifest declares those scripts:
+
+```json
+{
+  "signals": [
+    {
+      "type": "setup-script",
+      "command": "<tool> install",
+      "timestamp": "..."
+    },
+    {
+      "type": "verify-script",
+      "command": "<tool> typecheck && <tool> lint && <tool> test",
+      "timestamp": "..."
+    },
+    {
+      "type": "note",
+      "text": "Commands lifted verbatim from CLAUDE.md.",
+      "timestamp": "..."
+    }
+  ]
+}
 ```
 
 When only a manifest exists with install + test scripts and no context file:
 
-```
-<setup-script><tool> install</setup-script>
-<verify-script><tool> test</verify-script>
-<note>No context file found; commands inferred from package.json scripts.</note>
+```json
+{
+  "signals": [
+    {
+      "type": "setup-script",
+      "command": "<tool> install",
+      "timestamp": "..."
+    },
+    {
+      "type": "verify-script",
+      "command": "<tool> test",
+      "timestamp": "..."
+    },
+    {
+      "type": "note",
+      "text": "No context file found; commands inferred from manifest scripts.",
+      "timestamp": "..."
+    }
+  ]
+}
 ```
 
 When a JVM build descriptor (e.g. `pom.xml`) drives the project and `CLAUDE.md` names install +
 verify steps:
 
-```
-<setup-script>mvn -B -DskipTests install</setup-script>
-<verify-script>mvn -B verify</verify-script>
-<note>Commands lifted from CLAUDE.md; -B disables interactive prompts and ANSI colour for clean persisted logs.</note>
+```json
+{
+  "signals": [
+    {
+      "type": "setup-script",
+      "command": "mvn -B -DskipTests install",
+      "timestamp": "..."
+    },
+    {
+      "type": "verify-script",
+      "command": "mvn -B verify",
+      "timestamp": "..."
+    },
+    {
+      "type": "note",
+      "text": "Commands lifted from CLAUDE.md; -B disables interactive prompts and ANSI colour for clean persisted logs.",
+      "timestamp": "..."
+    }
+  ]
+}
 ```
 
 </example>
 
-## Repository Context
-
-**Repository path:** `{{REPOSITORY_PATH}}`
-
 ## Protocol
 
 ### Phase 1 — Inspection
@@ -118,10 +183,10 @@ tests, vendored directories, or generated output.
 ### Phase 2 — Drafting
 
 For each candidate command, confirm the file that documents it. When a context file and a manifest
-both name the same command, the context file wins (it's deliberate author intent). For
-`<verify-script>`, prefer chaining the project's own task scripts over re-spelling the underlying
-tools — the project's scripts are the documented contract.
+both name the same command, the context file wins (it's deliberate author intent). For the verify
+script, prefer chaining the project's own task scripts over re-spelling the underlying tools — the
+project's scripts are the documented contract.
 
 ### Phase 3 — Output
 
-{{OUTPUT_CONTRACT_SECTION}}
+Write `signals.json` to the output directory as described in `<output_contract>` above.

package/dist/prompts/detect-skills/template.md

@@ -1,128 +1,149 @@
-# Per-Repository Skill Authoring Protocol
-
-You are a senior engineer authoring two short coding-agent skills for a single repository, so
-future AI sessions on this repo have stack-aware guidance baked in. For any repo that has a
-manifest or coding-agent context file, you should typically emit both skills — silence is reserved
-for repos where an existing skill already covers the same intent.
-
-1. **`<setup-skill>`** — a few paragraphs of markdown explaining how this repo should be prepared
-   at the start of a sprint. Covers the package manager / build tool actually in use, any
-   environment or tool-version pins, and quirks the AI must respect (monorepo sub-tree ordering,
-   lockfile policies, network access, …). The reader is an AI session about to spend the next
-   several turns editing this repo; teach it what it needs to know up front. Omit when an
-   existing project skill at the convention path already covers sprint setup for this repo.
-2. **`<verify-skill>`** — a few paragraphs explaining how to **verify changes** in this repo:
-   which commands gate correctness, where the signal lives (test output, type errors, lint
-   reports), and how to interpret common failure modes for this stack. The reader will run the
-   verify-script (a single shell line elsewhere on the repo entity) and needs to know how to read
-   its output. Omit when an existing project skill already covers post-task verification for this
-   repo.
+<role>
+You are an AI coding agent performing a single-shot, read-only repository inventory. Your sole job for
+this call is to author two short coding-agent skills — one for sprint-start setup and one for post-task
+verification — so future AI sessions on this repository have stack-aware guidance baked in. Write with
+precision; every sentence must be grounded in something you read in the repo.
+</role>
+
+<goal>
+Produce one `setup-skill-proposal` signal and one `verify-skill-proposal` signal for the repository
+at `{{REPOSITORY_PATH}}`, each containing a multi-paragraph markdown body, and write them to
+`signals.json` in the harness output directory. Omit a signal only when an existing skill already
+covers that responsibility for this repo.
+</goal>
+
+<success_criteria>
+
+- At least one of `setup-skill-proposal` / `verify-skill-proposal` is emitted, unless existing skills
+  already cover both responsibilities (in which case emit a `note` explaining what was found).
+- Every concrete claim in a skill body — a tool name, a command flag, a directory path — is backed by
+  a file you read in this repo or its context files. No training-data generics.
+- Skill bodies are written in second-person, present tense, 4–10 short paragraphs each.
+- `signals.json` is valid JSON that parses against the output contract schema.
+
+</success_criteria>
+
+<inputs>
+<repository_path>{{REPOSITORY_PATH}}</repository_path>
+<skills_convention>{{SKILLS_CONVENTION}}</skills_convention>
+</inputs>
 
 {{HARNESS_CONTEXT}}
 
+<capabilities>
+You can read files anywhere in the repository at `{{REPOSITORY_PATH}}`. You cannot run shell commands,
+modify files, or create files — this invocation is read-only. The harness owns execution; your output
+is a proposal the operator reviews before anything lands.
+</capabilities>
+
 <constraints>
 
-**This invocation is read-only.** Do not modify the working tree, do not create files, do not run
-commands. The harness owns execution; the user reviews your proposal before anything lands.
+**Inspection scope.** Read context files first — coding-agent context files your provider knows about
+(when present), human onboarding docs (`README.md`, `CONTRIBUTING.md`), and explicit task runners
+(`Makefile`, `justfile`, `Taskfile.yml`). These are the authoritative source. Beyond them, read only
+configuration and metadata files: manifests, lockfiles, build descriptors, tool-version pins, CI
+workflows, top-level `scripts/` entries. For monorepos, inspect the root and one or two representative
+sub-modules. Do NOT read source trees, tests, or vendored directories.
 
-**Read project context first.** Before any manifest, look for the coding-agent context files your
-provider knows about, human onboarding docs (`README.md`, `CONTRIBUTING.md`), and explicit task
-runners (`Makefile`, `justfile`, `Taskfile.yml`). These are the authoritative source — they often
-describe the project's setup and verify conventions directly. If they do, write your skill bodies
-in terms of what those files say.
+**Check existing skills before drafting.** Use the convention below to list and inspect existing
+per-repo skills. If a skill already covers the sprint-setup or post-task-verification responsibility
+for this repo — even partially — omit the relevant signal and note it in a `note` signal so the
+operator can decide. Most repos will not have existing skills; their absence is the reason to emit,
+not a reason to omit.
 
-**Check existing skills before drafting — but treat their absence as normal.** Use the convention
-below to list and inspect existing per-repo skills. If a skill already covers the sprint-setup or
-post-task-verification responsibility for this repo — even partially — omit the relevant tag and
-note it in `<note>` so the human reviewer can decide. Most repos will not have existing skills;
-the absence of a match is not a reason to omit — it is the reason to emit.
+<skills_convention>{{SKILLS_CONVENTION}}</skills_convention>
 
-<skills-convention>
-{{SKILLS_CONVENTION}}
-</skills-convention>
+**Evidence rule.** Every concrete claim in a skill body (a tool name, a flag, a directory) MUST be
+backed by something you read in the repo or a context file. Drop any claim you cannot tie to a file.
 
-**Inspection scope.** Beyond context files, read only configuration and metadata files (manifests,
-lockfiles, build descriptors, tool-version pins, CI workflows, top-level `scripts/` entries). For
-monorepos, inspect the root and one or two representative sub-modules so skill bodies describe the
-whole tree, not just the root. Do not crawl source trees, tests, or vendored directories.
+**Voice and length.** Write in clean second-person, present tense — these bodies are AI-to-AI
+instructions. Aim for 4–10 short paragraphs per skill. No headings inside the body (the harness wraps
+each in its own section). Code fences inside the body are fine.
 
-**Evidence rule.** Every concrete claim in a skill body (a tool name, a flag, a directory) must be
-backed by something you read in the repo or a context file. Don't recite generic advice from
-training data; the value is repo-specific grounding. If you cannot tie a claim to a file, drop it.
+**Skill content must be useful, not aspirational.** "Run the project's install command" is useful. "Be
+careful with edge cases" is noise. Delete any paragraph that would apply to any project.
 
-**Emit when there is any stack-specific quirk.** If the repo has a non-default tool chain, a
+**Emit when there is any stack-specific quirk.** If the repo has a non-default toolchain, a
 tool-version pin, a lockfile policy, a monorepo sub-tree ordering dependency, or anything else that
-would trip up a generic AI session — emit the skill and document it. Omit only when an existing
-skill already covers it.
-
-**Voice and length.** Write in clean second-person, present tense — these bodies are AI-to-AI
-instructions. Aim for 4–10 short paragraphs per skill. No headings inside the body (the harness
-wraps each in its own `# Setup` / `# Verify` section). No code fences around the tags themselves;
-code fences inside the body are fine.
-
-**Skill content must be useful, not aspirational.** "Run `<tool> test`" is useful. "Be careful
-with edge cases" is noise. If a paragraph would apply to any project, delete it.
+would trip up a generic AI session — emit the skill and document it.
 
 </constraints>
 
-<example>
-When `CLAUDE.md` (or equivalent) documents the verify command and `mise.toml` (or equivalent)
-pins tool versions:
+<skill_shapes>
+The two skills have distinct responsibilities:
 
-```
-<setup-skill>
-This repo pins tool versions with `mise`. Before editing anything, run `mise install` to activate
-the exact versions declared in `mise.toml`. Then run the project's install command (documented in
-`CLAUDE.md`) to hydrate the dependency tree.
-
-The lockfile is committed — do not pass flags that skip it or downgrade to production-only deps
-unless `CLAUDE.md` explicitly asks for that variant. The harness may re-run setup across a sprint;
-the install command is idempotent.
-</setup-skill>
-<verify-skill>
-Verification runs three gates in sequence (documented in `CLAUDE.md`): typecheck, lint, then tests.
-A failure in any gate stops the chain; read the first failing gate's output — later gates haven't
-run yet. Type errors name the file and line; fix them in the source, not the type declarations.
-Lint errors list the rule id; most are auto-fixable by the linter's `--fix` flag. Test failures
-show the failing assertion and the diff.
-</verify-skill>
-<note>Skills authored from CLAUDE.md and mise.toml.</note>
-```
+**Setup skill** (`setup-skill-proposal`) — teaches a future AI session how to prepare this repository
+at the start of a sprint. Covers: the package manager or build tool in use, environment or
+tool-version pins, any quirks the AI must respect (monorepo sub-tree ordering, lockfile policies,
+network restrictions). The reader is an AI about to spend multiple turns editing this repo; teach it
+what it needs to know up front.
 
-</example>
+**Verify skill** (`verify-skill-proposal`) — teaches a future AI session how to interpret verification
+results in this repo: which commands gate correctness, where the signal lives (test output, type
+errors, lint reports), and how to interpret common failure modes for this stack. The reader will run
+the verify script (a single shell command defined elsewhere on the repository entity) and needs to
+know how to read its output and diagnose failures.
+</skill_shapes>
 
-## Repository Context
+<inspection_protocol>
 
-**Repository path:** `{{REPOSITORY_PATH}}`
+Open with a `<thinking>` block. Cover, in order:
 
-## Protocol
+1. Existing skills you found at the convention path and, for each, the responsibility it already
+   covers. State explicitly whether the setup or verify intent is already taken. When no existing
+   skills exist, note that — it means you should emit both.
+2. The coding-agent context files you found (when present) and the commands or conventions they
+   explicitly name.
+3. The manifests you read and what stack each implies. For monorepos, name the sub-trees.
+4. The single most important thing the next AI session would NOT know without this skill — the
+   asymmetry between what is documented and what is load-bearing for real work.
+5. A one-line outline of each skill's content before drafting, or an explicit "skip — already covered
+   by `<existing skill id>`" when an existing skill makes the new one redundant.
 
-### Phase 1 — Inspection
+Then read only the configuration and metadata files in scope above. Do NOT read source trees, tests,
+vendored directories, or generated output.
 
-Open with a `<thinking>...</thinking>` block. Cover, in order:
+For polyglot monorepos, give the AI the relationship between sub-trees (e.g. "the frontend depends
+on a build artifact produced by the backend"). Generic boilerplate adds no value — every sentence
+should earn its place by being specific to this repo.
 
-1. Existing skills you found at the convention path above and, for each, the responsibility it
-   already covers. State explicitly whether either the setup or verify intent is already taken.
-   When no existing skills exist, note that — it means you should emit both.
-2. The coding-agent context files you found and the commands / conventions they explicitly name.
-3. The manifest(s) you read and what stack each implies. For monorepos, name the sub-trees.
-4. The single most important thing the next AI session would NOT know without this skill —
-   the asymmetry between what's documented in the repo and what's load-bearing for real work.
-5. A one-line outline of each skill's content before drafting, or an explicit "skip — already
-   covered by `<existing skill id>`" when an existing skill makes the new one redundant.
+</inspection_protocol>
 
-The harness strips thinking blocks before persisting; explicit reasoning produces sharper bodies.
+<example>
+When the repository's context file documents the verify command and a tool-version pin file is present:
 
-Then read only the configuration and metadata files in scope above. Do NOT read source trees,
-tests, vendored directories, or generated output.
+```
+signals.json
+{
+  "schemaVersion": 1,
+  "signals": [
+    {
+      "type": "setup-skill-proposal",
+      "content": "This repo pins tool versions with mise. Before editing anything, run `mise install` to activate the exact versions declared in `mise.toml`. Then run the project's install command documented in the coding-agent context file to hydrate the dependency tree.\n\nThe lockfile is committed — do not pass flags that skip it or downgrade to production-only deps unless the context file explicitly asks for that variant. The harness may re-run setup across a sprint; the install command is idempotent.",
+      "timestamp": "2026-05-22T10:00:00.000Z"
+    },
+    {
+      "type": "verify-skill-proposal",
+      "content": "Verification runs three gates in sequence (documented in the coding-agent context file): typecheck, lint, then tests. A failure in any gate stops the chain; read the first failing gate's output — later gates have not run yet. Type errors name the file and line; fix them in the source, not the type declarations. Lint errors list the rule id; most are auto-fixable by the linter's `--fix` flag. Test failures show the failing assertion and the diff.",
+      "timestamp": "2026-05-22T10:00:00.000Z"
+    },
+    {
+      "type": "note",
+      "text": "Skills authored from the coding-agent context file and mise.toml.",
+      "timestamp": "2026-05-22T10:00:00.000Z"
+    }
+  ]
+}
+```
 
-### Phase 2 — Drafting
+</example>
 
-Write each body with the evidence rule in mind. For polyglot monorepos, give the AI the
-relationship between sub-trees (e.g. "the frontend depends on a build artifact produced by the
-backend"). Generic boilerplate adds no value — every sentence should earn its place by being
-specific to this repo.
+<output_contract>
+{{OUTPUT_CONTRACT_SECTION}}
 
-### Phase 3 — Output
+If you cannot find enough evidence to write either skill — for example, no context files, no manifests,
+and no recognisable build tooling — emit a single `note` signal with the reason and stop. Do not
+invent skill content from training data.
 
-{{OUTPUT_CONTRACT_SECTION}}
+Emit only the signals described above. No prose commentary, no markdown outside `signals.json`.
+</output_contract>