@codenhub/skills 0.0.2

package/src/test-driven-development/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: test-driven-development
+description: Use when an agent must do feature work, bug fixes, refactors, or behavior changes with fail-first TDD.
+metadata:
+  short-description: Enforce test-first development
+---
+
+# Test-Driven Development
+
+## Overview
+
+Use strict test-first development: write a failing test, make it pass with the
+smallest possible implementation, then refactor while keeping tests green.
+
+**Core principle:** If the test did not fail first for the expected reason, the
+test does not prove the behavior.
+
+## When To Use
+
+Apply this workflow for:
+
+- new features
+- bug fixes
+- behavior changes
+- refactors that can affect behavior
+
+Possible exceptions (only with explicit user confirmation in this conversation):
+
+- throwaway prototypes
+- generated code
+- strictly non-executable configuration edits (comments, whitespace, key
+  ordering, or descriptive metadata that no runtime/build/deploy tooling reads)
+
+Any configuration change that can affect runtime behavior (flags, permissions,
+routing, dependency resolution, build output, or environment loading) requires
+tests.
+
+Do not self-approve exception paths.
+
+When a change appears to qualify for the config-only exception and explicit
+confirmation is missing, ask once for explicit confirmation for this exact
+change. If confirmation is still missing, run full TDD.
+
+If there is any uncertainty about runtime impact, treat the change as behavior
+changing and run tests.
+
+Exception authorization must be explicit for this exact change in the
+conversation. Generic urgency language is not approval to skip TDD.
+
+Config-only exception checklist (all must be true):
+
+- change is limited to comments, formatting, key ordering, or descriptive text
+- no runtime/build/deploy-consumed key or value changed
+- no flags, permissions, routes, dependency pins, or environment keys changed
+- the diff itself clearly proves the above
+
+If any checklist item is false or uncertain, do not use the exception path.
+
+## The Iron Law
+
+```text
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+If production code is written before a failing test:
+
+1. Remove that code from the intended delivery change set.
+2. Write the failing test.
+3. Re-implement from the test.
+
+No exceptions:
+
+- Do not keep the old code as "reference".
+- Do not adapt pre-written code while pretending to do RED.
+- Do not use destructive version-control operations just to enforce this rule.
+- Delete means delete from the delivery path.
+
+## Red-Green-Refactor Loop
+
+### 1) RED - Write a Failing Test
+
+Write one small test for one behavior.
+
+Requirements:
+
+- one behavior per test
+- clear, behavior-focused test name
+- test real behavior, not mock wiring
+- avoid mocks unless isolation is truly required
+
+### 2) Verify RED - Watch It Fail
+
+**MANDATORY. Never skip this step.**
+
+Run the targeted test.
+
+Confirm:
+
+- test fails for the expected missing-behavior reason
+- failure is not caused by setup, typos, stale fixtures, or harness issues
+
+If the failure is a setup or harness error, fix setup and re-run until the
+failure reflects the expected missing behavior.
+
+If the test passes immediately, it is not proving new behavior. Fix the test or
+choose a different scenario.
+
+### 3) GREEN - Write Minimal Code
+
+Implement the smallest change that makes the failing test pass.
+
+Rules:
+
+- no speculative abstractions
+- no unrelated refactors
+- no extra features beyond the current test
+
+### 4) Verify GREEN - Watch It Pass
+
+**MANDATORY. Never skip this step.**
+
+Run:
+
+- the targeted test
+- nearby related tests
+- tests in changed modules or packages
+- tests that cover touched public interfaces and integration boundaries
+- repo-required smoke or pre-merge suites before finishing
+
+If baseline failures exist before coding (flaky or not), run the exact
+verification commands before coding and capture failing test IDs plus error
+signatures as baseline evidence.
+
+If uncertain, run the broader suite.
+
+Confirm:
+
+- new test passes
+- existing tests remain green, or only baseline failures with matching test IDs
+  and error signatures remain
+- no new warnings or runtime errors
+
+For baseline handling and flaky failure triage, use
+`verification-baselines.md`.
+
+### 5) REFACTOR - Improve Design Safely
+
+Refactor only while all tests are green.
+
+Allowed work:
+
+- remove duplication
+- improve naming
+- extract helpers
+- simplify design
+
+Do not change behavior during refactor. If behavior changes, start another RED
+cycle first.
+
+### 6) Repeat
+
+Move to the next behavior with a new failing test.
+
+## Test Quality Rules
+
+| Quality      | Good                                  | Bad                                      |
+| ------------ | ------------------------------------- | ---------------------------------------- |
+| Focus        | One behavior per test                 | Multiple behaviors in one test           |
+| Naming       | Describes expected behavior           | Vague names like `test1`                 |
+| Intent       | Validates externally visible behavior | Validates private implementation details |
+| Dependencies | Real collaborators when practical     | Heavy mocking without clear need         |
+
+## Common Rationalizations
+
+| Excuse                                   | Reality                                                                 |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| "It is too small to test."               | Small code breaks too. The test is cheap insurance.                     |
+| "I will add tests after coding."         | Passing tests written after code do not prove they can fail correctly.  |
+| "I already tested manually."             | Manual checks are not repeatable regression protection.                 |
+| "Deleting work is wasteful."             | Keeping unverified code creates future bugs and rework.                 |
+| "Tests after are equivalent."            | Tests-after ask what code does; tests-first define what code should do. |
+| "TDD is dogmatic. I am being pragmatic." | Pragmatic delivery includes repeatable tests that fail first.           |
+
+If these appear, stop and return to RED.
+
+## Red Flags
+
+Stop and restart the cycle when you see:
+
+- production code added before a failing test
+- tests written after implementation "for coverage"
+- tests that pass on first run when adding new behavior
+- inability to explain why the test failed
+- mock-heavy tests that do not validate real behavior
+- phrases like "just this once" or "I already manually tested it"
+- phrases that rationalize skipping fail-first behavior
+
+## Bug Fix Pattern
+
+For bugs, start by writing a failing regression test that reproduces the issue.
+
+If deterministic reproduction is not immediately possible, write the smallest
+deterministic characterization test (contract, property, or boundary case) that
+captures the observed failure before changing production code.
+
+If you cannot produce a failing automated test, stop and ask the user before
+shipping a bug fix.
+
+Then run the normal RED-GREEN-REFACTOR cycle. Never ship a bug fix without a
+reproduction or characterization test.
+
+## Testing Anti-Patterns
+
+When adding or changing tests, especially with mocks, review
+`testing-anti-patterns.md`.
+
+When baseline failures or flaky tests appear during verification, review
+`verification-baselines.md`.
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every behavior change has a test
+- [ ] Each new test was observed failing first
+- [ ] Failures happened for the expected reason
+- [ ] Implementation was minimal for each GREEN step
+- [ ] All relevant tests are passing
+- [ ] Refactors preserved behavior
+- [ ] Edge cases and error paths were covered
+
+If any box is unchecked, the workflow is incomplete.
+
+## Bottom Line
+
+```text
+Test first. Fail first. Minimal pass. Refactor safely.
+No failing test first means no TDD.
+```

package/src/test-driven-development/agents/openai.yaml

@@ -0,0 +1,11 @@
+interface:
+  display_name: "Test-Driven Development"
+  short_description: "Enforce strict test-first red-green-refactor"
+  default_prompt: >
+    Use $test-driven-development for strict test-first TDD: verify RED before
+    production code, remove any premature implementation from the delivery path,
+    allow config-only exceptions only with explicit user confirmation for that
+    exact change, verify GREEN with targeted plus relevant related suites,
+    handle flaky baselines by matching test IDs and error signatures, treat new
+    failures as regressions, refactor only while tests stay green, and apply
+    testing anti-pattern guardrails when mocks are involved.

package/src/test-driven-development/testing-anti-patterns.md

@@ -0,0 +1,162 @@
+# Testing Anti-Patterns
+
+Load this reference when writing tests, adding mocks, or considering test-only
+helpers in production code.
+
+## Overview
+
+Tests should verify behavior that matters to users and calling code. Mocks are
+tools for isolation, not the target of assertions.
+
+**Core principle:** Test real behavior, not mock behavior.
+
+## Iron Rules
+
+```text
+1. Never test mock existence instead of behavior.
+2. Never add test-only methods to production APIs.
+3. Never mock dependencies you do not understand.
+4. Do not use partial mocks for structured payloads unless fixture builders
+   provide all required fields by default.
+```
+
+## Anti-Pattern 1: Testing Mock Behavior
+
+Problem:
+
+- assertions target `*-mock` elements or fake methods
+- tests pass when mock is present, not when behavior is correct
+
+Fix:
+
+- assert externally visible behavior
+- use real collaborators when practical
+- if mocking is required, assert the unit output, not mock rendering details
+
+Gate check before adding assertions:
+
+```text
+Am I checking behavior of the system under test,
+or only confirming a mock exists?
+```
+
+If it is only mock existence, rewrite the test.
+
+## Anti-Pattern 2: Test-Only Methods in Production Code
+
+Problem:
+
+- production classes gain methods used only by tests
+- public APIs become polluted with lifecycle code that belongs in test tooling
+
+Fix:
+
+- move cleanup/setup behavior to test utilities
+- keep production APIs focused on production use cases
+
+Gate check before adding a method:
+
+```text
+Is this method required by production behavior,
+or only by test setup/cleanup?
+```
+
+If only tests need it, place it in test support code.
+
+## Anti-Pattern 3: Mocking Without Understanding Dependencies
+
+Problem:
+
+- high-level methods are mocked blindly
+- required side effects are accidentally removed
+- tests fail or pass for the wrong reasons
+
+Fix:
+
+1. Run the test against real code first.
+2. Identify which dependency is slow, flaky, or external.
+3. Mock only that boundary.
+4. Preserve side effects the test relies on.
+5. If dependency behavior is unclear, map required side effects before mocking.
+
+Red flags:
+
+- "I will mock this to be safe"
+- "I do not know what this dependency does"
+- mock setup is longer than the test behavior itself
+
+## Anti-Pattern 4: Incomplete Data Mocks
+
+Problem:
+
+- mocked payloads include only fields used by the current assertion
+- downstream code later depends on missing fields
+
+Fix:
+
+- include all required fields, metadata, and nested defaults from real schemas
+- prefer fixture builders/factories so tests override only fields under test
+- centralize canonical fixtures when the structure is reused
+
+Gate check:
+
+```text
+Does this mock represent the real schema,
+or only the subset I remembered?
+```
+
+## Anti-Pattern 5: Tests as a Final Step
+
+Problem:
+
+- implementation is marked "done"
+- tests are added afterward for confirmation
+
+Fix:
+
+- return to strict RED-GREEN-REFACTOR
+- write the failing test first for every behavior change
+
+If a test did not fail first, it did not drive the implementation.
+
+## When Mocks Become Too Complex
+
+Warning signs:
+
+- mock setup is longer than the test behavior
+- multiple layers of mocks or fakes are required just to run the test
+- the test fails when mock internals change but behavior stays the same
+- you cannot explain why each mock is needed
+
+Response:
+
+- prefer an integration test with real collaborators
+- mock only true external boundaries (network, process, filesystem, time)
+- keep assertions focused on observable behavior
+
+Gate check:
+
+```text
+Are mocks helping isolate the behavior,
+or replacing the behavior under test?
+```
+
+If mocks are replacing behavior, reduce mocking or move to an integration test.
+
+## Quick Diagnostic
+
+If any answer is "yes", revisit your test design:
+
+- Are assertions mostly about mocks?
+- Are you introducing test-only production methods?
+- Are you mocking dependencies without mapping side effects?
+- Are your mocked payloads incomplete vs real schemas?
+- Is mock setup larger than the behavior under test?
+- Were tests added only after implementation finished?
+
+## Bottom Line
+
+```text
+Use mocks to isolate boundaries, not to fake confidence.
+Behavior-first tests + strict TDD prevent most test anti-patterns.
+```

package/src/test-driven-development/verification-baselines.md

@@ -0,0 +1,42 @@
+# Verification Baselines and Flaky Triage
+
+Load this reference when baseline failures exist before coding or verification
+fails during VERIFY GREEN.
+
+## Core Rule
+
+Compare like-for-like test results using identical commands. Never re-label new
+or drifted failures as "known flaky."
+
+## 1) Capture Baseline Before Coding
+
+- run the exact verification commands you plan to use after changes
+- record failing test IDs and error signatures
+- keep enough evidence to compare later (command + failing IDs + signature text)
+
+## 2) Compare Post-Change Results
+
+Run the same commands and classify each failure:
+
+- **baseline match:** test ID and error signature match baseline evidence
+  exactly; document and continue
+- **new or drifted failure:** new failing test ID or changed signature; treat as
+  regression and fix before proceeding
+- **infrastructure failure:** runner outage, dependency timeout, or environment
+  instability; re-run once, then if still failing and clearly unrelated to
+  changed paths, document evidence and ask the user before completion
+
+## 3) Guardrails
+
+- use identical verification commands for baseline and post-change comparison
+- do not downgrade new failures to "already flaky"
+- if your change touched a flaky test, stabilize it now or quarantine it with a
+  documented follow-up issue before completion
+- if you must change verification commands, recapture baseline evidence first
+
+## Bottom Line
+
+```text
+Baseline evidence protects trust in GREEN. Same command, same comparison,
+no relabeling.
+```

package/src/writing-plans/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code.
+metadata:
+  short-description: Build complete implementation plans
+---
+
+# Writing Plans
+
+## Overview
+
+Write implementation-ready plans for a low-context engineer. Document the file map, task sequence, relevant docs, constraints, and verification needed to execute safely without guessing. Keep the plan concrete, but do not pre-write the full implementation unless the shape is fragile or non-obvious. Prefer plans that assume delegated execution via subagents when practical. DRY. YAGNI. TDD. Use frequent, atomic commits when the workflow calls for them.
+
+Assume they are a skilled developer, but know almost nothing about the toolset or problem domain.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** In planning context, include implementation workflow guidance when useful (often: new branch or isolated worktree, atomic commits, and a PR at the end). If repo conventions or explicit user instructions call for another approach, follow that instead.
+
+## 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 Plans To
+
+- Prefer `.docs/plans/NNNN--kebab-case-plan-name.md` (for example, `.docs/plans/0001--add-bulk-export-plan.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/plans/`, `.docs/plans/`, or another documented path.
+- User preferences for plan location override this default.
+
+## Status
+
+- Every plan must include `**Status:** Draft` near the top.
+- Valid statuses for spec and plan docs are `Draft`, `Approved`, `In Progress`, and `Implemented`.
+
+## Approval Gate
+
+- Prefer writing plans from a spec documented as `Approved`.
+- If no approved spec is available, write from explicit user-provided requirements when the user asks you to proceed.
+- Never mark a spec or plan `Approved` on your own. The user must update it, or you may update it only if they explicitly ask you to.
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it was not, suggest breaking this into separate plans, one per subsystem. Each plan should produce working, testable software on its own.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, do not unilaterally restructure, but if a file you are modifying has grown unwieldy, including a split in the plan is reasonable.
+
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
+
+## Bite-Sized Task Granularity
+
+**Each task should be a coherent, verifiable unit of work:**
+
+- Split into smaller steps only when sequencing, validation, or rollback boundaries are fragile.
+- Keep tightly coupled work together instead of exploding it into artificial micro-steps.
+- Include commit guidance only when the workflow or user explicitly calls for it, or when a milestone boundary matters.
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Status:** Draft
+
+> **For agentic workers:** Optional sub-skill: use `executing-plans` to implement this plan task-by-task when delegated execution is preferred.
+> Delegated and inline execution are both valid. When useful, default git flow is a new branch, atomic commits, and a PR at the end unless repo conventions or explicit user instructions say otherwise.
+
+**Goal:** [One sentence describing what this builds]
+**Architecture:** [2-3 sentences about approach]
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+Steps use checkbox (`- [ ]`) syntax for tracking.
+
+## Task Structure
+
+```markdown
+### Task N: [Component Name]
+
+**Goal:** [What this task completes]
+
+**Files:**
+
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py`
+- Test: `tests/exact/path/to/test.py`
+
+- [ ] **Implement the task**
+
+Implementation notes:
+
+- [Key behavior, interfaces, constraints, and patterns to follow]
+- [Reference an earlier helper or task when relevant, and restate what changes]
+
+- [ ] **Verify the task**
+
+Run: `pytest tests/path/test.py -v`
+Expected: PASS
+```
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs.
+
+These are **plan failures** and must never appear:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" without stating what behavior to verify and how to run it
+- "Similar to Task N" or "same as above" without pointing to the earlier task or helper and stating what changes
+- Steps that describe what to do without giving enough detail to execute safely
+- References to types, functions, or methods not defined anywhere in the plan or spec
+
+## Remember
+
+- Prefer exact file paths when known. If they are not yet certain, identify the owning area and the discovery needed before editing.
+- Make the plan concrete enough to execute without guesswork. Include exact code only when interface shape, migrations, commands, or test structure are non-obvious.
+- Exact commands with expected output when verification matters
+- DRY, YAGNI, TDD, and milestone-based commit guidance when the workflow calls for it
+
+## Self-Review
+
+After writing the complete plan, look at the spec with fresh eyes and check the plan against it.
+
+This is a checklist you run yourself, not a subagent dispatch.
+
+1. **Spec coverage:** Skim each section and requirement in the spec. Can you point to a task that implements it? List any gaps.
+2. **Placeholder scan:** Search your plan for red flags, any of the patterns from the "No Placeholders" section above. Fix them.
+3. **Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
+
+If you find issues, fix them inline. No need to re-review, just fix and move on. If you find a spec requirement with no task, add the task.
+
+## User Review Gate
+
+After saving the plan and completing self-review, ask the user to review it before execution.
+
+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 hand off to `executing-plans` once the plan document says `Approved`, unless the user explicitly instructs you to execute without documented approval.
+
+## Execution Handoff
+
+After the plan is documented as `Approved`, offer execution choice:
+
+\*\*"Plan complete and saved to `[PLAN_FILE_PATH]` with status `Approved`.
+
+Two execution options:
+
+1. Delegated execution
+   - Default when subagents are available and the tasks can be split cleanly
+   - Use `executing-plans` with fresh workers per task or independent workstream
+2. Inline execution
+   - Use when the work is tightly coupled, subagents are unavailable, or you explicitly prefer inline
+   - Follow the same plan and verification steps in this session
+
+Default implementation workflow is a new branch, atomic commits, and a PR at the end unless repo conventions or your instructions say otherwise.
+
+Which approach?"\*\*

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Writing Plans"
+  short_description: "Turn specs into detailed implementation plans"
+  default_prompt: "Use $writing-plans to turn an approved spec (preferred), or explicit user requirements when no approved spec exists or the user asks to proceed, into a direct, complete implementation plan with a status, bite-sized tasks, exact test steps, optional subagent-assisted execution guidance, and the usual new-branch/atomic-commit/PR workflow, then wait for documented approval before execution unless the user explicitly says otherwise."