Agent guide#

This file is mirrored to Dosu (page 6e69465b-8afd-4278-92cf-5aa2d416b6e2, deployment "Mag Stacker MCP Server") so it's queryable via dosu ask / the Dosu MCP. The page is a static snapshot — after editing this file, refresh it: dosu docs update 6e69465b-8afd-4278-92cf-5aa2d416b6e2 --body-file ./AGENTS.md.

Canonical project docs (read these first)#

The authoritative descriptions of the stack, structure, and product live in the
Kiro steering docs. Every agent — Kiro or otherwise — should treat them as the
source of truth; this file only adds the agent boundaries and the few
operational details not covered there.

• .kiro/steering/tech.md — the stack, the non-default tooling (Bun, Biome,
  taplo, mise), and the full just command table (dev, lint, format,
  typecheck, test, build, db, ci-check).
• .kiro/steering/structure.md — repo layout and the layered server-side
  flow (route pages → server actions → pure domain validators → auth/visibility
  → db), plus the feature-slice conventions for adding code.
• .kiro/steering/product.md — what MagStacker is, who it's for, the
  owner-scoping / grant-sharing core rules, and the "Machined Console" design
  identity.
• CONCEPTS.md (repo root) — domain glossary: entities, sharing/visibility
  model, classification & labeling, derived values. Canonical names for domain
  concepts.
• docs/solutions/ — solutions to past problems (bugs + knowledge),
  organized by category with YAML frontmatter (title, category, module,
  problem_type, component, severity, tags); relevant when implementing
  or debugging in a documented area.

Stack at a glance (see .kiro/steering/tech.md for detail): TypeScript ·
Next.js 16 (App Router) · React 19 · Bun · Biome (not ESLint/Prettier) ·
Tailwind v4 · Postgres + Drizzle (pg Pool) · Better Auth · Docker · multi-user
owner-scoped inventory + grant-based sharing (all shipped).

Operational details (not in steering)#

• Hooks: never wire ESLint/Prettier/pnpm hooks here — use bun biome check, bun biome format, bun tsc --noEmit.
• Auth specifics: disableSignUp: true — accounts are created server-side via auth.api.createUser (see scripts/seed-admin.ts); admin plugin; DB-stored rate limit (/sign-in/email = 5/60s). Session cookie: better-auth.session_token.
• BETTER_AUTH_URL must equal the request origin or Better Auth returns 403 "Invalid origin". mise.toml (env_cache=true, _.file=['.env','.env.local']) injects env vars stickily (default :3000) — override explicitly when serving on another port.
• DATABASE_URL is read by requireDatabaseUrl() (src/db/client.ts) and is not in .env.example — supply it. User delete CASCADEs children.
• Testcontainers detail: bunfig.toml preloads src/test-support/preload.ts, which starts a migrated ephemeral Postgres and exports DATABASE_URL before any test module loads; the pinned image lives in src/test-support/postgres-image.ts (single source, also read by CI). Never reintroduce a process.env.DATABASE_URL ? describe : describe.skip gate — that idiom silently skipped the whole integration suite whenever the variable was unset. Reuse src/test-support/factories.ts, and give a test its own owner rather than asserting over rows earlier tests left behind.
• MUST-PASS PRE-COMMIT GATE: You MUST run just ci-check and ensure it passes before every commit. Do not commit — for any reason — while just ci-check is failing. No --no-verify, no skipping, no "I'll fix it in a follow-up." A red just ci-check blocks the commit.

Workflow & boundaries#

• Git workflow: feature branches + PRs only — never commit directly to main. Conventional Commits, semver. For agent tasks, prefer an isolated worktree: git worktree add -b ai/<task> .worktrees/<task> (check git worktree list first; merge and clean up when done).
• PRs squash-merge, so the PR title and body ARE the commit message. This repo merges with squash_title: PR_TITLE and squash_msg: PR_BODY; every branch commit message is discarded at merge. Therefore:
  • The PR title MUST be a valid Conventional Commit subject — <type>[(<scope>)][!]: <description> — since it becomes the subject line on main verbatim. The scope is optional (docs: … is as valid as docs(agents): …).
  • A breaking change MUST be marked on the PR itself: a ! before the colon in the PR title and a BREAKING CHANGE: <what breaks> footer in the PR body. The ! is valid with or without a scope — feat!: … and feat(scope)!: … both work. Marking it only on a branch commit does not work — the marker is destroyed by the squash. A prose "Breaking change" heading in the body is not the footer and does not count.
  • Releases are cut by pushing a v*.*.* tag by hand; nothing parses commits to compute the bump, so these markers are the only record of what the next version should be. A merged PR carrying a breaking change means the next tag is a major.
• Releases/deploy: container image ghcr.io/unclesp1d3r/mag_stacker via GitHub Actions; project docs at https://unclesp1d3r.github.io/mag_stacker/. Style/structure reference repo: https://github.com/EvilBit-Labs/hash_hive.
• Do without asking: create/delete/rename files, rewrite sections, change dependencies, modify DB schema or Docker config, update docs.
• Ask first: anything touching secrets/credentials, auth logic changes, deleting failing tests.
• Never: skip or disable tests "temporarily".
• Testing preference: favor E2E and integration tests over mocks when possible.

This is NOT the Next.js you know#

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.