ninthwave: Instructions file for Claude Code

ninthwave

Parallel AI coding orchestration. TypeScript + Bun CLI.

Required reading: ETHOS.md -- core principles and hard boundaries.

Development

task setup            # install git hooks (run once after cloning)
bun run test          # run the full CI-equivalent suite (unit + system)
bun run test:unit     # run unit/contract/scenario/smoke tests only (fast, excludes test/system/)
bun run test:system   # run system integration tests only (test/system/, slow)
bun run test:pre-commit  # run the hook-equivalent safety gate
bun run core/cli.ts   # run CLI directly

No build step -- Bun executes TypeScript directly. Changes take effect immediately.

Architecture

• core/cli.ts -- CLI entry point and command dispatcher
• core/commands/ -- one file per command (list, launch, clean, watch, init, etc.)
• core/commands/orchestrate.ts -- nw orchestration event loop with TUI mode (interactive) and JSON mode (--json for piping/CI)
• core/parser.ts -- reads .ninthwave/work/ directory and domain normalization
• core/status-render.ts -- shared status table rendering for ninthwave status --watch and the daemon TUI
• skills/ -- SKILL.md files for AI tool integration (/decompose, etc.)
• agents/implementer.md -- implementation agent prompt (copied to all tool directories by init)
• core/commands/init.ts -- project setup command (seeds config and managed tool copies)

Conventions

• Filesystem boundary: ninthwave operates within the project directory and ~/.ninthwave/ only. It does not write to ~/.copilot/, ~/.claude/, ~/.config/, or any other tool-specific user config. If a tool requires external setup, document it -- don't automate it.
• Name casing: use Ninthwave when referring to the product in prose. Use lowercase only for commands, package names, repo names, and filesystem paths such as nw, ninthwave status, ninthwave-io/tap/ninthwave, and .ninthwave/.
• External project privacy: do not name external projects in durable artifacts such as work items, commit messages, PR titles, PR bodies, friction logs, or decision logs unless the project is public. For private projects, describe them generically.
• Comments and test names describe behavior, not the work that produced them. Default to no comment; only add one when the WHY is non-obvious (a hidden constraint, a workaround for a specific bug, behavior that would surprise a reader). Comments must not reference the current task, work item, round of review, fix, caller, or ticket -- those rot the moment the work item closes and belong in the PR description, commit message, or .ninthwave/ logs instead. Test names (describe, it, test titles, and test filenames) describe the behavior under test, not the work item that introduced the test. Work item IDs (M-MCX-12, H-MCX-345, round-3, [CHML]-<feature_code>-<seq>) belong in PR title/body, commit subject/body, branch name, and .ninthwave/ files -- never in source code, code comments, or test names.
• Conventional commits: feat:, fix:, refactor:, test:, docs:, chore:
• Tests live in test/ using bun's native test runner (vitest-compatible API via import { describe, it, expect, vi } from "vitest")
• Mock isolation: bun test does not isolate vi.mock between test files -- mocks leak across files and break unrelated tests. Prefer dependency injection (pass collaborators as function arguments) over vi.mock. Only use vi.mock when the mocked module is not imported by any other test file. When in doubt, inject.
• Always run bun run test for the full suite. If you invoke Bun directly, use bun test test/ (scoped to test/) to avoid picking up tests from .ninthwave/.worktrees/ during orchestration.
• Convention over configuration -- sensible defaults, minimal config files
• VISION.md is forward-looking only. Do not add completion markers (*(complete)*, strikethrough ~~done~~, (Shipped.), Decomposed →) to VISION.md. Completed work belongs in CHANGELOG.md. Vision workers should remove or collapse shipped sections, not annotate them.