Catalyst Specifications Repository

This repository contains detailed technical specifications, bug fixes, and feature documentation for the Catalyst Newsletter Generator application.

Purpose

The Catalyst Specifications Repository serves as the central documentation hub for:

• Feature Specifications: Detailed implementation plans for new features
• Bug Fix Specifications: Root cause analysis and fix documentation for identified issues
• AI Coding Guidelines: Comprehensive development standards in CLAUDE.md
• Technical Documentation: Architecture decisions and implementation patterns

This repository is separate from the main application to maintain clear separation between specification/planning and implementation code.

Relationship to Catalyst Newsletter

• This Repository: catalyst/ - Specifications, documentation, and planning
• Main Application: catalyst-newsletter - Actual Next.js application implementation

All specifications in this repository are intended to be implemented in the main catalyst-newsletter application.

Repository Structure

catalyst/
├── README.md                    # This file
├── CLAUDE.md                    # AI coding rules and development guidelines
└── specs/                       # Specification documents
    ├── feature-*.md            # Feature specifications
    ├── bug-*.md                # Bug fix specifications
    └── chore-*.md              # Maintenance task specifications

Available Specifications

Features

• Langfuse LLM Observability - Comprehensive LLM tracking and monitoring using Langfuse
• Claude Agent SDK Migration - Migration to Claude's official Agent SDK
• HTML Rendering and Enhanced Error Handling - Improved rendering and error management

Bug Fixes

• Sources Page Crash Fix - Fix for sources page rendering issues
• Admin Password Secret Manager Migration - Secure credential storage
• GCP Cloud Run Database Connection - Fix database connectivity in production
• Authentication Persistence - Fix auth session management
• Error Message Display - Improve error visibility
• Authentication Bypass in Development - Fix dev environment security
• Newsletter Generation 401 Error - Fix authentication issues in generation
• Missing Sources in Newsletter Prompt - Fix source inclusion logic
• Model Name Mismatch in UI - Fix display inconsistencies
• Langfuse Missing Claude Generation Spans - Fix observability gaps
• Langfuse Environment Display - Fix environment tagging

Chores

• Remove Follow-up Section from Agent Response - Clean up agent output format

Specification Format

Each specification document follows a consistent structure:

1. Description: Overview of the feature or bug
2. User Story: User-focused narrative
3. Problem Statement: Current issues or gaps
4. Solution Statement: Proposed approach
5. Relevant Files: Files that need modification
6. Implementation Plan: High-level phases
7. Step by Step Tasks: Detailed implementation steps
8. Testing Strategy: Unit, integration, and E2E tests
9. Acceptance Criteria: Definition of done
10. Validation Commands: Commands to verify implementation

Using This Repository

For Developers

1. Review the specification document for your assigned feature/bug
2. Follow the step-by-step implementation tasks
3. Implement changes in the catalyst-newsletter repository
4. Run validation commands to ensure correctness
5. Verify all acceptance criteria are met

For AI Assistants

When implementing specifications:

1. Read the entire specification document thoroughly
2. Review the CLAUDE.md coding guidelines
3. Locate relevant files in catalyst-newsletter
4. Follow the implementation plan step-by-step
5. Execute all validation commands
6. Ensure zero regressions

For Project Managers

• Use specifications to understand feature scope and complexity
• Track implementation progress against acceptance criteria
• Reference validation commands for QA processes
• Use specifications for estimation and planning

CLAUDE.md Guidelines

The CLAUDE.md file contains comprehensive AI coding rules covering:

• Coding Practices: Support levels, documentation standards, version control
• Frontend: React, Next.js, Astro, Tailwind, accessibility (WCAG)
• Backend: FastAPI, Express, database practices
• DevOps: GitHub Actions, Docker, GCP
• Testing: Pytest, Supertest, Playwright

All implementations should adhere to these guidelines.

Contributing

To add new specifications:

1. Create a new file in specs/ with the naming convention:

   • Features: feature-{name}.md
   • Bugs: bug-{description}.md
   • Chores: chore-{description}.md

2. Follow the standard specification template structure

3. Link relevant files from the catalyst-newsletter project

4. Include comprehensive testing strategy and validation commands

Related Links

• Main Application: catalyst-newsletter
• Langfuse Dashboard: Access via application environment configuration
• Deployment: GCP Cloud Run (see bug specs for deployment issues)

Questions or Issues?

For questions about:

• Specifications: Review the relevant spec document and CLAUDE.md
• Implementation: See the main catalyst-newsletter README
• AI Guidelines: Refer to CLAUDE.md

---

Last Updated: 2025-10-20