@minhduydev/md-harness

@minhduydev/md-harness

The composition and setup package for a project-local Pi development profile. It installs an exact-version set of independently packaged extensions while leaving the consumer application's dependency manifest untouched.

Default profile

All first-wave packages use the md-harness release version exactly:

Package	Ownership
@minhduydev/md-harness	setup CLI, behavioral kernel, skills, prompts, themes
@minhduydev/md-task	task/HerdR orchestration and four bundled agent profiles
@minhduydev/md-todo	artifact-backed TODO tools and reminders
@minhduydev/md-dcp	durable compression and session recall
@minhduydev/md-srcwalk	namespaced source-walk, semantic, and transactional-edit tools

Mixed versions are unsupported. setup derives the version from its own package metadata and registers every package as npm:<name>@<version>.

Requires Node.js 24+, npm 11+, and a compatible Pi installation. Published packages run no install lifecycle scripts and do not download or compile native code.

Quick start

# from your application repository root
npx @minhduydev/md-harness setup
pi

Then run /init inside Pi to reconcile repository context and local memory.

setup:

1. Runs pi install -l --approve for the five exact-version package sources in deterministic order.
2. Removes a conflicting project-local standalone @heyhuynhgiabuu/pi-task entry because md-task owns the task tool.
3. Appends a managed, idempotent .gitignore block for Pi package caches and local state before installation; if a later package fails, restores the original project package settings and attempts reverse-order rollback.
4. Leaves the application package.json and dependency lockfile unchanged.

Re-running setup is safe. Use npx @minhduydev/md-harness@<version> setup to select a specific compatible profile release.

What setup does not do

• It does not copy or symlink package resources into project-owned .pi roots.
• It does not publish, push, deploy, install global tools, or access release credentials.
• It does not write agent profiles into .pi/agents; package defaults remain read-only installation resources.
• It does not run native installers, download executables, mutate PATH, or compile Rust.

Ownership and overrides

• Author repository rules in .pi/AGENTS.md and .pi/APPEND_SYSTEM.md; the kernel is additive.
• Add a project or user agent with the same name to override explore, general, reviewer, or scout. Precedence is pi-task base < md-task < user < project.
• Keep .pi/MEMORY.md and session state local and gitignored.
• Keep .pi/artifacts/TODO.md, PLAN.md, PROGRESS.md, and DECISIONS.md under repository ownership.
• If standalone pi-task is installed globally, remove it from ~/.pi/agent/settings.json before starting Pi to avoid duplicate task registration.

md-srcwalk fallback policy

md-srcwalk is part of the default profile. Its TypeScript source walker, semantic fallback, and transactional-edit tools load without a native helper. A missing, incompatible, or invalid Rust binary must not block Pi startup.

The npm package runs no native lifecycle hook and contains no platform executable. Source-repository developers may explicitly build the pinned Rust helper; clean consumers remain on the deterministic fallback until checksum-verified platform packages are separately designed and released.

Update and uninstall

Update the complete profile:

npx @minhduydev/md-harness setup

Inspect exact installed sources with pi list. Remove every first-wave source to uninstall the profile:

pi remove -l npm:@minhduydev/md-srcwalk@<installed-version>
pi remove -l npm:@minhduydev/md-dcp@<installed-version>
pi remove -l npm:@minhduydev/md-todo@<installed-version>
pi remove -l npm:@minhduydev/md-task@<installed-version>
pi remove -l npm:@minhduydev/md-harness@<installed-version>

Optionally remove the managed ignore block afterward.

Installed layout

Pi installs npm package sources below the project-local .pi/npm/ cache. Package-owned dist/, extensions/, skills, prompts, themes, agent profiles, and fork sources are read-only and reproducible from their tarballs. Do not commit or edit the install tree.

A clean install must load the package entrypoints with zero resource diagnostics and expose the same runtime tool inventory as the authoring profile. Tarball checks reject tests, repository state, generated native build trees, sessions, artifacts, credentials, and unexpected executables.

What this tarball contains

The md-harness composition tarball contains compiled setup/kernel code, the remaining core extensions (including safety, diagnostics, checkpoint/rewind, providers, and the TUI composition shell), skills, prompts, themes, kernel documentation, README.md, LICENSE, and NOTICE.md. Task runtime, the TODO entrypoint, DCP, and srcwalk payloads are owned by their respective packages and are not duplicated here; TODO domain modules remain in core only where the TUI shell imports them.

License

MIT Minh Duy. Each first-wave package ships its own LICENSE and package-specific NOTICE.md; see @minhduydev/md-task and @minhduydev/md-srcwalk for upstream fork attribution.