/**
 * Per-flow copy for the Orchestrator flow launcher.
 *
 * - `oneliner` is the flow's own backend `description` (see
 *   apps/coder/src/conductor/flows/*), shown always-on under the flow name.
 * - `blurb` is a 1–2 sentence expansion (what it does + when to use, plus a
 *   "not for…" clause where the underlying Han skill has one), condensed from
 *   each Han skill's SKILL.md frontmatter `description` in /opt/skills/han/<name>.
 *   For the four bespoke flows with no Han skill (security-review, data-review,
 *   devops-review, stakeholder-summary) and the two empty SKILL.md files
 *   (runbook, test-planning) the blurb is condensed from the flow definition.
 *
 * Keyed by flow name — keep in sync with apps/coder/src/conductor/flows.
 */
export interface FlowInfo {
  /** Always-on one-liner (the flow's backend `description`). */
  oneliner: string;
  /** Expanded 1–2 sentence blurb: what it does + when to use / not. */
  blurb: string;
}

export const FLOW_INFO: Record<string, FlowInfo> = {
  // ── Analysis ──────────────────────────────────────────────────────────
  research: {
    oneliner: 'options, prior art, trade-offs → recommendation',
    blurb:
      'Surveys options, prior art, and trade-offs across the codebase, the web, and any material you provide, then recommends a direction backed by checkable evidence. Use to weigh approaches or understand how something works before committing — not to diagnose a bug (use Investigate) or compare two concrete artifacts (use Gap Analysis).',
  },
  investigate: {
    oneliner: 'root-cause a bug/failure from evidence',
    blurb:
      'An evidence-based deep dive that traces a bug, failure, or integration issue to its root cause and adversarially validates the proposed fix. Use to debug, troubleshoot, or diagnose why something is broken — not to audit code quality (use Code Review) or assess architecture (use Architectural Analysis).',
  },
  'architectural-analysis': {
    oneliner: 'structure + behaviour + concurrency → architecture synthesis',
    blurb:
      'Assesses an existing module or feature across structural coupling, data flow, concurrency, risk, and SOLID alignment, then synthesises recommended changes. Use to evaluate the design quality, dependency structure, or technical debt of a specific area — not to investigate a bug (use Investigate) or review code line-by-line (use Code Review).',
  },
  'security-review': {
    oneliner: 'adversarial security analysis (exploit-path proof standard)',
    blurb:
      'An adversarial hunt for real, exploitable vulnerabilities — every finding needs a file:line plus a demonstrated exploit path or a CVE, never a theoretical risk. At medium and above it also flags code-level resilience failures such as missing timeouts, swallowed errors, and unbounded results.',
  },
  'gap-analysis': {
    oneliner: 'gaps between two artifacts (impl vs spec, etc.)',
    blurb:
      'Compares a current state against a desired one (implementation vs spec, PRD vs shipped feature, design vs build) and reports what is missing, incomplete, conflicting, or assumed. Use to reconcile two artifacts — not to investigate a runtime bug (use Investigate) or assess architecture (use Architectural Analysis).',
  },
  'data-review': {
    oneliner: 'schema / query / data-access audit',
    blurb:
      'Audits schemas, migrations, queries, and data-access code against normalization, indexing strategy, access patterns, migration safety, and PII/regulated-data handling, citing each location and its data-level impact. Use before shipping schema or query changes.',
  },
  'devops-review': {
    oneliner: 'production-readiness / operability review',
    blurb:
      'Checks a change or feature for production readiness — twelve-factor concerns, observability via the four golden signals, rollout safety, secrets/PII handling, scale, and cost — citing each location and its blast radius. At medium and above it adds a code-level resilience pass.',
  },
  'issue-triage': {
    oneliner: 'assess + prioritise a reported issue',
    blurb:
      'Turns a raw, vague issue or bug report into a structured document naming what is known, what is missing, severity, and reproducibility, then recommends the right next step. Use to prep an incoming issue for work — not to find root causes (use Investigate) or plan a build (use a Planning flow).',
  },

  // ── Discovery ─────────────────────────────────────────────────────────
  'project-discovery': {
    oneliner: 'discover a repo: stack, structure, tooling',
    blurb:
      'Scans a repository and reports its languages, frameworks, build and test tooling, configuration, entry points, and directory structure as a map a newcomer could navigate. Use to detect a project’s tech stack and layout — not to write feature docs (use Project Documentation).',
  },
  'project-documentation': {
    oneliner: 'draft docs for a feature/system (one-pass)',
    blurb:
      'Drafts clear documentation for a feature, system, or component, grounded in the real implementation so every claim traces to evidence. Use to document how something works — not to scan the tech stack (use Project Discovery), record a decision (use ADR), or write a standard (use Coding Standard).',
  },
  'test-planning': {
    oneliner: 'behaviour-focused test plan',
    blurb:
      'Produces a prioritised, behaviour-focused test plan — observable inputs/outputs and collaborator interactions, recommended test doubles and test levels — rather than internal code paths. At medium and above it catalogs the edge cases and boundary values the plan must cover. Use to plan tests, not to write them (use TDD).',
  },

  // ── Planning ──────────────────────────────────────────────────────────
  'plan-a-feature': {
    oneliner: 'feature spec draft (one-pass; human-in-loop intended)',
    blurb:
      'Builds a first-draft feature specification — the problem, the user, in/out of scope, acceptance criteria, a build approach, and open questions — grounded in the codebase. Use to scope or design a new capability before implementation — not to refine an existing plan (use Iterative Plan Review) or document a built feature (use Project Documentation).',
  },
  'plan-implementation': {
    oneliner: 'implementation plan draft (one-pass)',
    blurb:
      'Turns a feature specification into an implementation blueprint — the specific files to create or modify, component designs, data flow, an ordered build sequence, and a test strategy. Use once behaviour is specified — not to decide what the feature should do (use Plan a Feature) or review code (use Code Review).',
  },
  'plan-a-phased-build': {
    oneliner: 'phased build plan draft (one-pass)',
    blurb:
      'Splits an initiative into a sequence of independently shippable, vertical-slice phases — each with a goal, its slice of work, dependencies, and a demoable outcome a real person can be shown. Use to sequence or roadmap a build — not for implementation detail (use Plan Implementation).',
  },
  'plan-work-items': {
    oneliner: 'break work into tracked items (one-pass)',
    blurb:
      'Breaks a trusted implementation plan into independently-grabbable, atomic work items — each with a title, a one-line outcome, dependencies, and a rough size, ordered by dependency. Use to convert a plan into tickets — not when there is no trusted plan yet (produce one with Plan Implementation first).',
  },
  'iterative-plan-review': {
    oneliner: 'stress-test an existing plan (one pass of the loop)',
    blurb:
      'Stress-tests an existing plan against the codebase — surfacing hidden assumptions, unstated prerequisites, muddied scope, and risk — to sharpen it before commitment. Use to refine, tighten, or verify the soundness of a plan — not to generate one from scratch (use a Planning flow) or implement it.',
  },

  // ── Authoring ─────────────────────────────────────────────────────────
  adr: {
    oneliner: 'architecture decision record draft (one-pass)',
    blurb:
      'Drafts an Architecture Decision Record — Context, the Decision, the Options considered with trade-offs, Consequences, and status — grounded in the real constraints. Use to record or update an architecture or design decision — not to write an enforceable standard (use Coding Standard) or feature docs (use Project Documentation).',
  },
  'coding-standard': {
    oneliner: 'coding standard draft (one-pass)',
    blurb:
      'Drafts an enforceable coding standard — the rule stated imperatively, the failure it prevents, a correct and an incorrect example, and its scope. Use to create or update a convention — not to record a one-off decision (use ADR) or write feature documentation (use Project Documentation).',
  },
  runbook: {
    oneliner: 'operational runbook draft (one-pass)',
    blurb:
      'Drafts an operational runbook for an incident scenario — detection signals, immediate mitigation, the diagnosis path, rollback/recovery, and escalation, with concrete commands where known. At medium and above it adds the failure modes and earliest signals the runbook must cover.',
  },
  tdd: {
    oneliner: 'failing-test scaffold + plan (one-pass; not the full red-green loop)',
    blurb:
      'Writes the failing ("red") tests that specify a behaviour — observable inputs/outputs and collaborator interactions — and outlines the smallest implementation that would make them pass. A single pass, not the full interactive red-green-refactor loop. Use to drive code test-first — not to produce a test plan document (use Test Planning).',
  },
  'stakeholder-summary': {
    oneliner: 'plain-language stakeholder summary (Han reporting)',
    blurb:
      'Writes a plain-language summary of a feature or piece of work for a non-technical stakeholder — what it is, why it matters, what changes for users, and the rough shape of the effort. No jargon, no implementation detail.',
  },

  // ── Review ────────────────────────────────────────────────────────────
  'code-review': {
    oneliner: 'per-dimension review → adversarially verify each dimension (drops false positives)',
    blurb:
      'Reviews changed code across multiple dimensions — correctness, structure, security, resilience, and concurrency — then adversarially verifies each finding so false positives are dropped before the report. Use to audit code quality, correctness, or security — not to analyse architecture (use Architectural Analysis) or investigate a bug (use Investigate).',
  },
};