prsm — Corrected Vision Brief (confrontation prompt)

gistfile0.txt

# prsm — Corrected Vision Brief

You previously reviewed the prsm design and flagged the multi-runtime compiler as obsolete because the "Agent Skills Open Standard" already handles cross-runtime skill content. That finding is partially correct but misses the actual problem prsm solves. This document corrects the record and presents the full vision.

---

## Where the prior review was wrong

The Agent Skills Open Standard solves skill *content format* — runtimes agree on SKILL.md frontmatter. It does NOT solve:

- Directory routing: Claude Code reads `.claude/skills/`, Codex reads `.agents/skills/`
- Hooks wiring: Claude Code requires `.claude/settings.json` with `SessionStart`, `PreToolUse`, `Stop` entries — no cross-runtime standard for this
- Permission allowlists: each runtime handles differently
- Agent definitions: `.claude/agents/*.md` with model/color/tools frontmatter — Codex has no equivalent
- Naming conventions and category prefixes (`hub-platform-copilot/SKILL.md`)

Platform-hub already has a `make skills.build` step that solves all of the above for one repo. prsm productizes that step into a first-class CLI that any team can adopt. The compiler is not obsolete — it's just not packaged yet.

**Corrected tagline:** Not "Write skills once, run anywhere" (content portability — partially solved). Instead: **"Wire your AI stack once, deploy to any runtime"** (config delivery + hooks orchestration — genuinely unsolved).

---

## The Primary Value Proposition

prsm is a **package manager for AI context repos** — skills, agents, hooks, permissions, and cross-repo topology — with a preset system as the organizational coordination layer.

Three use cases on one stack:

| Scope | How |
|-------|-----|
| Single team | `prsm init` + local skills + hooks → one repo owns the team's AI workflows |
| Department | `extends: my-org/prsm-preset-platform-engineering` → inherit all platform workflows, override only what differs |
| Company-wide | `extends: my-org/prsm-preset-base` → every team starts from the same AI foundation; company knowledge is versioned, lockfile-pinned, reproducible |

The preset/extends system (with last-layer-wins merge, `prsm eject` escape hatch) is the defensible moat. No current tool ships this.

---

## Feature: Repo Mapping + Multi-Repo Context

This is a new primitive not in the original design.

Platform-hub already solves multi-repo work via `config.yaml`: a file mapping repo names to local paths, used by cross-repo context hooks to inject relevant AGENTS.md/CLAUDE.md content when the AI session touches another repo. Developers mention `@gitops` or `@infrastructure` and the correct context loads automatically.

prsm makes this first-class:

```yaml
# prsm.yaml
repos:
  gitops:
    path: ../gitops
    default-branch: master
  infrastructure:
    path: ../infrastructure
    default-branch: main
  github-actions:
    path: ../github-actions
    default-branch: main
```

What this unlocks:
- `prsm context` generates a unified cross-repo context file the AI can reference in a single session
- Skills can declare `cross-repo: true` and gain awareness of the full repo topology
- A preset can bundle cross-repo context rules alongside skills — e.g. the platform-engineering preset ships with cross-repo dependency rules pre-wired
- `prsm sync` pushes skill changes to all mapped repos simultaneously (e.g. update `hub-platform-copilot` across 5 repos in one command)
- `prsm diff --cross-repo` shows drift between repos using the same preset

This is the feature that makes prsm the "AI hub for an entire company" — not just package management, but organizational AI topology as a versioned artifact.

---

## Repositioned Architecture Priority

| Doc | Status |
|-----|--------|
| Preset system (04) | Primary — this is the moat, move it to 02 |
| Dependency resolution (03) | Keep — lockfile model is the foundation |
| Compiler/adapters (02, 06) | Keep — re-frame as "config delivery engine" not "content compiler" |
| Registry (05) | Keep |
| Organizational scopes | NEW — team → dept → company preset chains |
| **Repo mapping** | **NEW — multi-repo context as first-class primitive** |

---

## What to validate now

1. Is the "wire your AI stack once" framing a genuine pain point at team scale? (answer: yes — platform-hub's entire CLAUDE.md complexity is the evidence)
2. Does the preset/extends system have any real competition? (craftdesk has packages, not preset inheritance)
3. Is cross-repo context wiring something other AI teams have solved? (no known tool does this)
4. What does the migration path look like for existing platform-hub users? (single `prsm init` should infer from existing `.claude/` structure)

Revisit implementation timeline only after these four points are addressed.