# Tuckmark Agent Import Source

> Exercise private order-derived Tuckmark agent imports from the current source tree without accidentally invoking a globally installed release CLI. Use while developing or validating a cloned Tuckmark checkout.

- Skill: `ivanli-cn/tuckmark-agent-import-source` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ivanli-cn/tuckmark-agent-import-source`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivanli-cn/tuckmark-agent-import-source/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ivanli-cn (https://skillmd.com/u/ivanli-cn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ivanli-cn/tuckmark-agent-import-source

---


# Tuckmark Agent Import Source

Use this skill inside a Tuckmark source checkout. It deliberately invokes the active worktree source CLI, never a globally installed `tuckmark` binary.

## Source Guard

Resolve the checkout before every command:

```bash
REPO_ROOT="$(git rev-parse --show-toplevel)"
test -f "$REPO_ROOT/packages/cli/src/index.ts"
```

Use this command prefix:

```bash
bun tsx --tsconfig "$REPO_ROOT/packages/cli/tsconfig.typecheck.json" "$REPO_ROOT/packages/cli/src/index.ts"
```

Do not substitute `tuckmark` while validating source changes. Run
`bun run dev:data:prepare` when representative local data is needed; an existing
valid worktree copy is reused. Otherwise use the empty isolated directory
created by `bun run dev:preview`. Never point development DEVD at the formal
user data directory.

## Workflow

1. Follow the privacy, identity, and browser boundaries in `tuckmark-agent-import`. Never add a real order export to a fixture, test, screenshot, or commit.
2. Start the worktree's named DEVD instance through `bun run dev:preview`, then
   query its catalog and inventory with the source CLI. The default instance is
   derived from the worktree path and printed at startup. Native commands use
   IPC; the CLI never reads the directory:

   ```bash
   bun tsx --tsconfig "$REPO_ROOT/packages/cli/tsconfig.typecheck.json" "$REPO_ROOT/packages/cli/src/index.ts" \
     agent-import catalog --instance "$DEVD_INSTANCE"
   ```

3. Use a mock `tuckmark.agent-import.v1` proposal for automated validation. Let the Agent decide `new` versus `restock`; use exact inventory IDs for restocks and set non-blocking `needsAttention` when evidence is incomplete. In each new-material payload, use `description` for the concise overview and one `deviceDetails` Markdown string for factual technical detail. Do not replace it with an Agent-invented structured object.
4. Create and drive a session with the same source command prefix:

   ```bash
   bun tsx --tsconfig "$REPO_ROOT/packages/cli/tsconfig.typecheck.json" "$REPO_ROOT/packages/cli/src/index.ts" \
     agent-import create --file /tmp/mock-proposal.json --instance "$DEVD_INSTANCE" --no-open
   bun tsx --tsconfig "$REPO_ROOT/packages/cli/tsconfig.typecheck.json" "$REPO_ROOT/packages/cli/src/index.ts" \
     agent-import wait --session <session-id> --instance "$DEVD_INSTANCE"
   ```

5. When the user changes a new-material template, read the event field contract, produce fresh values, and fulfill the event's exact revision. Do not overwrite a later user edit or select templates for an existing restock.
6. Keep confirmation user-owned. Do not call the confirm API from an Agent test workflow.

Template lifecycle validation uses the same instance boundary:

```bash
... template list --instance "$DEVD_INSTANCE"
... template update --id <template-id> --instance "$DEVD_INSTANCE" --recommended-use "<text>"
```

Complete package imports create saved versions. Metadata patches preserve the
saved-version count, and stale revisions must be re-read rather than replayed.

## Focused Validation

```bash
bun run --filter @tuckmark/inventory test
bun run --filter @tuckmark/server test
bun run --filter @tuckmark/cli test
bun run --filter @tuckmark/web test
```