OM Superpowers
SHGrowth/om-superpowers
Skill plugin para especificação, implementação e review em Open Mercato
Ver no GitHubPlugin Claude Code especializado para desenvolvedores Open Mercato com 11 skills cobrindo todo o ciclo de vida — de requisitos de negócio até code review. Utiliza personas (Cagan, Piotr, Krug, Vernon) para guiar ideação, especificação, implementação e revisão com perspectivas de PM, CTO, UX e domain modeling.
Instalação
npx convez-ai SHGrowth/om-superpowers1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Escrever especificações de apps B2B/B2C com validação de requisitos
- Decompor specs em módulos funcionais com gap analysis da plataforma
- Implementar features guiado por personas de arquitetura e UX
- Revisar código e testes de integração automatizados
- Estender modelos de dados via UMES e validar integridade do domínio
Veredito

Plugin robusto e opinado para o ecossistema OM, trazendo estrutura real de engenharia (personas, gap analysis, specs) ao fluxo de desenvolvimento com Claude Code. Excelente para equipes que já usam Open Mercato e buscam acelerar o ciclo ideação-código com validações de arquitetura.
README
A tradução para o português deste README ainda está na fila.
om-superpowers
Claude Code plugin for Open Mercato developers. 11 user-facing skills covering the full OM lifecycle — from business requirements through implementation to PR review. Specialist sub-tasks (module scaffolding, data-model design, system extension via UMES, integration builders, backend UI patterns, spec writing, user proxy, pre-impl analysis, toolkit audit) are demoted to references under their natural parent skills and load on demand.
Install
/plugins marketplace add SHGrowth/om-superpowers
/plugins install om-superpowers@om-superpowers
Prerequisites
- Claude Code (CLI or Desktop)
- GitHub CLI (
gh) — used byom-ctofor platform search
gh auth login # one-time setup
gh auth status # verify you're authenticated
Update
/plugins marketplace update om-superpowers
Getting Started
Ideation & spec writing (no app needed)
Create a project directory and start Claude Code:
mkdir my-project && cd my-project
mkdir app-spec
claude
The app-spec/ directory tells the plugin to activate. Then just describe what you want to build:
"I want to build a B2B portal for selling Apple devices to enterprises"
The plugin works through personas — real engineering thinkers whose decision-making style Claude already knows deeply:
| Persona | Role | Based on |
|---|---|---|
| Cagan | Product Manager — requirements, workflows, user stories | Marty Cagan, author of Inspired |
| Piotr | CTO — architecture, gap analysis, implementation | Piotr Karwatka, OM CTO (1,400+ contributions) |
| Krug | UX Reviewer — navigation, cognitive load, task flow | Steve Krug, author of Don't Make Me Think |
| Vernon | Domain Challenger — validates domain model integrity | Vaughn Vernon, author of Implementing DDD |
Each persona brings a distinct perspective. They challenge each other — Cagan defines what to build, Vernon challenges the domain model, Piotr maps it to the platform, Krug reviews the UI. The pipeline runs them in sequence:
- Cagan walks you through business requirements — who are the users, what are the workflows, what does success look like. Outputs an App Spec.
- Piotr decomposes the App Spec into functional specs — one per module or feature. You review and approve them.
- Piotr implements each spec one by one — writes code, runs tests, does code review — and checkpoints with you between each spec so you can test on localhost.
You can also invoke any skill directly, outside the pipeline:
- "does OM already handle inventory?" →
om-ctodoes a platform gap analysis - "extend the customer table with a VIP flag" →
om-implement-specloads its system-extension reference and guides the UMES approach - "this page is broken" →
om-troubleshooterdiagnoses the issue - "run integration tests" →
om-integration-testsexecutes the Playwright suite
Building an app
When you're ready to code, scaffold the OM app into the same directory:
npx create-mercato-app@develop .
yarn install
rm -rf .ai/skills/
Use the
@developtag to get the latest modules and templates. Therm -rf .ai/skills/removes frozen skill copies that the plugin replaces — this step will no longer be needed once open-mercato/open-mercato#1562 is merged.
Your app-spec/ stays in place. The pipeline continues where you left off — Piotr picks up the approved specs and starts implementing.
Codex CLI
Codex does not support Claude Code plugins natively. To use OM skills in Codex:
- Copy
skills/into your project's.agents/skills/ - Copy
om-reference/into your project root - Skills that use the
Skilltool will need manual invocation
How It Works
The plugin auto-detects OM projects on session start by checking for any of: @open-mercato/ in package.json, "Open Mercato" in AGENTS.md, .ai/ directory, or app-spec/ directory. When detected, all skills are injected into the session.
Two Workflows
Manual (skill-by-skill): Invoke any of the 11 top-level skills directly — om-troubleshooter, om-cto, om-implement-spec, etc.
Orchestrated (autonomous): Start with om-product-manager to define requirements, then om-cto takes over — writes specs, implements them, runs tests, does code review, and checkpoints with you between each spec.
Manual Orchestrated
(pick any skill) (autonomous pipeline)
┌─────────────────┐ ┌─────────────────────────┐
│ om-cto │ │ om-product-manager │
│ (gap analysis) │ │ (App Spec with Cagan) │
├─────────────────┤ └───────────┬─────────────┘
│ om-troubleshoot│ │
│ (fix errors) │ ▼
├─────────────────┤ ┌─────────────────────────┐
│ om-implement- │ │ om-cto │
│ spec (loads │ │ Spec Orchestrator: │
│ scaffold/UMES/ │ │ decompose → write specs│
│ data-model │ │ → cross-validate │
│ refs on demand)│ │ → execution plan │
├─────────────────┤ │ → you review │
│ ...any skill │ └───────────┬─────────────┘
└─────────────────┘ │ (per spec)
▼
┌─────────────────────────┐
│ om-cto │
│ Implementation Orch: │
│ implement → test → │
│ code review → you test │
│ on localhost → next │
└─────────────────────────┘
Skills
Spec & Design
| Skill | When to use |
|---|---|
om-product-manager | Defining business requirements — BEFORE any spec or code exists |
om-cto | Gap analysis, architecture decisions, orchestrating the full spec-to-build pipeline (loads references/spec-writing/ on demand), pre-impl BC/risk analysis, or auditing the skill corpus |
om-ux | UI architecture review — navigation, task completion, cognitive load |
Implementation
| Skill | When to use |
|---|---|
om-implement-spec | Multi-phase spec implementation with coordinated subagents. Loads on-demand references for module scaffolding, data-model design, system extension via UMES (incl. eject), and integration builders |
As of v1.11.6,
om-implement-specruns a mandatory post-PR review gate (Step 9) before reporting a spec implementation complete. After the run plan opens a PR, the implementer invokesom-auto-review-pr <PR#>in autofix mode (which itself chainsom-ds-guardian REVIEWfor UI work) and loops until clean verdict or only non-actionable findings remain. This closes the gap that caused PRM PR #4 + PR #5 to ship without code review or DS-Guardian passes — both required user-initiated cleanup loops surfaced only when the user asked "have we run tests, ui tests, design system review, code review?" Step 6 self-review is the implementer reading the checklist to itself; Step 9 is the real review. Rationale and forensic indocs/specs/2026-05-07-implement-spec-post-pr-gate.md.
As of v1.12.1, suspected Open Mercato core (
@open-mercato/*) bugs no longer get silent workarounds. Any om-superpowers agent that finds itself thinking "OM is broken, let me work around it" MUST route throughom-cto/references/upstream-bug-triage.mdbefore patching. om-cto verifies the bug, returns a verdict (not-a-bug/already-reported/confirmed-new-bug), classifies the proposed workaround size (minor: ≤50 LOC + single file + no abstraction leakage → apply+file upstream issue+file downstream removal-trigger task; major: anything else → wait-for-upstream + file blocker + stop+report to user), and drafts the upstream + downstream ticket bodies. The calling agent does the actualgh issue createfilings and applies the patch (or stops). Workaround code MUST contain a marker comment of the form// remove when @open-mercato/<pkg>#<N> ships;om-code-reviewflags missing markers + missing upstream issue + missing downstream task as Critical. The rule applies toom-troubleshooter,om-auto-create-pr,om-auto-continue-pr,om-code-review, and any agent loading theom-implement-spec/references/system-extension/reference. Reason: silent workaround accumulation hides real bugs from the OM core team, and major workarounds taken without user input become permanent because no one remembers they were temporary. Implemented as an on-demand reference insideom-ctoper the v1.12.0 surface-budget rule — no new top-level skill.
As of v1.15.0, the upstream-bug-triage flow closes its loop with a producer-consumer convention the model executes with native tools — no CLI wrapper. When triage's verdict is
confirmed-new-bugAND a fix in OM core is on the table, the calling consumer-app session does NOT author the upstream patch inline. Instead: (1)Read~/.config/om-superpowers/handoff.json'som_core_pathkey, asking the user once andWrite-ing the config if missing; (2) compose substance andWrite<om-core-checkout>/agents/tasks/YYYY-MM-DD-<slug>/README.mdwith the template inline inskills/om-cto/references/upstream-bug-triage.md(<om-core-checkout>placeholder kept literal in the README's example commands so the drain agent on a different machine doesn't see a stale absolute path); (3) stop the upstream-patch portion of the task and report the folder path to the user. A separate session running withcwdinside the OM checkout drains the queue per the newskills/om-cto/references/upstream-task-drain.md(claim bygit mvtoin-progress/, re-verify anchors → branch offorigin/main→ patch + tests → PR to your fork,git mvtodone/with siblingresolution.mdlinking the merged PR back to the originating downstream task). Abin/om-handoff+bin/om-task-listwrapper pair was drafted earlier in the day and deleted before commit after Musk-Step-1 review: five wrapper jobs all reduced to native primitives, the skeleton-then-Edit pattern inverted the friction goal (two round trips vs. oneWrite), and two BLOCKERs (heredoc leaking the producer-local path into the README; wrapper not on$PATHfrom consumer-app session) only existed because the wrapper existed — seedocs/specs/analysis/ANALYSIS-2026-05-10-upstream-handoff-baseline-v2.mdfor the reasoning. The PreToolUse cwd-jail lockdown-hook alternative was rejected separately. Empirical baseline (docs/specs/analysis/ANALYSIS-2026-05-10-upstream-handoff-baseline.md) mining 16 cross-project handoff writes since 2026-04-01 found a 67% binding rate without any rule — consumer-app sessions are willing to use the queue, the convention just makes the path explicit. Plan B (SessionEndgit-diff auditor scanning forpatches.diffwrites from non-OMcwd) deferred to 1.15.1 if Plan A measurement shows binding-rate <90%. The drain protocol is a sibling reference underom-cto, not a new top-level skill, per the surface-budget rule.
As of v1.16.0, the v1.12.0
om-orchestrateskill is removed. After 30 days of zero invocations and thefeedback_loop_self_pace_anti_patternfinding, the autonomous-fleet pattern was superseded by/loop 5m /auto-continue-pr <PR#>(harness cron mode, fixed interval, fresh context per turn). The original orchestration design spec (docs/specs/2026-05-07-github-tasks-orchestration.md) is preserved in repo history; theprompts/,references/, and dispatcher scripts underskills/om-orchestrate/are deleted. v1.12.0's bundled improvements to lean GitHub language acrossom-auto-create-pr,om-auto-continue-pr,om-auto-review-prsummary comment templates remain in effect.
Quality & Testing
| Skill | When to use |
|---|---|
om-code-review | CI/CD verification gate with full OM compliance checklist |
om-integration-tests | Creating or running Playwright integration tests |
om-troubleshooter | Diagnosing errors, 404s, missing modules, broken widgets |
om-ds-guardian | Design-system compliance + backend admin page builder. Loads on-demand references/backend-ui-design/ for CRUD/data-table/form patterns. Runs automatically inside auto-review-pr |
As of v1.13.0,
om-ds-guardiankeeps its references in sync with upstream OM via a manual sync script (node scripts/sync/ds.mjs). The script mirrors.ai/ds-rules.md+.ai/ui-components.mdintoom-reference/.ai/, source-extracts 11 specialized inputs (TagsInput, ComboboxInput, DatePicker, DateTimePicker, EventPatternInput, EventSelect, LookupSelect, PhoneNumberField, SwitchableMarkdownInput, TimeInput, TimePicker) intoreferences/specialized-inputs.md, and runs a discovery scan that surfaces new/removed/changed upstream files as action items insync-reports/YYYY-MM-DD.md. Pinned to a single upstream commit SHA per run, idempotent, dry-run via--dry-run, loud failures, smoke tests against mirrored content. Closes the TagsInput drift bug found while reviewing PRMcaseStudyForm.tsx— DS Guardian REVIEW silently accepted<Input value="comma,separated,slugs">because the skill's hand-curated references never mentionedTagsInputeven though it shipped in upstream@open-mercato/uilong ago and is used in 10+ core call-sites. Upstream issue tracking the canonical doc gap: open-mercato/open-mercato#1874. The new mirrors-docs relationship inUPSTREAM.mdgeneralizes the pattern — future shadowing references (now underom-implement-spec/references/{data-model-design,system-extension,module-scaffold,integration-builder}/andom-ds-guardian/references/backend-ui-design/after the v1.16.0 demotion) can adopt the same shape (manifest + discovery + extract + smoke test + report) when their upstream canonical docs land.
As of v1.14.0,
bin/claude-validatedships as opt-in tooling — a structural wrapper aroundclaude -p(headless mode) that runs 5 deterministic regex checks against output and rejects+retries on fabrication-shape violations:#1percentages without N/M fraction,#2English hedges (approximately/around/roughly/~[0-9]),#3persona invocations (Piotr/Caganas authority labels),#4Polish hedges (szacunkowo/około/mniej więcej/w przybliżeniu— locale-restrictive: forces English output regardless of input language),#5effort estimates without per-item enumeration. Drives toward exit 0 with grounded answer (within 2-retry budget) OR exit 1 with named FAIL on stderr — silent fabrication is no longer an option for "does platform X cover capability Y" prompts in headless mode. Driven by S008 → S010 → S011: 16 data points across 4 progressively-tightened text-channel gates (HARD-GATE prose,## Sourcesmandate, Phase 6 doubt-check, ROUTING CHECK) plus one deletion experiment (Replace Advisory with Research Plan), all empirically established that prose rules in skill bodies do not bindclaude -pfor fabrication-shape failures. Skill text is advisory; the wrapper's regex is normative. Opt-in:echo "<question>" | ~/Documents/om-superpowers/bin/claude-validated --model claude-opus-4-7, or symlink to PATH. Not in scope: interactive Claude Code, Claude Desktop, plainclaudewithout-p(post-emit by design — for interactive enforcement, Claude Code hooks would be needed; option (b) from S011, deferred). Bundled with:om-cto/SKILL.mdpersona-prune (drops# PiotrH1 + persona narrative +Red FlagsPiotr-says table; empirical chain probe 3 → S011 named these the load-bearing fabrication-shield surfaces). Cross-refs:agents-master/improvements/I018.md,sessions/S011.md.
Automation
| Skill | When to use |
|---|---|
om-auto-create-pr | Automatically create a pull request from current changes |
om-auto-review-pr | Automatically review an open pull request |
om-auto-continue-pr | Continue work on an existing pull request |
As of v1.10.0,
om-auto-create-prandom-auto-continue-prenforce a tests-with-code gate at commit time: any commit that stages source code (.ts/.tsx/.js/.jsx/.mjs/.cjsoutside__tests__/and not matching*.test.*/*.spec.*) without test files is blocked. The agent then either adds tests in the same commit or splits the staged set. Rationale and exemptions indocs/specs/2026-05-06-test-coverage-at-commit.md; baseline data that drove the scope indocs/specs/2026-05-06-ralph-loop-baseline.md.
As of v1.11.0, on session start the plugin auto-detects in-progress runs in
.ai/runs/, approved specs in.ai/specs/, orapp-spec/ideation state, and injects a specific actionable command into the agent's context. Vague prompts like "continue" or "finish this" route to the right skill instead of ad-hoc Bash. See hooks/session-start for the detection logic.
As of v1.11.2, the tests-with-code gate also fires on
om-auto-review-prautofix commits. Three entry points (create / continue / review-autofix), one gate, same shape.
As of v1.11.3, duplicate-work prevention runs in two layers. The SessionStart hook calls
gh pr listand surfaces any open PR whose body contains aTracking plan:line — so plans on other branches (invisible to the local.ai/runs/scan) become visible at session start.om-auto-create-prstep 0 then runs a keyword-overlap check (gh pr list --search "<spec/module> in:title,body") before claiming a slug; on match, the skill stops and asks the user viaAskUserQuestionwhether to resume the existing PR viaom-auto-continue-pr, proceed in parallel, or abort. Soft surfacing + hard enforcement, layered.
Autonomous Ralph-style runs
For unattended end-to-end execution against an in-progress PR, use Claude Code's harness /loop skill — no custom wrapper needed:
/loop 5m /auto-continue-pr 1796
Each iteration starts cold (clean context). The v1.11.0 SessionStart hook detects the in-progress plan and routes to om-auto-continue-pr, which runs the tests-with-code gate per atomic commit. The loop exits when you stop it or when the plan has no unchecked steps left and the PR flips to complete. Mirrors the Ralph pattern without shelling out to fresh claude -p processes — the harness handles iteration. For one-off scheduled runs, use /schedule instead.
As of v1.11.5, do NOT use
/loopself-paced (no interval) for chained autonomous coding. Self-pace mode wires the agent to callScheduleWakeup, whose tooltip default for "idle ticks" is 1200–1800 s (20–30 min). With an unchecked run-plan checklist there is nothing to wait for, so each "tick" inserts a multi-minute do-nothing gap between commits, and the agent will fabricate a cache-warmth rationale that contradicts the 5-min cache TTL. The two correct patterns are: (a)/loop 5m /auto-continue-pr <PR#>(cron mode, fixed interval, fresh context per turn) for unattended runs, or (b) a single long conversation that chains checklist items without sleeping. Triggered by patryk-standalone session forensic 2026-05-07 — seedocs/specs/2026-05-07-autonomous-loop-policy.md.
Demoted to references (loaded on demand by their parent)
These specialist tools are not user-invocable as top-level skills. The parent skill loads them when needed:
| Reference | Parent | When the parent loads it |
|---|---|---|
om-cto/references/gap-analysis-batch.md | om-cto | Multi-document engagement scoping — a folder of client docs → a persisted, gh-grounded Epic/Story backlog |
om-cto/references/spec-writing/ | om-cto | Writing or reviewing a SPEC against staff-engineer standards |
om-cto/references/user-proxy.md | om-cto | Resolving routine questions on the user's behalf before escalation |
om-cto/references/pre-impl-analysis.md | om-cto | Pre-implementation BC/risk audit at the spec→impl gate |
om-cto/references/toolkit-audit.md | om-cto | Auditing the skill corpus for context waste or trigger overlap |
om-implement-spec/references/module-scaffold/ | om-implement-spec | Bootstrapping a new module (entity, API, pages, ACL) |
om-implement-spec/references/data-model-design/ | om-implement-spec | Entity design, relationships, migration lifecycle |
om-implement-spec/references/system-extension/ | om-implement-spec | Extending core modules via UMES (enrichers, widgets, interceptors, guards) |
om-implement-spec/references/system-extension/eject.md | om-implement-spec | When UMES extensions are insufficient and ejection is required |
om-implement-spec/references/integration-builder/ | om-implement-spec | Building provider packages (payment, shipping, data sync) |
om-ds-guardian/references/backend-ui-design/ | om-ds-guardian | Backend admin/CRUD page patterns within the @open-mercato/ui library |
Architecture
Skills are lightweight — decision logic and workflows inline, reference material in references/ loaded on-demand. Rules from the OM platform's own AGENTS.md files are vendored in om-reference/ and referenced directly, never duplicated.
skills/
om-cto/
SKILL.md # Task router (~4 KB)
references/
advisory.md # Gap analysis workflow (on-demand)
spec-orchestrator.md # App Spec → functional specs (on-demand)
impl-orchestrator.md # Specs → implementation (on-demand)
...
om-implement-spec/
SKILL.md # Phases + Task Router for engineering specialty refs
references/
module-scaffold/ # New-module bootstrap (on-demand)
data-model-design/ # Entity + migration patterns (on-demand)
system-extension/ # UMES decision tree + eject playbook (on-demand)
integration-builder/ # Provider package scaffolding (on-demand)
...
om-reference/ # Vendored from open-mercato/open-mercato
AGENTS.md # Root platform conventions
packages/ # Per-package AGENTS.md files
Skill Syncing
Some skills are synced from the upstream open-mercato/open-mercato repo. A daily CI workflow checks for changes, bumps the patch version, and opens a PR for review.
To sync manually:
bash scripts/sync-om-skills.sh
git diff skills/
git add skills/ om-reference/ && git commit -m "chore: sync OM skills from upstream"
Custom vs Synced Skills
| Type | Skills | Maintained in |
|---|---|---|
| Custom | om-product-manager, om-cto, om-ux, om-ds-guardian, om-auto-create-pr, om-auto-continue-pr, om-auto-review-pr | This repo |
| Synced | om-implement-spec, om-code-review, om-integration-tests, om-troubleshooter | open-mercato/open-mercato (auto-sync via scripts/sync-om-skills.sh) |
| Frozen snapshot (v1.16.0) | spec-writing, module-scaffold, data-model-design, system-extension, integration-builder, backend-ui-design — all demoted to references under their parents | Originally upstream; manual cherry-pick required. See CHANGELOG 1.16.0 |
The auto-* trio forked from upstream across two releases to land the tests-with-code gate at every commit point: v1.10.0 added it to om-auto-create-pr step 6 and om-auto-continue-pr step 4; v1.11.2 added it to om-auto-review-pr's autofix loop after a session forensic showed autofix commits were bypassing the gate. See docs/specs/2026-05-06-test-coverage-at-commit.md for the spec.
Contributing
- Fork the repo
- Create a feature branch
- Make your changes — follow the existing skill structure (
SKILL.md+references/) - Open a pull request
For synced skills, contribute upstream to open-mercato/open-mercato instead.
License
MIT