pi-harness-runtime 1.1.166 → 1.1.167

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

@@ -0,0 +1,278 @@
+# 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: `/home/frappe/frappe-bench/.claude-plugins/moocoding-skills/skills/*`
+
+### Current runtime state
+
+- `pi-harness-runtime` already exposes bundled skills via:
+  - `package.json` -> `pi.skills = ["./skills"]`
+- Current bundled repo skill set is minimal:
+  - `skills/harness-runtime/SKILL.md`
+- `packages/skill-registry` is currently an in-memory registry, not a filesystem `SKILL.md` loader.
+
+---
+
+## Critical Constraints
+
+### 1. Live MooCoding skills must remain the evolving knowledge base
+
+The directory:
+
+`/home/frappe/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:
+
+- `/home/frappe/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

@@ -0,0 +1,345 @@
+# 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:
+
+- `/home/frappe/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:
+
+- `/home/frappe/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": "/home/frappe/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.