Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (59 loc) · 5.75 KB

AGENTS.md

File metadata and controls

67 lines (59 loc) · 5.75 KB
Raw

Repository Guidelines

Project Structure & Module Organization

This package is the TypeScript source for Interlinked CLI.

  • Interlinked MCP Server refers to the remote Cloudflare Worker system that the CLI optionally talks to.
  • Interlinked CLI refers to this package.
  • src/index.ts: CLI entry point and command registration.
  • src/commands/*.ts: command handlers (enable, status, doctor, workspace, etc.).
  • src/lib/*.ts: shared logic (auth, config, hooks, API client, formatting).
  • src/templates/: generated/template assets used by setup flows.
  • src/**/*.test.ts and src/commands/__tests__/: Vitest unit/regression tests.
  • docs/architecture.md: architecture notes.
  • dist/: build output (generated).

Build, Test, and Development Commands

  • npm run dev: run the CLI directly with tsx for local development.
  • npm run build: bundle src/index.ts to dist/ with type declarations (tsup).
  • npm run typecheck: run TypeScript checks with tsgo (tsgo --noEmit).
  • npm run typecheck:stable: run the stable TypeScript compiler (tsc --noEmit).
  • npm run test: run tests once (vitest run).
  • npm run test:watch: run tests in watch mode.
  • npm run docs: regenerate generated CLI/harness reference docs.

Example:

npm run dev -- status --short

Agent Notes

  • QuentinCody/interlinked-cli is the source of truth for the CLI.
  • Keep the exact product terms distinct: Interlinked CLI is this package; Interlinked MCP Server is the remote Worker/Durable Objects system used by server-backed commands.
  • Harness phase split: PreToolUse handles deterministic pre-execution blocks and warnings (destructive commands, file reservations, secrets-in-content, grep acceleration). PostToolUse handles checks that need files on disk or project context (type/lint/security/structure), and should report only new findings through diff-aware filtering.
  • Zero-FP contract: pre_block error checks must be fully deterministic. Heuristic smell/taste/coverage checks belong as warnings or in verify --all-checks. When changing advisory policy, update DEFAULT_ADVISORY_SKIPS and its regression tests together.
  • Adding an agent-quality check usually touches src/harness/generic-checks.ts, the check registry entries, src/harness/check-metadata.ts, src/harness/check-registry/ entry files, src/commands/verify*, and parity/advisory tests. Land those coupled changes together.
  • Hook scripts generated by the CLI must stay self-contained. PostToolUse is intentionally scoped to mutating tools, and PostToolUseFailure is intentionally not registered to avoid duplicate hook-count/output issues; see docs/investigation-posttooluse-hook-count.md before changing hook matchers.
  • Rule/check metadata changes require npm run docs; do not hand-edit stale generated counts.
  • Major changes in this repository MUST include a skill-impact review. This includes user-visible CLI commands/options/output, harness behavior or policy, configuration schemas/defaults, supported-client behavior, baseline semantics, and architecture or operator workflows. Update every affected skills/*/SKILL.md in the same change; code or design-doc updates alone are not complete when agent guidance changed. If no skill is affected, state why in the final handoff.
  • Keep the skill router and focused skills aligned: update skills/interlinked/SKILL.md when a capability's routing changes, and update the relevant focused skill with the current command/config contract and operational gotchas. Treat .agents/skills/ as an installed/generated copy, not the source of truth. Validate every touched skill folder with the skill validator before handoff.
  • Supported coding clients (interlinked enable --clients <list>): claude, copilot, gemini, codex. Per-client install logic lives in src/lib/hook-installers.ts; src/lib/hooks.ts is the orchestrator that wires them through CLIENT_INSTALL_REGISTRY. The generated .mjs script disambiguates Codex (Claude-shaped payloads) from Claude via the INTERLINKED_CLIENT env var set by the installed hook command.
  • Codex CLI hook gating: installCodexHooks writes .codex/hooks.json AND ensures [features] codex_hooks = true in .codex/config.toml. Without that flag Codex silently ignores the hooks.json file. Uninstall leaves config.toml untouched to avoid clobbering user-managed Codex configuration.

Coding Style & Naming Conventions

  • Language: TypeScript (ESM, strict mode).
  • Style in this repo: 4-space indentation, double quotes, semicolons.
  • File names: use descriptive kebab-case where practical (for example, activity-utils.ts).
  • Exports: use camelCase for functions and PascalCase for types/interfaces.
  • Command handlers should stay in src/commands/; reusable logic belongs in src/lib/.

Testing Guidelines

  • Framework: Vitest (environment: node, configured in vitest.config.ts).
  • Test file pattern: src/**/*.test.ts.
  • Prefer colocated regression tests for command behavior under src/commands/__tests__/.
  • Add tests for bug fixes, especially around config merging, auth flows, and CLI output modes.

Commit & Pull Request Guidelines

  • Follow conventional commit style seen in history: feat: ..., fix: ..., refactor: ... (optional scope is fine).
  • Keep commit subjects short and imperative.
  • PRs should include:
    • What changed and why.
    • Commands run (npm run typecheck, npm run test).
    • Linked issue/task, if applicable.
    • Terminal output snippets when user-facing CLI behavior changes.

Security & Configuration Tips

  • Never commit secrets from .interlinked/config.local.json (tokens are local-only).
  • Prefer environment variables for automation (for example, INTERLINKED_ACCESS_TOKEN).
  • Treat clean/reset operations as destructive; validate target workspace/project context first.