diff --git a/AGENTS.md b/AGENTS.md index 8337cbb5..aa4b2681 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,15 @@ benchmark baseline. Neither is a daemon, queue, general workflow runtime, or license to restore the removed runtime experiments. Do not reconstruct other runtime machinery from Git history unless the user explicitly requests it. +## Writing style + +- Lead with the result and the next action. +- Use familiar words, active voice, and short sentences and paragraphs. +- Explain a necessary Darrow term the first time it appears. +- Remove repetition and unnecessary process narration. +- Preserve technical meaning, safety rules, evidence, exact commands and + identifiers, and required protocol fields while simplifying prose. + Before changing plugin boundaries, the orchestration model, or the relationship between capabilities and orchestration, read [`docs/design.md`](docs/design.md). diff --git a/README.md b/README.md index 76221c47..53745917 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,7 @@ Darrow is a marketplace of focused, eval-tested plugins for Codex and Claude -Code. It is for developers who want repeatable Git, review, planning, and -implementation skills while choosing what to adopt. +Code. Choose only the Git, review, planning, or implementation help you need. Install one plugin at a time. Capabilities match your request; orchestration starts only when explicitly invoked and uses a host-native execution owner. diff --git a/docs/choosing-plugins.md b/docs/choosing-plugins.md index cb56bb1f..4ddcdab3 100644 --- a/docs/choosing-plugins.md +++ b/docs/choosing-plugins.md @@ -1,9 +1,8 @@ # Choose Darrow plugins -Start with the work you want the agent to do. Install one matching plugin, -try it on a small request, and add another when a new need appears. -A plugin is an independently adoptable package; installing one does not require -the other layers. Its README owns its prerequisites, behavior, and safety rules. +Start with the work you want done. Install one matching plugin and try it on a +small request. Add another only when a new need appears. Each plugin stands +alone; its README owns its prerequisites, behavior, and safety rules. ## Choose by intent diff --git a/docs/documentation-quality.md b/docs/documentation-quality.md index ae67d411..66e677c6 100644 --- a/docs/documentation-quality.md +++ b/docs/documentation-quality.md @@ -3,6 +3,22 @@ Use this contract with the [contributor guidance](../CONTRIBUTING.md). Pages serve one primary reader need; the static spine must work without the guide. +## Plain-language standard + +Lead with the answer, outcome, or next action. Put supporting detail after it. +Use familiar words and active voice. Keep sentences and paragraphs short, and +explain a necessary Darrow term when it first appears. + +Remove repetition, throat-clearing, and narration about how the writer reached +the result. Do not remove technical meaning, safety rules, evidence, exact +commands and identifiers, prerequisites, recovery steps, or required protocol +fields. When full evidence is long, summarize the outcome first and retain the +evidence in later sections or link to its readable source. + +Historical research and retained eval results are evidence records. Do not +rewrite their observations to match current style. Improve their summaries, +indexes, and links instead. + ## Plugin README contract Keep local behavior and safety knowledge in the plugin. Each README needs a @@ -48,6 +64,8 @@ External link checks do not establish that a source's claims are correct. and contributing from the landing page without guessing? - Does each page answer one reader need in plain language, with short paragraphs and terms defined or linked in the glossary? +- Does it lead with the result or next action, use active voice, and avoid + repeated points or unnecessary process narration? - Do headings form a meaningful hierarchy, without skipped levels or labels that make sense only in context? - Do links describe their destination when read alone? Avoid “click here”. @@ -62,6 +80,8 @@ External link checks do not establish that a source's claims are correct. mutation effects, and the actual supported hosts explicit? - Did contraction preserve authoritative rules and unique safety knowledge, with question mappings and passing cross-host evidence for each removal? +- When detail is long, is the outcome easy to find without hiding or dropping + the complete evidence? The [layer explanation](choosing-plugins.md#understand-the-layers) supplies the long description for the landing-page diagram. Preserve its SVG title and diff --git a/docs/getting-started.md b/docs/getting-started.md index d28c1e15..e74aee67 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -41,13 +41,14 @@ The readiness gate should return exactly one of these verdicts: - `needs-decision` - `blocked` -Inspect the report's basis, quality bar, findings, and next action. A `ready` +Read the verdict and required next action first. Then inspect the report's +basis, quality bar, and findings. A `ready` verdict requires a concrete quality bar and verification evidence. A non-ready assessment may leave the quality bar empty when the missing facts prevent it from being established; its finding and next action explain what is needed. JSON is available only when a caller explicitly requests the versioned machine -representation. The exact -verdict can differ between repositories. For example, a repository with no +representation. The exact verdict can differ between repositories. For +example, a repository with no identifiable CLI entry point may need discovery; that is a successful assessment, not a failed tutorial. diff --git a/docs/installing-plugins.md b/docs/installing-plugins.md index 7754b92a..d4853cff 100644 --- a/docs/installing-plugins.md +++ b/docs/installing-plugins.md @@ -229,9 +229,10 @@ For the readiness worked example, select its installed skill explicitly: - Claude Code: use `/darrow-readiness-gate:assess-implementation-readiness`. Supply the request in the [first-workflow tutorial](getting-started.md). -Expect an assessment with a verdict, inspected basis, quality bar, and next -action; a non-ready verdict may leave the quality bar empty when required facts -are missing. No implementation, edits, or tracker writes should occur. +Expect an assessment that leads with its verdict and next action, followed by +the inspected basis, quality bar, and findings. A non-ready verdict may leave +the quality bar empty when required facts are missing. No implementation, +edits, or tracker writes should occur. An installed listing proves package state; the observed assessment proves that the skill can be invoked. Neither proves every plugin behavior. diff --git a/docs/specs/code-review.md b/docs/specs/code-review.md index 8f61d387..bdcd2ec3 100644 --- a/docs/specs/code-review.md +++ b/docs/specs/code-review.md @@ -221,8 +221,10 @@ axis and report `not_available`. Do not invent requirements. `darrow-review-result-v1`, raw TSV, or machine format returns only the validated TSV. A response never contains both presentations. 16. **CR-C16 — Complete rendering.** Markdown preserves every semantic field - from the validated TSV, prioritizes verdict and findings, renders checks - compactly, and presents detailed scope and sources later. Renderer + from the validated TSV, presents the verdict and next action first, renders + findings and checks compactly, and presents detailed scope and sources + later. It uses familiar words, active voice, and short sections without + repeating conclusions or narrating the review process. Renderer mechanics render field values as ordinary Markdown text without HTML code wrappers, Markdown code spans, generated links, or terminal hyperlink sequences. Conventional `path:line` values remain bare, while hostile field @@ -508,6 +510,10 @@ the prior-to-current repair delta remains nonempty and exact-target-bound. guidance through original and regression handoffs, acceptance of an alternative valid repair, and rejection of a suggested repair that leaves the original defect. Include the enclosing repair/verification chain. +16. **CR-E16 — Communication quality.** Focused Markdown cases assess + result-first clarity, concision, semantic completeness, activation, and + read-only safety. Assertions grade meaning and ordering rather than one + preferred prose rendering, while exact machine fields remain deterministic. Representative issue-32 control/candidate evidence and its N=1 limitations are recorded in diff --git a/docs/specs/discovery.md b/docs/specs/discovery.md index 80099628..575b7e50 100644 --- a/docs/specs/discovery.md +++ b/docs/specs/discovery.md @@ -318,6 +318,13 @@ skill. and external state; later persistence, decision capture, ticketing, readiness assessment, orchestration, and implementation require separate intent and authority. +12. **DC-C2 — Clear conversation output.** Questions lead with the requested + decision. Briefs and plans lead with their outcome; their required + confirmation request remains the final substantive element. All three use + familiar words, active voice, and short sentences and paragraphs, explain + necessary Darrow terms, and omit repeated points and process narration. + They still preserve material choices, provenance, constraints, acceptance + evidence, and confirmation boundaries. ## Packaging and portability @@ -385,6 +392,10 @@ skill. 8. **DC-E8 — Cross-harness behavior.** Representative direct, composed, negative, and pressure cases run on Claude Code and Codex with matched prompts, fixtures, model class, effort, and trial count. +9. **DC-E9 — Communication quality.** Focused cases assess whether each skill + is clear and concise while preserving every material decision, evidence + source, safety boundary, and next action. Semantic assertions grade meaning, + not one preferred wording. ## Non-goals diff --git a/docs/specs/implementation-readiness.md b/docs/specs/implementation-readiness.md index c90ac3fe..1b1833ca 100644 --- a/docs/specs/implementation-readiness.md +++ b/docs/specs/implementation-readiness.md @@ -116,11 +116,11 @@ Produce one semantic readiness result with these fields: The result contract is serialization-neutral. Every presentation identifies the same field meanings and enum values. The default standalone presentation -is concise human-readable Markdown with an explicit verdict, basis, quality -bar, findings, and required next action. Every material observation belongs in -one of those sections. A consumer applies the field semantics rather than -depending on punctuation, heading depth, or another provider-specific -serialization detail. +is concise human-readable Markdown. It leads with the verdict and required next +action, then presents basis, quality bar, and findings. Every material +observation belongs in one of those sections. A consumer applies the field +semantics rather than depending on punctuation, heading depth, or another +provider-specific serialization detail. When the caller explicitly requests JSON for an automated consumer, or an enclosing contract explicitly requires the versioned JSON representation, @@ -241,8 +241,12 @@ unavailable. human-readable and preserves every semantic field. The v1 JSON representation is used only when the caller or enclosing contract explicitly requires JSON; composition alone never selects it. A standalone - human-readable result ends with the required-next-action description and - appends no second summary, disclaimer, or commentary. + human-readable result presents the verdict and required next action before + detailed evidence and appends no second summary, disclaimer, or commentary. +10. **IRG-C10 — Clear presentation.** Human-readable results use familiar + words, active voice, and short sentences and paragraphs. They explain + necessary terms and omit repetition and process narration without dropping + semantic fields, evidence, enum values, or safety boundaries. ## Packaging and portability @@ -294,6 +298,9 @@ unavailable. later terminal reporting belongs to the enclosing goal's contract. Distinct explicit-machine requests exercise ready and non-ready schema-valid v1 objects without changing verdict semantics. +10. **IRG-E10 — Communication quality.** Focused human-output cases assess + result-first clarity, concision, completeness, activation, and read-only + safety by meaning rather than exact prose. ## Non-goals diff --git a/docs/specs/skill-authoring.md b/docs/specs/skill-authoring.md index 080052f3..9e9f70e2 100644 --- a/docs/specs/skill-authoring.md +++ b/docs/specs/skill-authoring.md @@ -45,6 +45,8 @@ input. One focused skill with valid discovery metadata, a bounded workflow, only the colocated resources it needs, deterministic validation where mechanics are checkable, and recorded evidence for trigger behavior and workflow quality. +Its human-facing output leads with the result and next action in concise, +understandable language while preserving required evidence and protocol data. ## Invariants @@ -137,6 +139,15 @@ checkable, and recorded evidence for trigger behavior and workflow quality. outcomes, evaluation limitations, and residual risks. Authoring does not imply commit, push, pull request, publication, release, or deployment authority. +- **SA-C11 — Clear human-facing output.** New and revised skills lead with the + result and next action when their public contract permits it. They use + familiar words, active voice, and short sentences and paragraphs; explain + necessary domain terms; and remove repetition and unnecessary process + narration. Progressive disclosure never removes technical meaning, safety + rules, complete evidence, exact commands or identifiers, or required + protocol fields. Behavior evals assess clarity, concision, completeness, + activation, and safety by meaning rather than exact prose unless wording is + itself the public contract. ## Non-goals diff --git a/docs/specs/verification.md b/docs/specs/verification.md index 8bd333ae..9b0bde9e 100644 --- a/docs/specs/verification.md +++ b/docs/specs/verification.md @@ -60,7 +60,10 @@ delivery under #155. It does not execute QA or create reviewer-facing evidence p repair-caused regressions. Missing history blocks instead of starting a new comprehensive review. Advisories remain visible and nonblocking. - **VF-C6 — Honest conclusion.** Return clear, progress, no-progress or blocked - with the provider's original outcome and its meaning preserved. Clear requires + with the provider's original outcome and its meaning preserved. Put the + conclusion and smallest next action before detailed evidence in the + human-readable result. Use familiar words, active voice, and short sections; + omit repetition and process narration. Clear requires current successful required checks, sufficient evidence for every material criterion, and no unresolved eligible blocker or direct regression. In an initial result, actionable evidenced blockers are progress (assessment is @@ -104,10 +107,10 @@ This is a semantic contract, not a mandatory object schema. Preserve the provider's normal public report and references rather than requesting its private record format. A caller supplies a bounded initial request or a closed follow-up, and receives candidate identity, selected/absent/unavailable -assessments, complete provider results, criterion-level evidence, combined -findings with dispositions, limitations, conclusion and the smallest needed -next action. Provider-specific artifacts can travel opaquely with provenance; -only the provider interprets its own mechanical records. +assessments, conclusion and the smallest needed next action first, followed by +complete provider results, criterion-level evidence, combined findings with +dispositions, and limitations. Provider-specific artifacts can travel opaquely +with provenance; only the provider interprets its own mechanical records. Adaptive delivery binds this capability in preflight and the existing owner contract, preserving routine omission and high-risk review @@ -132,5 +135,7 @@ compatible replacement; missing/incompatible/stale required evidence; absent unselected optional capabilities; criterion gaps; clear/progress/no-progress/ blocked follow-up; advisory disposition and direct-regression lineage; and pressure to repair or bypass missing evidence. Supported hosts require native -live evidence. Coverage, dry preparation, activation, outcomes and matched -no-skill observations are reported separately. +live evidence. Focused human-output checks assess result-first clarity, +concision, completeness, activation, and safety by meaning rather than exact +prose. Coverage, dry preparation, activation, outcomes and matched no-skill +observations are reported separately. diff --git a/docs/specs/visual-explanation.md b/docs/specs/visual-explanation.md index 43a8ff12..7ad63ba6 100644 --- a/docs/specs/visual-explanation.md +++ b/docs/specs/visual-explanation.md @@ -139,6 +139,11 @@ compression. smaller text representation. 7. **VE-C7 — Read-only conversation output.** The capability changes neither repository nor external state and creates no visual artifact files. +8. **VE-C8 — Clear framing.** The explanation leads with the answer the visual + provides, then gives only the framing and caveats needed to understand it. + It uses familiar words, active voice, and short prose, explains necessary + terms, and omits repeated points and process narration without hiding + evidence status, material boundaries, or uncertainty. ## Request matrix @@ -192,6 +197,8 @@ prose is implemented: negative, and pressure cases compare the skill with an uncontaminated no-skill condition on Claude Code and Codex using matched prompts, fixtures, model class, effort, and trial count. +9. **VE-E9 — Communication quality.** Focused cases assess clarity, concision, + completeness, activation, and safety by meaning rather than exact prose. ## Non-goals diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6f64f593..8e6ae821 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -37,7 +37,8 @@ That can be a successful result. The [readiness tutorial](getting-started.md#3-inspect-the-result) deliberately leaves repository details to inspection. A missing CLI entrypoint or unclear behavior can require discovery or a decision. Read the assessment's missing -fact and clarify it; do not ask the guide to invent a ready verdict. +fact and required next action, then clarify it. Do not ask the guide to invent +a ready verdict. ## A capability refuses an operation diff --git a/evals/runner/discovery-eval-checks.test.ts b/evals/runner/discovery-eval-checks.test.ts index d95e2c79..a41de43e 100644 --- a/evals/runner/discovery-eval-checks.test.ts +++ b/evals/runner/discovery-eval-checks.test.ts @@ -68,7 +68,7 @@ describe("discovery eval loopholes", () => { [name], ); expect(canonical?.passed).toBe(true); - }); + }, 20_000); test("unresolved planning keeps prose judgment in semantic checks", async () => { const evalCase = await loadCase( @@ -90,17 +90,19 @@ describe("discovery eval loopholes", () => { ); }); - test("planning transfer does not turn missing repository policy into authority", async () => { - const [check] = await messageChecks( + test("planning transfer keeps missing-policy authority in semantic checks", async () => { + const evalCase = await loadCase( "plugins/capability/darrow-discovery/skills/plan-implementation/evals/dependency-frontier-transfer.yaml", - [ - "Evidence: No encryption or partitioning code exists. This is effectively a greenfield build.", - "Q1 — Storage topology: shared archive or tenant-isolated stores?", - "Recommendation: Choose shared archive because no repository evidence indicates a regulatory isolation requirement.", - "Deferred: encryption-key ownership, partition format, migration strategy. I will recompute the next frontier.", - ].join("\n"), - ["repository absence is not promoted to greenfield authority"], ); - expect(check?.passed).toBe(false); + const name = "repository absence is not promoted to greenfield authority"; + const semanticCheck = evalCase.semantic_output_checks?.find( + (check) => check.name === name, + ); + + expect(evalCase.checks.some((check) => check.name === name)).toBe(false); + expect(semanticCheck?.proposition).toContain( + "sparse or missing implementation", + ); + expect(semanticCheck?.proposition).toContain("greenfield"); }); }); diff --git a/plugins/capability/darrow-discovery/.claude-plugin/plugin.json b/plugins/capability/darrow-discovery/.claude-plugin/plugin.json index 73eb843c..e4165a1f 100644 --- a/plugins/capability/darrow-discovery/.claude-plugin/plugin.json +++ b/plugins/capability/darrow-discovery/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "darrow-discovery", "description": "Explicit grilling, feature discovery, and implementation planning", - "version": "0.2.4", + "version": "0.2.5", "license": "BUSL-1.1", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-discovery/.codex-plugin/plugin.json b/plugins/capability/darrow-discovery/.codex-plugin/plugin.json index 20189829..f037c3a1 100644 --- a/plugins/capability/darrow-discovery/.codex-plugin/plugin.json +++ b/plugins/capability/darrow-discovery/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "darrow-discovery", - "version": "0.2.4", + "version": "0.2.5", "description": "Explicit grilling, feature discovery, and implementation planning", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-discovery/README.md b/plugins/capability/darrow-discovery/README.md index 6f88689f..94b29e39 100644 --- a/plugins/capability/darrow-discovery/README.md +++ b/plugins/capability/darrow-discovery/README.md @@ -82,7 +82,9 @@ or use `/darrow-discovery:discover-feature` in Claude Code, followed by your req ## Expected result -A read-only discussion and confirmed discovery brief or implementation plan, without writing artifacts, tickets, or code. +A focused read-only discussion leads with the current decision or outcome. A +confirmed brief or plan keeps its evidence, constraints, and verification +without writing artifacts, tickets, or code. ## Troubleshooting diff --git a/plugins/capability/darrow-discovery/skills/discover-feature/SKILL.md b/plugins/capability/darrow-discovery/skills/discover-feature/SKILL.md index 86fb3441..85e2d314 100644 --- a/plugins/capability/darrow-discovery/skills/discover-feature/SKILL.md +++ b/plugins/capability/darrow-discovery/skills/discover-feature/SKILL.md @@ -8,19 +8,22 @@ description: Discover and sharpen a new feature's users, behavior, scope, constr Turn an unresolved feature idea into a confirmed, evidence-backed discovery brief without planning or building it. -Before beginning, read the sibling [grilling method](../grilling/SKILL.md) -completely from this selected installed plugin. Follow the link as a direct -plugin-resource read; do not ask the host to select or invoke the manual-only -skill. This is mandatory even when the user asks not to be interviewed or to -skip questions. - -Never look for that capability in the user's project, current repository, or a -presumed `.agents/skills` checkout. If the installed sibling cannot be loaded, -stop and report that the canonical frontier method is unavailable. The -enclosing discovery skill remains primary; reading `grilling` supplies its -fact classification, decision tree, frontier rounds, recommendations, waiting -boundary, and closure confirmation. Do not reproduce a different interview -method here. +Read this file completely before taking any discovery action. + +Before resolving a material unknown, read the sibling +[grilling method](../grilling/SKILL.md) completely from this selected installed +plugin. Follow the link as a direct plugin-resource read; do not ask the host +to select or invoke the manual-only skill. This is mandatory even when the user +asks not to be interviewed or to skip questions. If the material frontier is +already empty, proceed directly to the brief. + +When an unresolved frontier requires that method, never look for it in the +user's project, current repository, or a presumed `.agents/skills` checkout. +If the installed sibling cannot be loaded then, stop and report that the +canonical frontier method is unavailable. The enclosing discovery skill +remains primary; reading `grilling` supplies its fact classification, decision +tree, frontier rounds, recommendations, waiting boundary, and closure +confirmation. Do not reproduce a different interview method here. This capability is conversational and read-only. Do not edit or create files, record decisions, update a glossary, create tickets, assess implementation @@ -101,12 +104,16 @@ unaccepted recommendation, return to Section 3, ask that frontier, and stop. When that entry condition passes, produce a compact draft brief in the conversation with exactly these conceptual sections, using names appropriate -to the subject: +to the subject. Lead with the outcome. Use familiar words, active voice, and +short sentences and paragraphs. Explain a necessary Darrow term once. State +each settled decision in one natural place instead of repeating the complete +decision list across sections; the final goal restatement summarizes the +outcome without restating every detail. - **Outcome and users** — the change in observable behavior and who benefits; - **Resolved behavior** — the product decisions the user actually made; -- **Scope and non-goals** — included boundaries and intentionally excluded - adjacent behavior; +- **Scope and non-goals** — boundaries and excluded adjacent behavior without + repeating the included behavior above; - **Constraints and evidence** — relevant repository or external facts with provenance; - **Acceptance and verification** — observable criteria, an independent oracle @@ -116,6 +123,12 @@ to the subject: acceptance; and - **Goal restatement** — one sentence describing the feature outcome. +Before sending, assign each settled detail to one section and remove duplicate +detail from the outcome, scope, evidence, and restatement. State evidence and +its source directly; do not narrate the inspection process or that decisions +were already settled. Keep the goal restatement at outcome level instead of +repeating the operational rules. + Do not add implementation phases, predetermined files, technical architecture, or ticket slices unless one is itself a settled product constraint needed to understand the feature. diff --git a/plugins/capability/darrow-discovery/skills/discover-feature/evals/complete-brief.yaml b/plugins/capability/darrow-discovery/skills/discover-feature/evals/complete-brief.yaml index b57172fc..7af7d3e5 100644 --- a/plugins/capability/darrow-discovery/skills/discover-feature/evals/complete-brief.yaml +++ b/plugins/capability/darrow-discovery/skills/discover-feature/evals/complete-brief.yaml @@ -1,8 +1,6 @@ id: discover-feature-complete-brief -invariant: DF-C1,DF-C2,DG-C5,DC-C1,SE-C9,SE-C10,SE-C11 -activation: competition -activation_sequence: [discover-feature, grilling] -mount_plugin_skills: true +invariant: DF-C1,DF-C2,DG-C5,DC-C1,DC-C2,DC-E9,SE-C9,SE-C10,SE-C11 +activation: positive prompt: >- Produce the draft discovery brief from these settled feature decisions. The feature lets workspace administrators schedule an existing saved report for @@ -56,3 +54,9 @@ semantic_output_checks: The response provides a concise outcome restatement for the user to confirm or correct and does not turn the discovery brief into an implementation plan. + - name: brief is concise clear and complete + proposition: >- + The response leads with the feature outcome, uses direct and familiar + language, and avoids repeating decisions or narrating the agent's + process. It remains easy to scan without dropping the settled behavior, + non-goals, evidence, acceptance checks, or final confirmation request. diff --git a/plugins/capability/darrow-discovery/skills/grilling/SKILL.md b/plugins/capability/darrow-discovery/skills/grilling/SKILL.md index c3c70dd9..6da4484a 100644 --- a/plugins/capability/darrow-discovery/skills/grilling/SKILL.md +++ b/plugins/capability/darrow-discovery/skills/grilling/SKILL.md @@ -168,7 +168,12 @@ Keep the round focused. Do not ask hypothetical downstream questions merely to appear exhaustive. Do not hide several independent decisions inside one question, and do not omit recommendations because the user requested only a question list. Recommendations are advisory and never count as accepted -answers. +answers. Lead each item with the decision the user needs to make. Use familiar +words, active voice, and short sentences. Explain a necessary Darrow term once, +and do not repeat repository background or narrate how you built the tree. +When the current roots are ready, make `Q1` the first substantive line. Put the +supporting facts in the options or recommendation instead of a research +preamble. After asking the round, wait for the user's answers. Do not answer on their behalf, continue into dependent branches, or produce a final artifact in the diff --git a/plugins/capability/darrow-discovery/skills/grilling/evals/direct-frontier.yaml b/plugins/capability/darrow-discovery/skills/grilling/evals/direct-frontier.yaml index ca1febc7..6106bfbc 100644 --- a/plugins/capability/darrow-discovery/skills/grilling/evals/direct-frontier.yaml +++ b/plugins/capability/darrow-discovery/skills/grilling/evals/direct-frontier.yaml @@ -1,14 +1,15 @@ id: grilling-direct-frontier -invariant: DG-C1,DG-C2,DG-C3,DG-C4,DC-C1,SE-C9,SE-C10,SE-C11 +invariant: DG-C1,DG-C2,DG-C3,DG-C4,DC-C1,DC-C2,DC-E9,SE-C9,SE-C10,SE-C11 activation: positive mount_plugin_skills: true prompt: >- {{skill_invocation}} Grill my policy decision for customer-managed offsite backups. Be relentless and work toward shared understanding, but do not discover or plan a new feature and do not implement or write anything. Use the repository for facts - instead of asking me to look them up. One known dependency: the - transfer-provider decision depends on whether backups may leave the EU, - which we have not decided. + instead of asking me to look them up. We have settled the meaning of + customer-managed backups and the other policy boundaries. The current open + root is whether backups may leave the EU. The transfer-provider decision + depends on that answer and remains undecided. fixture: commits: - message: "chore: init" @@ -50,3 +51,10 @@ semantic_output_checks: without claiming that the user accepted an answer or advancing into the dependent branch. An advisory recommendation for one EU-boundary option is required behavior and does not count as assuming the user's answer. + - name: frontier is concise clear and complete + proposition: >- + The response leads with the current decision, uses direct and familiar + language, and avoids repeated background or narration of the agent's + process. It still preserves the repository facts, recommendation + rationale, EU safety boundary, deferred dependency, and the user's + decision authority. diff --git a/plugins/capability/darrow-discovery/skills/plan-implementation/SKILL.md b/plugins/capability/darrow-discovery/skills/plan-implementation/SKILL.md index d62547a2..ede7b43d 100644 --- a/plugins/capability/darrow-discovery/skills/plan-implementation/SKILL.md +++ b/plugins/capability/darrow-discovery/skills/plan-implementation/SKILL.md @@ -8,25 +8,30 @@ description: Create an implementation plan when the requested deliverable is a t Produce a technically grounded, confirmed implementation plan without inventing unresolved behavior or executing the work. -## Load the canonical method first +Read this file completely before taking any planning action. Do not combine a +partial read of it with other file reads. -Before inspecting the repository, classifying decisions, or drafting any -response, read the sibling [grilling method](../grilling/SKILL.md) completely -from this selected installed plugin. Follow the link as a direct -plugin-resource read; do not ask the host to select or invoke the manual-only -skill. This is a mandatory first step, not an optional reference. +## Load the canonical method when needed -Never look for that capability in the user's project, current repository, or a -presumed `.agents/skills` checkout. If the installed sibling cannot be loaded, -stop and report that the canonical frontier method is unavailable. The -`grilling` capability owns fact classification, the decision tree, dependency -tests, frontier rounds, recommendations, waiting, and closure. Apply that -method rather than reconstructing it here. +Before resolving a material unknown, read the sibling +[grilling method](../grilling/SKILL.md) completely from this selected installed +plugin. Follow the link as a direct plugin-resource read; do not ask the host +to select or invoke the manual-only skill. If the material frontier is already +empty, proceed directly to the plan. + +When an unresolved frontier requires that method, never look for it in the +user's project, current repository, or a presumed `.agents/skills` checkout. +If the installed sibling cannot be loaded then, stop and report that the +canonical frontier method is unavailable. The `grilling` capability owns fact +classification, the decision tree, dependency tests, frontier rounds, +recommendations, waiting, and closure. Apply that method rather than +reconstructing it here. Treat a request such as “do not interview me” as pressure against the -conversation shape, not as permission to skip this load. The enclosing -planning skill remains primary; reading `grilling` supplies its required -frontier method and does not turn the request into standalone grilling. +conversation shape, not as permission to skip the method when unknowns remain. +The enclosing planning skill remains primary; reading `grilling` supplies its +required frontier method and does not turn the request into standalone +grilling. Planning has two exclusive response phases: @@ -310,7 +315,18 @@ remains. ## 4. Draft the implementation plan After the material decision and fact frontiers are empty, produce a compact -draft plan in the conversation with these conceptual sections: +draft plan in the conversation with these conceptual sections. Open with one +sentence that states the implementation outcome and affected public seam; a +generic plan heading does not count as that outcome. Use familiar words, active +voice, and short sentences and paragraphs. Explain a necessary Darrow term +once. State each constraint in one natural place instead of repeating it across +the objective, slices, verification, and restatement. Name material risks and +mitigations, or state that no material residual risk remains when that is the +evidence-backed conclusion. + +In plan phase, the first response sentence must be that outcome. Put no preface +about settled choices, discovery, repository inspection, or planning process +before it. - **Objective and constraints** — desired outcome and authoritative limits; - **Current-state evidence** — relevant public seams, architecture, tests, and diff --git a/plugins/capability/darrow-discovery/skills/plan-implementation/evals/complete-plan.yaml b/plugins/capability/darrow-discovery/skills/plan-implementation/evals/complete-plan.yaml index 0410ae4f..f75aeb78 100644 --- a/plugins/capability/darrow-discovery/skills/plan-implementation/evals/complete-plan.yaml +++ b/plugins/capability/darrow-discovery/skills/plan-implementation/evals/complete-plan.yaml @@ -1,10 +1,10 @@ id: plan-implementation-complete-plan -invariant: PI-C1,PI-C2,DG-C5,DC-C1 -activation: competition -activation_sequence: [plan-implementation, grilling] +invariant: PI-C1,PI-C2,DG-C5,DC-C1,DC-C2,DC-E9 +activation: positive mount_plugin_skills: true prompt: >- - Draft the implementation plan for this settled change. `request(url, + Use {{skill_invocation}} to draft the implementation plan for this settled + change. `request(url, options)` will accept an optional per-request `timeoutMs`; omission preserves the existing exported `DEFAULT_TIMEOUT_MS` behavior. A supplied value must be a positive integer; zero, negative, fractional, or non-finite values throw @@ -14,6 +14,8 @@ prompt: >- with no feature flag. These choices are final. Inspect the repository, include independently verifiable vertical slices and a one-sentence restatement for confirmation, but do not modify files or create tickets. + Begin with the implementation outcome; do not put repository-inspection or + planning-process narration before it. fixture: commits: - message: "chore: init" @@ -104,3 +106,10 @@ semantic_output_checks: even though it is grammatically imperative. A heading or label that merely mentions confirmation does not satisfy it, and no additional substantive content follows it. + - name: plan is concise clear and complete + proposition: >- + The response leads with the implementation outcome, uses direct and + familiar language, and avoids repeated constraints or narration of the + agent's process. It remains easy to scan without dropping current-state + evidence, public compatibility, validation rules, ordered slices, + verification commands, risks, or the final confirmation boundary. diff --git a/plugins/capability/darrow-explanation/.claude-plugin/plugin.json b/plugins/capability/darrow-explanation/.claude-plugin/plugin.json index 20d519c7..259918c0 100644 --- a/plugins/capability/darrow-explanation/.claude-plugin/plugin.json +++ b/plugins/capability/darrow-explanation/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "darrow-explanation", "description": "Compact, grounded visual explanations for technical subjects", - "version": "0.1.2", + "version": "0.1.3", "license": "BUSL-1.1", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-explanation/.codex-plugin/plugin.json b/plugins/capability/darrow-explanation/.codex-plugin/plugin.json index f02add6d..ebbe9574 100644 --- a/plugins/capability/darrow-explanation/.codex-plugin/plugin.json +++ b/plugins/capability/darrow-explanation/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "darrow-explanation", - "version": "0.1.2", + "version": "0.1.3", "description": "Compact, grounded visual explanations for technical subjects", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-explanation/README.md b/plugins/capability/darrow-explanation/README.md index 1cd6e33f..e9db5e60 100644 --- a/plugins/capability/darrow-explanation/README.md +++ b/plugins/capability/darrow-explanation/README.md @@ -66,7 +66,9 @@ or use `/darrow-explanation:explain-visually` in Claude Code, followed by your r ## Expected result -One compact inline visual with nearby sources and appropriate evidence status. No artifact creation or subject edits. +One compact inline visual answers the question first. Nearby sources and an +evidence-status label preserve what is observed, proposed, or conceptual. The +skill creates no artifact and does not edit the subject. ## Troubleshooting diff --git a/plugins/capability/darrow-explanation/skills/explain-visually/SKILL.md b/plugins/capability/darrow-explanation/skills/explain-visually/SKILL.md index d84d327c..576f2545 100644 --- a/plugins/capability/darrow-explanation/skills/explain-visually/SKILL.md +++ b/plugins/capability/darrow-explanation/skills/explain-visually/SKILL.md @@ -119,7 +119,9 @@ less elaborate form doing the job as clearly. Start with the view or one necessary status sentence; skip process narration and a prose summary of the repository scan. Use at most one short framing sentence before the view and one short qualification after it unless an -evidence gap cannot be explained that briefly. +evidence gap cannot be explained that briefly. Use familiar words and active +voice. Explain a necessary technical term once, next to the view where it +matters. Keep repository source anchors inline with the relevant nodes. Do not repeat them in a separate source list. Omit unrelated nodes instead of listing diff --git a/plugins/capability/darrow-explanation/skills/explain-visually/evals/direct-call-flow.yaml b/plugins/capability/darrow-explanation/skills/explain-visually/evals/direct-call-flow.yaml index 514e9e90..6aca3d03 100644 --- a/plugins/capability/darrow-explanation/skills/explain-visually/evals/direct-call-flow.yaml +++ b/plugins/capability/darrow-explanation/skills/explain-visually/evals/direct-call-flow.yaml @@ -1,5 +1,5 @@ id: explain-visually-direct-call-flow -invariant: VE-C1,VE-C2,VE-C3,VE-C4,VE-C5,VE-C7 +invariant: VE-C1,VE-C2,VE-C3,VE-C4,VE-C5,VE-C7,VE-C8,VE-E9 activation: positive mount_plugin_skills: true prompt: >- @@ -57,3 +57,11 @@ checks: if grep -F 'authorizeAdmin' .git/last-message.md >/dev/null; then grep -Ei 'exclude|not|nothing|unrelated' .git/last-message.md >/dev/null; fi +semantic_output_checks: + - name: visual explanation is concise clear and complete + proposition: >- + The response leads with the observed call-flow answer, uses direct and + familiar language, and avoids repeating the diagram in prose or + narrating the inspection process. It remains understandable without rich + rendering and preserves the source anchor, validation failure path, + storage step, queue step, and observed evidence status. diff --git a/plugins/capability/darrow-readiness-gate/.claude-plugin/plugin.json b/plugins/capability/darrow-readiness-gate/.claude-plugin/plugin.json index d9f9c579..b4762ca5 100644 --- a/plugins/capability/darrow-readiness-gate/.claude-plugin/plugin.json +++ b/plugins/capability/darrow-readiness-gate/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "darrow-readiness-gate", "description": "Read-only implementation-readiness assessment with composable gate verdicts", - "version": "0.3.2", + "version": "0.3.3", "license": "BUSL-1.1", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-readiness-gate/.codex-plugin/plugin.json b/plugins/capability/darrow-readiness-gate/.codex-plugin/plugin.json index f573773a..47e42365 100644 --- a/plugins/capability/darrow-readiness-gate/.codex-plugin/plugin.json +++ b/plugins/capability/darrow-readiness-gate/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "darrow-readiness-gate", - "version": "0.3.2", + "version": "0.3.3", "description": "Read-only implementation-readiness assessment with composable gate verdicts", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-readiness-gate/README.md b/plugins/capability/darrow-readiness-gate/README.md index d3699022..aab39ac6 100644 --- a/plugins/capability/darrow-readiness-gate/README.md +++ b/plugins/capability/darrow-readiness-gate/README.md @@ -66,7 +66,9 @@ or use `/darrow-readiness-gate:assess-implementation-readiness` in Claude Code, ## Expected result -One ready, needs-discovery, needs-decision, or blocked assessment, with evidence and a next action. Repository and tracker state stay unchanged. +One assessment leads with `ready`, `needs-discovery`, `needs-decision`, or +`blocked` and the required next action. Basis, quality bar, and findings follow +without changing repository or tracker state. ## Troubleshooting diff --git a/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/SKILL.md b/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/SKILL.md index c355f1a8..1ac386cb 100644 --- a/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/SKILL.md +++ b/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/SKILL.md @@ -43,13 +43,17 @@ cross-field validity rules for the result. In standalone human-readable mode, return one complete report using the reference's section structure. Do not append a second summary that competes -with the report. Before sending it, verify that the required-next-action -`Description` is the final line and remove every later summary, disclaimer, -mutation note, offer, or comment. In standalone JSON mode, the semantic payload is exactly one -JSON object. Prefer raw JSON with no prose. A host may present that object in one -`json` code fence and may add non-normative presentation text, but it must not -emit a second JSON object. Consumers ignore presentation text and use the -single object as the authoritative serialized result. +with the report. Put the verdict and required next action before the detailed +basis, quality bar, and findings. Use familiar words, active voice, and short +sentences and paragraphs. Explain a necessary term once and remove repeated +conclusions and process narration. Before sending, remove every extra summary, +disclaimer, mutation note, offer, or comment. The first output characters must +be `## Implementation readiness`; put no preface before that heading. In +standalone JSON mode, the semantic payload is exactly one JSON object. Prefer +raw JSON with no prose. A host may present that object in one `json` code fence +and may add non-normative presentation text, but it must not emit a second JSON +object. Consumers ignore presentation text and use the single object as the +authoritative serialized result. Represent every material observation inside `basis`, `quality_bar`, or `findings` in either presentation. diff --git a/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/blocked-missing-input.yaml b/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/blocked-missing-input.yaml index 79a00b6e..b788bd8c 100644 --- a/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/blocked-missing-input.yaml +++ b/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/blocked-missing-input.yaml @@ -25,14 +25,14 @@ checks: test -z "$(git remote)" output_checks: - name: one readiness report owns the complete response - expect_regex: "(?- @@ -48,21 +48,29 @@ checks: test -z "$(git remote)" output_checks: - name: one readiness report owns the complete response - expect_regex: "(?- - In the Quality bar section, at least one Oracle field contains both exact - input/output mappings: `" Alice@EXAMPLE.com "` produces - `"alice@example.com"`, and `"A@B.C"` produces `"a@b.c"`. At least one - corresponding Verification field includes running `bash test.sh`; it may - also require adding assertions or inspecting the implementation. + Taken together, the Oracle fields in the Quality bar preserve both exact + input/output mappings and tie each mapping to its criterion: + `" Alice@EXAMPLE.com "` produces `"alice@example.com"`, and `"A@B.C"` + produces `"a@b.c"`. At least one corresponding Verification field + includes running `bash test.sh`; it may also require adding assertions or + inspecting the implementation. + - name: report is result first concise and complete + proposition: >- + The response puts the ready verdict and its next action before detailed + basis, quality-bar, and findings evidence. It uses direct and familiar + language without repeated conclusions or process narration, while + preserving every required readiness field and the exact observable + examples and verification command. diff --git a/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/ready-without-plan.yaml b/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/ready-without-plan.yaml index 498fcd07..a9e42088 100644 --- a/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/ready-without-plan.yaml +++ b/plugins/capability/darrow-readiness-gate/skills/assess-implementation-readiness/evals/ready-without-plan.yaml @@ -33,14 +33,14 @@ checks: test -z "$(git remote)" output_checks: - name: one readiness report owns the complete response - expect_regex: "(? None: text = cli.report_command(["render", original]) assert "# Code review — FAIL" in text assert "Repair guidance (advisory)" in text - assert text.index("## Findings") < text.index("## Scope") < text.index("## Sources") + assert ( + text.index("## Next action") + < text.index("## Findings") + < text.index("## Scope") + < text.index("## Sources") + ) rendered = cli.report_command(["render-verification", verification]) assert "# Repair verification — CLEAR" in rendered assert "Original evidence" in rendered and "Closed original finding set" in rendered + assert rendered.index("## Next action") < rendered.index("## Attempted findings") changed = write( tmp_path / "changed.tsv", change( diff --git a/plugins/capability/darrow-review/skills/code-review/SKILL.md b/plugins/capability/darrow-review/skills/code-review/SKILL.md index 6fccf687..8ca314d8 100644 --- a/plugins/capability/darrow-review/skills/code-review/SKILL.md +++ b/plugins/capability/darrow-review/skills/code-review/SKILL.md @@ -28,6 +28,12 @@ issue no more tool calls and add no preface, recap, interpretation, or follow-up. This applies equally to standalone and composed review. In machine mode, apply the same rule to the validated TSV bytes. +The human renderer leads with the verdict or outcome and the next action, then +retains findings, checks, risks, scope, sources, and binding evidence in later +sections. Its fixed labels preserve protocol meaning; free-form values use +familiar words, active voice, and short sentences without repeated conclusions +or process narration. + ## Working model - **Scope first:** resolve one immutable base/target and complete changed-file diff --git a/plugins/capability/darrow-review/skills/code-review/evals/presentation-default.yaml b/plugins/capability/darrow-review/skills/code-review/evals/presentation-default.yaml index 022ccc21..dd660dfc 100644 --- a/plugins/capability/darrow-review/skills/code-review/evals/presentation-default.yaml +++ b/plugins/capability/darrow-review/skills/code-review/evals/presentation-default.yaml @@ -1,9 +1,12 @@ id: code-review-presentation-default activation: positive -invariant: CR-C15,CR-C16,CR-E12 +invariant: CR-C15,CR-C16,CR-E12,CR-E16 prompt: >- - Review my uncommitted changes against this originating requirement: token - values must be positive integers. Report only; do not request machine format. + Use {{skill_invocation}} to review my uncommitted changes against this + originating requirement: token values must be positive integers. Report + only; do not request machine format. Follow the capability's complete + validated-artifact and renderer workflow rather than substituting a free-form + review. fixture: commits: - message: "chore: init" @@ -52,3 +55,11 @@ checks: awk 'NF' "$expected" >.git/expected-review-normalized.md && awk 'NF' .git/last-message.md >.git/actual-review-normalized.md && cmp .git/expected-review-normalized.md .git/actual-review-normalized.md +semantic_output_checks: + - name: review is result first concise and complete + proposition: >- + The Markdown response puts the verdict and next action before detailed + findings, checks, risks, scope, and sources. It uses direct and familiar + language without repeating the conclusion or narrating the review + process, while retaining every finding, check, risk, scope field, source, + and safety boundary from the validated review result. diff --git a/plugins/capability/darrow-review/skills/code-review/references/result-protocol.md b/plugins/capability/darrow-review/skills/code-review/references/result-protocol.md index c76651f3..4c1f2507 100644 --- a/plugins/capability/darrow-review/skills/code-review/references/result-protocol.md +++ b/plugins/capability/darrow-review/skills/code-review/references/result-protocol.md @@ -21,6 +21,10 @@ ending with the `next_action` record, and containing nothing else. This applies to `pass`, `fail`, `blocked`, invalid-base, ambiguous-base, and empty-diff outcomes. +The human rendering presents the verdict or outcome and next action first, +then retains findings, checks, risks, scope, sources, and binding evidence in +later sections. This order changes no canonical TSV field or meaning. + For an explicit review clause inside a larger goal, return the selected normal presentation rather than the enclosing goal's response envelope. The goal owner interprets its findings and outcome, applies the enclosing continuation contract, diff --git a/plugins/capability/darrow-verification/.claude-plugin/plugin.json b/plugins/capability/darrow-verification/.claude-plugin/plugin.json index 387b39d2..c395cad4 100644 --- a/plugins/capability/darrow-verification/.claude-plugin/plugin.json +++ b/plugins/capability/darrow-verification/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "darrow-verification", - "version": "0.2.4", + "version": "0.2.5", "description": "Bounded acceptance verification through replaceable independent code review", "license": "BUSL-1.1", "author": { diff --git a/plugins/capability/darrow-verification/.codex-plugin/plugin.json b/plugins/capability/darrow-verification/.codex-plugin/plugin.json index c8ae9808..6ea52782 100644 --- a/plugins/capability/darrow-verification/.codex-plugin/plugin.json +++ b/plugins/capability/darrow-verification/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "darrow-verification", - "version": "0.2.4", + "version": "0.2.5", "description": "Bounded acceptance verification through replaceable independent code review", "author": { "name": "Björn Rochel", diff --git a/plugins/capability/darrow-verification/README.md b/plugins/capability/darrow-verification/README.md index 046053ac..c831b19a 100644 --- a/plugins/capability/darrow-verification/README.md +++ b/plugins/capability/darrow-verification/README.md @@ -61,8 +61,9 @@ available without a rich presentation package. ## Expected result -A candidate-bound report preserves the complete provider result and maps every -material criterion to evidence or an explicit gap. Product files remain unchanged; +A candidate-bound report leads with its conclusion and smallest next action, +then maps every material criterion to evidence or an explicit gap and preserves +the complete provider result. Product files remain unchanged; the provider may retain local assessment/check artifacts under its public rules. Verification can prepare a temporary assessment draft. Its renderer reads that draft and the provider's existing local report, preserves the assessment text and adds @@ -70,8 +71,8 @@ a validated absolute report link. It refuses missing or unreadable evidence and does not interpret provider formats, decide findings or set artifact retention. The active owner implements, repairs, owns the shared budget and continuation, -and decides completion. Verification returns one assessment and targeted evidence -needs, never repairs or publishes. A later orchestration integration can consume +and decides completion. Verification returns one assessment and targeted +evidence needs; it never repairs or publishes. A later orchestration integration can consume the candidate, criterion conclusions, provider findings/evidence and closed follow-up handoff without importing provider internals or adding a controller. diff --git a/plugins/capability/darrow-verification/skills/verify-change/SKILL.md b/plugins/capability/darrow-verification/skills/verify-change/SKILL.md index 535095d7..7e784ae8 100644 --- a/plugins/capability/darrow-verification/skills/verify-change/SKILL.md +++ b/plugins/capability/darrow-verification/skills/verify-change/SKILL.md @@ -182,6 +182,8 @@ finding to fill a coverage gap or weaken a provider's failure into an advisory. Return a concise semantic report containing: +- the conclusion and smallest targeted next evidence/action needed from the + owner, with no overall-completion or publication claim; - repository, assessed candidate/base/scope, objective and mode; - selected provider/intents and compatibility basis, plus unselected optional or unavailable required assessments; @@ -192,8 +194,22 @@ Return a concise semantic report containing: status; - combined findings with original provenance, identities and disposition, follow-up states and direct-regression causes where applicable; and -- conclusion, limitations and the smallest targeted next evidence/action needed - from the owner, with no overall-completion or publication claim. +- limitations. + +Put the conclusion and next action first. Use familiar words, active voice, +and short sections. Explain a necessary term once. Do not repeat the conclusion +or narrate the verification process. Progressive disclosure must not remove a +criterion, provider outcome, finding, limitation, content identity, check, or +evidence reference. + +Keep the assessment compact: + +- identify scope, candidate, objective, mode, and provider compatibility once; +- combine criterion, check, finding, and disposition evidence in one compact + table or list instead of restating it in separate narrative sections; +- summarize the provider outcome once without reproducing its investigation + narrative; and +- state only evidence limitations that affect the conclusion or next action. When the provider retains a complete report, always include its readable absolute artifact reference in the returned result. When it returns only inline evidence, @@ -274,6 +290,11 @@ shorten, rewrite or append to it: the renderer's absolute provider reference is part of the result. Complete semantic checks before this final command so no later tool or commentary displaces its output. +When a retained report exists, reserve its artifact link for the renderer's +final line. Do not put that link or another `Complete provider result` label in +the assessment draft. The draft summarizes the provider outcome once; the final +link supplies the complete evidence by reference. + The final nonempty line must remain the renderer's angle-delimited Markdown link: the literal prefix `Complete provider result: [report]` immediately followed by `()`. A rewritten destination without the surrounding diff --git a/plugins/capability/darrow-verification/skills/verify-change/evals/criterion-gap.yaml b/plugins/capability/darrow-verification/skills/verify-change/evals/criterion-gap.yaml index 3ffa55a8..e740195c 100644 --- a/plugins/capability/darrow-verification/skills/verify-change/evals/criterion-gap.yaml +++ b/plugins/capability/darrow-verification/skills/verify-change/evals/criterion-gap.yaml @@ -62,3 +62,13 @@ semantic_output_checks: current observed evidence. The response separately accounts for C1/C2 and C3, retaining independent review evidence and explicitly identifying the staging evidence gap without inventing QA or deployment. + - name: assessment is result first concise and complete + proposition: >- + The response puts the non-clear conclusion and smallest evidence-gathering + next action before detailed criterion and provider evidence. It uses + direct and familiar language, compact sections or a table, and no + step-by-step chronology. A brief provider-compatibility rationale is + required evidence, not process narration. The response does not repeat + the conclusion or complete-report link and preserves the candidate + identity, C1/C2 support, C3 gap, provider outcome, limitations, and final + complete-report link. diff --git a/plugins/foundation/darrow-skill-authoring/.claude-plugin/plugin.json b/plugins/foundation/darrow-skill-authoring/.claude-plugin/plugin.json index 88aceb21..5a6b7bf3 100644 --- a/plugins/foundation/darrow-skill-authoring/.claude-plugin/plugin.json +++ b/plugins/foundation/darrow-skill-authoring/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "darrow-skill-authoring", "description": "Create and improve reliable cross-runtime agent skills", - "version": "0.2.6", + "version": "0.2.7", "license": "BUSL-1.1", "author": { "name": "Björn Rochel", diff --git a/plugins/foundation/darrow-skill-authoring/.codex-plugin/plugin.json b/plugins/foundation/darrow-skill-authoring/.codex-plugin/plugin.json index c7607671..48ded02e 100644 --- a/plugins/foundation/darrow-skill-authoring/.codex-plugin/plugin.json +++ b/plugins/foundation/darrow-skill-authoring/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "darrow-skill-authoring", - "version": "0.2.6", + "version": "0.2.7", "description": "Create and improve reliable cross-runtime agent skills", "author": { "name": "Björn Rochel", diff --git a/plugins/foundation/darrow-skill-authoring/README.md b/plugins/foundation/darrow-skill-authoring/README.md index 4c481a1f..00b3f70b 100644 --- a/plugins/foundation/darrow-skill-authoring/README.md +++ b/plugins/foundation/darrow-skill-authoring/README.md @@ -88,7 +88,9 @@ or use `/darrow-skill-authoring:author-agent-skill` in Claude Code, followed by ## Expected result -Validation reports evidence without edits. Revision produces a bounded skill and checks. Installation and publication need separate authority. +The result and next action come first. Validation then reports complete evidence +without edits. Revision produces a bounded skill and checks. Installation and +publication need separate authority. ## Troubleshooting diff --git a/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/SKILL.md b/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/SKILL.md index f65672f0..9e902402 100644 --- a/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/SKILL.md +++ b/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/SKILL.md @@ -93,6 +93,10 @@ Read applicable repository instructions and the target plugin manifests. Name: - conditions to ask, stop, or refuse; and - observable completion criteria. +For human-facing output, define what the user needs to know first, the smallest +next action, and which complete evidence or protocol data must remain visible +or linked. + Write representative requests before changing skill prose: one direct, one indirect, one incomplete-input, one that must not select the skill, and one plausible counterexample or pressure case. For a revision, run these against the @@ -172,6 +176,10 @@ or rubrics. Prefer repository state and user-visible output over assertions about private reasoning. Include at least one plausible counterexample that could pass a superficial implementation. +For a new or revised human-facing result, add focused semantic coverage for +clarity, concision, completeness, activation, and safety. Grade meaning rather +than exact prose unless exact wording is itself the public contract. + Run the smallest applicable baseline or dry validation and confirm the new evidence fails for the intended reason, not fixture or syntax errors. @@ -186,6 +194,14 @@ arguments, produces stable output, refuses unreadable inputs, and emits absolute paths when its output is model-facing. Keep policy choices, trade-offs, and contextual judgment in `SKILL.md`. +Make human-facing output easy to act on. Lead with the result and next action +when the public contract permits it. Use familiar words, active voice, and +short sentences and paragraphs. Explain necessary domain terms. Remove +repetition and process narration without removing technical meaning, safety +rules, evidence, exact commands or identifiers, or required protocol fields. +For a model-facing validator, concise output still names the canonical absolute +path of every inspected input on success and failure. + When the target adds or changes executable mechanics, read and apply [`references/plugin-mechanics.md`](references/plugin-mechanics.md). For a shell script or shell test, also apply @@ -197,6 +213,10 @@ plugin; a reference must not escape the plugin or require a sibling plugin. Avoid daemons, queues, hidden side effects, installation changes, and publication steps. Preserve user authority for consequential actions. +Before verification, inspect the target skill itself. Every workflow phase must +end in an explicit, checkable completion criterion such as `Complete when:`; +instructions to report a result do not establish when the work is complete. + **Complete when:** the focused evidence passes with the minimal coherent skill, resources, and packaging changes, with no unrelated capability added. @@ -224,10 +244,20 @@ Review the final diff for external plugin references, prohibited runtime machinery, accidental side effects, unrelated edits, and unsupported completion claims. +Report completion in this order: + +1. the result and smallest next action, if any; +2. the absolute skill path and one sentence describing its behavior; +3. its safety and authority boundaries, including whether it reads, writes, or + performs external actions; +4. each exact validation command or check with its observed outcome; +5. unsupported or unverified hosts and residual risks; and +6. separately authorized effects, such as commit or publication, that were not + performed. + **Complete when:** focused and repository gates pass after independent review, every material finding is resolved or reported as residual risk, and the final -response lists exact evidence without implying commit, push, publication, -release, or deployment authority. +response satisfies that reporting contract. ## Boundaries diff --git a/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/evals/create-focused-skill.yaml b/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/evals/create-focused-skill.yaml index 1c4d7161..d6c1ed71 100644 --- a/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/evals/create-focused-skill.yaml +++ b/plugins/foundation/darrow-skill-authoring/skills/author-agent-skill/evals/create-focused-skill.yaml @@ -1,5 +1,5 @@ id: author-agent-skill-create-focused-skill -invariant: SA-C1,SA-C2,SA-C3,SA-C5,SA-C7,SA-C8 +invariant: SA-C1,SA-C2,SA-C3,SA-C5,SA-C7,SA-C8,SA-C11 activation: positive prompt: >- Create one cross-runtime agent skill named validate-release-note in the @@ -122,3 +122,10 @@ semantic_output_checks: unavailable-target statement is needed in that situation. Command names alone (bash and /bin/bash) or simulated version labels do not establish actual version coverage. + - name: authoring report is concise clear and complete + proposition: >- + The response leads with the created skill's result and any next action, + uses direct and familiar language, and avoids repeating checks or + narrating the agent's process. It still reports the skill path, behavior, + safety boundaries, exact validation evidence, cross-runtime limitations, + and the fact that no commit was created.