agent-harness-init 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Harness Init Contributors
+
+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,197 @@
+# Agent Harness Init
+
+让用户在任意软件项目中对 AI Agent 说一句“帮我安装并适配 Harness”，
+Agent 就能先分析项目、生成安全计划，再部署项目级规则和验证门控。
+
+Agent Harness Init 是一个独立、Provider-neutral 的 Harness 安装器。它把
+Agent 的判断力用于识别项目，把文件生成、冲突检测、哈希所有权和写入交给
+确定性的 CLI，避免不同 Agent 手工复制模板造成漂移。
+
+> 当前版本：`0.1.0`。GitHub 仓库与 npm 包均公开发布。
+
+## 它解决什么问题
+
+传统模板要求用户自己复制 `AGENTS.md`、Skills、验证文档和配置，并且后续
+无法安全升级。本项目提供完整生命周期：
+
+- 自动识别 JavaScript/TypeScript、Python、全栈和 Monorepo 项目；
+- 无法识别时使用 `custom`，不虚构构建或测试命令；
+- 生成项目级 `AGENT_HARNESS.md`、Harness 文档和 Codex/Claude Skills；
+- 使用 `.harness/manifest.json` 记录所有生成文件的 SHA-256；
+- 更新和卸载只处理仍与 manifest 一致的文件；
+- 已存在或被用户修改的文件绝不静默覆盖；
+- OpenSpec 是可选工作流，不是运行时硬依赖；
+- 不读取无关源码、不上传代码、不包含遥测。
+
+## 工作方式
+
+```text
+自然语言请求
+     │
+     ▼
+Bootstrap Skill
+     │
+     ▼
+只读项目发现 ──> dry-run 安装计划 ──> 冲突检查
+                                          │
+                              无冲突且用户已授权
+                                          │
+                                          ▼
+                          原子写入 + 所有权 manifest
+                                          │
+                                          ▼
+                                       doctor
+```
+
+## 快速安装
+
+要求 Node.js 20 或更高版本。
+
+```bash
+# 在目标项目中预览适配计划（不写入）
+npx agent-harness-init plan --root .
+
+# 应用无冲突的安装计划
+npx agent-harness-init init --root . --yes
+
+# 检查生成文件是否完整、未漂移
+npx agent-harness-init doctor --root .
+```
+
+安装一次 Bootstrap Skill：
+
+```bash
+# Codex
+npx agent-harness-init install-skill --provider codex
+
+# Claude Code
+npx agent-harness-init install-skill --provider claude
+```
+
+安装 Skill 是用户级写入，与在具体项目中安装 Harness 是两个独立授权范围。
+
+## 一句话让 Agent 部署
+
+打开目标项目后告诉 Agent：
+
+> 帮我安装并适配 Agent Harness Init。先做只读计划，不覆盖已有规则，安装后运行 doctor 并报告结果。
+
+Bootstrap Skill 会引导 Agent 执行：
+
+```bash
+npx agent-harness-init plan --root .
+npx agent-harness-init init --root . --yes
+npx agent-harness-init doctor --root .
+```
+
+如果项目已经有 `AGENTS.md`，CLI 不会接管或覆盖它。Agent 会先阅读原规则，
+然后只添加一个指向 `AGENT_HARNESS.md` 的最小引用；原项目更严格的规则继续优先。
+
+## CLI
+
+| 命令 | 作用 | 是否写入 |
+|---|---|:---:|
+| `plan` | 发现项目并显示安装或升级计划 | 否 |
+| `init --yes` | 应用无冲突的安装计划 | 是 |
+| `update --yes` | 更新仍未被用户修改的托管文件 | 是 |
+| `doctor` | 检查托管文件缺失和漂移 | 否 |
+| `verify` | 按配置依次执行项目门控 | 运行项目命令 |
+| `uninstall --yes` | 删除未被修改的托管文件 | 是 |
+| `install-skill` | 安装用户级 Bootstrap Skill | 是，项目外 |
+
+所有项目命令都支持 `--root <path>`。`init` 和 `update` 在不带 `--yes` 时只
+显示计划。
+
+## 目标项目中生成的内容
+
+```text
+target-project/
+├── AGENT_HARNESS.md
+├── AGENTS.md                         # 仅在原项目不存在时生成
+├── INSTALL_AGENT.md
+├── harness.config.yaml
+├── harness/
+│   ├── architecture.md
+│   └── verification.md
+├── .agents/skills/agent-harness/     # Codex 项目 Skill
+├── .claude/skills/agent-harness/     # Claude 项目 Skill
+└── .harness/
+    ├── manifest.json
+    └── backups/                      # 仅升级托管文件时使用
+```
+
+`harness.config.yaml` 是适配层，保存检测到的项目类型、源码和测试目录、Agent
+Provider、工作流以及验证命令。框架源码不硬编码用户项目的包名和目录。
+
+## 安全模型
+
+- 计划阶段完全只读。
+- 目标路径必须解析在用户指定的项目根目录内。
+- 首次安装遇到同名文件会报告冲突，不使用覆盖开关绕过。
+- manifest 记录每个托管文件的 SHA-256。
+- 升级前当前哈希必须与旧 manifest 一致。
+- 文件通过同目录临时文件和 rename 原子替换。
+- 安装事务失败时回滚本次新建和已备份的托管文件。
+- 卸载保留项目拥有的 `harness.config.yaml`、缺失项和已修改文件，只删除确认未变的托管内容。
+- 项目内安装不授权全局 Skill、Git commit/push、远程建仓或 npm 发布。
+
+## 支持范围
+
+0.1 版本内置以下 Profile：
+
+- `javascript`
+- `python`
+- `fullstack`
+- `monorepo`
+- `custom`
+
+“支持任意项目”意味着未知项目可以通过 `harness.config.yaml` 配置接入，
+而不是框架声称能够自动理解所有业务架构。更多技术栈应通过配置和适配器扩展。
+
+## 开发
+
+```bash
+git clone https://github.com/xixixixi55/agent-harness-init.git
+cd agent-harness-init
+npm install
+npm run typecheck
+npm test
+npm run build
+npm run verify
+npm run release:check
+```
+
+## npm 发布维护
+
+仓库的 `publishConfig` 固定使用官方 npm registry 并公开发布。维护者发布前应：
+
+```bash
+npm version <patch|minor|major>
+npm run release:check
+npm publish --access public
+git push --follow-tags
+```
+
+`.github/workflows/ci.yml` 会在提交和 Pull Request 上验证 Node.js 20/22。
+`.github/workflows/npm-publish.yml` 可在 GitHub Release 发布时使用仓库的
+`NPM_TOKEN` secret 自动发布；首次配置 token 前不会执行外部发布。
+
+正式行为位于 `openspec/`。核心依赖方向为：
+
+```text
+types -> discovery -> planning -> rendering -> filesystem -> commands -> cli
+```
+
+## 独立性、致谢与许可证
+
+Agent Harness Init 是独立开发和维护的项目，不隶属于、不代表、也未获得
+Harness-OSPX 的官方背书。
+
+本项目早期设计参考了
+[Harness-OSPX](https://github.com/pxp995/harness-ospx) 将 Harness Engineering、
+项目级 Agent 指令、验证门控与 OpenSpec 工作流结合的思路。Harness-OSPX 由
+pxp995 及其贡献者维护，并以 MIT License 发布。对应版权和许可文本保存在
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 与
+[`licenses/harness-ospx-MIT.txt`](licenses/harness-ospx-MIT.txt)。
+
+本项目自身以 [MIT License](LICENSE) 发布。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party notices
+
+## Harness-OSPX
+
+Agent Harness Init is an independent project. Its early design was informed by
+[Harness-OSPX](https://github.com/pxp995/harness-ospx), including the idea of
+combining Harness Engineering, project-local agent instructions, verification
+gates, and OpenSpec-oriented change management.
+
+Harness-OSPX is maintained by pxp995 and its contributors and is distributed
+under the MIT License. The notice shipped with the locally reviewed
+`@pxp995/harness-ospx@1.0.2` distribution is preserved in
+`licenses/harness-ospx-MIT.txt`.
+
+This project is not affiliated with, endorsed by, or maintained by the
+Harness-OSPX project.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: string[]): number;

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import process from 'node:process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.js';
+import { applyInstallPlan, diagnoseInstallation, uninstallManagedFiles } from './filesystem.js';
+import { formatDoctor, formatPlan } from './format.js';
+import { createInstallPlan } from './planner.js';
+import { installBootstrapSkill } from './skill-install.js';
+import { runConfiguredVerification } from './verify.js';
+function packageVersion() {
+    const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(packagePath, 'utf8')).version;
+}
+function parseArgs(argv) {
+    const command = argv[0] ?? 'help';
+    let root = process.cwd();
+    let provider;
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--root')
+            root = path.resolve(argv[++index] ?? '');
+        if (arg === '--provider') {
+            const value = argv[++index];
+            if (value !== 'codex' && value !== 'claude')
+                throw new Error('--provider must be codex or claude');
+            provider = value;
+        }
+    }
+    return { command, root, provider, yes: argv.includes('--yes'), force: argv.includes('--force') };
+}
+function help() {
+    return `Agent Harness Init
+
+Usage:
+  agent-harness plan [--root PATH]
+  agent-harness init [--root PATH] --yes
+  agent-harness update [--root PATH] --yes
+  agent-harness doctor [--root PATH]
+  agent-harness verify [--root PATH]
+  agent-harness uninstall [--root PATH] --yes
+  agent-harness install-skill --provider codex|claude [--force]
+`;
+}
+export function runCli(argv = process.argv.slice(2)) {
+    try {
+        const args = parseArgs(argv);
+        const version = packageVersion();
+        if (args.command === 'help' || args.command === '--help' || args.command === '-h') {
+            console.log(help());
+            return 0;
+        }
+        if (args.command === 'plan') {
+            console.log(formatPlan(createInstallPlan(args.root, version)));
+            return 0;
+        }
+        if (args.command === 'init' || args.command === 'update') {
+            const plan = createInstallPlan(args.root, version);
+            console.log(formatPlan(plan));
+            if (!args.yes) {
+                console.error('Dry-run only. Re-run with --yes to apply this exact conflict-free plan.');
+                return plan.conflicts.length > 0 ? 2 : 0;
+            }
+            applyInstallPlan(plan);
+            console.log(`Installed Agent Harness Init ${version}.`);
+            return 0;
+        }
+        if (args.command === 'doctor') {
+            const findings = diagnoseInstallation(args.root);
+            console.log(formatDoctor(findings));
+            return findings.every((finding) => finding.status === 'ok') ? 0 : 2;
+        }
+        if (args.command === 'verify') {
+            const results = runConfiguredVerification(args.root, loadConfig(args.root));
+            return results.every((result) => result.status === 0) ? 0 : 1;
+        }
+        if (args.command === 'uninstall') {
+            if (!args.yes)
+                throw new Error('Uninstall requires --yes');
+            const findings = uninstallManagedFiles(args.root);
+            console.log(formatDoctor(findings));
+            return findings.every((finding) => finding.status === 'ok') ? 0 : 2;
+        }
+        if (args.command === 'install-skill') {
+            if (!args.provider)
+                throw new Error('install-skill requires --provider codex|claude');
+            console.log(`Installed Bootstrap Skill at ${installBootstrapSkill(args.provider, args.force)}`);
+            return 0;
+        }
+        console.error(help());
+        return 1;
+    }
+    catch (error) {
+        console.error(`agent-harness: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+process.exitCode = runCli();

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { AgentProvider, HarnessConfig, ProjectFacts } from './types.js';
+export declare function configFromFacts(facts: ProjectFacts, agents?: AgentProvider[]): HarnessConfig;
+export declare function serializeConfig(config: HarnessConfig): string;
+export declare function loadConfig(root: string): HarnessConfig;

package/dist/config.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+export function configFromFacts(facts, agents = ['codex', 'claude']) {
+    return {
+        schemaVersion: 1,
+        project: { name: facts.name, profile: facts.profile },
+        agents,
+        workflow: { provider: facts.markers.includes('openspec/') ? 'openspec' : 'native' },
+        architecture: { sourceRoots: facts.sourceRoots, testRoots: facts.testRoots },
+        commands: facts.commands,
+    };
+}
+export function serializeConfig(config) {
+    return stringify(config, { lineWidth: 100 });
+}
+export function loadConfig(root) {
+    const configPath = path.join(root, 'harness.config.yaml');
+    if (!existsSync(configPath))
+        throw new Error('harness.config.yaml is missing; run init first');
+    const value = parse(readFileSync(configPath, 'utf8'));
+    if (value?.schemaVersion !== 1 || !value.project?.name || !value.commands) {
+        throw new Error('harness.config.yaml is invalid or unsupported');
+    }
+    return value;
+}

package/dist/discovery.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectFacts } from './types.js';
+export declare function discoverProject(rootInput: string): ProjectFacts;

package/dist/discovery.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+function exists(root, relative) {
+    return existsSync(path.join(root, relative));
+}
+function readPackageJson(root) {
+    const packagePath = path.join(root, 'package.json');
+    if (!existsSync(packagePath))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(packagePath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function npmCommand(script, scripts) {
+    return scripts?.[script] ? `npm run ${script}` : undefined;
+}
+function detectCommands(packageJson, python) {
+    const scripts = packageJson?.scripts;
+    return {
+        build: npmCommand('build', scripts),
+        typecheck: npmCommand('typecheck', scripts),
+        lint: npmCommand('lint', scripts) ?? npmCommand('lint:arch', scripts),
+        test: npmCommand('test', scripts) ?? (python ? 'python -m pytest -q --tb=short' : undefined),
+    };
+}
+function detectProfile(javaScript, python, monorepo) {
+    if (monorepo)
+        return 'monorepo';
+    if (javaScript && python)
+        return 'fullstack';
+    if (javaScript)
+        return 'javascript';
+    if (python)
+        return 'python';
+    return 'custom';
+}
+function detectGitDirty(root) {
+    const result = spawnSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8', windowsHide: true });
+    return result.status === 0 ? result.stdout.trim().length > 0 : null;
+}
+export function discoverProject(rootInput) {
+    const root = path.resolve(rootInput);
+    const packageJson = readPackageJson(root);
+    const javaScript = Boolean(packageJson);
+    const python = exists(root, 'pyproject.toml') || exists(root, 'requirements.txt') || exists(root, 'setup.py');
+    const monorepo = Boolean(packageJson?.workspaces) || exists(root, 'pnpm-workspace.yaml') || exists(root, 'lerna.json');
+    const markers = [
+        javaScript && 'package.json',
+        exists(root, 'pnpm-workspace.yaml') && 'pnpm-workspace.yaml',
+        exists(root, 'pyproject.toml') && 'pyproject.toml',
+        exists(root, 'requirements.txt') && 'requirements.txt',
+        exists(root, 'openspec') && 'openspec/',
+    ].filter((value) => Boolean(value));
+    return {
+        root,
+        name: packageJson?.name ?? path.basename(root),
+        profile: detectProfile(javaScript, python, monorepo),
+        markers,
+        sourceRoots: ['src', 'app', 'packages', 'lib'].filter((candidate) => exists(root, candidate)),
+        testRoots: ['tests', 'test', '__tests__', 'e2e'].filter((candidate) => exists(root, candidate)),
+        commands: detectCommands(packageJson, python),
+        packageManager: packageJson?.packageManager?.split('@')[0],
+        gitDirty: detectGitDirty(root),
+        existingAgentFiles: ['AGENTS.md', 'CLAUDE.md', '.agents', '.claude'].filter((candidate) => exists(root, candidate)),
+    };
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,4 @@
+import type { DoctorFinding, HarnessManifest, InstallPlan } from './types.js';
+export declare function applyInstallPlan(plan: InstallPlan, now?: Date): HarnessManifest;
+export declare function diagnoseInstallation(root: string): DoctorFinding[];
+export declare function uninstallManagedFiles(root: string): DoctorFinding[];

package/dist/filesystem.js

@@ -0,0 +1,93 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { sha256 } from './hash.js';
+import { loadManifest, manifestRelativePath, serializeManifest } from './manifest.js';
+import { resolveInside } from './paths.js';
+function writeAtomic(target, content) {
+    mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = `${target}.agent-harness-${process.pid}.tmp`;
+    writeFileSync(temporary, content, 'utf8');
+    renameSync(temporary, target);
+}
+export function applyInstallPlan(plan, now = new Date()) {
+    if (plan.conflicts.length > 0) {
+        throw new Error(`Installation has conflicts: ${plan.conflicts.join(', ')}`);
+    }
+    const previousManifest = loadManifest(plan.root);
+    const transactionRoot = resolveInside(plan.root, `.harness/backups/${now.toISOString().replaceAll(':', '-')}`);
+    const created = [];
+    const updated = [];
+    try {
+        for (const artifact of plan.artifacts) {
+            if (artifact.action === 'unchanged')
+                continue;
+            const target = resolveInside(plan.root, artifact.path);
+            if (artifact.action === 'update') {
+                const backup = path.join(transactionRoot, ...artifact.path.split('/'));
+                mkdirSync(path.dirname(backup), { recursive: true });
+                copyFileSync(target, backup);
+                updated.push({ target, backup });
+            }
+            else {
+                created.push(target);
+            }
+            writeAtomic(target, artifact.content);
+        }
+        const manifest = {
+            schemaVersion: 1,
+            framework: { name: 'agent-harness-init', version: plan.frameworkVersion },
+            installedAt: now.toISOString(),
+            files: Object.fromEntries(plan.artifacts
+                .filter((artifact) => artifact.path !== 'harness.config.yaml')
+                .map((artifact) => [artifact.path, { hash: artifact.nextHash }])),
+        };
+        writeAtomic(resolveInside(plan.root, manifestRelativePath), serializeManifest(manifest));
+        return manifest;
+    }
+    catch (error) {
+        for (const target of created.reverse()) {
+            if (existsSync(target))
+                rmSync(target, { force: true });
+        }
+        for (const entry of updated.reverse())
+            copyFileSync(entry.backup, entry.target);
+        if (previousManifest) {
+            writeAtomic(resolveInside(plan.root, manifestRelativePath), serializeManifest(previousManifest));
+        }
+        throw error;
+    }
+}
+export function diagnoseInstallation(root) {
+    const manifest = loadManifest(root);
+    if (!manifest)
+        throw new Error('Harness is not installed: .harness/manifest.json is missing');
+    return Object.entries(manifest.files).map(([relativePath, entry]) => {
+        const target = resolveInside(root, relativePath);
+        if (!existsSync(target))
+            return { path: relativePath, status: 'missing' };
+        return { path: relativePath, status: sha256(readFileSync(target)) === entry.hash ? 'ok' : 'modified' };
+    });
+}
+export function uninstallManagedFiles(root) {
+    const manifest = loadManifest(root);
+    if (!manifest)
+        throw new Error('Harness is not installed');
+    const findings = diagnoseInstallation(root);
+    const preserved = {};
+    for (const finding of findings) {
+        if (finding.status === 'ok') {
+            unlinkSync(resolveInside(root, finding.path));
+        }
+        else {
+            preserved[finding.path] = manifest.files[finding.path];
+        }
+    }
+    const manifestPath = resolveInside(root, manifestRelativePath);
+    if (Object.keys(preserved).length === 0) {
+        unlinkSync(manifestPath);
+    }
+    else {
+        writeAtomic(manifestPath, serializeManifest({ ...manifest, files: preserved }));
+    }
+    return findings;
+}

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorFinding, InstallPlan } from './types.js';
+export declare function formatPlan(plan: InstallPlan): string;
+export declare function formatDoctor(findings: DoctorFinding[]): string;

package/dist/format.js

@@ -0,0 +1,14 @@
+export function formatPlan(plan) {
+    const lines = [
+        `Agent Harness plan | root=${plan.root}`,
+        `profile=${plan.facts.profile} | gitDirty=${String(plan.facts.gitDirty)} | markers=${plan.facts.markers.join(',') || 'none'}`,
+    ];
+    for (const artifact of plan.artifacts) {
+        lines.push(`${artifact.action.toUpperCase().padEnd(9)} ${artifact.path} — ${artifact.reason}`);
+    }
+    lines.push(`conflicts=${plan.conflicts.length}`);
+    return lines.join('\n');
+}
+export function formatDoctor(findings) {
+    return findings.map((finding) => `${finding.status.toUpperCase().padEnd(8)} ${finding.path}`).join('\n');
+}

package/dist/hash.d.ts

@@ -0,0 +1 @@
+export declare function sha256(content: string | Buffer): string;

package/dist/hash.js

@@ -0,0 +1,4 @@
+import { createHash } from 'node:crypto';
+export function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}

package/dist/manifest.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessManifest } from './types.js';
+export declare const manifestRelativePath = ".harness/manifest.json";
+export declare function loadManifest(root: string): HarnessManifest | undefined;
+export declare function serializeManifest(manifest: HarnessManifest): string;

package/dist/manifest.js

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+export const manifestRelativePath = '.harness/manifest.json';
+export function loadManifest(root) {
+    const manifestPath = path.join(root, manifestRelativePath);
+    if (!existsSync(manifestPath))
+        return undefined;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (manifest?.schemaVersion !== 1 || manifest.framework?.name !== 'agent-harness-init') {
+        throw new Error('Unsupported or invalid .harness/manifest.json');
+    }
+    return manifest;
+}
+export function serializeManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/dist/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeRelativePath(value: string): string;
+export declare function resolveInside(root: string, relativePath: string): string;

package/dist/paths.js

@@ -0,0 +1,21 @@
+import path from 'node:path';
+export function normalizeRelativePath(value) {
+    const normalized = value.replaceAll('\\', '/').replace(/^\.\//, '');
+    if (!normalized || normalized === '.' || path.isAbsolute(value)) {
+        throw new Error(`Path must be a non-empty relative path: ${value}`);
+    }
+    const segments = normalized.split('/');
+    if (segments.some((segment) => segment === '..' || segment === '')) {
+        throw new Error(`Path escapes or is malformed: ${value}`);
+    }
+    return segments.join('/');
+}
+export function resolveInside(root, relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, ...normalized.split('/'));
+    if (!resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new Error(`Resolved path escapes target root: ${relativePath}`);
+    }
+    return resolved;
+}

package/dist/planner.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider, InstallPlan } from './types.js';
+export declare function createInstallPlan(root: string, frameworkVersion: string, agents?: AgentProvider[]): InstallPlan;

package/dist/planner.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { configFromFacts, loadConfig } from './config.js';
+import { discoverProject } from './discovery.js';
+import { sha256 } from './hash.js';
+import { loadManifest } from './manifest.js';
+import { renderArtifacts } from './render.js';
+function classify(root, pathValue, content, managedHash) {
+    const target = path.join(root, ...pathValue.split('/'));
+    const nextHash = sha256(content);
+    if (!existsSync(target)) {
+        return { path: pathValue, content, action: 'create', reason: 'destination is absent', nextHash };
+    }
+    const currentHash = sha256(readFileSync(target));
+    if (currentHash === nextHash) {
+        return { path: pathValue, content, action: 'unchanged', reason: 'content already matches', nextHash, previousHash: currentHash };
+    }
+    if (managedHash && currentHash === managedHash) {
+        return { path: pathValue, content, action: 'update', reason: 'unchanged managed file can be updated', nextHash, previousHash: currentHash };
+    }
+    return { path: pathValue, content, action: 'conflict', reason: 'destination is unowned or was modified', nextHash, previousHash: currentHash };
+}
+export function createInstallPlan(root, frameworkVersion, agents = ['codex', 'claude']) {
+    const facts = discoverProject(root);
+    const manifest = loadManifest(facts.root);
+    const config = manifest ? loadConfig(facts.root) : configFromFacts(facts, agents);
+    const rendered = renderArtifacts(facts, config).filter((artifact) => !manifest || artifact.path !== 'harness.config.yaml');
+    const artifacts = rendered.map((artifact) => classify(facts.root, artifact.path, artifact.content, manifest?.files[artifact.path]?.hash));
+    return {
+        root: facts.root,
+        frameworkVersion,
+        facts,
+        artifacts,
+        conflicts: artifacts.filter((artifact) => artifact.action === 'conflict').map((artifact) => artifact.path),
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessConfig, ProjectFacts, RenderedArtifact } from './types.js';
+export declare function renderArtifacts(facts: ProjectFacts, config: HarnessConfig): RenderedArtifact[];

package/dist/render.js

@@ -0,0 +1,134 @@
+import { serializeConfig } from './config.js';
+function list(values, fallback) {
+    return values.length > 0 ? values.map((value) => `- \`${value}/\``).join('\n') : `- ${fallback}`;
+}
+function commandList(config) {
+    const entries = Object.entries(config.commands).filter((entry) => Boolean(entry[1]));
+    if (entries.length === 0)
+        return '- No commands detected. Configure `harness.config.yaml` before verification.';
+    return entries.map(([name, command]) => `- ${name}: \`${command}\``).join('\n');
+}
+function agentHarness(config) {
+    return `# Agent Harness — ${config.project.name}
+
+This file is managed by Agent Harness Init. Project-specific rules in an existing
+\`AGENTS.md\` or \`CLAUDE.md\` take precedence when they are more restrictive.
+
+## Operating contract
+
+- Inspect relevant source and tests before changing behavior.
+- Keep changes inside the authorized project and preserve unrelated work.
+- Use commands declared in \`harness.config.yaml\`; do not invent replacements.
+- Choose verification evidence according to risk. Security, persistence, public
+  contracts, and critical transformations require automated regression evidence.
+- Never commit, push, publish, install global tooling, or contact external
+  services unless the user authorizes that action.
+
+## Project profile
+
+- Profile: \`${config.project.profile}\`
+- Workflow: \`${config.workflow.provider}\`
+
+## Commands
+
+${commandList(config)}
+
+Detailed architecture and verification guidance lives in \`harness/\`.
+`;
+}
+function rootAgents(config) {
+    return `# AGENTS.md — ${config.project.name}
+
+Read \`AGENT_HARNESS.md\` before modifying this project. Project owners may add
+more restrictive rules below this notice.
+`;
+}
+function architecture(config) {
+    return `# Project architecture
+
+This file records detected structure, not inferred business behavior. Edit
+\`harness.config.yaml\` when the project structure changes, then run
+\`agent-harness update\`.
+
+## Source roots
+
+${list(config.architecture.sourceRoots, 'No source root detected; configure explicitly.')}
+
+## Test roots
+
+${list(config.architecture.testRoots, 'No test root detected; configure explicitly.')}
+
+## Dependency policy
+
+Architecture boundaries are project-owned. Define allowed dependency directions
+here or in a dedicated project rule before enabling an architecture lint gate.
+`;
+}
+function verification(config) {
+    return `# Verification strategy
+
+Run the smallest evidence that distinguishes the changed risk, then broaden only
+when the change crosses contracts or release boundaries.
+
+The CLI runs only commands declared in \`harness.config.yaml\`:
+
+${commandList(config)}
+
+Passing output is summarized. On failure, stop after the first failing command,
+inspect that failure, and do not hide unrelated baseline failures.
+`;
+}
+function projectSkill() {
+    return `---
+name: agent-harness
+description: Apply this project's Harness rules when implementing, fixing, reviewing, verifying, or planning changes in this repository.
+---
+
+Read \`AGENT_HARNESS.md\` and \`harness.config.yaml\`. Load only directly relevant
+project source, tests, and Harness guidance. Preserve user changes and run
+verification proportionate to actual risk. Use \`agent-harness doctor\` to
+diagnose managed-file drift and \`agent-harness verify\` only when requested or
+when implementation completion requires the configured project gates.
+`;
+}
+function installAgent() {
+    return `# Installing Agent Harness with an AI agent
+
+Ask your agent:
+
+> Install and adapt Agent Harness Init to this project. Run a read-only plan
+> first, preserve existing rules, apply only a conflict-free plan, then run
+> doctor and report the result.
+
+Deterministic protocol:
+
+1. \`agent-harness plan --root .\`
+2. Review detected commands and every conflict.
+3. If conflict-free, run \`agent-harness init --root . --yes\`.
+4. If an unowned \`AGENTS.md\` exists, inspect it and add only a reference to
+   \`AGENT_HARNESS.md\` without weakening existing rules.
+5. Run \`agent-harness doctor --root .\`.
+
+Do not authorize global Skill installation, repository creation, pushing, or
+publishing merely from a project-local installation request.
+`;
+}
+export function renderArtifacts(facts, config) {
+    const artifacts = [
+        { path: 'harness.config.yaml', content: serializeConfig(config) },
+        { path: 'AGENT_HARNESS.md', content: agentHarness(config) },
+        { path: 'harness/architecture.md', content: architecture(config) },
+        { path: 'harness/verification.md', content: verification(config) },
+        { path: 'INSTALL_AGENT.md', content: installAgent() },
+    ];
+    if (!facts.existingAgentFiles.includes('AGENTS.md')) {
+        artifacts.push({ path: 'AGENTS.md', content: rootAgents(config) });
+    }
+    if (config.agents.includes('codex')) {
+        artifacts.push({ path: '.agents/skills/agent-harness/SKILL.md', content: projectSkill() });
+    }
+    if (config.agents.includes('claude')) {
+        artifacts.push({ path: '.claude/skills/agent-harness/SKILL.md', content: projectSkill() });
+    }
+    return artifacts.sort((left, right) => left.path.localeCompare(right.path));
+}

package/dist/skill-install.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from './types.js';
+export declare function installBootstrapSkill(provider: AgentProvider, force?: boolean): string;

package/dist/skill-install.js

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+function providerSkillRoot(provider) {
+    if (provider === 'codex') {
+        return path.join(process.env.CODEX_HOME || path.join(homedir(), '.codex'), 'skills');
+    }
+    return path.join(homedir(), '.claude', 'skills');
+}
+export function installBootstrapSkill(provider, force = false) {
+    const sourceRoot = path.join(packageRoot(), 'skills', 'agent-harness-init');
+    const destinationRoot = path.join(providerSkillRoot(provider), 'agent-harness-init');
+    if (!existsSync(path.join(sourceRoot, 'SKILL.md'))) {
+        throw new Error(`Packaged Bootstrap Skill is missing at ${sourceRoot}`);
+    }
+    if (existsSync(destinationRoot) && !force) {
+        throw new Error(`Skill destination already exists: ${destinationRoot}; use --force only after review`);
+    }
+    for (const relativePath of ['SKILL.md', 'agents/openai.yaml', 'references/install-protocol.md']) {
+        const source = path.join(sourceRoot, ...relativePath.split('/'));
+        if (!existsSync(source))
+            continue;
+        const destination = path.join(destinationRoot, ...relativePath.split('/'));
+        mkdirSync(path.dirname(destination), { recursive: true });
+        writeFileSync(destination, readFileSync(source));
+    }
+    return destinationRoot;
+}

package/dist/types.d.ts

@@ -0,0 +1,70 @@
+export type ProjectProfile = 'javascript' | 'python' | 'fullstack' | 'monorepo' | 'custom';
+export type AgentProvider = 'codex' | 'claude';
+export interface ProjectCommands {
+    build?: string;
+    typecheck?: string;
+    lint?: string;
+    test?: string;
+}
+export interface ProjectFacts {
+    root: string;
+    name: string;
+    profile: ProjectProfile;
+    markers: string[];
+    sourceRoots: string[];
+    testRoots: string[];
+    commands: ProjectCommands;
+    packageManager?: string;
+    gitDirty: boolean | null;
+    existingAgentFiles: string[];
+}
+export interface HarnessConfig {
+    schemaVersion: 1;
+    project: {
+        name: string;
+        profile: ProjectProfile;
+    };
+    agents: AgentProvider[];
+    workflow: {
+        provider: 'native' | 'openspec';
+    };
+    architecture: {
+        sourceRoots: string[];
+        testRoots: string[];
+    };
+    commands: ProjectCommands;
+}
+export interface RenderedArtifact {
+    path: string;
+    content: string;
+}
+export type PlanAction = 'create' | 'update' | 'unchanged' | 'conflict';
+export interface PlannedArtifact extends RenderedArtifact {
+    action: PlanAction;
+    reason: string;
+    previousHash?: string;
+    nextHash: string;
+}
+export interface InstallPlan {
+    root: string;
+    frameworkVersion: string;
+    facts: ProjectFacts;
+    artifacts: PlannedArtifact[];
+    conflicts: string[];
+}
+export interface ManifestEntry {
+    hash: string;
+}
+export interface HarnessManifest {
+    schemaVersion: 1;
+    framework: {
+        name: 'agent-harness-init';
+        version: string;
+    };
+    installedAt: string;
+    files: Record<string, ManifestEntry>;
+}
+export interface DoctorFinding {
+    path: string;
+    status: 'ok' | 'missing' | 'modified';
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,7 @@
+import type { HarnessConfig } from './types.js';
+export interface VerificationResult {
+    name: string;
+    command: string;
+    status: number;
+}
+export declare function runConfiguredVerification(root: string, config: HarnessConfig): VerificationResult[];

package/dist/verify.js

@@ -0,0 +1,16 @@
+import { spawnSync } from 'node:child_process';
+export function runConfiguredVerification(root, config) {
+    const ordered = ['lint', 'typecheck', 'test', 'build'];
+    const results = [];
+    for (const name of ordered) {
+        const command = config.commands[name];
+        if (!command)
+            continue;
+        const result = spawnSync(command, { cwd: root, shell: true, stdio: 'inherit', windowsHide: true });
+        const status = result.status ?? 1;
+        results.push({ name, command, status });
+        if (status !== 0)
+            break;
+    }
+    return results;
+}

package/licenses/harness-ospx-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harness-OSPX Contributors
+
+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/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "agent-harness-init",
+  "version": "0.1.0",
+  "description": "Agent-native, provider-neutral Harness installer for adapting governance and verification gates to existing projects.",
+  "author": "xixixixi55",
+  "type": "module",
+  "bin": {
+    "agent-harness": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "licenses/"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "verify": "npm run typecheck && npm test && npm run build",
+    "release:check": "npm run verify && npm pack --dry-run --ignore-scripts",
+    "prepack": "npm run verify"
+  },
+  "keywords": [
+    "ai-agent",
+    "harness-engineering",
+    "governance",
+    "project-scaffold",
+    "openspec"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xixixixi55/agent-harness-init.git"
+  },
+  "homepage": "https://github.com/xixixixi55/agent-harness-init#readme",
+  "bugs": {
+    "url": "https://github.com/xixixixi55/agent-harness-init/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/agent-harness-init/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: agent-harness-init
+description: Install, deploy, initialize, adapt, update, diagnose, or remove Agent Harness Init in an existing or new software project. Use when a user asks to add Harness gates or make a project Agent-governed. Do not use for ordinary feature implementation after the Harness is installed.
+---
+
+# Agent Harness Init
+
+Use the deterministic `agent-harness` CLI for discovery, planning, rendering,
+hashing, and writes. Use Agent judgment only to validate detected project facts
+and merge a minimal reference into an existing project-owned instruction file.
+
+## Install or adapt
+
+1. Resolve the exact target-project root and read its existing `AGENTS.md` or
+   equivalent instructions. A request to install in the current project
+   authorizes project-local Harness files, not global tools or external actions.
+2. Run `agent-harness plan --root <root>` before any mutation. If the executable
+   is unavailable, report the missing installation; do not silently install a
+   global package. A user-approved ephemeral fallback is
+   `npx agent-harness-init plan --root <root>`.
+3. Validate the detected profile and commands against bounded project metadata
+   such as `package.json`, `pyproject.toml`, workspace files, and CI entrypoints.
+   Do not broadly read source contents merely to initialize the Harness.
+4. If the plan reports any conflict, stop and explain the exact paths. Never use
+   overwrite flags to bypass an unowned or modified file.
+5. Apply with `agent-harness init --root <root> --yes`.
+6. When a project-owned `AGENTS.md` already exists, preserve it and add only a
+   concise reference to `AGENT_HARNESS.md` if no equivalent reference exists.
+   Do not weaken or replace existing rules.
+7. Run `agent-harness doctor --root <root>` and report the detected profile,
+   generated files, preserved files, and diagnostic result. Do not run the
+   project's full verification suite unless requested or needed for a separate
+   implementation task.
+
+For updates, uninstall, provider paths, conflict behavior, and authorization
+boundaries, read [references/install-protocol.md](references/install-protocol.md).

package/skills/agent-harness-init/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Agent Harness Init"
+  short_description: "Safely install and adapt Harness gates to a project"
+  default_prompt: "Use $agent-harness-init to install and adapt the Harness to this project."
+policy:
+  allow_implicit_invocation: true

package/skills/agent-harness-init/references/install-protocol.md

@@ -0,0 +1,43 @@
+# Installation protocol
+
+## Update
+
+Run a plan first, then `agent-harness update --root <root> --yes` only when no
+conflicts exist. Updates may replace files only when their current SHA-256 still
+matches `.harness/manifest.json`. Preserve modified managed files and report them.
+
+## Diagnose
+
+`agent-harness doctor --root <root>` returns non-zero when a managed file is
+missing or modified. Treat this as project drift, not permission to restore it.
+
+## Verify
+
+`agent-harness verify --root <root>` executes only commands declared in
+`harness.config.yaml`, stops at the first failure, and may be expensive. Use it
+when the user asks for gates or when implementation completion requires them.
+
+## Uninstall
+
+Run doctor first. `agent-harness uninstall --root <root> --yes` removes only
+unchanged managed files. It preserves modified or missing entries for manual
+resolution. Do not delete an existing project-owned `AGENTS.md` reference until
+the managed sidecar has been removed and the user wants full cleanup.
+
+## Global Bootstrap Skill
+
+Installing a global Skill is a separate mutation outside the target project:
+
+```text
+agent-harness install-skill --provider codex
+agent-harness install-skill --provider claude
+```
+
+Require explicit authorization for that scope. Existing destinations are not
+overwritten unless the user reviews and explicitly requests `--force`.
+
+## External boundaries
+
+A local Harness installation never authorizes Git commits, pushes, remote
+repository creation, package publication, telemetry, uploads, or network access.
+Obtain separate authorization when those actions are needed.