digital-agency

Web development practice setup interview — detects or creates .agency/target.json binding, reads instance profile from `/agency-hub:setup`, interviews tech stack, deployment platform, connectors, and persona preference (six engineering personas vs merged), writes practice profile. Use on first install after `/agency-hub:setup`, when the user says "set up web development" or "bind target repo", or to redo engineering defaults only.

Use when the user wants to run a Ralph loop: an autonomous, self-referential delivery loop that drives a whole epic through implement, code review, fix, UX review, validate, commit, and merge request, one task per iteration, until a completion promise is emitted (ralph setup, ralph start), or to inspect or stop a running loop (ralph status, ralph cancel). Also supports simple ad-hoc loops that repeat a single prompt until done. Do NOT use to implement a single task once (implement), review a diff (code-review), or sign off an epic (validate) — the loop orchestrates those skills.

Use when the user wants a UX/design review of implemented UI — frontend components, pages, or flows — against the design source of truth (Figma via MCP, mockups, tokens, or style guide, whatever the repo provides), covering design fidelity, accessibility (WCAG 2.2 AA), interaction states, responsiveness, and design-system conformity; or to address UX review findings (ux-design-review fix, optionally scoped to an action tier). Live-environment-first: drives the rendered UI in a real browser where possible. Works with any framework or design tooling. Do NOT use for code correctness/security review (code-review), to review a design.md document (design), or to implement features (implement).

Use when the user is the reviewer of a merge request or pull request and wants it reviewed and the verdict published to the provider — inline comments on the right lines, threads resolved or replied to, and an approve / request-changes / comment decision. Handles first reviews and re-review rounds after the author pushes. Works with any codebase and any git provider — GitHub, GitLab, or Bitbucket — using MCP tools where available, provider CLIs otherwise. Do NOT use to review your own working diff before opening an MR (code-review), to open or babysit an MR (merge-request), or to implement changes (implement).

Use when the user wants to open a merge request or pull request for the current branch (merge-request create — the default — with a generated title, description, labels, and reviewer suggestions), or to babysit an open MR/PR to a merge-ready state (merge-request babysit) by watching CI, review comments, and merge conflicts. Works with any codebase and any git provider — GitHub, GitLab, or Bitbucket — using MCP tools where available, provider CLIs otherwise, and plain git as a last resort. Do NOT use to review code or an MR as its reviewer (code-review, merge-request-review) or to implement changes (implement).

Use when the user wants a code review of a branch, PR, or diff against its acceptance criteria and declared scope (whatever form they take in this repo), or to address review feedback without changing behaviour (code-review fix, optionally scoped to a blocking or warning action tier). Works with any language, delivery process, or issue tracker. Do NOT use to implement code, sign off completion of a larger body of work, or review rendered UI/UX (design fidelity, accessibility — use ux-design-review).

Use when the user wants to implement a task in code against approved design.md and .agency/work/{epic}/tasks.md. Do NOT use for code review (code-review), address review feedback (code-review fix), writing tasks (tasks), or design (design write).

Use when the user wants to write, review, or refine the product backlog, decompose delivery into epics, set Now-phase scope, or manage epic rows (e.g. CHK01). Default artefact .agency/backlog.md. Do NOT use for business strategy or PRD (product), phase exit criteria (roadmap), Gherkin tasks (tasks), epic design.md (design), architecture (solution), sprint retro (sprint), or pre-sprint doc alignment (docs). Task breakdown per epic lives at .agency/work/{epic}/ via tasks.

Use when the user wants a product strategy doc, PRD, pitch, vision, personas, or outcomes at .agency/product.md (write, review, refine). Do NOT use for phased delivery plan (roadmap), epics or backlog (backlog), architecture (solution), tasks or Gherkin (tasks), or implementation (implement).

Use when the user wants outcome-based delivery phases, exit criteria, or roadmap review at .agency/roadmap.md. Requires product.md for write. Do NOT use for epic breakdown or work paths (backlog), PRD (product), per-epic design (design), tasks (tasks), or architecture detail (solution).

Use when the user asks which skill to use, how to start delivery, or what to do next without naming a skill. Routes to product, backlog, tasks, design, etc. Do NOT produce artefacts or implement code — only recommend skill and mode.

Use when the user wants a sprint plan before the sprint or a retrospective after, under .agency/sprints/sprint-{id}/plan.md or retrospective.md. Do NOT use for product strategy (product), task Gherkin (tasks), epic doc refine pass (docs refine), or epic validation (validate).

Use when the user wants to break an epic into tasks.md, write Gherkin acceptance criteria, refine sprint-ready tasks, or review task breakdown for an epic (checkout-foundation, CHK01, etc.). Default .agency/work/{epic}/tasks.md. Do NOT use for epic list or work paths (backlog), product backlog stories only (backlog), design.md (design), code implementation (implement), PR code review (code-review), or epic completion sign-off (validate). EARS with --ears.

Use when the user wants final epic completion sign-off: every task in .agency/work/{epic}/tasks.md verified against Gherkin AC and roadmap phase exit criteria. Pass epic slug or ID. Do NOT use for PR or branch code review (code-review), writing tasks (tasks), or sprint retrospective (sprint). Not for drafting backlog or design.

Use when the user wants to write, review, or refine system architecture at .agency/architecture/solution.md (stub or full arc42-lite). Do NOT use for business strategy (product), delivery phases (roadmap), epic list (backlog), per-epic design.md (design), task Gherkin (tasks), or ADR files (adr write). Story AC belongs in .agency/work/{epic}/tasks.md.

Instance bootstrap interview — detects existing instance state, guides repo creation (link-first), interviews business identity/services/cadence/targets, writes config/instance.json and target skeletons, then hands off to brand-creative setup. Use on first install, when the user says "set up my instance" or "bootstrap my agency workspace", or to re-run integration checks after adding MCP connectors.

Use when reviewing content seed PRs for SEO — titles, meta descriptions, heading structure, keyword usage, and internal linking opportunities. Produces PR review comments. Do NOT use for technical site audits (technical-seo-audit) or drafting content (/content-marketing:draft-post).

Use when researching keywords for a topic area — search intent, volume signals, and content opportunities. Output at .agency/work/seo/keyword-research-{topic}.md on the target repo. Do NOT use for technical site audits (technical-seo-audit) or competitive product analysis (/delivery-practice:competitive-brief).

Use when auditing production SEO — metadata, canonical/OG, sitemap, robots, structured data, and Core Web Vitals signals. Creates GitHub issues labelled type:seo-recommendation with owning squad. Do NOT implement fixes — hand to engineering squads.

Use when producing a low-fidelity layout and interaction spec from a brief. Output at `<design-dir>/{page-or-flow}.md`. Resolve `<design-dir>` per ux-design-conventions.md. Reads brand-guide.md when present. Do NOT use for epic technical design (web-development:design), visual brand tokens (brand-creative:brand-guide), or code implementation (web-development:implement).

Use when the user wants ADR register planning, writing ADR-NNNN files, or ADR review under .agency/architecture/decisions/. Do NOT use for full architecture narrative (solution), epic design (design), or product strategy (product). Proposals stay in register.md only until accepted.

Use when the user wants epic-level technical design at .agency/work/{epic}/design.md, walking-skeleton or TDD design, or design review before tasks. Pass epic slug or ID (CHK01). Cite solution.md — do not re-narrate architecture. Do NOT use for product backlog or epics (backlog), task Gherkin (tasks), system-wide architecture (solution), ADR write (adr), code implementation (implement), or doc-only sprint-end pass (docs refine).

Use for pre-sprint documentation alignment (review) or sprint-end epic documentation pass (refine) — product, solution, and .agency/work/{epic}/design.md. Produces refine-session.md on refine. Do NOT use for sprint retrospective (sprint retrospective), epic validation against AC (validate), writing backlog (backlog), or initial architecture (solution write). Not a substitute for code review (code-review).

Use when structuring reproducible defect reports from failed QA output — automated suite failures, exploratory gaps, or combined validation results. Do NOT use to fix code (implement) or re-run tests (run-automated-suite).

Use when performing acceptance-criteria-driven exploratory validation in a prepared QA workspace — manual-style checks, browser verification, or CLI probes against tasks.md Gherkin. Do NOT use for automated tests only (run-automated-suite) or defect formatting (document-defects).

Use when the user wants a final technical gate on an open PR or MR after peer review — architecture boundaries, security, and acceptance-criteria coverage against .agency/work/{epic}/tasks.md. Do NOT use for pre-PR peer review (code-review), business stakeholder sign-off (validate), or implementation (implement).

Use when running the project's automated test suite in a prepared QA workspace. Do NOT use for workspace setup (deploy-qa), manual AC checks (exploratory-pass), or fixing failures (implement).

Cut a release of one or more digital-agency plugins — run plugin-check, validate, and test gates, bump per-plugin version(s), update CHANGELOG.md, and tag. Use when shipping a new or changed practice plugin, connector, or skill to the marketplace, or when the user asks to "cut a release", "ship this plugin", or "tag a version".

Content marketing practice setup interview — reads instance business identity and house tone hints from `/agency-hub:setup`, interviews content cadence, primary channels, distribution connectors, and persona preference (Content Strategist vs Content Writer vs merged), writes practice profile. Use on first install after `/agency-hub:setup`, when the user says "set up content" or "configure editorial calendar", or to redo content defaults only.

Delivery practice setup interview — reads instance cadence and risk posture from `/agency-hub:setup`, interviews reporting format, escalation model, and persona preference (Product Manager vs Delivery Lead vs merged), writes practice profile. Use on first install after `/agency-hub:setup`, when the user says "set up delivery" or "configure sprint cadence", or to redo delivery defaults only.

Use when investigating bugs, errors, or unexpected behavior — reproduce, isolate, diagnose, and fix. Trigger with an error message, stack trace, "works in staging but not prod", or "broke after deploy". Do NOT use for incident response workflows, code review (code-review), or implementation (implement).

Use when preparing a QA workspace — checkout a branch or MR ref, install dependencies, and verify the environment is ready for test execution. Do NOT use for running tests (run-automated-suite), exploratory validation (exploratory-pass), or fixing code (implement).

Use when auditing platform health — dependency updates, uptime, error rates, CI status, and deployment hygiene. Trigger for "dependency audit", "check Sentry errors", "platform health review", or scheduled maintenance. Do NOT use for feature implementation (implement) or debugging a single bug (debug).

Use when identifying, categorizing, and prioritizing technical debt — "tech debt audit", "what should we refactor", "code health", or refactoring priorities. Do NOT use for code review (code-review), architecture decisions (adr), or bug investigation (debug).

Use when analysing image or video media for structured tags: subjects, season, mood, content type, alt text, description, quality score. Reads brand and taxonomy from resolved brand path. Do NOT use for writing captions (write-captions) or selecting posts (curate-content).

Use when selecting the best assets to post next from an approved media inventory. Reads brand from instance repo config. Do NOT use for analysing single images (analyse-media) or writing captions (write-captions).

Use when drafting a blog post seed JSON for CMS import. Output at the target repo's resolved post seed path with body as markdown. Match brand-voice.md before finishing. Do NOT merge or publish — seed PR only.

Use when drafting a recipe seed JSON for CMS import. Output at the target repo's resolved recipe seed path. Include structured-data fields (times, servings, difficulty). Match brand-voice.md before finishing. Do NOT merge or publish — seed PR only.

Use when reviewing caption variants and selecting or lightly editing the best one for publication. Reads brand voice from instance repo config. Does not append hashtags. Do NOT use for initial caption generation (write-captions).

Use when writing Instagram caption variants and channel copy from media tags or analysis output. Reads brand from instance repo config. Do NOT use for selecting the final caption (edit-content) or vision analysis (analyse-media).