domain-cli

name	domain-cli
description	Use when changing, extending, testing, or reviewing the Bun-backed Paw CLI package and its generated agent skills.
paths	["packages/paw-cli/**","packages/ci/skill-gen/**","scripts/paw","justfile","specs/004-effect-paw-cli/**","specs/005-effect-cli-boundaries/**","specs/006-claude-agent-session-engine/**"]

domain-cli

Use this skill before changing the Paw CLI package. The CLI is a standalone Bun-first Effect v4 package at packages/paw-cli; feature-owned commands are added only when the owning feature needs them.

Before Editing

• Load code-quality, domain-cli, and domain-effect before writing or reviewing CLI code.
• Check backend/vendor/effect-smol for any Effect v4 API you are about to use; do not infer current APIs from older Effect docs or memory.
• Treat Bun runtime services, Effect v4 idioms, schema-backed boundaries, and contract-only docstrings as first-pass requirements, not cleanup work after scaffolding.

Package Shape

packages/paw-cli/
|-- src/
|   |-- Main.ts
|   |-- Cli.ts
|   |-- Commands.ts
|   |-- Helpers/
|   |-- Infrastructure/
|   |-- Modules/<Name>/
|   `-- Skills/Fragments.ts
`-- test/
    |-- unit/
    |-- integration/
    `-- fixtures/

Current Command Surface

Command	Aliases	Summary
paw doctor	-	Check local Paw CLI readiness
paw context	whoami	Print the active CLI context without secrets
paw completions <shell>	-	Generate shell completions

Rules

• Keep effect, @effect/platform-bun, and @effect/vitest on the same latest verified v4 beta in packages/paw-cli/package.json.
• Use Bun runtime services for CLI execution; do not add @effect/platform-node or node:* imports to packages/paw-cli/src.
• Keep shared runtime services under src/Infrastructure/; feature modules should not import shared services from each other.
• Keep command modules under src/Modules/<Name>/ with Command.ts, plus Domain.ts and focused helpers only when the command needs them.
• Register command modules in src/Commands.ts; do not create placeholder command groups for future product ideas.
• Feature-owned CLI commands must target real feature contracts. For 006 provider sessions, use paw sessions ... against session/Workspace/provider bindings; do not add paw agents ... until a real agent-management registry exists.
• CLI commands that call backend-ts should use public HTTP/RPC clients from api-core/rpc-core; normal CLI commands must not import provider adapters or harness internals.
• Keep command metadata next to the command implementation and make generated skills read from that metadata.
• Define schemas for external input and public output before adding ad hoc parsing or rendering code.
• Use Schema.TaggedErrorClass from src/Helpers/Errors.ts for expected public CLI failures and map failures to the public exit-code contract.
• Use src/Helpers/Output.ts for human, json, and plain rendering; JSON output must encode through a declared Effect Schema before stdout.
• Prefer JSON Schema documents from Effect Schema.toJsonSchemaDocument for CLI contracts; OpenAPI belongs to HttpApi, not this CLI package.
• Use src/Helpers/Config.ts for profile, state-root, TOML, and no-secret config behavior; environment-backed settings go through Effect Config descriptors and deterministic ConfigProvider tests.
• Preserve explicit Paw config precedence and source labels: flags, env, project TOML, profile TOML, user TOML, defaults.
• Treat first-slice helpers like InputSource.ts, writeProfileConfig(), and unused error tags as tested policy helpers until a feature-owned command needs them.
• Use @effect/vitest for tests that directly exercise Effect values or services; plain Vitest is fine for process integration and pure synchronous assertions.
• Remove old Python CLI references instead of bridging, shelling out, or maintaining compatibility shims.

Add A Command Group

1. Create packages/paw-cli/src/Modules/<Name>/Command.ts and a Domain.ts when the command needs domain types or services.
2. Define command metadata with name, summary, description, owner, flags, examples, output modes, structured output contracts, and exit codes.
3. Define schemas for external input, public JSON output, and expected errors before command rendering or parsing code.
4. Build the command with effect/unstable/cli primitives and Effect handlers.
5. Register the module in packages/paw-cli/src/Commands.ts.
6. Add unit and integration tests under packages/paw-cli/test/, including ConfigProvider tests for environment-backed settings.
7. Run the CLI checks and regenerate skills.

Skill Generation

packages/paw-cli/src/Skills/Fragments.ts exports dynamic fragments for paw and domain-cli. packages/ci/skill-gen loads those fragments and merges them with normal //<skill-gen> source markers, so generated skills stay aligned with the command registry.

bun run skill-gen:generate
bun run skill-gen:check
bun run skill-gen:e2e-test

Required Checks

bun run --filter @pawrrtal/cli typecheck
bun run --filter @pawrrtal/cli test
bun run --filter @pawrrtal/cli check
bun run skill-gen:check
just paw-cli-check