skills-monorepo

Activate when the project has a .backlog/ directory, or when the user discusses tasks, backlog, ideas, reports, bugs, or learnings. Provides contextual awareness of the flowstate backlog management system.

Generate a Changesets entry and commit it, for Changesets-managed monorepos. Use when the user says "changeset", "add changeset", needs to record a package version bump, or finishes work that should ship in the next release. Detects modified packages from staged files, picks major/minor/patch from the diff, and leaves `changeset version` to CI. Do NOT use for single-package repos or repos without a `.changeset/` directory.

Audit project docs (README, CLAUDE.md, AGENTS.md, package READMEs, docs/) for content drift AND structural fit — versions, commands, paths, examples and instructions out of sync with the code, plus a 3-tier layout check (rules stay terse, READMEs stay human, deep docs live under docs/). Use when the user says "check docs", "are the docs up to date?", after significant code changes, or before a release. Reports content + structural issues; defers markdown style/formatting to a linter. Monorepo-aware.

Create a git commit following Conventional Commits. Use when the user says "commit", "commit these changes", has finished a logical unit of work, or wants to save progress to git. Analyzes the staged diff to infer type/scope, scans for secrets and sensitive files, warns before committing to main/master, and never bypasses hooks without permission.

Review a GitHub pull request with specialized agents running in parallel (code quality, security, QA, architecture as needed). Use when the user says "review PR", "review this pull request", "/review-pr", pastes a GitHub PR URL, or finishes a branch and wants feedback before merge. Fetches diff via `gh`, checks CI status, produces a structured report with risk matrix and merge recommendation. Requires GitHub CLI authenticated.

Document a learning or insight discovered during development. Use when the user says "learned something", "TIL", "note this", "remember this for next time", or when a non-obvious discovery is made while working.

Interactively groom and add a new task to the backlog. Use when the user wants to add work, create a ticket, file a TODO, track a feature request, or says "add task", "new task", "I need to do X".

Verify that a task's declared status matches the actual codebase implementation. Use when the user says "check task status", "verify implementation", or during backlog health checks. Supports single-task and batch mode.

Mark a task as completed and move it to done. Use when the user finishes work, says "done with task", "complete task", "mark as done", or when all acceptance criteria are met.

Generate a detailed implementation plan for a feature or change before coding begins. Use when the user says "plan this", "how should we implement", "design approach", or when a task needs architectural thinking.

Analyze the backlog and recommend the best task to start next, or up to 3 tasks if they can run in parallel. Use when the user asks "what should I work on?", "next task", "what's the priority?", or needs help deciding between multiple pending items.

Show a comprehensive backlog overview with stats, active work, and health warnings. Use when the user asks "backlog status", "what's going on", "show tasks", "project overview", or wants to see the current state of all work.

Execute multiple independent backlog tasks simultaneously using subagents with worktree isolation. Use when the user says "run tasks in parallel", "do these at the same time", or when multiple non-overlapping tasks can be worked on concurrently.

Review a pending plan and decide — approve (convert to task), discard, or revise. Use when the user says "review plan", "approve plan", "check the plan", or after generating a plan with /flowstate:idea.

Initialize the .backlog/ directory structure in the current project. Use when starting a new project, setting up backlog management, or when the user says "set up flowstate", "create backlog", or "initialize tracking". Idempotent.

Start working on a task by moving it from pending to active. Use when the user says "start task", "begin working on", "pick up task", or wants to begin implementing something from the backlog.

Triage a pending report by converting it to a task, discarding it, or requesting more info. Use when the user says "triage report", "handle this bug", "convert to task", or when pending reports need attention.

Scaffold a complete new plugin in this monorepo — directory structure, plugin.json, package.json (zero-dep, ESM), shared tsconfig, vitest, optional CLI skeleton, marketplace entry, first build, and validation. Use when the user says "new plugin", "scaffold a plugin", "add a plugin to the marketplace", or "create plugin <name>". Do NOT use for adding a skill to an existing plugin (use new-skill).

Scaffold a new skill inside an existing plugin (flowstate or dev-workflow) following house conventions — frontmatter, model tiering, trigger-rich description, CLI-mutates/skill-orchestrates split, README table, validation. Use when the user says "add a skill", "new skill", "create a slash command", or "scaffold a skill for <plugin>". Do NOT use for a whole new plugin (use new-plugin) or for project-local .claude/skills.

Run the full release flow for a plugin in this monorepo — preflight checks, version bump, release commit, tag, push, and post-release verification. Use when the user says "release flowstate", "cut a release", "ship a new version", "bump and tag", or "publish dev-workflow". Do NOT use for changesets in other repos (that's dev-workflow:changeset) or for committing regular work.

Condense the learnings backlog: dedupe, normalize tags, archive stale entries, then caveman-compress the body of every remaining active learning. Validated against load-bearing invariants. Use when the user says "condense learnings", "clean up learnings", "deduplicate learnings", or "organize learnings".

Condense completed tasks: structural trim (drop Notes scratchpad, prune middle Progress Log) plus caveman-style prose compression (drop articles, filler, hedging) on remaining body. Validated against load-bearing invariants. Use when the user says "condense tasks", "clean up done tasks", "trim completed backlog", or wants to shrink the size of complete task files.

Browse and search the learnings index for relevant past insights. Use when the user says "check learnings", "what did we learn about", "search knowledge", or at the start of a work session to review insights.

File a structured bug report, finding, or security issue. Use when the user discovers a bug, says "found a bug", "report issue", "file a finding", "security concern", or when something unexpected is observed.

Mark a task as blocked with a documented reason. Use when the user hits a dependency, external blocker, or technical limitation — says "blocked by", "can't proceed", "waiting for", "stuck on".