pi-orchestrator-config 4.1.5

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

@@ -0,0 +1,335 @@
+---
+name: test-driven-development
+description: "TDD: enforce RED-GREEN-REFACTOR, tests before code."
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+**Violating the letter of the rules is violating the spirit of the rules.**
+
+## When to Use
+
+**Always:**
+
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask the user first):**
+
+- Throwaway prototypes
+- Generated code
+- Configuration files
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+## The Iron Law
+
+```text
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+Implement fresh from tests. Period.
+
+## Red-Green-Refactor Cycle
+
+### RED — Write Failing Test
+
+Write one minimal test showing what should happen.
+
+**Good test:**
+
+```python
+def test_retries_failed_operations_3_times():
+    attempts = 0
+    def operation():
+        nonlocal attempts
+        attempts += 1
+        if attempts < 3:
+            raise Exception('fail')
+        return 'success'
+
+    result = retry_operation(operation)
+
+    assert result == 'success'
+    assert attempts == 3
+```
+
+Clear name, tests real behavior, one thing.
+
+**Bad test:**
+
+```python
+def test_retry_works():
+    mock = MagicMock()
+    mock.side_effect = [Exception(), Exception(), 'success']
+    result = retry_operation(mock)
+    assert result == 'success'  # What about retry count? Timing?
+```
+
+Vague name, tests mock not real code.
+
+**Requirements:**
+
+- One behavior per test
+- Clear descriptive name ("and" in name? Split it)
+- Real code, not mocks (unless truly unavoidable)
+- Name describes behavior, not implementation
+
+### Verify RED — Watch It Fail
+
+**MANDATORY. Never skip.**
+
+```bash
+# Run the specific test
+uv run pytest tests/test_feature.py::test_specific_behavior -v
+```
+
+Confirm:
+
+- Test fails (not errors from typos)
+- Failure message is expected
+- Fails because the feature is missing
+
+**Test passes immediately?** You're testing existing behavior. Fix the test.
+
+**Test errors?** Fix the error, re-run until it fails correctly.
+
+### GREEN — Minimal Code
+
+Write the simplest code to pass the test. Nothing more.
+
+**Good:**
+
+```python
+def add(a, b):
+    return a + b  # Nothing extra
+```
+
+**Bad:**
+
+```python
+def add(a, b):
+    result = a + b
+    logging.info(f"Adding {a} + {b} = {result}")  # Extra!
+    return result
+```
+
+Don't add features, refactor other code, or "improve" beyond the test.
+
+**Cheating is OK in GREEN:**
+
+- Hardcode return values
+- Copy-paste
+- Duplicate code
+- Skip edge cases
+
+We'll fix it in REFACTOR.
+
+### Verify GREEN — Watch It Pass
+
+**MANDATORY.**
+
+```bash
+# Run the specific test
+uv run pytest tests/test_feature.py::test_specific_behavior -v
+
+# Then run ALL tests to check for regressions
+uv run pytest tests/ -q
+```
+
+Confirm:
+
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix the code, not the test.
+
+**Other tests fail?** Fix regressions now.
+
+### REFACTOR — Clean Up
+
+After green only:
+
+- Remove duplication
+- Improve names
+- Extract helpers
+- Simplify expressions
+
+Keep tests green throughout. Don't add behavior.
+
+**If tests fail during refactor:** Undo immediately. Take smaller steps.
+
+### Repeat
+
+Next failing test for next behavior. One cycle at a time.
+
+## Why Order Matters
+
+### "I'll write tests after to verify it works"
+
+Tests written after code pass immediately. Passing immediately proves nothing:
+
+- Might test the wrong thing
+- Might test implementation, not behavior
+- Might miss edge cases you forgot
+- You never saw it catch the bug
+
+Test-first forces you to see the test fail, proving it actually tests something.
+
+### "I already manually tested all the edge cases"
+
+Manual testing is ad-hoc. You think you tested everything but:
+
+- No record of what you tested
+- Can't re-run when code changes
+- Easy to forget cases under pressure
+- "It worked when I tried it" ≠ comprehensive
+
+Automated tests are systematic. They run the same way every time.
+
+### "Deleting X hours of work is wasteful"
+
+Sunk cost fallacy. The time is already gone. Your choice now:
+
+- Delete and rewrite with TDD (high confidence)
+- Keep it and add tests after (low confidence, likely bugs)
+
+The "waste" is keeping code you can't trust.
+
+### "TDD is dogmatic, being pragmatic means adapting"
+
+TDD IS pragmatic:
+
+- Finds bugs before commit (faster than debugging after)
+- Prevents regressions (tests catch breaks immediately)
+- Documents behavior (tests show how to use code)
+- Enables refactoring (change freely, tests catch breaks)
+
+"Pragmatic" shortcuts = debugging in production = slower.
+
+### "Tests after achieve the same goals — it's spirit not ritual"
+
+No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
+
+Tests-after are biased by your implementation. You test what you built, not what's required. Tests-first force edge case discovery before implementing.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+| ------ | ------- |
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to the test. Hard to test = hard to use. |
+| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
+| "Existing code has no tests" | You're improving it. Add tests for the code you touch. |
+
+## Red Flags — STOP and Start Over
+
+If you catch yourself doing any of these, delete the code and restart with TDD:
+
+- Code before test
+- Test after implementation
+- Test passes immediately on first run
+- Can't explain why test failed
+- Tests added "later"
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "Keep as reference" or "adapt existing code"
+- "Already spent X hours, deleting is wasteful"
+- "TDD is dogmatic, I'm being pragmatic"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.
+
+## When Stuck
+
+| Problem | Solution |
+| ------- | -------- |
+| Don't know how to test | Write the wished-for API. Write the assertion first. Ask the user. |
+| Test too complicated | Design too complicated. Simplify the interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify the design. |
+
+## Pi Agent Integration
+
+### Running Tests
+
+Use `bash` to run tests at each step:
+
+```bash
+# RED: Run the failing test
+uv run pytest tests/test_feature.py::test_name -v
+
+# GREEN: Run after implementing
+uv run pytest tests/test_feature.py::test_name -v
+
+# Full suite: Check for regressions
+uv run pytest tests/ -q
+```
+
+### With subagent
+
+The test-automator agent follows TDD discipline.
+The orchestrator delegates test creation and verification to this agent.
+
+### With systematic-debugging
+
+Bug found? Write failing test reproducing it. Follow TDD cycle. The test proves the fix and prevents regression.
+
+Never fix bugs without a test.
+
+## Testing Anti-Patterns
+
+- **Testing mock behavior instead of real behavior** — mocks should verify interactions, not replace the system under test
+- **Testing implementation details** — test behavior/results, not internal method calls
+- **Happy path only** — always test edge cases, errors, and boundaries
+- **Brittle tests** — tests should verify behavior, not structure; refactoring shouldn't break them
+
+## Final Rule
+
+```text
+Production code → test exists and failed first
+Otherwise → not TDD
+```
+
+No exceptions without the user's explicit permission.

package/skills/update-agents-md/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: update-agents-md
+description: "Create or update AGENTS.md / CLAUDE.md using industry best practices. Use when the user asks to create AGENTS.md, update project documentation, or after code changes that need documentation updates."
+---
+
+# AGENTS.md Best Practice Guide
+
+Research-backed guide for creating and updating AGENTS.md files.
+Sources: GitHub (2,500-repo analysis), Augment Code (measured eval), Blake Crosley (pattern analysis), agents.md spec.
+
+---
+
+## Mode: Creating New AGENTS.md
+
+1. Scan the repo — identify tech stack, build system, test framework, file structure
+   - For monorepos, use subdirectory AGENTS.md files scoped to each package — don't put everything in one root file.
+2. Use the **Template** below as starting skeleton
+3. Fill in all **Required Sections** in order
+4. Verify total is under 150 lines (longer files hurt performance)
+5. Move detailed content to referenced files if needed
+
+## Mode: Updating Existing AGENTS.md
+
+1. Read the entire current file first
+2. Run the **Audit Checklist** below
+3. Fix gaps in priority order — don't rewrite what already works
+4. Verify size stays under 150 lines after changes
+
+## Mode: Post-Code-Change Update
+
+1. Check if the change affects: commands, file structure, dependencies, workflows
+2. Update only the affected sections — don't touch unrelated content
+3. Verify commands in the file still work
+
+---
+
+## Required Sections (in this order)
+
+Order matters — front-load highest-ROI content. Commands FIRST.
+
+### 1. Build & Test Commands (HIGHEST ROI)
+
+```markdown
+## Commands
+- Build: `<build command>`
+- Test: `<test command with flags>`
+- Lint: `<lint command with flags>`
+- Type check: `<type check command>`
+- Full verify: `<lint command> && <test command> && <type check command>`
+```
+
+Rules:
+
+- Exact invocations with flags — not just tool names
+- Include the "full verify" one-liner the agent runs before committing
+- Every instruction in the file should answer: "What command proves this was done?"
+
+### 2. Definition of Done
+
+```markdown
+## Definition of Done
+A task is complete when ALL pass:
+1. `<lint command>` exits 0
+2. `<test command>` exits 0 with no failures
+3. `<type check command>` exits 0
+4. Changed files staged and committed
+5. Commit message: `type(scope): description`
+```
+
+Rules:
+
+- Specific exit codes, not feelings
+- Without this, "done" means "I think I'm done" — the #1 agent failure mode
+
+### 3. Escalation Rules
+
+```markdown
+## When Blocked
+- Tests fail after 3 attempts → stop, report failing test with full output
+- Missing dependency → check requirements first, then ask
+- Merge conflicts → stop, show conflicting files
+- NEVER: delete files to resolve errors, force push, skip tests
+```
+
+Rules:
+
+- Without escalation rules, agents improvise destructively when blocked
+- Pair every "never" with what to do instead
+
+### 4. Project Context
+
+```markdown
+## Project
+- Stack: <technology with version>, <technology with version>, <build tool>
+- Structure: `src/` (app code), `tests/` (tests), `docs/` (documentation)
+- Key deps: <dependency> for <purpose>, <dependency> for <purpose>
+```
+
+Rules:
+
+- Specific versions and key dependencies
+- Vague descriptions ("React project") are useless — include versions and key deps
+- File structure with one-line descriptions
+
+### 5. Task-Organized Sections
+
+```markdown
+## When Writing Code
+- Run `<lint command>` after every file change
+- Add type hints to all new functions
+- Test: `<test command for specific module>`
+
+## When Reviewing Code
+- Check security: `<security audit command>`
+- Verify coverage: `<test command with coverage flag>`
+
+## When Releasing
+- Update version in `<manifest file>`
+- Run full suite: `<test command> && <lint command> && <type check command>`
+- Tag: `git tag -a v<version> -m "Release v<version>"`
+```
+
+Rules:
+
+- "When X" sections let agents select relevant instructions by task context
+- Flat topic lists force parsing everything regardless of current task
+- Task-organized > topic-organized
+
+### 6. Boundaries
+
+```markdown
+## Boundaries
+- ✅ Always: run tests before commits, follow naming conventions
+- ⚠️ Ask first: database schema changes, adding dependencies, modifying CI
+- 🚫 Never: commit secrets, edit dependency dirs, force push to main
+```
+
+Rules:
+
+- Three tiers: always do, ask first, never do
+- Pair every "don't" with a "do" — warning-only docs consistently underperform
+- 15+ sequential "don'ts" without "dos" cause agent overexploration
+
+---
+
+## Size Budget (for generated AGENTS.md files)
+
+These limits apply to the AGENTS.md files you CREATE, not to this skill guide.
+
+| Metric | Target | Why |
+|--------|--------|-----|
+| Total file | Under 150 lines | Longer files actively hurt (Augment, measured) |
+| Per section | Under 50 lines | Context window truncation risk |
+| Reference files | 3-10 max | Agent reads 90%+ when referenced from AGENTS.md |
+
+**Progressive disclosure:** Keep main file concise. Push details to referenced files:
+
+```markdown
+For detailed API conventions, see `docs/api-conventions.md`.
+For migration procedures, see `docs/migrations.md`.
+```
+
+**Warning:** A 150-line AGENTS.md on top of 500K of surrounding docs won't save the agent from the docs. Fix the documentation environment, not just the entry point.
+
+---
+
+## Decision Table
+
+When the agent needs to choose what patterns to include:
+
+| If you want to improve... | Use this pattern |
+|--------------------------|-----------------|
+| Reuse of existing code | 3-10 line examples from actual prod code |
+| Following codebase conventions | Decision tables for ambiguous choices |
+| Wiring of complex features | Numbered procedural workflows |
+| Handling of gotchas | "Don't X" paired with "Do Y instead" |
+| Reducing context rot | Progressive disclosure via reference files |
+
+---
+
+## Anti-Patterns (NEVER do these)
+
+| Anti-Pattern | Why it fails | Fix |
+|-------------|-------------|-----|
+| Prose paragraphs without commands | Agent can't verify compliance | Add the command that proves it |
+| "Be careful with X" | Not a constraint — no trigger, no action | "Run `cmd` before X. Abort if Y." |
+| Contradictory priorities without ordering | Agent skips verification, rushes to code | Number priorities: P1 > P2 > P3 |
+| Style guide without enforcement command | No verification mechanism | Add the lint command that enforces it |
+| 15+ "don'ts" without "dos" | Agent overexplores, stays conservative | See Boundaries rules above |
+| Architecture overview essays | Agent reads 100K+ tokens of docs | Keep to 2-3 sentences, reference files for details |
+
+---
+
+## Writing Style Rules
+
+- Fewer lines = more compliance. One sentence per concept.
+- Reserve MANDATORY/NEVER/FORBIDDEN for data loss, security, or irreversible actions. When everything is critical, nothing stands out.
+- Use precise language — ambiguous rules get exploited. Scope restrictions clearly (e.g., 'Outside slash commands, never use bash' not 'never use bash').
+- One ❌/✅ example per section only when it shows a specific recurring mistake.
+- Merge sub-sections that say the same thing from different angles.
+- Numbered checklists over ASCII flowcharts — fewer tokens, easier to follow.
+- Match the project's existing format — read the file before editing.
+
+---
+
+## Cross-Tool Compatibility
+
+| Tool | Native file | Reads AGENTS.md? |
+|------|------------|-------------------|
+| Codex CLI | AGENTS.md | Yes (native) |
+| Cursor | `.cursor/rules` | Yes (native) |
+| GitHub Copilot | `.github/copilot-instructions.md` | Yes (native) |
+| Claude Code | CLAUDE.md | Yes (native + CLAUDE.md) |
+| Gemini CLI | GEMINI.md | Configurable |
+| Windsurf | `.windsurfrules` | Yes (native) |
+
+**Strategy:** Write AGENTS.md as canonical source. Claude Code reads both AGENTS.md and CLAUDE.md natively — use CLAUDE.md for Claude-specific overrides only.
+
+---
+
+## Template
+
+````markdown
+# Project Name
+
+Brief one-line description of the project.
+
+## Commands
+- Build: `<build command>`
+- Test: `<test command with flags>`
+- Lint: `<lint command>`
+- Full verify: `<all-in-one verification command>`
+
+## Definition of Done
+A task is complete when ALL pass:
+1. `<lint>` exits 0
+2. `<test>` exits 0
+3. `<type check>` exits 0
+4. Files committed with message: `type(scope): description`
+
+## When Blocked
+- Tests fail after 3 attempts → stop, report with full output
+- Missing dependency → check manifest first, then ask
+- NEVER: delete files to fix errors, force push, skip tests
+
+## Project
+- Stack: <technologies with versions>
+- Structure: `src/` (code), `tests/` (tests), `docs/` (docs)
+
+## When Writing Code
+- <key convention 1>
+- <key convention 2>
+- Test: `<how to run relevant tests>`
+
+## When Reviewing Code
+- <review checklist item 1>
+- <review checklist item 2>
+
+## Boundaries
+- ✅ Always: <what to always do>
+- ⚠️ Ask first: <what needs approval>
+- 🚫 Never: <what to never do>
+````
+
+---
+
+## Audit Checklist (for updating existing files)
+
+Run through when reviewing an existing AGENTS.md:
+
+- [ ] Commands section exists and comes FIRST (before any prose)?
+- [ ] All commands are exact invocations with flags (not just tool names)?
+- [ ] Definition of Done section with specific exit codes?
+- [ ] Escalation rules — what to do when blocked?
+- [ ] Total file under 150 lines?
+- [ ] Each section under 50 lines?
+- [ ] Organized by task ("When X") not by topic?
+- [ ] Every "don't" paired with a "do"?
+- [ ] No prose paragraphs without commands?
+- [ ] No ambiguous directives ("be careful", "where possible")?
+- [ ] No contradictory priorities without explicit ordering?
+- [ ] Detailed content in referenced files, not inline?