{"_id":"@blazity-atlas/ai-harness","_rev":"3-7611382713866ee3a8338b390e50f6ba","name":"@blazity-atlas/ai-harness","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@blazity-atlas/ai-harness","version":"0.1.0","license":"MIT","_id":"@blazity-atlas/ai-harness@0.1.0","maintainers":[{"name":"jj-blazity","email":"jakub.jablonski@blazity.com"}],"homepage":"https://github.com/Blazity/ai-harness#readme","bugs":{"url":"https://github.com/Blazity/ai-harness/issues"},"bin":{"ai-harness":"bin/ai-harness.js"},"dist":{"shasum":"3958a6faec11efaf0b3d5e59661fb8e09a3fc083","tarball":"https://registry.npmjs.org/@blazity-atlas/ai-harness/-/ai-harness-0.1.0.tgz","fileCount":13,"integrity":"sha512-fbXdcwVo6nVfVYFpzvpc2FKs3QrVRKoXxuT3yUQRtNUDNfrSjHCBhO6rkJjC7Yz+iho+No0VIpYNIyruh3jO/g==","signatures":[{"sig":"MEYCIQDAgxkfhGk3WaNcIwLiL8LHFAbm/4wHoxzDOBRc3CQabwIhAIi0Klfv5y0He/S6LX1s/uiy5USXd8QqA0m0pMkB2E+u","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37092},"type":"module","engines":{"node":">=20"},"gitHead":"f167758785502c574573d8b1d2b78acf275c84b1","scripts":{"test":"node --test","check":"node --test","pack:smoke":"node test/pack-smoke.test.js"},"_npmUser":{"name":"jj-blazity","email":"jakub.jablonski@blazity.com"},"repository":{"url":"git+https://github.com/Blazity/ai-harness.git","type":"git"},"_npmVersion":"11.12.1","description":"Config-driven AI agent documentation harness for project repositories.","directories":{},"_nodeVersion":"24.15.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ai-harness_0.1.0_1779191034473_0.5893207302429928","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@blazity-atlas/ai-harness","version":"0.2.0","description":"Config-driven AI agent documentation harness for project repositories.","type":"module","bin":{"ai-harness":"bin/ai-harness.js"},"scripts":{"test":"node --test","check":"node --test","pack:smoke":"node test/pack-smoke.test.js"},"engines":{"node":">=20"},"repository":{"type":"git","url":"git+https://github.com/Blazity/ai-harness.git"},"publishConfig":{"access":"public"},"license":"MIT","_id":"@blazity-atlas/ai-harness@0.2.0","bugs":{"url":"https://github.com/Blazity/ai-harness/issues"},"homepage":"https://github.com/Blazity/ai-harness#readme","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-rGgXRDaw9wg+QAaiKCgmcJqD+B7sv7Lhpjkn63FiU9OnBMMpiZtP8nB0iAtUN3Jl0omO+Ic9skdUhlMo43FOYg==","shasum":"51e7b2bd3bb2f0e0668185b76f97afb8f5256894","tarball":"https://registry.npmjs.org/@blazity-atlas/ai-harness/-/ai-harness-0.2.0.tgz","fileCount":15,"unpackedSize":49723,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICrzkzHjfDjpeKjiyRbk8AhXw8jANAvWRJMBmcrSNSEOAiEApKhJ9vfWlIEgapd1CMhxKntLJ+OZ/45V8o/9nCZmJwo="}]},"_npmUser":{"name":"jj-blazity","email":"jakub.jablonski@blazity.com"},"directories":{},"maintainers":[{"name":"jj-blazity","email":"jakub.jablonski@blazity.com"},{"name":"kc-blazity","email":"karol.chudzik@blazity.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-harness_0.2.0_1779795922937_0.4643594787511387"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-19T11:43:54.402Z","modified":"2026-05-26T11:45:23.254Z","0.1.0":"2026-05-19T11:43:54.616Z","0.2.0":"2026-05-26T11:45:23.096Z"},"bugs":{"url":"https://github.com/Blazity/ai-harness/issues"},"license":"MIT","homepage":"https://github.com/Blazity/ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Blazity/ai-harness.git"},"description":"Config-driven AI agent documentation harness for project repositories.","maintainers":[{"name":"jj-blazity","email":"jakub.jablonski@blazity.com"},{"name":"kc-blazity","email":"karol.chudzik@blazity.com"}],"readme":"# ai-harness\n\nConfig-driven AI agent documentation harness for project repositories.\n\n`ai-harness` installs a small `.ai/` workspace, writes cross-agent instructions, and validates that AI-generated artifacts stay in the configured folders. The CLI is the deterministic layer; agent rules are guidance.\n\n## Install\n\nPublic setup always goes through the published npm package. Do not copy this repository's `.ai/` folder or run local maintainer scripts to install AI Harness in another product repository.\n\nRun in the root of a git repository:\n\n```bash\nnpx --yes @blazity-atlas/ai-harness@latest init\n```\n\nPick a deterministic starter template when you already know the repository shape:\n\n```bash\nnpx --yes @blazity-atlas/ai-harness@latest init --template app\n```\n\nAvailable templates are `standard`, `library`, `app`, `monorepo`, and `agency`.\n\nPreview first:\n\n```bash\nnpx --yes @blazity-atlas/ai-harness@latest init --dry-run\n```\n\nThe installer is idempotent. It creates `.ai/config.json`, the configured `.ai/` folders, `AGENTS.md` managed instructions, a Claude shim, supported skill-discovery links, and a local `setup` skill when it can do so safely.\n\nAfter installation, ask your agent to use the `setup` skill. The skill inspects the repository, asks whether you want standard setup or repository-specific customization, and fills the first useful `AGENTS.md`, vocabulary, and memory files. If you choose customization, the skill lazy-loads its longer customization workflow from `setup/customization.md`.\n\nYou can also start from the skill first. In that flow the agent must still use the npm package through `npx`, checks whether AI Harness is installed, runs `init` or `doctor --fix` when safe, and only then continues into repository questions.\n\n## Commands\n\n```bash\nnpx --yes @blazity-atlas/ai-harness@latest init          # Install or refresh managed harness files\nnpx --yes @blazity-atlas/ai-harness@latest init --template app\nnpx --yes @blazity-atlas/ai-harness@latest init --dry-run\nnpx --yes @blazity-atlas/ai-harness@latest doctor        # Inspect harness drift; no writes\nnpx --yes @blazity-atlas/ai-harness@latest doctor --fix  # Apply safe deterministic repairs\nnpx --yes @blazity-atlas/ai-harness@latest doctor --fix --force\n```\n\n`doctor` is the dry run for repairs. It reports fixable issues separately from manual conflicts. `doctor --fix` only applies the fixable set, and requires `--force` when the git worktree is dirty.\n\n## Configuration\n\n`.ai/config.json` is the source of truth for artifact locations:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"template\": \"standard\",\n  \"artifactRoot\": \".ai\",\n  \"paths\": {\n    \"language\": \"LANGUAGE.md\",\n    \"memory\": \"memory\",\n    \"plans\": \"plans\",\n    \"research\": \"research\",\n    \"decisions\": \"decisions\",\n    \"adrs\": \"decisions/adrs\",\n    \"results\": \"results\",\n    \"skills\": \"skills\"\n  },\n  \"pathAliases\": {\n    \"docs/superpowers/plans\": \"plans\",\n    \"docs/superpowers/specs\": \"research\",\n    \"docs/adrs\": \"decisions/adrs\",\n    \"docs/specs\": \"research\"\n  }\n}\n```\n\nRules:\n\n- `artifactRoot` is relative to the repository root unless absolute.\n- `paths` values are relative to `artifactRoot` unless absolute.\n- `pathAliases` keys are legacy or wrong locations relative to the repository root.\n- `pathAliases` values are relative to `artifactRoot` unless absolute.\n\nAgents are instructed to map conflicting skill/template paths through this config before reading or writing artifacts.\n\n## Templates and Customization\n\nTemplates are deterministic CLI presets. They choose the initial `.ai/config.json` shape and known path aliases for common repository types:\n\n- `standard`: the default generic harness.\n- `library`: API, release, compatibility, and documentation-oriented aliases.\n- `app`: product, QA, runtime, and runbook-oriented aliases.\n- `monorepo`: package, app, and workspace-oriented aliases.\n- `agency`: client context, handoff, and delivery-oriented aliases.\n\nTemplates are not a substitute for repository understanding. After `init`, use the `setup` skill. It asks whether you want standard setup or customization. Standard setup fills stable context quickly; customization reads `setup/customization.md` and interviews you about artifact layout, enabled workflows, strictness, agent surfaces, vocabulary, safe commands, and optional project-local skills.\n\n## Why Config, Not Patched Skills\n\nEarlier versions explored vendoring third-party skills and patching hardcoded paths. That works, but it creates maintenance drift and makes updates fragile. The MVP uses a simpler model:\n\n- `.ai/config.json` defines where artifacts belong.\n- Agent instructions tell models to respect that config.\n- `doctor` detects drift.\n- `doctor --fix` moves files from explicit aliases into canonical folders.\n- `setup` handles semantic setup and later refreshes.\n\nThird-party skills are optional. The CLI does not patch or update third-party skill internals.\n\n## Agent-Led Setup and Refresh\n\nThe CLI intentionally does not ask product or architecture questions. The npm package creates a local managed skill instead:\n\n```text\n.ai/skills/setup/SKILL.md\n.ai/skills/setup/customization.md\n```\n\nUse that skill after first install and after major repository changes. It should inspect the codebase, ask focused questions for missing context, preserve human-authored content, and keep `AGENTS.md` concise. It only reads `customization.md` when the user opts into customization.\n\nThe skill can also be the first entrypoint, but it must not implement setup itself. Ask an agent to use the skill in a git repository and it should call the npm package:\n\n```bash\nnpx --yes @blazity-atlas/ai-harness@latest doctor\nnpx --yes @blazity-atlas/ai-harness@latest init\nnpx --yes @blazity-atlas/ai-harness@latest doctor --fix\n```\n\nThe skill must stop on manual conflicts and must not use `--force` unless the user explicitly approves it after a dirty-worktree refusal.\n\n## Claude Code Plugin\n\nAI Harness can also be installed as a thin Claude Code plugin through the Blazity Atlas marketplace:\n\n```text\n/plugin marketplace add Blazity/atlas\n/plugin install ai-harness@blazity\n/ai-harness:setup\n```\n\nThe plugin only exposes the `setup` skill. It does not replace the npm package or duplicate installer logic; the skill still calls the same `npx --yes @blazity-atlas/ai-harness@latest ...` commands that a human would run.\n\n## Safety Model\n\n`init` requires a git repository. Mutating commands refuse to run on a dirty worktree when they have changes to apply unless `--force` is passed.\n\n`doctor --fix` will:\n\n- create missing configured folders;\n- create missing default config and starter files;\n- add or refresh managed instruction blocks;\n- repair safe skill symlinks;\n- restore the managed `setup` skill;\n- move files from explicit alias roots to canonical paths.\n\nIt will not:\n\n- delete unknown files;\n- infer new aliases;\n- overwrite target conflicts;\n- rewrite project prose outside managed blocks;\n- patch third-party skills.\n\n## Development\n\nThese commands are for maintainers working inside this repository. Product repositories should use the npm package commands above.\n\n```bash\nnpm test\nnpm run pack:smoke\nnode bin/ai-harness.js --help\n```\n\nThe package smoke test runs `npm pack`, installs the packed tarball into a temporary git repo, runs `init`, then runs `doctor`.\n\n## Attribution\n\nThis project was informed by existing agent-workflow patterns, including Superpowers and public skill repositories. The current npm CLI does not install patched third-party skills by default. Any copied third-party material retained in this repository keeps its license and attribution next to the copied files.\n","readmeFilename":"README.md"}