claude-dev-env 1.0.0

package/skills/skill-writer/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: skill-writer
+description: Guide users through creating Agent Skills for Codex. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
+---
+
+# Writing Skills
+
+## Overview
+
+Create well-structured Agent Skills for Codex that follow superpowers patterns and validation requirements.
+
+**Core principle:** Skills encode expertise. A good skill prevents the same mistake from happening twice.
+
+**Announce at start:** "I'm using the skill-writer skill to create a new skill."
+
+**Context:** Skills complement agents. Skills are invoked inline; agents run as subprocesses. Use skills for workflows that need conversation context.
+
+## The Process
+
+### Step 1: Understand the Need
+
+Ask clarifying questions (one at a time):
+
+1. What specific capability should this Skill provide?
+2. When should Codex use this Skill?
+3. Is this critical (must follow exactly) or advisory (adapt to context)?
+4. Does this fit in an existing workflow pipeline?
+
+**Keep it focused:** One Skill = one capability
+- Good: "PDF form filling", "plan review", "TDD enforcement"
+- Too broad: "Document processing", "code quality"
+
+### Step 2: Choose Format
+
+**CRITICAL DECISION:** Advisory vs Superpowers format.
+
+| Format | When to Use | Key Signals |
+|--------|-------------|-------------|
+| **Superpowers** | Rules that MUST be followed | Production failures if violated, anti-patterns to block, non-negotiable workflows |
+| **Advisory** | Helpful guidance | Best practices, tips, adaptable to context |
+
+**If in doubt:** If you're tempted to say "should" instead of "MUST", it's advisory.
+
+### Step 3: Choose Location
+
+**Personal Skills** (`~/.Codex/skills/`):
+- Individual workflows
+- Experimental skills
+
+**Project Skills** (`.Codex/skills/`):
+- Team conventions
+- Project-specific expertise
+- Committed to git
+
+### Step 4: Write Frontmatter
+
+```yaml
+---
+name: skill-name
+description: [What it does] + [When to use it] + [Trigger phrases]
+---
+```
+
+**Name rules:**
+- Lowercase, hyphens only, max 64 chars
+- Must match directory name
+
+**Description formula:** `[What] + [When] + [Triggers]`
+
+```yaml
+# Good
+description: Review implementation plans against AGENTS.md standards. Use after writing-plans and before executing-plans to validate TDD compliance and right-sized engineering.
+
+# Bad
+description: Helps with plans
+```
+
+### Step 5: Write Content
+
+#### Superpowers Format Structure
+
+```markdown
+# Skill Name
+
+## Overview
+
+Brief description.
+
+**Core principle:** [One sentence that captures the essential insight]
+
+**Announce at start:** "I'm using the [skill] skill to [purpose]."
+
+**Context:** [Where this fits in the workflow pipeline]
+
+## The Process
+
+### Step 1: [First Action]
+[Narrative instructions, not verbose checklists]
+
+### Step 2: [Second Action]
+[Continue with clear steps]
+
+## Output Format
+
+[What the skill produces - be specific]
+
+## After Completion
+
+[What happens next - reference sub-skills if applicable]
+
+**If [condition]:**
+- [Action]
+- **REQUIRED SUB-SKILL:** Use [skill-name]
+
+## Red Flags - STOP
+
+[List signals that mean something is wrong]
+
+- [Red flag 1]
+- [Red flag 2]
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "[Common shortcut]" | [Why it fails] |
+| "[Another excuse]" | [Why it fails] |
+
+## Remember
+
+- [Key point 1]
+- [Key point 2]
+- [Key point 3]
+```
+
+#### Advisory Format Structure
+
+```markdown
+# Skill Name
+
+## Overview
+
+Brief description of what this Skill does.
+
+**Announce at start:** "I'm using the [skill] skill."
+
+## Instructions
+
+Step-by-step guidance:
+1. First step
+2. Second step
+3. Handle edge cases
+
+## Examples
+
+Concrete usage examples.
+
+## Best practices
+
+- Key conventions
+- Common pitfalls
+```
+
+#### Ironclad Format (Critical Rules)
+
+For skills where violations cause production failures:
+
+```markdown
+<EXTREMELY_IMPORTANT>
+# Skill Name
+
+**This skill is MANDATORY for [context].**
+
+IF you are [doing task], YOU DO NOT HAVE A CHOICE. YOU MUST FOLLOW THIS SKILL.
+
+## MANDATORY FIRST RESPONSE PROTOCOL
+
+Before doing ANYTHING:
+
+1. [ ] [First verification]
+2. [ ] [Second verification]
+3. [ ] [Third verification]
+
+**Responding WITHOUT completing this checklist = automatic failure.**
+
+## Critical Rules - NO EXCEPTIONS
+
+### Rule 1: [Rule Name]
+
+**NEVER [forbidden action].**
+
+- [ ] FORBIDDEN: [specific example]
+- [x] REQUIRED: [correct approach]
+
+**WHY:** [Production consequence]
+
+## Common Rationalizations That Mean You're About To Fail
+
+- **"[Excuse 1]"** -> WRONG. [Reality]
+- **"[Excuse 2]"** -> WRONG. [Reality]
+
+</EXTREMELY_IMPORTANT>
+
+---
+
+## Implementation Guide
+
+[Supporting material outside the critical wrapper]
+```
+
+### Step 6: Validate
+
+**Structure:**
+- [ ] SKILL.md in correct location
+- [ ] Directory name matches `name` field
+- [ ] Valid YAML frontmatter
+
+**Content (Superpowers format):**
+- [ ] Has Overview with Core principle
+- [ ] Has "Announce at start"
+- [ ] Has Context (pipeline placement)
+- [ ] Steps are narrative, not verbose checklists
+- [ ] Has Red Flags section
+- [ ] Has Rationalization Prevention table
+- [ ] Has Remember section
+- [ ] References sub-skills where appropriate
+
+**Content (Ironclad format):**
+- [ ] `<EXTREMELY_IMPORTANT>` wrapper
+- [ ] Absolute language ("MUST", "NEVER", "NO EXCEPTIONS")
+- [ ] Checkbox protocol
+- [ ] WHY explanations with consequences
+- [ ] Rationalizations are specific, not generic
+
+### Step 7: Test
+
+1. Restart Codex to load the skill
+2. Ask questions that should trigger it
+3. Verify activation and behavior
+
+## Red Flags - STOP
+
+- Skill is too broad ("handles documents")
+- No clear trigger phrases in description
+- Steps say "consider" or "might" in Ironclad format
+- No workflow context (where does this fit?)
+- Rationalizations are generic ("I'll do it later")
+- Missing WHY explanations for rules
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "This skill is simple, doesn't need structure" | Simple skills become complex. Structure prevents drift. |
+| "I'll add the rationalization section later" | Later never comes. Add it now. |
+| "Nobody will try to shortcut this" | Developers always shortcut. Block it proactively. |
+| "The description is good enough" | Vague descriptions mean skill never activates. |
+| "Advisory format is fine for critical rules" | Critical rules need Ironclad format or they get ignored. |
+
+## Remember
+
+- **Core principle first** - captures the essential insight
+- **Announce at start** - makes skill usage visible
+- **Context placement** - skills fit in pipelines
+- **Red flags** - catch problems early
+- **Rationalizations** - block shortcuts proactively
+- **Sub-skill references** - connect to related workflows
+- One skill = one capability
+- Specific triggers in description
+- Test activation before shipping

package/skills/tdd-team/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: tdd-team
+description: "Spawn an orchestrated TDD agent team (planner, tester, implementer, validator) to build features or fix bugs via Red-Green-Refactor. Use when the user says /tdd-team, 'TDD team', 'agent team for this', 'have a team build this', or describes a non-trivial implementation task they want done with test-driven development and parallel agents. Also triggers on 'agentically', 'orchestrated team', or 'planner implementer tester validator'."
+---
+
+# TDD Team
+
+Spawn an orchestrated team of 4 agents that implements a feature or fix using strict Test-Driven Development: Plan -> RED (failing tests) -> GREEN (minimum code to pass) -> Validate.
+
+## When to use
+
+- Non-trivial features requiring 3+ files changed
+- Bug fixes where the fix needs tests proving the bug exists first
+- Any task where the user says "TDD" and "team" or "agentically"
+
+## Arguments
+
+The full task description follows the command. Example:
+```
+/tdd-team fix proportional split distribution when item prices exceed order total
+```
+
+## Workflow
+
+### Phase 1: Setup
+
+1. **Create team** via TeamCreate with a name derived from the task (kebab-case, max 30 chars)
+2. **Create tasks** with dependencies:
+   - #1 PLAN — blocked by nothing
+   - #2-N RED — blocked by #1
+   - #N+1 GREEN — blocked by all RED tasks
+   - #LAST VALIDATE — blocked by GREEN task
+3. **Spawn 4 agents** (all at once for parallel startup):
+   - `planner` (team-lead) — reads code, designs the approach, defines file ownership so agents work independently, and messages teammates with clear assignments
+   - `tester` (team-implementer) — writes failing tests that define the expected behavior before implementation exists, establishing the contract the code must satisfy
+   - `implementer` (team-implementer) — writes the minimum production code to satisfy the test contracts, keeping scope tight to keep all behavior tested
+   - `validator` (team-reviewer) — runs the full test suite to catch regressions across files, and verifies the feature works end-to-end
+
+### Phase 2: Orchestrate
+
+As the team lead, your job is to:
+- **Nudge blocked agents** when upstream tasks complete (send messages)
+- **Shutdown idle agents** when all their tasks are done (send shutdown_request)
+- **Report progress** to the user at milestones (plan done, tests written, implementation done, validation complete)
+- **Fix coordination issues** (e.g., tester waiting for planner who already finished)
+
+### Phase 3: Cleanup
+
+After validator reports success:
+1. Shutdown all remaining agents
+2. Clean up any temporary files, scripts, or helper files created during iteration
+3. Delete the team via TeamDelete
+4. Run `python -m pytest tests/ -q` to confirm final count
+5. Commit with descriptive message
+6. Report summary to user
+
+## Agent Prompts
+
+Each agent receives a structured prompt containing:
+
+### Common context (all agents get this)
+- The task description from the user
+- Working directory path
+- Code rules reminder: no magic values, no abbreviations, complete type hints, no new inline comments, imports at top, constants in config/
+- Collaboration guidance: flag ambiguity or uncertainty to teammates and use [PLACEHOLDER] for values you have not verified. Your role contributes to a specific phase of the TDD cycle — the separation between phases is what makes TDD effective.
+- Anti-test-fixation: write general solutions that work for all valid inputs, not just the specific test cases. Tests verify correctness -- they do not define the solution. If a test seems incorrect, flag it rather than working around it.
+- Commit-and-execute: choose an approach and commit to it. Avoid revisiting decisions unless new information directly contradicts your reasoning. Course-correct later if needed.
+
+### Planner-specific
+- Read the relevant source files before designing
+- Design the implementation with function signatures and return types
+- Define file ownership boundaries (tester owns test files, implementer owns production files)
+- Create the task breakdown with specific test cases to write
+- Mark task complete and message teammates with assignments
+- If the scope is unclear or requirements are ambiguous, flag this to the orchestrator and propose assumptions for confirmation
+- Commit to an approach and communicate it clearly to teammates -- avoid revisiting architectural decisions unless implementation reveals a fundamental problem
+
+### Tester-specific
+- Wait for planner to complete (check TaskList)
+- Write FAILING tests that reproduce the desired behavior
+- Use existing test patterns from the project (read test files first)
+- Mock external calls, use patch.dict for env vars
+- Tests must FAIL before implementation — that's the point
+- Mark each task complete, check TaskList for next work
+- If a test case from the plan is ambiguous about expected behavior, ask the planner for clarification — a clear test is the most valuable deliverable
+
+### Implementer-specific
+- Wait for tester to complete (check TaskList)
+- Read the failing tests to understand expected behavior
+- Write MINIMUM code to make tests pass — no extras
+- Run the specific test file to verify green
+- Mark task complete, check TaskList for next work
+- Write general solutions that work for all valid inputs -- never hard-code values or create implementations that only satisfy specific test assertions
+- If a failing test seems to test the wrong behavior or has a bug in the test itself, flag it to the validator for review
+
+### Validator-specific
+- Wait for implementer to complete (check TaskList)
+- Run full test suite (`python -m pytest tests/ -q`)
+- Fix test regressions from the new code (e.g., unmocked new functions in existing tests)
+- Verify new functions exist and are wired correctly
+- Verify the implementation fully captures the planner's design (all planned functions exist, signatures match, edge cases covered)
+- Verify the implementation follows project code rules (centralized config, complete type hints, full-word naming, self-documenting code)
+- Report: test count, pass/fail, regressions found and fixed, plan coverage assessment, code rules compliance
+- If regressions trace to a design issue, report the root cause to the orchestrator for a targeted follow-up task
+
+## Task Sizing
+
+The planner decides how many RED tasks to create based on the scope:
+- **Small fix** (1 function): 1 RED task, 1 GREEN task
+- **Medium feature** (2-3 functions): 2-3 RED tasks (can be parallel), 1-2 GREEN tasks
+- **Large feature** (4+ functions across files): 3-5 RED tasks, 2-3 GREEN tasks with dependencies
+
+## Error Recovery
+
+- If tester writes tests that import non-existent constants, that's expected (RED phase)
+- If implementer's code breaks existing tests, validator fixes the regressions
+- If validator finds issues, create a new fix task and assign to implementer
+- If an agent goes idle repeatedly without progress, send a message with specific instructions
+- When encountering obstacles, use standard tools and approaches -- do not create helper scripts or workarounds to bypass problems; flag the issue for resolution
+
+## Ownership Boundaries
+
+Each agent owns its phase — this separation ensures the TDD cycle produces reliable results:
+
+- The tester writes tests; the implementer writes production code. This separation ensures tests define behavior independently of implementation.
+- Failing tests exist before any production code. This is the core of TDD — the test proves the requirement, then the code satisfies it.
+- The validator runs after implementation. It catches regressions across files that are invisible to agents working on individual files.
+- Shut down agents after their tasks complete. Idle agents consume context; active agents produce value.