spovishun-skills 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-05-25
+
+First public release on npm.
+
+### Added
+
+- **CLI commands**
+  - `validate <skill-dir>` — validates a skill's `manifest.yaml` against the JSON Schema
+  - `init` — interactive wizard that generates `spovishun-skills.config.yaml`
+  - `install --target=<claude|codex|windsurf>` — installs filtered artefacts and writes the lockfile
+  - `sync` — re-applies the install from existing config + lockfile (no wizard)
+  - `update --upstream=<dir>` — three-way merge against an upstream copy (`--skill <id>`, `--dry-run`)
+  - `doctor` — validates installation integrity (config, lockfile, Notion ids, `.gitignore`, `settings.json`)
+- **Target adapters**
+  - Claude Code (native plugin via `.claude-plugin/` + `.claude/`)
+  - Codex (single `AGENTS.md` ≤ 32 KiB)
+  - Windsurf (one file per artifact under `.windsurf/rules/`, auto-split at 6 000 chars)
+- **Validation & schema**
+  - Manifest validation with Ajv 8 and JSON Schema 2020-12
+  - Consumer config schema (`schema/config.schema.json`)
+  - Conditional `requires:` rule (mandatory for `category: stack-specific`, forbidden for `universal`)
+- **Placeholders** — Mustache `{{KEY}}` substitution with `UPPER_SNAKE_CASE` key validation; non-matching tokens (e.g. `${{ runner.os }}`) preserved verbatim
+- **Stack filtering** — install only artifacts whose `requires:` flags are all enabled in the consumer config
+- **Lockfile** (`spovishun-skills.lock.yaml`) — pinned versions and SHA-256 checksums for reproducible installs
+
+### Bundled artifacts
+
+- 37 skills · 9 agents · 6 hooks (Claude only) · 6 rules
+
+### Known limitations
+
+- **Cursor adapter** — planned for 1.1
+- **`update --target=codex`** is a no-op. The monolithic `AGENTS.md` doesn't support per-artifact three-way merge; regenerate with `install --target=codex` instead.
+
+[1.0.0]: https://github.com/Astrumon/spovishun-skills/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danylo Bidnyk
+
+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.

package/README.md

@@ -0,0 +1,169 @@
+# spovishun-skills
+
+[![npm version](https://img.shields.io/npm/v/spovishun-skills.svg)](https://www.npmjs.com/package/spovishun-skills)
+[![license](https://img.shields.io/npm/l/spovishun-skills.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/spovishun-skills.svg)](https://nodejs.org)
+
+Portable [Claude Code](https://claude.com/claude-code) skills, agents, hooks and rules — extracted from the [Spovishun](https://github.com/Astrumon/SpovishunTelegramBotV2) project, packaged for reuse in any project.
+
+One canonical source. Multiple AI assistants. Configurable per project.
+
+## What you get
+
+A single `npx` command installs a curated set of:
+
+- **37 skills** — task decomposition, code review, Notion workflows, Kotlin/Postgres helpers, etc.
+- **9 agents** — specialized reviewers (architecture, refactor, docs, …)
+- **6 hooks** *(Claude only)* — session start/end, learning capture, Notion task injection
+- **6 rules** — design principles, git workflow, security, testing, Kotlin style
+
+Artifacts are filtered by your stack flags (kotlin / postgres / telegram / notion / docker) — you get only what's relevant to your project.
+
+## Supported targets
+
+| Target       | Status | Notes                                                              |
+|--------------|--------|--------------------------------------------------------------------|
+| Claude Code  | ✅     | Native plugin via `.claude-plugin/` + `.claude/`                   |
+| Codex        | ✅     | Single `AGENTS.md` at project root (≤ 32 KiB)                      |
+| Windsurf     | ✅     | One file per skill/rule under `.windsurf/rules/` (≤ 6 000 chars)   |
+| Cursor       | 🚧     | Planned for 1.1                                                    |
+
+## Quickstart
+
+```bash
+# 1. Generate your project config (interactive wizard)
+npx spovishun-skills@latest init
+
+# 2. Install artifacts for your target AI assistant
+npx spovishun-skills@latest install --target=claude
+
+# 3. Verify installation integrity
+npx spovishun-skills@latest doctor
+```
+
+After `install`, commit the generated `spovishun-skills.lock.yaml` to lock versions. Re-run `sync` on any machine to reproduce the exact same install.
+
+## Configuration
+
+`init` creates `spovishun-skills.config.yaml` in your project root:
+
+```yaml
+project:
+  name: "MyProject"
+  language: "uk"           # uk | en
+
+stack:
+  kotlin: true
+  postgres: false
+  telegram: true
+  notion: true
+  docker: false
+
+git:
+  branch_prefix: "feature/myproject"
+  main_branch: "main"
+  dev_branch: "develop"
+
+# Required only if stack.notion: true
+notion:
+  token_env: "NOTION_TOKEN"      # env var name, NOT the token value
+  database_id: "<32-hex-chars>"
+  epics_database_id: "<32-hex-chars>"
+```
+
+Schema is validated against [`schema/config.schema.json`](./schema/config.schema.json). Edit by hand or re-run `init` to overwrite.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Interactive wizard → `spovishun-skills.config.yaml` |
+| `install --target=<t>` | Generate target-specific files + write lockfile |
+| `sync` | Re-apply install from existing config + lockfile (no wizard, no merge) |
+| `update --upstream=<dir>` | Three-way merge against a fresh upstream copy of `spovishun-skills` |
+| `doctor` | Validate installation integrity (config, lockfile, Notion ids, `.gitignore`, `settings.json`) |
+| `validate <skill-dir>` | Validate a single skill's `manifest.yaml` against the JSON schema |
+
+Run `npx spovishun-skills --help` for full options.
+
+### `update` flags
+
+```bash
+npx spovishun-skills update --upstream=./node_modules/spovishun-skills
+# [--skill <id>]   limit to one artifact
+# [--dry-run]      print planned actions, write nothing
+```
+
+> **Codex limitation:** `update --target=codex` is a no-op (the monolithic `AGENTS.md` doesn't support per-artifact merge). Regenerate with `install --target=codex` instead.
+
+## How stack filtering works
+
+Each artifact's `manifest.yaml` declares which stack flags it needs:
+
+```yaml
+id: postgresql-exposed-orm
+category: stack-specific
+requires:
+  - kotlin
+  - postgres
+```
+
+An artifact installs **iff all `requires:` flags are `true`** in your `spovishun-skills.config.yaml`. Universal artifacts (no `requires:`) install for everyone.
+
+## Reproducible installs (lockfile)
+
+After `install`, `spovishun-skills.lock.yaml` is written to your project root. It pins exact versions + checksums of every installed artifact. **Commit this file** — `sync` and `update` both rely on it.
+
+```yaml
+version: 1
+generated_at: "2026-05-25T17:00:00Z"
+target: claude
+artifacts:
+  - id: code-reviewer
+    type: skill
+    version: 1.2.0
+    checksum: "sha256:…"
+  - …
+```
+
+## Placeholders
+
+Canonical artifact bodies use Mustache `{{KEY}}` placeholders for project-specific values (project name, language, Notion DB ids, etc.). Keys must be `UPPER_SNAKE_CASE`. Resolved at install time from your config.
+
+Tokens that don't match the pattern (e.g. GitHub Actions `${{ runner.os }}`) are preserved verbatim.
+
+## Requirements
+
+- Node.js ≥ 18
+- For Notion-tagged artifacts: a `NOTION_TOKEN` env var (or whatever name you set in `notion.token_env`)
+
+## Project structure (after install into a Claude project)
+
+```
+your-project/
+├── .claude-plugin/                  ← native plugin entry
+├── .claude/
+│   ├── skills/
+│   ├── agents/
+│   ├── hooks/
+│   ├── rules/
+│   └── settings.json
+├── spovishun-skills.config.yaml     ← editable, commit it
+└── spovishun-skills.lock.yaml       ← generated, commit it
+```
+
+For Codex: a single `AGENTS.md` at project root. For Windsurf: `.windsurf/rules/*.md`.
+
+## Contributing
+
+PRs welcome. See [`CLAUDE.md`](./CLAUDE.md) for architecture, layer rules, manifest schema, and commit convention.
+
+Branch: `feature/<short-slug>` · Commits: Conventional Commits (`feat:`, `fix:`, `refactor:`, …).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+[MIT](./LICENSE) © Danylo Bidnyk

package/adapters/claude/index.js

@@ -0,0 +1,123 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { filterByStack } from '../../lib/stack-filter.js';
+import { renderTemplate } from '../../lib/template-renderer.js';
+import { buildPlaceholderMap } from '../../lib/placeholder-map.js';
+import { sha256 } from '../../lib/checksum.js';
+import { mergeSettings } from '../../lib/settings-merger.js';
+
+/**
+ * Installs filtered artifacts into the consumer's .claude/ directory.
+ *
+ * @param {object} opts
+ * @param {string}   opts.consumerCwd   — absolute path to consumer project root
+ * @param {string}   opts.pkgRoot       — absolute path to this package's root (for hooks/ and rules/)
+ * @param {object}   opts.config        — validated consumer config object
+ * @param {Array}    opts.artifacts     — all loaded artifacts from loadArtifacts()
+ * @returns {Array<{kind, id, version, checksum}>}  — lockfile entries for installed artifacts
+ */
+export async function installClaude({ consumerCwd, pkgRoot, config, artifacts }) {
+  const filtered = filterByStack(artifacts, config.stack ?? {});
+  const configMap = buildPlaceholderMap(config);
+
+  const claudeDir = join(consumerCwd, '.claude');
+  mkdirSync(claudeDir, { recursive: true });
+  mkdirSync(join(claudeDir, 'skills'), { recursive: true });
+  mkdirSync(join(claudeDir, 'agents'), { recursive: true });
+  mkdirSync(join(claudeDir, 'hooks'), { recursive: true });
+  mkdirSync(join(claudeDir, 'rules'), { recursive: true });
+
+  const lockEntries = [];
+
+  for (const artifact of filtered) {
+    const manifestPlaceholders = (artifact.manifest?.placeholders ?? []).map((p) => p.key);
+    const rendered = renderTemplate(artifact.bodyText, { configMap, manifestPlaceholders });
+    const checksum = sha256(rendered);
+
+    if (artifact.kind === 'skill') {
+      const outPath = join(claudeDir, 'skills', `${artifact.id}.md`);
+      writeFileSync(outPath, rendered, 'utf8');
+    } else if (artifact.kind === 'agent') {
+      const outPath = join(claudeDir, 'agents', `${artifact.id}.md`);
+      writeFileSync(outPath, rendered, 'utf8');
+    }
+
+    lockEntries.push({ kind: artifact.kind, id: artifact.id, version: artifact.version, checksum });
+  }
+
+  // Always ensure settings.json exists, even with no plugin hooks
+  patchSettings(claudeDir, {});
+  installHooks(pkgRoot, claudeDir);
+  installRules(pkgRoot, claudeDir);
+
+  return lockEntries;
+}
+
+/**
+ * Copies all hook scripts from hooks/ to .claude/hooks/ and merges hooks.json
+ * event mappings into .claude/settings.json.
+ */
+function installHooks(pkgRoot, claudeDir) {
+  const hooksDir = join(pkgRoot, 'hooks');
+  if (!existsSync(hooksDir)) return;
+
+  const hooksJsonPath = join(hooksDir, 'hooks.json');
+  if (!existsSync(hooksJsonPath)) return;
+
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
+  } catch {
+    return;
+  }
+
+  // Copy all .js scripts verbatim
+  const scripts = readdirSync(hooksDir).filter((f) => f.endsWith('.js'));
+  for (const script of scripts) {
+    copyFileSync(join(hooksDir, script), join(claudeDir, 'hooks', script));
+  }
+
+  // Merge event entries from hooks.json into settings.json
+  const pluginHooks = hooksJson.hooks ?? {};
+  patchSettings(claudeDir, pluginHooks);
+}
+
+/**
+ * Copies all .md rule files from rules/ into .claude/rules/, preserving subdirectory structure.
+ */
+function installRules(pkgRoot, claudeDir) {
+  const rulesDir = join(pkgRoot, 'rules');
+  if (!existsSync(rulesDir)) return;
+
+  copyRulesRecursive(rulesDir, rulesDir, claudeDir);
+}
+
+function copyRulesRecursive(baseDir, currentDir, claudeDir) {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const srcPath = join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      copyRulesRecursive(baseDir, srcPath, claudeDir);
+    } else if (entry.name.endsWith('.md')) {
+      const rel = relative(baseDir, srcPath);
+      const destPath = join(claudeDir, 'rules', rel);
+      mkdirSync(join(destPath, '..'), { recursive: true });
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function patchSettings(claudeDir, pluginHooks) {
+  const settingsPath = join(claudeDir, 'settings.json');
+  let existing = {};
+  if (existsSync(settingsPath)) {
+    try {
+      existing = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      existing = {};
+    }
+  }
+
+  const merged = mergeSettings(existing, pluginHooks);
+  writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}

package/adapters/claude/update.js

@@ -0,0 +1,41 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { threeWayMerge } from '../../lib/three-way-merge.js';
+
+/**
+ * Writes or merges a single artifact for the claude target.
+ *
+ * - AUTO_APPLY / NEW  (conflict=false): overwrites <kind>s/<id>.md with upstream content
+ * - CONFLICT          (conflict=true):  writes conflict markers into the file
+ *
+ * @param {object} opts
+ * @param {string}  opts.consumerCwd    — consumer project root
+ * @param {object}  opts.upstreamEntry  — { artifact: {kind, id}, rendered: string }
+ * @param {object}  [opts.installedEntry] — { content: string, paths: string[] } or null
+ * @param {boolean} opts.conflict
+ * @param {string}  [opts.oursLabel]
+ * @param {string}  [opts.theirsLabel]
+ */
+export async function updateClaude({
+  consumerCwd,
+  upstreamEntry,
+  installedEntry = null,
+  conflict,
+  oursLabel = 'ours',
+  theirsLabel = 'theirs',
+}) {
+  const { artifact, rendered } = upstreamEntry;
+  const subdir = artifact.kind === 'skill' ? 'skills' : 'agents';
+  const outDir = join(consumerCwd, '.claude', subdir);
+  mkdirSync(outDir, { recursive: true });
+  const outPath = join(outDir, `${artifact.id}.md`);
+
+  if (!conflict) {
+    writeFileSync(outPath, rendered, 'utf8');
+    return;
+  }
+
+  const ours = installedEntry ? installedEntry.content : rendered;
+  const { content } = threeWayMerge({ ours, theirs: rendered, oursLabel, theirsLabel });
+  writeFileSync(outPath, content, 'utf8');
+}

package/adapters/codex/build-agents-md.js

@@ -0,0 +1,135 @@
+import { renderTemplate } from '../../lib/template-renderer.js';
+
+const HEADING_DEMOTE = 2;
+
+/**
+ * Builds the AGENTS.md content string for Codex from filtered artifacts.
+ * Pure function — no filesystem access.
+ *
+ * @param {object} opts
+ * @param {Array}   opts.artifacts     — stack-filtered artifacts (skills, agents)
+ * @param {Array}   [opts.rules]       — rule files: { id, body }; sorted by id
+ * @param {object}  opts.config        — validated consumer config
+ * @param {Map}     opts.configMap     — placeholder map from buildPlaceholderMap()
+ * @param {string}  opts.pluginVersion — version string for the header
+ * @returns {string}                   — full AGENTS.md text
+ */
+export function buildAgentsMd({ artifacts, rules = [], config, configMap, pluginVersion }) {
+  const skills = artifacts.filter((a) => a.kind === 'skill');
+  const agents = artifacts.filter((a) => a.kind === 'agent');
+
+  const lines = [];
+  lines.push(...renderHeader(config, pluginVersion));
+  lines.push(...renderProjectContext(config));
+
+  if (skills.length > 0) {
+    lines.push('## Skills', '');
+    for (const skill of skills) {
+      lines.push(...renderArtifact(skill, configMap));
+    }
+  }
+
+  if (agents.length > 0) {
+    lines.push('## Agents', '');
+    for (const agent of agents) {
+      lines.push(...renderArtifact(agent, configMap));
+    }
+  }
+
+  if (rules.length > 0) {
+    lines.push('## Rules', '');
+    for (const rule of rules) {
+      lines.push(...renderRule(rule, configMap));
+    }
+  }
+
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
+function renderRule(rule, configMap) {
+  const rendered = renderTemplate(rule.body, { configMap });
+  const demoted = demoteHeadings(rendered, HEADING_DEMOTE);
+  return [`### ${rule.id}`, '', demoted.trimEnd(), ''];
+}
+
+function renderHeader(config, pluginVersion) {
+  const name = config.project?.name ?? 'Project';
+  return [
+    `# ${name} — Agent Instructions`,
+    '',
+    `> Generated by spovishun-skills v${pluginVersion}. Do not edit manually — re-run \`spovishun-skills install --target=codex\` instead.`,
+    '',
+  ];
+}
+
+function renderProjectContext(config) {
+  const lines = ['## Project context', ''];
+  if (config.project?.language) {
+    lines.push(`- Language: ${config.project.language}`);
+  }
+  const activeFlags = Object.entries(config.stack ?? {})
+    .filter(([, v]) => v === true)
+    .map(([k]) => k);
+  if (activeFlags.length > 0) {
+    lines.push(`- Tech stack: ${activeFlags.join(' | ')}`);
+  }
+  if (config.git?.branch_prefix) {
+    lines.push(`- Git branch prefix: \`${config.git.branch_prefix}\``);
+  }
+  lines.push('');
+  return lines;
+}
+
+function renderArtifact(artifact, configMap) {
+  const body = prepareBody(artifact);
+  const manifestPlaceholders = (artifact.manifest?.placeholders ?? []).map((p) => p.key);
+  const rendered = renderTemplate(body, { configMap, manifestPlaceholders });
+  const demoted = demoteHeadings(rendered, HEADING_DEMOTE);
+  return [
+    `### ${artifact.id} (v${artifact.version})`,
+    '',
+    demoted.trimEnd(),
+    '',
+  ];
+}
+
+/**
+ * Strips a leading YAML frontmatter block (--- ... ---) if present.
+ * AGENT.md files use Claude-specific frontmatter (tools, model, maxTurns) that
+ * Codex cannot interpret, so we drop it to keep the output clean.
+ */
+function prepareBody(artifact) {
+  const text = artifact.bodyText;
+  if (!text.startsWith('---\n')) return text;
+  const end = text.indexOf('\n---', 4);
+  if (end === -1) return text;
+  return text.slice(end + 4).replace(/^\r?\n/, '');
+}
+
+/**
+ * Adds `levels` extra `#` to each ATX heading so artifact bodies nest under
+ * the top-level AGENTS.md sections without collision. Caps at h6.
+ * Code fences are skipped so headings inside ```...``` blocks remain intact.
+ */
+function demoteHeadings(text, levels) {
+  const out = [];
+  let inFence = false;
+  for (const line of text.split('\n')) {
+    const fenceMatch = line.match(/^(\s*)(```|~~~)/);
+    if (fenceMatch) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    if (!inFence) {
+      const m = line.match(/^(#{1,6})(\s)/);
+      if (m) {
+        const newLevel = Math.min(6, m[1].length + levels);
+        out.push('#'.repeat(newLevel) + m[2] + line.slice(m[0].length));
+        continue;
+      }
+    }
+    out.push(line);
+  }
+  return out.join('\n');
+}

package/adapters/codex/index.js

@@ -0,0 +1,109 @@
+import { writeFileSync, readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { Buffer } from 'node:buffer';
+import { filterByStack } from '../../lib/stack-filter.js';
+import { buildPlaceholderMap } from '../../lib/placeholder-map.js';
+import { sha256 } from '../../lib/checksum.js';
+import { buildAgentsMd } from './build-agents-md.js';
+
+export const AGENTS_MD_FILENAME = 'AGENTS.md';
+export const SIZE_LIMIT_BYTES = 32 * 1024;
+
+const CODEX_KINDS = new Set(['skill', 'agent']);
+
+/**
+ * Generates AGENTS.md for Codex at the consumer project root.
+ *
+ * Skips hooks and other Claude-only artifacts. Renders Mustache placeholders
+ * the same way the Claude adapter does. If the resulting file exceeds the
+ * 32 KiB AGENTS.md soft limit, emits a stderr warning but still writes the file.
+ *
+ * @param {object} opts
+ * @param {string}   opts.consumerCwd    — absolute path to consumer project root
+ * @param {string}   opts.pkgRoot        — absolute path to the spovishun-skills package root (for rules/)
+ * @param {object}   opts.config         — validated consumer config
+ * @param {Array}    opts.artifacts      — all loaded artifacts from loadArtifacts()
+ * @param {string}   opts.pluginVersion  — version string for the AGENTS.md header
+ * @param {object}   [opts.warn]         — writable stream for warnings (default: process.stderr)
+ * @returns {Array<{kind, id, version, checksum}>} — lockfile entries for included artifacts
+ */
+export async function installCodex({
+  consumerCwd,
+  pkgRoot,
+  config,
+  artifacts,
+  pluginVersion,
+  warn = process.stderr,
+}) {
+  const stackFiltered = filterByStack(artifacts, config.stack ?? {});
+  const included = stackFiltered.filter((a) => CODEX_KINDS.has(a.kind));
+  const rules = collectRules(pkgRoot);
+  const configMap = buildPlaceholderMap(config);
+
+  const content = buildAgentsMd({
+    artifacts: included,
+    rules,
+    config,
+    configMap,
+    pluginVersion,
+  });
+
+  const outPath = join(consumerCwd, AGENTS_MD_FILENAME);
+  writeFileSync(outPath, content, 'utf8');
+
+  const byteSize = Buffer.byteLength(content, 'utf8');
+  if (byteSize > SIZE_LIMIT_BYTES) {
+    const kib = (byteSize / 1024).toFixed(1);
+    warn.write(
+      `Warning: AGENTS.md is ${kib} KiB (>32 KiB Codex soft limit). Codex may truncate. ` +
+        `Consider splitting universal/global instructions into ~/.codex/AGENTS.md and ` +
+        `keeping project-specific content in ./AGENTS.md.\n`
+    );
+  }
+
+  const artifactEntries = included.map((artifact) => ({
+    kind: artifact.kind,
+    id: artifact.id,
+    version: artifact.version,
+    checksum: sha256(artifact.bodyText),
+  }));
+
+  const ruleEntries = rules.map((rule) => ({
+    kind: 'rule',
+    id: rule.id,
+    version: '0.0.0',
+    checksum: sha256(rule.body),
+  }));
+
+  return [...artifactEntries, ...ruleEntries];
+}
+
+/**
+ * Walks pkgRoot/rules/ recursively and returns each .md file as a flat list.
+ * Rules in this repo are data files (not artifact-loader entries), so we walk
+ * them directly the same way installClaude does.
+ */
+function collectRules(pkgRoot) {
+  if (!pkgRoot) return [];
+  const rulesDir = join(pkgRoot, 'rules');
+  if (!existsSync(rulesDir)) return [];
+
+  const collected = [];
+  walk(rulesDir, rulesDir, collected);
+  collected.sort((a, b) => a.id.localeCompare(b.id));
+  return collected;
+}
+
+function walk(baseDir, currentDir, out) {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const fullPath = join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      walk(baseDir, fullPath, out);
+    } else if (entry.name.endsWith('.md')) {
+      const rel = relative(baseDir, fullPath).split(/[\\/]/).join('/');
+      const id = rel.replace(/\.md$/, '');
+      out.push({ id, body: readFileSync(fullPath, 'utf8') });
+    }
+  }
+}