From 9169552b7a5cfec3d4e25129b1fcd63aa58e303f Mon Sep 17 00:00:00 2001 From: CheckPickerUpper <194722943+CheckPickerUpper@users.noreply.github.com> Date: Tue, 22 Sep 2026 12:03:01 -0400 Subject: [PATCH] Add compose-goal skill --- .claude-plugin/plugin.json | 1 + README.md | 1 + skills/productivity/README.md | 1 + skills/productivity/compose-goal/SKILL.md | 174 +++++++++++++ .../compose-goal/references/goal-rules.md | 234 ++++++++++++++++++ .../compose-goal/references/pull-goal.md | 35 +++ 6 files changed, 446 insertions(+) create mode 100644 skills/productivity/compose-goal/SKILL.md create mode 100644 skills/productivity/compose-goal/references/goal-rules.md create mode 100644 skills/productivity/compose-goal/references/pull-goal.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index df8b1f1..2d20d44 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -4,6 +4,7 @@ "./skills/engineering/antimatter-code-quality-review", "./skills/engineering/pizza1", "./skills/engineering/readonly", + "./skills/productivity/compose-goal", "./skills/productivity/dependency-trace", "./skills/productivity/grill-with-docs-requiem", "./skills/productivity/to-issues-clearly" diff --git a/README.md b/README.md index 80c3fca..071c6c6 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ Skills for code, architecture, APIs, and design decisions, with an emphasis on c General workflow tools. +- **[compose-goal](./skills/productivity/compose-goal/SKILL.md)** — Compose or retrieve a gist-backed agent goal with a human outcome, live issue references, traceable implementation scope, and real behavior proof. - **[dependency-trace](./skills/productivity/dependency-trace/SKILL.md)** — Derive a correctness dependency graph before implementation. Use when determining foundations, dependency order, or a lowest-to-highest flow for a feature. - **[grill-with-docs-requiem](./skills/productivity/grill-with-docs-requiem/SKILL.md)** — A design interview that asks useful batches, infers obvious answers, and records settled domain language and ADRs as the conversation progresses. Use when sharpening a plan while maintaining docs. - **[to-issues-clearly](./skills/productivity/to-issues-clearly/SKILL.md)** — Create GitHub issues whose titles a stranger can act on. Refuses rhetoric, sarcasm, personified code, and type vocabulary dressed as domain language; splits issues by whether anything visibly breaks; errs granular, demands watchable acceptance criteria, and wires real GitHub sub-issue edges rather than prose references. Use when turning a plan, audit or bug report into tracked work. diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 1d0df17..de00776 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -2,6 +2,7 @@ General workflow tools. +- **[compose-goal](./compose-goal/SKILL.md)** — Compose or retrieve a gist-backed agent goal with a human outcome, live issue references, traceable implementation scope, and real behavior proof. - **[dependency-trace](./dependency-trace/SKILL.md)** — Derive a correctness dependency graph before implementation. Use when determining foundations, dependency order, or a lowest-to-highest flow for a feature. - **[grill-with-docs-requiem](./grill-with-docs-requiem/SKILL.md)** — A design interview that asks useful batches, infers obvious answers, and records settled domain language and ADRs as the conversation progresses. Use when sharpening a plan while maintaining docs. - **[to-issues-clearly](./to-issues-clearly/SKILL.md)** — Create GitHub issues whose titles a stranger can act on. Refuses rhetoric, sarcasm, personified code, and type vocabulary dressed as domain language; splits issues by whether anything visibly breaks; errs granular, demands watchable acceptance criteria, and wires real GitHub sub-issue edges rather than prose references. Use when turning a plan, audit or bug report into tracked work. diff --git a/skills/productivity/compose-goal/SKILL.md b/skills/productivity/compose-goal/SKILL.md new file mode 100644 index 0000000..27b6438 --- /dev/null +++ b/skills/productivity/compose-goal/SKILL.md @@ -0,0 +1,174 @@ +--- +name: compose-goal +description: "Compose or retrieve a gist-backed agent goal from a task or GitHub issues. Use when handing work to another agent and require a human outcome, live issue references, real behavior proof, and an explicit hard-blocker contract." +user-invocable: true +argument-hint: "" +short_description: "Compose or retrieve a verified agent goal." +allow_implicit_invocation: true +--- + +# Compose Goal + +Compose one executable goal from a task, or pull and run an existing goal +capsule. + +When the request is to pull a goal rather than compose one, read +references/pull-goal.md and follow that branch. The pulled goal remains the +source of its outcome, verification, and hard-blocker contract. + + +## Compose branch + +### 0. Resolve ambiguity with the user + +Before drafting or publishing, apply this gate: + +- In Claude, when any material ambiguity remains, use the `AskUserQuestion` + tool to ask focused questions about the human outcome, scope, target + repository, or proof. Wait for the answers before drafting or publishing. +- In every other agent, when a material ambiguity remains, ask one to three + focused questions. Ask them together when possible, and wait for the answers + before drafting or publishing. +- When no material ambiguity remains, continue without asking a question. + +Do not ask a ceremonial question or use a plain-text question in Claude when +`AskUserQuestion` is available. Never invent an answer to pass this gate. + +Completion criterion: every material ambiguity is resolved, and any required +user answers have been received. + +### 1. Load the drafting contract + +Read references/goal-rules.md before drafting. + +Read the target repository's instruction files and inspect the commands that +define its test, build, and verification surfaces. Follow those instructions +when composing or publishing the goal. + +When the request names GitHub issues, resolve the owner and repository, then +read every issue's current full body with: + +~~~bash +gh issue view --repo --json number,title,state,body +~~~ + +Use the issue bodies as composer input. The published goal records the +repository and issue references, not copied issue bodies or copied acceptance +criteria. + +Completion criterion: the user request, target repository, relevant +instructions, live issue bodies, and available proof surfaces are identified. + +### 2. Establish the outcome + +Write the human outcome before listing implementation work. State what a person +can do when the goal is complete, what must be true in the product, and why it +matters. + +Treat crate counts, file migrations, deleted languages, closed issues, and +proof files as means or evidence. They may constrain or verify the work, but +they cannot replace the outcome. + +Keep one goal to one coherent human outcome. If the requested issue set +contains separate outcomes, resolve that split before publishing instead of +flattening unrelated work into one goal. + +Completion criterion: the outcome can be read without opening the repository, +and every requested behavior has a place in that outcome. + +### 3. Run the traceability gate + +For every behavior named in the outcome, privately map four things: + +- the source of the requirement: the user's request or a live issue reference; +- the implementation surface that is in scope to make it true; +- the real product, API, client, or test state that proves it; and +- the output the executing agent must show in the transcript. + +A verification step is traceable only when all four are present. A browser +screen, route, or workflow may be absent today when the goal explicitly +includes building it. A proof-only screen is never an implementation surface. + +When a required verification step names behavior outside the goal's boundaries, +ask one focused question or report the exact orphan requirement before +publishing. Do not fill the gap with a fake page, state-changing buttons that +touch no product state, a screenshot, a recording, or a file whose existence +only proves that the artifact was made. + +Completion criterion: every outcome behavior and verification step has one +requirement source, one in-scope implementation path, and one real proof +surface, or the goal is held for the user's decision. + +### 4. Draft the goal + +Use the exact structure in references/goal-rules.md. + +The top of the goal contains the human outcome and its short current-state +paragraph. The task is imperative and preserves the full requested scope. +Verification describes real behavior and transcript-visible output. Screenshots, +videos, and GIFs are supporting evidence unless the user explicitly requested +the artifact itself as the outcome. + +For issue-sourced work, use this shape: + +~~~markdown +## Issues in scope + +Repository: + +Read each issue's live body before changing files or verifying the result: + +- # +- # +~~~ + +Do not paste issue bodies into the goal. The issue number is the reference and +the live issue is the source of its detailed acceptance criteria. Never make +"all issues are closed" the only verification. + +Completion criterion: the draft has one human outcome, live issue references +where applicable, real behavior proof, and the behavioral contract plus +hard-blocker list from references/goal-rules.md. + +### 5. Publish the goal + +Write the full goal to a scratchpad file named goal.md outside the target +repository, then create a private gist. Secret is the default, so pass no +visibility flag: + +~~~bash +gh gist create /goal.md --desc "agent goal: " +~~~ + +The final output line is the gist URL. Keep the filename goal.md. To revise an +existing goal, edit the same gist and keep that filename. + +Completion criterion: the gist exists and its goal.md contains the exact draft +that passed the traceability gate. + +### 6. Copy and verify the handoff + +Write only the short pull directive beside goal.md. It must start with /goal, +include the verification sentence, and contain no trailing newline. + +~~~bash +printf '%s' "/goal Pull the agent goal from <gist-url> through compose-goal's pull branch, read it, and complete it exactly as written. Done when <verification sentence>; paste each verification command's output into the transcript as proof. Keep working until every verification line is true. Stop only on a hard blocker or if I say stop." > <scratchpad-dir>/directive.txt +wl-copy < <scratchpad-dir>/directive.txt +wl-paste > <scratchpad-dir>/directive-readback.txt +cmp -- <scratchpad-dir>/directive.txt <scratchpad-dir>/directive-readback.txt +~~~ + +If gist publication or clipboard readback fails, surface the exact error and +stop. Do not paste the full goal into chat as a fallback. + +Completion criterion: the readback matches directive.txt byte for byte and the +directive starts with /goal. + +### 7. Report + +Report one line naming the gist URL and the copied directive length. Tell the +user to paste with Ctrl+V. + +Completion criterion: the handoff report is the only user-facing output of the +compose branch. +</what-to-do> diff --git a/skills/productivity/compose-goal/references/goal-rules.md b/skills/productivity/compose-goal/references/goal-rules.md new file mode 100644 index 0000000..6bf3e55 --- /dev/null +++ b/skills/productivity/compose-goal/references/goal-rules.md @@ -0,0 +1,234 @@ +# Rules for the compose-goal skill + +Composer-facing: this file is drafting guidance. Copy only the behavioral +contract and hard-blocker list into a goal. Never publish this rulebook as part +of the goal. + +The goal is an execution contract, not a backlog export. It tells an agent what +a person must be able to do, how that behavior is owned, and what evidence will +prove it. + +## Outcome before implementation + +The first sentence names the human outcome. The paragraph beneath it explains +the current state, the failure it causes, and the state the goal creates. + +Implementation details belong in the task, constraints, or boundaries. Issue +closure, deleted files, migrated languages, crate counts, screenshots, and +recordings are not outcomes. + +A useful cold-read test is: can a person who has never opened the repository say +what they will be able to do when the goal is complete? + +Example: + +~~~text +BAD +# Agent Goal: Finish the API migration +Verified by: a browser recording shows signup, booking, deposits, and history; +rust-backend-walk.gif exists. + +GOOD +# Agent Goal: Let an operator complete and review the full booking workflow in the product +When this is complete, an operator can sign up, invite staff, connect payments, +take a registration and booking deposit, schedule the balance, hold and release +a damage deposit, message a customer, store a file, and see who changed each +record and when. + +The recording, if requested, is evidence of those real actions. It is not the +thing being built. +~~~ + +The good form makes a fake page visibly insufficient because the outcome is a +product capability, not a file or recording. + +## One outcome and full scope + +One goal carries one coherent human outcome. Keep every requested behavior that +belongs to that outcome. Do not rename a large task as a smaller migration or +split it into unrequested phases. + +When issues are involved, check that every referenced issue contributes to the +same outcome. An implementation issue can belong when its change is required +for the outcome, but its role must be clear in the task or boundary. An +unrelated issue, a second user outcome, or a separate product decision needs a +separate goal or one focused user decision before publication. + +The goal's completion test is whether the person can perform the outcome. A +goal that can be completed by closing issues or deleting files has lost the +product target. + +## Issues are live references + +Issue bodies are composer input and execution-time source material. Read each +full body while composing so the outcome and traceability are grounded in the +actual request. Record only the repository and issue reference in the published +goal: + +~~~markdown +## Issues in scope + +Repository: owner/repo + +Read the current body of each issue before acting: + +- owner/repo#123 +- owner/repo#456 +~~~ + +Do not paste issue bodies, copied acceptance criteria, or paraphrased issue +sections into the goal. That creates a second requirement store that grows the +gist, drifts from GitHub, and hides which issue owns each behavior. + +At execution time, fetch the live body again. If the body has changed, use the +current text only when it still fits the goal outcome and boundaries. If it +changes the outcome, required surface, or verification contract, report the +issue number and the conflict before writing. + +Issue state is bookkeeping. Closing an issue is not proof that the product +behavior works. The goal must name the command, request, or observable state +that proves each behavior. + +## Traceability gate + +Build a requirement-to-proof map before drafting: + +| Human behavior | Source | In-scope implementation | Real proof | +| --- | --- | --- | --- | +| the person can complete ... | user request or repo#N | product/API/client/test path | command and output or observed state | + +The map may stay in the composer's scratchpad. The published goal must still +make the outcome, boundaries, issue references, and proof surface explicit. + +Every verification step must point to a behavior in the outcome. Every behavior +must point to a requirement source and an in-scope path that can make it true. + +A screen, route, or browser flow missing today is valid only when the goal +includes the work that creates or repairs it. If the goal excludes that work, +the verification step is orphaned. Hold the goal before publication and ask one +focused question or report the exact missing scope. + +A screenshot, video, GIF, fixture, or report is evidence only when it records +real product behavior. It becomes a deliverable only when the user explicitly +asks for that artifact as the outcome. A proof artifact cannot create a missing +screen, database row, payment, message, file, or history record. + +For browser proof, each step must use the real product or API-backed application, +perform a real user action, and leave or reveal real state. A static page with +buttons that only update local display state proves only that the static page +works. + +The executing agent should surface the relevant command output, API response, +database state, or browser result in the transcript. Silent success and file +existence alone are not enough when the claim is behavior. + +## Evidence rules + +Start with one line: + +Verified by: <concrete evidence joined with AND>. + +Each clause names: + +- the behavior it proves; +- the command, request, or interaction that exercises it; and +- the output or state that counts. + +Use live issue references for detailed acceptance criteria, but add the proof +surface. For example: + +~~~text +Verified by: owner/repo#731's live acceptance criteria are met, with the real +checkout request returning the expected response and the end-to-end test +printing its passing summary. +~~~ + +Do not use these as sole gates: + +- works as expected; +- looks good; +- tests pass without a runner and output; +- all issues are closed; +- a screenshot, recording, or GIF exists; +- a page contains the requested labels. + +Join independent gates with AND. An AND gate is valid only when every clause +proves part of the same human outcome. Remove a clause that has no owner, +implementation path, or real proof. + +When the work is testable, end the goal with the exact repository test +invocation. Discover it from the repository's scripts or instructions; do not +guess a runner. For docs, chores, and config, use a concrete file-content, +grep, or other runner-free check. + +## Goal shape + +Draft in this order: + +1. # Agent Goal: <plain-language outcome title> +2. One short current-state paragraph. +3. The full task in imperative voice. +4. Verified by: <concrete, AND-joined evidence>. +5. ## Issues in scope, containing repository and issue references only. +6. ## Verification, with one bullet per command or interaction and the output + that counts. +7. ## Constraints. +8. ## Boundaries, including the natural surface and an escape hatch for a + shared dependency that needs to change. +9. ## Between iterations. +10. The behavioral contract below. +11. The hard-blocker list below. + +The title and paragraph stay in plain product language. The task carries the +implementation detail. The issue section points at live ownership. The +verification section proves the outcome. Do not add drafting commentary, +backlog summaries, or copied issue bodies. + +## Behavioral contract while pursuing this goal + +1. Keep the human outcome as the target. Treat issue closure, implementation + migrations, screenshots, recordings, fixtures, and file lists as means or + supporting proof. +2. Prove real behavior. Drive the actual product, API, client, or test path and + show output that establishes the resulting state. A visual artifact cannot + substitute for missing product behavior. +3. Read every referenced issue live before implementation and verification. Use + current issue text only when it still fits the outcome and boundaries. +4. Keep the full requested scope. When normal implementation work is difficult, + inspect more code, find the owning path, and continue. +5. Surface transcript-visible proof for every verification clause. Show the + command, request, interaction, and confirming output or state. +6. When a browser step lacks an in-scope real product path, report the exact + orphan requirement instead of making a proof-only screen. +7. Continue until every outcome and proof gate is true. Do not add a turn or + time limit. +8. Follow the target repository's instruction files. This goal does not + override system, platform, or repository rules. +9. Stop only for a hard blocker from the list below or when the user says stop. + +## Hard blockers + +Hard blockers are the only reasons to stop short of the verification gate: + +- Authentication failure that no command can recover, such as an expired token + with no refresh path. +- Network unreachable for a required remote operation. +- Irrecoverable merge conflict in business logic that the agent cannot resolve. +- Build environment corrupted beyond recovery in the current session. +- A required behavior or verification clause has no implementation path inside + the goal's boundaries, and adding that path would change the requested + outcome or scope. Report the exact clause, the missing path, and the decision + required. +- A live issue materially conflicts with the goal's outcome, boundaries, or + verification contract and cannot be reconciled without user direction. +- The user explicitly says stop in a follow-up turn. + +These are normal work, not blockers: + +- Hook, lint, type, or test failures. Fix the implementation or the test's + wrong invariant and continue. +- A large issue set or a long implementation. +- A missing screen when the goal explicitly includes building the screen. +- A long live issue body. Read it; do not copy it into the goal. +- An artifact that has not yet been produced when it is only supporting proof. +- Uncertainty about an implementation path. Read more code and find the owner. diff --git a/skills/productivity/compose-goal/references/pull-goal.md b/skills/productivity/compose-goal/references/pull-goal.md new file mode 100644 index 0000000..0ed7c94 --- /dev/null +++ b/skills/productivity/compose-goal/references/pull-goal.md @@ -0,0 +1,35 @@ +# Pull Goal + +Use this branch when the user provides a /goal directive, a gist reference, or +asks to pull an existing goal. + +## 1. Resolve the gist reference + +Accept a bare gist id, a gh:gist:<id> reference, or a +https://gist.github.com/.../<id> URL. If the prompt contains more than one +reference, use the first one and ignore surrounding prose. + +## 2. Pull the goal text + +compose-goal names the gist's file goal.md. Pull it by that name: + +~~~bash +gh gist view <id> --filename goal.md --raw +~~~ + +Save the output to a scratchpad file before reading or acting on it. If gh is +missing, unauthenticated, or the gist is inaccessible, surface the exact error +and stop. + +If the pulled goal names GitHub issues, read each live issue from the repository +and number recorded in the goal before changing files. The gist is not a frozen +copy of issue bodies. + +## 3. Continue or stop + +If the current message is a /goal directive or asks you to complete or run the +goal, follow it exactly. Preserve its human outcome, live issue references, +real-behavior proof, and hard-blocker contract. + +Otherwise reply with one line naming the scratchpad file. Do not summarize the +goal body unless explicitly asked.