@nichollasf/ai-kit 1.0.1

package/README.md

@@ -0,0 +1,151 @@
+# @nichollasf/ai-kit
+
+A personal archetype catalog for **Claude Code, Codex and OpenCode**, installed into a project with `npx`. Select a complete team or individual roles, choose the harnesses, and install relative file links or copies. Node.js 20+; zero runtime dependencies.
+
+The CLI distributes packaged content. It does not run agents, install harnesses, configure credentials, or install globally. Harness installation and account access are needed to execute the profiles, not to copy the catalog.
+
+## Install
+
+From an existing project, open the wizard:
+
+```sh
+npx @nichollasf/ai-kit
+```
+
+The wizard defaults to the complete seven-role team. Individual selection leaves orchestration disabled. Noninteractive installation requires explicit harness selection and defaults to the full team:
+
+```sh
+npx @nichollasf/ai-kit add --harnesses codex,claude-code,opencode --yes
+npx @nichollasf/ai-kit add --harnesses codex --archetypes quick,reviewer --primary quick --method copy --yes
+npx @nichollasf/ai-kit add --harnesses opencode --team --target "../my project" --dry-run
+```
+
+For an incomplete team, `--primary <selected-role>` chooses the standalone main role without enabling delegation. Change it transactionally with `update --primary reviewer`; the other selected roles stay installed. All harnesses default to the first selected role when no primary is specified. Claude/OpenCode also support native manual agent selection.
+
+`init` remains an alias for `add`. `--method symlink` is the default; every discovery link points relatively to a known regular file inside the installation. Unsupported symlinks abort with a recommendation to use `--method copy`; the method never changes silently.
+
+## Commands
+
+| Command       | Behavior                                                                               |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `add`, `init` | Install into an existing project; an identical installation is a no-op.                |
+| `list`        | Print all archetypes, pinned model bindings, effort mappings and presets.              |
+| `update`      | Replace intact owned artifacts; keep selection unless explicitly replaced.             |
+| `check`       | Report structural integrity, local availability and behavioral limitations separately. |
+| `uninstall`   | Remove only intact manifest-owned artifacts and the manifest.                          |
+
+All project commands accept `--target`. Mutating commands accept `--dry-run` with zero writes, including no temporary files. `check --dry-run` checks structure but skips harness processes, returning readiness unverified. `--yes` bypasses the wizard for explicit selections. There is no `--force` or global mode.
+
+```sh
+npx @nichollasf/ai-kit list
+npx @nichollasf/ai-kit update --dry-run
+npx @nichollasf/ai-kit update --harnesses codex,opencode --method copy
+npx @nichollasf/ai-kit check
+npx @nichollasf/ai-kit check --route claude
+npx @nichollasf/ai-kit uninstall --dry-run
+```
+
+`--route claude` checks the explicit OpenCode alternative; it does not rewrite defaults. Exit codes: `0` success; `2` CLI usage; `3` safety/preflight rejection; `4` check failed or readiness unverified; `1` unexpected failure. Installer errors never authorize overwriting local changes.
+
+## Archetypes and presets
+
+| Archetype                                 | Responsibility                                                                                      | Codex / default OpenCode | Claude Code / alternative OpenCode |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------- |
+| Planner                                   | Architecture and executable tasks; no implementation or delegation                                  | `gpt-6-astra`            | `claude-fable-5-1`                 |
+| Orchestrator                              | Dispatch approved tasks, track dependencies and synthesize; no product implementation or replanning | `gpt-5.6-sol`            | `claude-opus-5`                    |
+| Senior-Implementer (`implementer-senior`) | Complex, risky or coupled implementation; no delegation                                             | `gpt-5.6-sol`            | `claude-opus-5`                    |
+| Implementer                               | Bounded implementation with defined approach and acceptance                                         | `gpt-5.6-terra`          | `claude-sonnet-5`                  |
+| Quick                                     | Narrow, reversible changes; escalate high-risk work                                                 | `gpt-5.6-luna`           | `claude-haiku-4-5-20251001`        |
+| Researcher                                | Evidence and uncertainty; no architecture decisions or implementation                               | `gpt-5.6-luna`           | `claude-haiku-4-5-20251001`        |
+| Reviewer                                  | Independent review and validation assessment; no edits to reviewed work                             | `gpt-5.6-sol`            | `claude-opus-5`                    |
+
+Only Orchestrator delegates. No worker coordinates another worker. Four workers may run simultaneously only with independent scopes. Non-trivial changes require Reviewer in a fresh context; changing model provider is optional.
+
+GPT effort by low / medium / high task complexity:
+
+| Role                                       | Effort mapping             |
+| ------------------------------------------ | -------------------------- |
+| Planner                                    | medium / high / xhigh      |
+| Orchestrator, Senior-Implementer, Reviewer | xhigh / xhigh / xhigh      |
+| Implementer, Researcher                    | low / medium / high        |
+| Quick                                      | low / medium / unavailable |
+
+Claude Planner uses medium/high/xhigh, Opus roles use xhigh, and Implementer uses low/medium/high. Haiku effort is explicitly unsupported; adapters emit no effort parameter. IDs are explicit and versioned; neither installation nor routing resolves `latest`.
+
+Each binding has stable profiles containing archetype, model ID and effort, such as `implementer-gpt-5.6-terra-high`. OpenCode also exposes `implementer` for the default GPT route and `implementer-claude` for the explicit Claude route. Unavailable unselected Claude models do not block GPT; selecting an unavailable route produces a diagnostic instead of fallback.
+
+## Layout and discovery
+
+```text
+.agents/
+  archetypes/                 Selected model-free role contracts
+  catalog/personal.json       Versioned bindings and presets
+  catalog/catalog-v2.schema.json
+  generated/selection.json    Selection and orchestration state
+  generated/<harness>/        Materialized profiles and main configuration
+  skills/                     Own shared skills
+  .ai-kit-manifest.json        Exact artifact ownership, schema v3
+  plans/                      User-owned; never installed or removed
+  evals/                      User-owned; never installed or removed
+.codex/config.toml             Main configuration link/copy
+.codex/agents/*.toml           Codex role links/copies
+.claude/settings.json          Main Orchestrator selection when team is complete
+.claude/agents/*.md            Adapted Claude links/copies
+.claude/skills/...             Per-file skill links/copies
+.opencode/agents/*.md          Native OpenCode profile links/copies
+opencode.json                 OpenCode main configuration link/copy
+```
+
+Codex and OpenCode discover shared skills in `.agents/skills/`; Claude receives per-file links or copies. Canonical `.agents/archetypes` frontmatter is a deliberately small OpenCode-compatible subset: exactly a JSON-quoted `description` scalar and `mode: primary|subagent`, UTF-8/LF, no duplicate keys or other YAML features. Rendered Claude and OpenCode frontmatter are separate adaptations.
+
+Codex must trust the project before its project configuration loads. Claude's complete-team settings select `orchestrator` as the main agent. OpenCode selects `orchestrator` as its primary agent; choose a `*-claude` profile explicitly for the alternative route.
+
+## Plans and actual enforcement
+
+A Planner task records ID, Objective, Role, Binding/profile, Effort, Dependencies, Write Scope, Acceptance Criteria and Validation Commands. Approval uses `Approved-Plan-SHA256` over the UTF-8/LF plan body before the marker, including its final LF. The marker is recorded after actual user approval; a hash is not evidence of consent. Orchestrator rejects missing fields, changed digests, invalid dependencies and stale evidence. Architecture or plan changes return to Planner and require renewed approval.
+
+Roles without a cryptographic hash tool must receive fresh verification from a trusted host or user tool and compare the current plan with the verified snapshot. They must never invent a digest. If this evidence is missing, they request it before dispatch. For example, outside the agent, use Node's SHA-256 on the exact LF plan body before adding the marker; retain that verified body with the approval.
+
+Start planning in a standalone Planner session: `claude --agent planner --effort high --setting-sources project` or `opencode --agent planner`. Codex can select it with `ai-kit update --archetypes planner --primary planner`, then restore the approved-plan team with `ai-kit update --team`. These commands use the existing installed harness selection. Orchestrator does not invent a plan to bypass missing approval.
+
+Handoffs preserve `Objective; Evidence; Work Or Findings; Validation; Risks; Escalation`.
+
+| Harness     | Enforced configuration                                                                                                              | Behavioral limits                                                                                                                                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Codex       | Configured workers disable delegation; Planner, Researcher and Reviewer have read-only sandboxes; four-thread setting               | Main Orchestrator uses workspace-write so implementing workers can inherit it. Its no-product-edit rule and restriction to registered profiles remain instructions. Planner returns plan text for the user to save. |
+| Claude Code | Worker `Agent`/`Task` tools denied; main `Agent(...)` allowlist; read-only roles lack write/shell tools; depth/concurrency settings | Planner's plan-directory scope is behavioral; concurrency has harness exceptions. The allowlist applies only in the main context.                                                                                   |
+| OpenCode    | Task allowlist on primary Orchestrator, worker task denial, read-only/edit restrictions and depth limit                             | Four-worker cap, task-scoped product edits, approval freshness and mechanical routing depend on compliance.                                                                                                         |
+
+Prompts do not provide security isolation. Personal settings, CLI overrides, account model access and harness versions can affect effective behavior. `check` separates those availability/capability checks from file integrity; missing authentication never prevents installation but prevents declaring the environment ready. No model generation is used for diagnostics or integration tests.
+
+## Updates and migration
+
+Ownership is by exact file path, never directory or filename prefix. Preexisting conflicting configurations abort before mutation; the installer does not merge personal or shared configuration files. Unrelated agents, files inside skill directories, empty user directories, plans, evaluations and personal Kilo configuration remain untouched.
+
+`update` migrates intact v1/v2 installations only with explicit new harness selection:
+
+```sh
+npx @nichollasf/ai-kit update --harnesses codex,claude-code,opencode --dry-run
+npx @nichollasf/ai-kit update --harnesses codex,claude-code,opencode
+```
+
+Only historical files recorded in a complete validated manifest are retired, including Kilo agents. Modified or missing owned files abort the whole operation. Legacy `.agents/catalog/local.json` stays unmanaged and preserved; incompatible overrides block migration and new installation. Empty legacy overlay metadata is accepted. Overlays never alter the new presets silently.
+
+Customize model IDs in the **source repository's** `personal.json`, review and package that change, then run `update` in target projects. Do not edit installed owned files: their checksum mismatch deliberately blocks update/uninstall. Previous v3 aliases are derived from the verified installed catalog so a source model update can safely retire renamed profiles. A renamed role or changed layout requires an explicit migration design.
+
+Changes stage on the same filesystem, back up each file or link, roll back on failure, and apply the manifest last. A lock prevents cooperating concurrent installers. If rollback cannot safely restore data, backups and the lock remain with a diagnostic path. After a process crash, inspect `.agents/.ai-kit-lock` and transaction backups before retrying; crash recovery is manual.
+
+## Development
+
+```sh
+npm ci
+npm run check
+npm run test:integration
+npm pack --dry-run --json
+```
+
+Tests cover the catalog, wizard, ownership, links/copies, migrations, rollback, zero-write dry-run and installation from an actual tarball through offline `npx`. Codex 0.154.0 has no validated narrow API for project trust and every effective role setting. Normal `check` uses redacted diagnostics and conservatively returns `4` for that unresolved layer; it does not fetch raw personal configuration. Native integration establishes those configuration properties only in isolated test stores. Claude runtime discovery uses project-only settings, so use `claude --setting-sources project` for that checked scope. OpenCode Planner paths are relative to its Git worktree; nested project targets may require returning plan text in the handoff when native plan-directory writes are denied.
+
+Native integration checks use isolated temporary configuration stores and no model calls. Unavailable CLIs are explicitly skipped; see the test report. Validated locally with Codex 0.154.0, Claude Code 2.1.265 and OpenCode 1.18.30.
+
+The public package allowlist excludes legacy catalog/prompts, credentials, overlays, plans, evaluations and third-party skills. Version 1.0.0 introduces the breaking layout and manifest transition described in [the architecture decision](docs/architecture.md). Release validation includes an exact package inventory and a redacted secret scan of the public source, Git history and packed artifact.

package/dist/catalog.d.ts

@@ -0,0 +1,99 @@
+import { type Asset } from "./manifest.js";
+export declare const ROLE_NAMES: readonly ["planner", "orchestrator", "implementer-senior", "implementer", "quick", "researcher", "reviewer"];
+export type RoleName = (typeof ROLE_NAMES)[number];
+export declare const HARNESS_NAMES: readonly ["codex", "claude-code", "opencode"];
+export type HarnessName = (typeof HARNESS_NAMES)[number];
+export type Method = "symlink" | "copy";
+export interface Selection {
+    harnesses: HarnessName[];
+    archetypes: RoleName[];
+    method: Method;
+    primary?: RoleName;
+}
+export declare const COMPLEXITIES: readonly ["low", "medium", "high"];
+export type Complexity = (typeof COMPLEXITIES)[number];
+export declare const EFFORTS: readonly ["low", "medium", "high", "xhigh"];
+export type Effort = (typeof EFFORTS)[number];
+export declare const ROUTES: readonly ["gpt", "claude"];
+export type Route = (typeof ROUTES)[number];
+export declare const CATALOG_SCHEMA_PATH = ".agents/catalog/catalog-v2.schema.json";
+export declare const BASE_CATALOG_PATH = ".agents/catalog/personal.json";
+export declare const LOCAL_CATALOG_PATH = ".agents/catalog/local.json";
+export declare const PROMPT_PATHS: string[];
+export declare const CATALOG_PATHS: string[];
+export declare const SKILL_PATHS: readonly [".agents/skills/ai-kit-model-calibration/SKILL.md", ".agents/skills/ai-kit-model-calibration/assets/scorecard.md", ".agents/skills/ai-kit-model-calibration/references/rubric.md", ".agents/skills/ai-kit-task-routing/SKILL.md", ".agents/skills/ai-kit-task-routing/references/handoff.md"];
+export declare const REQUIRED_TASK_FIELDS: readonly ["ID", "Objective", "Role", "Binding", "Effort", "Dependencies", "Write Scope", "Acceptance Criteria", "Validation Commands"];
+export declare const HANDOFF_FIELDS: readonly ["Objective", "Evidence", "Work Or Findings", "Validation", "Risks", "Escalation"];
+export interface ModelDefinition {
+    family: Route;
+    id: string;
+    harnesses: Partial<Record<HarnessName, string>>;
+}
+export interface Binding {
+    archetype: RoleName;
+    route: Route;
+    model: string;
+    effortSupport: "supported" | "unsupported";
+    supportedEfforts: Effort[];
+    effort: Partial<Record<Complexity, Effort>>;
+}
+export interface RolePolicy {
+    archetype: string;
+    capabilities: {
+        read: true;
+        write: {
+            enabled: boolean;
+            scopes: string[];
+        };
+        delegate: boolean;
+        review: boolean;
+    };
+}
+export interface Catalog {
+    schemaVersion: 2;
+    profile: "personal";
+    maxConcurrency: number;
+    roles: Record<RoleName, RolePolicy>;
+    models: Record<string, ModelDefinition>;
+    bindings: Record<string, Binding>;
+    presets: {
+        codex: Record<RoleName, string>;
+        "claude-code": Record<RoleName, string>;
+        opencode: {
+            defaultRoute: "gpt";
+            routes: ["gpt", "claude"];
+        };
+    };
+    taskContract: {
+        requiredFields: string[];
+        approvalMarker: "Approved-Plan-SHA256";
+        digestAlgorithm: "sha256";
+    };
+    reviewGate: {
+        requiredFor: "non-trivial";
+        role: "reviewer";
+        independent: true;
+    };
+    handoff: string[];
+}
+export interface LoadedCatalog {
+    catalog: Catalog;
+    baseChecksum: string;
+    catalogAssets: Asset[];
+    prompts: Record<RoleName, string>;
+    descriptions: Record<RoleName, string>;
+    skillAssets: Asset[];
+}
+export declare function normalizeSelection(value: Selection): Selection;
+export declare function orchestrationEnabled(selection: Selection): boolean;
+export declare function validateCatalog(value: unknown): Catalog;
+/** Own frontmatter is deliberately limited to two scalar keys; it is not a YAML parser. */
+export declare function parseArchetype(content: string, role: RoleName): {
+    description: string;
+    body: string;
+};
+export declare function loadCatalog(packageRoot: string, _target?: string): Promise<LoadedCatalog>;
+export declare function getBinding(catalog: Catalog, role: RoleName, harness: HarnessName, route?: Route): Binding;
+export declare function defaultEffort(binding: Binding): Effort | undefined;
+export declare function profileName(catalog: Catalog, role: RoleName, binding: Binding, effort?: Effort): string;
+export declare function materialize(loaded: LoadedCatalog, value: Selection): Asset[];