8000 inkie-deck/AGENTS.md at main · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
63 lines (54 loc) · 3.45 KB

AGENTS.md

File metadata and controls

63 lines (54 loc) · 3.45 KB

inkie-deck

A local-first control room for a team of AI agents: a chat-style inbox, decision and action cards, projects and drafts, backed by a file-based message protocol. This file is the short orientation for AI coding agents. The rules live in one place each, so read these before your first change: CONTRIBUTING.md (rules), DEVELOPMENT.md (workflow), README.md and INSTALL.md (setup), Testing and evals and UI components.

Map

  • packages/deck: the React Router web app, with vitest unit tests and Playwright journeys.
  • packages/base: the agent protocol (packages/base/docs/protocol.md), persona templates and the inbox CLI. It never imports from packages/deck; pnpm check:boundaries enforces that.
  • .specs/<issue-number>-<slug>/: one SPEC per ticket, written first and updated as the work happens.
  • scripts/: the root gates (leak, licence, lib-version) and setup.sh. The dash check is packages/deck/scripts/check-dashes.mjs.

How to work

  1. Start from a GitHub issue. start-issue (skill) creates the branch and the SPEC skeleton.
  2. Write or update the SPEC in the same pull request as the code. Never keep a spec only in a chat, a ticket comment or a wiki.
  3. Keep changes small and focused, follow the patterns in the files you touch, and add tests for core behaviour and for anything that can lose data or leak.
  4. Before pushing, run the checks listed in CONTRIBUTING.md ("Checks a pull request must pass"). Commit first: two suites assert the tree is clean.
  5. Branch off main, keep each pull request to one change, and title commits type(scope): summary (#issue). Never push to main.

Patterns and tests

  • Test core behaviour, meaningful regressions and safeguards against unexpected spend, data loss or leaks. Skip exhaustive low-risk edge cases and implementation details unless they are part of the contract.
  • Test shell scripts in subprocesses with temporary fixtures, fake homes and stubs. For Nudges, use synthetic requests and fake cron dependencies, never a real crontab. If tmux is needed, use a private fixture socket, never the real agents session or the user's tmux. Do not run live agents for tests.
  • The eval workflow is proposed, not implemented: use synthetic fixtures, check outputs and side effects deterministically first, and use a fixed rubric for model grading only where judgement is needed. Keep live evals opt-in and agree limits first.
  • Feature components live in packages/deck/app/components/, with shared primitives in its ui/ subdirectory. Reuse existing components before adding new ones and follow the semantic tokens in packages/deck/app/app.css. See the UI components guide.

House rules

  • No internal material (names, hosts, paths, ticket ids, addresses) in the repository. pnpm check:leaks enforces it.
  • ASCII only, no em-dashes or en-dashes anywhere in the tree: U+2014 is the field separator in the message protocol. pnpm -C packages/deck check:dashes enforces it.
  • Sign off every commit (git commit -s); an unsigned commit fails the DCO gate.
  • Agents: do not push to main, force-push a shared branch, merge your own pull request, or create a release unless a maintainer asked you to in the issue or pull request.
0