mirror of
https://github.com/open-mercato/skills.git
synced 2026-09-19 08:13:32 +08:00
zielivia
7c81ffe68d
* feat(sdlc): Definition of Ready gate, Discovery row, and the document's own scope The generated SDLC.md started at a ticket with "enough detail to act on", which nothing checked. It now carries a Discovery row driven by om-brainstorm (#59), a before-intake paragraph naming the spec skills, an after-merge paragraph saying where the collection stops, and a two-tier Definition of Ready: ticket-level items only a human can supply, spec-level items a covering spec provides. om-auto-manage-issues records READY_STATUS and posts one idempotent not-ready comment naming the missing items. om-auto-fix-issue's feature route stops with NOT_READY on a ticket that fails the ticket-level tier instead of speccing around the gap; a spec-level gap still authors the spec. om-prepare-issue files tickets with the matching sections. Upgrade note and decision entry included. * feat(om-discover): product-level discovery and define, with a product-brief.md the other skills read New interactive skill with three modes (existing product, client idea, own idea). It runs a context gate over the research directory before writing anything: a brief section with no interviews, data, or documents behind it becomes a collection plan with capture templates, never prose. Interview rounds ask the whole frontier at once with a recommended answer and the evidence tier it would carry; a skeptic subagent and a quality gate catch invented personas, unsourced numbers, and benchmarks without a link and date. The brief tags every claim (interview, data, document, product, benchmark, synthetic, assumption), carries a coverage line, and gives business rules, non-goals, and decisions stable ids with an owner, a status, and a required path to change them. om-brainstorm, om-spec-writing, and om-prepare-issue read the brief when it exists. Roster, README, docs card, PM role, upgrade note, and decision entry included. * feat(om-synthetic-users): personas, simulated interviews, and persona walkthroughs tagged synthetic New interactive skill. Builds personas from the material the repository already holds (product-brief.md, a spec, interview notes, data), with stable ids and every line tagged with its source and no demographics. Runs simulated interviews that ask about the past, never the future, and walks a named flow through the personas' eyes: on the brief or spec as a narrative, on a static prototype through the browser provider, or on the running app booted through om-prepare-test-env. Three stances default from the brief's mode: validate on a real product, simulate with every answer marked to confirm, adversary where agreement is discarded. Every finding is [SYNTHETIC], paired with the real-user check that would settle it, and never satisfies the Definition of Ready. om-ux-review-pr walks as the personas when personas.md exists, om-spec-writing reads walkthrough reports as hypotheses, om-discover --refresh pulls them into the brief. Roster, README, docs card, role docs, upgrade note, and decision entry included. * feat(review): product-brief non-goals, rules, and decisions as a protected contract When om-discover has written product-brief.md, its Non-goals, Business rules, and Decisions (stable ids, owner, status, review-by date, required path to change) are enforced the way BACKWARD_COMPATIBILITY.md surfaces are. om-code-review gains a product-decision gate: a change that contradicts an active entry without a superseding row in the same diff is a blocker quoting the id; a touched entry past its review-by date is a minor finding. om-ux-review-pr applies the same to screens. The decisions in play are surfaced where people work: om-auto-manage-issues ends its implementation notes with them, om-spec-writing carries a Decisions in play section and may not default against them, and the unified PR body template (three synced copies) gains Decisions touched. om-discover --refresh records human-confirmed assumptions from spec PRs as decisions. SDLC.md and its template describe the contract; upgrade note and decision entry included. * feat(om-ux-style): a declared design contract from scratch, in the files the UX skills already read New interactive skill for repositories with no design system yet. Gathers a moodboard from references the team chooses (never invented), derives five confirmed principles and five anti-patterns, defines tokens by role for both themes with contrast checked, and lists the components the product's flows need with all six states plus three recipes. Writes declared tokens into .uxproof/tokens.json (two additive fields), the rules into the manual section of conventions.md, a minimal contract.json when none exists, and a theme.css with the eight identity tokens a prototype directory expects. Stops and routes to om-ux-setup when a design system already exists; om-ux-setup names it back when only a proposed palette is available. The generic look's signatures are an explicit anti-pattern list in the quality gate. Roster, README, docs card, designer role, upgrade note, and decision entry included. * feat(om-backlog): epics, stories with acceptance criteria, and tasks from a brief or a spec New interactive skill. Drafts a tree from product-brief.md (Scope, Key flows, Goals, Business rules, Non-goals) or a spec's Phasing: epics for the Now items or Phases, stories as user-facing outcomes with Given/When/Then criteria and the decision ids they rely on, tasks only where a story needs decomposition. Ids open every title, stories carry an Epic line, epics a rewritten checklist; no tracker feature beyond issues, bodies, comments, and labels is assumed. Every issue is created through om-prepare-issue, so dedupe, SDLC labels, and the rationale comment are unchanged; existing issues are adopted, never duplicated. A brief whose problems rest on synthetic or assumed claims is refused and the research backlog offered instead. The tree is shown and confirmed before any write. Roster, README, docs card, PM role, upgrade note, and decision entry included. * feat(qa-gate): pin qa-approved to the tested head with a QA head line The comment that grants qa-approved now carries QA head: <sha> — the commit that was tested. om-auto-qa-pr writes it on --self-qa-signoff; the SDLC.md template asks QA reviewers for the same line. om-approve-merge-pr reads it back and, when the PR head moved past it, lists the commits pushed since and asks for confirmation in the same idiom as its changes-requested confirm. om-merge-buddy reports a stale sign-off as "QA evidence older than head" and classifies the PR as almost ready at best. A sign-off without the line is treated as pre-dating the rule. No new label, no new state. * feat(qa-gate): self-QA only below risk-high, and one statement across documents SDLC.md said automation never applies qa-approved, DECISIONS.md said never a self-granted qa-approved, and om-auto-qa-pr --self-qa-signoff applied it. The documents now say the one thing the skill does: the self-QA exception is available to an engineer or to om-auto-qa-pr on risk-low and risk-medium PRs only, with an evidence list (scenario, environment, test data, result, negative cases, QA head). On a risk-high PR — labeled, or inferred from a diff touching auth, sessions, data scoping, money, migrations, or shared contracts — the skill posts the evidence and withholds the sign-off; a QA reviewer or a maintainer's stated exception is required, and auth or money changes need a second person's review regardless. om-approve-merge-pr's gate explanation matches. * feat(qa-gate): state matrix and contract conformance are part of QA pass/fail For a UI surface, om-auto-qa-pr's scenario now carries one required step per state the change can show — default, empty, loading, error, no-permission, long content, narrow viewport — and, when .uxproof/ exists, one step for contract conformance on the changed screens (hardcoded colors where tokens exist, raw elements where the registry has a component, a screen ignoring its archetype). A missing or broken state is a FAIL step, not a note. om-ux-review-pr stays the advisory design review; SDLC.md says which checks QA owns. * feat(review): risk-high requires integration evidence for its area om-code-review gains a risk-high evidence gate next to its test-coverage step: a PR labeled risk-high, or whose diff touches an area SDLC.md infers as risk-high (auth and sessions, data scoping, money, schema migrations, shared contracts), is a blocker without integration-level evidence for that area — the denied path and wrong-scope read, the failure/retry/idempotency paths, migration up and down, the consuming side of a contract — unless a maintainer waives it on the PR. The SDLC.md template replaces "strengthens the case for deeper review" with an area-to-evidence table, and om-auto-review-pr's label rules say the rating is not advisory. Upgrade note and decision entry for the four QA-gate changes included. * feat(ux-review): the accepted prototype is an acceptance artifact A spec's UI/UX section may carry a Prototype: line naming the accepted mockups or an interactive prototype directory. om-ux-review-pr reads the PR's Source doc spec, opens the linked prototype through the browser provider beside the running screens, and reports a deviation the spec does not explain as a [PRODUCT] finding with evidence of both; a deliberate improvement is a deviation for the author to confirm, never silently accepted or rejected. The review comment gains a Prototype line. Design-file review stays out of the collection, recorded under Deferred. The producer side of the marker lands with the prototype skill (#104). * docs: the collection now ships forty skills * feat(om-synthetic-users): panels, fresh runs, pressure, and a parity check The skill now runs the way the research on synthetic respondents says it must to mean anything. A panel (--panel, default 5) is resampled every run (--runs, default 2) from the segments the data names, includes a persona who barely cares, and runs one persona per fresh-context subagent; a panel that answers alike is resampled. Only what survived every run is a finding, with its weight and spread; ties are marked; single-run items sit under Seen once; saturation is reported. Interviews ask about the last time and never a stated preference; the decision is then simulated under the brief's pressures and the record shows where the story collapses. Each answer carries the fast reaction with its feeling, then the considered one, and records the research passages that grounded it. --open runs exploratory interviews that track topics. When real interview notes exist, the same script runs on the panel and the deviation is reported as blind spots and questions, logged in calibration.md as a trend. references/research-basis.md lists the sources, what was adopted, and what was left out (survey prediction, eye-tracking, personality inventories, model routing). No numbers from personas; the synthetic label stands. * feat(om-synthetic-users): measure acquiescence, keep assumptions out of the persona Two rules from the silicon-crowd study (Science Advances 2024) and the forecasting literature that followed it. Language models say yes more than the world does, so the quality gate now counts the panel's yes share on yes/no questions and excludes unsupported agreement from the findings. A model handed the hoped-for answer uses it worse than averaging afterwards would, so the brief's assumptions and expected answers shape the questions and the pressures but never enter a persona's context. research-basis.md cites the peer-reviewed version and adds ForecastBench (ICLR 2025), the prompt-engineering and evaluation-pitfalls papers, and AI-augmented predictions, each with what was adopted. * fix(pre-intake): defects found by integration runs of om-discover, om-ux-style, and om-backlog Each new skill was executed as written against a scratch repository with real research material; the runs produced the intended artifacts and a list of instruction defects. This commit closes the ones that would have changed behavior in a real repository. om-discover: an explicit --mode is never second-guessed and the team's own workshop no longer detects the client mode; decisions the user makes in the session become decision records the brief can cite as documents; an unowned decision is a proposal with a blocking question, in one rule instead of three; the own-mode sections (kill criteria, the assumption map's importance and evidence columns) exist in the template; the quality gate runs before the skeptic sees the draft; one shape for the Coverage line with a benchmark bucket and a counting rule; workshop exports tagged by what was said versus what was decided; a benchmark capture template; round format without glossary-foreign emoji; Next: none is the right line when material must be collected first. om-ux-style: role names unified with tokens.md; a code scan detects a design system without a contract; the quality gate runs before writing; Next: none in a repository without components; proposed values marked and confirmed; no-image and unopened-link cases recorded honestly; the .dark block's scope stated in the header; kind values and counts defined; contract-format.md in om-ux-setup documents the design and proposed sentinels and the theme field. om-backlog and om-prepare-issue: the readiness stop applies the whole ticket-level tier, not only assumption-tagged problems; om-prepare-issue gains --title, --no-spec, and --skip-dedupe so tree ids open titles, no spec PR is opened per story, and dedupe runs once; body sections handed over are embedded verbatim; a greenfield exception to the real-paths rule; dry runs never trigger setup and end with Next: om-backlog <source>; the research variant files tasks, not stories; story-level labels in the tree; decisions may produce criteria; "sessions" in the risk inference means login sessions. * fix(om-synthetic-users): hold-out parity, bounded transcripts, smaller default panel The integration run showed two things the report could not have said better. The parity check scored the panel against the same interview note that had built four of the six personas, and correctly called its own 9 of 9 overlap leaked; the skill now splits real notes into persona material and held-out notes (--hold-out, or the newest note per flow), scores only the held-out ones, and skips the check with the reason stated when nothing can be held out. Two personas built from one note are one voice twice, so the second is an assumption persona. And an unbounded run of five-persona panels took over half an hour on a narrative subject: the default panel is three, transcripts are budgeted to the script, the report records elapsed time per phase, and --runs 1 is allowed as an exploration that yields only seen-once items. * fix(om-synthetic-users): defects from the integration run's full report The subagent hand-off is now specified: a general-purpose subagent with no tools, given the persona block with evidence tags stripped, a subject excerpt that excludes the brief's assumptions, goals, hypotheses, and open questions, and the script with passages attached per question and marked as background, not memory; retelling a passage as one's own or relaying what "people like me" report is flagged and carries no finding. One confirmation stop before any subagent runs (composition, flow mapping, stance). A flow name that matches no heading is mapped and confirmed; report and transcript names use a kebab-case slug. Four balanced past-behaviour yes/no questions make the acquiescence measure operational. Saturation is measured over the last three interviews or twenty topics; ties use the larger spread; the discard rule is per interview, a whole run only when every persona agreed. Assumptions the panel's segment cannot answer are listed as not askable. Unquantified pressures are applied as unstated, never invented. The indifferent seat's salience may be an assumption and says so; passage-quoted quantities are allowed, invented ones dropped. Header and contract line shapes no longer collide. * feat(om-discover): --quick pass and bounded rounds A full run asked as many questions as the frontier held (eleven in the integration run), dispatched a skeptic subagent that re-read the whole research directory, and wrote every template up front. Rounds are now at most eight questions, two rounds the norm and three the ceiling; the skeptic subagent gets the draft and the source list, not the directory; templates are written only for entries the collection plan names. --quick runs one round, the skeptic as an inline checklist, the critical gate items only, and writes the ticket-level sections with the rest on the collection plan, for first passes, lessons, and tests. Reports carry Elapsed per step. * fix(om-discover): align coverage shape, step numbers, and pre-confirmation writes across references * fix(om-discover, om-backlog): one coverage shape in the header, assumption result vocabulary, dry-run never runs setup, criteria shown in full before filing * feat(om-discover): hand off to the next step after the brief; housekeeping out of the round * fix(om-discover): the mode is confirmed before the gate, never as a round question * feat(om-discover): one voice for the interviewer and the skeptic; questions in plain words with an example answer * fix: preserve pre-intake identities and handoff contracts * fix(om-discover): ask neutral questions and qualify recommendations * feat(om-discovery-setup): the product layer is opt-in, added by its own setup The Discovery stage, the Definition of Ready, the product roles, and the protected product decisions move behind `IF discovery` in the SDLC template and are written into an existing SDLC.md by the new om-discovery-setup skill, between discovery:start/end markers, so a re-run is idempotent and a template change is a --refresh. om-setup-agent-pipeline never asks about the layer; a fresh setup renders the delivery-only document with om-brainstorm as the pre-ticket step. The intake skills no longer fall back to a built-in Definition of Ready: om-auto-manage-issues records READY_STATUS n/a, om-auto-fix-issue's feature route skips the gate, and om-backlog skips the readiness check and says so, whenever SDLC.md has no such section. The product skills keep running without the setup and mention it once in their reports; only om-discovery-setup runs the delivery setup when it is missing. Roles settled against the market: Product owner is always part of the layer, Domain expert and Designer are flags, the Reviewer line carries the tech-lead duties (second person on risk-high, spec sign-off), the Maintainer owns the installed skills and acts as release manager unless one is named. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Wn4uCwRHXeknwj2s91JWW * refactor: rename om-discovery-setup to om-setup-discovery-pipeline It edits the pipeline files om-setup-agent-pipeline owns (the config and SDLC.md), so it is that skill's counterpart, not om-ux-setup's, and the two names now read as a pair. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Wn4uCwRHXeknwj2s91JWW * fix(om-setup-discovery-pipeline): defects from the first run on a lesson-3 repository A run on an SDLC.md generated from the pre-discovery template left the old Intake row under the new pair, placed the Definition of Ready before the validation gate because the after-merge paragraph it anchored on did not exist, and put marker lines inside the lifecycle table, which breaks a GFM table. Rows are now replaced by stage name (an Intake row that does not mention the Definition of Ready is the delivery-only row, whatever its wording), the two sections anchor on the first of the section headings that exists, and rows and bullets carry an inline <!-- discovery --> marker instead of marker lines. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Wn4uCwRHXeknwj2s91JWW * feat(om-setup-discovery-pipeline): one voice for the questions and the confirmation The first interactive run asked in the skill's own vocabulary — "delivery-only Intake row", "marked blocks", "byte-for-byte", "amending block" — the same defect om-discover fixed on 2026-09-03. A voice reference now binds the two questions, the pre-write confirmation, and the report to the user's language: say what they will see in SDLC.md, the one row that is rewritten and what it said before, what is left alone and why; one thing per question, with a default and what the answer changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Wn4uCwRHXeknwj2s91JWW * fix(om-setup-discovery-pipeline): report length target; never advise re-running om-setup-agent-pipeline to refresh an existing SDLC.md Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Wn4uCwRHXeknwj2s91JWW * fix(pre-intake): preserve contracts while rebasing onto current base * feat(discovery): add neutral prototypes before brief refresh * fix(om-discover): clarify questions, briefs, and handoffs * fix(skills): make discovery and QA contracts executable --------- Co-authored-by: Maciej Gren <maciej.gren@gmail.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: Piotr Karwatka <piotr@catchthetornado.com> Co-authored-by: Piotr Karwatka <piotr.karwatka@gmail.com>
Open Mercato Skills
🧠 plan · 🔨 implement · 🔍 review · ✅ QA gate · 🚢 merge
Forty-one agent skills that run a full PR pipeline. Install them into any repo, with any coding agent.
These skills wrote and shipped a real product. Inside the Open Mercato project, this workflow produced ~800k lines of code with zero hand-written lines, 1700+ merged PRs, 4000 unit tests, 730 integration tests, and weekly releases, with 100+ contributors working through it. This repository extracts the pipeline itself, stripped of everything product-specific, so any team with a GitHub repo can run it.
⚡ 30-second quickstart
npx skills add open-mercato/skills --skill '*'
Install all forty-one — the pipeline composes, and every skill is small until invoked. Drop --skill '*' to cherry-pick interactively. Skills install for 22+ coding agents (Claude Code, Cursor, Codex, and others) via skills.sh.
Then, once per repository:
/om-setup-agent-pipeline
It inspects your repo (default branch, validation scripts, GitHub labels), asks a few questions, writes .ai/agentic.config.json, and generates SDLC.md — your team's ticket-flow doc. Every other skill reads the config.
Then ship something:
/om-auto-create-pr "add rate limiting to the login endpoint"
The agent drafts an execution plan, implements it phase by phase in an isolated worktree, runs your validation commands, reviews its own diff, and opens a labeled, reviewed PR.
🔄 Update an existing installation
Update project-installed skills from the project directory:
npx skills update -p
For skills installed globally, update the global installation instead:
npx skills update -g
This refreshes the installed skill files to their latest versions. It does not overwrite artifacts that the setup skill previously generated inside your repository, including .ai/trackers/<tracker>.md and .ai/browsers/<provider>.md. After updating, run:
/om-apply-upgrade-notes
That skill applies the relevant UPGRADE_NOTES.md migrations while preserving local edits.
ℹ️ A few skills drive a real browser through the configured browser provider — om-prepare-test-env, om-integration-tests, and om-auto-qa-pr. Because of that, skills.sh validation may flag them as Medium or High risk. We of course recommend reading any skill before you run it — but we use these exactly as shipped at Open Mercato, with no issues so far.
🎬 See how it works!
🛠️ Local development
Working on the skills themselves? Skip the npx skills add round-trip and symlink this checkout straight into your agents' skill directories:
npm run install-skills
This links every skill in skills/ into ~/.claude/skills (Claude Code) and ~/.codex/skills (Codex). Because they are symlinks, any edit you make in this repo is live on the next skill invocation — no reinstall needed.
Options:
npm run install-skills -- --agent claude # only one agent (claude or codex)
npm run install-skills -- --force # replace existing non-symlink installs
npm run uninstall-skills # remove only the links owned by this repo
The installer never touches skills it does not own: an existing real directory (e.g. installed earlier via npx skills add) is skipped with a warning unless you pass --force, and uninstall removes only symlinks that point into this checkout.
🔁 The pipeline
Three entry paths: hand the agent a task brief (om-auto-create-pr), a spec (om-auto-write-spec to author one, om-auto-implement-spec to build one), or a GitHub issue (om-auto-fix-issue). The issue path classifies first — a bug drives the autofix chain, a feature request gets its spec resolved (or autonomously written) and implemented on the same PR. All paths converge on the same review loop and the same QA gate. And when there is no artifact yet — just an idea or a question — om-brainstorm runs the conversation first and hands the pipeline a routing decision plus a brief. Before even that, om-discover establishes the product context every later decision reads: a product-brief.md built from real material — interviews, data, documents — with every claim tagged by its evidence and every decision owned by a person.
The skills chain: every PR-producing skill ends with a PR: #<number> (link: <url>) reference line the next skill consumes, and every skill checks for a PR a previous skill already opened and continues on it instead of opening a duplicate. A completed autonomous run always leaves a ready, fully labeled PR (pipeline + category + priority + risk + QA meta) with a run-summary comment — and screenshots from the working app when the change is user-facing. Skills claim PRs and issues with an in-progress label, so concurrent agents back off instead of colliding.
flowchart LR
discover["om-discover<br/>(product context)"] --> brainstorm
discover -. "optional first panel" .-> panel["om-synthetic-users"]
panel -. "optional low-fi flow" .-> prototype["om-mockup-prototype"]
prototype --> refresh["om-discover --refresh"]
panel -. "prototype declined" .-> refresh
refresh -. "ready" .-> backlog["om-backlog --dry-run"]
brainstorm["om-brainstorm<br/>(conversation)"] -. "small task" .-> createPR
brainstorm -. "feature" .-> writeSpec
subgraph brief ["From a task brief"]
createPR["om-auto-create-pr"] --> reviewPR["om-auto-review-pr"]
reviewPR -- "changes requested" --> continuePR["om-auto-continue-pr"]
continuePR --> reviewPR
reviewPR -- "approved" --> qaGate{"QA gate"}
qaGate -- "skip-qa" --> mergePR["om-merge-buddy /<br/>om-approve-merge-pr"]
qaGate -- "needs-qa" --> manualQA["manual QA"]
manualQA -- "qa-approved" --> mergePR
end
subgraph issue ["From a GitHub issue: om-auto-fix-issue classifies, then routes"]
classify{"bug or FR?"}
classify -- "bug" --> verifyStep["om-verify-in-repo"]
verifyStep --> rootCause["om-root-cause"]
rootCause --> applyFix["om-fix"]
applyFix --> openPR["om-open-pr"]
classify -- "feature request" --> specExists{"spec exists?"}
specExists -- "no spec" --> writeSpec["om-auto-write-spec<br/>(spec PR + mockups)"]
writeSpec --> implementSpec["om-auto-implement-spec"]
specExists -- "spec exists" --> implementSpec
end
openPR --> reviewPR
implementSpec --> reviewPR
📦 Skill catalog
📇 Per-skill cards with parameters: docs/skills/
🤖 Autonomous skills
Naming convention: the om-auto-* prefix means autonomous and non-interactive — hand these a brief, an issue, or nothing at all and they run end-to-end without supervision: they claim their work with the in-progress lock so concurrent agents back off, work in isolated worktrees so your checkout stays untouched, run the validation gate, self-review, make the recommended most-reversible call themselves (documented for override) instead of stopping to ask, and finish with a PR, a review verdict, or a reconciled tracker. Safe to run on a schedule or in CI. Every skill without the auto prefix is interactive: it acts once, may ask you questions, reports, and hands control back.
| Skill | What it does autonomously |
|---|---|
om-auto-create-pr |
Takes a free-form task brief end-to-end: execution plan, isolated worktree, phase-by-phase commits, validation gate, self-review, labeled PR, then an autofix review loop until clean. Resumable. Hands runs whose plan exceeds the configured step threshold to om-auto-create-pr-loop automatically. |
om-auto-create-pr-loop |
Advanced om-auto-create-pr for long spec implementations: run folder with PLAN/HANDOFF/NOTIFY, one commit per step, checkpoint verification every ~5 steps, plan-driven executor dispatch (per-step placement + model-tier hints in the plan), full gate at completion. |
om-auto-fix-issue |
The single issue-to-PR entry point: classifies the issue first, then routes. A bug drives the autofix chain — triage gate, root-cause analysis, minimal fix with regression tests, a ready labeled PR, autofix review loop. A feature request takes the feature route — claims the issue, resolves its spec (autonomously written via om-auto-write-spec when none exists, implemented via om-auto-implement-spec), and verifies the contract on the same PR — reviewed, UI-verified, fully labeled. For a spec without implementation, run om-auto-write-spec directly. Stops cleanly when the issue is already solved or claimed, and on the feature route when the ticket fails SDLC.md's Definition of Ready (the gaps are named on the issue). |
om-auto-write-spec |
Turns a brief or FR issue into a finished spec on a ready PR: autonomous Open-Questions defaults posted for override, UI mockups + current-app screenshots attached as PR evidence, full SDLC labels, chain markers for om-auto-implement-spec. |
om-auto-implement-spec |
Implements an existing spec (by path, name, issue, or spec-PR number; clean stop when not found): reuses the spec PR's branch or runs om-auto-create-pr, then the review autofix loop and UI verification with screenshots on the PR. |
om-auto-continue-pr |
Resumes an in-progress PR from the first unchecked step in its tracking plan and carries it to completion — implementation, validation, review loop, summary comment. A PR with no plan (a human's, another tool's, a crashed run's) is adopted: the goal is reconstructed from its description, comments, review feedback, linked issues and diff, landed as a real plan, then executed. |
om-auto-continue-pr-loop |
Resumes runs started by om-auto-create-pr-loop: orients from HANDOFF.md, picks up at the first non-done Tasks-table row, keeps the per-step commit and checkpoint discipline to completion. |
om-auto-review-pr |
Reviews a PR by number in an isolated worktree, approves or requests changes, manages labels. On changes-requested, its autofix loop iterates fixes and re-review until merge-ready. A spec-only design PR gets a specification review instead of the code checklist: what can go wrong, backward compatibility, what's missing, how the spec can be improved, and whether it is the simplest possible solution — same severity scale and verdict rule, and the autofix loop amends the spec document (never adds implementation). |
om-auto-fix-pr |
Drives one PR to merge-ready: merges the latest base in first, then loops review-autofix (om-auto-review-pr), its own CI-stabilization step (classify each failing check as real bug / test bug / flake / infra, fix the real ones with tests, never fake green), and UI QA (om-auto-qa-pr), re-merging base whenever it advances. Files follow-up issues for non-blocking nits via om-followup-issue-from-pr, keeps the fork carry-forward supersede/credit rules, normalizes labels, and hands off to om-approve-merge-pr — it never merges itself. A --ci-only [--branch <name>] mode drives a plain branch or no-PR change to green CI without the rest of the loop. |
om-pr-autopilot |
The single "just finish this PR" entry point: diagnoses what state one open PR is actually in — unfinished plan steps, missing review, unresolved conversations, red CI, base conflicts, missing labels or QA evidence, merge-ready — then maps that onto an ordered chain of the skills above and runs it, re-diagnosing between steps. Dispatch only: om-auto-continue-pr, om-auto-fix-pr, om-auto-qa-pr, om-followup-issue-from-pr and om-approve-merge-pr do the work. Never merges without --allow-merge; --dry-run diagnoses and mutates nothing. |
om-review-prs |
Sweeps all unreviewed open PRs, newest first, through om-auto-review-pr, respecting claim locks. |
om-close-fixed-issues |
Post-merge housekeeping sweep: closes issues that merged PRs fix, comments on issues whose PRs were closed without merging. |
🧑💻 Interactive skills
Interactive helpers (no auto in the name — the other half of the naming convention): they act once, may ask you questions along the way, report, and hand control back to you.
| Skill | What it does |
|---|---|
om-setup-agent-pipeline |
One-per-repo configurator. Inspects the repository, asks a few questions, writes .ai/agentic.config.json, installs tracker and browser-provider descriptors, generates SDLC.md and an AGENTS.md starter when missing. Verifies cross-skill coverage: if an installed skill references one that isn't installed, it prints the exact npx skills add command to fix it. |
om-setup-discovery-pipeline |
Adds the optional product layer to a configured repo: one yes per product role, a discovery block in the config, and the Discovery stage, Definition of Ready, product roles, and protected product decisions inserted into the existing SDLC.md between markers. Turns on the readiness checks in om-auto-manage-issues, om-auto-fix-issue, and om-backlog; nothing in om-discover requires it. |
om-apply-upgrade-notes |
Post-upgrade migrator. Applies UPGRADE_NOTES.md to the repo: re-syncs installed tracker/browser descriptors while preserving local edits, reports custom-provider gaps, and checks the config against notable upgrades. |
om-merge-buddy |
Scans open PRs and reports which can merge now and which are close but blocked, based on labels, reviews, CI, and mergeability. |
om-pipeline-retro |
Classifies runs the pipeline already finished — clean single pass, hard recovery, loop checkpoints, or a second pass with no recorded cause — and ranks the causes by the wall-clock hours they cost. Read-only; hands the top cause to om-prepare-issue. |
om-approve-merge-pr |
Approves and squash-merges a PR given only its number. Can file a follow-up issue at the same time. |
om-check-and-commit |
Runs the configured validation gate on the current branch, fixes obvious drift, then commits and pushes when green. |
om-followup-issue-from-pr |
Turns a PR or a PR comment into a tracked follow-up issue, assigned to the right person. |
om-discover |
Product-level discovery and define, before there is anything to brainstorm about. Runs in three modes — existing product, client idea, own idea — and leaves one product-brief.md: problem and who has it, stakeholders, rules, flows, benchmark, success criteria, scope (now, later, not doing), non-goals, decisions with owners, riskiest assumptions with tests, open questions. Gathers real material first: a section with nothing behind it becomes a collection plan with capture templates, never prose; synthetic personas and assumptions are tagged and never count as evidence. om-brainstorm, om-spec-writing, and om-prepare-issue read the brief when it exists, and its non-goals, business rules, and decisions become a contract the review skills enforce. |
om-synthetic-users |
A panel of personas from the material the repo already holds, interviewed about the last time and then under the pressures the brief describes (never "would you use"), walking one flow through their eyes — on the brief or spec as a narrative, on a static prototype, or on the running app through the browser provider. Fresh panel per run, at least two runs, only what repeats is a finding, spread is the error bar; saturation tracked; a parity check against real interview notes when they exist, where the deviation is the finding. Three stances: validate, simulate (every answer is "to confirm"), adversary (agreement is discarded). Everything tagged [SYNTHETIC], never evidence, never numbers. |
om-mockup-prototype |
Turns a selected brief flow and the first synthetic panel into a neutral clickable discovery prototype. Keeps assumptions visible, checks navigation and recovery states in a browser, and writes a local revision with its context. It runs before the brief refresh and backlog; detailed visual design belongs to the later specification stage. |
om-backlog |
Turns a product brief or a spec's Phasing into epics, stories with acceptance criteria, and tasks — ids in titles, Epic: lines, epic checklists — filing every issue through om-prepare-issue so dedupe, labels, and rationale are unchanged. Adopts existing issues instead of duplicating them, refuses a brief that rests on assumptions (offering the research backlog instead), and shows the whole tree before writing anything. |
om-brainstorm |
The conversation before any artifact exists: open questions one at a time, alternatives weighed (including building nothing), a challenger subagent attacks the conclusion, then the user confirms a routing decision — a machine-parsed Next: line plus a handoff brief that feeds om-prepare-issue, om-auto-write-spec, om-spec-writing, or om-auto-create-pr. |
om-spec-writing |
Writes and reviews feature specs to staff-engineer standards: skeleton-first with a hard Open Questions gate, phased implementation breakdown that feeds om-auto-create-pr, severity-ranked architectural reviews. |
om-prepare-issue |
Files a single well-formed tracker issue for deferred work: dedupes against existing issues and PRs, links (or authors) a covering spec, otherwise embeds step-by-step guidance, and applies the SDLC labels on creation. |
om-auto-manage-issues |
Brings existing issues up to standard, single or in bulk: applies missing SDLC labels, and for a laconic issue (one line + a screenshot) analyzes the screenshot with the terse text, clarifies the wording non-destructively, and posts the agent's understanding as a comment. Checks every issue against the Definition of Ready in SDLC.md and posts a not-ready comment naming what is missing. Checks spec coverage for feature issues: when one lacks a covering spec it posts a spec-required comment to the issue author (fill up the spec before implementation), or authors the spec itself via om-auto-write-spec with --write-missing-specs (default off). Batch defaults to the last ~25 open, worst-described first, narrowable by state/label/author/limit. Idempotent and claim-aware. |
om-integration-tests |
Creates and runs integration/E2E tests by exploring the running app first — real locators, runtime fixtures, no hardcoded IDs — and reports failures with artifact-based per-test diagnosis. Reuses the shared om-prepare-test-env instance so QA and tests hit the same booted app. |
om-auto-qa-pr |
QAs a change's UI in a real browser without merging. Checks the PR's review state first and runs om-auto-review-pr when the PR is still unreviewed, then boots the app via om-prepare-test-env, derives a scenario from the diff, drives the configured browser provider with screenshots, and produces a pass/fail report. Posts evidence as a PR comment when a tracker is configured; otherwise saves screenshots + JSON/Markdown reports. |
om-auto-update-changelog |
Drafts a CHANGELOG.md release entry for every PR merged since the last release — emoji categories, contributor credits resolved by the Supersede Credit Rule and verified against commit authorship so carry-forwards and umbrella merges credit the author, not the merger — then delegates to om-auto-create-pr to ship it as a docs PR. |
🤝 Skills invoke each other
The building blocks behind the autofix chain and the review loop. You can call them directly, but they mainly exist for the other skills to compose.
| Skill | What it does |
|---|---|
om-verify-in-repo |
Read-only triage gate: decides whether a GitHub issue is a real, still-unfixed defect, and stops the chain cleanly when there is nothing to do. |
om-root-cause |
Read-only analysis: locates the bug and the minimal change surface so the fix step never re-explores the repo. |
om-fix |
Implements the minimal change, adds regression tests, runs the validation gate. Does not commit or push. |
om-open-pr |
The shared PR opener: commits, pushes, opens (or reuses) a ready PR with the unified body template, applies the full SDLC label set, posts the run summary, releases the claim lock, and emits the chain markers. |
om-code-review |
The review checklist behind om-auto-review-pr: correctness, security, contract surfaces, plus your repo-local checklist when configured. |
om-prepare-test-env |
Boots the app for QA and tests, any stack: reuses the repo's own environment or generates portable bring-up scripts, then caches builds and validates warm reuse. It autonomously provisions the configured browser provider (agent-browser by default; Playwright supported), writes a shared environment descriptor, and works on macOS, Linux, WSL2, and Windows. |
👥 Workflows by role
Same pipeline, different entry points. Each role runs one or two commands; the skills chain the rest automatically. Deeper guides live under docs/roles/.
📋 Product Manager / Analyst
Turn ideas into well-formed, labeled work — and review the plan before any code is written.
| ▶️ You run | ⚙️ Runs automatically inside | 🎁 You get |
|---|---|---|
/om-setup-discovery-pipeline once |
om-setup-agent-pipeline when the delivery layer is missing; the SDLC template's product-layer blocks |
the product layer switched on: product roles, the Discovery stage, the Definition of Ready, and protected decisions in SDLC.md, and the readiness gate the skills below enforce |
/om-discover --mode client "Benefits portal for SMB clients" |
context gate over your research folder, interview rounds, a skeptic subagent, a quality gate against invented evidence | product-brief.md with tagged evidence and owned decisions, or a collection plan naming what still has to be gathered |
/om-synthetic-users .ai/specs/product-brief.md --flow "first claim" |
personas built from the brief's evidence, simulated interviews, a narrative or browser walk, a quality gate against invented detail | barriers, missing cases, and contradictions as [SYNTHETIC] hypotheses, each with the real-user check that would settle it |
/om-backlog .ai/specs/product-brief.md |
readiness check against the Definition of Ready, dedupe per story, om-prepare-issue per issue |
epics, stories with acceptance criteria, and tasks in the tracker, ids in titles, a backlog.md map — after you have seen the tree and said yes |
/om-brainstorm "should we build bulk-archive?" |
read-only repo reading and tracker checks, a challenger subagent | a routing decision with its reasoning, and a brief file the pipeline can run with |
/om-prepare-issue "Bulk-archive orders from the grid" |
dedupe search, om-spec-writing (when a feature needs a spec) |
one well-formed issue with SDLC labels, a linked spec or step-by-step guidance |
/om-auto-manage-issues |
claim-aware label sync, screenshot analysis, implementation-prep comment, spec-coverage check | the backlog triaged: missing labels added, laconic issues clarified, feature issues without a spec get a spec-required comment to their author (or a spec via --write-missing-specs) |
/om-auto-write-spec 123 |
om-spec-writing --autonomous, om-open-pr |
a spec-first PR to review before implementation starts |
More: docs/roles/product-manager.md
🎨 Designer
Get a written spec with visuals attached — mockups of the new layout next to screenshots of the current app.
| ▶️ You run | ⚙️ Runs automatically inside | 🎁 You get |
|---|---|---|
/om-auto-write-spec "Redesign the checkout summary panel" |
om-spec-writing --autonomous, om-open-pr, om-prepare-test-env + browser provider |
a ready spec PR with UI mockups, current-app screenshots, and an assumptions comment |
/om-auto-implement-spec 2026-07-18-checkout-redesign |
om-auto-create-pr, om-auto-review-pr, om-auto-qa-pr |
the built change with before/after screenshots from the working app |
/om-auto-qa-pr 123 |
om-prepare-test-env, browser provider |
fresh screenshots of a PR's UI to design-review, no source touched |
/om-ux-setup once, then /om-ux-review-pr 123 |
om-ux-setup extracts the repo's design contract; om-ux-review-pr walks the PR in a real browser |
a design review judged against your own design system: evidence-tagged findings with done-when criteria |
/om-ux-shape "Quick-add flow for the people list" |
om-ux-shape |
a decided direction before anything is drawn: scope, states, riskiest-assumption test |
💡 Tip — ask for visuals explicitly to force mockups: /om-auto-write-spec "Redesign the checkout summary panel — include mockups of the new layout and screenshots of the current one".
More: docs/roles/designer.md
👩💻 Developer
Hand off a brief, a spec, or an issue number; get back a reviewed, labeled PR.
| ▶️ You run | ⚙️ Runs automatically inside | 🎁 You get |
|---|---|---|
/om-auto-write-spec "CSV export for the orders grid" |
om-spec-writing --autonomous, om-open-pr, browser provider for mockups |
a ready spec PR with mockups + assumptions comment |
/om-auto-implement-spec 2026-07-18-csv-export |
om-auto-create-pr / om-auto-continue-pr, om-auto-review-pr, om-auto-qa-pr |
an implemented, reviewed PR with screenshots from the working app |
/om-auto-fix-issue 123 |
classifies then routes: bugs to the autofix chain, features to om-auto-write-spec + om-auto-implement-spec |
a finished, fully-labeled PR from an issue number |
/om-auto-fix-issue 456 |
om-verify-in-repo, om-root-cause, om-fix, om-open-pr, om-auto-review-pr |
a bug-fix PR with regression tests and a clean review |
🔁 /om-auto-create-pr-loop "Implement the multi-tenant billing spec" |
run folder (PLAN/HANDOFF/NOTIFY), per-step commits, checkpoint verification | a resumable, step-tracked PR for a large spec (continue with om-auto-continue-pr-loop; plain runs escalate here on their own past the step threshold) |
More: docs/roles/developer.md
🧪 QA
Boot the app once, verify UI changes in a real browser, and add integration coverage — without touching source.
| ▶️ You run | ⚙️ Runs automatically inside | 🎁 You get |
|---|---|---|
/om-prepare-test-env |
app discovery, launch-script generation, browser-provider provisioning | a reusable booted app + shared test-env descriptor the other QA skills reuse |
/om-auto-qa-pr 123 |
om-prepare-test-env, browser provider |
screenshots + a pass/fail report posted on the PR (evidence only, no labels changed) |
/om-auto-qa-pr 123 --self-qa-signoff |
same, plus label guards | qa-approved + qa-self-verified — only on a fully-green run with screenshots on a needs-qa PR |
/om-integration-tests |
om-prepare-test-env, browser provider |
integration/E2E tests written against the live app, with artifact-based failure diagnosis |
More: docs/roles/qa.md
🚀 Release Manager
Sweep open PRs, drive them to merge-ready, and ship — the QA gate stays a human decision.
| ▶️ You run | ⚙️ Runs automatically inside | 🎁 You get |
|---|---|---|
/om-merge-buddy |
tracker scan of labels, reviews, CI, mergeability | a report of which PRs can merge now and which are close but blocked |
/om-review-prs |
om-auto-review-pr per PR, claim-lock aware |
every unreviewed open PR reviewed, newest first |
/om-auto-fix-pr 123 |
om-auto-review-pr, its CI-stabilization step, om-auto-qa-pr, om-followup-issue-from-pr |
one PR driven to approvable, green, QA-evidenced — handed to om-approve-merge-pr, never self-merged |
/om-auto-fix-pr 123 --ci-only |
tracker check status + failed-step logs | green CI from real fixes with tests, never by weakening checks |
/om-pr-autopilot 123 |
diagnosis of the PR's real state, then the matching chain of the skills above | one PR driven from wherever it is to merge-ready, with a summary comment covering every step — never merged unless --allow-merge |
/om-auto-update-changelog |
om-auto-create-pr |
a CHANGELOG release entry landed as a docs PR, with Supersede Credit |
/om-approve-merge-pr 123 |
approving review + squash-merge, QA-gate guard | the PR merged — refused when needs-qa lacks qa-approved or a blocking label is set |
More: docs/roles/release-manager.md
🧰 Works with any stack
Nothing here assumes JavaScript, or any particular product. The base branch, the validation commands, the label taxonomy, and the working paths all come from one committed file, .ai/agentic.config.json, written by om-setup-agent-pipeline:
{
"version": 1,
"baseBranch": "auto",
"tracker": "github",
"browser": { "provider": "agent-browser" },
"validation": {
"commands": ["pnpm typecheck", "pnpm test", "pnpm build"]
},
"labels": {
"enabled": true,
"pipeline": ["review", "changes-requested", "qa", "qa-failed", "merge-queue", "blocked", "do-not-merge"],
"category": ["bug", "feature", "refactor", "security", "dependencies", "documentation"],
"meta": ["needs-qa", "skip-qa", "qa-approved", "qa-self-verified", "in-progress"],
"priority": ["priority-low", "priority-medium", "priority-high", "priority-extreme"],
"risk": ["risk-low", "risk-medium", "risk-high"]
},
"qaGate": true,
"paths": {
"runs": ".ai/runs",
"analysis": ".ai/analysis",
"specs": ".ai/specs",
"scripts": ".ai/scripts",
"qa": ".ai/qa"
},
"reviewChecklist": null,
"closeKeywords": []
}
A Rust repo puts cargo test and cargo clippy in validation.commands; a Go repo puts go test ./.... Skills run whatever you configure and treat any non-zero exit as a gate failure. A skill invoked in a repo without the config runs om-setup-agent-pipeline first — interactively when you're there to answer its questions, with --defaults when running unattended — then continues with the freshly written config.
GitHub is the default tracker. Shipped split-provider templates also support Linear issues through schpet/linear-cli and Jira Cloud work items through Atlassian CLI, while GitHub continues to own PRs, reviews, and CI — see the tracker providers section below.
Agent-browser is the default browser automation provider for fresh setups. It installs itself and Chrome for Testing when needed; existing repositories remain on Playwright until their config makes a provider explicit.
🎨 Make it yours
Four layers of project fit, no forking:
- Agent instructions — skills read your
AGENTS.md/CLAUDE.mdbefore working, so project conventions apply from the first run. No such file?om-setup-agent-pipelineoffers a starter. - Generated project docs —
SDLC.md(the process doc),CODE_REVIEW.md(review rules, auto-applied byom-code-review),BACKWARD_COMPATIBILITY.md(protected contract surfaces — reviews flag violations, implementations warn you), and anAGENTS.mdstarter with a task-routing table.om-setup-agent-pipelinederives each from your repository and only when the file is missing; existing docs are honored as-is. - Repo-local skills — drop a skill with the same name into your repo at
.ai/skills/<skill-name>/SKILL.mdand it takes precedence over the installed one (details below). - Tracker descriptor — every issue/PR/label command the skills run lives in one committed file,
.ai/trackers/<tracker>.md, that you can edit or replace (details below).
🧩 Extending the skills
How a skill is laid out
Each skill keeps its numbered main algorithm in SKILL.md and factors its repeatable procedures into per-skill references/<step>.md files under standard names — agentic-setup.md, worktree-setup.md, claim-pr.md, pr-finalize.md, review-report.md, rules.md. These standard step files are deliberately duplicated inside every skill that uses them rather than shared through cross-skill pointers, so each skill installs and runs standalone (om-auto-create-pr holds the canonical copy). The trade-off is intentional: standalone installability over DRY. When you edit a standard step file in one skill, sync the same change into the other skills that carry it — the collection's own contributor rule is to ask whether to propagate before doing so.
Repo-local skill overrides
Every installed skill checks, right after loading the config, for a repo-local skill of the same name at .ai/skills/<skill-name>/SKILL.md. When present, the local skill wins — the installed one follows it instead of its own instructions. To extend rather than replace, the local skill just @-imports or references the installed skill and adds rules on top:
<!-- .ai/skills/om-auto-review-pr/SKILL.md -->
Follow the installed `om-auto-review-pr` skill, plus:
- Also run `pnpm test:e2e` before approving PRs that touch `apps/web`.
- Our PR body template additionally requires a "Screenshots" section for UI changes.
Local rules win, but a local skill can never relax the installed skill's safety rules (no skipping tests, no --no-verify, no force-pushes). This convention is also what makes the collection a drop-in for repos that already keep specialized om-* skills under .ai/skills/: the installed skills defer to them automatically.
Project management (tracker) providers
No skill calls gh — or any tracker CLI — directly. Skills name tracker operations (get-issue, create-pr, comment-pr, merge-pr, …) and one committed descriptor file, .ai/trackers/<tracker>.md, defines how each operation is executed. om-setup-agent-pipeline asks which tracker you use, sets the config's tracker field, and installs the matching descriptor into your repo.
That file is yours, which makes three things easy:
- Extend or override GitHub behavior — edit
.ai/trackers/github.md: add flags, change the merge strategy, adjust comment conventions, extend the label taxonomy commands. Every skill picks it up on its next run. - Use a shipped split provider — select
linearfor Linear issues throughschpet/linear-cli, orjirafor Jira Cloud work items through Atlassian CLI. Setup installs the selected descriptor plusgithub.md, because the code host still owns PRs, reviews, CI, and PR labels. The templates document authentication, issue-label semantics, claim signals, identifier cross-links, and explicit post-merge issue transitions. - Bring your own tracker — write
.ai/trackers/<name>.mdfrom the shippedTEMPLATE.md(inom-setup-agent-pipeline/references/trackers/), implementing each operation with your tracker's CLI, MCP tools, or API, and set"tracker": "<name>"in the config. No skill changes needed — the descriptor is the whole integration surface. - Build another split setup — implement issue operations against the project tracker and delegate repository/PR/review/CI/PR-label operations to its code-host companion. The template documents the pattern, including how identifiers cross-link (for example, an
ENG-123ticket referenced from a GitHub PR).
The claim protocol (assignee + in-progress + 🤖 comment), the label guards (missing label ⇒ logged skip, labels.enabled: false ⇒ no label ops), and the QA gate semantics are part of the contract — a provider must express them, in whatever way its tracker allows.
Browser automation providers
QA and integration-test skills select browser.provider from
.ai/agentic.config.json and execute the committed descriptor at
.ai/browsers/<provider>.md. Fresh setups use agent-browser; Playwright remains
available for existing repositories and teams that prefer it. The agent-browser
descriptor downloads its native release binary and Chrome for Testing itself,
then verifies a live headless launch — no Node runtime, project dependency, or
cloud-browser subscription is required.
Custom providers implement the operations in
skills/om-setup-agent-pipeline/references/browsers/TEMPLATE.md. Repository E2E
suites remain authoritative; the provider controls agent-driven exploration,
assertions, and screenshots.
🏷️ Labels and the QA gate
Every PR carries at most one pipeline label (review, changes-requested, merge-queue, ...) plus additive category, meta, priority, and risk labels; priority says how urgent the work is, risk says how dangerous the change is to ship. The full taxonomy, and whether to use labels at all, lives in the config; om-setup-agent-pipeline documents every group and creates missing labels for you.
A PR labeled needs-qa cannot merge without qa-approved, even with green checks. A QA reviewer grants approval, or om-auto-qa-pr --self-qa-signoff uses the documented exception below risk-high, with evidence tied to the current head and the qa-self-verified label. Authoring and merge skills do not grant QA approval.
🚀 Built with this workflow
Real production case studies are being added here.
Built by the Open Mercato team, where these skills ship the product every week. We teach this way of working at aitechleaders.pl (an AI engineering course, in Polish).