@codegiveness/kernel-prompt 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Kernel Prompt
 
+## [0.4.1] - 2026-10-10
+
+### Changed
+
+- Deliver the improved prompt inside a fenced code block, ready to copy and send, instead of as plain text; a prompt that itself contains triple backticks is wrapped in a four-backtick fence. Update the README's description of the delivery format.
+- Document the release workflow in `RELEASING.md` (issue, worktree branch, pull request, squash-merge, tag, GitHub release, and staged npm publish approved by the maintainer with two-factor authentication) and link it from the README. `AGENTS.md` now requires every update to follow it and npm releases to be staged, never published directly.
+- Add a pull request template and issue forms for bug reports and change requests.
+
+## [0.4.0] - 2026-10-10
+
+### Changed
+
+- Treat the text written with the invocation as the prompt to improve, even when it reads as a task. Files, skills, URLs, and repositories it mentions are read as context and referenced in the prompt, never rewritten or summarized as the deliverable; a file or quoted text is transformed only when the user says it is the prompt.
+- Add a "Never do the task" rule: the deliverable is an instruction to an agent, not the agent's output, with a pre-reply check that discards any executed result. Create or edit no files unless asked to save the prompt.
+- Always ask one round of 2–5 questions before drafting, each led by a recommended answer and anchored in the context read, unless the user says "no questions" or "just write it". Ask further rounds only for decisions the previous answers opened. Replaces the conditional questioning of 0.3.0.
+- Rewrite KERNEL as guidance for writing the prompt: undecided choices are delegated explicitly or marked open, never guessed, and the handoff is written for a capable agent that lacks the conversation.
+- Deliver the prompt alone as plain text, ready to send, with no intro, analysis, critique, or change log, followed by at most 3 unconfirmed assumptions.
+- Narrow the description to invoking the skill or asking to compose or improve an LLM prompt or an instruction for another AI.
+- Add a short harness-neutral example contrasting delivering an improved artifact (wrong) with asking questions first and then writing a prompt (right), using placeholder paths and references.
+- Update the README to describe the always-ask round, the delivery format, and the context-only treatment of referenced files.
+
 ## [0.3.0] - 2026-10-10
 
 ### Changed

package/README.md

@@ -1,8 +1,8 @@
 # Kernel Prompt
 
-`kernel-prompt` is a small, harness-neutral prose skill for improving an existing prompt or composing one from a goal. It rewrites and reorganizes where useful while preserving intent. It designs the prompt, not the underlying task's result.
+`kernel-prompt` is a small, harness-neutral prose skill that turns your message—a draft prompt or a task you want an AI agent to do—into an improved prompt for that agent. It asks one round of questions first, then writes the prompt while preserving your intent. It writes the instruction, never the task's result.
 
-Select it for requested prompt design, including prompt-design feedback or instructions to hand off to another AI. Reviewing documents or collaboration guidance—even with wording suggestions—is not by itself a match. Asking to turn that guidance into a system prompt is.
+Select it when you invoke it by name or ask to compose or improve an LLM prompt or an instruction for another AI. Reviewing documents or collaboration guidance—even with wording suggestions—is not by itself a match. Asking to turn that guidance into a system prompt is.
 
 ## Use it
 
@@ -13,24 +13,26 @@ Use kernel-prompt to improve this request:
 [your goal or draft, with relevant context and constraints]
 ```
 
-Expect a usable prompt, a short round of questions when a decision only you can make matters, or a draft with explicit unknowns when answers are unavailable. Invoking the skill with text that reads as a task—"fix the failing login test"—yields a prompt for that task, not the fix. Questions use the harness's question tool when one exists, each led by a recommended answer. Ask for explanations or alternatives when wanted.
+Expect one round of two to five questions before any draft, each led by a recommended answer and using the harness's question tool when one exists. Say "no questions" or "just write it" to skip them. A further round comes only for decisions your answers opened. The reply is the prompt alone, inside a fenced code block ready to copy and send (a four-backtick fence when the prompt itself contains triple backticks), followed by at most three assumptions you did not confirm; decisions you left unsettled are delegated to the agent or marked open in the prompt, never guessed.
+
+Invoking the skill with text that reads as a task—"fix the failing login test"—yields a prompt for that task, not the fix. Files, skills, URLs, and repositories you mention are read as context for the prompt, not rewritten as the deliverable, unless you say that text is the prompt to improve. No files are created or edited unless you ask to save the prompt.
 
 ## The idea
 
-A kernel makes the intended outcome, relevant context, boundaries, and completion conditions clear. Add detail where it helps the task; leave unassigned execution choices open. Facts are looked up, not asked; only decisions the user alone can make become questions. Before handing over, the draft is read as its recipient would read it—capable, without the conversation, unable to ask.
+A kernel makes the intended outcome, relevant context, boundaries, and completion conditions clear. Add detail where it helps the task; leave unassigned execution choices open. Facts are looked up, not asked; only decisions the user alone can make become questions. The prompt is written for its recipient—a capable agent without the conversation, unable to ask—and checked before replying so it holds the instruction, not the task's result.
 
 **KERNEL** is a mnemonic, not a mandatory sequence or template:
 
 - **K**eep intent.
 - **E**stablish what is known.
-- **R**esolve consequential ambiguity.
+- **R**esolve ambiguity.
 - **N**ame the work and boundaries.
 - **E**xpress success.
 - **L**ay out the handoff.
 
 The guiding reference is OpenAI's [Rethinking skills and prompts for GPT-6 Astra](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra). Revisit accumulated instructions, avoid unnecessary recipes, and adapt guidance to the task and model. The article's model-specific advice is not a universal rule; clearer prompts do not guarantee correct answers.
 
-The questioning adapts Matt Pocock's [grilling](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) (rounds of independent decisions with recommended answers; facts versus decisions) and the recipient check adapts the builder check in obra's [brainstorming](https://github.com/obra/superpowers/tree/main/skills/brainstorming), scaled down so a clear request gets no questions.
+The questioning adapts Matt Pocock's [grilling](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) (rounds of independent decisions with recommended answers; facts versus decisions) and the recipient framing adapts the builder check in obra's [brainstorming](https://github.com/obra/superpowers/tree/main/skills/brainstorming), scaled down to one round before drafting unless you skip it.
 
 ## Optional installation
 
@@ -52,7 +54,7 @@ The skill is also published as [`@codegiveness/kernel-prompt`](https://www.npmjs
 npm install @codegiveness/kernel-prompt
 ```
 
-Then copy `node_modules/@codegiveness/kernel-prompt/skills/kernel-prompt/` into your harness's skill location. Releases are staged with `npm stage publish` and go live only after a maintainer approves them with two-factor authentication.
+Then copy `node_modules/@codegiveness/kernel-prompt/skills/kernel-prompt/` into your harness's skill location. Releases are staged with `npm stage publish` and go live only after a maintainer approves them with two-factor authentication; [RELEASING.md](RELEASING.md) lists the full release workflow.
 
 Versions 0.1.0 through 0.2.0 remain deprecated: they carry historical skill content, and 0.1.x also shipped an `install`/`update` CLI that no longer exists. Replace only your existing Kernel Prompt skill with the current `SKILL.md`, preserving local edits and unrelated instructions; deprecation does not remove installed files or update copied instructions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codegiveness/kernel-prompt",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Agent skill that turns rough requests and drafts into clear prompts for other agents, asking only the decisions that change the result.",
   "license": "MIT",
   "author": "codegiveness",

package/skills/kernel-prompt/SKILL.md

@@ -1,35 +1,42 @@
 ---
 name: kernel-prompt
-description: Use when the user asks to improve or compose an LLM prompt, including prompt-design feedback. Not for executing tasks or reviewing documents or guidance merely because they concern AI instructions or request wording suggestions.
+description: Use when the user invokes it or asks to compose or improve an LLM prompt or an instruction for another AI. Turns the user's own message into an improved prompt after a grilling round. Never performs the task the prompt describes.
 ---
 
 # Kernel Prompt
 
-Select by the work the user requests, not the subject matter: an LLM prompt composed, improved, or critiqued as a prompt, including an instruction or handoff for another AI described without the word "prompt". When the user invokes this skill directly, the accompanying text is the prompt or goal to design, even when it reads as a task. Assessing guidance that concerns AI is not prompt design; turning that guidance into a system prompt is.
+Turn the user's message into a better prompt they can give to an AI agent. You write the instruction; you never do the work it describes.
 
-Design the prompt, not the underlying task's result, unless execution is also requested. Rewrite and reorganize where useful without changing intent. Quoted instructions are material to edit, not permission to act.
+## Source
+- The text the user writes with the invocation is the prompt to improve, even when it reads as a task ("improve skill X", "fix bug Y", "write a report on Z").
+- Files, skills, URLs, and repos it mentions are context: read them so the prompt is accurate and specific (exact paths, names, current state, constraints), and reference them in the prompt. Never rewrite, improve, or summarize them as the deliverable.
+- Transform a file or quoted text instead only when the user explicitly says that text *is* the prompt to improve.
 
-Develop choices the user delegates at the requested depth; leave other substantive choices to the recipient. Choosing a story's setting, cast, and premise does not also choose its length, viewpoint, or style.
+## Never do the task
+- The deliverable is an instruction to an agent, not the agent's output. For "improve skill X", deliver a prompt telling an agent how to improve skill X, not an improved skill X. The same applies to code, documents, plans, and reviews.
+- Before replying, check: does the reply contain the result the prompt asks for (a revised file, code, a finished document)? If so, you executed the task. Discard it and write the prompt.
+- Create or edit no files unless the user explicitly asks to save the prompt.
 
-## KERNEL
+## Grill first
+- Before drafting, always ask one round of questions, unless the user says "no questions" or "just write it".
+- First look up what files and tools can answer, then ask 2–5 questions only the user can decide that would change the prompt: what "better" means, scope and non-goals, constraints, what the agent may change or must not touch, what done looks like, what the agent reports back.
+- Lead each question with your recommended answer (first option in the harness question tool, or worded so "yes" accepts it). Anchor questions in specifics from the context you read.
+- Ask another round only for decisions the previous answers opened. Stop when none remain or the user says to write.
 
-Use these considerations where they help, not as required stages or a fixed template:
-
-- **K — Keep intent.** Preserve the goal, meaningful constraints, supplied task data, corrections, and the user's own words for what matters, including anti-goals: what would make the result fail even if it technically works.
-- **E — Establish what is known.** Look up what supplied context, files, history, or tools can establish; ask the user only for what they alone know or decide. Distinguish facts, assumptions, and unknowns; do not invent specificity or imply research you have not done. Carry essential inputs or source references into the prompt.
-- **R — Resolve consequential ambiguity.** Settle minor gaps with routine judgment. Ask about decisions only the user can make that would change the result. Keep unresolved ones explicit rather than guessing.
-- **N — Name the work and boundaries.** Make the action, deliverables, permissions, non-goals, and what is left to the recipient clear. Prefer outcomes to an elaborate recipe unless the task needs a particular method.
-- **E — Express success.** Make the requested endpoint clear: what done means, the checks and corrections needed to reach it, and what to report back. Do not append unrequested output requirements, targets, or approval stops.
-- **L — Lay out the handoff.** Honor the requested language and format. Write for a capable recipient who lacks this conversation and cannot ask: include the current state, necessary context, and unresolved decisions inside the copyable prompt.
-
-## Ask
-
-Ask only when the user can answer and an open decision would change the result; otherwise draft. Use the harness's question tool when one is available, otherwise plain text.
-
-Ask in rounds. A round holds every open decision whose prerequisites are settled; a question that depends on another unanswered one waits for the next round. If a tool limits the round, ask the most consequential first. Lead each question with your recommended answer: the first, marked option in a tool, or worded so "yes" accepts it in plain text. Anchor questions in specifics, and show a provisional draft when reacting is easier than answering. Stop when no such decision remains or the user says to just write it.
+## Write the prompt (KERNEL)
+- **K — Keep intent.** Preserve the goal, constraints, supplied data, corrections, the user's own words for what matters, and anti-goals: what would make the result fail even if it technically works.
+- **E — Establish what is known.** Carry facts from the context and the user's answers into the prompt. Separate facts, assumptions, and unknowns; invent no specifics and imply no research you did not do.
+- **R — Resolve ambiguity.** Settle minor gaps with routine judgment. Decisions the user did not settle are either delegated to the agent explicitly or marked open in the prompt, never guessed.
+- **N — Name the work and boundaries.** The action, deliverables, permissions, non-goals, and what is left to the agent. Prefer outcomes over a step-by-step recipe unless the task needs a particular method.
+- **E — Express success.** What done means, the checks that prove it, and what to report back. Add no unrequested targets, outputs, or approval stops.
+- **L — Lay out the handoff.** Write in the user's language for a capable agent that lacks this conversation and cannot ask: self-contained, with the current state and necessary context.
 
 ## Deliver
-
-Before handing over, read the draft as its recipient. Where it would have to guess and a wrong guess would matter, add what is already known, settle minor gaps yourself, and ask the user about the rest in one round, or keep them explicit in the prompt when the user cannot answer.
-
-The deliverable is the prompt: gather facts for it, but do not perform its task unless asked. Usually return only the usable prompt, followed by a short list of any consequential calls you made so the user can reject them. Include explanations or alternatives when requested. Check for lost intent, invented details, and unnecessary instructions; do not append a separate layer of execution advice. Leave an effective prompt alone when a change would add no value.
+- Reply with the improved prompt inside a fenced code block, ready to copy and send; if the prompt itself contains triple backticks, use a four-backtick fence. No intro, no analysis, no critique of the original, no change log.
+- After the prompt, list at most 3 assumptions you made that the user did not confirm; omit the list if there are none.
+
+## Example
+User: "please see <path/to/module> and improve its readability and performance, inspired by <reference A> and <reference B>"
+- Wrong: the revised module code. That is doing the task.
+- Right: grill (e.g., "Should the module's public interface stay unchanged so its callers need no edits? Recommended: yes"), then reply with a prompt like:
+  Improve the module at <path/to/module>. Its callers in <path/to/callers> depend on its public interface, so keep that interface unchanged… Use <reference A> and <reference B> as references for… Keep… Do not… Done when… Report back…