Skip to content

DataArt/artisyn-implementation-harness / skills/implementation-harness

implementation-harness

Flagged

Install the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.

FileKindSize
CHANGELOG.mdmarkdown37.5 KB
README.mdmarkdown13.7 KB
SKILL.mdskill md9.6 KB
bin/artisyn-implementation-harness.mjsexecutablescript11.8 KB
bin/lib/placer.mjsscript2.6 KB
bin/lib/providers.mjsscript1.8 KB
bin/lib/reporter.mjsscript3.0 KB
bin/lib/zip.mjsscript4.0 KB
canonical/adaptors/claude/browser.mdmarkdown2.5 KB
canonical/adaptors/claude/context.mdmarkdown517 B
canonical/adaptors/claude/credentials.mdmarkdown512 B
canonical/adaptors/claude/delegation.mdmarkdown910 B
canonical/adaptors/claude/interaction.mdmarkdown359 B
canonical/adaptors/claude/planning.mdmarkdown745 B
canonical/adaptors/claude/review.mdmarkdown1.0 KB
canonical/adaptors/claude/task-tracking.mdmarkdown897 B
canonical/adaptors/codex/browser.mdmarkdown1.0 KB
canonical/adaptors/codex/context.mdmarkdown517 B
canonical/adaptors/codex/credentials.mdmarkdown480 B
canonical/adaptors/codex/delegation.mdmarkdown910 B
canonical/adaptors/codex/interaction.mdmarkdown359 B
canonical/adaptors/codex/planning.mdmarkdown904 B
canonical/adaptors/codex/review.mdmarkdown973 B
canonical/adaptors/codex/task-tracking.mdmarkdown1.1 KB
canonical/adaptors/copilot/browser.mdmarkdown620 B
canonical/adaptors/copilot/context.mdmarkdown881 B
canonical/adaptors/copilot/credentials.mdmarkdown992 B
canonical/adaptors/copilot/delegation.mdmarkdown1.2 KB
canonical/adaptors/copilot/interaction.mdmarkdown454 B
canonical/adaptors/copilot/planning.mdmarkdown785 B
canonical/adaptors/copilot/review.mdmarkdown791 B
canonical/adaptors/copilot/task-tracking.mdmarkdown723 B
canonical/agents/architect/INTENT.mdmarkdown2.4 KB
canonical/agents/architect/TEMPLATE.mdmarkdown6.5 KB
canonical/agents/docs-writer/INTENT.mdmarkdown2.2 KB
canonical/agents/docs-writer/TEMPLATE.mdmarkdown2.8 KB
canonical/agents/infra/INTENT.mdmarkdown2.1 KB
canonical/agents/infra/TEMPLATE.mdmarkdown5.1 KB
canonical/agents/layer/INTENT.mdmarkdown6.0 KB
canonical/agents/layer/TEMPLATE.mdmarkdown1.5 KB
canonical/agents/onboarding/INTENT.mdmarkdown5.3 KB
canonical/agents/onboarding/TEMPLATE.mdmarkdown4.2 KB
canonical/agents/product-architect/INTENT.mdmarkdown7.5 KB
canonical/agents/product-architect/TEMPLATE.mdmarkdown3.9 KB
canonical/agents/scrum-master/INTENT.mdmarkdown10.9 KB
canonical/agents/scrum-master/TEMPLATE.mdmarkdown12.3 KB
canonical/docs/.og/cli.mjsscript13.6 KB
canonical/docs/.og/cli.test.mjsscript19.6 KB
canonical/docs/.og/constants.mjsscript2.9 KB
canonical/docs/.og/docs-operational-graph.sqlitebinary24.0 KB
canonical/docs/.og/docs.mjsscript5.5 KB
canonical/docs/.og/edges.mjsscript5.8 KB
canonical/docs/.og/schema.mjsscript741 B
canonical/docs/.og/utils.mjsscript5.2 KB
canonical/docs/Engineering Guide/01 Conventions.mdmarkdown3.0 KB
canonical/docs/Engineering Guide/03 Engineer Role.mdmarkdown2.6 KB
canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/05 MCP Setup.mdmarkdown6.6 KB
canonical/docs/Engineering Guide/Documentation/01 Principles.mdmarkdown15.3 KB
canonical/docs/Engineering Guide/Documentation/02 Structure.mdmarkdown3.8 KB
canonical/docs/Engineering Guide/Documentation/03 HLD Intent.mdmarkdown8.1 KB
canonical/docs/Engineering Guide/Documentation/04 LLD Intent.mdmarkdown9.7 KB
canonical/docs/Engineering Guide/Documentation/05 NFR Intent.mdmarkdown6.0 KB
canonical/docs/Engineering Guide/Documentation/07 Terminology.mdmarkdown1.4 KB
canonical/docs/Engineering Guide/Lifecycles/00 Overview.mdmarkdown5.8 KB
canonical/docs/Engineering Guide/Lifecycles/01 Dev Lifecycle.mdmarkdown19.9 KB
canonical/docs/Engineering Guide/Lifecycles/02 Design Lifecycle.mdmarkdown29.4 KB
canonical/docs/Engineering Guide/Lifecycles/03 Evolve Lifecycle.mdmarkdown7.0 KB
canonical/docs/Engineering Guide/Lifecycles/04 Architecture Lifecycle.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/Lifecycles/05 Documents Flow.mdmarkdown9.5 KB
canonical/manifest.jsonconfig1.6 KB
canonical/mcp.jsonconfig23 B
canonical/root-instructions/INTERFACE.mdmarkdown3.3 KB
canonical/settings.jsonconfig332 B
canonical/skills/design/INTENT.mdmarkdown28.6 KB
canonical/skills/design/TEMPLATE.mdmarkdown19.0 KB
canonical/skills/design/interfaces/architecture.mdmarkdown2.8 KB
canonical/skills/design/interfaces/contract.mdmarkdown7.4 KB
canonical/skills/design/interfaces/design.mdmarkdown2.3 KB
canonical/skills/design/interfaces/efforts.mdmarkdown2.5 KB
canonical/skills/design/interfaces/stack.mdmarkdown1.6 KB
canonical/skills/design/patterns/announce-progress.mdmarkdown997 B
canonical/skills/design/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/design/patterns/approval-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/context-resolution.mdmarkdown6.6 KB
canonical/skills/design/patterns/design-architect-review.mdmarkdown2.4 KB
canonical/skills/design/patterns/design-oq-triage.mdmarkdown3.8 KB
canonical/skills/design/patterns/design-quality-gate.mdmarkdown1.4 KB
canonical/skills/design/patterns/do-report-commit.mdmarkdown1.2 KB
canonical/skills/design/patterns/docs-writer-authoring.mdmarkdown3.6 KB
canonical/skills/design/patterns/metrics.mdmarkdown11.9 KB
canonical/skills/design/patterns/multi-decision-split.mdmarkdown3.6 KB
canonical/skills/design/patterns/phase-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/satellite-review.mdmarkdown1.5 KB
canonical/skills/design/patterns/session-continuity.mdmarkdown827 B
canonical/skills/design/patterns/task-tracking.mdmarkdown779 B
canonical/skills/design/patterns/waf-review.mdmarkdown4.2 KB
canonical/skills/design/patterns/write-confirm.mdmarkdown963 B
canonical/skills/design/references/00-decision-router.mdmarkdown3.8 KB
canonical/skills/design/references/00-router.mdmarkdown4.6 KB
canonical/skills/design/references/01-context-gathering.mdmarkdown8.1 KB
canonical/skills/design/references/02-ceremony.mdmarkdown4.6 KB
canonical/skills/design/references/03-frame.mdmarkdown6.7 KB
canonical/skills/design/references/04-research.mdmarkdown8.1 KB
canonical/skills/design/references/05-evaluate.mdmarkdown9.0 KB
canonical/skills/design/references/06-solution.mdmarkdown13.7 KB
canonical/skills/design/references/07-review-gate.mdmarkdown4.1 KB
canonical/skills/design/references/08-address-feedback.mdmarkdown8.0 KB
canonical/skills/design/references/09-publish.mdmarkdown8.9 KB
canonical/skills/design/references/10-completion.mdmarkdown7.4 KB
canonical/skills/design/scripts/constants.mjsscript2.0 KB
canonical/skills/design/scripts/design-metrics.mjsscript35.4 KB
canonical/skills/design/scripts/design-metrics.test.mjsscript12.0 KB
canonical/skills/design/scripts/utils.mjsscript3.1 KB
canonical/skills/design/templates/evaluate.mdmarkdown1.4 KB
canonical/skills/design/templates/frame.mdmarkdown2.6 KB
canonical/skills/design/templates/report.mdmarkdown4.8 KB
canonical/skills/design/templates/research.mdmarkdown2.4 KB
canonical/skills/design/templates/stat.jsonconfig1.7 KB
canonical/skills/design/templates/stat.schema.jsonconfig17.1 KB
canonical/skills/dev/INTENT.mdmarkdown15.9 KB
canonical/skills/dev/TEMPLATE.mdmarkdown9.0 KB
canonical/skills/dev/interfaces/intent.mdmarkdown2.6 KB
canonical/skills/dev/patterns/announce-progress.mdmarkdown1.1 KB
canonical/skills/dev/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/dev/patterns/approval-sign-off.mdmarkdown1.9 KB
canonical/skills/dev/patterns/do-report-commit.mdmarkdown888 B
canonical/skills/dev/patterns/metrics.mdmarkdown17.7 KB
canonical/skills/dev/patterns/phase-sign-off.mdmarkdown2.2 KB
canonical/skills/dev/patterns/review-gate.mdmarkdown3.6 KB
canonical/skills/dev/patterns/satellite-review.mdmarkdown3.1 KB
canonical/skills/dev/patterns/session-continuity.mdmarkdown797 B
canonical/skills/dev/patterns/task-tracking.mdmarkdown766 B
canonical/skills/dev/patterns/write-confirm.mdmarkdown615 B
canonical/skills/dev/references/00-router.mdmarkdown2.2 KB
canonical/skills/dev/references/01-context-gathering.mdmarkdown10.3 KB
canonical/skills/dev/references/02-ceremony.mdmarkdown4.5 KB
canonical/skills/dev/references/03-plan.mdmarkdown14.2 KB
canonical/skills/dev/references/04-implement.mdmarkdown11.7 KB
canonical/skills/dev/references/05-test.mdmarkdown7.8 KB
canonical/skills/dev/references/06-document.mdmarkdown11.7 KB
canonical/skills/dev/references/07-completion.mdmarkdown6.3 KB
canonical/skills/dev/scripts/constants.mjsscript3.2 KB
canonical/skills/dev/scripts/quality.mjsscript9.1 KB
canonical/skills/dev/scripts/quality.test.mjsscript6.6 KB
canonical/skills/dev/scripts/timing.mjsscript38.1 KB
canonical/skills/dev/scripts/timing.test.mjsscript21.0 KB
canonical/skills/dev/scripts/utils.mjsscript3.1 KB
canonical/skills/dev/templates/plan.mdmarkdown3.3 KB
canonical/skills/dev/templates/report.mdmarkdown6.4 KB
canonical/skills/dev/templates/stat.jsonconfig1.4 KB
canonical/skills/dev/templates/stat.schema.jsonconfig29.3 KB
canonical/skills/evolve/INTENT.mdmarkdown1.6 KB
canonical/skills/evolve/TEMPLATE.mdmarkdown1.3 KB
canonical/skills/evolve/interfaces/improvement.mdmarkdown1.2 KB
canonical/skills/evolve/interfaces/reflection.mdmarkdown353 B
canonical/skills/evolve/interfaces/validation.mdmarkdown653 B
canonical/skills/evolve/patterns/task-tracking.mdmarkdown787 B
canonical/skills/evolve/references/00-router.mdmarkdown1.1 KB
canonical/skills/evolve/references/01-reflect.mdmarkdown805 B
canonical/skills/evolve/references/02-triage.mdmarkdown2.6 KB
canonical/skills/evolve/references/03-draft.mdmarkdown1.2 KB
canonical/skills/evolve/references/04-validate.mdmarkdown1.5 KB
canonical/skills/evolve/references/05-adopt.mdmarkdown1.5 KB
canonical/skills/war/INTENT.mdmarkdown4.5 KB
canonical/skills/war/TEMPLATE.mdmarkdown1.8 KB
canonical/skills/war/patterns/present-and-save.mdmarkdown1.0 KB
canonical/skills/war/patterns/scope-resolution.mdmarkdown830 B
canonical/skills/war/references/01-design.mdmarkdown3.4 KB
canonical/skills/war/references/02-implementation.mdmarkdown3.8 KB
canonical/skills/war/templates/design-report.mdmarkdown869 B
canonical/skills/war/templates/implementation-report.mdmarkdown1.8 KB
canonical/skills/where-we-are/INTENT.mdmarkdown3.3 KB
canonical/skills/where-we-are/TEMPLATE.mdmarkdown6.3 KB
canonical/skills/where-we-are/report-template.mdmarkdown2.0 KB
canonical/skills/x-ray/INTENT.mdmarkdown2.4 KB
canonical/skills/x-ray/TEMPLATE.mdmarkdown10.5 KB
implementation-harness.mdmarkdown1.4 KB
package.jsonmanifest696 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/CHANGELOG.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/README.md.patchother1.9 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/SKILL.md.patchother2.5 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/agents/docs-writer/INTENT.md.patchother1.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/.og/cli.test.mjs.patchother846 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.md.patchother3.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/05 MCP Setup.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/manifest.json.patchother662 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/settings.json.patchother150 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/skills/design/INTENT.md.patchother19.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/patterns/skill-authoring.md.patchother692 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/host-capabilities.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01-launch.md.patchother1.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01a-launch-plan.md.patchother1.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01b-launch-install.md.patchother7.3 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/02-launch-questions.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/08-provider-launch.md.patchother3.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/04-patch-harvest.md.patchother2.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/05-patch-apply.md.patchother3.0 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/06-patch-state.md.patchother7.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/scripts/lib/agent-format.mjs.patchother2.2 KB

bin/artisyn-implementation-harness.mjs

View on GitHub
#!/usr/bin/env node
/** Install CLI for the Artisyn Implementation Harness: init, update, doctor.
 *
 * It places the package in a provider skills folder and keeps the project's `.harness/state/`
 * and `package:` records in step. It does not run launch or patch apply. Node >= 22, `node:`
 * modules only.
 */
import fs from 'node:fs';
import path from 'node:path';
import { createHash } from 'node:crypto';
import { fileURLToPath } from 'node:url';
import { parseArgs } from 'node:util';
import {
  ensureGitignore,
  ensureStateDirs,
  readPackageIdentity,
  resolvePackagePath,
  resolveProjectRoot,
  stateDirOf,
  writePackageRecord,
} from '../scripts/lib/state-root.mjs';
import {
  PACKAGE_FOLDER,
  PROVIDER_NAMES,
  command,
  detectProviders,
  launchCommand,
  providerOfPath,
  skillsFolder,
} from './lib/providers.mjs';
import { placePackage, swapPackage } from './lib/placer.mjs';
import { extractZip } from './lib/zip.mjs';
import {
  VERSION_PATTERN,
  compareVersions,
  releaseAsset,
  releaseTag,
  updateCommand,
} from './lib/reporter.mjs';

const OWN_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const DEFAULT_RELEASE_BASE =
  'https://github.com/DataArt/artisyn-implementation-harness/releases/download';
const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
const CHANNELS = ['npm', 'zip'];

const USAGE = `Usage: artisyn-implementation-harness <command> [options]

Commands
  init      Place the package in the first selected provider's skills folder and create .harness/state/
  update    Replace the installed package with the version of this CLI (npm) or a release ZIP (zip)
  doctor    Report installed packages, versions and state health

Options
  --dir <path>               Project root (default: git top level, else the working directory)
  --provider <name>          claude, codex or copilot; repeatable (init)
  --channel <npm|zip>        How this package was obtained (init; default npm)
  --version <x.y.z>          Version to update to (update)
  --force                    Replace a different version (init) or allow a downgrade (update)
  --release-base-url <url>   Release origin for the zip channel; https or loopback http only
`;

class Exit extends Error {
  constructor(code, message) {
    super(message);
    this.exitCode = code;
  }
}

const say = (line = '') => process.stdout.write(`${line}\n`);
const warn = (line) => process.stderr.write(`${line}\n`);
const relative = (root, file) => path.relative(root, file).split(path.sep).join('/') || '.';

function ownIdentity() {
  const identity = readPackageIdentity(OWN_DIR);
  if (!identity) throw new Exit(1, `Cannot read this package's name and version from ${OWN_DIR}`);
  return identity;
}

function readRecord(root) {
  const file = path.join(stateDirOf(root), 'launch', 'package.json');
  if (!fs.existsSync(file)) return null;
  return JSON.parse(fs.readFileSync(file, 'utf8'));
}

function installedFolders(root) {
  return PROVIDER_NAMES.map((provider) => ({
    provider,
    dir: path.join(root, skillsFolder(provider), PACKAGE_FOLDER),
  })).filter(({ dir }) => fs.existsSync(dir));
}

function validateReleaseBase(raw) {
  let url;
  try {
    url = new URL(raw);
  } catch {
    throw new Exit(2, `--release-base-url is not a URL: ${raw}`);
  }
  const loopback = url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
  if (url.protocol !== 'https:' && !loopback)
    throw new Exit(
      2,
      '--release-base-url must use https: (or http: on a loopback address, for tests)'
    );
  return raw.replace(/\/+$/, '');
}

async function download(url) {
  const response = await fetch(url);
  if (!response.ok) throw new Exit(1, `Download failed: GET ${url} returned ${response.status}`);
  return Buffer.from(await response.arrayBuffer());
}

// ---------------------------------------------------------------------------------- init

function init(root, options) {
  let providers;
  try {
    providers = detectProviders(root, options.provider ?? []);
  } catch (error) {
    throw new Exit(2, error.message);
  }
  if (providers.length === 0)
    throw new Exit(
      2,
      'No provider detected. Create .claude/, .agents/ or .github/ in the project, or pass --provider claude|codex|copilot.'
    );
  const channel = options.channel ?? 'npm';
  if (!CHANNELS.includes(channel))
    throw new Exit(2, `--channel must be one of ${CHANNELS.join(', ')}`);

  const provider = providers[0];
  const target = path.join(root, skillsFolder(provider), PACKAGE_FOLDER);
  const own = ownIdentity();
  let alreadyInstalled = false;
  if (fs.existsSync(target)) {
    const present = readPackageIdentity(target);
    alreadyInstalled = present?.version === own.version && !options.force;
    if (!alreadyInstalled && !options.force)
      throw new Exit(
        1,
        `${relative(root, target)} already holds a different version (${present?.version ?? 'unknown'}); use --force to replace it.`
      );
  }
  if (!alreadyInstalled) placePackage({ source: OWN_DIR, target });

  ensureStateDirs(root);
  ensureGitignore(root);
  writePackageRecord(root, { ...own, channel, path: target });

  say(
    `${alreadyInstalled ? 'Already installed' : 'Installed'} ${own.name} ${own.version} in ${relative(root, target)}`
  );
  say('State root: .harness/state/');
  say(`Next: run \`${launchCommand(provider)}\``);
}

// -------------------------------------------------------------------------------- update

async function update(root, options) {
  const record = readRecord(root);
  if (!record)
    throw new Exit(1, 'No install record at .harness/state/launch/package.json. Run `init` first.');
  const target = resolvePackagePath(root);
  if (!target)
    throw new Exit(1, 'Cannot find the installed package for the recorded version. Run `doctor`.');
  const provider = providerOfPath(root, target);
  const installed = readPackageIdentity(target)?.version ?? record.version;
  const own = ownIdentity();

  if (!CHANNELS.includes(record.channel)) {
    say(
      `This install came from ${record.channel}; update it with: ${updateCommand({ ...record, provider })}`
    );
    say(`Then run \`${command(provider, 'patch apply')}\`.`);
    return;
  }
  const wanted = options.version ?? own.version;
  if (!VERSION_PATTERN.test(wanted))
    throw new Exit(2, `--version must look like 1.2.3, got: ${wanted}`);
  if (record.channel === 'npm' && wanted !== own.version)
    throw new Exit(2, `This CLI is ${own.version}. Run: npx ${own.name}@${wanted} update`);

  const order = compareVersions(wanted, installed);
  if (order === 0) {
    say(`Already at ${installed}; nothing to do.`);
    return;
  }
  if (order < 0 && !options.force)
    throw new Exit(3, `Refusing to downgrade ${installed} to ${wanted}. Use --force to allow it.`);

  if (record.channel === 'npm') placePackage({ source: OWN_DIR, target });
  else await updateFromRelease({ target, wanted, base: options.releaseBase });

  writePackageRecord(root, {
    name: record.name,
    version: wanted,
    channel: record.channel,
    path: target,
  });
  say(`Updated ${record.name} ${installed} -> ${wanted} (${record.channel})`);
  say(`Next: run \`${command(provider, 'patch apply')}\``);
}

async function updateFromRelease({ target, wanted, base }) {
  const tag = releaseTag(wanted);
  const asset = releaseAsset(wanted);
  const origin = base ?? DEFAULT_RELEASE_BASE;
  const zipUrl = `${origin}/${tag}/${asset}.zip`;
  const zip = await download(zipUrl);
  const expected = (await download(`${zipUrl}.sha256`)).toString('utf8').trim().split(/\s+/)[0];
  const actual = createHash('sha256').update(zip).digest('hex');
  if (!/^[a-f0-9]{64}$/.test(expected) || expected !== actual)
    throw new Exit(
      1,
      `sha256 mismatch for ${asset}.zip: expected ${expected}, got ${actual}. The installed package is unchanged.`
    );

  const parent = path.dirname(target);
  fs.mkdirSync(parent, { recursive: true });
  const scratch = fs.mkdtempSync(path.join(parent, '.implementation-harness-update-'));
  try {
    extractZip(zip, scratch);
    const staged = path.join(scratch, PACKAGE_FOLDER);
    const identity = fs.existsSync(staged) ? readPackageIdentity(staged) : null;
    if (!identity || identity.version !== wanted)
      throw new Exit(
        1,
        `The archive does not hold ${PACKAGE_FOLDER} ${wanted}. The installed package is unchanged.`
      );
    swapPackage({ staged, target });
  } finally {
    fs.rmSync(scratch, { recursive: true, force: true });
  }
}

// --------------------------------------------------------------------------------- doctor

function doctor(root) {
  let problems = 0;
  const problem = (text) => {
    problems += 1;
    say(`  PROBLEM  ${text}`);
  };
  const record = readRecord(root);
  const installs = installedFolders(root).map((item) => ({
    ...item,
    identity: readPackageIdentity(item.dir),
  }));

  say(`Project: ${root}`);
  say('Installed packages:');
  if (installs.length === 0) say('  none in the provider skills folders');
  for (const { provider, dir, identity } of installs)
    say(
      `  ${provider}: ${relative(root, dir)} (${identity ? `${identity.name} ${identity.version}` : 'unreadable'})`
    );

  const versions = new Set(installs.map(({ identity }) => identity?.version).filter(Boolean));
  if (versions.size > 1)
    problem(
      `version skew between providers: ${installs.map((i) => `${i.provider} ${i.identity?.version}`).join(', ')}`
    );

  if (record) {
    say(`Recorded: ${record.name} ${record.version} via ${record.channel}`);
    const located = resolvePackagePath(root);
    if (located) say(`  package path: ${located}`);
    else if (installs.length === 0) problem('the recorded package cannot be found on this machine');
    const provider = installs[0]?.provider ?? 'claude';
    say(`  update: ${updateCommand({ ...record, provider })}`);
    say(
      `  launch: ${record.channel === 'marketplace' ? `${command(provider, 'launch').replace('implementation-harness', 'artisyn:implementation-harness')}` : launchCommand(provider)}`
    );
  } else if (installs.length === 0) {
    problem('no installed package and no install record; run `init`');
  } else {
    problem('no install record at .harness/state/launch/package.json; run `init` or launch once');
  }

  say(
    fs.existsSync(stateDirOf(root)) ? 'State root: .harness/state/ present' : 'State root: missing'
  );
  if (!fs.existsSync(stateDirOf(root))) problem('.harness/state/ does not exist');

  say(problems === 0 ? 'OK' : `${problems} problem(s) found`);
  process.exitCode = problems === 0 ? 0 : 1;
}

// ----------------------------------------------------------------------------------- main

async function main(argv) {
  const { values, positionals } = parseArgs({
    args: argv,
    allowPositionals: true,
    options: {
      dir: { type: 'string' },
      provider: { type: 'string', multiple: true },
      channel: { type: 'string' },
      version: { type: 'string' },
      force: { type: 'boolean', default: false },
      'release-base-url': { type: 'string' },
      help: { type: 'boolean', default: false },
    },
  });
  const [name] = positionals;
  if (values.help || !name) {
    say(USAGE);
    return;
  }
  const root = values.dir ? path.resolve(values.dir) : resolveProjectRoot();
  const options = {
    provider: values.provider,
    channel: values.channel,
    version: values.version,
    force: values.force,
    releaseBase: values['release-base-url']
      ? validateReleaseBase(values['release-base-url'])
      : undefined,
  };
  switch (name) {
    case 'init':
      return init(root, options);
    case 'update':
      return update(root, options);
    case 'doctor':
      return doctor(root);
    default:
      throw new Exit(2, `Unknown command "${name}".\n\n${USAGE}`);
  }
}

main(process.argv.slice(2)).catch((error) => {
  warn(error instanceof Exit ? error.message : `Unexpected error: ${error.stack ?? error.message}`);
  process.exitCode = error instanceof Exit ? error.exitCode : 1;
});
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall