Menü
Provides expertise on how to plan for work in this repo
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
| name | planning |
| description | Provides expertise on how to plan for work in this repo |
This skill provides comprehensive guidance on how to plan a new feature in this repo.
Automated tests verify the actual behavior of bash functions during execution using TypeScript/Vitest.
When to use:
Tools:
pnpm test)*.test.ts in TypeScripttests/helpers/bash.ts for executing bash from TypeScriptExample:
import { describe, it, expect } from 'vitest'
import { sourcedBash } from './helpers/bash'
describe('list utilities', () => {
it('should retain items with matching prefixes', () => {
const result = sourcedBash('./utils/lists.sh', `
items=("apple" "banana" "cherry")
retain_prefixes_ref items "a"
`)
expect(result).toContain('apple')
expect(result).not.toContain('cherry')
})
})
Visual demonstration scripts provide interactive examples that require human inspection.
When to use:
Tools:
*-demo.sh or showcase-*.sh in tests/demos/./tests/demos/color-demo.shUse Automated Tests (*.test.ts) when:
Use Demo Scripts (*.sh in tests/demos/) when:
Rule of thumb: When in doubt, write automated tests. Only use demos when automation isn't feasible.
Tests use a hybrid approach: TypeScript for automation, bash for visual demos.
tests/
├── demos/ # Visual demonstration scripts (bash)
│ ├── color-demo.sh # Interactive color showcase
│ └── showcase.sh # General feature demonstrations
├── helpers/ # TypeScript test utilities
│ ├── bash.ts # Bash execution helpers
│ ├── bash.test.ts # Tests for bash helper itself
│ └── example.test.ts # Example/documentation
├── WIP/ # Work in progress (during TDD phases)
│ └── *.test.ts # In-progress tests
├── *.test.ts # Automated Vitest tests
└── README.md # Testing documentation
*.test.ts (TypeScript files testing bash functions)*-demo.sh or showcase-*.sh (bash files for visual inspection)it("should return true when...)it("should handle empty strings")DO:
describe blocksDON'T:
When implementing a new feature, ALWAYS follow this comprehensive TDD workflow:
When a user provides you with a new feature or plan idea, the first step is always to take that as an input into making a more structured and formalized plan:
.ai/plans/${YYYY}-${MM}-${DD}-${NAME}.mdtxt if you are simply using the block as a text output.The remaining steps represent how each PHASE of the plan should be structured.
Capture the current state of all tests before making any changes.
Actions:
Run all tests:
pnpm test
Create a simple XML or text representation of test results
Document any existing failures (these are your baseline - don't fix yet)
Purpose: Establish a clear baseline so you can detect regressions and measure progress.
Create a log file to track this phase of work.
Actions:
Create log file with naming convention:
mkdir -p .ai/logs
touch .ai/logs/YYYY-MM-planName-phaseN-log.md
Example: .ai/logs/2025-10-symbol-filtering-phase1-log.md
Add ## Starting Test Position section with XML code block containing test results from SNAPSHOT
Add ## Repo Starting Position section
Run the start-position script to capture git state:
bun run .claude/skills/planning/scripts/start-position.ts planName phaseNumber
This returns markdown content showing:
Append the start-position output to the log file
Purpose: Create a detailed record of the starting point for debugging and tracking progress.
Write tests FIRST before any implementation. This is true Test-Driven Development.
Actions:
Understand existing test structure:
Create tests in WIP directory:
tests/WIP/pnpm test WIPpnpm test --grep -v WIPWrite comprehensive test coverage:
Verify tests FAIL initially:
pnpm test WIPExample WIP structure:
tests/WIP/
├── phase1-text-utils.test.ts
├── phase1-list-utils.test.ts
└── phase1-filesystem.test.ts
Purpose: Tests define the contract and expected behavior before any code is written.
Use the tests to guide your implementation.
Actions:
Implement minimal code to pass each test:
Iterate rapidly:
pnpm test WIPpnpm test:watch WIPContinue until all phase tests pass:
tests/WIP/ should be greenRefactor with confidence:
Purpose: Let tests drive the implementation, ensuring you build exactly what's needed.
Verify completeness, check for regressions, and finalize the phase.
Actions:
Run full test suite:
pnpm test # All tests (excluding WIP)
Handle any regressions:
If existing tests now fail:
## Regressions FoundIf no regressions, migrate tests to permanent locations:
tests/ directory (e.g., tests/lists.test.ts)tests/WIP/ to their permanent homestests/WIP/ directoryUpdate the log file:
Add a ## Phase Completion section with:
Report completion:
Inform the user that the phase is complete with a summary of:
Purpose: Ensure quality, prevent regressions, and properly integrate work into the codebase.
Prefer real implementations over mocks: Only mock external dependencies (APIs, file system, databases). Keep internal code integration real.
Use realistic test data: Mirror actual usage patterns. If your function processes user objects, use realistic user data in tests.
One behavior per test: Each it() block should test a single specific behavior. This makes failures easier to diagnose.
Tests should be deterministic: Same input = same output, every time. Avoid depending on current time, random values, or external state unless that's what you're testing.
Keep tests independent: Each test should be able to run in isolation. Use beforeEach() for setup, not shared variables.
Test the contract, not the implementation: If you change HOW something works but it still behaves the same, tests shouldn't break.
Prioritize fixing source code over changing tests: When tests fail, your first instinct should be to fix the implementation to meet the test's expectation, not to change the test to match the implementation.
Understand failures deeply: Don't just read the error message - understand WHY the test is failing. Use debugging, logging, or step through the code if needed.
Document complex test scenarios: If a test needs explanation, add a comment describing what scenario it's covering and why it matters.
Keep unit tests fast: Unit tests should run in milliseconds. If a test is slow, it's likely testing too much or hitting external resources.
Separate fast and slow tests: Integration tests can be slower. Keep them in separate files (e.g., *.fast.test.ts vs *.test.ts).
Use focused test runs during development: Don't run the entire suite on every change. Use glob patterns to run just what you're working on.
Test exit codes: Bash functions use exit codes (0 for success, non-zero for failure). Test these explicitly using bashExitCode() helper.
Test stdout and stderr separately: Use the bash helper to capture output. Consider testing stderr for error messages.
Handle environment variables: Set up required environment variables (like ROOT, ADAPTIVE_SHELL) in test setup.
Test with realistic data: Use actual file paths, realistic strings, and representative arrays when testing bash functions.
Clean up temporary files: Use beforeEach/afterEach to create and clean up any temporary files or directories needed for tests.
import { describe, it, expect } from 'vitest'
import { sourcedBash } from './helpers/bash'
it("should trim whitespace from string", () => {
const result = sourcedBash('./utils/text.sh', `trim " hello "`)
expect(result).toBe('hello')
})
it("should handle empty strings", () => {
const result = sourcedBash('./utils/empty.sh', `is_empty ""`)
expect(result).toBe('') // Success (exit 0)
})
import { bashExitCode } from './helpers/bash'
it("should return 0 for successful operation", () => {
const exitCode = bashExitCode(`
source ./utils/lists.sh
items=("apple" "banana")
list_contains_ref items "apple"
`)
expect(exitCode).toBe(0)
})
it("should return 1 when item not found", () => {
const exitCode = bashExitCode(`
source ./utils/lists.sh
items=("apple" "banana")
list_contains_ref items "cherry"
`)
expect(exitCode).toBe(1)
})
import { beforeEach, afterEach, it, expect } from 'vitest'
import { mkdtempSync, rmSync } from 'fs'
import { join } from 'path'
import { tmpdir } from 'os'
import { sourcedBash } from './helpers/bash'
let tempDir: string
beforeEach(() => {
tempDir = mkdtempSync(join(tmpdir(), 'test-'))
})
afterEach(() => {
rmSync(tempDir, { recursive: true, force: true })
})
it("should detect file exists", () => {
const testFile = join(tempDir, 'test.txt')
writeFileSync(testFile, 'content')
const result = sourcedBash('./utils/filesystem.sh', `
file_exists "${testFile}"
`)
expect(result).toBe('') // Success (exit 0)
})
# Test execution
pnpm test # Run all tests
pnpm test lists # Run specific test file (e.g., lists.test.ts)
pnpm test WIP # Run only WIP tests
pnpm test --grep -v WIP # Run all except WIP (regression check)
pnpm test:watch # Run in watch mode
pnpm test:watch WIP # Watch mode for WIP tests
pnpm test:ui # Run with Vitest UI
pnpm test:coverage # Run with coverage report
# Common patterns during development
pnpm test text # Test text utilities
pnpm test lists # Test list utilities
pnpm test --grep "trim" # Test functions matching pattern
Before considering tests complete, verify:
Before closing out a phase:
tests/WIP/tests/WIP/ directory removedEffective testing in this repo requires understanding what to test, how to test it, and when to use different testing approaches:
Hybrid Approach:
*.test.ts)*-demo.sh)tests/helpers/bash.ts to execute and test bash functions from TypeScriptFollow TDD principles: write tests first, implement to pass them, then refactor with confidence. Keep tests fast, focused, and independent.
For phase-based development, use the five-step workflow: SNAPSHOT → CREATE LOG → WRITE TESTS → IMPLEMENTATION → CLOSE OUT. This ensures comprehensive test coverage, prevents regressions, and maintains clear documentation of your progress.
When tests fail, understand why before fixing. Prioritize fixing bash implementation over changing tests, unless the test itself was wrong.