@ankhorage/devtools 1.8.5 → 1.9.1

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
 

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

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

@@ -0,0 +1,117 @@
+# Ankhorage Package CLI
+
+An Ankhorage package may expose one package-level Ankh command provider under `src/cli/`. The
+package is the CLI ownership boundary.
+
+Do not create `cli/` directories inside internal domains. An independently bound package owns its
+own package-level `src/cli/` and release lifecycle.
+
+## Command tree
+
+The filesystem below `src/cli/commands/` mirrors the public command path after the package prefix.
+
+```text
+ankh <package> <segment> ... <command>
+  -> src/cli/commands/<segment>/.../<command>.ts
+```
+
+Examples:
+
+```text
+ankh studio dev
+  -> src/cli/commands/dev.ts
+
+ankh studio projects list
+  -> src/cli/commands/projects/list.ts
+
+ankh studio projects create --name Shop
+  -> src/cli/commands/projects/create.ts
+
+ankh deploy release inspect
+  -> src/cli/commands/release/inspect.ts
+```
+
+The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
+positional arguments do not affect the directory tree.
+
+Bad:
+
+```text
+src/cli/commands/studio/projects/list.ts
+src/cli/commands/listProjects.ts
+src/projects/cli/list.ts
+```
+
+Good:
+
+```text
+src/cli/commands/projects/list.ts
+```
+
+## Layout
+
+```text
+src/
+  cli/
+    index.ts
+    commands/
+      <command>.ts
+      <group>/
+        <command>.ts
+```
+
+`src/cli/index.ts` owns provider identity, category, capabilities, command definitions, handler
+registration, and package-level composition. It contains no substantial command implementation.
+
+Each leaf command module owns one command handler and its command-specific argument/output mapping.
+Tests are colocated:
+
+```text
+src/cli/commands/projects/list.ts
+src/cli/commands/projects/list.test.ts
+```
+
+Do not add command-group barrels unless the group intentionally exposes an API or requires genuine
+composition.
+
+## Naming exception
+
+Command filenames follow public CLI segments rather than exported handler names:
+
+```text
+command:  ankh studio projects list
+file:     src/cli/commands/projects/list.ts
+handler:  listProjects
+```
+
+This is an intentional exception to primary-symbol filenames. It applies only to CLI command leaf
+modules.
+
+## Adapter boundary
+
+A handler may parse `request.argv`, use the provided command context, call package-owned
+application operations, translate failures into command results, and create the package
+composition needed for the invocation.
+
+A handler must not:
+
+- implement domain rules;
+- duplicate application behavior;
+- implement substantial filesystem, network, process, database, credential, or provider logic;
+- proxy behavior owned by another package to place it under the local prefix;
+- preserve removed commands through aliases or hidden handlers.
+
+## Capabilities and public metadata
+
+Keep provider metadata, command definitions, handler paths, public exports, documentation, and
+tests synchronized. Remove unused capabilities when a command disappears. Published command or
+metadata changes require the repository's normal changeset treatment.
+
+## Standalone generated applications
+
+Generated applications own their installation, validation, build, and runtime commands. Execute
+the generated application's canonical command with that application as `cwd`.
+
+Studio must not own a parallel workspace-install command or assume generated applications are
+Studio workspace members. Do not preserve obsolete workspace commands, capabilities, handlers,
+tests, or documentation after the standalone architecture replaces them.