codexkit 1.0.0

package/.codex/skills/writing-plans/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: writing-plans
+description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
+---
+
+# Writing Plans
+
+> **Replaces** vague implementation plans that assume the engineer knows the codebase — produces zero-ambiguity plans with exact file paths and complete code examples
+## When to Use
+
+- Design/PRD is complete and you need a detailed, step-by-step implementation plan
+- You need a plan for engineers with minimal codebase context and explicit file paths
+
+## When NOT to Use
+
+- Requirements are still being defined (use brainstorming or prd)
+- You already have a vetted plan and only need execution (use executing-plans)
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use skill({ name: "executing-plans" }) to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+### Goal-Backward Section (REQUIRED)
+
+Document the reasoning that produced this plan using goal-backward methodology:
+
+```markdown
+## Must-Haves
+
+**Goal:** [Outcome-shaped goal from PRD]
+
+### Observable Truths
+
+(What must be TRUE for the goal to be achieved?)
+
+1. [Truth 1: User can...]
+2. [Truth 2: User can...]
+3. [Truth 3: User can...]
+
+### Required Artifacts
+
+(What must EXIST for truths to be true?)
+| Artifact | Provides | Path |
+|----------|----------|------|
+| [File/component] | [What it does] | `src/path/to/file.ts` |
+
+### Key Links
+
+(Where is this most likely to break?)
+| From | To | Via | Risk |
+|------|-----|-----|------|
+| [Component] | [API] | `fetch` | [Why it might fail] |
+```
+
+### Dependency Graph
+
+```markdown
+### Task Dependencies
+```
+
+Task A (User model): needs nothing, creates src/models/user.ts
+Task B (Product model): needs nothing, creates src/models/product.ts
+Task C (User API): needs Task A, creates src/api/users.ts
+
+Wave 1: A, B (parallel)
+Wave 2: C (after Wave 1)
+
+````
+
+## Tiered Task Hierarchy
+
+For multi-agent execution at scale (10+ agents), use explicit tier declarations. This prevents flat decomposition that fails when many agents work in parallel.
+
+### Tier Definitions
+
+| Tier | Role | Description | Example |
+|------|------|-------------|---------|
+| **planner** | Lead orchestrator | Analyzes scope, decomposes into sub-tasks, coordinates workers | "Design auth system" |
+| **sub-planner** | Mid-level coordinator | Takes planner output, further decomposes, assigns to workers | "Break auth into API, model, middleware" |
+| **worker** | Execution agent | Executes assigned work, reports progress | "Implement auth service" |
+
+### When to Use Tiers
+
+- **<10 agents**: Optional - flat decomposition works
+- **10-50 agents**: Recommended - planner + workers
+- **50+ agents**: Required - planner + sub-planners + workers
+
+### Tier Declaration Format
+
+Add tier metadata to each task:
+
+```markdown
+### Task 1: Design Auth System
+
+**Tier:** planner
+
+**Files:**
+- Create: `docs/auth-design.md`
+
+This task decomposes the auth feature into sub-tasks for implementation.
+````
+
+### Handoff Contracts
+
+Tasks must declare what they produce for downstream tasks:
+
+```markdown
+### Handoff Contract
+
+**Produces:**
+
+- `docs/auth-design.md` - Architecture decision document
+
+**Consumed By:**
+
+- Task 2: Implement Auth Service
+- Task 3: Add Auth Tests
+```
+
+### Tier Enforcement in Plans
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **Tier Structure:**
+>
+> - **Planners (2):** Task 1, Task 5
+> - **Workers (6):** Tasks 2,3,4,6,7,8
+
+## Task Hierarchy
+
+### Tier 1: Planner Tasks (Orchestration)
+
+### Task 1: [Planner] Design Auth System
+
+### Task 5: [Planner] Design API Layer
+
+### Tier 2: Worker Tasks (Execution)
+
+### Task 2: [Worker] Implement Auth Service
+
+### Task 3: [Worker] Add Auth Middleware
+
+### Task 4: [Worker] Write Auth Tests
+```
+
+### Wave Execution with Tiers
+
+When executing with tiers:
+
+1. **Planner waves** execute first (scope definition)
+2. **Worker waves** execute after planner output is ready
+3. **Sub-planners** sit between, bridging planner → worker
+
+```markdown
+Wave 1 (Planners): Task 1, Task 5
+Wave 2 (Workers): Tasks 2, 3, 4 (after Task 1)
+Wave 3 (Workers): Tasks 6, 7, 8 (after Task 5)
+```
+
+### Anti-Pattern: Flat Decomposition at Scale
+
+Without tiers, 20 agents get 20 flat tasks → chaos:
+
+- Workers step on each other
+- No coordination between related work
+- Merge conflicts everywhere
+
+With tiers, the structure emerges:
+
+```
+Planner → Sub-planner A → Worker 1, 2, 3
+                     → Worker 4, 5
+        Sub-planner B → Worker 6, 7
+```
+
+This mirrors real engineering orgs: lead → tech lead → IC.
+
+`````
+
+## Context Budget
+
+Target: ~50% context per plan execution
+Maximum: 2-3 tasks per plan
+
+| Task Complexity | Max Tasks | Typical Context |
+| --------------- | --------- | --------------- |
+| Simple (CRUD)   | 3         | ~30-45%         |
+| Complex (auth)  | 2         | ~40-50%         |
+| Very complex    | 1-2       | ~30-50%         |
+
+**Split signals:**
+
+- More than 3 tasks → Create child plans
+- Multiple subsystems → Separate plans
+- Any task with >5 file modifications → Split
+- Checkpoint + implementation → Split
+- Discovery + implementation → Split
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+`````
+
+````
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+
+```
+
+## Remember
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills with @ syntax
+- DRY, YAGNI, TDD, frequent commits
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `.beads/artifacts/<bead-id>/plan.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Load `$executing-plans` for wave-based parallel execution
+- Stay in this session
+- Fresh subagent per task + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- **REQUIRED SUB-SKILL:** New session uses skill({ name: "executing-plans" })
+```
+````
+
+## See Also
+
+- `executing-plans` - Execute vetted plans in controlled batches with checkpoints
+- `prd` - Convert validated design into explicit behavioral requirements
+- `brainstorming` - Refine rough ideas and constraints before specification/planning

package/.codex/skills/writing-skills/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: writing-skills
+description: "Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization"
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
+---
+
+# Writing Skills
+
+## When to Use
+
+- Creating a new skill from scratch
+- Editing or improving an existing skill
+- Verifying a skill works correctly before deployment
+- Applying TDD methodology to process documentation
+
+## When NOT to Use
+
+- Routine code implementation (use executing-plans instead)
+- One-off instructions that don't need to be reusable
+- Quick configuration changes that don't warrant a skill
+
+## Overview
+
+**Writing skills IS Test-Driven Development applied to process documentation.**
+
+**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)**
+
+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.
+
+**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
+
+**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
+
+## 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     |
+
+The entire skill creation process follows RED-GREEN-REFACTOR.
+
+## 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)
+
+## 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 (office docs)
+
+## Directory Structure
+
+```
+skills/
+  skill-name/
+    SKILL.md              # Main reference (required)
+    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
+
+**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 (no parentheses, special chars)
+- `description`: Third-person, includes BOTH what it does AND when to use it
+  - Start with "Use when..." to focus on triggering conditions
+  - Include specific symptoms, situations, and contexts
+  - Keep under 500 characters if possible
+
+```markdown
+---
+name: Skill-Name-With-Hyphens
+description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
+---
+
+# Skill Name
+
+## Overview
+
+What is this? Core principle in 1-2 sentences.
+
+## When to Use
+
+[Small inline flowchart IF decision non-obvious]
+
+Bullet list with SYMPTOMS and use cases
+When NOT to use
+
+## 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 or reusable tools
+
+## Common Mistakes
+
+What goes wrong + fixes
+
+## Real-World Impact (optional)
+
+Concrete results
+```
+
+## The Iron Law (Same as TDD)
+
+```
+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"
+- Don't keep untested changes as "reference"
+- Don't "adapt" while running tests
+- Don't look at it
+- Delete means delete
+
+**REQUIRED BACKGROUND:** The test-driven-development skill explains why this matters. Same principles apply to documentation.
+
+## RED-GREEN-REFACTOR for Skills
+
+Follow the TDD cycle:
+
+### 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)?
+- Which pressures triggered violations?
+
+This is "watch the test fail" - you must see what agents naturally do before writing the skill.
+
+### 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.
+
+**REQUIRED SUB-SKILL:** Use skill({ name: "testing-skills-with-subagents" }) for the complete testing methodology:
+
+- How to write pressure scenarios
+- Pressure types (time, sunk cost, authority, exhaustion)
+- Plugging holes systematically
+- Meta-testing techniques
+
+## STOP: Before Moving to Next Skill
+
+**After writing ANY skill, you MUST STOP and complete the deployment process.**
+
+**Do NOT:**
+
+- Create multiple skills in batch without testing each
+- Move to next skill before current one is verified
+- Skip testing because "batching is more efficient"
+
+**The deployment checklist below is MANDATORY for EACH skill.**
+
+Deploying untested skills = deploying untested code. It's a violation of quality standards.
+
+## Skill Creation Checklist (TDD Adapted)
+
+**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
+
+**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 (no parentheses/special chars)
+- [ ] YAML frontmatter with only name and description (max 1024 chars)
+- [ ] Description starts with "Use when..." and includes specific triggers/symptoms
+- [ ] Description written in third person
+- [ ] Keywords throughout for search (errors, symptoms, tools)
+- [ ] Clear overview with core principle
+- [ ] Address specific baseline failures identified in RED
+- [ ] Code inline OR link to separate file
+- [ ] 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
+- [ ] Create red flags list
+- [ ] Re-test until bulletproof
+
+**Quality Checks:**
+
+- [ ] Small flowchart only if decision non-obvious
+- [ ] Quick reference table
+- [ ] Common mistakes section
+- [ ] No narrative storytelling
+- [ ] Supporting files only for tools or heavy reference
+
+**Deployment:**
+
+- [ ] Commit skill to git and push to your fork (if configured)
+- [ ] Consider contributing back via PR (if broadly useful)
+
+## References
+
+- `references/claude-search-optimization.md` - CSO guidance: descriptions, keywords, token efficiency, cross-references
+- `references/flowcharts-and-examples.md` - Flowchart usage rules and code example guidance
+- `references/file-organization.md` - Patterns for self-contained vs heavy-reference skills
+- `references/testing-skill-types.md` - How to test discipline, technique, pattern, and reference skills
+- `references/rationalization-hardening.md` - Loophole closure, rationalization tables, red flags
+- `references/anti-patterns.md` - Anti-patterns to avoid
+- `references/discovery-workflow.md` - How future agents find and use skills