pi-harness-runtime 1.1.445 → 1.1.446

package/harness/skills-plan/2026-07-12-herdr-moo-skills-adaptation-plan.md

@@ -1,282 +0,0 @@
-# Herdr-style Skill Adaptation Plan for `pi-harness-runtime`
-
-## Goal
-
-Study Herdr's reusable `SKILL.md` distribution model and adapt the idea to `pi-harness-runtime` **without** treating the live MooCoding skill corpus as publishable package content.
-
-## Source Context
-
-### External reference
-
-- Herdr docs: `https://herdr.dev/docs/agent-skill/`
-- Herdr source skill: `https://github.com/ogulcancelik/herdr/blob/master/SKILL.md`
-
-### Local source of truth to protect
-
-- Live skills: `~/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
-
-### Current runtime state
-
-- `pi-harness-runtime` ships exactly one skill of its own:
-  - `package.json` -> `pi.skills = ["./skills"]`
-  - `skills/harness-runtime/SKILL.md` - the skill of the package itself
-  - every other skill payload lives in the user's own Qdrant collection and
-    in the installation-local skill store, never in the published package
-- `packages/skills` is the runtime implementation: it discovers, sanitizes,
-  embeds and queries skills.
-- The scanner still reads the `skills/` and `.agents/skills/` directories of
-  the *working* project, so a project may keep its own skills on disk.
-
----
-
-## Critical Constraints
-
-### 1. Live MooCoding skills must remain the evolving knowledge base
-
-The directory:
-
-`~/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
-
-is continuously updated and acts as the operational knowledge base.
-
-Implication:
-
-- `pi-harness-runtime` must **not** become the primary authoring location for those skills.
-- Any adaptation must preserve the bench-side corpus as the editable source of truth.
-
-### 2. Live MooCoding skills are not yet safe to publish
-
-Those skills may still contain:
-
-- client names
-- project-specific identifiers
-- internal procedures
-- sensitive business context
-- unsanitized examples
-
-Implication:
-
-- Do **not** copy the entire MooCoding corpus into the publishable `pi-harness-runtime` package.
-- Do **not** expose those files through npm/GitHub package distribution until sanitization is proven.
-- Treat publication as a separate release stage with explicit validation gates.
-
----
-
-## What Herdr Actually Gives Us
-
-Herdr demonstrates a **distribution pattern**, not a safe-content pipeline:
-
-- repository-hosted `SKILL.md`
-- installable via `npx skills add <repo> --skill <name> -g`
-- raw `SKILL.md` is the manual fallback/source of truth
-
-Useful takeaway:
-
-- `pi-harness-runtime` can adopt Herdr's packaging/install ergonomics for skills
-- but must add a stronger separation between **live private skill source** and **sanitized public skill artifacts**
-
----
-
-## Recommended Architecture
-
-Use a **three-tier model**.
-
-### Tier A — Private live source
-
-Location:
-
-- `~/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
-
-Role:
-
-- authoritative editable knowledge base
-- may contain unsanitized internal content
-- never published directly
-
-### Tier B — Curated staging area
-
-Proposed role:
-
-- local-only review area for candidate skills
-- explicit human or automated sanitization review
-- contains only skills being prepared for distribution
-
-Possible future location options:
-
-- `pi-harness-runtime/harness/skills-staging/`
-- separate private repo
-- generated temporary export directory outside package root
-
-### Tier C — Public distributable skills
-
-Location:
-
-- `pi-harness-runtime/skills/*`
-
-Role:
-
-- sanitized, approved subset only
-- package-safe
-- installable Herdr-style through repo/package distribution
-
----
-
-## Recommended Plan
-
-## Phase 1 — Keep publication and live authoring separate
-
-Decision:
-
-- Keep MooCoding skills authored only in the bench-side directory
-- Keep `pi-harness-runtime/skills/*` as a **public distribution surface**, not the live working corpus
-
-Actions:
-
-1. Document the split-brain model clearly:
-   - private live source
-   - public curated export
-2. Do not auto-sync all live skills into the package
-3. Only allow explicit export of selected skills
-
-Success criteria:
-
-- no accidental publication path from private corpus to npm package
-- package repo remains safe by default
-
-## Phase 2 — Define a sanitization gate before export
-
-Create a formal checklist for any skill before publication.
-
-Required checks:
-
-- no client names
-- no private URLs/IPs/domains
-- no credentials/tokens/cookies
-- no environment-specific hostnames
-- no private repo names unless intended for public disclosure
-- no business-sensitive examples
-- no customer-specific workflow assumptions
-
-Recommended validation modes:
-
-1. automated scanner
-2. manual human review
-3. approved export manifest
-
-Success criteria:
-
-- every published skill has traceable sanitization approval
-- the export path is auditable
-
-## Phase 3 — Add an explicit export workflow
-
-Instead of publishing directly from the live skill tree, add a tool/script that:
-
-1. selects one or more source skills from the private corpus
-2. copies them into a staging/export area
-3. runs sanitization checks
-4. writes approved results into `pi-harness-runtime/skills/`
-
-Important rule:
-
-- export should be **pull-based and explicit**, never automatic background mirroring
-
-Suggested future command shape:
-
-- `scripts/export-skill.ts --source <private-skill> --target <public-skill>`
-- optional `--check-only`
-- optional `--manifest approved-skills.json`
-
-Success criteria:
-
-- no bulk one-shot publish of the entire MooCoding corpus
-- each public skill has an intentional export event
-
-## Phase 4 — Use Herdr-style installation only for approved public skills
-
-Once a sanitized skill exists inside `pi-harness-runtime/skills/<name>/SKILL.md`:
-
-- expose it through the existing `pi.skills` package field
-- document Herdr-style installation ergonomics for the public subset
-
-This gives the benefit of Herdr's distribution model without risking raw private content leakage.
-
-Success criteria:
-
-- only sanitized skills are installable from the public runtime package
-- public docs never point users at the live private MooCoding corpus
-
-## Phase 5 — Optional local filesystem loader for private use
-
-If desired, extend `packages/skill-registry` later to read `SKILL.md` files from configurable local directories.
-
-This should be treated as a **local runtime feature**, not a publication mechanism.
-
-Potential capabilities:
-
-- discover local private skills from configured paths
-- list them in the runtime
-- mark source type: `bundled` vs `external-private`
-- never publish external-private skills automatically
-
-Important safeguard:
-
-- external-private discovery must not imply packaging or registry distribution
-
-Success criteria:
-
-- local users can benefit from private skills dynamically
-- private skill ingestion remains isolated from public release paths
-
----
-
-## Non-Goals
-
-The following should **not** happen in the first implementation:
-
-- copying the full MooCoding skill corpus into `pi-harness-runtime/skills/`
-- publishing unsanitized skills to npm/GitHub
-- treating the package repo as the authoring source of truth
-- building automatic bidirectional sync between private and public skill trees
-- assuming Herdr's install model is sufficient without a content-safety layer
-
----
-
-## Proposed Deliverables
-
-### Immediate deliverable
-
-- this planning note in `harness/skills-plan/`
-
-### Next implementation deliverables
-
-1. `PUBLIC_SKILLS_POLICY.md` or similar policy doc
-2. sanitization checklist/spec
-3. explicit export script for selected skills
-4. public skill index for approved packaged skills
-5. optional file-backed registry loader for local-only skill discovery
-
----
-
-## Suggested Execution Order
-
-1. Write policy: private vs public skill boundary
-2. Define sanitization rules and approval process
-3. Implement export workflow for selected skills only
-4. Publish one or two proven-safe sample skills first
-5. Only then consider broader Herdr-style public skill distribution
-6. Later, separately, consider local private skill loading in `packages/skill-registry`
-
----
-
-## Recommendation
-
-**Do not adapt by importing the full MooCoding corpus into `pi-harness-runtime` right now.**
-
-Best first move:
-
-- keep MooCoding skills private and live
-- make `pi-harness-runtime` the home only for **sanitized exported skills**
-- treat Herdr as the inspiration for install UX, not as the whole architecture
-
-This preserves your knowledge base, avoids accidental disclosure, and still leaves room for a clean public skill distribution story later.

package/harness/skills-plan/2026-07-12-minimax-prompt-step1-sync.md

@@ -1,345 +0,0 @@
-# Minimax Prompt — Implement Skills Sync First Slice
-
-Use this prompt with Minimax to implement the first safe slice of the MooCoding skill export pipeline.
-
----
-
-You are coding inside this repo:
-
-- `~/pi-harness-runtime`
-
-Read these planning notes first:
-
-1. `harness/skills-plan/2026-07-12-herdr-moo-skills-adaptation-plan.md`
-2. `harness/skills-plan/2026-07-12-public-skill-export-and-sync-design.md`
-
-Also inspect this existing script for repo conventions:
-
-- `scripts/convert-skills-to-okf.ts`
-
-## Goal
-
-Implement only the **first safe slice** of the design:
-
-1. add private staging manifest files
-2. add a one-way `skills-sync.ts` command
-3. make sure sync updates only private staging and never public package skills
-
-Do **not** implement sanitize or export in this task.
-
----
-
-## Critical constraints
-
-The live private source of truth is:
-
-- `~/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
-
-This source changes often and may contain private or unsanitized content.
-
-Therefore:
-
-- sync is allowed
-- publish is not allowed
-- sync must go only into private staging
-- sync must never write to `skills/*`
-- sync must never mirror the whole private corpus by default
-- sync must be allowlist/manifest driven
-
-Treat this as a privacy-sensitive workflow.
-
----
-
-## Scope to implement
-
-### 1. Create staging manifest files
-
-Create these files:
-
-- `harness/skills-staging/manifests/source-index.json`
-- `harness/skills-staging/manifests/approval-index.json`
-
-Use safe initial content.
-
-Suggested initial shape:
-
-`source-index.json`
-
-```json
-{
-  "version": 1,
-  "sourceRoot": "~/frappe-bench/.claude-plugins/moocoding-skills/skills",
-  "skills": []
-}
-```
-
-`approval-index.json`
-
-```json
-{
-  "version": 1,
-  "skills": []
-}
-```
-
-The `skills` entries in `source-index.json` should support at least:
-
-```json
-{
-  "sourceName": "form-state-persistence-fix",
-  "targetName": "form-state-persistence-fix",
-  "sync": true,
-  "publicCandidate": true
-}
-```
-
-You may define TypeScript interfaces in the sync script or a small helper module if needed.
-
-### 2. Create private staging ignore rules
-
-Add a repo-local ignore strategy so private mirrored content is not accidentally treated as public package content.
-
-Preferred approach:
-
-- create `harness/skills-staging/.gitignore`
-- ignore these directories:
-  - `source-mirror/`
-  - `sanitized-candidates/`
-  - `reports/`
-- do **not** ignore `manifests/`
-
-If you think an additional package-level safeguard is needed, explain it in your final summary, but keep the implementation minimal.
-
-### 3. Implement `scripts/skills-sync.ts`
-
-Create a Bun TypeScript script using repo style similar to `scripts/convert-skills-to-okf.ts`.
-
-Use:
-
-- shebang: `#!/usr/bin/env bun`
-- ESM imports
-- `fs/promises`
-- `existsSync` if useful
-- no extra dependencies
-
-### 4. Add package script aliases
-
-Add at least these package.json scripts:
-
-```json
-{
-  "skills:sync": "bun scripts/skills-sync.ts",
-  "skills:sync:check": "bun scripts/skills-sync.ts --check-only"
-}
-```
-
-Do not remove or alter existing scripts unrelated to this task.
-
----
-
-## CLI requirements for `skills-sync.ts`
-
-Support these flags:
-
-### Selection
-
-- `--skill <name>`
-- `--all-from-manifest`
-
-Exactly one selection mode must be used.
-
-### Modifiers
-
-- `--changed-only`
-- `--check-only`
-
-Allowed combinations:
-
-- `--skill <name>`
-- `--skill <name> --changed-only`
-- `--skill <name> --check-only`
-- `--all-from-manifest`
-- `--all-from-manifest --changed-only`
-- `--all-from-manifest --check-only`
-
-If flags are invalid or missing, print usage and exit non-zero.
-
----
-
-## Sync behavior
-
-### Source manifest loading
-
-Read `harness/skills-staging/manifests/source-index.json`.
-
-Use `sourceRoot` from that file.
-
-Optionally allow env override:
-
-- `MOO_SKILLS_SOURCE_ROOT`
-
-If you add the override, document it in code comments and final summary.
-
-### Skill selection
-
-- `--skill <name>` should only operate on a matching manifest entry
-- `--all-from-manifest` should only operate on manifest entries where `sync: true`
-- if a requested skill is not in the manifest, fail clearly
-- do not discover and sync arbitrary folders outside the manifest
-
-### Per-skill source path
-
-For each selected skill:
-
-- source file:
-  - `<sourceRoot>/<sourceName>/SKILL.md`
-- staging target file:
-  - `harness/skills-staging/source-mirror/<targetName>/SKILL.md`
-
-### Hashing and drift detection
-
-Compute a SHA-256 hash for the source file.
-
-Also determine previous mirror hash if the mirrored target file already exists.
-
-Use this to calculate:
-
-- `changed: true|false`
-- `previousHash`
-- `sourceHash`
-
-### `--changed-only`
-
-When enabled:
-
-- only copy files whose source hash differs from the current mirror hash
-- unchanged skills should still appear in the report as skipped/unchanged
-
-### `--check-only`
-
-When enabled:
-
-- do not write mirrored skill files
-- do not update reports except possibly a dry-run style summary file if you think that is useful
-- printing a summary is enough
-
-### Normal sync mode
-
-When not in `--check-only` mode:
-
-- create parent directories as needed
-- copy source `SKILL.md` into staging mirror
-- never write to `skills/*`
-- never modify approval manifest
-
----
-
-## Reporting requirements
-
-Write a machine-readable report file at:
-
-- `harness/skills-staging/reports/sync-report.json`
-
-Only in non-check mode.
-
-Suggested report structure:
-
-```json
-{
-  "version": 1,
-  "executedAt": "2026-07-12T00:00:00.000Z",
-  "mode": {
-    "selection": "skill",
-    "checkOnly": false,
-    "changedOnly": true
-  },
-  "skills": [
-    {
-      "sourceName": "form-state-persistence-fix",
-      "targetName": "form-state-persistence-fix",
-      "sourcePath": "...",
-      "mirrorPath": "...",
-      "sourceHash": "...",
-      "previousHash": "...",
-      "changed": true,
-      "status": "synced"
-    }
-  ]
-}
-```
-
-Reasonable status values:
-
-- `synced`
-- `unchanged`
-- `missing-source`
-- `skipped`
-- `error`
-
-Also print a concise human-readable CLI summary.
-
----
-
-## Error handling
-
-Fail clearly and non-zero for:
-
-- missing manifest file
-- invalid manifest JSON
-- invalid flags
-- requested skill not present in manifest
-- missing source `SKILL.md`
-
-For `--all-from-manifest`, if one skill fails, continue collecting results for others if reasonable, but exit non-zero if any error occurred.
-
----
-
-## Out of scope
-
-Do **not** implement in this task:
-
-- `skills-sanitize.ts`
-- `skills-export.ts`
-- writing anything into `skills/*`
-- package manifest changes beyond adding `skills:sync` scripts
-- `packages/skill-registry` loader changes
-- automatic approval
-- automatic public publishing
-
----
-
-## Expected files changed
-
-You should likely touch only these areas:
-
-- `package.json`
-- `scripts/skills-sync.ts`
-- `harness/skills-staging/.gitignore`
-- `harness/skills-staging/manifests/source-index.json`
-- `harness/skills-staging/manifests/approval-index.json`
-
-If you add a small helper file under `scripts/`, keep it minimal and explain why.
-
----
-
-## Implementation style
-
-- keep the first slice small and reviewable
-- prefer explicit code over framework-heavy abstractions
-- keep data shapes simple JSON
-- do not introduce dependencies
-- follow current repo script style
-- keep comments only where they clarify safety boundaries or flag behavior
-
----
-
-## Final response format
-
-When done, respond with:
-
-1. summary of files changed
-2. CLI usage examples
-3. safety guarantees confirming sync never writes to `skills/*`
-4. any open questions or follow-up suggestions
-
-Do not commit or push anything.