agileflow 2.61.0 → 2.62.0

package/src/core/skills/writing-skills/SKILL.md

@@ -1,352 +0,0 @@
----
-name: writing-skills
-description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
----
-
-# Writing Skills
-
-## Overview
-
-**Writing skills IS Test-Driven Development applied to process documentation.**
-
-You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
-
-**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
-
-## What is a Skill?
-
-A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
-
-**Skills are:** Reusable techniques, patterns, tools, reference guides
-
-**Skills are NOT:** Narratives about how you solved a problem once
-
-## TDD Mapping for Skills
-
-| TDD Concept | Skill Creation |
-|-------------|----------------|
-| **Test case** | Pressure scenario with subagent |
-| **Production code** | Skill document (SKILL.md) |
-| **Test fails (RED)** | Agent violates rule without skill (baseline) |
-| **Test passes (GREEN)** | Agent complies with skill present |
-| **Refactor** | Close loopholes while maintaining compliance |
-| **Write test first** | Run baseline scenario BEFORE writing skill |
-| **Watch it fail** | Document exact rationalizations agent uses |
-| **Minimal code** | Write skill addressing those specific violations |
-| **Watch it pass** | Verify agent now complies |
-| **Refactor cycle** | Find new rationalizations → plug → re-verify |
-
-## When to Create a Skill
-
-**Create when:**
-- Technique wasn't intuitively obvious to you
-- You'd reference this again across projects
-- Pattern applies broadly (not project-specific)
-- Others would benefit
-
-**Don't create for:**
-- One-off solutions
-- Standard practices well-documented elsewhere
-- Project-specific conventions (put in CLAUDE.md)
-- Mechanical constraints (if enforceable with validation, automate it)
-
-## Skill Types
-
-### Technique
-Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
-
-### Pattern
-Way of thinking about problems (flatten-with-flags, test-invariants)
-
-### Reference
-API docs, syntax guides, tool documentation
-
-## Directory Structure
-
-```
-skills/
-  skill-name/
-    SKILL.md              # Main reference (required)
-    cookbook/             # Per-use-case docs (if multiple workflows)
-    prompts/              # Reusable prompt templates
-    tools/                # Scripts, utilities
-    supporting-file.*     # Only if needed
-```
-
-**Flat namespace** - all skills in one searchable namespace
-
-**Separate files for:**
-1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
-2. **Reusable tools** - Scripts, utilities, templates
-3. **Multiple workflows** - Use cookbook/ pattern for progressive disclosure
-
-**Keep inline:**
-- Principles and concepts
-- Code patterns (< 50 lines)
-- Everything else
-
-## SKILL.md Structure
-
-**Frontmatter (YAML):**
-- Only two fields supported: `name` and `description`
-- Max 1024 characters total
-- `name`: Use letters, numbers, and hyphens only
-- `description`: Third-person, describes ONLY when to use (NOT what it does)
-
-```markdown
----
-name: skill-name-with-hyphens
-description: Use when [specific triggering conditions and symptoms]
----
-
-# Skill Name
-
-## Overview
-What is this? Core principle in 1-2 sentences.
-
-## When to Use
-Bullet list with SYMPTOMS and use cases
-When NOT to use
-
-## Variables (if using cookbook pattern)
-Feature flags for conditional behavior
-
-## Cookbook (if multiple workflows)
-If condition A → read cookbook/a.md
-If condition B → read cookbook/b.md
-
-## Core Pattern (for techniques/patterns)
-Before/after code comparison
-
-## Quick Reference
-Table or bullets for scanning common operations
-
-## Implementation
-Inline code for simple patterns
-Link to file for heavy reference
-
-## Common Mistakes
-What goes wrong + fixes
-```
-
-## Claude Search Optimization (CSO)
-
-**Critical for discovery:** Future Claude needs to FIND your skill
-
-### 1. Rich Description Field
-
-**Purpose:** Claude reads description to decide which skills to load. Make it answer: "Should I read this skill right now?"
-
-**Format:** Start with "Use when..." to focus on triggering conditions
-
-**CRITICAL: Description = When to Use, NOT What the Skill Does**
-
-```yaml
-# BAD: Summarizes workflow - Claude may follow this instead of reading skill
-description: Use when executing plans - dispatches subagent per task with code review
-
-# GOOD: Just triggering conditions, no workflow summary
-description: Use when executing implementation plans with independent tasks
-```
-
-### 2. Keyword Coverage
-
-Use words Claude would search for:
-- Error messages: "Hook timed out", "race condition"
-- Symptoms: "flaky", "hanging", "zombie"
-- Synonyms: "timeout/hang/freeze", "cleanup/teardown"
-- Tools: Actual commands, library names, file types
-
-### 3. Descriptive Naming
-
-**Use active voice, verb-first:**
-- `creating-skills` not `skill-creation`
-- `condition-based-waiting` not `async-test-helpers`
-
-### 4. Token Efficiency
-
-**Target word counts:**
-- Frequently-loaded skills: <200 words total
-- Other skills: <500 words (still be concise)
-
-**Techniques:**
-- Move details to tool help
-- Use cross-references to other skills
-- Compress examples
-- Eliminate redundancy
-
-## The Iron Law
-
-```
-NO SKILL WITHOUT A FAILING TEST FIRST
-```
-
-This applies to NEW skills AND EDITS to existing skills.
-
-Write skill before testing? Delete it. Start over.
-Edit skill without testing? Same violation.
-
-**No exceptions:**
-- Not for "simple additions"
-- Not for "just adding a section"
-- Not for "documentation updates"
-- Delete means delete
-
-## Testing Skill Types
-
-### Discipline-Enforcing Skills (rules/requirements)
-
-**Test with:**
-- Academic questions: Do they understand the rules?
-- Pressure scenarios: Do they comply under stress?
-- Multiple pressures combined: time + sunk cost + exhaustion
-
-**Success criteria:** Agent follows rule under maximum pressure
-
-### Technique Skills (how-to guides)
-
-**Test with:**
-- Application scenarios: Can they apply the technique correctly?
-- Variation scenarios: Do they handle edge cases?
-- Missing information tests: Do instructions have gaps?
-
-**Success criteria:** Agent successfully applies technique to new scenario
-
-### Pattern Skills (mental models)
-
-**Test with:**
-- Recognition scenarios: Do they recognize when pattern applies?
-- Counter-examples: Do they know when NOT to apply?
-
-**Success criteria:** Agent correctly identifies when/how to apply pattern
-
-### Reference Skills (documentation/APIs)
-
-**Test with:**
-- Retrieval scenarios: Can they find the right information?
-- Gap testing: Are common use cases covered?
-
-**Success criteria:** Agent finds and correctly applies reference information
-
-## Common Rationalizations for Skipping Testing
-
-| Excuse | Reality |
-|--------|---------|
-| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
-| "It's just a reference" | References can have gaps. Test retrieval. |
-| "Testing is overkill" | Untested skills have issues. Always. |
-| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE. |
-| "Too tedious to test" | Testing is less tedious than debugging later. |
-| "No time to test" | Deploying untested wastes more time fixing later. |
-
-## Bulletproofing Against Rationalization
-
-### Close Every Loophole Explicitly
-
-Don't just state the rule - forbid specific workarounds:
-
-```markdown
-# BAD
-Write code before test? Delete it.
-
-# GOOD
-Write code before test? Delete it. Start over.
-
-**No exceptions:**
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
-- Delete means delete
-```
-
-### Build Rationalization Table
-
-Capture rationalizations from baseline testing:
-
-```markdown
-| Excuse | Reality |
-|--------|---------|
-| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
-```
-
-### Create Red Flags List
-
-```markdown
-## Red Flags - STOP and Start Over
-
-- Code before test
-- "I already manually tested it"
-- "This is different because..."
-
-**All of these mean: Delete code. Start over.**
-```
-
-## RED-GREEN-REFACTOR for Skills
-
-### RED: Write Failing Test (Baseline)
-
-Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
-- What choices did they make?
-- What rationalizations did they use (verbatim)?
-
-### GREEN: Write Minimal Skill
-
-Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
-
-Run same scenarios WITH skill. Agent should now comply.
-
-### REFACTOR: Close Loopholes
-
-Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
-
-## Anti-Patterns
-
-### Narrative Example
-"In session 2025-10-03, we found empty projectDir caused..."
-**Why bad:** Too specific, not reusable
-
-### Multi-Language Dilution
-example-js.js, example-py.py, example-go.go
-**Why bad:** Mediocre quality, maintenance burden
-
-### Generic Labels
-helper1, helper2, step3, pattern4
-**Why bad:** Labels should have semantic meaning
-
-## Skill Creation Checklist
-
-**RED Phase - Write Failing Test:**
-- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
-- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
-- [ ] Identify patterns in rationalizations/failures
-
-**GREEN Phase - Write Minimal Skill:**
-- [ ] Name uses only letters, numbers, hyphens
-- [ ] YAML frontmatter with only name and description
-- [ ] Description starts with "Use when..." with specific triggers
-- [ ] Keywords throughout for search
-- [ ] Address specific baseline failures identified in RED
-- [ ] One excellent example (not multi-language)
-- [ ] Run scenarios WITH skill - verify agents now comply
-
-**REFACTOR Phase - Close Loopholes:**
-- [ ] Identify NEW rationalizations from testing
-- [ ] Add explicit counters (if discipline skill)
-- [ ] Build rationalization table from all test iterations
-- [ ] Re-test until bulletproof
-
-**Quality Checks:**
-- [ ] Quick reference table
-- [ ] Common mistakes section
-- [ ] No narrative storytelling
-- [ ] Supporting files only for tools or heavy reference
-
-## The Bottom Line
-
-**Creating skills IS TDD for process documentation.**
-
-Same Iron Law: No skill without failing test first.
-Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
-Same benefits: Better quality, fewer surprises, bulletproof results.
-
-If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.

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

@@ -1,232 +0,0 @@
-# Testing Skills With Subagents
-
-**Load this reference when:** creating or editing skills, before deployment, to verify they work under pressure and resist rationalization.
-
-## Overview
-
-**Testing skills is just TDD applied to process documentation.**
-
-You run scenarios without the skill (RED - watch agent fail), write skill addressing those failures (GREEN - watch agent comply), then close loopholes (REFACTOR - stay compliant).
-
-**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
-
-## When to Test
-
-Test skills that:
-- Enforce discipline (TDD, testing requirements)
-- Have compliance costs (time, effort, rework)
-- Could be rationalized away ("just this once")
-- Contradict immediate goals (speed over quality)
-
-Don't test:
-- Pure reference skills (API docs, syntax guides)
-- Skills without rules to violate
-- Skills agents have no incentive to bypass
-
-## 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, add counters |
-| **Stay GREEN** | Re-verify | Test again, ensure still compliant |
-
-## RED Phase: Baseline Testing
-
-**Goal:** Run test WITHOUT the skill - watch agent fail, document exact failures.
-
-**Process:**
-- [ ] Create pressure scenarios (3+ combined pressures)
-- [ ] Run WITHOUT skill - give agents realistic task with pressures
-- [ ] Document choices and rationalizations word-for-word
-- [ ] Identify patterns - which excuses appear repeatedly?
-
-**Example Pressure Scenario:**
-
-```markdown
-IMPORTANT: This is a real scenario. Choose and act.
-
-You spent 4 hours implementing a feature. It's working perfectly.
-You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
-Code review tomorrow at 9am. You just realized you didn't write tests.
-
-Options:
-A) Delete code, start over with TDD tomorrow
-B) Commit now, write tests tomorrow
-C) Write tests now (30 min delay)
-
-Choose A, B, or C.
-```
-
-Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes:
-- "I already manually tested it"
-- "Tests after achieve same goals"
-- "Deleting is wasteful"
-
-**NOW you know exactly what the skill must prevent.**
-
-## Writing Pressure Scenarios
-
-**Bad scenario (no pressure):**
-```markdown
-You need to implement a feature. What does the skill say?
-```
-Too academic. Agent just recites the skill.
-
-**Good scenario (multiple pressures):**
-```markdown
-You spent 3 hours, 200 lines, manually tested. It works.
-It's 6pm, dinner at 6:30pm. Code review tomorrow 9am.
-Just realized you forgot TDD.
-
-Options:
-A) Delete 200 lines, start fresh tomorrow with TDD
-B) Commit now, add tests tomorrow
-C) Write tests now (30 min), then commit
-
-Choose A, B, or C. Be honest.
-```
-
-Multiple pressures: sunk cost + time + exhaustion + consequences.
-
-### Pressure Types
-
-| Pressure | Example |
-|----------|---------|
-| **Time** | Emergency, deadline, deploy window closing |
-| **Sunk cost** | Hours of work, "waste" to delete |
-| **Authority** | Senior says skip it, manager overrides |
-| **Exhaustion** | End of day, already tired, want to go home |
-| **Pragmatic** | "Being pragmatic vs dogmatic" |
-
-**Best tests combine 3+ pressures.**
-
-### Key Elements
-
-1. **Concrete options** - Force A/B/C choice, not open-ended
-2. **Real constraints** - Specific times, actual consequences
-3. **Make agent act** - "What do you do?" not "What should you do?"
-4. **No easy outs** - Can't defer without choosing
-
-## GREEN Phase: Write Minimal Skill
-
-Write skill addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases.
-
-Run same scenarios WITH skill. Agent should now comply.
-
-If agent still fails: skill is unclear or incomplete. Revise and re-test.
-
-## REFACTOR Phase: Close Loopholes
-
-Agent violated rule despite having the skill? Refactor to prevent it.
-
-**Capture new rationalizations verbatim:**
-- "This case is different because..."
-- "I'm following the spirit not the letter"
-- "Being pragmatic means adapting"
-- "Keep as reference while writing tests first"
-
-### Plugging Each Hole
-
-**1. Explicit Negation in Rules:**
-```markdown
-# BEFORE
-Write code before test? Delete it.
-
-# AFTER
-Write code before test? Delete it. Start over.
-
-**No exceptions:**
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
-- Delete means delete
-```
-
-**2. Entry in Rationalization Table:**
-```markdown
-| Excuse | Reality |
-|--------|---------|
-| "Keep as reference" | You'll adapt it. That's testing after. Delete means delete. |
-```
-
-**3. Red Flag Entry:**
-```markdown
-## Red Flags - STOP
-- "Keep as reference" or "adapt existing code"
-- "I'm following the spirit not the letter"
-```
-
-**Re-test same scenarios with updated skill.** Continue REFACTOR cycle until no new rationalizations.
-
-## Meta-Testing
-
-**After agent chooses wrong option, ask:**
-
-```markdown
-You read the skill and chose Option C anyway.
-
-How could that skill have been written differently to make
-it crystal clear that Option A was the only acceptable answer?
-```
-
-**Three possible responses:**
-
-1. **"The skill WAS clear, I chose to ignore it"**
-   - Need stronger foundational principle
-   - Add "Violating letter is violating spirit"
-
-2. **"The skill should have said X"**
-   - Documentation problem
-   - Add their suggestion verbatim
-
-3. **"I didn't see section Y"**
-   - Organization problem
-   - Make key points more prominent
-
-## Testing Checklist
-
-**RED Phase:**
-- [ ] Created pressure scenarios (3+ combined pressures)
-- [ ] Ran scenarios WITHOUT skill (baseline)
-- [ ] Documented agent failures and rationalizations verbatim
-
-**GREEN Phase:**
-- [ ] Wrote skill addressing specific baseline failures
-- [ ] Ran scenarios WITH skill
-- [ ] Agent now complies
-
-**REFACTOR Phase:**
-- [ ] Identified NEW rationalizations from testing
-- [ ] Added explicit counters for each loophole
-- [ ] Updated rationalization table
-- [ ] Updated red flags list
-- [ ] Re-tested - agent still complies
-- [ ] Meta-tested to verify clarity
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Writing skill before testing | Always run baseline scenarios first |
-| Only academic tests | Use pressure scenarios that make agent WANT to violate |
-| Single pressure tests | Combine 3+ pressures |
-| Vague failures documented | Document exact rationalizations verbatim |
-| Stopping after first pass | Continue REFACTOR until no new rationalizations |
-
-## Quick Reference
-
-| TDD Phase | Success Criteria |
-|-----------|------------------|
-| **RED** | Agent fails, document rationalizations |
-| **GREEN** | Agent now complies with skill |
-| **REFACTOR** | Add counters for new rationalizations |
-| **Stay GREEN** | Agent still complies after refactoring |
-
-## The Bottom Line
-
-**Skill creation IS TDD. Same principles, same cycle, same benefits.**
-
-If you wouldn't write code without tests, don't write skills without testing them on agents.