Catalyst

Catalyst is a VS Code-first AI Product Studio extension. It turns a product idea or product revision into implementation-ready artifacts for Codex, Claude Code, GitHub Copilot, and other coding agents.

Catalyst is not an LLM chat surface and it is not for ideating from scratch. Bring an already-ideated product plan; Catalyst structures it into artifacts, task order, handoff notes, and coding-agent prompts.

The extension is local-first: it reads the currently open workspace, writes generated artifacts into that workspace, stores secrets in VS Code SecretStorage, and keeps agent handoff files beside the code they describe.

This repository can be packaged locally as a VSIX or published to the VS Code Marketplace when the publisher account and token are ready.

What Catalyst Does

Catalyst helps you move from "I have an app idea" to "my coding agent knows exactly what to build next."

It can:

• Scan the active VS Code workspace and summarize repo structure.
• Generate product, design, architecture, workflow, task, prompt, and handoff artifacts.
• Run in a guided mode where each major stage can be approved or revised.
• Keep all generated files under artifacts/.
• Create versioned artifact snapshots under artifacts/v*.
• Track implementation state in artifacts/IMPLEMENTATION_STATE.json.
• Generate coding-agent prompts in artifacts/PROMPTS.md.
• Install or update workspace agent instruction files:
  • AGENTS.md for Codex.
  • CLAUDE.md for Claude Code.
  • .github/copilot-instructions.md for GitHub Copilot.
• Manage model provider profiles and route each pipeline agent to a preferred model.
• Store API keys in VS Code SecretStorage instead of writing secrets into source files.
• Point users to Stitch for manual design review instead of running live Stitch sync.
• Import Stitch or Figma export JSON into normalized design intake artifacts.

Extension Overview Page

VS Code displays this README.md as the extension overview page when the local VSIX is installed. Update this file before packaging whenever user-facing setup or feature behavior changes.

Requirements

• VS Code 1.90 or newer.
• Node.js 20 or newer.
• npm.
• The code command available on your PATH if you want to reinstall the local VSIX from the terminal.
• At least one configured LLM provider for real generation runs.
• Optional Stitch or Figma exports if you want to bring external visual context back into Catalyst.

Local Development Setup

Install dependencies:

npm install

Build TypeScript:

npm run build

Run tests:

npm test

Package the extension:

npm run package:vsix

Install the freshly packaged VSIX into VS Code:

npm run reinstall:vsix

The reinstall command intentionally uninstalls the existing local extension first, then installs catalyst-0.1.0.vsix. This avoids stale extension folders and is important for runtime dependencies such as @google/stitch-sdk.

After reinstalling, reload the VS Code window.

First Run In VS Code

1. Open the workspace you want Catalyst to manage.
2. Open the Catalyst activity bar view.
3. Open Settings inside Catalyst.
4. Add provider keys or configure model profiles.
5. Choose the default profile:
   • UI focused for fast product/design/task output.
   • Full research when you want the research stage included.
6. Review the Stitch note: Catalyst does not run live Stitch sync. Check your Stitch account directly for design work, then import an export JSON or Figma reference if needed.
7. Enter a product idea or revision.
8. Click Generate.
9. When the run completes, click Install agent files from the success prompt.

Catalyst will create or update the supported agent instruction files with the latest artifact workflow.

Normal Workflow

The recommended loop is:

1. Generate artifacts from a product idea.
2. Review the generated artifact list in the Catalyst inspector.
3. Install the updated agent files after the successful run.
4. Open artifacts/PROMPTS.md.
5. Give Prompt 1 to your coding agent.
6. Let the coding agent implement only that task packet.
7. Run the packet acceptance commands.
8. Update artifacts/IMPLEMENTATION_STATE.json after meaningful progress.
9. Continue with the next prompt only after acceptance criteria pass.

The generated agent files tell Codex, Claude Code, and Copilot to treat artifacts/ as the source of truth.

Generated Artifacts

Common generated files include:

• artifacts/PLAN.md
• artifacts/PRD.md
• artifacts/STACK.md
• artifacts/WORKFLOW.md
• artifacts/PROMPTS.md
• artifacts/PROCESS_LOG.md
• artifacts/AGENT_LOGS.md
• artifacts/IMPLEMENTATION_STATE.md
• artifacts/IMPLEMENTATION_STATE.json
• artifacts/AGENT_HANDOFF.md
• artifacts/VISUAL_CONTEXT.md
• artifacts/DESIGN_INTENT.md
• artifacts/STITCH_BRIEF.md
• artifacts/SCREEN_FLOW_MAP.md
• artifacts/TAILWIND_THEME.md
• artifacts/DESIGN_INTAKE.json
• artifacts/DESIGN_SYSTEM.json
• artifacts/STITCH_SYNC.json
• artifacts/SCREENS.json
• artifacts/COMPONENT_MAP.json
• artifacts/TASK_QUEUE.json
• artifacts/AGENT_LOGS.json

Version snapshots are written under folders such as artifacts/v2, artifacts/v3, and later.

Agent Files

After a successful run, Catalyst prompts you to install updated agent files. The button writes the latest instruction files into the active workspace:

• AGENTS.md
• CLAUDE.md
• .github/copilot-instructions.md

These files instruct agents to:

• Read generated artifacts before editing code.
• Use artifacts/TASK_QUEUE.json as the task order.
• Use artifacts/PROMPTS.md for copy-ready implementation prompts.
• Track status in artifacts/IMPLEMENTATION_STATE.json.
• Use artifacts/VISUAL_CONTEXT.md, artifacts/STITCH_SYNC.json, and artifacts/DESIGN_INTAKE.json for visual context.
• Keep changes scoped to the active task.
• Run the commands listed in each task packet when relevant.

You can also install agent files at any time from:

• The Catalyst sidebar Install agents action.
• The Agents tab in the inspector.
• The command palette command Catalyst: Install Agent Files.

Model Configuration

Catalyst supports built-in provider settings and custom model profiles.

From the Settings panel you can store keys for:

• Gemini.
• Groq.
• OpenRouter.
• Azure OpenAI.
• Local OpenAI-compatible endpoints.
• Firecrawl.
• Stitch.
• Figma.

From the Models tab you can:

• Create named model profiles.
• Set endpoints and model IDs.
• Choose provider presets.
• Test a model profile.
• Route individual Catalyst stages to primary and fallback profiles.

Secrets are stored through VS Code SecretStorage. They are not written to README.md, package.json, generated artifacts, or source-controlled config files.

Provider Environment Variables

The CLI and extension can also read environment variables.

Core provider variables:

GROQ_API_KEY=...
GEMINI_API_KEY=...
OPENROUTER_API_KEY=...
AZURE_OPENAI_API_KEY=...
LOCAL_LLM_BASE_URL=http://localhost:11434/v1/chat/completions
LOCAL_LLM_API_KEY=...

Runtime tuning:

LLM_TEMPERATURE=0.2
LLM_MAX_TOKENS=4096

Routing overrides:

PROVIDER_GROQ_ENABLED=true
PROVIDER_GROQ_BASE_URL=https://api.groq.com/openai/v1/chat/completions
ROUTE_RESEARCH_PROVIDER=gemini
ROUTE_RESEARCH_MODEL=gemini-2.5-flash
ROUTING_OVERRIDES_JSON={...}

Stitch Design Review

Catalyst does not run live Stitch sync at runtime. Stitch should be treated as a manual design workspace: open your Stitch account directly to review or manage generated designs.

When you want Catalyst to consume visual context from Stitch, use one of these paths:

• Export JSON from Stitch and import it with Catalyst: Import Design Export.
• Export or move designs into Figma, then set FIGMA_TOKEN, FIGMA_FILE_KEY, and optional FIGMA_NODE_IDS.
• Add design links or screenshots to artifacts/VISUAL_CONTEXT.md.

You may still see artifacts/STITCH_SYNC.json, but it records that Stitch sync was skipped and manual review is expected.

Useful manual import variables:

STITCH_EXPORT_PATH=C:\path\to\stitch-export.json
STITCH_FIGMA_FILE_KEY=...

Design context is recorded in:

• artifacts/STITCH_SYNC.json
• artifacts/STITCH_BRIEF.md
• artifacts/VISUAL_CONTEXT.md

Figma And Design Export Intake

Catalyst can import design export JSON through the command:

Catalyst: Import Design Export

The import path normalizes Stitch or Figma export payloads into:

• artifacts/DESIGN_INTAKE.json
• artifacts/VISUAL_CONTEXT.md

If you use Figma REST intake, configure:

FIGMA_TOKEN=...
FIGMA_FILE_KEY=...
FIGMA_NODE_IDS=...

CLI Usage

The extension is the primary experience, but the CLI remains available.

Generate artifacts:

node cli generate "Build a local-first CRM for freelancers"

Run unattended:

node cli generate --yes "Build a local-first CRM for freelancers"

Iterate from an existing workspace:

node cli iterate "make the MVP simpler and Streamlit-first"

Point at a target app repo:

node cli iterate --project-root C:\path\to\your\app "sync with the current implementation"

Run UI-focused mode:

node cli generate --profile ui --project-root C:\path\to\your\app "Migrate the CLI experience into a web app"

Run one agent:

node cli agent research --project-root C:\path\to\your\app "Summarize what this repo needs for a web UI"

Feed a coding-agent progress report back into Catalyst:

node cli iterate --project-root C:\path\to\your\app --report C:\path\to\progress-report.md "review implementation progress"

Development Commands

npm run build
npm test
npm run package:vsix
npm run reinstall:vsix

Use npm test before packaging. Use npm run reinstall:vsix before testing the local extension in VS Code.

Repository Layout

• agents/: product, design, architecture, research, prompt, and review agents.
• cli/: CLI entry point.
• core/: orchestration, routing, schemas, design artifact generation, project state, and observability.
• extension/: VS Code extension UI and services.
• integrations/: Stitch, Figma, execution, search, and embedding adapters.
• providers/: LLM provider adapters.
• schemas/: JSON schemas for generated artifacts.
• scripts/: packaging and verification scripts.
• tests/: Node test suite.
• artifacts/: generated workspace artifacts.
• .catalyst/: local extension state.

Production Readiness Checklist

Before publishing later:

• Keep .env out of git.
• Keep real secrets in VS Code SecretStorage or local environment variables only.
• Verify npm run build.
• Verify npm test.
• Verify npm run package:vsix.
• Install the local VSIX with npm run reinstall:vsix.
• Run a Catalyst generation from the VS Code UI.
• Click the post-run Install agent files button.
• Confirm the Stitch tab tells users to review designs directly in Stitch.
• Confirm the extension overview page renders this README correctly in VS Code.

Troubleshooting

No Catalyst view appears:

• Reload the VS Code window.
• Confirm the local VSIX is installed.
• Confirm the workspace is open as a folder, not only as a loose file.

Model calls fail:

• Check Settings for missing provider keys.
• Test model profiles from the Models tab.
• Confirm custom endpoints return a compatible response shape.

Stitch designs are needed:

• Open your Stitch account directly.
• Import a Stitch export JSON with Catalyst: Import Design Export, or connect Figma references.

Agent files look stale:

• Run Catalyst again.
• Use the success prompt button Install agent files.
• Or run Catalyst: Install Agent Files from the command palette.