# Debug And Test

> |

- **Type:** Skill
- **Install:** `agentstack add skill-hec-ovi-agentickit-debug-and-test`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hec-ovi](https://agentstack.voostack.com/s/hec-ovi)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hec-ovi](https://github.com/hec-ovi)
- **Source:** https://github.com/hec-ovi/agentickit/tree/main/.pilot/skills/debug-and-test

## Install

```sh
agentstack add skill-hec-ovi-agentickit-debug-and-test
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Debug and Test

## Contract

By the end of this skill the agent can:

- Build the package locally (`pnpm --filter @hec-ovi/agentickit build`).
- Run the test suite (`pnpm --filter @hec-ovi/agentickit test`).
- Run the todo example against the local package
  (`pnpm --filter @agentickit-examples/todo dev`).
- Diagnose the most common failure modes with a specific fix.

## Iron Law: reproduce before you change

Never attempt a fix without first seeing the failure locally. The pnpm
workspace links `agentickit` from `packages/agentickit/dist/` into the
example. If `dist/` is stale, the example runs last build's behavior
and your "fix" targets the wrong tree. **`pnpm --filter @hec-ovi/agentickit build`
before every reproduction, no exceptions.**

## Phases

### Phase 1: understand the layout

```
agentickit/
  package.json              # workspace root (declares pnpm workspaces)
  pnpm-workspace.yaml       # workspace globs
  packages/
    agentickit/             # the published package
      src/
        index.ts            # public client exports
        hooks/              # usePilotState, usePilotAction, usePilotForm
        components/         # , 
        server/             # createPilotHandler
        protocol/           # .pilot/ loader
      dist/                 # tsup output, regenerated on build
      tsup.config.ts
      vitest.config.ts
  examples/
    todo/                   # consumes agentickit via the workspace link
      app/
        api/pilot/route.ts
        page.tsx
```

Always use absolute paths from repo root when editing. Never `cd`.

### Phase 2: build the package

```bash
cd /home/hector/workspace/test-task/agentickit
pnpm --filter @hec-ovi/agentickit build
```

Runs `tsup` (config at `packages/agentickit/tsup.config.ts`), producing
three entry points under `dist/`: `index`, `server`, `protocol`. Each
ships ESM + CJS + `.d.ts`.

If the build fails with a TypeScript error, the `src/` tree has a real
type bug. Fix the source, not the build config.

### Phase 3: run the tests

```bash
pnpm --filter @hec-ovi/agentickit test
```

Runs Vitest once (`vitest run` in `package.json` scripts). Happy-DOM
environment. Fast; no external network.

For watch mode during iteration:

```bash
pnpm --filter @hec-ovi/agentickit test:watch
```

### Phase 4: run the example

```bash
pnpm --filter @agentickit-examples/todo dev
```

Starts Next.js on port 3000 against a fresh build of `agentickit`.

Before running, set a provider env var in `examples/todo/.env.local`:

```
OPENROUTER_API_KEY=sk-or-v1-...
```

(See `skills/choose-provider/SKILL.md` for the supported keys.)

The example's route at `examples/todo/app/api/pilot/route.ts` omits
`model`; it relies on auto-detection. See
`skills/install-and-setup/SKILL.md` for the auto-detect priority list.

### Phase 5: rebuild-and-retry after source edits

The example imports from the built `dist/` via the workspace link, so:

```bash
pnpm --filter @hec-ovi/agentickit build && pnpm --filter @agentickit-examples/todo dev
```

For an iteration loop:

```bash
pnpm --filter @hec-ovi/agentickit dev   # tsup --watch in one terminal
pnpm --filter @agentickit-examples/todo dev   # next dev in another
```

### Phase 6: common failure modes

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| Example imports but types are `any` | Stale `dist/` | `pnpm --filter @hec-ovi/agentickit build` |
| "no model configured" on first message | No env var in example `.env.local` | Set `OPENROUTER_API_KEY` (or another supported key) |
| 500 `MODULE_NOT_FOUND` for `@ai-sdk/xxx` | Env var set but adapter not installed in the example | `cd examples/todo && npm install @ai-sdk/` |
| Sidebar renders but no messages appear | `` outside `` tree | Move sidebar inside the provider |
| `usePilotAction` warning in console, no tool call | Hook called outside `` | Move the hook into a descendant of the provider |
| Manifest fetch fails silently | `.pilot/` folder not under `public/` | Move to `public/pilot/` so Next.js serves it |
| Tool call stalls the loop | Registered handler throws before `addToolOutput` | Catch in handler, return `{ ok: false, reason }` |
| Two tool calls with same name execute twice | Two components registered the same `name` | Pick unique names; check dev-mode warning |

### Phase 7: where to look when the code disagrees with the docs

Priority order, always:

1. `packages/agentickit/src/`: the source.
2. Tests under the same tree (if present): executable contract.
3. `README.md` and `packages/agentickit/README.md`: consumer-facing narrative.
4. `.pilot/skills/*`: agent procedures.

If a `.pilot/skill` disagrees with (1) or (2), the skill is out of date.
Fix the skill. Report the drift in your final message.

## Anti-Patterns

- Editing `dist/` directly. It's regenerated on every build.
- Using `npm install` at the workspace root. Use `pnpm install`; this
  is a pnpm workspace and `npm install` will fight the lockfile.
- Bypassing the workspace link by installing `agentickit` from npm into
  the example. The local source becomes invisible to the running example;
  you'll chase ghosts.
- Running tests against the published package instead of `src/`. Vitest
  reads from `src/` via the config at `packages/agentickit/vitest.config.ts`;
  there's no reason to publish-and-retry.

## Output Format

After a debugging session, report:

- The exact command sequence that reproduced the failure.
- The file and line number of the root cause.
- The fix (as a diff summary, not a full patch; the caller can read
  the file).
- Any drift between docs and code you noticed along the way.

## Tools Used

- `pnpm --filter @hec-ovi/agentickit build` / `test` / `dev`.
- `pnpm --filter @agentickit-examples/todo dev`.
- Read source files under `packages/agentickit/src/`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hec-ovi](https://github.com/hec-ovi)
- **Source:** [hec-ovi/agentickit](https://github.com/hec-ovi/agentickit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hec-ovi-agentickit-debug-and-test
- Seller: https://agentstack.voostack.com/s/hec-ovi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.