---
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

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

## Instructions

### 1. Scan Deployed Tickets

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

### 2. Extract File Metadata

For each deployed ticket, extract:

```json
{
  "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

```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

```json
{
  "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

```markdown
# 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:**
```json
{
  "project_dir": "/projects/oxygen_site",
  "tickets_dir": "/projects/oxygen_site/tickets/sprint_current/deployed",
  "include_tests": false,
  "include_deps": true
}
```

**Include test files:**
```json
{
  "project_dir": "/projects/oxygen_site",
  "tickets_dir": "/projects/oxygen_site/tickets/sprint_current/deployed",
  "include_tests": true,
  "include_deps": true
}
```

**Custom tickets directory:**
```json
{
  "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