{"_id":"@akinlabs/ai-engineering","_rev":"3-844c67dc911b3578efd057a45367f248","name":"@akinlabs/ai-engineering","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@akinlabs/ai-engineering","version":"0.1.0","keywords":["ai","ai-engineering","ai-coding","claude-code","codex","developer-tools","compiler"],"author":{"name":"Akin Oztorun"},"license":"MIT","_id":"@akinlabs/ai-engineering@0.1.0","maintainers":[{"name":"akino_","email":"akinoztorun@gmail.com"}],"homepage":"https://github.com/akin-oz/ai-engineering#readme","bugs":{"url":"https://github.com/akin-oz/ai-engineering/issues"},"bin":{"ai":"bin/ai.mjs"},"dist":{"shasum":"cf1b03afca634638c2f36b71340b240c899bc2be","tarball":"https://registry.npmjs.org/@akinlabs/ai-engineering/-/ai-engineering-0.1.0.tgz","fileCount":17,"integrity":"sha512-LOf/udEdWfP9IIoHzAUU94jneZrm91CJx+/5FjOSH4aiN/TQCSYkBpY9RDIMnf6W4aTpEWtaFguhlC2pwQXBDg==","signatures":[{"sig":"MEUCIQC4vx+M3OnlSortTt81FLltpKZemFfm2bkUs3JAcu8UcQIgCy4fNnqVjpa8KZjkr7gQc6CYaT1Xtf4k29jSGi+f4N8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25333},"type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"funding":{"url":"https://github.com/sponsors/akin-oz","type":"individual"},"gitHead":"77dca797d113cb3cefea8f8e4a9b85b6b97ffaf2","scripts":{"test":"node --test","check":"node --check bin/ai.mjs && node --check src/index.mjs && node --check src/cli/run.mjs"},"_npmUser":{"name":"akino_","email":"akinoztorun@gmail.com"},"repository":{"url":"git+https://github.com/akin-oz/ai-engineering.git","type":"git"},"_npmVersion":"10.9.2","description":"Compile tool-agnostic .ai workspaces into AI coding assistant runtimes.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"yaml":"^2.8.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ai-engineering_0.1.0_1785661018669_0.29811844730455594","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@akinlabs/ai-engineering","version":"0.1.1","keywords":["ai","ai-engineering","ai-coding","claude-code","codex","developer-tools","compiler"],"author":{"name":"Akin Oztorun"},"license":"MIT","_id":"@akinlabs/ai-engineering@0.1.1","maintainers":[{"name":"akino_","email":"akinoztorun@gmail.com"}],"homepage":"https://github.com/akin-oz/ai-engineering#readme","bugs":{"url":"https://github.com/akin-oz/ai-engineering/issues"},"bin":{"ai":"bin/ai.mjs"},"dist":{"shasum":"2f5f8c5682871abf1b6351c7c7b0f9ed4adceaa4","tarball":"https://registry.npmjs.org/@akinlabs/ai-engineering/-/ai-engineering-0.1.1.tgz","fileCount":18,"integrity":"sha512-bmqWwSZ28l/lwoWrrtTDiHvQoBxnWdIMOKNiRzkOhfivHZR1HSWTz0xwIDXE9StONSfP5lj+Kfg51RgaOaiK2A==","signatures":[{"sig":"MEUCIQDC7BVf4swDC9FsSAtPyT/5LZBNl+KVdF2CZQdksi1fSQIgTfzyoPUbbbFymXN3AWiCyNwppSVUFzcA2yluuL1rA+U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27625},"type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"funding":{"url":"https://github.com/sponsors/akin-oz","type":"individual"},"gitHead":"700cd411453862ef3cde34d3fc32fd83eb47052c","scripts":{"test":"node --test","check":"node --check bin/ai.mjs && node --check src/index.mjs && node --check src/cli/run.mjs"},"_npmUser":{"name":"akino_","email":"akinoztorun@gmail.com"},"repository":{"url":"git+https://github.com/akin-oz/ai-engineering.git","type":"git"},"_npmVersion":"10.9.2","description":"Compile tool-agnostic .ai workspaces into AI coding assistant runtimes.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"yaml":"^2.8.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ai-engineering_0.1.1_1785661654074_0.5020904965118638","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@akinlabs/ai-engineering@0.2.0","bin":{"ai":"bin/ai.mjs","aie":"bin/aie.mjs"},"bugs":{"url":"https://github.com/akin-oz/ai-engineering/issues"},"dist":{"shasum":"d2cc8ca79986974c8a50b1cf8700127825ef442b","tarball":"https://registry.npmjs.org/@akinlabs/ai-engineering/-/ai-engineering-0.2.0.tgz","integrity":"sha512-ucDiTxfPSzPs1GwnGliil2pcZGPqO7/3RFlEkl8ZEY+PucEisQkFD1p9MjVOS6QlZ29SI/kBRfeSXUgQzbo2og==","fileCount":41,"unpackedSize":123591,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICd3EZza/ZnkabijOIkeAs27llXg7HUiSBsjtl/8OjmcAiA5srSN8xeiyI53+mNNYp3r+8BY/iz7n9XCvfK3pVGnXw=="}]},"name":"@akinlabs/ai-engineering","type":"module","author":{"name":"Akin Oztorun"},"engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"funding":{"url":"https://github.com/sponsors/akin-oz","type":"individual"},"gitHead":"fdeb7895a4d669606496587419f0a799090a7ed6","license":"MIT","scripts":{"test":"node --test","check":"node --check bin/aie.mjs && node --check bin/ai.mjs && node --check src/index.mjs && node --check src/cli/run.mjs","verify:dogfood":"node scripts/verify-dogfood.mjs"},"version":"0.2.0","_npmUser":{"name":"akino_","email":"akinoztorun@gmail.com","approver":{"name":"akino_","email":"akinoztorun@gmail.com"}},"homepage":"https://github.com/akin-oz/ai-engineering#readme","keywords":["ai","ai-engineering","ai-coding","claude-code","codex","developer-tools","compiler"],"repository":{"url":"git+https://github.com/akin-oz/ai-engineering.git","type":"git"},"_npmVersion":"11.17.0","description":"Compile tool-agnostic .ai workspaces into AI coding assistant runtimes.","directories":{},"maintainers":[{"name":"akino_","email":"akinoztorun@gmail.com"}],"_nodeVersion":"26.5.1","dependencies":{"yaml":"^2.8.1"},"publishConfig":{"access":"public"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-engineering_0.2.0_1786031719771_0.6376091463496665"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-02T08:56:58.511Z","modified":"2026-08-06T15:55:20.118Z","0.1.0":"2026-08-02T08:56:58.824Z","0.1.1":"2026-08-02T09:07:34.226Z","0.2.0":"2026-08-06T15:55:19.869Z"},"bugs":{"url":"https://github.com/akin-oz/ai-engineering/issues"},"author":{"name":"Akin Oztorun"},"license":"MIT","homepage":"https://github.com/akin-oz/ai-engineering#readme","keywords":["ai","ai-engineering","ai-coding","claude-code","codex","developer-tools","compiler"],"repository":{"url":"git+https://github.com/akin-oz/ai-engineering.git","type":"git"},"description":"Compile tool-agnostic .ai workspaces into AI coding assistant runtimes.","maintainers":[{"name":"akino_","email":"akinoztorun@gmail.com"}],"readme":"# AI Engineering Compiler\n\n> Keep AI assistant instructions in one reviewable source tree. Compile them for\n> Claude Code and Codex.\n\n[![npm version](https://img.shields.io/npm/v/%40akinlabs%2Fai-engineering)](https://www.npmjs.com/package/@akinlabs/ai-engineering)\n[![npm downloads](https://img.shields.io/npm/dm/%40akinlabs%2Fai-engineering)](https://www.npmjs.com/package/@akinlabs/ai-engineering)\n[![CI](https://github.com/akin-oz/ai-engineering/actions/workflows/ci.yml/badge.svg)](https://github.com/akin-oz/ai-engineering/actions/workflows/ci.yml)\n[![Node.js](https://img.shields.io/node/v/%40akinlabs%2Fai-engineering)](https://www.npmjs.com/package/@akinlabs/ai-engineering)\n[![License](https://img.shields.io/github/license/akin-oz/ai-engineering)](LICENSE)\n\n## The problem\n\nAI coding assistants each want instructions in a different place and format.\nCopying a few rules into `CLAUDE.md` and `AGENTS.md` is simple at first. It stops\nbeing simple when the same policy lives in five generated places, because the\nfailure is quiet: someone tightens a rule in one file, nothing errors, and the\nassistants start giving different advice depending on which one you opened.\n\nThis compiler keeps project intent in `.ai/` and generates the runtime files\nfrom it. Generated files stay visible and commit-ready — they are just never\nedited by hand.\n\n**Most repositories do not need this.** If one prose file covers your\ninstructions, symlink `CLAUDE.md` to `AGENTS.md` and stop there. See\n[docs/comparison.md](docs/comparison.md) for honest comparisons against\nsymlinks, the AGENTS.md standard, rulesync, and doing nothing.\n\n## Quick start\n\n```sh\nnpm install --save-dev @akinlabs/ai-engineering\nnpx aie init\nnpx aie sync\n```\n\n`aie init` creates a `.ai/` workspace with a starter rule, without overwriting\nanything. `aie sync` compiles it:\n\n    .ai/                              CLAUDE.md\n    ├── manifest.yaml       ──►       AGENTS.md\n    ├── rules/                        .claude/agents/\n    ├── agents/                       .claude/commands/\n    └── commands/\n\nBoth runtimes load their instructions from the repository root, so `CLAUDE.md`\nand `AGENTS.md` are the files that actually get read.\n\nIn CI, fail the build when generated files drift from their source:\n\n```sh\nnpx aie check\n```\n\n## It will not overwrite your work\n\n`aie sync` may only delete or replace a file it can prove it generated: one\nlisted in its ownership record (`.ai/state/targets/`), one whose bytes still\nmatch the source it was copied from, or one carrying the generated banner.\n\nAnything else is reported and the sync stops before writing:\n\n    Refusing to overwrite files this workspace does not own:\n\n      CLAUDE.md (claude)\n\n    Move them aside, or run with --force to overwrite them and take ownership.\n\nYour existing `.claude/settings.json` and hand-written commands survive every\nsync. Nothing is skipped silently either — a source a runtime cannot express\nproduces a diagnostic naming it, on every run.\n\n## Already have CLAUDE.md and AGENTS.md?\n\nImport them instead of starting over:\n\n```sh\nnpx aie adopt\n```\n\nAdopt is a dry run by default. It splits your existing instruction files into\n`.ai/` sources, flags pairs that look like the same policy written twice, and\nnever modifies the originals. `--write` applies the plan. See\n[examples/adopt-existing](examples/adopt-existing) for the walkthrough.\n\n## Commands\n\n| Command | Behavior | Exit codes |\n| --- | --- | --- |\n| `aie init` | Create a `.ai` workspace with a starter rule | 0 |\n| `aie adopt` | Import existing assistant files (dry run by default) | 0 |\n| `aie sync` | Compile enabled targets | 0, 1 on failure |\n| `aie check` | Report drift without writing | 0 clean, 1 drift, 2 broken workspace |\n| `aie validate` | Validate the workspace without comparing output | 0, 1 on failure |\n| `aie explain` | Show what a workflow contributed and where it lands | 0 |\n\nOptions: `--strict` (warnings become errors), `--force` (overwrite unowned\nfiles), `--write` (apply an adoption), `--blueprint`, `--dry-run`, `--json`.\n\n## In CI\n\n```yaml\n- uses: akin-oz/ai-engineering@v0\n```\n\nThe action runs `aie check`, annotates the drifted files on the pull request,\nand fails the job. It writes nothing.\n\n## Supported runtimes\n\n| Runtime | Rules | Agents | Commands | Hooks |\n| --- | --- | --- | --- | --- |\n| Claude Code | `CLAUDE.md` | `.claude/agents/` | `.claude/commands/` | `.claude/hooks/` + `settings.json` |\n| Codex | `AGENTS.md` | inlined | — | — |\n| Cursor | `.cursor/rules/*.mdc` | — | — | — |\n\nA dash means the runtime has no format for it. The compiler says so on every\nrun rather than dropping the source silently.\n\nHooks are declared in the manifest with a normalized event\n(`pre-edit`, `post-edit`, `session-start`, `session-end`) and wired into\n`.claude/settings.json` — the compiler owns only the entries it wrote there and\npreserves the rest of your settings.\n\n## Compiling a workflow instead of listing files\n\n`aie init --blueprint` writes a `.ai/blueprint.yaml` that names an engineering\nworkflow rather than individual files:\n\n```yaml\nschema: 2\nproject:\n  type: library\nworkflow:\n  development: spec-driven\nai:\n  runtimes: [claude, codex]\n```\n\n`aie sync` composes that workflow into `.ai/generated/` — agents, rules,\ncommands, and templates, committed and reviewable — then compiles it for each\nruntime. `aie explain` shows what came from where. Your own files in `.ai/`\ncompile alongside it.\n\nOne workflow ships today (`spec-driven`). More arrive when this one has proven\nuseful in real repositories, not before.\n\n## Examples\n\n- [examples/basic](examples/basic) — smallest complete workspace\n- [examples/typescript-library](examples/typescript-library) — the case where\n  hand-maintenance actually fails\n- [examples/adopt-existing](examples/adopt-existing) — a repository already\n  carrying drifted instruction files, and how to import it\n\nThis repository compiles itself: [CLAUDE.md](CLAUDE.md) and [AGENTS.md](AGENTS.md)\nare generated from [.ai/](.ai), and CI fails if they drift or if any source file\nis empty.\n\n## Documentation\n\n- [docs/](docs) — shipped behavior: [architecture](docs/architecture.md),\n  [public API](docs/api.md), [adapter contract](docs/adapter-api.md),\n  [writing an adapter](docs/writing-an-adapter.md),\n  [comparisons](docs/comparison.md)\n- [specs/](specs) — scoped work that is committed but not finished\n- [rfcs/](rfcs) — design that may never be built\n\nThat split is deliberate: 0.1 documented features that did not exist, which made\nthe real claims harder to trust.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md). Report security concerns per\n[SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}