@nichollasf/ai-kit 1.0.1

package/.agents/catalog/personal.json

@@ -0,0 +1,370 @@
+{
+  "schemaVersion": 2,
+  "profile": "personal",
+  "maxConcurrency": 4,
+  "roles": {
+    "planner": {
+      "archetype": ".agents/archetypes/planner.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": true,
+          "scopes": [".agents/plans/**"]
+        },
+        "delegate": false,
+        "review": false
+      }
+    },
+    "orchestrator": {
+      "archetype": ".agents/archetypes/orchestrator.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": false,
+          "scopes": []
+        },
+        "delegate": true,
+        "review": false
+      }
+    },
+    "implementer-senior": {
+      "archetype": ".agents/archetypes/implementer-senior.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": true,
+          "scopes": ["task write scope"]
+        },
+        "delegate": false,
+        "review": false
+      }
+    },
+    "implementer": {
+      "archetype": ".agents/archetypes/implementer.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": true,
+          "scopes": ["task write scope"]
+        },
+        "delegate": false,
+        "review": false
+      }
+    },
+    "quick": {
+      "archetype": ".agents/archetypes/quick.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": true,
+          "scopes": ["task write scope"]
+        },
+        "delegate": false,
+        "review": false
+      }
+    },
+    "researcher": {
+      "archetype": ".agents/archetypes/researcher.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": false,
+          "scopes": []
+        },
+        "delegate": false,
+        "review": false
+      }
+    },
+    "reviewer": {
+      "archetype": ".agents/archetypes/reviewer.md",
+      "capabilities": {
+        "read": true,
+        "write": {
+          "enabled": false,
+          "scopes": []
+        },
+        "delegate": false,
+        "review": true
+      }
+    }
+  },
+  "models": {
+    "astra": {
+      "family": "gpt",
+      "id": "gpt-6-astra",
+      "harnesses": {
+        "codex": "gpt-6-astra",
+        "opencode": "openai/gpt-6-astra"
+      }
+    },
+    "sol": {
+      "family": "gpt",
+      "id": "gpt-5.6-sol",
+      "harnesses": {
+        "codex": "gpt-5.6-sol",
+        "opencode": "openai/gpt-5.6-sol"
+      }
+    },
+    "terra": {
+      "family": "gpt",
+      "id": "gpt-5.6-terra",
+      "harnesses": {
+        "codex": "gpt-5.6-terra",
+        "opencode": "openai/gpt-5.6-terra"
+      }
+    },
+    "luna": {
+      "family": "gpt",
+      "id": "gpt-5.6-luna",
+      "harnesses": {
+        "codex": "gpt-5.6-luna",
+        "opencode": "openai/gpt-5.6-luna"
+      }
+    },
+    "fable": {
+      "family": "claude",
+      "id": "claude-fable-5-1",
+      "harnesses": {
+        "claude-code": "claude-fable-5-1",
+        "opencode": "anthropic/claude-fable-5-1"
+      }
+    },
+    "opus": {
+      "family": "claude",
+      "id": "claude-opus-5",
+      "harnesses": {
+        "claude-code": "claude-opus-5",
+        "opencode": "anthropic/claude-opus-5"
+      }
+    },
+    "sonnet": {
+      "family": "claude",
+      "id": "claude-sonnet-5",
+      "harnesses": {
+        "claude-code": "claude-sonnet-5",
+        "opencode": "anthropic/claude-sonnet-5"
+      }
+    },
+    "haiku": {
+      "family": "claude",
+      "id": "claude-haiku-4-5-20251001",
+      "harnesses": {
+        "claude-code": "claude-haiku-4-5-20251001",
+        "opencode": "anthropic/claude-haiku-4-5-20251001"
+      }
+    }
+  },
+  "bindings": {
+    "planner:gpt": {
+      "archetype": "planner",
+      "route": "gpt",
+      "model": "astra",
+      "effortSupport": "supported",
+      "supportedEfforts": ["medium", "high", "xhigh"],
+      "effort": {
+        "low": "medium",
+        "medium": "high",
+        "high": "xhigh"
+      }
+    },
+    "planner:claude": {
+      "archetype": "planner",
+      "route": "claude",
+      "model": "fable",
+      "effortSupport": "supported",
+      "supportedEfforts": ["medium", "high", "xhigh"],
+      "effort": {
+        "low": "medium",
+        "medium": "high",
+        "high": "xhigh"
+      }
+    },
+    "orchestrator:gpt": {
+      "archetype": "orchestrator",
+      "route": "gpt",
+      "model": "sol",
+      "effortSupport": "supported",
+      "supportedEfforts": ["xhigh"],
+      "effort": {
+        "low": "xhigh",
+        "medium": "xhigh",
+        "high": "xhigh"
+      }
+    },
+    "orchestrator:claude": {
+      "archetype": "orchestrator",
+      "route": "claude",
+      "model": "opus",
+      "effortSupport": "supported",
+      "supportedEfforts": ["xhigh"],
+      "effort": {
+        "low": "xhigh",
+        "medium": "xhigh",
+        "high": "xhigh"
+      }
+    },
+    "implementer-senior:gpt": {
+      "archetype": "implementer-senior",
+      "route": "gpt",
+      "model": "sol",
+      "effortSupport": "supported",
+      "supportedEfforts": ["xhigh"],
+      "effort": {
+        "low": "xhigh",
+        "medium": "xhigh",
+        "high": "xhigh"
+      }
+    },
+    "implementer-senior:claude": {
+      "archetype": "implementer-senior",
+      "route": "claude",
+      "model": "opus",
+      "effortSupport": "supported",
+      "supportedEfforts": ["xhigh"],
+      "effort": {
+        "low": "xhigh",
+        "medium": "xhigh",
+        "high": "xhigh"
+      }
+    },
+    "implementer:gpt": {
+      "archetype": "implementer",
+      "route": "gpt",
+      "model": "terra",
+      "effortSupport": "supported",
+      "supportedEfforts": ["low", "medium", "high"],
+      "effort": {
+        "low": "low",
+        "medium": "medium",
+        "high": "high"
+      }
+    },
+    "implementer:claude": {
+      "archetype": "implementer",
+      "route": "claude",
+      "model": "sonnet",
+      "effortSupport": "supported",
+      "supportedEfforts": ["low", "medium", "high"],
+      "effort": {
+        "low": "low",
+        "medium": "medium",
+        "high": "high"
+      }
+    },
+    "quick:gpt": {
+      "archetype": "quick",
+      "route": "gpt",
+      "model": "luna",
+      "effortSupport": "supported",
+      "supportedEfforts": ["low", "medium"],
+      "effort": {
+        "low": "low",
+        "medium": "medium"
+      }
+    },
+    "quick:claude": {
+      "archetype": "quick",
+      "route": "claude",
+      "model": "haiku",
+      "effortSupport": "unsupported",
+      "supportedEfforts": [],
+      "effort": {}
+    },
+    "researcher:gpt": {
+      "archetype": "researcher",
+      "route": "gpt",
+      "model": "luna",
+      "effortSupport": "supported",
+      "supportedEfforts": ["low", "medium", "high"],
+      "effort": {
+        "low": "low",
+        "medium": "medium",
+        "high": "high"
+      }
+    },
+    "researcher:claude": {
+      "archetype": "researcher",
+      "route": "claude",
+      "model": "haiku",
+      "effortSupport": "unsupported",
+      "supportedEfforts": [],
+      "effort": {}
+    },
+    "reviewer:gpt": {
+      "archetype": "reviewer",
+      "route": "gpt",
+      "model": "sol",
+      "effortSupport": "supported",
+      "supportedEfforts": ["xhigh"],
+      "effort": {
+        "low": "xhigh",
+        "medium": "xhigh",
+        "high": "xhigh"
+      }
+    },
+    "reviewer:claude": {
+      "archetype": "reviewer",
+      "route": "claude",
+      "model": "opus",
+      "effortSupport": "supported",
+      "supportedEfforts": ["xhigh"],
+      "effort": {
+        "low": "xhigh",
+        "medium": "xhigh",
+        "high": "xhigh"
+      }
+    }
+  },
+  "presets": {
+    "codex": {
+      "planner": "planner:gpt",
+      "orchestrator": "orchestrator:gpt",
+      "implementer-senior": "implementer-senior:gpt",
+      "implementer": "implementer:gpt",
+      "quick": "quick:gpt",
+      "researcher": "researcher:gpt",
+      "reviewer": "reviewer:gpt"
+    },
+    "claude-code": {
+      "planner": "planner:claude",
+      "orchestrator": "orchestrator:claude",
+      "implementer-senior": "implementer-senior:claude",
+      "implementer": "implementer:claude",
+      "quick": "quick:claude",
+      "researcher": "researcher:claude",
+      "reviewer": "reviewer:claude"
+    },
+    "opencode": {
+      "defaultRoute": "gpt",
+      "routes": ["gpt", "claude"]
+    }
+  },
+  "taskContract": {
+    "requiredFields": [
+      "ID",
+      "Objective",
+      "Role",
+      "Binding",
+      "Effort",
+      "Dependencies",
+      "Write Scope",
+      "Acceptance Criteria",
+      "Validation Commands"
+    ],
+    "approvalMarker": "Approved-Plan-SHA256",
+    "digestAlgorithm": "sha256"
+  },
+  "reviewGate": {
+    "requiredFor": "non-trivial",
+    "role": "reviewer",
+    "independent": true
+  },
+  "handoff": [
+    "Objective",
+    "Evidence",
+    "Work Or Findings",
+    "Validation",
+    "Risks",
+    "Escalation"
+  ]
+}

package/.agents/skills/ai-kit-model-calibration/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ai-kit-model-calibration
+description: Benchmarks and calibrates catalog-bound Claude Code, Codex or OpenCode models and reasoning variants on representative local tasks. Use only when the user explicitly asks to compare models, measure routing quality, run roll-call, or update the ai-kit model matrix.
+license: MIT
+metadata:
+  author: nychollas09
+  version: "2.0"
+---
+
+# AI Kit Model Calibration
+
+Requires the selected Claude Code, Codex or OpenCode CLI, disposable fixtures or worktrees, model-provider access, and permission to incur model usage.
+
+Measure routing quality with representative tasks instead of relying on public leaderboards. Never run calibration against a working tree containing valuable uncommitted work.
+
+## Safety Gate
+
+Before any model call:
+
+1. Confirm the user explicitly requested calibration and approved the expected provider usage.
+2. Create or select a disposable fixture or disposable git worktree.
+3. Record the selected harness and CLI version, model IDs, reasoning efforts or variants, fixture revision, platform, and date.
+4. Define acceptance criteria and a deterministic validation command for each task.
+5. Ensure no credentials, private source, or secrets will appear in prompts or scorecards.
+
+Do not modify production repositories, publish results, or treat subscription access as permission to spend against another provider.
+
+## Evaluation Order
+
+Start with the strongest candidate at high reasoning effort to establish the quality baseline. Then test cheaper model or effort substitutions on the same task and context. Randomize task order when ordering effects could matter.
+
+Use the selected CLI's documented model, reasoning-effort, agent, and structured-output options when running representative tasks. A CLI discovery or connectivity probe is evidence of availability, not a quality benchmark. Keep the installed versioned model IDs and supported efforts from `.agents/catalog/personal.json`; Haiku has no effort control, so omit that parameter. Record an explicitly selected OpenCode Claude route and do not fall back silently.
+
+Keep authentication and project trust in their normal CLI-managed locations. Never copy auth files into a fixture, print credentials, or record personal harness configuration. A disposable Codex fixture may use an isolated `CODEX_HOME` containing only the minimum project-trust entry created for that run.
+
+## Score Dimensions
+
+Score each run using [the rubric](references/rubric.md):
+
+- Correctness and completed acceptance criteria.
+- Instruction and scope adherence.
+- Tool-call efficiency.
+- Latency and cost or usage evidence.
+- Escalation accuracy.
+- Independent review quality.
+
+Do not collapse these into one score until hard failures are recorded. A fast incorrect result is not a viable route.
+
+## Recording Results
+
+Copy [the scorecard template](assets/scorecard.md) to a new dated path under `.agents/evals/model-routing/`. Use a collision-resistant filename such as `YYYY-MM-DD-HHMM-<fixture>-<model>.md`. Never overwrite a prior run.
+
+Record raw command parameters and concise evidence, but never tokens, API keys, auth files, environment values, or full private prompts. Mark facts, inference, and reviewer judgment separately.
+
+## Routing Recommendation
+
+Recommend a source-catalog change only when it repeatedly meets the quality baseline for that role's representative workload. Do not change installed presets or legacy overlays during calibration. Planner owns the architectural recommendation; only Orchestrator delegates, and benchmark workers never coordinate each other. State sample size, confidence, regressions, and catalog/provider assumptions. Public benchmark scores may inform candidate selection but never override local failures.

package/.agents/skills/ai-kit-model-calibration/assets/scorecard.md

@@ -0,0 +1,61 @@
+---
+date: YYYY-MM-DD
+fixture: fixture-name
+fixture_revision: git-revision-or-hash
+harness: claude-code-or-codex-or-opencode
+cli_version: x.y.z
+agent: agent-name
+model: provider/model
+effort: catalog-effort-or-unsupported
+---
+
+# Model Routing Scorecard
+
+## Task
+
+- Objective:
+- Acceptance criteria:
+- Validation command:
+- Explicit non-goals:
+
+## Environment
+
+- Platform:
+- Runtime versions:
+- Disposable fixture/worktree:
+- Command parameters:
+- Catalog binding:
+- Explicit route (GPT / Claude):
+- Effort support (supported / unsupported):
+
+## Results
+
+| Dimension             | Score (0-4) | Evidence |
+| --------------------- | ----------: | -------- |
+| Correctness           |             |          |
+| Instruction adherence |             |          |
+| Tool efficiency       |             |          |
+| Latency and cost      |             |          |
+| Escalation accuracy   |             |          |
+| Review quality        |             |          |
+
+## Hard Failures
+
+None observed.
+
+## Validation
+
+- Outcome:
+- Reviewer findings:
+
+## Facts And Inference
+
+- Verified facts:
+- Inference:
+- Uncertainty:
+
+## Routing Recommendation
+
+- Recommendation:
+- Sample size and confidence:
+- Regressions or constraints:

package/.agents/skills/ai-kit-model-calibration/references/rubric.md

@@ -0,0 +1,41 @@
+# Model Calibration Rubric
+
+Score each dimension from 0 to 4 and attach evidence.
+
+| Score | Meaning                                                            |
+| ----- | ------------------------------------------------------------------ |
+| 0     | Failed fundamentally or created unacceptable risk.                 |
+| 1     | Major acceptance criteria missed; extensive correction required.   |
+| 2     | Partially correct; material correction or supervision required.    |
+| 3     | Correct with minor, bounded correction.                            |
+| 4     | Correct, efficient, and independently verified without correction. |
+
+## Dimensions
+
+### Correctness
+
+Use objective tests and acceptance criteria. Any destructive behavior, secret exposure, fabricated evidence, or unapproved scope change is a hard failure regardless of aggregate score.
+
+### Instruction Adherence
+
+Check source-of-truth usage, write boundaries, explicit non-goals, output contract, and user approval requirements.
+
+### Tool Efficiency
+
+Compare relevant calls, duplicated exploration, avoidable retries, context waste, and whether parallelism was justified.
+
+### Latency And Cost
+
+Record elapsed time and provider-reported cost or usage when available. Do not estimate missing billing data as fact.
+
+### Escalation Accuracy
+
+Reward stopping on real architecture, security, migration, or approval boundaries. Penalize both silent overreach and needless escalation of routine work.
+
+### Review Quality
+
+Measure valid defects found, false positives, severity ordering, reference precision, and residual-gap disclosure.
+
+## Decision Rule
+
+A cheaper route is eligible only if it has no hard failures, satisfies every must-pass criterion, and performs within the task's tolerated quality margin over repeated runs. Report per-dimension scores and failures alongside any aggregate.

package/.agents/skills/ai-kit-task-routing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ai-kit-task-routing
+description: Execute the ai-kit approved-plan workflow in Claude Code, Codex or OpenCode using the installed archetype contracts and fixed catalog bindings. Use for substantial planned software work; skip a single obvious local edit.
+license: MIT
+metadata:
+  author: nychollas09
+  version: "2.0"
+---
+
+# AI Kit Task Routing
+
+Read `.agents/generated/selection.json` before activating this workflow. Continue only when `orchestrationEnabled` is true and all seven archetypes are installed. An individual selection exposes individual roles without activating orchestration.
+
+Use `.agents/archetypes/` as the role contracts and `.agents/catalog/personal.json` as the binding authority. Do not read or apply an old `local.json` overlay. Models change only through a reviewed source-catalog update and installation update.
+
+## Authority
+
+Only Orchestrator delegates. Planner defines architecture and tasks but neither implements nor delegates. Senior-Implementer (`implementer-senior`), Implementer and Quick implement within assigned scope and never coordinate workers. Researcher gathers evidence without choosing architecture. Reviewer independently reviews without editing the reviewed work.
+
+These contracts are instructions. Read the rendered profile's enforcement notes to distinguish tool restrictions and sandbox behavior from behavioral obligations. A prompt is not a security boundary.
+
+## Planning And Approval
+
+Initial planning is a manually selected Planner main context. Claude Code and OpenCode users select the installed Planner profile directly. For a partial Codex installation, select Planner using `--primary planner`; its read-only sandbox returns the plan through a handoff. Orchestrator starts only after a complete plan and actual approval exist; it does not bootstrap planning by dispatching workers before that gate.
+
+Planner assesses ambiguity, blast radius, reversibility, coupling, security, migration risk and validation cost. File count alone does not select a role. Choose Senior-Implementer for complex, risky or coupled work; Implementer for bounded known approaches; Quick for narrow reversible tasks; Researcher for evidence.
+
+Each task contains ID, Objective, Role, Binding, Effort, Dependencies, Write Scope, Acceptance Criteria and Validation Commands. Specify a catalog binding ID and exact rendered model/effort profile. Quick has no high-complexity GPT route; escalate that work. Haiku's effort is recorded as `unsupported` and no effort argument is emitted.
+
+Plans use UTF-8 and LF. SHA-256 covers the entire plan body before the marker, including one final LF. Obtain actual user approval for that body and record `Approved-Plan-SHA256: <64 lowercase hex digits>`; the marker alone is not proof of approval. Orchestrator checks approval provenance, digest, required fields, acyclic known dependencies and current repository evidence. Reject incomplete, altered or stale plans. Expected changes from completed dependencies do not invalidate the plan; unrelated changes that invalidate assumptions do. Return changed requirements or architecture to Planner and renew approval after edits.
+
+SHA-256 must be calculated and checked by a cryptographic hashing tool. Never invent, estimate or mentally calculate a digest, and never treat the marker embedded in a plan as independent verification. If this role has no permitted hashing tool, use fresh verification evidence supplied by a trusted external host or user tool. That evidence must identify the exact approved UTF-8/LF plan-body snapshot and its SHA-256 result. Before dispatch, read the current plan and compare its body with that verified snapshot; require a fresh external check if the bytes cannot be established as unchanged. If trustworthy verification evidence is missing, report that missing evidence to the user or host and do not dispatch. This is an evidence requirement, not a request to approve an already authorized action again.
+
+## Dispatch
+
+Dispatch only ready tasks, using their exact catalog binding and profile. Codex uses the GPT preset and Claude Code uses the Claude preset. OpenCode defaults to GPT and exposes an explicit Claude route; never silently substitute or fall back if the selected route is unavailable. The availability of an unselected Claude alternative does not block GPT work.
+
+Limit execution to four simultaneous workers. Parallelize only independent dependencies and disjoint write scopes with independent acceptance criteria. Workers return to Orchestrator; no nested delegation. Orchestrator tracks and synthesizes work but does not implement product changes or replan.
+
+Every dispatch includes the bounded objective, repository evidence, allowed write scope, acceptance criteria, validation, binding/profile and constraints. Read [the handoff contract](references/handoff.md) when composing or evaluating results.
+
+## Completion
+
+For every non-trivial change, use Reviewer in a fresh independent context after implementation. A different model provider is optional. Address valid findings through the responsible implementation worker within approved scope. Route architecture changes back to Planner. Report objective validation, review outcome and remaining limitations before completion.

package/.agents/skills/ai-kit-task-routing/references/handoff.md

@@ -0,0 +1,29 @@
+# Worker Handoff Contract
+
+Return these exact sections, in order:
+
+## Objective
+
+Restate the bounded task and its acceptance criteria.
+
+## Evidence
+
+Reference inspected files, symbols, commands, versions and primary sources. Distinguish observation from inference.
+
+## Work Or Findings
+
+For implementation, describe changed behavior and paths. For research or review, order findings by impact and provide precise references. A reviewer reports independently and never edits the reviewed work.
+
+## Validation
+
+Report commands and observed outcomes, including failures and checks that could not run.
+
+## Risks
+
+Identify unresolved assumptions, compatibility concerns and validation gaps. Say `None identified` only after checking.
+
+## Escalation
+
+Recommend accept, revise within scope, return to Planner, or request a missing user decision. Workers send the recommendation to Orchestrator; they never dispatch another worker. Orchestrator handles corrections and requests a fresh approval if the plan changes.
+
+Do not forward credentials or raw sensitive logs, broaden scope silently, or claim completion from intent alone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nichollas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.