holycodex 0.15.1 → 0.15.2

package/dist/assets/plugin/skills/stop-slop/references/structures.md

@@ -0,0 +1,134 @@
+# Structures to Avoid
+
+## Binary Contrasts
+
+These create false drama. State the point directly.
+
+| Pattern                                                       | Problem                        |
+| ------------------------------------------------------------- | ------------------------------ |
+| "Not because X. Because Y." / "Not because X, but because Y." | Telegraphed reversal           |
+| "[X] isn't the problem. [Y] is."                              | Formulaic reframe              |
+| "The answer isn't X. It's Y."                                 | Predictable pivot              |
+| "It feels like X. It's actually Y."                           | Setup/reveal cliche            |
+| "The question isn't X. It's Y."                               | Rhetorical misdirection        |
+| "Not X. But Y." / "not X, it's Y" / "isn't X, it's Y"         | Mechanical contrast            |
+| "It's not this. It's that."                                   | Same formula, different words  |
+| "stops being X and starts being Y"                            | False transformation arc       |
+| "doesn't mean X, but actually Y"                              | Negation-then-assertion crutch |
+| "is about X but not Y"                                        | False distinction              |
+| "not just X but also Y"                                       | Additive hedge                 |
+
+**Instead:** State Y directly. "The problem is Y." "Y matters here." Drop the negation entirely.
+
+## Negative Listing
+
+Listing what something is _not_ before revealing what it _is_. A rhetorical striptease.
+
+| Pattern                               | Problem                           |
+| ------------------------------------- | --------------------------------- |
+| "Not a X... Not a Y... A Z."          | Dramatic buildup through negation |
+| "It wasn't X. It wasn't Y. It was Z." | Same structure, past tense        |
+
+**Instead:** State Z. The reader doesn't need the runway.
+
+## Dramatic Fragmentation
+
+Sentence fragments for emphasis read as manufactured profundity.
+
+| Pattern                                  | Problem                 |
+| ---------------------------------------- | ----------------------- |
+| "[Noun]. That's it. That's the [thing]." | Performative simplicity |
+| "X. And Y. And Z."                       | Staccato drama          |
+| "This unlocks something. [Word]."        | Artificial revelation   |
+
+**Instead:** Complete sentences. Trust content over presentation.
+
+## Rhetorical Setups
+
+These announce insight rather than deliver it.
+
+| Pattern               | Problem                |
+| --------------------- | ---------------------- |
+| "What if [reframe]?"  | Socratic posturing     |
+| "Here's what I mean:" | Redundant preview      |
+| "Think about it:"     | Condescending prompt   |
+| "And that's okay."    | Unnecessary permission |
+
+**Instead:** Make the point. Let readers draw conclusions.
+
+## Formulaic Constructions
+
+| Pattern                   | Problem                     |
+| ------------------------- | --------------------------- |
+| "By the time X, I was Y." | Narrative template          |
+| "X that isn't Y"          | Indirect. Say "X is broken" |
+
+## False Agency
+
+Giving inanimate things human verbs. Complaints don't "become" fixes. Bets don't "live or die." Decisions don't "emerge." A person does something to make those things happen. AI loves this because it avoids naming the actor.
+
+| Pattern                         | Problem                                                           |
+| ------------------------------- | ----------------------------------------------------------------- |
+| "a complaint becomes a fix"     | The complaint did nothing. Someone fixed it.                      |
+| "a bet lives or dies in days"   | Bets don't have lifespans. Someone kills the project or ships it. |
+| "the decision emerges"          | Decisions don't emerge. Someone decides.                          |
+| "the culture shifts"            | Cultures don't shift on their own. People change behavior.        |
+| "the conversation moves toward" | Conversations don't move. Someone steers.                         |
+| "the data tells us"             | Data sits there. Someone reads it and draws a conclusion.         |
+| "the market rewards"            | Markets don't reward. Buyers pay for things.                      |
+
+**Instead:** Name the human. "The team fixed it that week" beats "the complaint becomes a fix." If no specific person fits, use "you" to put the reader in the seat.
+
+## Narrator-from-a-Distance
+
+Floating above the scene instead of putting the reader in it.
+
+| Pattern                   | Problem                 |
+| ------------------------- | ----------------------- |
+| "Nobody designed this."   | Disembodied observation |
+| "This happens because..." | Lecturer voice          |
+| "This is why..."          | Same                    |
+| "People tend to..."       | Armchair sociologist    |
+
+**Instead:** Put the reader in the room. "You don't sit down one day and decide to..." beats "Nobody designed this."
+
+## Passive Voice
+
+Every sentence needs a subject doing something. Passive voice hides the actor and drains energy.
+
+| Pattern                    | Fix                  |
+| -------------------------- | -------------------- |
+| "X was created"            | Name who created it  |
+| "It is believed that"      | Name who believes it |
+| "Mistakes were made"       | Name who made them   |
+| "The decision was reached" | Name who decided     |
+
+**Instead:** Find the actor. Put them at the front of the sentence.
+
+## Sentence Starters to Avoid
+
+| Pattern                                                         | Fix                                             |
+| --------------------------------------------------------------- | ----------------------------------------------- |
+| Sentences starting with What, When, Where, Which, Who, Why, How | Restructure. Lead with the subject or the verb. |
+| Paragraphs starting with "So"                                   | Start with content                              |
+| Sentences starting with "Look,"                                 | Remove                                          |
+
+Wh- openers become a crutch. "What makes this hard is..." becomes "The constraint is..." or better, name the specific constraint.
+
+## Rhythm Patterns
+
+| Pattern                        | Fix                                                 |
+| ------------------------------ | --------------------------------------------------- |
+| Three-item lists               | Use two items or one                                |
+| Questions answered immediately | Let questions breathe or cut them                   |
+| Every paragraph ends punchily  | Vary endings                                        |
+| Em-dashes                      | Remove. Use commas or periods. No em dashes at all. |
+| Staccato fragmentation         | Don't stack short punchy sentences                  |
+| "Not always. Not perfectly."   | Hedging disguised as reassurance                    |
+
+## Word Patterns
+
+| Pattern                                                                                               | Problem                                                    |
+| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Lazy extremes (every, always, never, everyone, everybody, nobody)                                     | False authority. Use specifics instead of sweeping claims. |
+| All adverbs (-ly words, "really," "just," "literally," "genuinely," "honestly," "simply," "actually") | Empty emphasis. See phrases.md for full list.              |

package/dist/assets/plugin/skills/testing-quality.md

@@ -0,0 +1,15 @@
+# Testing quality
+
+Protect stable behavior, contracts, invariants, safety properties, compatibility guarantees, and meaningful failure modes. Prefer observable behavior and typed or public boundaries while leaving implementation choices free.
+
+Before adding a regression or smoke test, identify:
+
+1. the stable behavior it protects;
+2. the real regression it catches;
+3. why a less brittle boundary cannot protect it.
+
+Remove or rewrite tests that freeze incidental counts, inventories, internal paths, prompt or skill sizes, exact non-contract wording, irrelevant call order, deleted names, broad repository shape, or one implementation strategy. Avoid large internal snapshots and static source inspection when a behavior check exists.
+
+A smoke test consumes the shipped artifact through one supported outer boundary with minimal realistic setup. It answers whether the artifact can start and perform its smallest supported job. It does not duplicate the suite, reproduce packaging logic, crawl file inventories, or accumulate historical implementation assertions.
+
+Use proportional proof. A test that constrains more design than meaningful regression risk should not exist.

package/dist/assets/plugin/skills/workflows/SKILL.md

@@ -5,6 +5,6 @@ description: Use for substantive non-Go orchestration involving discovery, imple
 
 Use this skill for substantive orchestration, because the active plan must control specialist routes, budgets, concurrency, retained context, and terminal proof.
 
-Owner: Root control plane; Luna executes literal bounded assignments. Boundary: apply the active plan and workflow runtime, keep capability and approval gates intact, and route contradictions or material choices back to Root. Go remains direct.
+Owner: Root control plane; specialists execute literal bounded assignments. Boundary: apply the active plan and workflow runtime, keep capability and approval gates intact, and route contradictions or material choices back to Root. Direct mode remains with Root.
 
 Completion: each assigned step has a structured outcome, accepted evidence, bounded changes, required checks, and a terminal branch; no specialist delegates or silently broadens authority.

package/dist/assets/plugin/skills/writing-for-agents/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/assets/plugin/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,19 @@
+# Skill mechanics
+
+This is the skill-specific branch of [writing-for-agents](SKILL.md): frontmatter, invocation choice, and router skills.
+
+## Invocation
+
+A **model-invoked** skill keeps a trigger-first `description` so an agent can select it and another skill can reach its shared reference. The always-loaded pointer spends context on every turn, so use one compact trigger per real branch and remove routing prose from the body.
+
+A **user-invoked** skill sets `disable-model-invocation: true`. Its description becomes a human-facing one-line summary with trigger lists removed. Use this when only a person should select the skill.
+
+Shared reference required by user-invoked skills belongs in a plain disclosed file that each can point to.
+
+## Splitting by invocation
+
+Split a model-invoked skill only when a distinct leading word should trigger it independently or another skill must reach it. The independent route must justify its permanent context pointer.
+
+## Router skills
+
+When many user-invoked skills exceed human cognitive load, add one user-invoked router that names them and their branches. A router can guide the person; it cannot autonomously invoke skills whose model invocation is disabled.

package/dist/assets/plugin/skills/writing-for-agents/SKILL.md

@@ -1,26 +1,37 @@
 ---
 name: writing-for-agents
-description: Use when authoring or reviewing instructions consumed by agents, including prompts, skills, profiles, delegations, handoffs, and workflows.
+description: Use when authoring or reviewing prompts, skills, profiles, delegations, handoffs, workflows, or agent-facing repository instructions; make them independently actionable with low context load.
 ---
 
 # Writing for agents
 
-Treat instructions as a small interface, not a role description. Start with one contract:
+Treat each instruction as an interface with one contract:
 
-Owner: the authoring role within its approved scope.
-Boundary: keep policy in one source of truth and return material decisions to the owning agent.
-Completion: the receiving agent can act, prove, and stop from this instruction alone.
+- **Owner:** the role permitted to act or decide.
+- **Boundary:** the exact scope, authority, constraints, and escalation point.
+- **Completion:** the observable outcome and proof that permit the agent to stop.
 
-- **Objective and outcome:** what must be true when the assignment ends.
-- **Scope and authority:** exact files or decisions in scope, and who owns everything else.
-- **Constraints:** retained policy, tools, security, and non-goals.
-- **Evidence and completion:** the output shape, proof required, and the condition that permits stopping.
-- **Escalation:** the precise missing fact or conflict that returns to the owning agent.
+Write an objective, scope, retained constraints, evidence, exclusions, and the exact missing fact or material choice that returns to the owner. The receiver must be able to act, prove, and stop without reconstructing intent.
 
-Write each behavior beside its reason when the reason changes a decision. Prefer direct positive steering, one source of truth, and pointers to branch-only detail. Remove duplicate policy, stale context, no-op prose, and instructions the environment already enforces. Keep a resumed assignment to its changed constraints and delta; do not replay the whole contract.
+## Information design
 
-For Sol, state invariants and decision boundaries. For Luna, name the exact files or actions, evidence fields, authority limit, and stop condition; do not leave operational choices implicit. Keep dynamic assignments short enough to preserve working context.
+A **context pointer** names out-of-context material and front-loads the branches that load it. Keep one trigger per genuine branch; synonyms spend permanent context without improving routing.
 
-Use the narrowest route: `programming` for implementation, `code-review` once after implementation, `workflows` for substantive orchestration, `context7-cli` for current external documentation, and `handoff` when context must pause or transfer. Read the selected route's skill only after choosing it.
+Budget two loads:
 
-Completion means the instruction is independently actionable, triggerable at the right branch, explicit about exclusions and escalation, and testable through the receiver's output. Adapted from the supplied Matt Pocock skills-writing concepts.
+- **Context load:** always-loaded descriptions and repository rules.
+- **Cognitive load:** material a person must remember and select.
+
+Place information by immediacy: in-file steps, in-file reference, then disclosed reference. Inline what every invocation needs. Put branch-specific mechanics behind a clear pointer. Co-locate each concept with its rules and caveats; split real invocation or sequence branches when one file sprawls or later steps cause premature completion.
+
+Each step needs a clear, demanding completion criterion. Sharpen a vague bound before splitting the sequence. Use leading words with useful pretrained meaning to compress repeated concepts. Prefer positive steering; keep prohibitions for hard guardrails and pair them with the target behavior.
+
+## Pruning
+
+Keep each meaning in one source of truth. Treat code, configuration, directory layout, and `--help` as authoritative environment lookups; document only reasons, gotchas, or contracts the environment cannot reveal. Delete stale caches, irrelevant branches, sediment, and instructions that do not change model behavior.
+
+Use architectural role names: Root owns material decisions, Workers implement bounded seams, Reviewers repair their assigned findings to fixed point, and other specialists follow their literal authority. Continuations carry changed constraints, evidence, decisions, and semantic delta instead of replaying accepted context.
+
+When the document is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md) for invocation and frontmatter mechanics.
+
+Completion means the instruction routes at the right branch, names authority and exclusions, prevents premature completion, supplies checkable proof, and contains no duplicated or no-op policy.