Lucas WintherandClaude Opus 5.5
be04fab098
Captures the owner's requirements and decisions from the planning conversation, current branch/worktree state, open tasks 17-19, pending owner decisions and the controller's rulings so a new agent can resume. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
59 lines
3.2 KiB
Markdown
59 lines
3.2 KiB
Markdown
# 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 <noreply@anthropic.com>`
|
|
|
|
## 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:postgres@127.0.0.1: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.
|