generate-catalog

name	generate-catalog
description	Generate CATALOG.md from deployed tickets. Extracts files_created metadata and builds project asset catalog with usage instructions.

generate-catalog - Project Catalog Generator

Generates or updates CATALOG.md from deployed ticket metadata. Builds a comprehensive asset catalog showing all components, styles, and utilities with usage instructions.

Input Schema

{
  "project_dir": "/path/to/project",
  "tickets_dir": "/path/to/tickets/deployed",
  "include_tests": false,
  "include_deps": true
}

Instructions

1. Scan Deployed Tickets

cd $tickets_dir
for ticket in *.json; do
    jq -r '.files_created[]' "$ticket"
done

2. Extract File Metadata

For each deployed ticket, extract:

{
  "files_created": [
    {
      "path": "src/components/MetricCard.js",
      "type": "component",
      "intended_use": "Import { MetricCard } from './MetricCard.js'"
    }
  ]
}

3. Categorize Assets

Category	Patterns	Description
Components	src/components/**/*.js	Reusable UI components
Styles	src/styles/**/*.css	CSS stylesheets
Utils	src/utils/**/*.js, src/js/utils/**	Helper functions
Data	src/data/**/*.json	Static data files
Pages	src/pages/**/*.html	HTML pages
Tests	tests/**/*, *.spec.js	Test files (if included)

4. Generate Markdown

# Project Asset Catalog

> Auto-generated by generate-catalog on {date}

## Summary

| Category | Count | Status |
|----------|-------|--------|
| Components | 5 | ✅ |
| Styles | 3 | ✅ |

## Components

| File | Intended Use | Created By |
|------|--------------|------------|
| `src/components/MetricCard.js` | Import { MetricCard } | TICKET-001 |

Output Format

{
  "skill": "generate-catalog",
  "status": "success|failure",
  "catalog_path": "src/CATALOG.md",
  "stats": {
    "tickets_processed": 5,
    "files_cataloged": 23,
    "categories": {
      "components": 8,
      "styles": 5,
      "utils": 4,
      "data": 2,
      "pages": 4
    }
  },
  "errors": [],
  "warnings": [],
  "next_action": "proceed"
}

Catalog Structure

# Project Asset Catalog

> Auto-generated by generate-catalog on 2026-01-07

## Summary

| Category | Count | Status |
|----------|-------|--------|
| Components | 8 | ✅ |
| Styles | 5 | ✅ |
| Utils | 4 | ✅ |
| Data | 2 | ✅ |
| **Total** | **19** | |

## Components

| File | Intended Use | Created By |
|------|--------------|------------|
| `src/components/impact/MetricCard.js` | Import { MetricCard } from './MetricCard.js' | TICKET-OXY-003-A.3 |

## Styles

| File | Intended Use | Created By |
|------|--------------|------------|
| `src/styles/components/metric-card.css` | Link in HTML: <link rel="stylesheet" href="..."> | TICKET-OXY-003-A.3 |

## Changelog

- **2026-01-07**: Added MetricCard component via TICKET-OXY-003-A.3

Decision Logic

All tickets parsed successfully?
    YES → status: "success"
    NO  → status: "failure", errors: [parse errors]

Catalog written successfully?
    YES → next_action: "proceed"
    NO  → next_action: "fix"

Usage Examples

Generate from deployed tickets:

{
  "project_dir": "/projects/oxygen_site",
  "tickets_dir": "/projects/oxygen_site/tickets/sprint_current/deployed",
  "include_tests": false,
  "include_deps": true
}

Include test files:

{
  "project_dir": "/projects/oxygen_site",
  "tickets_dir": "/projects/oxygen_site/tickets/sprint_current/deployed",
  "include_tests": true,
  "include_deps": true
}

Custom tickets directory:

{
  "project_dir": "/projects/oxygen_site",
  "tickets_dir": "/projects/oxygen_site/tickets/archive/sprint-42",
  "include_tests": false,
  "include_deps": false
}

Merge Behavior

When updating existing CATALOG.md:

1. Read existing catalog
2. Add new files from recently deployed tickets
3. Preserve existing entries (don't remove)
4. Update changelog section
5. Sort entries alphabetically within categories

Token Efficiency

• JSON parsing only, no LLM inference
• Incremental updates (append-only)
• ~2-5 second execution
• Writes directly to file system