STTracker/docs/plans/001-phase1-sdd/common-implementer.md

Common instructions for every STTracker implementer (binding)

You implement one task of the STTracker Phase 1 plan. STTracker is a Bun 1.3 + TypeScript self-hosted media tracker.

Read first

1. Your task brief, whose path is given in your dispatch. It is your requirements; use its exact values verbatim.
2. AGENTS.md at the repo root (rules).
3. The "Global constraints" section of docs/plans/001-phase1-own-your-data.md. Read only that section, not the whole plan.
4. Only the spec sections your brief cites: docs/specs/001-sttracker-v1-design.md.

Workspace

• If you were started in a git worktree, work there. First run bun install --frozen-lockfile. Never modify package.json or bun.lock: every approved dependency is already installed. If you truly need another one, report NEEDS_CONTEXT.
• If not in a worktree, work in /home/user/STTracker on branch feat/phase1.
• Never commit to main. Commit messages use Conventional Commits and end with the line: Co-Authored-By: Claude Opus 5.5 <[email protected]>

Facts from earlier tasks

• @sttracker/db/db: createDb(url) → Db { k: Kysely<Database>; dialect: "sqlite"|"postgres"; close() }.
• @sttracker/db/ids: newId() (UUIDv7) and nowIso().
• @sttracker/db/json: toJson() and fromJson(s, fallback).
• @sttracker/db/migrate: migrateToLatest(db).
• @sttracker/db/testing: forEachDialect(name, getDb => …) gives each test a fresh, migrated DB.
• @sttracker/core/errors: AuthError(code), ValidationError(field, reason) (code "validation"), CryptoError, ImportError(code), NotFoundError(what) (code "not_found").
• Kysely 0.29: import Migration/Migrator from kysely/migration.
• Inside a transaction always use the tx handle, never db.k. SQLite runs on one connection behind a mutex, so calling db.k inside a transaction deadlocks.
• Packages import each other by path (@sttracker/core/entries). There are no barrel index.ts files.

Testing

• TDD: failing test first, watch it fail (RED), minimal code, watch it pass (GREEN).
• DB tests must pass on both databases:
  • bun test <path> (SQLite);
  • TEST_POSTGRES_URL=postgres://postgres:[email protected]:55432/postgres bun test <path> (Postgres; the server is running).
• Tests never touch the network.
• bun run typecheck must be clean before your final commit.
• Output must be pristine (no stray warnings or logs).

You do not dispatch subagents

Do all the work yourself. Never spawn helpers or reviewers. Review happens after you report.

If stuck

Report BLOCKED or NEEDS_CONTEXT with specifics. Bad work is worse than no work. If something in the brief contradicts these instructions or the spec, ask rather than guess.

Report

Write the full report to the report path given in your dispatch. Include:

• what you built;
• files changed;
• TDD evidence: the RED command and output, and the GREEN command and output, on both DBs where relevant;
• typecheck output;
• self-review findings;
• concerns.

Your final reply must be ONLY (under 15 lines):

• Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT;
• commits (short SHA + subject);
• the branch name you committed on;
• a one-line test summary;
• concerns;
• the report path.