fmk-plugins

Operate fticket (FTS, the Factory Ticket System) through its `fts` CLI — the SQLite-backed transactional control plane that coordinates concurrent agents in an AI software factory. Covers initializing a staged pipeline database, creating tickets, atomic claim/renew/start/complete/advance through stages, dependencies, resource leases with FIFO waitlists, the scheduler sweep, and diagnosing stuck work (board, why, triage, doctor, events, serve). TRIGGER whenever the user or task mentions fticket, FTS, `fts` commands, factory.db, factory tickets, ticket stages/queues, claiming or advancing a ticket, worker claims, resource leases, dead-letter or orphan triage, or wiring agents/workers to a ticket pipeline — even if they just say "check the board" or "why is ticket N stuck" in a factory context. SKIP for GitHub/Jira/Linear issues or generic project-management tickets that are not backed by an fticket database.

A Definition-of-Ready gate run on a task/ticket BEFORE decomposition or implementation begins. Restates the goal as observable behavior, walks a readiness checklist item by item, and classifies every gap as blocking (needs a human decision), resolvable-by-research (answer exists in the codebase/docs — go find it), or deferrable (a conservative default exists — propose it). Prevents the failure mode where a capable model receives a vague ticket, silently fills the gaps with plausible assumptions, and builds something that compiles and is confidently wrong in ways nobody decided. Moves ambiguity discovery to the cheapest point — before any agent is spawned. TRIGGER on phrases like "is this ticket ready", "definition of ready", "readiness check", "can we start on this", "is this ready to implement", "check this ticket before we build", "DoR gate", "is this well-specified enough", "ready for decomposition", "vet this ticket", "any blockers before we start", "/check-readiness". SKIP when the work is already in fli

Executor discipline for splitting a feature or change into parallelizable tasks for multiple agents. Enforces disjoint file ownership (a verified zero-intersection ownership table), explicit dependency edges between every pair of tasks, an independently-completable bar (each task finishable and gate-passable with only its contract, spec, and file list), right-sizing into vertical slices, per-task specs in the standard template, a contract frozen FIRST when tasks share an interface, and an explicit integration task at the end. Prevents the two agents editing the same file / task B silently needing task A's output failure that causes collisions, merge conflicts, and integration failure. TRIGGER on phrases like "decompose this task", "break this into parallel tasks", "split this feature for multiple agents", "how do I fan this out", "plan the parallel work", "divide this across agents", "who owns which files", "make a task breakdown", "parallelize this change", "carve this into tasks", "assign work to subagents"

Executor discipline for designing a PUBLIC or consumer-facing API surface — HTTP/REST, RPC, GraphQL, webhooks/events, or an SDK surface that callers you do not control will depend on. Forces a surface-wide inventory FIRST so new endpoints match existing naming, envelope, pagination, error, and auth conventions instead of each being locally elegant and collectively incoherent; makes auth (authn + object-level authz), idempotency, pagination, a single error envelope, and a stated compatibility stance mandatory per endpoint; and runs a consumer-journey walkthrough before freezing. Emits the surface as an executable spec (OpenAPI/proto/GraphQL SDL or a typed endpoint table). Exists to prevent the verb-soup RPC surface, the unguarded endpoint, and the accidental forever-contract. TRIGGER on phrases like "design the API", "design the REST endpoints", "design the public API surface", "spec the HTTP API", "design the GraphQL schema", "write the OpenAPI spec", "design the webhook/events contract", "design the SDK surf

Executor discipline for authoring the FROZEN contract — the interfaces, types, error taxonomy, config schema, and constants that parallel implementers and test writers build against — with zero logic smuggled in. Enforces strong types (no any/dict/stringly-typed enums), first-class error shapes, boundary completeness between parallel tasks, a decision log, and a freeze protocol that makes the contract immutable once fan-out starts. Exists to prevent leaky, ambiguous contracts that cause parallel agents to diverge and integration to fail. TRIGGER on phrases like "design the contract", "write the contract first", "freeze the interfaces", "define the types and signatures", "contract-first", "set up the API contract before we split the work", "define the error shapes", "write the shared types for the parallel tasks", "spec the config schema", "the interface contract for the fan-out", "author the frozen contract", "define the seams between modules". SKIP when the user wants the implementation itself (this skill pr

Executor discipline for designing and writing tests (unit + integration) that catch real defects instead of restating the implementation. Forces every test case to be derived from a behavioral requirement in the contract/spec, a systematic edge-case enumeration before any test code is written, and a "can this test fail?" mutation check on each assertion. Kills the implementation-mirroring failure mode — tests that assert a mock was called or copy the code's own logic into the assertion and therefore pass forever while catching nothing. TRIGGER on phrases like "write tests for X", "add unit tests", "design a test suite", "test this function/module", "improve test coverage", "write integration tests", "what edge cases should I test", "add a regression test", "these tests pass but the bug shipped", "tests for the new endpoint", "cover this with tests", "test plan for this feature". SKIP when the user is running an existing suite with no new tests to author, when they want the red step of a strict TDD red-green-r

Executor discipline for the integration task at the end of a multi-agent parallel build — wiring independently-built, contract-conforming modules into a running whole. Enforces an inventory gate (no wiring while any module reports a red gate or contract conflict), wiring-files-only ownership (never edit an implementer's module), composition strictly through the frozen contract types, typed config assembly validated at startup, and a driven end-to-end smoke test (primary path + one error path + auth on the wired surface) as the done criterion. Prevents integration from becoming the place where hacks accumulate — the silent adapter/cast/glue-shim that makes mismatched modules "fit" and converts a loud compile-time defect into a quiet runtime one. TRIGGER on phrases like "integrate the modules", "wire everything together", "run the integration task", "compose the built modules", "wire the composition root", "assemble and smoke test", "hook up the DI/entry point", "final wiring and end-to-end", "stitch the slices

Executor discipline for making code measurably faster or lighter without breaking it. Forces a stated performance budget (target + workload) before any change, a recorded baseline benchmark on representative data, profiling to find the real bottleneck before hypothesizing, one change per measurement with a before/after table, structural wins before micro-optimization, and correctness held green throughout. Prevents optimization-by-intuition — the failure where a capable model "knows" what's slow (it is usually wrong), rewrites code for speed with no baseline, cannot prove any improvement, and trades away correctness or readability for wins that never existed. TRIGGER on phrases like "make this faster", "optimize this function/query/endpoint", "this is too slow", "reduce the latency of X", "speed up the build/job/pipeline", "cut memory usage", "the p99 is too high", "this query is slow", "profile and fix the hot path", "improve throughput of X", "reduce cold start / bundle size", "why is this taking so long".

Executor discipline for schema and data migrations. Forces you to classify the change (additive vs destructive vs data-transforming), plan expand-migrate-contract for anything non-additive, state deploy-window compatibility at every step, name the lock behavior and scale class of each DDL statement, batch large backfills, write a rollback story per step, and verify data integrity against a pre-written expected result. Exists to stop the migration that runs fine on a laptop and takes down prod — a table lock on a hot table, old code crashing against new schema mid-deploy, no rollback, or silent data loss on a rename or backfill. TRIGGER on phrases like "write a migration", "add a column", "drop this column", "rename this field", "change the column type", "backfill this data", "add an index", "add a NOT NULL constraint", "alter this table", "schema migration", "database migration", "reshape this table", "split this table". SKIP when the change is a pure application-code edit with no schema or data reshape, a re

Executor discipline for behavior-preserving refactoring. Forces a written invariant list, a verified test safety net BEFORE any edit, small green steps that keep the build and tests passing after every commit-sized move, and strict no-scope-creep — behavior changes and bug fixes found mid-refactor are reported as findings, not smuggled in. Prevents "refactor" from becoming a euphemism for a risky rewrite where behavior drifts, scope bleeds into neighboring code, and the module sits red for hours. TRIGGER on phrases like "refactor this", "clean up this module", "extract a function/class/service", "rename X across the codebase", "restructure this code", "split this file", "decouple X from Y", "tidy up without changing behavior", "improve the structure of X", "make this more readable/maintainable", "move this logic into", "deduplicate this code". SKIP when the change intentionally alters public interfaces or observable behavior (that is a contract change to escalate, not a refactor), when the task is a greenfiel

Defensive security review of a diff or module, driven by a threat model and an explicit absence checklist. Forces the reviewer to enumerate what SHOULD be present (authn, authz/IDOR, input validation, parameterized queries, secret handling, SSRF, rate limiting) rather than only critiquing the code that exists, and to prove every finding with a concrete attack scenario before reporting it. Blocks generic CVE trivia and unexploitable hardening noise dressed up as vulnerabilities. TRIGGER on phrases like "security review", "review this for security", "is this endpoint safe", "audit this diff for vulnerabilities", "check for injection/XSS/SSRF", "any authz holes here", "IDOR in this code", "threat model this change", "pentest this module (code-level)", "security sign-off on this PR", "review the auth flow for holes", "/review-security". SKIP when the task is offensive tooling against systems the team does not own, a pure dependency-version bump with no code change (run an SCA/`audit` tool instead), or a general "

Executor discipline for upgrading or adding a single dependency — read every changelog across the version range, map each breaking change to actual codebase usage, regenerate and review the lockfile, vet new packages against the registry, adapt code to the new API properly, and verify by behavior. Blocks the "bump and hope" failure where you change the version number, see it install and the build go green, and ship — silently inheriting runtime breaking changes, changed defaults, transitive-dependency shifts, and supply-chain risk. TRIGGER on phrases like "upgrade this dependency", "bump the version of X", "update X to the latest", "add package Y", "install this library", "upgrade the framework", "move to X v3", "update our dependencies", "apply this security patch / CVE fix", "migrate to the new major version", "add a new dependency for X", "npm update / pip upgrade this". SKIP when the task is implementing app behavior with no manifest change (use implement-feature), debugging a failure whose cause is not a

End-to-end generator for a complete, running, product-quality software system (frontend + backend, or either alone) built from a short brief in one orchestrated multi-agent build. Use whenever the user gives a one-line or short product idea and wants working software — "build me a CRM", "make an expense tracker with an API", "create an internal dashboard for X", "single-shot this app" — especially when they want it done autonomously, in parallel, or "like the Fable game build". The architect expands the brief with taste, freezes a compiler-enforced contract, product-directs every screen and endpoint in prose, fans out parallel implementers with disjoint file ownership, then hardens through compile loop → multi-lens review → adversarial verification → mechanical gate. Trigger even if the user never says "contract", "workflow", or "agents". Do NOT use for small edits to an existing codebase, single features in an established repo, or games (use single-shot-game-generation for games).

Open, decode, and inspect a Figma `.fig` file locally — no Figma app, account, login, or network needed. Use this WHENEVER the user wants to look inside, read, open, decode, convert, or extract anything from a `.fig` file (or a Figma export sitting on disk): listing the screens/frames, pulling the text content of a screen, extracting design tokens (color/spacing variables), grabbing the embedded images, or turning the design into JSON so it can be implemented in code. Trigger even when the user just says "open this figma file", "what's in this .fig", "extract the design from X.fig", "get the colors out of the Figma file", or points at a path ending in `.fig` — they almost never know it's a proprietary binary, so don't make them ask for "decoding" by name. Do NOT use for live figma.com URLs (that needs the browser/Figma API, not this skill) or for already-exported PNG/SVG/PDF assets (just read those directly).

End-to-end generator for a complete, playable, visually beautiful game built in one orchestrated multi-agent workflow. Use whenever the user wants a whole game from scratch — "build me a game", "make a 3D/2D/browser game", "generate a complete game", "single-shot a game", "vibe-code a game", or describes a game concept to turn into working software, especially when visual polish matters. The orchestrator writes an immutable contract plus a one-page art-direction style bible, fans the build across parallel implementers (dedicated world/structure/character/fx/lighting/audio art agents), runs a review/verify/fix gauntlet, then runs the game, captures screenshots, and iterates against an art-director judge until it looks great. Trigger even if the user never says "contract", "workflow", or "agents". Do NOT use for small edits to an existing game, a single mechanic or asset, engine/tooling questions, or non-game apps.

Prepare a greenfield codebase for fast, parallel, multi-agent implementation by writing an immutable CONTRACT first. Use this whenever the user wants to build a whole app, game, service, library, or system from scratch — "build me a full X", "implement this entire Y", "create a complete Z from scratch", "scaffold a new ..." — especially when you intend to fan the work out across multiple subagents or a Workflow. It produces four artifacts: a project scaffold with a typecheck gate, a single-source-of-truth type/interface contract, a pure-data config file, and a non-overlapping module decomposition with per-module specs — the groundwork that lets many implementers work in parallel without colliding. Trigger it even when the user never says "contract", "parallel", or "subagents": if the task is a sizable from-scratch build, this prep is what makes the build actually come together. Do NOT use it for small edits, single-file scripts, or work inside an existing codebase that already has its own structure.

Generate a C4-model architecture map of a codebase as Structurizr DSL (docs/c4/workspace.dsl) — Context / Container / Component levels — so the system is graspable at a glance. Reuses docs/wiki (workspaces → containers, server-communication → relationships) if present; bundles a Docker helper (c4.sh) to validate the DSL, view it live in the Structurizr UI, and export Mermaid to embed in the wiki or a PR. Stack-agnostic. Trigger: /to-c4.

Map an unfamiliar codebase into a fast, navigable local wiki (docs/wiki/) using parallel subagents. Built for the start of a live coding assessment on an UNKNOWN monorepo: discovers the stack, workspaces, conventions, server-communication style, testing setup, scope boundaries, and traces one reference feature end-to-end — so you can read the repo fluently and mirror its patterns. Pages carry YAML frontmatter with a per-source SHA1 freshness signal (detect + refresh stale pages after the code changes). Use at the very start, or whenever you are dropped into a strange repo and need a map before writing code. Trigger: /to-wiki.

TDD GREEN phase for ONE slice. With a failing test already in place (from /red), writes the MINIMAL implementation — the vertical walking skeleton (route → data → server/stub → render → mutation) — to make the slice's E2E pass, mirroring the repo's patterns and staying inside the editable scope. Does inner unit red→green cycles for pure logic. Commits the working feature. Second step of /red → /green → /refactor. Trigger: /green (optionally /green slice-X).

Final pre-submission gate + grading panel. First runs ALL the repo's real checks (typecheck, lint, format, unit, build, and the full E2E suite incl. regression) with no masking. Then spins one subagent per EVALUATED ASPECT — the FULL set the brief names (functional completeness, frontend fluency, monorepo awareness, convention consistency/pattern fidelity, code quality, server-communication & state/data-flow, testing, commit hygiene & history, scope & regression discipline, AI-leveraged understanding) — to grade with file:line evidence. Produces a scorecard + prioritized fixes + a go/no-go. Run before declaring a task done. Trigger: /presubmit.

TDD RED phase for ONE slice. Writes the failing acceptance test (the slice's happy-path E2E) for docs/slices/slice-X.md, meeting the assessment's test criteria (meaningful, mirrors repo conventions, strict assertions), and confirms it fails for the RIGHT reason before any code is written. Commits the failing test. First step of the controllable /red → /green → /refactor loop. Use to start a slice test-first. Trigger: /red (optionally /red slice-X).

TDD REFACTOR phase for ONE slice. With tests GREEN, improves the slice's code WITHOUT changing behavior so it adheres to the assessment rules: strict TypeScript (no any), lint-clean, mirrors the repo's conventions and the traced feature, reuses shared packages, no new deps, stays in scope. Keeps tests green after each step, then runs the full gate incl. the regression E2E suite. Commits the cleanup (skipped if nothing changed). Final step of /red → /green → /refactor. Trigger: /refactor (optionally /refactor slice-X).

Break an assessment task into ordered VERTICAL slices (walking skeletons), each independently testable end-to-end, written to docs/slices/slice-1.md, slice-2.md, … The user sets the rough slice count by task complexity. Each slice touches every architectural layer (route → data → server call/stub → render → mutation) and ships with its own happy-path E2E. Reads the codebase map from docs/wiki/ (run /to-wiki first) to mirror real patterns and respect scope. Plan-first: proposes the slice breakdown for sign-off BEFORE writing the slice docs. Trigger: /to-slices.

Create detailed implementation plans backed by research AND a mandatory clarification dialog. Before writing any plan content, every open question, undefined term, ambiguity, missing constraint, or scope edge must be resolved with a citation — an explicit user answer (recorded verbatim) or codebase/external evidence (file:line or doc URL). Plans built on assumptions or "reasonable defaults" are forbidden. The skill iterates a Q&A loop with the user until the open-question table has zero OPEN rows; in parallel, sub-agents research code- and external-answerable items. Produces a phased plan at docs/plans/ with SHA-tracked references and embeds the resolved questions table in the plan body as a permanent audit trail. TRIGGER on "create a plan", "plan the implementation", "write an implementation plan", "/plan", "plan this feature", "how should we implement". SKIP for trivial single-file edits, plans the user explicitly opts out of clarification on, or when the user provides a fully-specified plan and only asks f

Proof-based bug investigation. Forces explicit hypothesis formation, empirical verification with concrete evidence, 5 Whys root cause chain, falsification check, and a written investigation log at docs/investigations/ BEFORE any code change. Blocks speculative fixes — every hypothesis must be either PROVEN (with log lines, reproductions, file:line references, command output, or test output) or REJECTED (with a counterexample). Requires at least 3 hypotheses, at least 1 rejected, and a regression test before declaring the bug fixed. TRIGGER on phrases like "debug X", "why is X failing", "investigate this bug", "find the root cause of", "fix this error", "fix this bug", "X is broken", "X isn't working", "troubleshoot X", "what's wrong with X", "this is a bug", "regression in X", "/debug". SKIP only when the user has already proven the root cause themselves and is asking for the fix verbatim, or when the defect is a typo / syntax error the user has already pinpointed.

Analyze and address all review comments on a pull request. Fetches unresolved comments via GitHub GraphQL API, reads code context for each, evaluates validity, makes necessary changes or drafts polite responses. Also handles replying to PR threads with auto-linkable commit hashes. TRIGGER on "analyze PR comments", "address PR review", "resolve PR feedback", "check PR comments", "reply to PR review".

Manage C4-model documentation hierarchies with SHA-tracked source-file references and bottom-up staleness propagation. Use this skill whenever the user wants to audit doc/code drift, find stale documentation, sync docs after a refactor, scaffold a docs tree with init, check doc coverage, find orphan source files (code that no doc references), add a new code-level doc, regenerate aggregator overviews from leaves, or wire a pre-commit/CI doc-staleness gate. TRIGGER on phrases like "are docs stale", "doc coverage", "docs drifted", "init docs", "C4 docs", "fmk docs", "doc audit", "which docs need updating", "regenerate the container overview", "find uncovered files", "fmk-docs check", "fmk-docs orphans", or any mention of `docs/.fmk-docs.yml`. SKIP for prose-only docs with no source-file linkage, generated API reference docs (typedoc/sphinx), or single-file READMEs that don't follow C4 hierarchy.

Research codebase comprehensively and emit SHA-tracked, line-referenced research docs at docs/research/. Decomposes the user's question, spawns parallel sub-agents to investigate, synthesizes findings with concrete file:line references, computes git hash-object SHA for every referenced source file, and writes a YAML-frontmatter doc. If a doc with the same topic/slug already exists, UPDATES that doc instead of duplicating (refreshes SHAs, appends a Follow-up Research section). Companion to the `docs` plugin (C4 docs). TRIGGER on phrases like "research X", "investigate Y", "deep dive into Z", "how does X work in this codebase", "audit X", "explore the codebase for X", "/research". SKIP if the user only wants a quick answer with no doc artifact, or for non-codebase questions.