| 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:
- Read existing catalog
- Add new files from recently deployed tickets
- Preserve existing entries (don't remove)
- Update changelog section
- 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