Skip to content

AGENTS.md

Latest commit

 

History

History
151 lines (100 loc) · 8.34 KB

AGENTS.md

File metadata and controls

151 lines (100 loc) · 8.34 KB

AGENTS

<skills_system priority="1">

Skills Discovery

  • Canonical skills live in .agents/skills.
  • Provider-linked views are managed by sync tooling; do not duplicate full skill inventories in this file.
  • Refresh provider views with oat sync --scope all.
  • Update installed skills to latest bundled versions with oat tools update.
  • When a PR changes a canonical skill at .agents/skills/*/SKILL.md, increase that skill's frontmatter version: in the same PR.
  • The version bump is PR-scoped, not edit-scoped: one bump per changed skill in the final PR diff is required, even if the skill was edited multiple times on the branch.

</skills_system>

Development Commands

Essential Commands

  • pnpm build - Build all packages and applications (excludes docs for speed)
  • pnpm build:docs - Build the docs site and its dependencies
  • pnpm lint - Lint code using oxlint
  • pnpm format - Check formatting (oxfmt --check); use pnpm format:fix to auto-fix
  • pnpm type-check - TypeScript type checking across all packages
  • pnpm test - Run tests across the workspace

Development Workflow

  • pnpm dev - Run workspace development tasks
  • pnpm run cli -- help - Run the OAT CLI help from repo root
  • pnpm run cli -- <command> [options] - Execute specific OAT CLI commands during local testing
  • After creating or switching to a worktree, run pnpm run worktree:init before using the CLI workflow.

Web Retrieval Convention

  • For web content fetches, prefer https://markdown.new/<original-url> when viable (docs/blog/reference pages) to reduce HTML parsing overhead.
  • Example: https://markdown.new/developers.openai.com/codex/skills/
  • If markdown conversion is unavailable or loses required structure, fall back to the original URL.

Import Path Convention

  • Prefer same-directory imports (./...) for local modules.
  • For anything outside the current directory, use explicit TypeScript aliases configured by the package.
  • Avoid parent-relative imports (../...), src/... imports, and catch-all aliases like @/*.

Package Management

  • Uses pnpm workspaces with Turborepo for efficient monorepo management
  • All packages use workspace:* for internal dependencies
  • Build dependencies are automatically handled by Turborepo (^build dependency)
  • Publishable packages under packages/ are released from npm and participate in PR release dry-runs.
  • Publishable package guardrail: the lockstep public package set is packages/cli, packages/control-plane, packages/docs-config, packages/docs-theme, and packages/docs-transforms. If a PR changes shipped functionality for any of them, bump all five public package versions together in the same PR.
  • For release policy, bundled assets count as shipped CLI functionality. Changes under .agents/skills, .agents/agents, .oat/templates, .oat/scripts, or apps/oat-docs/docs require the same lockstep public package version bump even if no file under packages/cli/src changed.
  • Definition of done for publishable package changes: run pnpm release:validate before finishing. A publishable-package PR is not done until that command passes.

Architecture Overview

Monorepo Structure

  • Turborepo-based with pnpm workspaces for efficient builds and caching
  • TypeScript ESM - All packages use "type": "module" with ES modules
  • Shared configurations - TypeScript and build configs in packages/

Technology Stack

  • Runtime: Node.js 22.17.0 with TypeScript 5.8.3
  • Development: tsx for direct TypeScript execution with hot reloading
  • Build: Turborepo 2.7.6 with TypeScript compilation to dist/
  • Linting/Formatting: oxlint + oxfmt (configured via .oxlintrc.json and .oxfmtrc.jsonc)

Build System

  • Turborepo handles dependency ordering and parallel builds
  • TypeScript compilation to dist/ directories
  • Watch mode available for both packages (pnpm dev) and applications (tsx watch)
  • Clean builds with pnpm clean to remove all dist/ directories

Feature Planning Triage

Pre-implementation gate: Before making any code changes, confirm that either a workflow option has been selected or the user has explicitly opted out. If neither has happened, present the workflow options below. This applies even if the task seems small — the user decides scope, not the agent.

Workflow Options

Present these options to the user, with a recommendation based on the assessment heuristic below:

  1. Full spec-driven workflow — Discovery → Spec → Design → Plan → Implement Best for: complex features, cross-cutting concerns, multiple components, projects needing formal requirements or traceability. → Use oat-project-new (scaffolds spec-driven project)

  2. Quick workflow — Discovery → [Optional Lightweight Design] → Plan → Implement Best for: bounded features at any size, clear requirements, rapid iteration preferred. Can still produce a design artifact when architecture decisions matter. → Use oat-project-quick-start

  3. Import external plan — Normalize an existing plan into OAT format → Implement Best for: plans already drafted in another tool, session, or document. → Use oat-project-import-plan

  4. Provider plan mode → import — Use provider's native plan mode, then import the result into an OAT project for tracked implementation. Best for: users who prefer provider planning UX but want OAT tracking.

  5. No project workflow — Proceed without OAT project tracking. Best for: small fixes, straightforward changes, or explicit user preference.

Recommendation Heuristic

Before presenting options, assess the request and lead with a recommendation:

  • Multiple components/APIs/data models, unclear boundaries, or cross-cutting concerns → Recommend spec-driven (#1)
  • Bounded feature of any size, some design questions but clear requirements → Recommend quick (#2)
  • User references an existing plan or external artifact → Recommend import (#3)
  • User is already in plan mode or prefers that UX → Recommend provider plan mode → import (#4)
  • Simple, well-understood change or user says "just do it" → Recommend no workflow (#5)

The distinguishing factor is requirements clarity and design risk, not task count. A large but well-understood migration is fine for quick mode. A small but architecturally unclear feature might need spec-driven.

Guardrail

Once a workflow is selected (or explicitly declined), do NOT produce ad-hoc planning artifacts outside the chosen workflow. All planning output must flow through the selected workflow's artifacts (discovery.md, spec.md, design.md, plan.md, etc.) or, if no workflow was selected, proceed directly to implementation.

If the user declines all workflows, confirm once:

"Got it — I'll proceed without project tracking. If this grows in scope, I can set up a project workflow at any point."

Agent Workflow

For multi-session or complex development tasks, use the structured agent project workflow:

Execution Continuation

This rule applies only to OAT project lifecycle execution, such as oat-project-implement, and OAT project review/receive flows. It does not apply to non-OAT tasks or ad-hoc work outside the OAT project workflow.

When executing an OAT project implementation or OAT project review workflow, do not stop at task boundaries, phase boundaries, or other clean checkpoints unless:

  • the configured HiLL checkpoint has been reached,
  • a real blocker exists,
  • or explicit user input is required.

Status summaries, completed bookkeeping, and "clean boundary" pauses are not completion criteria. After updating tracking artifacts, continue execution until one of the allowed stop conditions applies.

Project Structure

Projects live in .oat/projects/<scope>/<project>/ with:

  • Core files: state.md, discovery.md, spec.md, design.md, plan.md, implementation.md
  • Optional: reviews/, pr/

Docs Pack Workflows

  • oat-docs-bootstrap - Guide users through bootstrapping a docs app end-to-end: preflight, input gathering, scaffold (via oat docs init) with capability-gated post-patches, build verification, config inspection, and educational walkthrough.
  • oat-docs-analyze - Analyze a docs surface for index.md contract coverage, nav drift, and docs app readiness.
  • oat-docs-apply - Apply approved docs-analysis recommendations with branch, nav-sync, and PR workflow support.