AGENTS.md — Working on @agentinit/cli

This file is for AI coding agents (and humans) developing this repository. It is hand-written; it is not output generated by the CLI.

Source of Truth

• What to build: docs/PRD.md. Never contradict it silently.
• What to build next: docs/tasks/. Work on exactly one task per session.
• Where code goes: ARCHITECTURE.md — folder map, dependency rules, which modules may touch disk.
• If the PRD and a task disagree, or the PRD is silent on something you need, stop and ask instead of inventing behavior. If the user decides, update the PRD in the same change.

Commands

Repo-only scripts (common build / dev / lint / test / typecheck live in the managed block below):

pnpm check:package    # publint
pnpm registry:check   # registry content checks
pnpm smoke            # packed-tarball smoke test

Before finishing any task, pnpm lint && pnpm typecheck && pnpm test && pnpm build must pass.

Core Conventions

• TypeScript strict, ESM only, Node ^22.18.0 || ^24.11.0 || >=26.0.0. Named exports only; no default exports.
• Respect the purity boundaries in ARCHITECTURE.md: registry/resolve.ts, plan/, and targets/ never touch disk, process, prompts, or the clock.
• User-facing errors are AgentInitError with an exit code, readable without a stack trace.
• Keep dependencies to those listed in PRD §4.2. Ask before adding a runtime dependency.
• Every task adds or updates tests for the behavior it introduces.
• Comments explain constraints the code can't show, not what the next line does.

Area-Specific Rules

Detailed rules for each area live in .cursor/rules/. Cursor loads them automatically when you touch matching files; other agents must read the matching file before editing that area:

Workflows

Reusable procedures live in docs/workflows/ and are exposed as slash commands (.claude/skills/; Cursor loads these too):

• /implement-task <id> — implement one task from docs/tasks/.
• /review-task <id> — read-only review of a finished task.
• /write-fragment <id> — author or revise a registry fragment.
• /commit-changes — commit the working tree (conventional commits, no co-author trailer, no push).
• /pr-summary — draft the pull request title and description against the PR's base branch (main, or release/0.2 for 0.2 task work). Does not open the pull request.

Agents without slash commands can open the matching file in docs/workflows/ and follow it.

Git

• Conventional Commits; never add Co-authored-by: trailers or AI/tool attribution. Full convention: .cursor/rules/git-commits.mdc.
• One task = one branch (task/T05-registry-loader) = one PR, unless the task file says otherwise.

Compatibility

Public API rules for fragments, the manifest, --json, and exit codes: CONTRIBUTING.md (PRD §6.2, §9). In short: published fragment ids are never renamed; manifest changes in 0.x stay additive; --json / exit-code breaks need a minor release and a BREAKING CHANGE changeset note.

Always-on rules for this project. Scoped rules and workflows stay in each agent's own files.

Contents

• Project commands
• Architecture
• TypeScript Strict

Project commands

• pnpm build
• pnpm dev
• pnpm lint
• pnpm test
• pnpm typecheck

Architecture

• Put each concern in its own top-level folder under src/.
• Put types and contracts shared by more than one concern at the src/ root.
• Import another concern only through the surface that concern exposes.
• Declare which concerns may import which in ARCHITECTURE.md.
• Keep the graph of concern folders free of import cycles.

See ARCHITECTURE.md for the folder map and conventions for new code.

TypeScript Strict

Boundary

These rules apply to every .ts and .tsx file. The project typechecks with strict enabled. unknown is the top type for a value that is not yet checked. any turns checking off for that value.

Directives

• NEVER use the any type. ALWAYS hold an unchecked value as unknown and narrow it before property access, a call, or assignment to a specific type.
• ALWAYS write an explicit return type on every exported function, including small helpers (parse*, safeParse wrappers, and schema mappers). Exception: React components and framework entry files (page, layout, route handlers) may omit a return type. PREFER inference for a function that is not exported.
• NEVER use the postfix ! non-null assertion. Narrow null and undefined with a check.
• ALWAYS check a config object literal with satisfies when the variable should keep its specific property types.
• PREFER a discriminated union (a shared literal field such as status) over a boolean plus optional fields.
• ALWAYS finish a switch on that discriminant with a default that assigns the value to never.
• ALWAYS use import type for a binding used only as a type. NEVER use import type for a value you call, construct, or extend.
• NEVER set strict or strictNullChecks to false.

Contract

// ✅ Good: unknown is narrowed, exports name their return types, config keeps its own types
import type { InvoiceId } from './ids';

type Invoice =
  | { status: 'open'; id: InvoiceId; total: number }
  | { status: 'paid'; id: InvoiceId; total: number; paidOn: string };

type ParseAmountResult =
  | { success: true; data: number }
  | { success: false; error: string };

type RGB = [red: number, green: number, blue: number];
type ThemeName = 'danger' | 'ok';

export const theme = {
  danger: [255, 0, 0],
  ok: '#00ff00',
} satisfies Record<ThemeName, string | RGB>;

export function parseAmount(input: unknown): ParseAmountResult {
  if (typeof input !== 'number') return { success: false, error: 'Expected a number' };
  return { success: true, data: input };
}

export function label(invoice: Invoice): string {
  switch (invoice.status) {
    case 'open':
      return 'Open';
    case 'paid':
      return invoice.paidOn;
    default: {
      const unexpected: never = invoice;
      throw new Error(`Unhandled invoice: ${String(unexpected)}`);
    }
  }
}

// ❌ Anti-pattern: any, a boolean flag, a non-null assertion, and a missing export return type
type Loose = { paid: boolean; paidOn?: string };
export function paidOn(invoice: Loose, input: any) {
  return invoice.paidOn!.slice(0, input.total);
}