agent-ready-repo

Use this skill whenever you're implementing a non-trivial change -- a feature, a multi-file bug fix, a refactor, a migration, a framework or dependency upgrade, a schema or API change, performance work, an infrastructure or build-system edit, or anything spec-driven. Also triggered by argless resume phrases -- "resume", "continue", "keep going", "pick up where I left off", "let's get going" (bare phrases only; "resume the X project" or "resume the X investigation" routes to desk-research-project-status). It enforces the project's plan -> execute -> self-review -> fix loop with mechanical gates (lint, typecheck, tests) and adversarial review. Default to this skill for any task larger than a one-line edit.

Use when holding a raw signal (market observation, OKR gap, user pain pattern, engineering finding, competitive signal) at initiative or capability level — turning it into a typed finding, a Wardley capability maturity assessment, and an anchor into the PE six-step shaping sequence. Triggers on "frame this situation", "what do we do with this signal", "is this an opportunity or a risk", "where should we start", "map this to the shaping sequence". Do NOT use for a feature-scoped request (use `frame-intent`), testing an assumption (use `de-risk-intent`), or breaking down a shaped intent (use `decompose-intent`).

Use this skill when a session has surfaced a list of future work — follow-ons, review recommendations, audit remediation items, deferred scope — and you want to capture it into workspace.toml so a later session can pick it up cold. Triggers on "capture this", "add these to the queue", "capture these as queue items", "queue these up", "add this to the backlog" + a bulleted or numbered list in context. Do NOT use to turn unstructured external input into a product brief (use author-brief), to decompose a brief into specs (use receive-brief), or to orient at session start (use workspace-status).

Use this skill to orient at session start, check initiative queue state, or see what's ready to work on next. Reads workspace.toml and surfaces ready-to-start items, blocked items with reason, parallel candidates, and active signals. Triggers on "workspace status", "where am I", "orient me", "session start", "what's ready", "show the queue", "what's next", "what should I work on", "check workspace", or any cold-start orientation request. Offers to initialise workspace.toml if absent.

Use this skill when the user receives an externally-authored, multi-feature product brief -- a PRD, a solution handoff, a requirements packet -- and needs to turn it into shippable specs. Triggers on "receive a brief", "decompose this PRD", "we got a product brief", "break this handoff into specs". Elicits the load-bearing fields without mandating a schema, decomposes by shippability, and executes each slice through new-spec then work-loop. Do NOT use to author a single feature from scratch (use new-spec) or to record a decision (use new-adr).

Convert documents and images to Markdown for AI context layers. Documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, CSV/TSV, OpenDocument, .eml) go through `scripts/convert.py`, which extracts at a no-ML Tier-0 floor (pure-Python / stdlib parsers) and falls through to Docling (Tier 2) only for .xls and images; images go through a two-pass sliding-window vision pipeline whose tiling and reconciliation are deterministic (`scripts/split_image.py` and `scripts/reconcile.py`). Every output carries a versioned frontmatter contract (provenance + a quality/confidence signal). The agent's job is the per-tile vision read; tile dedup and ordering are handled by the script.

Use this skill when the user wants to start a new feature with a spec, or wants to write a spec for something they're about to build. Triggers on "new spec", "write a spec for X", "let's spec this out", "start a feature for...". Spec-driven development; the spec drives implementation. Do NOT use for cross-cutting proposals (use `new-rfc`) or recording decisions (use `new-adr`).

Load when a task's primary output is HTML, CSS, or JS. Provides design pre-flight, codified craft rules, and GATES verification commands for that surface.

Use when designing an analytical surface — a dashboard, a reporting view, a monitoring screen, or any surface whose primary purpose is to help a user understand a data set and act on it. Triggers on 'design the dashboard', 'structure the reporting view', 'what goes on the analytics screen', 'KPI layout', 'design a monitoring view'. Produces domain-model-first IA and widget hierarchy specifications. Scope boundary — individual chart encoding design is out of scope (use interaction-design for component state machines); this skill handles dashboard IA only. Do NOT use for marketing surfaces (use conversion-design) or workspace productivity surfaces (use workspace-design). Surface genre: analytical.

Use when designing a marketing surface — a landing page, product homepage, pricing page, or acquisition flow — where the primary goal is to convert a visitor into a lead, trial user, or customer. Triggers on 'design the landing page', 'structure the homepage', 'what goes above the fold', 'convert visitors', 'design the pricing page', 'product marketing surface'. Produces IA and structural specifications for conversion surfaces. Do NOT use for product UI design (use user-flow + interaction-design), documentation surfaces (use documentation-design), or analytical dashboards (use analytical-design). Surface genre: marketing.

Use when a design team needs shared, durable decision rules — converting journey-map insights and opportunity pains into 3–5 named principles that resolve design disputes and persist across sprints. Triggers on "what are our design principles", "how do we make design decisions consistently", "we keep relitigating the same tradeoffs", "write our design principles", "derive principles from this journey". Produces principles in the form [Imperative verb] + [what] + [why/for whom] with an arbitration test. Do NOT use to set visual direction (use `creative-direction`), to derive tokens or scales (use `design-system`), or to evaluate an existing screen (use `design-review`).

Use when designing a documentation surface — a docs site, a help centre, an API reference, or a technical guide set. Decides what type of content belongs where, how navigation scales with content volume, and what the first-value-moment is for each content type. Triggers on 'design the docs site', 'structure the help centre', 'what goes on the docs landing page', 'how should we navigate the API reference', 'TTFV for this tutorial'. Produces IA and navigation specifications for documentation surfaces. Do NOT use for marketing surfaces (use conversion-design) or informational editorial pages (use informational-design). Surface genre: documentation.

Use when designing an informational surface — an article page, a news or editorial page, a long-form content page, or a content-rich page whose primary purpose is to inform, not to convert or enable tasks. Triggers on 'design the article page', 'structure the editorial page', 'how should the blog look', 'long-form content design', 'reading experience design'. Uses typography as the primary design tool. Do NOT use for documentation (use documentation-design), marketing (use conversion-design), or tool/app surfaces (use workspace-design). Surface genre: informational.

Use when designing a marketplace surface — a catalogue, a listing grid, a product detail page, or a buying/transaction flow that connects buyers and sellers or producers and consumers. Triggers on 'design the marketplace', 'structure the listing page', 'how should the catalogue work', 'design the search and filter', 'buyer journey on the marketplace', 'product card design'. Produces IA specifications for catalogue, filter, comparison, and transaction bridge surfaces. Do NOT use for single-product marketing surfaces (use conversion-design) or workspace tool surfaces (use workspace-design). Surface genre: marketplace.

Use when designing a workspace surface — a productivity tool, a collaborative environment, an agentic UI, or any surface whose primary purpose is to support sustained professional work across sessions. Triggers on 'design the workspace', 'structure the tool UI', 'collaborative editing surface', 'agentic UI design', 'multi-agent coordination UI', 'task management surface', 'session arc design'. Covers context-persistence, collaboration state IA, ambient attention, agentic patterns, and interrupt design. Do NOT use for dashboards and monitoring views (use analytical-design) or marketplace surfaces (use marketplace-design). Surface genre: workspace.

Orient to the current desk-research project at a glance — reads overview.md and surfaces phase, working hypothesis, stop-signal verdict, and what to do next. Triggers on 'where are we on the X research', 'status of the Y investigation', 'resume the Z project', 'what phase is the research in', 'where did we leave off on the research', or any return-to-a-named-research-project phrasing. Read-only: never advances phase, never modifies any file.

Orient to the current design thread at a glance — reads design artifacts from the configured output directory and surfaces what exists, what's missing, and which skill to run next. Triggers on 'where are we with the design', 'what experience artifacts do we have', 'status of the design thread', 'what's next in the design', 'show me what design work exists', or any cold-start orient for the experience-design work thread. Read-only: never writes files, never elicits configuration.

Use this skill when the user asks to propose, draft, or open an RFC, OR when generating follow-on implementation artifacts (specs, ADRs) for an already-Accepted RFC. Triggers on "RFC", "propose a change to...", "let's get input on...", "draft a proposal", "create the follow-on specs for RFC-NNNN", "generate ADRs for the accepted RFC", "implement the follow-on work from an RFC". Do NOT use for recording a standalone architectural decision outside an RFC context (use `new-adr`), or for authoring a spec with no associated Accepted RFC (use `new-spec` for standalone spec authoring; for RFC follow-on work, invoke this skill first).

Use this skill when the user has unstructured external input (an email thread, a prose description, a Linear Issue, a stakeholder message) and needs to produce a DoR-compliant product brief and queue it in workspace.toml. Triggers on "author a brief", "write a brief from this email", "create a brief from this Linear issue", "intake this brief", "turn this into a brief". Do NOT use to decompose an existing brief into specs (use receive-brief) or to author a single feature from scratch (use new-spec).

Surface the current RFC landscape at a glance — how many RFCs are in each lifecycle state, which are active, and how many findings are waiting in the candidate register. Triggers on 'rfc status', 'show rfcs', 'what rfcs are open', 'rfc dashboard', 'how many rfcs', 'rfc candidates', 'rfc report', or any request for an overview of the RFC landscape. Read-only: never creates or modifies RFC files.

Use when a strategist needs to cascade company OKRs to team level and identify strategic gaps for the product-engineering shaping queue. Triggers on "run an OKR cascade", "I need to cascade company OKRs", "align team OKRs to company goals", "identify OKR gaps", "what are we missing to hit our objectives". Produces okr-cascade.md and workspace.toml shaping-queue entries. Do NOT use for per-feature goal-setting — cascade is org-wide alignment, not product backlog prioritization.

Use when a designer or product person needs to decide what a surface should say, for whom, in what form, and to what objective — before any wireframe or screen flow is opened. Routes across two surface types: acquisition surfaces (marketing pages, landing pages, web onboarding flows) and product/reference surfaces (help pages, feature reference, in-product wayfinding). Triggers on "what should this landing page say", "write a content brief for our onboarding flow", "what's the narrative arc for this marketing page", "what does this feature page need to communicate", "help me decide the above-fold structure". Do NOT use to write final copy (use `tone-of-voice` for copy voice, then `voice-and-microcopy` for UI strings), to produce an analytics or CRO measurement framework, or to generate SEO keyword plans.

Use when a designer, copywriter, or builder has a felt "copy vibe" but no named direction — turning a vague register sense into ranked copy goals grounded in stable referents (persona language, copy precedents, persuasion standards), and recording copy arbitration rules the rest of the build references. Triggers on "what voice should our copy have", "write a tone-of-voice doc", "how do we sound different from our competitors", "what should our hero headline feel like", "copy vibe check". Do NOT use for product UI copy states (error messages, empty states, button labels, form labels) — use `voice-and-microcopy` in the `product-engineering` pack for those. Do NOT use for SEO keyword targeting, advertising copy templates, or brand identity documentation.

Use to turn a raw product idea into a ratified, build-ready decision brief — the upstream discovery loop run by the discovery-lead agent. Triggers on "scaffold the product vision for X", "run a discovery for X", "diverge on the product shape then converge to a brief", "take this idea to a decision brief", "resume the X discovery". It diverges across candidate product shapes, converges the chosen one through a research/product/UX/architecture/safety lens roster, pauses at the consent gates (G0 vision, G1.5 altitude/MVP, G2 the "what"), emits a connected hypothesis with validation hooks, and hands off to work-loop at G3 — with no new engine, scheduler, or service. Do NOT use to build a spec (use new-spec → work-loop), to ship one (the release loop), or to author one discovery artifact standalone (use frame-intent / frame-domain / explore-options directly).

Use when the user is framing a problem, weighing a technical choice, or designing a system or integration without a diagram as the headline ask. Triggers on "how should we", "we need to", "what's the right way to build X", tech-selection, integration design, NFR trade-offs. Shapes a one-page concept first, then produces a Google-style design doc (TL;DR, context, goals/non-goals, proposal, alternatives, risks, rollout, open questions), 2-5 pages, with Mermaid inline, and converges it against review. Cloud well-architected by construction (AWS/Azure/GCP and primitives providers like Hetzner). Do NOT use when the ask is a diagram (use `architect-diagram`) or a critique (use `architect-review`).

Use when the user asks for a diagram of a system, integration, flow, state, data model, deployment topology, roadmap, prioritization matrix, or decomposition. Triggers on "show me", "draw", "diagram of", or artifact-shaped nouns like "sequence", "C4 Container view", "state machine", "roadmap", "2×2", "mind map", "branching strategy", "gantt", "sprint plan". Produces Mermaid diagrams (flowchart, sequenceDiagram, C4, stateDiagram-v2, erDiagram, gitGraph, gantt, plus timeline, quadrantChart, and mindmap for roadmaps, prioritization, and hierarchical decomposition) routed by intent. Cloud-aware (AWS, Azure, GCP, and primitives providers like Hetzner) and agentic-platform-aware (Bedrock AgentCore, AI Foundry, Vertex Agent Engine). Do NOT use for full design-doc drafting (use `architect-design`), critique (use `architect-review`), or comparison tables (use plain Markdown).

Start a stateful, multi-week research project — the lifecycle axis, orthogonal to the depth axis the `/research` skill carries. Triggers on explicit project-lifecycle phrasing — "start a research project", "set up a research project on X", "begin a sustained investigation", "open a research dossier" — never on a one-shot lookup. Scaffolds the three-layer project folder (overview.md + a raw sources/ layer + the later digest and synthesis), records the question and a possibly-empty working hypothesis, and sets phase to capture. Resolves output_dir: repo-scope agentbundle-layout.toml [research] output_dir first, then user-scope, then two-branch elicitation (repo vs personal workspace) — never a silent .context/ default. Prompt-only: phase is a frontmatter string the agent reads and writes; no engine, index, daemon, or counter. Does not replace /research — episodic quick/standard/applied/deep lookups stay there.

Use when a product team needs to understand how a customer moves through an experience end-to-end — mapping the stages, actions, emotions, pains, and opportunities along the path. Triggers on "map the customer journey", "what does the user go through", "journey map this flow", "map out the experience stages", "what are the customer touchpoints", "where does the user feel pain". Carries a platform/surface axis (responsive-web, iOS, Android, cross-platform) that changes what the method asks at each stage. Scoped to customer/end-user journeys only — employee journeys are out of v1. Do NOT use to design screen interactions (use `user-flow`), to blueprint the backing services (use `service-blueprint`), or to map an internal business process (use `process-mapping`).

Use when a team needs to understand, document, or improve how an internal business operation works — mapping an APQC L3 process end-to-end as a swimlane flow with as-is and to-be states, a SIPOC scoping table, and a pain/waste register. Triggers on "map our internal process", "document this business process", "what does our current process look like", "as-is to-be process", "process improvement", "how does this workflow actually work", "swimlane diagram for this process", "map the claims process", "map the order fulfilment flow". This is the inside-out operations sibling of `journey-mapping`. Do NOT use to map what a customer experiences (use `journey-mapping`), to blueprint how screens tie to backing services (use `service-blueprint`), or to sequence screen transitions (use `user-flow`). Does NOT carry a platform/surface axis — it is actor/swimlane-shaped, not device-shaped.

Use when you need to map the backing services that fulfil a customer journey — building a service blueprint with four rows (frontstage / line-of-visibility / backstage / support) that ties every screen action to the service or system behind it. Triggers on "service blueprint", "what backs this screen", "map the backstage", "what services support this journey", "blueprint the service". Do NOT use to map the customer journey itself (use `journey-mapping`), to sequence screens and their transitions (use `user-flow`), or to design system components (use `design-system`).

Use when a customer journey needs to become the screens that realize it — sequencing the screens, the transitions between them, and the error/edge flows (a failed action lands the user where?), then emitting one self-contained brief per screen. Triggers on map the screen flow, what screens do we need, sequence the screens for this journey, design the screen-to-screen flow, what happens when this action fails, turn this journey into screens. Carries a platform/surface axis and ends in a whole-journey walk that never skips. Do NOT use to map the journey itself (use journey-mapping), to design how one screen behaves internally (use interaction-design), or to blueprint the backing services (use service-blueprint).

Use at business-unit scale to stand up and keep current a value-stream meta-repo — a coordinating repo with no app code that holds the cross-component artifacts a polyrepo has nowhere else to put (the federated Backstage catalog, the shared-contract authority, the C4/bounded-context architecture, and the cross-component delivery rollup). Triggers on "set up a value-stream meta-repo", "coordinate across component repos", "stand up the cross-component catalog", "where does the shared contract live", "is this feature delivered across all the repos". Reads the per-component slices that decompose-intent produces and rolls up their delivery. Do NOT use at app scale (use decompose-intent — the leaf is one repo's brief) or to author an intent (use frame-intent).

Use when shaping a piece of product work before it becomes a spec — turning an idea, a request, or a strategy into a level-tagged `intent` (an outcome + the opportunity behind it). Triggers on "shape this", "what's the intent here", "frame the problem", "before we build X", "turn this into a brief/PRD". Authors an `intent` at any altitude in the open recognized set — product-vision, product-strategy, capability, or feature — resolves Scale (app ↔ business-unit) at intake, and offers current-state inputs only when brownfield. Do NOT use to test an assumption (use `de-risk-intent`) or to break an intent down (use `decompose-intent`).

Use when a strategist needs to set the organizational content direction before content design begins — the governance and structural layer above per-surface content execution. Triggers on "define the content strategy", "I need to set the content strategy before content design", "content governance framework", "Halvorson content strategy", "Purpose Process Structure Governance". Produces a committed content-strategy.md. Do NOT use to write per-surface content or microcopy — that belongs to the content-design skill in the experience-design pack.

Use when a strategist needs to set the experience direction before design begins — the bridge between business goals and what the designed product must achieve. Triggers on "define the UX strategy", "I need to set the experience strategy before design", "what should our UX strategy be", "align design to business goals", "set the experience vision". Produces a committed ux-strategy.md. Do NOT use to produce a customer journey map — that belongs to journey-mapping in the experience-design pack.

Use when a strategist needs to assess portfolio position and derive investment priorities across multiple products or business units. Triggers on "run a BCG matrix", "I need to assess portfolio position", "portfolio growth-share analysis", "which products should we invest in or cut", "star cash cow dog question mark". Produces a committed portfolio-position artifact. Do NOT use for single-product strategy — BCG requires at least two offerings to compare relative market share.

Use when a strategist needs to scan the macro environment before setting strategy or evaluating market entry. Triggers on "run a PESTLE", "I need to understand the macro environment", "political economic social analysis", "macro scan", "what external forces affect us". Produces a committed macro-environment artifact. Do NOT use as a substitute for current intelligence — PESTLE organizes and prioritizes information you supply; it does not generate market research.

Use when a strategist needs to understand the competitive dynamics of an industry before setting market positioning. Triggers on "run Porter's Five Forces", "I need to understand the competitive landscape", "map industry attractiveness", "how competitive is this market", "supplier and buyer power analysis". Produces a committed competitive-landscape artifact. Do NOT use for individual competitor profiling — this is an industry-structure analysis, not a competitor teardown.

Use when a strategist needs a structured situation synthesis before committing to a strategic direction. Triggers on "run a SWOT", "I need to understand our position", "situation synthesis before setting strategy", "what are our strengths and weaknesses", "map out opportunities and threats". Produces a committed SWOT artifact. Do NOT use as a substitute for market data — SWOT organizes what you know; it does not generate evidence you don't have.

Use when a strategist needs to turn existing stakeholder research into a strategic narrative organized by theme. Triggers on "synthesize stakeholder research", "I need to turn research into strategic direction", "what does the research tell us strategically", "consolidate stakeholder perspectives", "research synthesis for strategy". Requires existing research inputs — surfaces a diagnostic when none are found. Do NOT use to conduct research — this skill synthesizes; it does not interview, survey, or produce primary research.