{"id":"221e5894-5c09-44a0-9221-946a751d88e7","slug":"prag-man-pragman-exp","kind":"skill","name":"pragman-exp","summary":"Privacy-first agent skills and local CLI for shaping, routing, researching, prototyping, and improving work across Codex, Claude Code, and Cursor.","owner":"prag-man","repoUrl":"https://github.com/prag-man/pragman-exp","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-10T07:18:33.000Z","addedAt":"2026-10-14T11:46:59.359Z","logoUrl":"https://avatars.githubusercontent.com/u/77991118?u=13c9c8362cc098426845e3467e02fba09230e3aa&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai-agents","claude-code","codex","cursor","developer-tools","workflow-automation","pragman"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T22:06:49.861Z","sample":false,"url":"https://conduits.dev/tools/prag-man-pragman-exp","language":"TypeScript","transports":["stdio"],"install":{"npm":"@prag-man/pragman-exp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Pragman Exp\n\n[![CI](https://github.com/prag-man/pragman-exp/actions/workflows/ci.yml/badge.svg)](https://github.com/prag-man/pragman-exp/actions/workflows/ci.yml)\n[![skills.sh](https://skills.sh/b/prag-man/pragman-exp)](https://skills.sh/prag-man/pragman-exp)\n\nPragman Exp is an **adaptive control panel for agentic work**. Its eight portable skills and optional local CLI help an agent decide what matters, use the right capability, keep context separated, and leave evidence behind. Simple work stays fast; ambiguous or risky work gets proportionate shaping, approvals, and verification.\n\nIt works with Codex, Claude Code, and Cursor, and can discover compatible providers such as gstack, Compound Engineering, and Superpowers without silently replacing, rewriting, or trusting them.\n\n## What it accelerates\n\nPragman is most useful when an agent can otherwise lose time to the wrong kind of work:\n\n- **Less ceremony:** the router skips interviews for obvious, bounded, low-risk requests.\n- **Less rework:** shape the outcome, non-goals, success evidence, and kill criteria before implementation.\n- **Faster decisions:** research only until the decision threshold is met, then turn evidence into an action.\n- **Safer context:** keep personal, company, client, and project context in explicit layers with privacy boundaries.\n- **Better learning:** analyze completed work and tune only approved, reversible workflow overlays.\n- **Visible risk:** preserve approval boundaries for writes, credentials, egress, paid actions, destructive changes, and deployments.\n\nThe skills are complementary, not a mandatory eight-step ceremony. Start with `pragman-router`, then add only the skills your workflow needs.\n\n## Install the skills from skills.sh\n\nReview the repository and its [skills.sh audit](https://skills.sh/prag-man/pragman-exp) before installing third-party instructions. Skills are project-local by default and remain useful without the CLI.\n\nList the catalog:\n\n```sh\nnpx skills add prag-man/pragman-exp --list\n```\n\nInstall the adaptive front door for Codex, Claude Code, and Cursor:\n\n```sh\nnpx skills add prag-man/pragman-exp \\\n  --skill pragman-router \\\n  --agent codex --agent claude-code --agent cursor \\\n  --copy --yes\n```\n\nInstall the complete set for one host:\n\n```sh\nnpx skills add prag-man/pragman-exp --skill '*' --agent codex --copy --yes\n```\n\nUse a skill once without keeping a project installation when your `skills` CLI supports `use`:\n\n```sh\nnpx skills use prag-man/pragman-exp --skill pragman-shape --agent codex\n```\n\nTo update an existing installation:\n\n```sh\nnpx skills update -y\n```\n\n## Install the optional CLI from npm\n\nThe CLI package name is scoped: **`@prag-man/pragman-exp`**. `pragman` is the installed binary name, not the npm package name. The current repository version is the beta channel, so install the beta tag explicitly:\n\n```sh\nnpm install --global @prag-man/pragman-exp@beta\npragman --version\npragman init\n```\n\nWhen a stable release is available, the normal command is:\n\n```sh\nnpm install --global @prag-man/pragman-exp\n```\n\nThe CLI requires Node.js 22 or 24. Check the registry before installing if you are testing a new release:\n\n```sh\nnpm view @prag-man/pragman-exp@beta version\n```\n\nIf that command returns `E404`, npm has not received the first public package yet; changing a local `package.json` cannot create a registry entry. The release owner must authenticate once and bootstrap the beta from a verified checkout:\n\n```sh\nnpm login\nnpm ci\nnpm run build\nnpm run validate:skills\nnpm run package:verify\nnpm publish --access public --tag beta\n```\n\nAfter that, `npm install --global @prag-man/pragman-exp@beta` resolves normally. Until the bootstrap is complete, use the skills directly or install the CLI from the public repository:\n\n```sh\nnpm install --global github:prag-man/pragman-exp\n```\n\nThe repository's `prepare` hook builds the GitHub installation. Never paste an npm token into a prompt, issue, config file, or commit.\n\nSkills have an honest manual fallback when the CLI is unavailable. Deterministic discovery, schema validation, routing, redaction, preview/apply, rollback, and event aggregation require a compatible CLI.\n\n## A fast operating loop\n\nUse the following loop instead of invoking every skill on every task:\n\n1. **Set up once:** install the CLI, run `pragman init`, and create or link the workspaces you actually use.\n2. **Route each non-trivial request:** let `pragman-router` choose Fast, Standard, Deep, or Operational work and identify the minimum capability contract.\n3. **Shape only when uncertainty is expensive:** use `pragman-shape` for vague, oversized, or premature requests; use `pragman-research` when current evidence changes the decision.\n4. **Make uncertainty tangible:** use `pragman-prototype` for a disposable clickable flow before committing to a product or UI direction.\n5. **Keep context clean:** use `pragman-workspace` for reusable company, client, venture, or project context rather than copying it into every prompt.\n6. **Close the loop:** use `pragman-analyze` after meaningful work; use `pragman-unfck` when repeated sessions are slow, chaotic, or unreliable.\n7. **Measure selectively:** record content-free events only when comparing outcomes matters; never trade privacy for telemetry.\n\nTypical combinations:\n\n| Situation | Start with | Then use | Result |\n| --- | --- | --- | --- |\n| A normal coding request | `pragman-router` | The selected capability | Direct work without a needless interview |\n| A vague feature idea | `pragman-shape` | `pragman-research` or `pragman-prototype` | A smallest valuable, testable bet |\n| A decision needing current facts | `pragman-research` | `pragman-shape` or `pragman-router` | Evidence tied to an explicit action |\n| Multiple clients or projects | `pragman-workspace` | `pragman-router` | Reusable context without cross-client leakage |\n| A risky change or deployment | `pragman-router` | The approved specialist | Explicit side effects and host-native approval |\n| Repeated agent friction | `pragman-unfck` | `pragman-analyze` | Reversible workflow improvements backed by evidence |\n\nThe prompts can be as simple as:\n\n```text\nUse $pragman-router for this request. Keep the fastest safe path and ask only questions that change the route.\n\nUse $pragman-shape to turn this idea into a smallest valuable bet with success and kill criteria.\n\nUse $pragman-research to gather the minimum current, primary evidence needed to choose between these options.\n```\n\n## The eight skills\n\n| Skill | Use it for |\n| --- | --- |\n| `pragman-init` | First-time onboarding, bounded host/skill discovery, health checks, repair, and a reviewable operating map. |\n| `pragman-workspace` | Personal, company, client, venture, and project context with explicit ownership, ordering, privacy, and links. |\n| `pragman-router` | The adaptive front door: choose the smallest trustworthy capability sequence and preserve approval boundaries. |\n| `pragman-research` | Source-first technical, market, decision, multi-source, and internal research with freshness and evidence quality. |\n| `pragman-shape` | Convert vague or oversized requests into an outcome, smallest bet, non-goals, success evidence, and kill criteria. |\n| `pragman-prototype` | Create safe, self-contained clickable HTML artifacts that let people decide before production implementation. |\n| `pragman-analyze` | Explain outcomes from observable evidence and produce Keep/Change/Stop/Automate/Learn/Test next actions. |\n| `pragman-unfck` | Analyze selected Codex, Claude Code, and Cursor sessions and propose evaluated, reversible workflow tuning. |\n\nEach skill has a focused trigger, a portable workflow, a CLI-unavailable fallback, compatibility notes, and sanitized evaluation scenarios. The detailed descriptions and instructions are indexed individually on [skills.sh](https://skills.sh/prag-man/pragman-exp).\n\n`pragman-router` is adaptive by default. It skips interviews for obvious bounded low-risk requests and increases rigor only when ambiguity, impact, side effects, privacy, cost, or reversibility justify it.\n\n## CLI commands\n\nEvery command supports concise human output. The stable command contract also supports `--json` and `--non-interactive`; mutating commands support preview-before-apply and stale-preview protection.\n\n```text\npragman init\npragman scan\npragman doctor\npragman tune\npragman route\n\npragman workspace add\npragman workspace edit\npragman workspace list\npragman workspace link\npragman workspace unlink\npragman workspace validate\n\npragman providers list\npragman providers inspect\npragman providers prefer\npragman providers trust\n\npragman sessions scan\npragman sessions analyze\npragman sessions purge\n\npragman changes list\npragman changes preview\npragman changes apply\npragman changes rollback\npragman history purge\n\npragman eval\n\npragman events record\npragman events score\npragman events list\npragman events summary\npragman events rebuild\npragman events export\npragman events purge\npragman events candidates list\npragman events candidates decide\n```\n\nRun `pragman <command> --help` for command-specific inputs. Configuration is layered personal → workspace → project, and one person can create and link multiple isolated workspaces.\n\n`pragman route` returns an immutable route with `execution_status: not-started`; provider selection is not reported as completed work. Host integrations execute that route through `createRouteExecution`/`executeReadyRoute` in `host-adapters/orchestrator`: the seam projects each ordered `provider_assignment` into a bounded adapter contract, applies stop/fallback/independent policies, propagates cancellation, and reports success only when verified provider results cover every routed capability.\n\n## Privacy, events, and learning\n\nPragman is local by default. It does not require a hosted account or daemon, store credentials, sync private context to a Pragman service, or silently edit third-party skills. Session sources are treated as untrusted input, selected explicitly, bounded, and redacted before analysis.\n\nThe CLI records content-free events for routed work and evaluation runs, and compatible host integrations can use the adapter lifecycle observer. Portable direct skill use is not automatically observable: record its lifecycle and outcome explicitly with `pragman events record` when measurement matters. Events contain identifiers, digests, lifecycle state, durations, route evidence, and approved outcome scores—not prompts, responses, session content, secrets, or workspace prose. Aggregates are the default export. Raw evidence has bounded retention and can be purged locally.\n\nEvaluations compare immutable skill and metric digests. Observations may become evaluation candidates, but Pragman changes configuration or a learning corpus only after a visible preview, evaluation, and user approval. It never self-modifies a public or third-party skill.\n\n## Development\n\n```sh\nnpm ci\nnpm test\nnpm run build\nnpm run validate:skills\nnpm run evals\nnpm run package:verify\nnpm pack --dry-run\n```\n\nRelease-only live evaluation is opt-in and offline-safe by default: `node scripts/test-live-hosts.mjs --check` performs prerequisite checks, while `--behavioral` requires authenticated hosts, an explicit environment opt-in, and a create-only content-free evidence path. See the [release checklist](docs/operations/release-checklist.md) for the Codex and Claude Code authentication gates, npm bootstrap, trusted publishing, and skills.sh verification steps.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). The project is licensed under the [MIT License](LICENSE).\n"}