Skip to content

wrsmith108/linear-claude-skill

Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.

FileKindSize
SKILL.mdskill md22.7 KB
scripts/__tests__/bulk-create.test.tsscript5.0 KB
scripts/__tests__/issue-description.test.tsscript6.8 KB
scripts/__tests__/lin-cli.test.tsscript3.8 KB
scripts/__tests__/lint-issues.test.tsscript2.3 KB
scripts/__tests__/retry.test.tsscript8.2 KB
scripts/__tests__/smoke.test.tsscript7.0 KB
scripts/__tests__/validate-description.test.tsscript4.3 KB
scripts/build.mjsscript1.4 KB
scripts/bulk-create.tsscript12.5 KB
scripts/create-initiative-update.tsscript5.8 KB
scripts/create-issue-with-project.tsscript8.0 KB
scripts/create-project-update.tsscript5.5 KB
scripts/extract-image.tsscript2.2 KB
scripts/lib/agent-selection.tsscript8.7 KB
scripts/lib/exit-codes.tsscript357 B
scripts/lib/index.tsscript3.1 KB
scripts/lib/initiative.tsscript5.0 KB
scripts/lib/issue-description.tsscript7.1 KB
scripts/lib/labels.tsscript7.6 KB
scripts/lib/lin-cli.tsscript7.3 KB
scripts/lib/linear-utils.tsscript9.3 KB
scripts/lib/project-template.tsscript8.8 KB
scripts/lib/retry.tsscript4.8 KB
scripts/lib/taxonomy-data.tsscript8.1 KB
scripts/lib/taxonomy-validation.tsscript10.0 KB
scripts/lib/taxonomy.tsscript3.6 KB
scripts/lib/verify.tsscript6.6 KB
scripts/linear-api.mjsexecutablescript12.1 KB
scripts/linear-ops.tsscript69.1 KB
scripts/lint-issues.tsscript6.9 KB
scripts/phase-complete.tsscript12.4 KB
scripts/query.shexecutablescript498 B
scripts/query.tsscript3.5 KB
scripts/run.shexecutablescript321 B
scripts/setup.tsscript8.6 KB
scripts/sync-skill-version.mjsscript2.0 KB
scripts/sync.tsscript5.7 KB
scripts/upload-image.tsscript4.4 KB

scripts/lib/issue-description.ts

View on GitHub
/**
 * Issue Description Validation
 *
 * Enforces that every new Linear issue has a detailed description with a
 * populated Acceptance Criteria section. Mirrors the taxonomy-validation.ts
 * pattern: a pure validator returning {valid, errors, warnings}.
 */

/** Minimum body length (excluding heading lines). */
export const MIN_BODY_CHARS = 120

/** Minimum number of non-placeholder acceptance-criteria bullets. */
export const MIN_AC_ITEMS = 2

/** Matches `# Acceptance Criteria` through `###### Acceptance Criteria`. */
const AC_HEADING_RE = /^#{1,6}\s+Acceptance Criteria\b.*$/im

/** A checkbox/bullet whose body is empty or a common placeholder. */
const PLACEHOLDER_RE = /^\s*(TODO|FIXME|TBD|TBA|N\/A|XXX|\?+|<[^>]*>|\.\.\.|-{2,}|_{2,})\s*$/i

export interface DescriptionValidationResult {
  valid: boolean
  errors: string[]
  warnings: string[]
}

/**
 * Validate an issue description against the acceptance-criteria contract.
 *
 * Rules (all required for valid=true):
 *   1. Non-empty after trim.
 *   2. At least MIN_BODY_CHARS characters of body (headings excluded).
 *   3. Contains an "Acceptance Criteria" heading (H1-H6).
 *   4. At least MIN_AC_ITEMS non-placeholder bulleted items under that heading.
 */
export function validateIssueDescription(description: string): DescriptionValidationResult {
  const errors: string[] = []
  const warnings: string[] = []

  const trimmed = (description ?? '').trim()

  if (trimmed.length === 0) {
    errors.push('Description is empty. Use `--template` to print a starter template.')
    return { valid: false, errors, warnings }
  }

  // Rule 2: body length (strip heading lines before counting)
  const bodyChars = trimmed
    .split(/\r?\n/)
    .filter(line => !/^\s*#{1,6}\s/.test(line))
    .join('\n')
    .length
  if (bodyChars < MIN_BODY_CHARS) {
    errors.push(
      `Description body is ${bodyChars} chars; minimum is ${MIN_BODY_CHARS}. ` +
      `Explain what is changing and why, not just the title.`
    )
  }

  // Rule 3: Acceptance Criteria heading
  const acHeadingMatch = trimmed.match(AC_HEADING_RE)
  if (!acHeadingMatch) {
    errors.push(
      'Acceptance Criteria heading missing. Add a "## Acceptance Criteria" ' +
      'section with a checklist of testable outcomes.'
    )
    // Can't check rule 4 without a heading; still surface warnings below.
  } else {
    // Rule 4: count non-placeholder bullets under the heading
    const lines = trimmed.split(/\r?\n/)
    const headingIdx = lines.findIndex(l => AC_HEADING_RE.test(l))
    const acItems: string[] = []
    for (let i = headingIdx + 1; i < lines.length; i++) {
      const line = lines[i]
      if (/^#{1,6}\s/.test(line)) break // next heading ends the section
      const bullet = line.match(/^\s*(?:-|\*)\s+(?:\[[ xX]\]\s+)?(.*)$/)
      if (!bullet) continue
      const body = bullet[1].trim()
      if (body.length === 0) continue
      if (PLACEHOLDER_RE.test(body)) continue
      acItems.push(body)
    }

    if (acItems.length < MIN_AC_ITEMS) {
      errors.push(
        `Fewer than ${MIN_AC_ITEMS} acceptance-criteria items found (got ${acItems.length}). ` +
        `Replace placeholder text like \`<criterion>\` or \`TODO\` with concrete, testable outcomes.`
      )
    } else if (acItems.every(item => item.length < 10)) {
      warnings.push(
        'All acceptance-criteria items are under 10 characters. They likely need more detail.'
      )
    }
  }

  // Soft warnings
  if (!/^#{1,6}\s+(Context|Why|Background)\b/im.test(trimmed)) {
    warnings.push('No Context/Why/Background heading. Consider adding one to explain motivation.')
  }

  return { valid: errors.length === 0, errors, warnings }
}

/**
 * Return the canonical issue-description template as a string.
 *
 * When `title` is supplied, the Context section opens with a `**Title:**`
 * line so the template stays self-describing when pasted into external tools.
 * The returned string never contains an H1 — Linear renders the issue title
 * separately.
 */
export function buildIssueTemplate(title?: string): string {
  const titleLine = title ? `**Title:** ${title}` : '**Title:** <to fill>'
  return [
    '## Context',
    titleLine,
    '',
    '<What is changing and why. 2-4 sentences. Link prior issues, docs, or incidents that motivate this.>',
    '',
    '## Problem',
    '<What specifically is broken, missing, or insufficient today. Name the file, flow, or behavior.>',
    '',
    '## Proposal',
    '<What you intend to do about it. High-level approach, not implementation line-by-line.>',
    '',
    '## Acceptance Criteria',
    '- [ ] <Concrete, testable outcome>',
    '- [ ] <Concrete, testable outcome>',
    '',
    '## Verification',
    '<How the AC will actually be checked. Manual steps, test command, or review instruction.>',
    '',
    '## Out of Scope',
    '- <What this issue does NOT cover — redirect to the follow-up or explain why it is deferred>',
    ''
  ].join('\n')
}

/**
 * Format a validation result for human consumption. Writes to stderr when used
 * by the CLI; callers are responsible for the actual stream choice.
 *
 * Contract:
 *   - Header line naming the failure.
 *   - Bulleted list of errors.
 *   - Optional warnings block.
 *   - Footer pointing at --template and --strict=false.
 */
export function formatDescriptionValidationResult(result: DescriptionValidationResult): string {
  const lines: string[] = []

  if (result.valid) {
    lines.push('✓ Issue description is valid.')
  } else {
    lines.push('✗ Issue description failed acceptance criteria validation.')
    lines.push('')
    for (const error of result.errors) {
      lines.push(`  • ${error}`)
    }
  }

  if (result.warnings.length > 0) {
    lines.push('')
    lines.push('Warnings:')
    for (const warning of result.warnings) {
      lines.push(`  ⚠ ${warning}`)
    }
  }

  if (!result.valid) {
    lines.push('')
    lines.push(
      'Run `npm run ops -- create-issue --template` to print a ready-to-edit template, ' +
      'or pass --strict=false to downgrade to a warning.'
    )
  }

  return lines.join('\n')
}

/**
 * Render only the warnings block (no valid/invalid banner, no footer). Used by
 * CLI sites that want to surface warnings inline when the description is
 * otherwise valid — printing the full formatter output with a ✓ banner reads
 * as contradictory when the caller is alerting the user to a concern.
 */
export function formatWarningsOnly(result: DescriptionValidationResult): string {
  if (result.warnings.length === 0) return ''
  const lines: string[] = ['Description warnings:']
  for (const warning of result.warnings) {
    lines.push(`  ⚠ ${warning}`)
  }
  return lines.join('\n')
}

/**
 * Decide whether strict-mode is active for the current invocation.
 *
 * Precedence (highest to lowest):
 *   1. Explicit `--strict=false` flag ⇒ warning-only.
 *   2. Explicit `--strict=true` flag ⇒ strict (overrides env var).
 *   3. `LINEAR_REQUIRE_ACCEPTANCE_CRITERIA=0` env var ⇒ warning-only.
 *   4. Default ⇒ strict.
 */
export function isStrictMode(flagValue?: boolean): boolean {
  if (flagValue === false) return false
  if (flagValue === true) return true
  if (process.env.LINEAR_REQUIRE_ACCEPTANCE_CRITERIA === '0') return false
  return true
}
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall