spec-export

What this skill does

# Spec Export

Export pipeline that reads all sections from a structured-editor document, uses AI to map them into a ticket hierarchy (epic, stories, tasks), presents a preview for confirmation, and creates tickets in Linear or GitHub Issues via MCP. Created ticket IDs are stored back on document sections as external references.

The pipeline flow:

1. Read all sections from a structured-editor document
2. Use AI to map sections into a ticket hierarchy (epic -> stories -> tasks)
3. Present a preview of tickets to be created
4. User confirms -> tickets created via MCP tools (Linear or GitHub Issues)
5. Created ticket IDs stored back on sections as external references

## Prerequisites

- Next.js app with `src/` directory and App Router
- `ai-mcp` skill installed (provides MCP server connectivity for Linear/GitHub)
- `ai-tasks` skill installed (provides task management infrastructure)
- `structured-editor` skill installed (provides document + sections data model)
- `ai-core` skill installed (provides `getModel()`)
- Auth skill installed (provides `withAuth` from `@/lib/auth-guard`)
- shadcn/ui initialized

## Installation

```bash
bunx shadcn@latest add dialog radio-group checkbox progress
```

No additional npm packages required. Uses `ai`, `zod`, and existing infrastructure from prerequisite skills.

## What Gets Created

```
src/
├── lib/
│   └── spec-export/
│       ├── types.ts               # ExportTarget, TicketPreview, ExportResult types
│       ├── mapper.ts              # Maps document sections -> ticket hierarchy using AI
│       └── targets/
│           ├── linear.ts          # Linear-specific ticket format + MCP tool calls
│           └── github.ts          # GitHub Issues format + MCP tool calls
├── app/
│   └── api/
│       └── documents/
│           └── [documentId]/
│               └── export/
│                   ├── preview/
│                   │   └── route.ts   # POST — generates ticket preview from document
│                   └── execute/
│                       └── route.ts   # POST — creates tickets in target system
└── components/
    └── editor/
        ├── export-dialog.tsx      # Modal: target picker -> preview -> confirm -> progress
        └── export-button.tsx      # "Export to..." button that opens export dialog
```

## What Gets Modified

```
src/components/editor/document-editor.tsx   # Add export button to toolbar
```

## Setup Steps

### Step 1: Create `src/lib/spec-export/types.ts`

```typescript
export type ExportTarget = "linear" | "github";

export type TicketType = "epic" | "story" | "task";

export type TicketPreview = {
  id: string;
  type: TicketType;
  title: string;
  description: string;
  labels: string[];
  priority: "urgent" | "high" | "medium" | "low" | "none";
  parentId: string | null;
  sourceSectionId: string;
  sourceSectionType: string;
  acceptanceCriteria: string[];
};

export type ExportResult = {
  ticketId: string;
  externalId: string;
  externalUrl: string;
  status: "created" | "failed";
  error?: string;
};

export type ExportPreviewResponse = {
  target: ExportTarget;
  documentTitle: string;
  tickets: TicketPreview[];
  totalCount: number;
};

export type ExportExecuteRequest = {
  target: ExportTarget;
  tickets: TicketPreview[];
};

export type ExportExecuteResponse = {
  results: ExportResult[];
  successCount: number;
  failCount: number;
};
```

### Step 2: Create `src/lib/spec-export/mapper.ts`

```typescript
import { generateObject } from "ai";
import { getModel } from "@/lib/ai";
import { z } from "zod";
import type { TicketPreview } from "./types";

const ticketSchema = z.object({
  tickets: z.array(
    z.object({
      title: z.string(),
      type: z.enum(["epic", "story", "task"]),
      description: z.string(),
      labels: z.array(z.string()),
      priority: z.enum(["urgent", "high", "medium", "low", "none"]),
      parentIndex: z.number().nullable(),
      sourceSectionId: z.string(),
      sourceSectionType: z.string(),
      acceptanceCriteria: z.array(z.string()),
    })
  ),
});

type DocumentInput = {
  title: string;
  description: string | null;
};

type SectionInput = {
  id: string;
  type: string;
  title: string;
  content: unknown;
};

export async function mapDocumentToTickets(
  document: DocumentInput,
  sections: SectionInput[]
): Promise<TicketPreview[]> {
  const sectionSummary = sections
    .map(
      (s) =>
        `## ${s.title} (type: ${s.type}, id: ${s.id})\n${JSON.stringify(s.content, null, 2)}`
    )
    .join("\n\n");

  const result = await generateObject({
    model: getModel(),
    schema: ticketSchema,
    system: `You are a project management expert. Convert a feature specification into a ticket hierarchy.

Rules:
- Create exactly ONE epic for the overall feature
- Create stories for each user story in the spec
- Create tasks for each acceptance criterion, edge case, error state, and open question
- Tasks belong to their most relevant story (or directly to the epic if no story fits)
- Set priority based on importance signals in the text
- Add labels: section type, "edge-case", "error-handling", "question", etc.
- Keep titles concise (under 80 chars)
- Descriptions should include enough context to implement independently
- Include acceptance criteria from the spec on relevant stories
- For parentIndex, use the array index of the parent ticket (null for the epic)
- sourceSectionId must match one of the provided section IDs
- sourceSectionType must match the type of the source section`,
    prompt: `Feature: ${document.title}
${document.description ? `Description: ${document.description}` : ""}

Sections:
${sectionSummary}`,
  });

  return result.object.tickets.map((ticket, index) => ({
    id: `ticket-${index}`,
    type: ticket.type,
    title: ticket.title,
    description: ticket.description,
    labels: ticket.labels,
    priority: ticket.priority,
    parentId:
      ticket.parentIndex !== null ? `ticket-${ticket.parentIndex}` : null,
    sourceSectionId: ticket.sourceSectionId,
    sourceSectionType: ticket.sourceSectionType,
    acceptanceCriteria: ticket.acceptanceCriteria,
  }));
}
```

### Step 3: Create `src/lib/spec-export/targets/linear.ts`

```typescript
import type { TicketPreview, ExportResult } from "../types";

type LinearIssuePayload = {
  title: string;
  description: string;
  priority: number;
  labelNames: string[];
  parentId?: string;
};

export function formatLinearIssue(ticket: TicketPreview): LinearIssuePayload {
  const descriptionParts: string[] = [ticket.description];

  if (ticket.acceptanceCriteria.length > 0) {
    descriptionParts.push(
      `\n## Acceptance Criteria\n${ticket.acceptanceCriteria.map((c) => `- [ ] ${c}`).join("\n")}`
    );
  }

  return {
    title: ticket.title,
    description: descriptionParts.filter(Boolean).join("\n"),
    priority: mapPriority(ticket.priority),
    labelNames: ticket.labels,
  };
}

function mapPriority(priority: TicketPreview["priority"]): number {
  const map: Record<TicketPreview["priority"], number> = {
    urgent: 1,
    high: 2,
    medium: 3,
    low: 4,
    none: 0,
  };
  return map[priority];
}

type LinearCreateResponse = {
  id: string;
  url: string;
};

export async function createLinearTickets(
  tickets: TicketPreview[],
  mcpFetch: (toolName: string, args: Record<string, unknown>) => Promise<unknown>
): Promise<ExportResult[]> {
  const results: ExportResult[] = [];
  const idMap = new Map<string, string>();

  // Sort so epics are created first, then stories, then tasks
  const typeOrder: Record<string, number> = { epic: 0, story: 1, task: 2 };
  const sorted = [...tickets].sort(
    (a, b) => (typeOrder[a.type] ?? 2) - (typeOrder[b.type] ?? 2)
  );

  for (const ticket of sorted) {
    try {
      const payload = formatLinearIssue(ticket);

      // If this ticket has a parent, resolve the external ID
      if (ticket.parentId && idMap.has(ticket.parentId)) {
        payload.parentId = idMap.get(ticket.parentId);
      }

      const resp