Pinmind is a Russian-and-English workflow controller packaged as a Grok skill and a Codex App plugin. It classifies non-trivial work, including colloquial and lightly misspelled Russian, applies a process proportional to risk, composes specialist skills, and requires current evidence before calling a task complete.
Current stable version: 0.11.0.
- GitHub repository marketplace: included in this repository.
- Universal Plugins Directory: not listed yet. ChatGPT catalog steps apply only after OpenAI approval and a live listing check.
-
Add the pinned stable repository marketplace:
codex plugin marketplace add iammedved/Pinmind --ref v0.11.0
-
Start Codex, run
/plugins, select Pinmind Project, and install Pinmind. -
Start a new Codex session.
-
Run
/skillsand confirm thatpinmindis available.
The repository marketplace is separate from OpenAI's universal Plugins Directory. Pinning v0.11.0 selects this exact stable release; omit --ref only when you intentionally want the reviewed latest repository state.
Pinmind 0.11.0 can deterministically select two maintained external design
skills. They are not bundled with Pinmind and must be installed separately.
For a fresh project, use this order:
-
Install UI/UX Pro Max:
npx skills add nextlevelbuilder/ui-ux-pro-max-skill
It supplies a searchable local corpus for product patterns, palettes, typography, UX and accessibility guidance, icons, animation presets, and stack-specific implementation recommendations. It answers focused design questions; it does not own the full interface lifecycle.
-
Install Impeccable:
npx impeccable skills install
Select the current project when prompted. Enabling its project hook is optional but recommended when you want automatic UI checks after edits. Impeccable owns end-to-end interface work: product context, shaping, redesign, critique, audit, refinement, responsive adaptation, motion, implementation discipline, and final visual verification.
-
Install the reviewed Pinmind release:
codex plugin marketplace add iammedved/Pinmind --ref v0.11.0
Open
/plugins, install Pinmind from Pinmind Project, and start a new Codex session. -
Run
/skillsand confirm thatpinmind,impeccable, andui-ux-pro-maxare available.
The historical frontend-skill is deprecated upstream and is not part of
Pinmind 0.11.0 design routing. Do not install it for this workflow.
Replace <reviewed-tag-or-commit> with an immutable release tag or commit that
you have reviewed, then refresh only the Pinmind marketplace and plugin:
codex plugin remove pinmind@pinmind-project
codex plugin marketplace remove pinmind-project
codex plugin marketplace add iammedved/Pinmind --ref <reviewed-tag-or-commit>
codex plugin add pinmind@pinmind-projectStart a new Codex session and use /skills to confirm that pinmind is
available. The repository-local installer helper is retained only as a legacy
recovery path; it is not the supported public upgrade path.
- Copy
https://github.com/iammedved/Pinmind. - Start Codex CLI and invoke
$skill-installer. - Ask:
Install the Pinmind skill from https://github.com/iammedved/Pinmind, path skills/pinmind. - If Pinmind does not appear immediately, restart Codex.
- Run
/skillsand confirm thatpinmindis available.
Pinmind needs no connector, external account, API key, or MCP server. The bundled local hook only classifies the submitted prompt and adds routing context; it performs no task action itself.
Copy the skill into the user-scope Grok directory, or install the repository as a trusted plugin:
mkdir -p ~/.grok/skills
cp -a skills/pinmind ~/.grok/skills/pinmind
# or, from this repository:
grok plugin install . --trustStart a new Grok session. Pinmind should appear in /skills. The host still chooses implicit activation; $pinmind or @Pinmind is the reliable trigger for critical work.
Send:
$pinmind Audit this repository without changing files. Determine the route first and report only verified findings.
When routing is requested for diagnostics or explains a material boundary, the response may include:
Route: audit |
Pinmind is not currently available in the public Plugins Directory. After the listing is approved and verified:
- Open Plugins in ChatGPT.
- Search for Pinmind and open its details.
- Select the plus button to install it.
- Start a new chat.
- Send:
@Pinmind Audit this repository without changing files. Determine the route first and report only verified findings.
No connector, external account, API key, or additional configuration is required for the current local skill-and-hook package.
Official OpenAI guidance: install and use plugins, package plugins and repository marketplaces, and build or install skills.
- After Pinmind is installed in a supported host, ChatGPT or Codex selects it implicitly, or you invoke it with
@Pinmindor$pinmind. - The bundled kernel chooses
simple,operational,spike,audit,investigation, orsoftware-change. - Pinmind applies only the workflow needed for that route and keeps authority boundaries explicit.
- Mixed requests may expose bounded diagnostic clauses while retaining one primary route.
- Substantive changes use a frozen outcome contract and traceable evidence.
- An optional pure Goal adapter distinguishes standalone, active, paused, complete, blocked, and mismatched host context without making Goal a dependency or authority source.
- Final reporting separates passed, failed, uncertain, pending, and manual results.
Implicit selection is probabilistic. Explicit invocation is the reliable choice for critical work.
Earlier Pinmind releases could compose specialist skills only through general
instructions. That left the choice between overlapping design skills to the
host or the current prompt. Version 0.11.0 includes a deterministic post-route
decision:
- Impeccable only for an explicit Impeccable command or an end-to-end interface workflow.
- UI/UX Pro Max only for a focused lookup such as a palette, font pairing, UX rule, accessibility outcome, icon, chart, animation preset, or stack-specific recommendation.
- Impeccable + UI/UX Pro Max for substantive page or component work that also needs researched design guidance. Impeccable remains primary; UI/UX Pro Max supplies bounded supporting evidence.
- Neither for backend-only, database, infrastructure, or non-visual work.
Pinmind makes this choice with design route after its main process route.
The specialist result never grants permission to edit, publish, deploy, use
network services, or change Figma. Those boundaries still come from the user.
0.11.0 is a minor release because Pinmind now owns automatic orchestration.
It decides whether a task needs passive Skillstate checkpoints while keeping
Ponytail limited to code simplification.
Pinmind 0.10.0 added journaled abandon, non-destructive archive, proportional debugging/TDD/architecture/review guidance, and a compact readability profile. Superpowers and dyslex.ai remain research inputs: they are not installed, imported, or made runtime dependencies.
AEP and P2 are not runtime. SKILL.md and the kernel do not load them. They stay in the repository as an offline evaluation contract and a design decision.
0.3.0-experimental introduced AEP Phase 0: a provider-neutral decision contract, 16 original synthetic contrast cases, a held-out release split, and a deterministic validator.
0.4.0-experimental added the P0/P1 routing, recovery, baseline, freshness, and final-check guarantees. 0.4.1-experimental corrected a fresh-CLI read-only regression. 0.4.2-experimental distinguishes planning from execution, recognizes bounded Russian no-change gerunds, rejects unknown or repeated CLI flags, and reduces roadmap duplication. The adapter-first P2 architecture decision remains design-only; P2 host adapters are gated, unimplemented, and off by default.
0.5.0-experimental adds a closed-schema, dependency-free language evaluator with 32 development and 32 frozen release-gate cases. It reports route, authority, mutation boundary, pair, risk, and language-slice results without changing runtime routing. The fixed corpus is regression evidence, not a statistically independent benchmark or a claim of universal language understanding or host activation.
0.6.0 is the first stable public release line. It carries forward the reviewed
experimental baseline, fixes the P0 routing contrasts, adds the required GitHub
CI and frozen-input gate, exposes remaining boundaries in generated reports, and
publishes Codex logo metadata that points to the same tracked image as this
README. Stable refers to the release contract and versioning discipline; it does
not claim universal implicit activation, ChatGPT directory availability, an
independently administered corpus, or authoritative token measurement.
0.10.0 adds a separate offline A/B/C record validator for the same sanitized tasks across released Pinmind, a fixed Superpowers+dyslex.ai protocol descriptor, and hybrid Pinmind. Its public sample is deliberately pending-review: schema validity is not presented as measured product superiority, and token totals remain unavailable unless a host adapter verifies authoritative receipts.
Phase 0 does not select a concrete model, change route, start an agent, authorize an action, or store prompts and traces. It only defines how a future host adapter could choose a work shape, capability profile, escalation reason, and verification oracle. Mapping profiles to current models and reasoning levels remains a later opt-in step that requires held-out evaluation and separate authorization.
Run kernel commands from the target workspace with the repository-relative entry point:
node skills/pinmind/scripts/pinmind.mjs route --file request.json
node skills/pinmind/scripts/pinmind.mjs route --decompose --file request.json
node skills/pinmind/scripts/pinmind.mjs design route --file request.json
printf '%s' '{"text":"Audit this repository and report only."}' | node skills/pinmind/scripts/pinmind.mjs route --file -
node skills/pinmind/scripts/pinmind.mjs init --run <run-id> --brief brief.md
node skills/pinmind/scripts/pinmind.mjs state reconcile --dry-run
node skills/pinmind/scripts/pinmind.mjs state recover --apply --expected-sha256 <transition-sha256> [--expected-lock-sha256 <dead-local-lock-sha256>]
node skills/pinmind/scripts/pinmind.mjs baseline capture --run <run-id> --file baseline.json -- <command> [args...]
node skills/pinmind/scripts/pinmind.mjs contract freeze --run <run-id> --file contract.json
node skills/pinmind/scripts/pinmind.mjs evidence capture --run <run-id> --file evidence.json -- <command> [args...]
node skills/pinmind/scripts/pinmind.mjs final check --run <run-id>
node skills/pinmind/scripts/pinmind.mjs finalize --run <run-id>
node skills/pinmind/scripts/pinmind.mjs abandon --run <run-id> --reason "<reason>"
node skills/pinmind/scripts/pinmind.mjs archive --run <run-id> --reason "<reason>"
node skills/pinmind/scripts/pinmind.mjs report --run <run-id> --format mdroute --file - reads the same JSON object from standard input and is the
write-free bootstrap for a read-only host. Stdin must finish within 5 seconds
and is limited to 1 MiB. Keep --text for short,
non-sensitive manual checks because its value is visible in process arguments.
Do not combine --file with --text or --kind; put an optional kind in the
JSON object instead.
New runs require an explicit baseline receipt before contract freeze. final check is the pure read-only gate; finalize is the preferred explicit completion command. The legacy final verify spelling remains a deprecated finalizing alias so existing automation does not silently change behavior.
abandon terminates the canonical active run without claiming completion and clears its pointer. archive accepts only a completed or abandoned run, writes archive.json, and preserves the run directory and evidence in place. Both require an explicit sanitized reason and use the same lock, journal, and hash-bound recovery path as existing lifecycle mutations.
See kernel-cli.md for schemas and safety behavior.
- CHANGELOG.md — stable and experimental release history.
- ADAPTIVE_EXECUTION_POLICY.md — offline AEP Phase 0 evaluation contract; not runtime.
- P2 architecture decision — adapter-first design that keeps host adapters out of the kernel.
- ROADMAP.md — evidence-backed future priorities.
- LANGUAGE_ROUTING.md — implemented multilingual routing evaluator and remaining host-evaluation boundary.
- Goal context — optional host adapter contract and ownership matrix.
- Offline A/B/C evaluation — comparable-run and token-receipt rules.
- Readability profile — typo, literal, re-entry, and comparison safeguards.
- SKILL.md — controller instructions and discovery rules.
- Safety reference — secrets, workspace, and side-effect boundaries.
- SECURITY.md — private vulnerability reporting.
- PRIVACY.md — data-handling scope.
- SUPPORT.md — safe support requests.
- CONTRIBUTING.md — manually reviewed proposals.
Runtime state is written to the target workspace's ignored .pinmind/ directory. It must not be committed or packaged. Pinmind rejects symlinks in this state path and sanitizes credential-shaped text before persistence.
Pinmind follows Semantic Versioning 2.0.0:
MAJORfor incompatible public-contract changes.MINORfor backward-compatible capabilities.PATCHfor backward-compatible fixes and documentation corrections.
Release tags and plugin manifests use the same MAJOR.MINOR.PATCH version.
Changed packages always receive a new patch or minor version; Pinmind does not
publish or display Codex cachebuster build metadata.
The stable public line starts at 0.6.0. Backward-compatible fixes use patch
versions such as 0.6.1, 0.6.2, 0.6.3, 0.8.1, 0.8.2, 0.9.1, and 0.10.1; backward-compatible feature releases use a
new minor such as 0.7.0, 0.8.0, 0.9.0, 0.10.0, or 0.11.0. Existing experimental tags are immutable history and
are never moved to newer commits.
The supported local release gate uses the exact Node version in
.node-version, validates the frozen-input manifest, and then
runs the same fixed command list as CI:
node scripts/verify-release.mjs --runThe manifest records SHA-256 digests for the router, optional Goal/decomposition seams, A/B/C validator/profile/schema/sample, language validator, GitHub web-flow signing key, development corpus, held-out release corpus, and mandatory unsafe-negative route regressions. The identity gate permits provider-authored merge metadata only after local signature verification against that frozen key. A digest change therefore requires an intentional manifest update in review. Because the manifest and inputs remain in the same repository, this is a review-visible tamper-evidence boundary, not a cryptographically independent benchmark.
For an auditable inventory, Pinmind counts top-level test( declarations rather
than quoting Node's runtime summary. The current manifest records 127 declarations
across eleven test files, plus fixture-case counts for routes, activation, AEP,
parallel admission, and language evaluation. These are separate dimensions and
are not presented as one inflated "test count."
The expanded commands executed by the gate are:
node --test tests/kernel.test.mjs
node --test tests/terminal-lifecycle.test.mjs
node --test tests/goal-context.test.mjs
node --test tests/decomposition.test.mjs
node --test tests/route-phase-regression.test.mjs
node scripts/evaluate-abc.mjs
node --test tests/abc-evaluator.test.mjs
node scripts/validate-aep-decision-contract.mjs
node --test tests/aep-decision-contract.test.mjs
node scripts/validate-parallel-admission.mjs
node --test tests/parallel-admission.test.mjs
node scripts/evaluate-language-routing.mjs
node --test tests/language-routing-evaluator.test.mjs
node --test tests/release-verification.test.mjs
node scripts/validate-plugin-skill.mjs
node --check skills/pinmind/scripts/lib/core.mjs
node --check skills/pinmind/scripts/lib/route.mjs
node --check skills/pinmind/scripts/lib/persist.mjs
node --check skills/pinmind/scripts/lib/contract.mjs
node --check skills/pinmind/scripts/lib/evidence.mjs
node --check skills/pinmind/scripts/lib/state.mjs
node --check skills/pinmind/scripts/lib/decomposition.mjs
node --check skills/pinmind/scripts/lib/goal-context.mjs
node --check skills/pinmind/scripts/pinmind.mjs
node scripts/check-release-identity.mjs
node scripts/check-repository-diff.mjsThe repository workflow runs this gate for pull requests and pushes to main
with read-only contents permission and immutable action revisions. A local pass
does not prove the GitHub-hosted check passed; that evidence exists only after the
workflow runs on GitHub.
- Pinmind cannot control whether a host selects it implicitly.
- The deterministic router runs only after Pinmind is selected.
- The design specialists are external installations. Pinmind reports a route;
it cannot make a missing
impeccableorui-ux-pro-maxskill available. - Passing the fixed language corpus does not prove arbitrary-language accuracy or host selection.
- AEP Phase 0 is an evaluation contract, not a runtime model or agent router.
- Goal context is an optional pure adapter; Pinmind does not create, resume, complete, or mutate a host Goal.
- The public A/B/C sample is pending review; comparable host runs and authoritative token receipts are not bundled.
- Filesystem locking is cooperative and single-host, not a distributed lock.
- Evidence containment protects workflow integrity; it is not a sandbox against a hostile writer.
- Pinmind includes no dashboard, daemon, connector, MCP server, or external telemetry service.