{"_id":"@empratur256/ai-workspace","name":"@empratur256/ai-workspace","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@empratur256/ai-workspace","version":"0.1.0","description":"Local-first AI context layer for projects and workspaces. Canonical .ai/ knowledge for Cursor, Claude, Codex, and custom agents — without vendor lock-in.","type":"module","bin":{"aiw":"dist/cli/index.js"},"main":"./dist/core/index.js","types":"./dist/core/index.d.ts","exports":{".":"./dist/core/index.js"},"engines":{"node":">=20"},"scripts":{"build":"tsc -p tsconfig.build.json && node scripts/copy-definitions.mjs","clean":"node -e \"const fs=require('fs'); for (const d of ['dist','dist-test']) fs.rmSync(d,{recursive:true,force:true})\"","test":"npm run build && tsc -p tsconfig.test.json && node scripts/run-tests.mjs","aiw":"node dist/cli/index.js","prepublishOnly":"npm test"},"keywords":["ai","ai-workspace","ai-context","ai-agents","agent-context","cursor","claude","codex","developer-tools","context-management","workspace","cli"],"homepage":"https://github.com/kamranshalilian/AI-Workspace#readme","repository":{"type":"git","url":"git+https://github.com/kamranshalilian/AI-Workspace.git"},"bugs":{"url":"https://github.com/kamranshalilian/AI-Workspace/issues"},"license":"MIT","author":{"name":"Kamran Shalilian","url":"https://github.com/kamranshalilian"},"dependencies":{"minimatch":"^10.0.3","yaml":"^2.8.1"},"devDependencies":{"@types/node":"^24.3.0","typescript":"^5.9.2"},"gitHead":"4ec2b44d72c40b98fcc765e61eb6167f83603ade","_id":"@empratur256/ai-workspace@0.1.0","_nodeVersion":"24.11.0","_npmVersion":"11.19.1","dist":{"integrity":"sha512-peYtb2q8lujyLgYGMNRkNc+Q5rsVWKIefC0HuQ5sE8G7Xq56HKMgZJLuC8BF1miZ1vFCWdZmYfwV2KWuEdFCRQ==","shasum":"0670401154da4e41afc40ac858acc128a33e2c15","tarball":"https://registry.npmjs.org/@empratur256/ai-workspace/-/ai-workspace-0.1.0.tgz","fileCount":192,"unpackedSize":508890,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDoeN3wTVhzfIsUnWzmoyCY/Bu/hcWYPTlxBdYN1toRtQIgYGtRVi9NH51qgBD+A/JjBkhsjfcwIstozsEkwDYB/aI="}]},"_npmUser":{"name":"empratur256","email":"shaliliankamran@gmail.com"},"directories":{},"maintainers":[{"name":"empratur256","email":"shaliliankamran@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-workspace_0.1.0_1788941035045_0.2997898859302526"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-09T08:03:54.782Z","0.1.0":"2026-09-09T08:03:55.215Z","modified":"2026-09-09T08:03:55.427Z"},"maintainers":[{"name":"empratur256","email":"shaliliankamran@gmail.com"}],"description":"Local-first AI context layer for projects and workspaces. Canonical .ai/ knowledge for Cursor, Claude, Codex, and custom agents — without vendor lock-in.","homepage":"https://github.com/kamranshalilian/AI-Workspace#readme","keywords":["ai","ai-workspace","ai-context","ai-agents","agent-context","cursor","claude","codex","developer-tools","context-management","workspace","cli"],"repository":{"type":"git","url":"git+https://github.com/kamranshalilian/AI-Workspace.git"},"author":{"name":"Kamran Shalilian","url":"https://github.com/kamranshalilian"},"bugs":{"url":"https://github.com/kamranshalilian/AI-Workspace/issues"},"license":"MIT","readme":"# AI Workspace\n\n[![npm version](https://img.shields.io/npm/v/@empratur256/ai-workspace.svg)](https://www.npmjs.com/package/@empratur256/ai-workspace)\n[![npm downloads](https://img.shields.io/npm/dm/@empratur256/ai-workspace.svg)](https://www.npmjs.com/package/@empratur256/ai-workspace)\n[![Node.js](https://img.shields.io/node/v/@empratur256/ai-workspace.svg)](https://www.npmjs.com/package/@empratur256/ai-workspace)\n[![License: MIT](https://img.shields.io/npm/l/@empratur256/ai-workspace.svg)](https://github.com/kamranshalilian/AI-Workspace/blob/main/LICENSE)\n[![GitHub](https://img.shields.io/badge/GitHub-kamranshalilian%2FAI--Workspace-181717?logo=github)](https://github.com/kamranshalilian/AI-Workspace)\n\nLocal-first **AI context** for software projects and multi-project workspaces.\n\nAI Workspace (`aiw`) gives a repository one canonical place for agent knowledge — `.ai/` — and treats Cursor, Claude, Codex, and custom-agent files as **adapters** of that layer, not as the source of truth.\n\n**Status: Phase 6 (workspace federation).** The public CLI covers init, inheritance, declarative agents, export, federated sources, import, promote, sync, and multi-project `--all`.\n\nRepository: [github.com/kamranshalilian/AI-Workspace](https://github.com/kamranshalilian/AI-Workspace)\n\n## Why this exists\n\nCoding agents each want project context in a different place: `.cursor/`, `CLAUDE.md`, `AGENTS.md`, and more. Teams copy the same rules into every native format. That duplicates knowledge, creates vendor lock-in, and falls apart across an **AI project workspace** with several repositories.\n\nAI Workspace inverts that:\n\n```text\nHuman / Developer\n        │\n        ▼\n  AI Workspace (.ai/)     ← canonical AI agent context\n        │\n   Resolution\n        │\n   ┌────┼────┐\n   │    │    │\nCursor Codex Claude       ← generated native interfaces\n```\n\n`.ai/` is the Git-diffable source of truth. Native files are projections you can regenerate.\n\n## What you get\n\n- **Canonical `.ai/`** — rules, architecture, skills, decisions, and workflows in one tree\n- **Cursor / Claude / Codex context** from the same files, without vendor-specific core code\n- **Custom agents** as YAML definitions (`aiw agent create`)\n- **Workspace federation** — register projects and run `aiw status --all`, `export --all`, `sync --all`\n- **Sources / import / promote / export / sync** — reference external knowledge, snapshot it, and compare related representations without last-write-wins\n\n## Install\n\nRequires Node.js 20 or newer.\n\n```bash\nnpm install -g @empratur256/ai-workspace\n```\n\nThe package name is `@empratur256/ai-workspace`. The CLI is `aiw`. After global install it works from any directory; project state stays in that project's `.ai/`.\n\n```bash\naiw --help\naiw --version\n```\n\n## Quick start\n\n```bash\ncd your-project\naiw init --name my-project\n```\n\nAdd canonical context (this is the AI developer-tools layer agents will share):\n\n```bash\nmkdir -p .ai/rules\necho \"Do not commit secrets.\" > .ai/rules/security.md\n```\n\nEnable bundled agents and write native files:\n\n```bash\naiw agent add cursor\naiw agent add claude\naiw agent add codex\naiw export\naiw status\n```\n\nThat produces Cursor rules, `CLAUDE.md`, and `AGENTS.md` from the same `.ai/rules/security.md`. Edit the canonical file, then `aiw export` again.\n\n```text\ncreate = create an agent definition\nadd    = register/enable it in the manifest\nexport = materialize native output\n```\n\n## Canonical `.ai/` layout\n\n`aiw init` writes only `manifest.yaml`. Everything else is optional and created by you or by later commands:\n\n```text\n.ai/\n├── manifest.yaml          # contract (required after init)\n├── rules/                 # shared AI context\n├── architecture/\n├── skills/\n├── decisions/\n├── workflows/\n├── agents/                # local YAML definitions (optional)\n├── sources/               # imported snapshots (after aiw import)\n└── state/                 # sync hashes (Git-ignored)\n```\n\nNative files live **outside** `.ai/` and are never canonical:\n\n```text\n.cursor/rules/             # Cursor context (adapter output)\nCLAUDE.md                  # Claude context (adapter output)\nAGENTS.md                  # Codex context (adapter output)\n```\n\n## Agents without lock-in\n\nBundled definition ids: `cursor`, `claude`, `codex`. They are YAML data, not TypeScript branches.\n\n```bash\naiw agent list\naiw agent create my-agent\naiw agent add my-agent\naiw export --agent my-agent\naiw agent remove cursor          # unregister only; native files stay\n```\n\nA file at `.ai/agents/<id>.yaml` shadows a bundled definition with the same id. If Cursor disappeared tomorrow, `.ai/` would still be valid; a new agent would be another definition, not a core rewrite.\n\n## Sources, import, promote, and sync\n\nA **source** is a federated reference. Registration does not copy, import, or execute anything.\n\n```bash\naiw source add knowledge --type directory --path ./docs --capabilities read,index,import\naiw import --source knowledge\naiw sync --source knowledge\naiw promote --agent cursor\n```\n\n| Command | Meaning |\n| --- | --- |\n| `source add` | Register a path in the manifest |\n| `import` | Snapshot Source → `.ai/sources/<id>/` |\n| `export` | Canonical `.ai/` → native agent files |\n| `promote` | Native artifact → canonical `.ai/` (reversible mappings only) |\n| `sync` | State-aware comparison (`clean`, `canonical-changed`, `external-changed`, `conflict`) |\n\n`aiw sync` is report-only unless you pass `--apply`. `--apply` never last-write-wins and never writes into a live source. Concatenated files such as `CLAUDE.md` cannot be promoted.\n\n## Multi-project workspace\n\nA workspace registry is **not** inheritance. Registering a project only means it belongs to this workspace. Inheritance stays explicit via `extends`.\n\n```bash\naiw init --kind workspace --name company-workspace\naiw project add accounting ./accounting\naiw project add wallet ./wallet\naiw project list\naiw status --all\naiw export --all\naiw sync --all\n```\n\n```yaml\nspecVersion: 1\nkind: workspace\nname: company-workspace\n\nprojects:\n  accounting:\n    path: ./accounting\n  wallet:\n    path: ./wallet\n```\n\n`--all` iterates the registry. It does not scan the filesystem. Each project keeps its own `.ai/` and native files. `export --all` does not export the workspace `.ai/` as if it were a project.\n\nA project inherits workspace context only when its own manifest says so:\n\n```yaml\nspecVersion: 1\nkind: project\nname: accounting\n\nextends:\n  - path: ../.ai\n    mode: extend\n```\n\nSee the [CLI](https://github.com/kamranshalilian/AI-Workspace/blob/main/docs/cli/README.md) and [scope, inheritance, and resolution](https://github.com/kamranshalilian/AI-Workspace/blob/main/docs/specification/03-scope-inheritance-resolution.md).\n\n## Current status\n\nPhase 6 is complete: specification through workspace federation.\n\nImplemented: `init`, `status`, `validate`, `doctor`, `agent create|add|remove|list|status`, `export`, `source add|list|remove`, `import`, `promote`, `sync`, `project add|list|remove`, and `--all` on status, validate, doctor, export, and sync.\n\nNot in this release: plugins, MCP execution, cloud sync, GUI, automatic project discovery, or `import --all` / `promote --all`.\n\n### Limitations\n\n- Concatenated and reference-index native files cannot be promoted\n- `sync --apply` may refresh an imported snapshot; it never writes the live source\n- `--all` requires `kind: workspace` (pass `--path` to the workspace root)\n- Source content is not fed into agent export\n- No executable adapters or plugins\n\n## Support\n\nDonations are optional and help fund continued development of AI Workspace.\n\n**USDT** (optional)\n\n```text\n0x4430DA48ad0bF37583262966097E7AC76482b83A\n```\n\nIssues and discussion: [github.com/kamranshalilian/AI-Workspace/issues](https://github.com/kamranshalilian/AI-Workspace/issues)\n\n## Documentation\n\n| Area | Location |\n| --- | --- |\n| Specification | [docs/specification/](https://github.com/kamranshalilian/AI-Workspace/tree/main/docs/specification) |\n| Architecture | [docs/architecture/](https://github.com/kamranshalilian/AI-Workspace/tree/main/docs/architecture) |\n| CLI | [docs/cli/](https://github.com/kamranshalilian/AI-Workspace/tree/main/docs/cli) |\n| Integrations | [docs/integrations/](https://github.com/kamranshalilian/AI-Workspace/tree/main/docs/integrations) |\n\n## Development\n\n```bash\ngit clone https://github.com/kamranshalilian/AI-Workspace.git\ncd AI-Workspace\nnpm install\nnpm test\nnpm run build\n```\n\nThis repository dogfoods itself as `kind: project` under `.ai/`.\n\n## License\n\nMIT. See [LICENSE](https://github.com/kamranshalilian/AI-Workspace/blob/main/LICENSE).\n","readmeFilename":"README.md","_rev":"1-bcee17ee1cc8a5ee149c0303440e6ed4"}