@aethrekh/pisces-cli

Workspace lifecycle commands for Pi Coding Agent. Registers the /pisces command with five flags: --activate, --deactivate, --status, --setup, and --doctor.

This package is the user-facing complement to @aethrekh/pisces-core. Core owns skill gating and evaluation; CLI owns everything a learner types to manage their workspace.

---

Installation

Install alongside pisces-core — both are needed for the full experience:

pi install npm:@aethrekh/pisces-core
pi install npm:@aethrekh/pisces-cli

---

Commands

All commands are accessed via /pisces <flag> inside a Pi session.

/pisces --status

Shows the current workspace state. No side effects.

When inactive:

Pisces  ✗ Not Active
────────────────────
No .pisces workspace marker found.
(searched up from /Users/you/projects/lab1)

Next step
─────────
Navigate to your workspace folder, then run:

  /pisces --activate   Create workspace here
  /pisces --setup      Guided setup (recommended)

When active:

Pisces  ✓ Active
────────────────────
Workspace   /Users/you/my-project
             (2 levels inside)

Skills:
  /attempt

Running /pisces with no flag is equivalent to --status.

---

/pisces --activate

Creates a .pisces marker file in the current directory and reloads Pi so skills become available immediately.

Before creating the marker, Pisces walks up the directory tree looking for a directory whose name matches a workspace root pattern (university, uni, college, school, cs, fall2025, spring2025, etc.). If a better root is found, it is offered as an alternative:

Better root found: /Users/you/university
Activate there instead of /Users/you/university/fall2025/CS301? [y/N]

Choosing y creates .pisces at the suggested root so all subdirectories inherit workspace activation. Choosing n (or entering nothing) creates it at the current directory.

After activation Pi reloads automatically.

---

/pisces --deactivate

Removes the .pisces marker from the nearest workspace root above the current directory.

Deactivate workspace at /Users/you/my-project? [y/N]

Requires confirmation before deleting. After deactivation Pi reloads and skills are suppressed.

---

/pisces --setup

Guided first-time setup. Walks through:

1. Prerequisites check — Node.js version ≥ 18, pisces-core installed.
2. Workspace activation — if not already active, offers to run --activate.
3. Post-activation — confirms setup is complete and shows the --status output.

Recommended for first-time users. Equivalent to running --doctor + --activate with guided prompts.

---

/pisces --doctor

Health check. Reports on:

Check	Pass condition
Pisces CLI loaded	Extension registered successfully
Node.js version	>= 18.0.0
Workspace active	.pisces found at or above cwd
Stale system prompt	~/.pi/agent/APPEND_SYSTEM.md exists and is current

Example output:

Pisces Doctor
─────────────────────────────
✓  Pisces CLI loaded
✓  Node.js v20.11.0 (≥ 18 required)
✗  Workspace not active
     Run /pisces --activate to enable skills here.
✓  System prompt installed

---

Workspace detection

The CLI reads workspace state from pisces-core's syncWorkspaceState() and findWorkspace() utilities. On resources_discover, the CLI syncs the state cache so all command handlers see a consistent view.

Detection algorithm:

1. Start from Pi's working directory (cwd from the resources_discover event).
2. Walk up the directory tree, checking for a .pisces file at each level.
3. Stop at the user's home directory or after 15 levels, whichever comes first.
4. Cache the result for the session — mid-session cd does not re-trigger detection.

---

Inactive workspace nudge

When Pi starts in a directory without .pisces, the CLI fires a session_start notification:

✓ Pisces is installed  ·  ✗ Not active here

Skills are off until you activate a workspace.

  /pisces --activate   Mark this directory as your workspace
  /pisces --setup      Guided first-time setup (recommended)
  /pisces --status     See what Pisces detects

The status bar also updates to show 🐠 Pisces · not active in a muted style.

If the workspace is active, the nudge is suppressed entirely — no noise in active sessions.

---

Skill redirect stubs

The CLI registers stub commands for every Pisces skill name (attempt). This means learners get a helpful redirect rather than Pi's "unknown command" error when they try to use a skill in an inactive workspace:

🐠 Pisces: /attempt is available but the workspace isn't active here.

  /pisces --activate   Enable skills in this directory
  /pisces --setup      Guided setup (recommended for first time)

When the workspace is active, the stub redirects to /skill:attempt (the proper Pi skill invocation path).

---

Package scripts

pnpm build           # Compile src/ → dist/
pnpm test            # Run Jest test suite
pnpm test:coverage   # With coverage (70% branch / 80% line thresholds)
pnpm typecheck       # Type-check without emit
pnpm lint            # ESLint over src/
pnpm check           # typecheck + lint + test:coverage (CI gate)

---

Architecture

packages/cli/
├── pi-package.yaml           # Pi runtime manifest (triggers: resources_discover, session_start)
└── src/
    ├── index.ts              # Pi extension factory — registers /pisces and skill stubs
    ├── commands/
    │   ├── activate.ts       # --activate: create .pisces, suggest parent root, reload
    │   ├── deactivate.ts     # --deactivate: remove .pisces with confirmation, reload
    │   ├── status.ts         # --status: show workspace state and available skills
    │   ├── setup.ts          # --setup: guided first-time walkthrough
    │   └── doctor.ts         # --doctor: health checks with pass/fail output
    └── lib/
        ├── suggest-root.ts   # Walk up for university-named ancestors
        └── ui.ts             # Shared UI primitives (SEP, row, skillsList)

---

Peer dependencies

Package	Role
@earendil-works/pi-coding-agent	Pi runtime types (ExtensionAPI, ExtensionCommandContext)
@aethrekh/pisces-core	Workspace detection (findWorkspace, syncWorkspaceState, getWorkspaceState)

---

License

MIT