interlinked-cli AGENTS.md

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.