Creating Threadlines

Threadline Format

Each threadline is a markdown file with YAML frontmatter. Place them in a /threadlines directory in your repository root.

---
id: unique-threadline-id
version: 1.0.0
patterns:
  - "**/api/**"
  - "**/*.ts"
context_files:
  - "path/to/context-file.ts"
---

# Your Threadline Title

Your guidelines and standards here...

Required Fields

  • id: Unique identifier (e.g., sql-queries, error-handling)
  • version: Semantic version (e.g., 1.0.0)
  • patterns: Array of glob patterns matching files to check (e.g., ["**/api/**", "**/*.ts"])
  • Body: Markdown content describing your standards

Optional Fields

  • context_files: Array of file paths that provide context (always included, even if unchanged)

Context files are useful when your threadline needs to reference other files. For example, SQL query standards might reference your database schema file.

Pattern Matching

Patterns use glob syntax. Common patterns:

  • **/*.ts - All TypeScript files
  • **/api/** - All files in api directories
  • **/*.sql - All SQL files
  • src/components/**/*.tsx - React components in src/components

Remember: Threadlines only run on files that match their patterns. If a file doesn't match any pattern, it won't be checked.

Writing Effective Threadlines

  • Be specific: Focus on one concern per threadline
  • Provide examples: Include good and bad examples in your markdown
  • Explain why: Help developers understand the reasoning behind the standard
  • Keep it focused: Each threadline should check one thing well