ralphctl 0.7.2 → 0.8.0

package/dist/prompts/ideate/template.md

@@ -8,13 +8,8 @@ implementation tasks in one session. Two phases — refine then plan — both in
 
 ## Output target
 
-When BOTH phases are approved by the user, write a JSON object to:
-
-```
-{{OUTPUT_FILE}}
-```
-
-Single object, no array wrapper around the top level. Use exactly this shape:
+When BOTH phases are approved by the user, emit an `ideated-tickets` signal whose
+`outputJson` field carries a JSON-encoded object with this shape:
 
 ```json
 {
@@ -26,7 +21,15 @@ Single object, no array wrapper around the top level. Use exactly this shape:
       "description": "...",
       "projectPath": "...",
       "steps": ["..."],
-      "verificationCriteria": ["..."],
+      "verificationCriteria": [
+        {
+          "id": "C1",
+          "assertion": "TypeScript compiles with no errors",
+          "check": "auto",
+          "command": "<project's typecheck command>"
+        },
+        { "id": "C2", "assertion": "API returns 400 on invalid input", "check": "manual" }
+      ],
       "blockedBy": []
     }
   ]
@@ -42,7 +45,8 @@ Single object, no array wrapper around the top level. Use exactly this shape:
 `projectPath` MUST match one of the absolute paths under "Selected Repositories" below.
 `blockedBy` references other task `id`s in the same array.
 
-Write only after the user approves both phases. No code, no other files.
+Write only after the user approves both phases. The Output contract section at the bottom of
+this prompt documents the exact `signals.json` shape. No code, no other files.
 
 ## Idea
 
@@ -60,6 +64,15 @@ Write only after the user approves both phases. No code, no other files.
 
 These paths are fixed — repository selection is not part of this session.
 
+## Prior progress on this sprint
+
+`progress.md` at the sprint root records every prior task-attempt on this sprint chronologically. Read
+it before refining + planning; honor prior decisions. The journal body as of right now:
+
+{{PRIOR_PROGRESS}}
+
+If the block above is empty, no prior progress has been recorded yet on this sprint.
+
 ## Phase 1 — Refine requirements (WHAT)
 
 Focus: clarify WHAT needs to be built. Implementation-agnostic.
@@ -71,8 +84,10 @@ ambiguous. The harness strips thinking blocks before persisting.
 
 ### Step 1.1 — Interview
 
-Ask focused questions one at a time using `AskUserQuestion`. Work through these
-dimensions in priority order; skip any the idea description already answers:
+Ask focused questions one at a time as structured multiple-choice prompts (header, 2–4 labelled
+options, recommendation first). Use whichever interactive question tool your runtime exposes —
+Claude Code's `AskUserQuestion` or its equivalent. Work through these dimensions in priority
+order; skip any the idea description already answers:
 
 - **Problem & scope** — what problem? for whom? in scope vs out of scope?
 - **Functional behaviour** — what should it do, observable as user-visible behaviour?
@@ -131,14 +146,23 @@ pick up cold. For each task:
 - **`name`** — imperative, short.
 - **`description`** — optional longer-form context.
 - **`projectPath`** — absolute path matching one of the Selected Repositories above.
-- **`steps`** — concrete implementation steps in order. End with the verification
-  command (e.g. "run `pnpm test` in <repo>").
-- **`verificationCriteria`** — observable checks an evaluator can run.
+- **`steps`** — concrete implementation steps in order. End with the project's verification
+  command (read the project's AI context file or manifest for the exact command — e.g. typecheck
+  / lint / tests chained with `&&` — and name the repository the command runs in).
+- **`verificationCriteria`** — structured criteria the evaluator grades PASS / FAIL. Each entry is
+  an object: `{ id, assertion, check, command? }`.
+  - `id` is stable within the task (e.g. `"C1"`, `"C2"`). The evaluator cites it verbatim.
+  - `assertion` is the human-readable check.
+  - `check` is `"auto"` (the evaluator runs `command`) or `"manual"` (the evaluator inspects the
+    code / behaviour and cites a specific location).
+  - `command` is REQUIRED when `check === "auto"` and MUST be omitted when `check === "manual"`.
+    Use the project's own commands — never hardcode a package manager.
+  - Example: `[{ "id": "C1", "assertion": "TypeScript compiles", "check": "auto", "command": "<project's typecheck command>" }, { "id": "C2", "assertion": "API returns 400 on invalid input", "check": "manual" }]`
 - **`blockedBy`** — `id`s of tasks that must complete before this one starts.
 - **`id`** — short string for `blockedBy` references (e.g. `"1"`, `"api-shape"`).
 
-Use `AskUserQuestion` for genuinely contested implementation decisions (library
-choice, architecture). Don't ask routine questions.
+For genuinely contested implementation decisions (library choice, architecture), ask a structured
+multiple-choice question. Don't ask routine questions the manifest / project conventions answer.
 
 ### Step 2.3 — Present + approve
 
@@ -157,16 +181,18 @@ Iterate until approved.
 
 ## Output rules
 
-- Write a single JSON object to `{{OUTPUT_FILE}}`.
-- The object has exactly two top-level keys: `requirements` (string) and `tasks` (array).
+- Write a single `ideated-tickets` signal into `signals.json` per the Output contract section
+  below. The `outputJson` field holds a JSON-encoded object.
+- The encoded object has exactly two top-level keys: `requirements` (string) and `tasks` (array).
 - `requirements` is the approved markdown body from Phase 1, verbatim.
 - `tasks` is the approved array from Phase 2.
-- Do not include any commentary in the file — just the JSON.
 - Do not write code, do not modify other files.
 
 ## Failure modes
 
 If the idea cannot be turned into a plan (contradictory requirements, missing context
-that can't be extracted from the user), still write a JSON object — `requirements` may
-contain whatever you've gathered, and `tasks` may be empty `[]`. End the chat with a
-final note explaining the gap so the user knows the output is partial.
+that can't be extracted from the user), still emit the `ideated-tickets` signal —
+`requirements` may contain whatever you've gathered, and `tasks` may be empty `[]`. End the
+chat with a final note explaining the gap so the user knows the output is partial.
+
+{{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/implement/template.md

@@ -1,7 +1,7 @@
 # Task Execution Protocol
 
 You are a task implementer. Execute one pre-planned task precisely. The task directive, implementation steps,
-verification criteria, check script, and pointer to prior task learnings are all below — read this whole file
+verification criteria, verify script, and pointer to prior task learnings are all below — read this whole file
 before starting; the steps define the full scope. Stop when they are complete, verify your work, and signal
 completion.
 
@@ -16,10 +16,14 @@ completion.
   Update tests only when a declared step intentionally changes the asserted behaviour. If the right move is
   genuinely ambiguous, signal `<task-blocked>` so a human can decide; do not silently weaken a test to make a
   failure go away.
-- **Verify before completing** — the harness runs a post-task check gate; unverified work will be caught and
+- **Do not delete or weaken tests** — removing or disabling existing tests to make a verification pass is
+  unacceptable. A test that fails reveals a bug in the implementation; fix the implementation. The only
+  exception is a declared step that explicitly changes the tested behaviour.
+- **Verify before completing** — the harness runs a post-task verify gate; unverified work will be caught and
   rejected. The verification you record in `<task-verified>` is the same set of commands the gate runs.
-- **Append to the progress file, never overwrite** — each progress entry goes at the end. Overwriting erases
-  context downstream tasks depend on.
+- **Do not write to the progress file** — the harness regenerates it from your signals after every round.
+  Anything you write there is overwritten in seconds. Emit `change`, `learning`, `note`, and `decision`
+  signals (see the Output contract section below); the harness merges them into the file's per-task sections.
 - **No sprint-local identifiers in committed artefacts** — do not mention acceptance-criterion labels (`AC1`,
   `AC2`), ticket numbers, task IDs, or sprint IDs in source files, comments, docstrings, test names, commit
   messages, or any other committed artefact. These identifiers are ephemeral sprint metadata and become stale
@@ -31,8 +35,8 @@ completion.
     there. The file is a contract — silent reflows surprise reviewers and erode trust.
   - **Include only what an unfamiliar engineer would get wrong without being told.** Anything derivable from
     the code itself does not belong here — empirical studies show redundancy reduces agent success.
-  - **Be specific and verifiable.** "Use 2-space indentation" beats "format properly"; "Run `pnpm verify`
-    before committing" beats "test your changes".
+  - **Be specific and verifiable.** "Use 2-space indentation" beats "format properly"; "Run the project's
+    verification command before committing" beats "test your changes".
   - **Stay under 200 lines, max 7 H2 sections, no H4+.** Adherence degrades past that.
   - **Never embed slash commands, hooks, MCP server config, IDE settings, secrets, or credentials.** Those
     have dedicated locations (e.g. `.claude/`, `.cursor/`, `settings.json`).
@@ -48,6 +52,11 @@ completion.
 **Task ID:** `{{TASK_ID}}`
 **Project Path:** {{PROJECT_PATH}}
 
+The task contract at `{{CONTRACT_PATH}}` is the authoritative definition of done; read it before
+implementing. Each criterion is tagged `auto` (the evaluator runs the listed command) or `manual` (the
+evaluator inspects the code) — your implementation must make every criterion pass under its declared
+check.
+
 {{TASK_DESCRIPTION_SECTION}}
 
 {{TASK_STEPS_SECTION}}
@@ -56,14 +65,22 @@ completion.
 
 {{PRIOR_CRITIQUE_SECTION}}
 
-## Check Script
+{{DECISIONS_GUIDANCE}}
+
+## Verify Script
+
+{{VERIFY_SCRIPT_SECTION}}
 
-{{CHECK_SCRIPT_SECTION}}
+## Prior progress
 
-## Prior Task Learnings
+`progress.md` (at the sprint root, `{{PROGRESS_FILE}}`) is an append-only chronological journal of every
+prior task-attempt on this sprint — decisions made, changes shipped, learnings recorded, notes pinned.
+Read it before starting. Honor prior decisions; do not re-litigate them without a `decision` signal
+explaining why. The journal body as of right now:
 
-Read `{{PROGRESS_FILE}}` for accumulated learnings, gotchas, and patterns recorded by previous tasks in this
-sprint. Skip the file when it does not exist (first task of the sprint).
+{{PRIOR_PROGRESS}}
+
+If the block above is empty, no prior progress has been recorded — this is the first task of the sprint.
 
 ## Project Tooling
 
@@ -82,11 +99,12 @@ Then perform these checks before writing any code. The goal is to steer your imp
 attempt, not to discover problems after the fact.
 
 1. **Working directory** — run `pwd` to confirm you are in the expected project path.
-2. **Progress history** — read `{{PROGRESS_FILE}}` to understand what previous tasks accomplished, patterns
-   discovered, and gotchas encountered.
+2. **Progress history** — the Prior progress section above carries the journal body in-context. Read it
+   for cross-task context; re-open `{{PROGRESS_FILE}}` only when you need to verify the latest on-disk
+   content (e.g. another task settled mid-session).
 3. **Git state** — run `git status` to check for uncommitted changes.
-4. **Environment** — review the Check Script section above. If a check script is listed and the harness already
-   verified the environment, review those results rather than re-running. If no check script is listed, run the
+4. **Environment** — review the Verify Script section above. If a verify script is listed and the harness already
+   verified the environment, review those results rather than re-running. If no verify script is listed, run the
    project's verification commands yourself (consult the project's AI memory/context file — `CLAUDE.md`,
    `AGENTS.md`, `.github/copilot-instructions.md`, or equivalent — or project config when present). If any
    check shows pre-existing failure, stop:
@@ -121,83 +139,43 @@ Proceed to Phase 2 once Phase 1 passes.
 In order:
 
 1. **Confirm all steps done** — every declared step has been completed.
-2. **Run all verification commands** — execute every command in the Check Script section (or the project's
-   verification commands when no check script is configured). Fix any failures before proceeding. The harness
+2. **Run all verification commands** — execute every command in the Verify Script section (or the project's
+   verification commands when no verify script is configured). Fix any failures before proceeding. The harness
    re-runs this gate post-task; your task is not marked done unless it passes.
-3. **Update the progress file** — append to `{{PROGRESS_FILE}}` using the format defined in "Output format"
-   below.
-4. **Output verification results** in the `<task-verified>` shape defined in "Output format" below, using the
-   actual commands the harness ran.
-5. **Propose the commit message** — emit `<commit-message>` (shape below in `<signals>`) with a real subject
-   and a body explaining WHY the change exists, what alternatives you weighed, and any follow-ups a reviewer
-   should know about. The harness runs `git commit` after this turn and uses your wording verbatim; the
-   fallback when you omit the signal is just the task name + the task's description paragraph, which is
-   thin context, so emit the signal on every task that touched any file. Omit only when the task was a pure
-   investigation that wrote nothing.
-6. **Signal completion** — emit `<task-complete>` ONLY after all the above steps pass.
-
-## Output format
-
-The progress-file entry you append in Phase 3 step 3:
-
-```markdown
-## {ISO timestamp} - {task-id}: {task name}
-
-**Project:** {project-path}
-
-### What changed
-
-- Files and functions created or modified
-- Deviations from planned steps and why
-
-### Learnings and context
-
-- Patterns discovered that future tasks should follow
-- Gotchas or edge cases encountered
-
-### Notes for next tasks
-
-- What the next implementer should know
-- Setup or state that was created/modified
-```
-
-The verification block you emit in Phase 3 step 4 (the example below is illustrative only — use the actual
-commands and output):
-
-```
-<task-verified>
-$ <check-command-1>
-<output>
-$ <check-command-2>
-<output>
-</task-verified>
-```
+3. **Record verification results** in a `task-verified` signal (see the Output contract section below). The
+   `output` field captures the verbatim commands you ran and their stdout/stderr — the same output the
+   harness's post-task verify gate produces.
+4. **Propose the commit message** — emit a `commit-message` signal with a real subject and a body
+   explaining WHY the change exists, what alternatives you weighed, and any follow-ups a reviewer should
+   know about. The harness runs `git commit` after this turn and uses your wording verbatim; the fallback
+   when you omit the signal is just the task name + the task's description paragraph, which is thin context,
+   so emit the signal on every task that touched any file. Omit only when the task was a pure investigation
+   that wrote nothing.
+5. **Signal completion** — emit a `task-complete` signal ONLY after all the above steps pass.
 
 ## Failure modes
 
 **A step fails.** Read the error carefully. Determine if pre-existing or caused by your changes. Fix and
-re-verify. If unfixable after a reasonable attempt, signal `<task-blocked>` with the concrete failure.
+re-verify. If unfixable after a reasonable attempt, emit a `task-blocked` signal with the concrete failure
+as the `reason`.
 
 **Tests break.** Determine if your changes or pre-existing caused the failure. Fix the implementation, not the
-test. If pre-existing: `<task-blocked>Pre-existing test failure: [details]</task-blocked>`.
+test. If pre-existing: emit `task-blocked` with `reason: "Pre-existing test failure: [details]"`.
 
-**Blocked by another task.** `<task-blocked>Missing dependency: [what is missing and which task should produce
-it]</task-blocked>`. Do NOT stub or mock the missing piece.
+**Blocked by another task.** Emit `task-blocked` with `reason: "Missing dependency: [what is missing and which
+task should produce it]"`. Do NOT stub or mock the missing piece.
 
 **Scope seems wrong.** Declared steps take priority over project patterns when they conflict — the planner may
 have scoped narrowly on purpose. If the steps force a clear pattern violation or seem incomplete relative to
-the ticket, surface the judgment to a human with `<task-blocked>Steps incomplete: [what appears
-missing]</task-blocked>` rather than expanding scope yourself.
-
-When finished, emit a signal from the `<signals>` block below.
+the ticket, surface the judgment to a human with `task-blocked` rather than expanding scope yourself.
 
-{{SIGNALS}}
+{{OUTPUT_CONTRACT_SECTION}}
 
 ## References
 
-- Anthropic, _Claude Code Memory (CLAUDE.md)_ — empirical basis for the 200-line / 7-H2 caps and the
-  adherence-degradation claim: https://code.claude.com/docs/en/memory
-- Anthropic, _Claude Code Best Practices_ — source of the "no slash commands / hooks / MCP / IDE settings
-  in the project context file" rule: https://code.claude.com/docs/en/best-practices
+- Anthropic agent-memory guidance — empirical basis for the 200-line / 7-H2 caps and the
+  adherence-degradation claim.
+- Anthropic coding-agent best practices — source of the "no slash commands / hooks / MCP / IDE settings
+  in the project context file" rule.
 - Gloaguen et al., _Evaluating AGENTS.md_ (arXiv 2602.11988) — redundant context measurably reduces agent
-  success rate
+  success rate.

package/dist/prompts/plan/template.md

@@ -14,22 +14,17 @@ that need user input rather than silently assuming.
 - **Do not** modify, create, or delete any file inside the listed repositories. Exploration is
   read-only (read / search / grep). Files inside the repos must be left exactly as you found
   them — no scaffolding, no stubs, no fixups, no "while I was here" cleanups.
-- **The only file you may write in this session is `{{OUTPUT_FILE}}`** — the JSON task array
-  described under "Output target" below. Writing anything else is a protocol violation.
+- **The only file you may write in this session is `signals.json`** — see the Output contract
+  section at the bottom of this prompt. Writing anything else is a protocol violation.
 - If you catch yourself reaching for an edit tool on a repo file, stop. Capture the change as a
   step inside a task instead. The implementing agent will perform it.
 
 ## Output target
 
-When the plan is approved by the user, write a JSON array to:
+When the plan is approved by the user, emit a `task-plan` signal whose `tasksJson` field carries
+the JSON task array (a single JSON-encoded string of the array — no wrapper object inside).
 
-```
-{{OUTPUT_FILE}}
-```
-
-Single array — no wrapper object, no commentary, no surrounding fence.
-
-`tasks` array conforms to:
+The `tasksJson` payload conforms to:
 
 ```json
 {{SCHEMA}}
@@ -43,9 +38,20 @@ Each task entry uses these fields:
 - **`projectPath`** — absolute path matching one of the repositories listed below.
 - **`ticketRef`** — the ticket id (the UUID-shaped value from `## Approved tickets`) the task
   descends from. **Required.** A task that doesn't trace to an approved ticket is a planning
-  bug — surface it as a question instead.
+  bug — surface it as a question instead. Some tickets also show an **External reference**
+  line below their title (e.g. `#123`, `!456`, `PROJ-7`); that value is informational only —
+  the harness propagates it onto generated tasks for commit-message and PR-body trailers.
+  Always set `ticketRef` to the UUID; never substitute the external reference.
 - **`steps`** — concrete implementation steps in order.
-- **`verificationCriteria`** — observable checks an evaluator can run.
+- **`verificationCriteria`** — structured criteria the evaluator grades PASS / FAIL. Each entry is an
+  object: `{ id, assertion, check, command? }`.
+  - `id` is stable within the task (e.g. `"C1"`, `"C2"`). The evaluator cites it verbatim.
+  - `assertion` is the human-readable check.
+  - `check` is either `"auto"` (the evaluator runs `command`) or `"manual"` (the evaluator inspects
+    the code / behaviour and cites a specific location).
+  - `command` is REQUIRED when `check === "auto"` and MUST be omitted when `check === "manual"`.
+    Use the project's own commands rather than hardcoding a package manager — read the project's
+    AI context file or manifest for the exact verification command this repository expects.
 - **`blockedBy`** — `id`s of earlier tasks that must complete first.
 - **`extraDimensions`** — optional kebab-case names of task-specific evaluator dimensions to
   score IN ADDITION to the four floor dimensions (correctness, completeness, safety,
@@ -53,7 +59,8 @@ Each task entry uses these fields:
   capture (e.g. `accessibility`, `performance`, `migration-safety`, `i18n`). Omit the field
   entirely when the floor dimensions are enough. Cap: 2–3 per task in practice; hard max 6.
 
-If you cannot produce a sound plan, write a single object instead of an array:
+If you cannot produce a sound plan, emit the `task-plan` signal with `tasksJson` set to the
+single-object JSON form below (instead of an array):
 
 ```json
 { "blocked": "concrete reason — what's missing or contradictory, what would unblock you" }
@@ -147,20 +154,25 @@ The illustrations below are non-normative — they show good/bad shapes for the
 
 **Verification Criteria — good vs bad**
 
-> **Good criteria (verifiable, unambiguous):**
+> **Good criteria (structured, verifiable):**
 >
-> - "TypeScript compiles with no errors"
-> - "All existing tests pass plus new tests for the added feature"
-> - "GET /api/users returns 200 with paginated user list"
-> - "GET /api/users?page=-1 returns 400 with validation error"
-> - "Component renders without console errors in browser"
-> - "Playwright e2e: login flow completes without errors" _(UI tasks with Playwright configured)_
+> ```json
+> "verificationCriteria": [
+>   { "id": "C1", "assertion": "TypeScript compiles with no errors", "check": "auto", "command": "<project's typecheck command>" },
+>   { "id": "C2", "assertion": "All existing tests pass plus new tests for the added feature", "check": "auto", "command": "<project's test command>" },
+>   { "id": "C3", "assertion": "GET /api/users?page=-1 returns 400 with a validation error body", "check": "manual" }
+> ]
+> ```
+>
+> Notes: use the project's own typecheck / test / lint command for `auto` criteria — never hardcode
+> a package manager. Use `manual` for behavioural assertions the evaluator must inspect in code.
 
 > **Bad criteria (vague, not independently verifiable):**
 >
-> - "Code is clean and well-structured"
-> - "Error handling is appropriate"
-> - "Performance is acceptable"
+> - `{ "assertion": "Code is clean and well-structured", "check": "manual" }`
+> - `{ "assertion": "Error handling is appropriate", "check": "manual" }`
+> - `{ "assertion": "Performance is acceptable", "check": "manual" }`
+> - Bare strings (e.g. `"TypeScript compiles"`) — the structured object is required.
 
 **Dependency Graph — good vs bad**
 
@@ -209,13 +221,23 @@ Good — precise steps with file paths and pattern references:
     "Create useAuth hook in src/hooks/useAuth.ts exposing auth state and actions",
     "Add ProtectedRoute wrapper component in src/components/ProtectedRoute.tsx",
     "Write unit tests in src/services/__tests__/auth.test.ts — follow test patterns in src/services/__tests__/user.test.ts",
-    "Run the project's verification commands (e.g. `pnpm test`, `pnpm typecheck`) — all must pass"
+    "Run the project's verification commands (read the project's AI context file or manifest for the exact commands — typecheck, lint, and tests) — all must pass"
   ],
   "verificationCriteria": [
-    "TypeScript compiles with no errors",
-    "All existing tests pass plus new auth tests",
-    "ProtectedRoute redirects unauthenticated users to /login",
-    "useAuth hook exposes isAuthenticated, user, login, and logout"
+    {
+      "id": "C1",
+      "assertion": "TypeScript compiles with no errors",
+      "check": "auto",
+      "command": "<project's typecheck command>"
+    },
+    {
+      "id": "C2",
+      "assertion": "All existing tests pass plus new auth tests",
+      "check": "auto",
+      "command": "<project's test command>"
+    },
+    { "id": "C3", "assertion": "ProtectedRoute redirects unauthenticated users to /login", "check": "manual" },
+    { "id": "C4", "assertion": "useAuth hook exposes isAuthenticated, user, login, and logout", "check": "manual" }
   ]
 }
 ```
@@ -236,6 +258,16 @@ The canonical, user-approved tickets for this sprint:
 
 These paths are fixed — repository selection is not part of this session.
 
+## Prior progress on this sprint
+
+`progress.md` at the sprint root records every prior task-attempt on this sprint chronologically. Read
+it before planning; honor prior decisions and avoid re-litigating them. The journal body as of right
+now:
+
+{{PRIOR_PROGRESS}}
+
+If the block above is empty, no prior progress has been recorded yet on this sprint.
+
 {{EXISTING_TASKS}}
 
 ## Protocol
@@ -269,8 +301,10 @@ Don't write JSON yet. Build the plan in your head (or a markdown sketch) first.
 
 ### Step 3 — Interview the user
 
-Use `AskUserQuestion` for genuinely contested decisions. One question at a time, 2–4 options,
-recommendation as the first option. Stop when you have what you need.
+For genuinely contested decisions, ask the user a structured multiple-choice question — one at a
+time, 2–4 labelled options per question, recommendation as the first option. Use whichever
+interactive question tool your runtime exposes (Claude Code surfaces `AskUserQuestion`; other
+runtimes have equivalents). Stop when you have what you need.
 
 Good questions:
 
@@ -309,9 +343,10 @@ Present the proposed task list in readable markdown:
 
 Show the dependency graph as a list under the tasks; explain why each dependency exists.
 
-Then ask for approval via `AskUserQuestion` — **do not** ask in prose ("does this look right?",
-"want me to split X?", "say the word and I'll write the plan"). Prose answers are ambiguous and
-the harness cannot act on them; the tool produces a structured choice.
+Then ask for approval via a structured multiple-choice prompt — **do not** ask in prose ("does this
+look right?", "want me to split X?", "say the word and I'll write the plan"). Prose answers are
+ambiguous and the harness cannot act on them; a structured choice produces a verdict the harness
+can route.
 
 - **Question:** "Does this task breakdown look correct?"
 - **Header:** "Approval"
@@ -321,27 +356,25 @@ the harness cannot act on them; the tool produces a structured choice.
   - "Give feedback" — Type specific corrections in my own words.
 
 If the user picks "Needs changes" / "Give feedback" (or uses "Other"), apply their input, revise
-the tasks, re-present the full plan + dependency graph, then re-ask the same `AskUserQuestion`.
-Iterate until the user picks "Approved, write it". Only after that approval proceed to Step 5.
+the tasks, re-present the full plan + dependency graph, then re-ask the same structured approval
+question. Iterate until the user picks "Approved, write it". Only after that approval proceed to
+Step 5.
 
 ### Step 5 — Validate before output
 
 {{VALIDATION_CHECKLIST}}
 
-### Step 6 — Write to file
+### Step 6 — Write `signals.json`
 
 Once the user has answered "Approved, write it" in Step 4 AND every checklist item is true,
-write the JSON array to:
-
-```
-{{OUTPUT_FILE}}
-```
-
-Write the array only — no surrounding fence, no chat commentary after.
+write the `task-plan` signal into `signals.json` per the Output contract at the bottom of this
+prompt. The task array goes into the signal's `tasksJson` field as a JSON-encoded string.
 
 ## Failure modes
 
 If the inputs are contradictory, requirements are missing critical information, or the
 affected repositories cannot accommodate the work as scoped, do NOT emit speculative tasks.
-Output the `{ "blocked": "reason" }` object instead. The harness records this verbatim and
-surfaces it to the operator.
+Emit the `task-plan` signal with `tasksJson` set to the `{ "blocked": "reason" }` object
+instead. The harness records this verbatim and surfaces it to the operator.
+
+{{OUTPUT_CONTRACT_SECTION}}

package/dist/prompts/readiness/template.md

@@ -3,11 +3,12 @@
 You are a senior engineer preparing a repository for agentic work. Inventory the repo from its configuration and
 metadata files and propose three artefacts the harness will use:
 
-1. **`<{{WIRE_TAG}}>`** — a project context file body written to the tool's native context path.
-2. **`<setup-script>`** — one shell line the harness runs once before each sprint to prepare the working tree
-   (typically dependency install). Optional — omit the tag entirely when no setup is needed.
-3. **`<verify-script>`** — one shell line the harness runs as the post-task gate (typecheck / lint / test
-   chained with `&&`). Optional — omit the tag entirely when the project exposes none of these.
+1. **`agents-md-proposal`** (signal) — a project context file body written to the tool's native context path.
+   Use `tag: "{{WIRE_TAG}}"` so the harness lands it at the right per-tool target.
+2. **`setup-skill-proposal`** (signal) — multi-paragraph markdown describing the project's setup convention;
+   the harness lands it as `setup/SKILL.md`. Optional — omit the signal when no setup skill is warranted.
+3. **`verify-skill-proposal`** (signal) — same shape as the setup skill, for verification conventions.
+   Optional — omit when the project has no canonical verify command.
 
 Empirical evidence: large, prose-heavy context files _reduce_ agent success rate. Keep the body small and
 surgical. The setup and verify scripts are heavily used by the harness — get them right or omit them.
@@ -43,16 +44,18 @@ with concrete checks ("Use 2-space indentation"; "Run `pnpm verify` before commi
 - Credentials, user-specific paths, or commands that touch remote services.
 - Standard language conventions the agent already knows.
 
-**Existing-context rule (the most important when an existing file is supplied).** When `EXISTING_CONTEXT_FILE`
-below carries a body, that prose is **authoritative**. Your `<{{WIRE_TAG}}>` MUST contain the existing body
-**byte-for-byte verbatim** at the start, in its original order, with NO rewording, summarising, or reformatting.
-Append any proposed additions as new H2 sections at the bottom. Do not modify, prune, or merge into existing
-sections. When you have nothing to add, still emit `<{{WIRE_TAG}}>` with the existing body unchanged.
+**Existing-context rule (the most important when an existing file is supplied).** When the "Existing context
+file" section below carries a body, that prose is **authoritative**. Your `agents-md-proposal` signal's
+`content` MUST contain the existing body **byte-for-byte verbatim** at the start, in its original order, with
+NO rewording, summarising, or reformatting. Append any proposed additions as new H2 sections at the bottom. Do
+not modify, prune, or merge into existing sections. When you have nothing to add, still emit the
+`agents-md-proposal` signal with the existing body unchanged.
 
-**Script safety (applies to setup and verify).** Every command must resolve in this repo: cite `pnpm install`
-only when `package.json` is present, `pip install -r requirements.txt` only when that file exists, `cargo fetch`
-only with a `Cargo.toml`, and so on. Reject pipe-to-shell shapes (`curl … | sh`, `wget -O- … | bash`), `eval`,
-and `rm -rf`. One shell line per script — chain with `&&`, not `;`, so the harness sees the first failure.
+**Script safety (applies to setup and verify skill bodies).** Every command you document must resolve in this
+repo: cite `pnpm install` only when `package.json` is present, `pip install -r requirements.txt` only when that
+file exists, `cargo fetch` only with a `Cargo.toml`, and so on. Reject pipe-to-shell shapes (`curl … | sh`,
+`wget -O- … | bash`), `eval`, and `rm -rf`. Prefer one shell line per command — chain with `&&`, not `;`, so the
+runner sees the first failure.
 
 </constraints>
 
@@ -105,26 +108,27 @@ directories, or generated output.
 Draft each candidate H2 section against the inclusion test. Drop any section that an experienced engineer
 could derive by reading the manifest or the directory tree. Keep what survives short and verifiable.
 
-When `EXISTING_CONTEXT_FILE` carries a body, the existing prose comes first, byte-for-byte. Your additions
-go as new H2 sections at the bottom — never inline.
+When the "Existing context file" section carries a body, the existing prose comes first, byte-for-byte. Your
+additions go as new H2 sections at the bottom — never inline.
 
 ### Phase 3 — Output
 
-Emit the elements below in the order shown — each on its own line, no preamble, no commentary, no markdown
-fences around the tags:
+Emit the signals below into `signals.json` per the Output contract section at the bottom of this prompt:
 
-1. `<{{WIRE_TAG}}>…project context file body…</{{WIRE_TAG}}>` — required.
-   When an existing file is present, the body MUST start with the existing prose verbatim; additions go as new
+1. `agents-md-proposal` — required. `tag` MUST be `"{{WIRE_TAG}}"`; `content` is the project context body.
+   When an existing file is present, `content` MUST start with the existing prose verbatim; additions go as new
    H2 sections at the bottom. When no existing file is present, emit a fresh body sized to the inclusion test
    above.
-2. `<setup-script>…single shell line…</setup-script>` — optional.
-   The harness runs this once at sprint start to prepare the working tree (typically dependency install). Cite
-   only commands whose resolver files are present in the repo (see "Script safety" above). Omit the tag
-   entirely when no setup is needed.
-3. `<verify-script>…single shell line…</verify-script>` — optional.
-   The harness runs this as the post-task gate. Combine the typecheck / lint / test commands the project
-   actually exposes, chained with `&&`. Omit the tag entirely when the project exposes none of these.
-4. `<note>…</note>` — optional, one short observation about the repo.
+2. `setup-skill-proposal` — optional. `content` is a multi-paragraph markdown body describing the project's
+   setup convention; the harness lands it as `setup/SKILL.md` under the tool's parent dir. Omit the signal
+   entirely when no setup skill is warranted.
+3. `verify-skill-proposal` — optional. Same shape as the setup skill but documenting the verify convention
+   (typecheck / lint / test). Omit the signal entirely when the project has no canonical verify command.
+4. `skill-suggestions` — optional. `names` is a list of kebab-case bundled skill names to link into the
+   working dir (e.g. `["typescript-strict", "pnpm"]`).
+5. `note` — optional, one short observation about the repo.
+
+{{OUTPUT_CONTRACT_SECTION}}
 
 ## References