@ankhorage/devtools 1.8.4 → 1.9.0

package/README.md

@@ -11,6 +11,8 @@ src/
 ├── cli/
 ├── policy/
 └── tools/
+    ├── agents/
+    ├── skills/
     ├── eslint/
     ├── prettier/
     ├── knip/
@@ -21,6 +23,8 @@ src/
 
 - `policy`: shared repository runtime policy, including the canonical Bun version
 - `changesets`: package-resolved Changesets execution and release command policy
+- `agents`: canonical repository `AGENTS.md` rendered from stable package identity
+- `skills`: immutable Ankhorage-owned repository skills under `.agents/skills/`
 - `eslint`: shared flat ESLint configuration, automatic project profiles, and the bundled ESLint runner
 - `prettier`: shared Prettier configuration and the bundled Prettier runner
 - `knip`: shared Knip configuration helpers and the bundled Knip runner
@@ -61,6 +65,10 @@ The package is discovered under the `devtools` category and exposes these capabi
 - `devtools.knip`
 - `devtools.sync`
 - `devtools.status`
+- `devtools.agents.sync`
+- `devtools.agents.status`
+- `devtools.skills.sync`
+- `devtools.skills.status`
 - `devtools.eslint.sync`
 - `devtools.eslint.status`
 - `devtools.prettier.sync`
@@ -125,6 +133,8 @@ ankh devtools status .
 Synchronize one concern:
 
 ```bash
+ankh devtools agents sync .
+ankh devtools skills sync .
 ankh devtools eslint sync .
 ankh devtools prettier sync .
 ankh devtools knip sync .
@@ -136,6 +146,8 @@ ankh devtools vscode sync .
 Report one concern:
 
 ```bash
+ankh devtools agents status .
+ankh devtools skills status .
 ankh devtools eslint status .
 ankh devtools prettier status .
 ankh devtools knip status .
@@ -148,11 +160,13 @@ Preview synchronization without writing:
 
 ```bash
 ankh devtools sync . --dry-run
+ankh devtools agents sync . --dry-run
+ankh devtools skills sync . --dry-run
 ankh devtools eslint sync . --dry-run
 ankh devtools package sync . --dry-run
 ```
 
-A dry run reports `would create` and `would update` actions without mutating files. `status` exits with code `1` when managed state has drifted and `0` when it is current.
+A dry run reports `would create`, `would update`, and `would remove` actions without mutating files. `status` exits with code `1` when managed state has drifted and `0` when it is current.
 
 ## Synchronization guarantees
 
@@ -160,6 +174,7 @@ Synchronization is deterministic and idempotent:
 
 - missing managed artifacts are created
 - outdated centrally owned artifacts are updated
+- stale files in Devtools-owned skill trees are removed
 - the managed Bun runtime version is applied consistently to package metadata and workflows
 - Changesets-enabled repositories use the Devtools-owned runner without a direct `@changesets/cli` declaration
 - package changes are followed by `bun install` after all managed files have been written, keeping installed dependencies and `bun.lock` synchronized without invalidating the running sync
@@ -169,7 +184,19 @@ Synchronization is deterministic and idempotent:
 - invalid target paths and write failures return a non-zero exit code
 - create-only repository extension files are never overwritten after creation
 
-The canonical workflow and VS Code files are packaged with `@ankhorage/devtools`; synchronization does not fetch mutable files from GitHub at runtime.
+The canonical workflow, VS Code, and skill files are packaged with `@ankhorage/devtools`; synchronization does not fetch mutable files from GitHub at runtime.
+
+## Managed agent instructions
+
+`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy and directs structural work to the managed project-structure skill.
+
+Only the current Ankhorage architecture is supported. Managed instructions reject deprecated APIs, compatibility aliases, shims, dual old/new paths, historical-state fallbacks, and migrations whose sole purpose is obsolete state. A canonical cross-package change requires affected repositories to update to the latest released public API.
+
+## Managed repository skills
+
+`ankh devtools skills sync` owns the complete `.agents/skills/ankhorage-coding-rules/` and `.agents/skills/ankhorage-project-structure/` trees from the immutable copies shipped in the Devtools release. It creates `.agents/` when missing, replaces stale files in those managed skills, and preserves every unrelated skill directory.
+
+`.agents/.devtools-manifest.json` records the source Devtools version and SHA-256 hashes for every managed skill file. That ownership record allows status and dry-run to report drift and lets later releases remove stale owned files without deleting repository-owned skills.
 
 ## ESLint profiles
 
@@ -313,7 +340,7 @@ A repository participates in Changesets synchronization when `.changeset/config.
 
 CI and Release render their `bun-version` from the same managed Bun runtime policy used for `package.json`. They also render Changesets status, version, and publish commands from the same policy that owns the synchronized package scripts. The CI workflow installs that Bun version with the frozen lockfile, builds before repository-provider validation, runs `bunx @ankhorage/ankh doctor validate .`, and conditionally runs lint, formatting, Knip, tests, typecheck, and Changesets checks. Ordinary pull requests run the strict `changeset:status --since=origin/main` guard. A same-repository `changeset-release/main` pull request instead runs `bun run changeset -- status --since=HEAD`, validating the Version Packages metadata from the detached release checkout without requiring a local `main` ref or another unreleased Changeset after the release Changeset was consumed. A fork using that branch name remains subject to the ordinary strict guard. Release publishing calls the Devtools-owned runner through the synchronized package script; it never resolves an ambient or mutable Changesets executable.
 
-The Renovate workflow accepts only same-repository branches created by `renovate[bot]`. It calls the SHA-pinned `ankhorage/renovate` workflow to add a release Changeset for runtime Ankhorage dependency updates or an empty Changeset for dev-only updates, then dispatches CI for that bot-authored commit. It never checks out or executes pull-request code in the privileged `pull_request_target` context.
+The Renovate workflow accepts only same-repository branches created by `renovate[bot]`. It calls the SHA-pinned `ankhorage/renovate` workflow to add a release Changeset for runtime Ankhorage dependency updates or an empty Changeset for dev-only updates. The trusted workflow scopes the Ankhorage Renovate Sync GitHub App token to the current repository and uses it only for the validated commit, allowing every normal pull-request CI workflow to start without manual approval. It never checks out or executes pull-request code in the privileged `pull_request_target` context.
 
 ## Managed VS Code configuration
 

package/dist/cli/commands.d.ts

@@ -1,7 +1,7 @@
 export type DevtoolsToolName = 'changeset' | 'format' | 'knip' | 'lint';
-type DevtoolsManagedScope = 'all' | 'eslint' | 'knip' | 'package' | 'prettier' | 'vscode' | 'workflows';
+type DevtoolsManagedScope = 'agents' | 'all' | 'eslint' | 'knip' | 'package' | 'prettier' | 'skills' | 'vscode' | 'workflows';
 type DevtoolsManagedOperation = 'status' | 'sync';
-type DevtoolsCapability = 'devtools.changeset' | 'devtools.format' | 'devtools.knip' | 'devtools.lint' | 'devtools.status' | 'devtools.sync' | 'devtools.eslint.status' | 'devtools.eslint.sync' | 'devtools.knip.status' | 'devtools.knip.sync' | 'devtools.package.status' | 'devtools.package.sync' | 'devtools.prettier.status' | 'devtools.prettier.sync' | 'devtools.vscode.status' | 'devtools.vscode.sync' | 'devtools.workflows.status' | 'devtools.workflows.sync';
+type DevtoolsCapability = 'devtools.changeset' | 'devtools.format' | 'devtools.knip' | 'devtools.lint' | 'devtools.status' | 'devtools.sync' | 'devtools.agents.status' | 'devtools.agents.sync' | 'devtools.eslint.status' | 'devtools.eslint.sync' | 'devtools.knip.status' | 'devtools.knip.sync' | 'devtools.package.status' | 'devtools.package.sync' | 'devtools.prettier.status' | 'devtools.prettier.sync' | 'devtools.skills.status' | 'devtools.skills.sync' | 'devtools.vscode.status' | 'devtools.vscode.sync' | 'devtools.workflows.status' | 'devtools.workflows.sync';
 interface DevtoolsCommandBase {
     readonly path: readonly [string, ...string[]];
     readonly capability: DevtoolsCapability;

package/dist/cli/commands.js

@@ -5,6 +5,10 @@ const DEVTOOLS_COMMANDS = [
     externalCommand('knip', 'devtools.knip', 'Run the shared Knip toolchain.', 'knip', 'knip'),
     repositoryCommand(['sync'], 'devtools.sync', 'Synchronize all managed repository setup.', 'all', 'sync'),
     repositoryCommand(['status'], 'devtools.status', 'Report drift for all managed repository setup.', 'all', 'status'),
+    repositoryCommand(['agents', 'sync'], 'devtools.agents.sync', 'Synchronize the canonical repository agent instructions.', 'agents', 'sync'),
+    repositoryCommand(['agents', 'status'], 'devtools.agents.status', 'Report drift for the canonical repository agent instructions.', 'agents', 'status'),
+    repositoryCommand(['skills', 'sync'], 'devtools.skills.sync', 'Synchronize canonical repository-local agent skills.', 'skills', 'sync'),
+    repositoryCommand(['skills', 'status'], 'devtools.skills.status', 'Report drift for canonical repository-local agent skills.', 'skills', 'status'),
     repositoryCommand(['eslint', 'sync'], 'devtools.eslint.sync', 'Synchronize the shared ESLint setup.', 'eslint', 'sync'),
     repositoryCommand(['eslint', 'status'], 'devtools.eslint.status', 'Report drift for the shared ESLint setup.', 'eslint', 'status'),
     repositoryCommand(['prettier', 'sync'], 'devtools.prettier.sync', 'Synchronize the shared Prettier setup.', 'prettier', 'sync'),

package/dist/cli/index.d.ts

@@ -2,10 +2,10 @@ declare const provider: {
     id: string;
     category: string;
     version: string;
-    capabilities: ("devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync")[];
+    capabilities: ("devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.agents.status" | "devtools.agents.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.skills.status" | "devtools.skills.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync")[];
     commands: {
         path: string[];
-        capability: "devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync";
+        capability: "devtools.changeset" | "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.agents.status" | "devtools.agents.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.skills.status" | "devtools.skills.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync";
         summary: string;
     }[];
     handlers: {

package/dist/cli/index.js

@@ -4,13 +4,13 @@
  * `ankh devtools changeset`, `ankh devtools lint`, `ankh devtools format`, and
  * `ankh devtools knip` execute the bundled Changesets, ESLint, Prettier, and Knip versions.
  * Repository synchronization is available through
- * `ankh devtools sync` and `ankh devtools status`, with focused `eslint`, `prettier`, `knip`,
- * `package`, `workflows`, and `vscode` sync/status subcommands.
+ * `ankh devtools sync` and `ankh devtools status`, with focused `agents`, `skills`, `eslint`,
+ * `prettier`, `knip`, `package`, `workflows`, and `vscode` sync/status subcommands.
  *
  * Sync commands accept an optional target directory and `--dry-run`. Aggregate sync is
- * deterministic and idempotent: canonical managed files are created or updated, create-only
- * local extension files remain repository-owned, and package metadata is merge-updated without
- * replacing unrelated fields.
+ * deterministic and idempotent: canonical managed files and skill trees are created or updated,
+ * unrelated repository-local skills and create-only local extension files remain repository-owned,
+ * and package metadata is merge-updated without replacing unrelated fields.
  *
  * Fresh repositories can bootstrap the standard setup with `ankh devtools sync .` after adding
  * `@ankhorage/devtools`. Existing ESLint configuration is preserved during first migration as a

package/dist/cli/runRepositoryCommand.js

@@ -1,9 +1,11 @@
+import { agentsManagedFiles } from '../tools/agents/index.js';
 import { eslintManagedFiles } from '../tools/eslint/managed.js';
 import { knipManagedFiles } from '../tools/knip/managed.js';
 import { inspectPackageManifest, readCurrentDevtoolsVersion, syncPackageManifest, } from '../tools/package/index.js';
 import { planBunDependencySync, syncBunDependencies, } from '../tools/package/syncBunDependencies.js';
 import { prettierManagedFiles } from '../tools/prettier/managed.js';
 import { inspectManagedFiles, resolveManagedTargetDirectory, syncManagedFiles, } from '../tools/shared/managedFiles.js';
+import { inspectManagedSkills, syncManagedSkills } from '../tools/skills/managed.js';
 import { vscodeManagedFiles } from '../tools/vscode/index.js';
 import { workflowManagedFiles } from '../tools/workflows/index.js';
 export async function runRepositoryCommand(command, argv, context) {
@@ -47,6 +49,9 @@ async function runStatus(scope, targetDirectory, devtoolsVersion, context) {
         statuses.push(await inspectPackageManifest(targetDirectory, devtoolsVersion));
     }
     statuses.push(...(await inspectManagedFiles(targetDirectory, getManagedFiles(scope))));
+    if (scope === 'all' || scope === 'skills') {
+        statuses.push(...(await inspectManagedSkills(targetDirectory, devtoolsVersion)));
+    }
     writeStatusOutput(statuses, context);
     return { exitCode: statuses.some((status) => status.state !== 'current') ? 1 : 0 };
 }
@@ -59,6 +64,9 @@ async function runSync(scope, targetDirectory, devtoolsVersion, dryRun, context)
         packageDependenciesChanged = packageResult.action !== 'unchanged';
     }
     results.push(...(await syncManagedFiles(targetDirectory, getManagedFiles(scope), { dryRun })));
+    if (scope === 'all' || scope === 'skills') {
+        results.push(...(await syncManagedSkills(targetDirectory, devtoolsVersion, { dryRun })));
+    }
     if (packageDependenciesChanged) {
         if (dryRun) {
             results.push(planBunDependencySync(targetDirectory));
@@ -73,9 +81,11 @@ async function runSync(scope, targetDirectory, devtoolsVersion, dryRun, context)
 }
 function getManagedFiles(scope) {
     const definitionsByScope = {
+        agents: agentsManagedFiles,
         eslint: eslintManagedFiles,
         knip: knipManagedFiles,
         prettier: prettierManagedFiles,
+        skills: [],
         vscode: vscodeManagedFiles,
         workflows: workflowManagedFiles,
     };
@@ -95,6 +105,9 @@ function writeStatusOutput(statuses, context) {
         else if (status.state === 'missing') {
             context.writeStdout(`+ ${status.relativePath} missing\n`);
         }
+        else if (status.state === 'obsolete') {
+            context.writeStdout(`- ${status.relativePath} obsolete\n`);
+        }
         else {
             context.writeStdout(`✗ ${status.relativePath} outdated\n`);
         }
@@ -113,6 +126,9 @@ function getActionPrefix(action) {
     if (action === 'created' || action === 'would-create') {
         return '+';
     }
+    if (action === 'removed' || action === 'would-remove') {
+        return '-';
+    }
     return '↻';
 }
 function formatAction(action) {
@@ -121,10 +137,14 @@ function formatAction(action) {
             return 'created';
         case 'updated':
             return 'updated';
+        case 'removed':
+            return 'removed';
         case 'unchanged':
             return 'unchanged';
         case 'would-create':
             return 'would create';
+        case 'would-remove':
+            return 'would remove';
         case 'would-update':
             return 'would update';
     }

package/dist/internal/readmeDocs.js

@@ -6,6 +6,8 @@ const REQUIRED_README_SNIPPETS = [
     'ankh devtools knip',
     'ankh devtools sync',
     'ankh devtools status',
+    'ankh devtools agents sync',
+    'ankh devtools skills sync',
     'ankh devtools eslint sync',
     'ankh devtools prettier sync',
     'ankh devtools knip sync',
@@ -13,6 +15,9 @@ const REQUIRED_README_SNIPPETS = [
     'ankh devtools workflows sync',
     'ankh devtools vscode sync',
     'devtools.eslint.sync',
+    'devtools.agents.sync',
+    'devtools.skills.sync',
+    'ankhorage-coding-rules',
     'devtools.prettier.sync',
     'devtools.knip.sync',
     'devtools.package.sync',

package/dist/tools/agents/index.d.ts

@@ -0,0 +1,6 @@
+export declare const agentsManagedFiles: readonly [{
+    readonly relativePath: "AGENTS.md";
+    readonly render: typeof renderAgentsFile;
+}];
+declare function renderAgentsFile(targetDirectory: string): Promise<string>;
+export {};

package/dist/tools/agents/index.js

@@ -0,0 +1,70 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const agentsManagedFiles = [
+    {
+        relativePath: 'AGENTS.md',
+        render: renderAgentsFile,
+    },
+];
+async function renderAgentsFile(targetDirectory) {
+    const manifest = await readPackageManifest(targetDirectory);
+    const packageName = readNonEmptyString(manifest.name) ?? 'Package name not declared';
+    const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
+    return `# AGENTS.md
+
+<!-- This file is managed by @ankhorage/devtools. -->
+
+## Repository
+
+Package: \`${escapeInlineCode(packageName)}\`
+
+${description}
+
+## Current architecture only
+
+Only the current Ankhorage architecture is valid. Do not add or retain deprecated APIs,
+compatibility aliases, shims, dual old/new paths, historical-state fallbacks, or migrations whose
+sole purpose is supporting obsolete states. Remove superseded implementations instead.
+
+When a canonical change affects another repository, update that repository to the latest released
+public API instead of preserving compatibility locally. Cross-package usage must go through
+published public APIs and declared dependencies, never sibling source files.
+
+Current-runtime error handling and canonical database or infrastructure migrations remain valid
+when they support states that the current architecture can intentionally produce.
+
+## Project structure
+
+For directory ownership, package boundaries, architectural profiles, ports and adapters, public
+entrypoints, or cross-repository structural work, load and follow
+\`.agents/skills/ankhorage-project-structure/SKILL.md\`.
+`;
+}
+async function readPackageManifest(targetDirectory) {
+    try {
+        const contents = await readFile(resolve(targetDirectory, 'package.json'), 'utf8');
+        const parsed = JSON.parse(contents);
+        if (!isRecord(parsed)) {
+            throw new Error('package.json must contain a JSON object.');
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+}
+function escapeInlineCode(value) {
+    return value.replaceAll('`', '\\`');
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}

package/dist/tools/shared/managedFiles.d.ts

@@ -7,8 +7,8 @@ export interface ManagedFileDefinition {
     readonly render?: ManagedFileRenderer;
     readonly mode?: ManagedFileMode;
 }
-type ManagedFileState = 'current' | 'missing' | 'outdated';
-type ManagedFileSyncAction = 'unchanged' | 'created' | 'updated' | 'would-create' | 'would-update';
+type ManagedFileState = 'current' | 'missing' | 'obsolete' | 'outdated';
+export type ManagedFileSyncAction = 'unchanged' | 'created' | 'removed' | 'updated' | 'would-create' | 'would-remove' | 'would-update';
 export interface ManagedFileStatus {
     readonly relativePath: string;
     readonly state: ManagedFileState;

package/dist/tools/skills/assets/ankhorage-coding-rules/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ankhorage-coding-rules
+description: >
+  Implement, refactor, test, review, or hand off code changes in Ankhorage repositories. Use for
+  task branches and pull requests, canonical lint compliance, behavior-focused testing, Paradox
+  function documentation, validation, and release-quality delivery. Use ankhorage-project-structure
+  as well when the task changes package ownership, public entrypoints, or source architecture.
+---
+
+# Ankhorage Coding Rules
+
+Deliver focused changes that satisfy the repository's current canonical policy and are ready for
+review. Read the repository `AGENTS.md`, package scripts, public exports, representative tests, and
+documentation ownership before editing.
+
+Repository instructions may add stricter requirements. They must not be bypassed with local
+exceptions or replaced by generic preferences from this skill.
+
+## Git and delivery
+
+- For a new task, fetch the latest `origin/main` and create a fresh task branch from it. Never
+  implement directly on `main`.
+- Continue existing pull-request work on its existing branch. Do not create a nested task branch.
+- Preserve unrelated or dirty user work. Use an isolated worktree when changing branches would
+  disturb it.
+- Keep the diff within the requested issue. Do not mix opportunistic cleanup into the change.
+- Deliver coding work through a pull request. If remote writes are unavailable or unauthorized,
+  prepare the branch and report the pending push or PR explicitly.
+- Describe the change, architectural effect, validation, public API and changeset impact,
+  documentation impact, and linked issue in the PR body.
+
+## Canonical lint compliance
+
+- New and materially changed code must satisfy the canonical ESLint configuration.
+- Never add, widen, or depend on `eslint.local.config.mjs` exceptions. Existing exceptions are
+  removable migration debt, not policy for new work.
+- Do not weaken rules or add suppression comments, unsafe casts, or similar bypasses merely to make
+  validation pass.
+- Resolve size, complexity, and related findings around cohesive responsibilities and clear data
+  flow. Do not split a function or file mechanically just to cross a threshold.
+- Prefer reusable pure transformations, immutable values, and explicit inputs and outputs. Keep
+  unavoidable mutation and external side effects at clear boundaries.
+- Keep one canonical implementation. Do not add compatibility aliases, dual paths, historical-state
+  fallbacks, or sibling-source imports.
+
+## Testing
+
+- Test observable behavior at the owning boundary. Keep tests deterministic and independent of
+  execution order, ambient state, and live network services.
+- When testing dependency declarations, assert the required semver range shape or a shared policy
+  value instead of a Renovate-managed literal version. Assert an exact version only when the pin is
+  itself the contract under test.
+- Follow the range-shape patterns in the
+  [Devtools repository sync test](https://github.com/ankhorage/devtools/blob/main/src/cli/runRepositoryCommand.test.ts)
+  and [ZORA PR #313](https://github.com/ankhorage/zora/pull/313).
+- Run focused unit or integration tests before full E2E and smoke suites.
+- Do not rerun an unchanged E2E or smoke failure without a new hypothesis. After two unsuccessful
+  full reruns without a substantive code or configuration change, stop cycling, inspect logs and
+  artifacts, and report the blocker.
+
+## Paradox documentation
+
+- Give every named production function under `src` a concise Paradox `/*** ... */` description,
+  including internal helpers. Inline callbacks are exempt.
+- Add `@param`, `@returns`, `@example`, or `@readme` to public APIs only when the tag adds useful
+  information.
+- Update documentation sources and regenerate tracked Paradox output. Never hand-edit generated
+  README or Paradox artifacts.
+
+## Public API and release quality
+
+- Export public symbols intentionally from canonical entrypoints and exercise those exports in
+  tests. Do not introduce consumer deep imports.
+- Add the repository-required changeset for published behavior, package shape, dependency, or
+  public API changes.
+- Justify new dependencies and keep generated artifacts, lockfiles, and package metadata aligned
+  with the repository's owning workflows.
+- Review the final diff, then run the applicable build, lint, test, typecheck, Knip, format, docs,
+  changeset-status, and packaging checks.
+- Report the exact commands run and any omissions or failures. Do not imply a fully green handoff
+  when a required check did not run or pass.

package/dist/tools/skills/assets/ankhorage-coding-rules/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: 'Ankhorage Coding Rules'
+  short_description: 'Implement and deliver Ankhorage changes'
+  default_prompt: 'Use $ankhorage-coding-rules to implement and deliver this Ankhorage change.'
+
+policy:
+  allow_implicit_invocation: true

package/dist/tools/skills/assets/ankhorage-project-structure/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ankhorage-project-structure
+description: >
+  Design, review, or migrate the source structure of Ankhorage repositories and generated
+  applications. Use for directory ownership, package boundaries, architectural profiles,
+  ports and adapters, package CLI layout, repository skill distribution, public entrypoints,
+  or cross-repository cleanup.
+---
+
+# Ankhorage Project Structure
+
+Apply a repository profile instead of forcing one folder tree onto every package.
+
+Before deciding structure:
+
+1. Read the repository `AGENTS.md`, `package.json`, exports, source tree, and representative tests.
+2. Load `ankhorage-coding-rules` and `ankhorage-package-structure` when available.
+3. Identify the repository's owning capability and its profile below.
+4. Identify current public subpaths and cross-package release boundaries.
+
+Repository-specific rules may refine this skill, but must not silently reverse package ownership
+or dependency direction.
+
+## Primary boundary
+
+An Ankhorage repository/package is the primary bounded capability and independently released
+unit. Do not create a generic `src/features/` layer that imitates package boundaries.
+
+- Independently bindable capabilities belong in standalone packages.
+- Substantial responsibilities inside a package use cohesive domain directories directly under
+  `src/`.
+- Cross-package access uses published APIs and declared dependencies, never sibling source.
+- A package owns its application behavior; adapters belonging to another package are not copied
+  or proxied locally.
+
+## Select a profile
+
+Read [repository-profiles.md](references/repository-profiles.md), select one primary profile, and
+apply only the references routed by that profile.
+
+| Profile                            | Typical repositories                                          | Required references                                                                                        |
+| ---------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Application, engine, or hybrid     | Studio, Runtime, Orchestrator, Deploy, Infra                  | [hexagonal-architecture.md](references/hexagonal-architecture.md)                                          |
+| React Native / Expo application    | generated apps, Studio app host                               | [hexagonal-architecture.md](references/hexagonal-architecture.md), [expo-apps.md](references/expo-apps.md) |
+| Component or design-system library | ZORA, Surface                                                 | [ui-libraries.md](references/ui-libraries.md)                                                              |
+| Contracts or value library         | Contracts and other portable models                           | [repository-profiles.md](references/repository-profiles.md)                                                |
+| Utility library                    | Utility                                                       | [utilities.md](references/utilities.md)                                                                    |
+| Platform/provider adapter          | Expo Runtime, Supabase packages, orchestrator modules         | [repository-profiles.md](references/repository-profiles.md)                                                |
+| Tooling or CLI package             | Ankh, Doctor, Devtools and any package exposing Ankh commands | [cli.md](references/cli.md)                                                                                |
+
+When a package declares an Ankh provider or changes `src/cli/`, always read
+[cli.md](references/cli.md), regardless of its primary profile.
+
+When the task is a structural cleanup or migration, also read
+[migration.md](references/migration.md). For Studio specifically, read
+[studio.md](references/studio.md).
+
+When adding, distributing, or synchronizing repository-local agent skills, read
+[skill-distribution.md](references/skill-distribution.md).
+
+## Universal invariants
+
+- Keep only intentional package entrypoints and required declaration shims directly under `src/`.
+- Keep one abstraction level and responsibility among siblings.
+- Prefer domain ownership over technical dumping grounds such as `common`, `core`, `helpers`,
+  `misc`, or `shared`.
+- `app/`, `cli/`, `host/`, and `platform/` are package-level edges or composition areas, not
+  alternate owners of domain behavior.
+- Ports are owned by the application/domain code that requires the capability.
+- Adapters depend inward; domain/application code does not import concrete adapters.
+- Add a port only for a real external or replaceable boundary. Do not wrap every function in
+  architecture ceremony.
+- Colocate focused unit tests. Put cross-domain acceptance, E2E, smoke infrastructure, and large
+  fixtures outside production source.
+- Public package subpaths may point to nested source. Do not keep files at `src/` merely because
+  they are exported.
+- Preserve one canonical implementation. Do not add legacy paths, compatibility barrels, or
+  duplicate APIs to make a migration appear smaller.
+
+## Ownership decision
+
+For every file or new symbol, decide in order:
+
+1. Which Ankhorage package owns the capability?
+2. Which internal domain owns it?
+3. Is it core policy, application orchestration, a required port, an edge adapter, composition,
+   or a public entrypoint?
+4. Is it reusable enough to belong in `@ankhorage/utility` instead?
+
+If any answer is unclear, resolve ownership before moving or creating code.

package/dist/tools/skills/assets/ankhorage-project-structure/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: 'Ankhorage Project Structure'
+  short_description: 'Structure and migrate Ankhorage repositories'
+  default_prompt: 'Use $ankhorage-project-structure to design or review this Ankhorage repository structure.'
+
+policy:
+  allow_implicit_invocation: true