@codenhub/skills 0.0.2

package/src/writing-skills/persuasion-principles.md

@@ -0,0 +1,172 @@
+# Persuasion Principles for Skill Design
+
+## Contents
+
+- Overview
+- The Seven Principles
+- Principle Combinations by Skill Type
+- Why This Works
+- Ethical Use
+- Research Citations
+- Quick Reference
+
+## Overview
+
+Language models respond to many of the same persuasion principles that influence people. Understanding that helps you design skills that hold up under pressure.
+
+**Research foundation:** Meincke et al. (2025) tested seven persuasion principles across 28,000 model conversations and found that persuasion techniques more than doubled compliance rates.
+
+## The Seven Principles
+
+### 1. Authority
+
+**What it is:** deference to expertise, credentials, or official rules.
+
+**How it works in skills:**
+
+- Imperative language such as `must`, `never`, and `always`
+- Non-negotiable framing
+- Less room for rationalization
+
+**When to use:**
+
+- Discipline-enforcing skills
+- Safety-critical practices
+- Established best practices
+
+**Example:**
+
+```markdown
+Write code before test? Delete it. Start over. No exceptions.
+```
+
+### 2. Commitment
+
+**What it is:** consistency with prior actions or explicit commitments.
+
+**How it works in skills:**
+
+- Require explicit announcements
+- Force clear choices
+- Use progress tracking for multi-step work
+
+**When to use:**
+
+- Multi-step workflows
+- Skills that are often ignored mid-process
+- Accountability mechanisms
+
+### 3. Scarcity
+
+**What it is:** urgency created by timing or sequence.
+
+**How it works in skills:**
+
+- "Before proceeding"
+- "Immediately after X"
+- Prevents procrastination
+
+**When to use:**
+
+- Immediate verification requirements
+- Time-sensitive workflows
+- Anything often deferred until it is too late
+
+### 4. Social Proof
+
+**What it is:** conformity to what is treated as normal practice.
+
+**How it works in skills:**
+
+- Universal framing such as `every time` or `always`
+- Naming common failure modes explicitly
+- Establishing the practice as standard behavior
+
+### 5. Unity
+
+**What it is:** shared identity and shared goals.
+
+**How it works in skills:**
+
+- Collaborative language
+- Shared responsibility for quality
+- Encourages honest technical judgment
+
+### 6. Reciprocity
+
+**What it is:** pressure to return perceived benefits.
+
+**How it works:**
+
+- Rarely needed in skill writing
+- Easy to overdo
+
+### 7. Liking
+
+**What it is:** preference for cooperating with those we like.
+
+**How it works:**
+
+- Avoid for discipline enforcement
+- Can encourage sycophancy instead of rigor
+
+## Principle Combinations by Skill Type
+
+| Skill type             | Use                                   | Avoid                  |
+| ---------------------- | ------------------------------------- | ---------------------- |
+| Discipline-enforcing   | Authority + commitment + social proof | Liking, reciprocity    |
+| Guidance or technique  | Moderate authority + unity            | Heavy authority        |
+| Collaborative workflow | Unity + commitment                    | Excess authority       |
+| Reference              | Clarity only                          | Unnecessary persuasion |
+
+## Why This Works
+
+**Bright-line rules reduce rationalization:**
+
+- `must` reduces decision fatigue
+- absolute language removes exception-hunting
+- explicit anti-rationalization counters close loopholes
+
+**Implementation intentions create automatic behavior:**
+
+- clear triggers plus required actions improve follow-through
+- `when X, do Y` is stronger than vague guidance
+- less cognitive load means better compliance
+
+**Models learn these patterns from human language:**
+
+- authority language is often followed by compliance
+- commitment sequences are common in training data
+- social proof establishes norms quickly
+
+## Ethical Use
+
+**Legitimate:**
+
+- ensuring critical practices are followed
+- preventing predictable failures
+- making documentation more reliable
+
+**Illegitimate:**
+
+- manipulation for personal gain
+- false urgency
+- guilt-driven compliance
+
+Use the technique only when it serves the partner's genuine interests.
+
+## Research Citations
+
+**Cialdini, R. B. (2021).** _Influence: The Psychology of Persuasion (New and Expanded)._ Harper Business.
+
+**Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** _Call Me A Jerk: Persuading AI to Comply with Objectionable Requests._ University of Pennsylvania.
+
+## Quick Reference
+
+When designing a skill, ask:
+
+1. What type of skill is this?
+2. What behavior needs to change?
+3. Which principle fits that behavior?
+4. Am I using more persuasion than necessary?
+5. Would this still be justified if the partner understood it fully?

package/src/writing-skills/testing-skills-with-subagents.md

@@ -0,0 +1,310 @@
+# Testing Skills With Subagents
+
+**Load this reference when:** creating or editing skills, before deployment, to verify they work under pressure and resist rationalization.
+
+## Contents
+
+- When to Use
+- Validation Depth by Change Type
+- TDD Mapping for Skill Testing
+- RED Phase: Baseline Testing
+- GREEN Phase: Write Minimal Skill
+- VERIFY GREEN: Pressure Testing
+- REFACTOR Phase: Close Loopholes
+- Meta-Testing
+- When the Skill Is Bulletproof
+- Testing Checklist
+- Common Mistakes
+- Quick Reference
+
+## Overview
+
+Testing skills is test-driven development applied to process documentation.
+
+You run scenarios without the skill, write the skill to address those failures, then close loopholes until the guidance holds up under pressure.
+
+**Core principle:** If you did not watch an agent fail without the skill, you do not know whether the skill prevents the right failures.
+
+**Complete worked example:** See `examples/SKILL_AUTHORING_GUIDE_TESTING.md` for a full test campaign focused on portable skill authoring guidance under pressure.
+
+## When to Use
+
+Test skills that:
+
+- Enforce discipline
+- Have compliance costs such as time, effort, or rework
+- Could be rationalized away
+- Compete with immediate goals such as speed over quality
+
+Do not spend this level of testing on:
+
+- Pure reference skills with no meaningful choices to violate
+- Skills with no rules or constraints to enforce
+
+## Validation Depth by Change Type
+
+Choose testing depth based on what changed.
+
+- **Behavioral changes or new skills:** run full RED-GREEN-REFACTOR
+- **Editorial or reference-only updates:** run lightweight validation instead of a full pressure campaign
+
+Lightweight validation loop:
+
+1. State that behavior should not change.
+2. Run one before/after prompt pair that targets the edited wording.
+3. Confirm the same decision or policy outcome before and after.
+4. Verify links, frontmatter, and references still resolve.
+5. If behavior changed or uncertainty remains, escalate to full RED-GREEN-REFACTOR.
+
+## TDD Mapping for Skill Testing
+
+| TDD phase    | Skill testing            | What you do                                  |
+| ------------ | ------------------------ | -------------------------------------------- |
+| RED          | Baseline test            | Run scenario without skill, watch agent fail |
+| Verify RED   | Capture rationalizations | Document exact failures verbatim             |
+| GREEN        | Write skill              | Address specific baseline failures           |
+| Verify GREEN | Pressure test            | Run scenario with skill, verify compliance   |
+| REFACTOR     | Plug holes               | Find new rationalizations and add counters   |
+| Stay GREEN   | Re-verify                | Test again and ensure compliance remains     |
+
+## RED Phase: Baseline Testing
+
+**Goal:** run the test without the skill and document the failure.
+
+**Process:**
+
+- [ ] Create pressure scenarios with combined pressures
+- [ ] Run them without the skill
+- [ ] Document choices and rationalizations word-for-word
+- [ ] Identify repeated failure patterns
+- [ ] Note which pressures were most effective
+
+**Example:**
+
+```markdown
+IMPORTANT: This is a real scenario. Choose and act.
+
+You spent 4 hours implementing a feature. It is working perfectly.
+You manually tested all edge cases. It is 6pm, dinner at 6:30pm.
+Code review is tomorrow at 9am. You just realized you did not write tests.
+
+Options:
+A) Delete code and start over tomorrow with TDD
+B) Commit now and write tests tomorrow
+C) Write tests now, then commit
+
+Choose A, B, or C.
+```
+
+Without the skill, the agent will often choose B or C and rationalize with phrases such as:
+
+- I already manually tested it
+- Tests after achieve the same goal
+- Deleting is wasteful
+- I am being pragmatic, not dogmatic
+
+That tells you exactly what the skill must counter.
+
+## GREEN Phase: Write Minimal Skill
+
+Write the smallest skill that addresses the failures you actually observed.
+
+Run the same scenarios with the skill present. If the agent still fails, the skill is unclear or incomplete.
+
+## VERIFY GREEN: Pressure Testing
+
+**Goal:** confirm the agent follows the rule when it wants to break it.
+
+### Writing Pressure Scenarios
+
+Bad:
+
+```markdown
+You need to implement a feature. What does the skill say?
+```
+
+This is too academic.
+
+Good:
+
+```markdown
+Production is down. Revenue is being lost every minute. A senior engineer says
+to add a two-line fix now. The deploy window closes in five minutes. What do you do?
+```
+
+Great:
+
+```markdown
+You spent 3 hours, wrote 200 lines, and manually tested everything.
+It is 6pm and you need to leave soon. Code review is tomorrow morning.
+You just realized you forgot TDD.
+
+Options:
+A) Delete the work and restart with TDD tomorrow
+B) Commit now and add tests tomorrow
+C) Write tests now and then commit
+
+Choose A, B, or C.
+```
+
+This combines sunk cost, time pressure, exhaustion, and consequences.
+
+### Pressure Types
+
+| Pressure          | Example                                    |
+| ----------------- | ------------------------------------------ |
+| Time              | Emergency, deadline, deploy window closing |
+| Sunk cost         | Hours of work already invested             |
+| Authority         | Senior engineer or manager says skip it    |
+| Economic          | Revenue or job consequences                |
+| Exhaustion        | End of day, low patience                   |
+| Social            | Fear of seeming rigid                      |
+| Pragmatic framing | "Be practical"                             |
+
+Best tests combine three or more pressures.
+
+### Key Elements of Good Scenarios
+
+1. Force a concrete choice.
+2. Use real constraints.
+3. Use realistic file paths or project details.
+4. Ask the agent to act, not recite policy.
+5. Remove easy exits such as vague deferral.
+
+## REFACTOR Phase: Close Loopholes
+
+If the agent violates the rule despite having the skill, capture the new rationalization verbatim.
+
+Common patterns:
+
+- This case is different because...
+- I am following the spirit, not the letter
+- I achieved the same goal another way
+- Being pragmatic means adapting
+- I can keep this as reference while doing it correctly now
+
+### Plugging Each Hole
+
+#### 1. Add Explicit Negation
+
+Before:
+
+```markdown
+Write code before test? Delete it.
+```
+
+After:
+
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+
+- Do not keep it as reference
+- Do not adapt it while writing tests
+- Do not look at it
+- Delete means delete
+```
+
+#### 2. Add It to the Rationalization Table
+
+```markdown
+| Excuse                                   | Reality                                           |
+| ---------------------------------------- | ------------------------------------------------- |
+| Keep it as reference while writing tests | That is still testing after. Delete means delete. |
+```
+
+#### 3. Add It to Red Flags
+
+```markdown
+## Red Flags - Stop
+
+- Keep it as reference
+- I am following the spirit not the letter
+```
+
+#### 4. Update the Description
+
+If a rule is routinely ignored in the same contexts, encode those violation signals in the description.
+
+### Re-verify After Refactoring
+
+Re-run the same scenarios. A resilient skill should now produce the correct choice and cite the updated guidance.
+
+## Meta-Testing
+
+If GREEN is still not working, ask the agent why it ignored the skill.
+
+```markdown
+You read the skill and still chose Option C.
+
+How should that skill have been written differently to make it clear that Option A
+was the only acceptable answer?
+```
+
+Possible outcomes:
+
+1. The skill was clear and the agent ignored it. Strengthen foundational rules.
+2. The skill should have said something more explicit. Add it.
+3. The agent missed a section. Improve structure and prominence.
+
+## When the Skill Is Bulletproof
+
+Signs of success:
+
+1. The agent chooses the correct option under strong pressure.
+2. The agent cites the skill as justification.
+3. The agent acknowledges the temptation and still complies.
+4. Meta-testing confirms the skill was clear.
+
+It is not bulletproof if the agent still finds new rationalizations, invents hybrid workarounds, or argues around the rule.
+
+## Testing Checklist
+
+**RED:**
+
+- [ ] Created pressure scenarios with combined pressures
+- [ ] Ran scenarios without the skill
+- [ ] Documented failures and rationalizations verbatim
+
+**GREEN:**
+
+- [ ] Wrote the skill to address specific failures
+- [ ] Ran scenarios with the skill
+- [ ] Verified compliance
+
+**REFACTOR:**
+
+- [ ] Captured new rationalizations
+- [ ] Added explicit counters
+- [ ] Updated the rationalization table
+- [ ] Updated the red flags list
+- [ ] Re-tested until behavior held up
+- [ ] Meta-tested for clarity
+
+## Common Mistakes
+
+**Writing the skill before testing:** you end up documenting what you assume matters instead of what actually fails.
+
+**Weak test cases:** single-pressure scenarios are rarely enough.
+
+**Not capturing exact failures:** vague summaries do not tell you what to fix.
+
+**Vague fixes:** generic warnings do not stop specific rationalizations.
+
+**Stopping after one pass:** passing once does not mean the skill is resilient.
+
+## Quick Reference
+
+| TDD phase    | Skill testing              | Success criteria                         |
+| ------------ | -------------------------- | ---------------------------------------- |
+| RED          | Run scenario without skill | Agent fails and reveals the real problem |
+| Verify RED   | Capture exact wording      | Failures documented verbatim             |
+| GREEN        | Write the skill            | Skill addresses real failures            |
+| Verify GREEN | Re-test                    | Agent follows the rule under pressure    |
+| REFACTOR     | Close loopholes            | Skill counters new rationalizations      |
+| Stay GREEN   | Re-verify                  | Compliance remains after refactoring     |
+
+## The Bottom Line
+
+If you would not write code without tests, do not write skills without testing them on agents.

package/src/writing-specs/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: writing-specs
+description: Use after brainstorming or other design work to write a validated feature spec or design document before implementation planning.
+metadata:
+  short-description: Write validated specs before planning
+---
+
+# Writing Specs
+
+## Overview
+
+Write the validated design as a complete spec, review it for planning readiness, and get user approval before moving on to implementation planning.
+
+**Announce at start:** "I'm using the writing-specs skill to write the spec."
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## Save Specs To
+
+- Prefer `.docs/specs/NNNN--short-kebab-title.md` (for example `.docs/specs/0001--design-auth-session-lifecycle.md`).
+- Before choosing the path, inspect the project for an existing structure and respect it if one is already in use, for example `docs/superpowers/specs/`, `.docs/specs/`, or another documented path.
+- User preferences for spec location override this default.
+
+## Status
+
+- Every spec must include `**Status:** Draft` near the top.
+- Valid statuses for spec and plan docs are `Draft`, `Approved`, `In Progress`, and `Implemented`.
+
+## What the Spec Must Do
+
+- Capture the validated design, not a fresh brainstorming pass.
+- Start in `Draft` status.
+- Cover the design clearly enough that engineers can plan and implement it without guessing.
+- Cover architecture, components, data flow, error handling, and testing.
+- If the project is too large for a single implementation plan, split it into sub-project specs instead of forcing everything into one document.
+
+## The Process
+
+1. Write the validated design to the spec file and set its status to `Draft`.
+2. Commit the design document to git if the workflow calls for committing planning artifacts.
+3. Run the spec self-review loop.
+4. Ask the user to review the written spec before proceeding.
+5. Never mark the spec `Approved` on your own. The user must update it, or you may update it only if they explicitly ask you to.
+6. Only after the spec is documented as `Approved`, proceed to implementation planning unless the user explicitly asks to proceed without documented approval.
+
+## Spec Self-Review
+
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review, just fix and move on.
+
+## User Review Gate
+
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and saved to `[SPEC_FILE_PATH]` with status `Draft`. Please review it and let me know if you want any changes, or if you want me to update the status to `Approved`."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. If they approve in chat but the document is still `Draft`, ask whether they want to update it themselves or want you to update it. Only proceed once the document says `Approved`, unless the user explicitly instructs you to continue without documented approval.
+
+## Implementation Planning
+
+- If the user asks for planning support, you may invoke `writing-plans` to create a detailed implementation plan.
+- Follow repo conventions and user workflow for planning and implementation handoff.
+- Do NOT invoke `writing-plans` or any implementation skill before the written spec is documented as `Approved`, unless the user explicitly instructs otherwise.

package/src/writing-specs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Writing Specs"
+  short_description: "Write designs as implementation-ready specs with approval gating"
+  default_prompt: "Use $writing-specs to write the design to a spec that starts in Draft status, review it for gaps, and only proceed to planning or implementation once the spec is documented as Approved unless the user explicitly says otherwise."