---
name: implement
description: Disciplined implementation in pi-agent-dashboard. Pairs (a) the 3-component rebuild matrix — extension→reload, server→restart, client→build+restart, openspec-apply→full rebuild — with (b) the project's code discipline rules (TDD, simplicity-first, surgical changes). Use when starting to write code, after editing src/extension|src/server|src/client, when unsure what to rebuild after a change, or before committing. Loads on triggers like "I changed the bridge", "rebuild and restart", "implement X", "after edit", "TDD this", "how do I land this change". Skip for trivial edits.
---

# Implement

Two halves: **how to write the change** (discipline) and **how to land it in the running system** (rebuild + restart).

The skill exists because both halves are easy to get wrong:
- Agents over-engineer simple changes when they're not anchored.
- Agents rebuild the wrong component (or worse, all components when they didn't need to) after editing files.

## Quick decision tree

```
        Did you edit code?
                │
       ┌────────┴────────┐
       │                 │
       ▼                 ▼
   src/extension/    src/server/ or src/shared/
       │                 │
       ▼                 ▼
   npm run reload    curl -X POST localhost:8000/api/restart
                     (no build step — jiti runs TS directly)

   src/client/ (dev mode)   →  nothing, Vite HMR
   src/client/ (prod mode)  →  npm run build && restart
   Multi-component / openspec  →  npx tsx ./scripts/full-rebuild.ts
```

Quick check current mode:
```bash
npx tsx ./scripts/check-mode.ts           # prints "dev" or "production"
```

Restart server (preserves mode unless overridden):
```bash
npx tsx ./scripts/restart-server.ts             # graceful restart, keeps mode
npx tsx ./scripts/restart-server.ts --dev       # force dev mode
npx tsx ./scripts/restart-server.ts --prod      # force production mode
```

Full rebuild (after `openspec-apply` or multi-component change):
```bash
npx tsx ./scripts/full-rebuild.ts
```

> `full-rebuild.ts` **deploys the checked-out dev version to the local running instance** (build + restart + reload). It is NOT a feature-implementation step — worktree / Docker-isolated feature work does not run it. The code-review gate is separate (below).
>
> Scripts are TypeScript (cross-platform). All invocations use `npx tsx` so they work identically on Linux, macOS, and Windows. `tsx` is already a project dep.

Full matrix with edge cases (dev-mode fallback, fault-tolerant restart, single-restart-path rule) lives in [`references/rebuild-matrix.md`](references/rebuild-matrix.md).

## Review — two tiers (inner loop vs ship gate)

Review is split by moment. The inner loop runs on an **unlimited** engine every non-trivial change; the rate-limited cloud gate is **reserved for the PR**.

**Inner loop (during dev, before commit) — `review-code` discipline.** After writing a non-trivial change, review the diff with the **`review-code`** skill (eng-disciplines): engine-agnostic — inspect design→correctness→complexity→tests→naming→security, emit labelled findings, fix `issue(blocking)` surgically, re-review until no blocking finding remains, then commit. Runs on a model engine — no cloud quota spent, so run it freely per change.

**Ship gate (opt-in, PR-time) — CodeRabbit.** Reserved for the pull request so its quota is unspent during dev. **Worktree-safe and server-independent** — no build, no restart:

```bash
RUN_CR_REVIEW=1 npx tsx ./scripts/review-changes.ts             # opt in (uncommitted)
npx tsx ./scripts/review-changes.ts --ship -t committed --base main
npx tsx ./scripts/review-changes.ts                            # default: skips → use review-code
```

**Warn-and-continue, never blocks**: CodeRabbit is cloud rate-limited; on limit / missing CLI / auth failure it prints "deferred to a later cycle" and exits 0. Fix Critical/Warning findings, then commit. See the **`code-review`** skill for the CodeRabbit severity triage + fix loop.

> openspec-apply: the `review-code` inner-loop pass runs after each task's code is written; the CodeRabbit gate is opt-in at ship (ship-change owns the PR-time review). Both run in the worktree without touching the main server.

## The discipline — write less code, write the right code

The full code-discipline reference lives in [`references/code-discipline.md`](references/code-discipline.md). It expands `AGENTS.md` "Code Instructions" with concrete patterns, anti-patterns, and examples. Headline rules:

| Rule | One-liner |
|------|-----------|
| 1. Think before coding | State assumptions. Ask via `ask_user` when unclear. Never speculate about unread files. Confirm major plans. |
| 2. Simplicity first | Minimum code that solves the problem. No speculative abstractions. "Would a senior engineer say this is overcomplicated?" |
| 3. Surgical changes | Touch only what you must. Don't "improve" adjacent code. Match existing style. Every changed line traces to the request. |
| 4. Goal-driven (TDD) | Write/update tests first → verify they fail → make them pass. Captures intent before code exists. |
| 5. Communication | High-level summary per change. Use `ask_user` (not plain text) when you need a choice. |

These rules also live in `AGENTS.md` so they're always in context. This skill loads on implementation triggers so they get foregrounded when the agent is about to write code.

## Running tests — tee→grep, never rerun

Never rerun `npm test` to inspect errors. Pipe once, grep many times:

```bash
npm test 2>&1 | tee /tmp/pi-test.log         # run once, capture
grep -nE 'FAIL|Error|✗|✘' /tmp/pi-test.log    # find failures
grep -n -A 20 'FAIL ' /tmp/pi-test.log         # failure + context
```

For deeper test triage (per-package vitest configs, watch mode, coverage), see the **`debug-dashboard`** skill — its `references/test-failure-triage.md`.

## When the running system misbehaves

Implementing != debugging. If the dashboard starts misbehaving (server hung, bridge won't connect, blank page, tests failing for non-obvious reasons), switch to the **`debug-dashboard`** skill.

If your change went red in CI after `git push`, switch to the **`ci-troubleshoot`** skill.

## Related skills

- `openspec-new-change` — capture a non-trivial change as an OpenSpec proposal first
- `openspec-apply-change` — implement tasks from an OpenSpec change with the artifact workflow
- `openspec-verify-change` — validate implementation matches artifacts before archiving
- `review-code` — inner-loop diff review discipline (unlimited engine), before commit
- `code-review` — the opt-in CodeRabbit ship gate (PR-time)
- `debug-dashboard` — diagnose a misbehaving running system
- `ci-troubleshoot` — diagnose failed CI runs after push
- `release-cut` — when the change is ready to ship as a versioned release