Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (43 loc) · 3.88 KB

AGENTS.md

File metadata and controls

66 lines (43 loc) · 3.88 KB

Repository Guidelines

Project Structure & Module Organization

This is a TypeScript monorepo with a full implementation. Key top-level paths:

  • src/: library source code (TypeScript, ESM)
  • tests/: Vitest test suite mirroring src/ structure
  • apps/: example/demo applications (e.g. apps/todo-linear-demo/)
  • dist/: compiled output (generated by pnpm build, not committed)
  • docs/: supplementary documentation
  • biome.json: Biome lint and format configuration
  • tsconfig.json / tsconfig.build.json: TypeScript project configs
  • vitest.config.ts: test runner configuration
  • README.upstream.md / SPEC.upstream.md: upstream reference docs

Keep new source files under src/, tests under tests/, and additional apps under apps/<name>/. Store design assets and media under docs/assets/ or .github/media/.

Build, Test, and Development Commands

The package manager is pnpm (>=10.0.0) and the runtime target is Node.js >=22.

Command Purpose
pnpm install Install dependencies
pnpm build Compile TypeScript to dist/ via tsc
pnpm test Run all tests once with Vitest
pnpm test:watch Run tests in watch mode
pnpm typecheck Type-check without emitting output
pnpm lint Lint and check formatting with Biome
pnpm format Auto-format source files with Biome

Coding Style & Naming Conventions

Keep Markdown concise, imperative, and specific to this repository. Use sentence-style prose in docs and short sections with meaningful headings. Name new files clearly by purpose, for example ARCHITECTURE.md, docs/setup.md, or apps/orchestrator/.

Match the formatter and linter of the language you introduce. If you add source code, also add the corresponding config files in the same change.

Testing Guidelines

The repository uses Vitest. All tests live under tests/ and mirror the src/ directory structure. Run pnpm test to execute the full suite. Prefer naming test files after the module they cover (e.g. tests/orchestrator/core.test.ts for src/orchestrator/core.ts) and name individual test cases after observable behavior.

Commit & Pull Request Guidelines

Recent commits use short imperative subjects, for example Add execution order to implementation plan. Follow that pattern: start with a verb, keep the subject focused, and avoid punctuation at the end.

Pull requests should include:

  • a short problem statement and scope summary
  • links to relevant issues, specs, or upstream references
  • pnpm test output confirming all tests pass
  • screenshots or logs when changing UX, automation flows, or generated artifacts

Security & Configuration Tips

Do not commit secrets, tokens, or private board data. Keep local environment settings in untracked files such as .env.local, and document required variables without checking in real values.

Source of Truth

Use IMPLEMENTATION_PLAN.md as the required development sequence: contributors should implement work in that order unless the plan is explicitly revised. Treat SPEC.upstream.md as the single source of truth for product behavior, feature scope, and acceptance criteria. If the plan, local notes, or code comments conflict with the spec, follow the spec and update the other artifacts to match it.

Branching & Worktree Workflow

Tasks 1 and 2 may be developed directly in the main working copy. For every task after Task 2, create a dedicated worktree under .worktrees/ and do the implementation on a separate branch. Complete the work there, push the branch, and open a pull request before merging. Example flow: git worktree add .worktrees/task-3 -b task-3, implement the change in that worktree, then submit a PR for review.

After finishing any task, verify that the implementation matches SPEC.upstream.md without behavioral or scope drift. Once that check passes, open the pull request immediately rather than batching multiple tasks into one PR.