Compound Context (CO2) Workflow

https://compound-context.com

Key Features

📝 User Story to drive UI and UX design + Non-Functional Requirement to drive business logic and technical design + Constraints to drive technical design and implementation.

🔄 Versioning to keep track of the changes and updates in the context as the project progresses.

📦 Multi application support where each application will have its own context. This is to support:

• Microservices architecture (multiple backend services with REST API or GraphQL API)
• Mobile application development (mobile frontend + REST API backend)
• Single Page Application development (web frontend + REST API backend)

🔗 Traceability from the generated code to the artifacts in the context to the User Stories, Non-Functional Requirements and Constraints.

🧠 Comprehensive context to reduce AI hallucination and AI slop, which includes:

• Data Models
• HTML Mockups
• Technical Specifications
• Test Specifications

Pre-requisites

• Claude Code (Preferably MAX plan)
• Claude Code Plugins
• Playwright Test Generator Plugin (for generating Playwright test specifications and test scripts)
• Ralph Loop Plugin (for orchestrating the development and bug fixing process)
• Node and npm version 18 or above (for serving the HTML mockups and running the Playwright test scripts)

Getting Started

• Plugin Name: Compound Context (CO2) Workflow (see below for details)

To install the plugin: ~~~bash

Step 1: Add the marketplace

/plugin marketplace add rashidee/co2-skills

Step 2: Install the plugin

/plugin install co2-skills@co2 ~~~

Development Workflow

Context Window Preparation

_This is the initial step where you want to ensure the AI coding agent has all the information needed to work._

💡 Bootstrapping a brand-new project? Use /util-projectinit "<one-paragraph brief>" or /util-projectinit <brief.md> to auto-generate skeleton CLAUDE.md, DEVTOOL.md and ENVIRONMENT.md from a free-form prompt or markdown brief. The skill infers 3rd-party infrastructure, custom applications, system/business modules and the local toolchain. It is non-destructive — it refuses to overwrite an existing CLAUDE.md.

CLAUDE.md

⚠️ Shared by the team - Checked in the repository

• Project detail
• Project goals
• Terminology (if any)
• Applications (1 or more)
• Modules (System Modules and Business Modules)

DEVTOOL.md

⚠️ Per developer - NOT CHECKED IN the repository

• Local development tools available to the AI coding agent (JDK, Maven, Node.js, kubectl, database CLIs, etc.)

ENVIRONMENT.md

⚠️ Per developer - NOT CHECKED IN the repository

• Per-environment configs and credentials for all 3rd party supporting applications
• Auto-generated/updated by util-preparek8senv skill

PRD Development

PRD.md is the main input for the development phase, which contains the User Stories, Non-Functional Requirements and Constraints. It is also the main reference for all the skills in this phase. The PRD.md should be updated and versioned as the project progresses.

Example of the PRD.md structure: ~~~markdown

Business Modules

<Module 1>

User Story

[v1.0.0]

• As a <type of user> I want to <perform some task> so that I can <achieve some goal>.
• As a <type of user> I want to <perform some task> so that I can <achieve some goal>.

Non-Functional Requirement

[v1.0.0]

• <Non-Functional Requirement 1>
• ~~<Non-Functional Requirement 2>~~

[v1.0.1]

• <Updated Non-Functional Requirement 1>
• Removed <Non-Functional Requirement 2> since <reason for removal>

Constraint

[v1.0.0]

• <Constraint 1>
• <Constraint 2>

Reference

[v1.0.0]

• <Reference 1>

<Module 2>

... ~~~

PRD Clean Up

_Since PRD.md is based on human input, it may require some validation and each new points added need to be tagged with unique ID for traceability:_

The skills to invoke the clean-up process are:

Data Model

_The skill goal is to generate the data model for each module for you to review before proceeding to next step._

Example skill invocation for data model generation: ~~~bash /modelgen-relational <app_name> ## For relational database model (SQL) /modelgen-nosql <app_name> ## For NoSQL document database model (MongoDB, Couchbase, DynamoDB, Firestore, CosmosDB) ~~~

• Input:
• PRDd.md (User Stories, Non-Functional Requirements and Constraints)
• Output:
• Model Markdown file containing:
• Entity name
• Attributes (name, type, description)
• Relationships (type of relationship, related entity, description)
• ERD Diagram in Mermaid syntax

Example of the Model Markdown file structure: ~~~markdown

• context
• model
• <module_1_folder>
• model.md
• erd.mermaid
• <module_2_folder>
• model.md
• erd.mermaid

MODEL.md ## A summary of the data model for all the modules ~~~

HTML Mockup

_The skill goal is to generate the HTML mockup for each screen for you to review before proceeding to next step._

Example skill invocation for HTML mockup generation: ~~~bash /mockgen-tailwind <app_name> ## For generating HTML mockup using Node.js + Express + Tailwind CSS + HTMX /mockgen-shadcn <app_name> ## For generating React + shadcn/ui mockups served via Vite + React Router ~~~

• Input:
• PRD.md (User Stories, Non-Functional Requirements and Constraints)
• Data Model (to understand the data structure and relationships)
• Output:
• HTML mockup screens for the application, served via Node.js + Express + HTMX
• MOCKUP.html — A landing page for all the mockup screens with links to each screen, and each screen will have a link back to the related User Stories, Non-Functional Requirements and Constraints in PRD.md for traceability.

Example of the HTML mockup output: ~~~markdown

• context
• mockup
• <role_1_folder>
• screen1.html
• screen2.html
• <role_2_folder>
• screen1.html
• screen2.html

MOCKUP.html ## A landing page for all the mockup screens ~~~

Technical Specification

_The skill goal is to generate the technical specification for the application, which includes the architecture, components, APIs, etc. for you to review before proceeding to next step._

>⚠️ At this point, you should already have determined the technology stack as the technical specification generation will be based on the specific technology stack skill

Example skill invocation for technical specification generation: ~~~bash /specgen-spring-jpa-jtehtmx <app_name> ## For generating Spring Boot 3 web application technical specification with JTE, Tailwind and htmx. /specgen-spring-jpa-restapi <app_name> ## For generating Spring Boot 3 REST API technical specification. /specgen-laravel-eloquent-bladehtmx <app_name> ## For generating Laravel 12 web application technical specification with Blade, Tailwind and htmx /specgen-react-mui <app_name> ## For generating React 19 SPA technical specification with TypeScript, Vite, Material UI and more. /specgen-react-tailwind <app_name> ## For generating React 19 SPA technical specification with TypeScript, Vite, Tailwind CSS, Headless UI and more. /specgen-flutter-riverpod <app_name> ## For generating Flutter 3 mobile application technical specification with Riverpod, Hive, Dio, go_router and Firebase Messaging. /specgen-ts-cli <app_name> ## For generating Node.js CLI application technical specification with TypeScript, Commander.js and tsup. ~~~

• Input:
• PRD.md (User Stories, Non-Functional Requirements and Constraints)
• Data Model (to understand the data structure and relationships)
• HTML Mockup (to understand the UI design and user interactions)
• Output:
• Technical specification document containing:
• SPEC.md — A per-module specification file containing:
• Module overview (package, type, authentication)
• Traceability table mapping back to User Story IDs, NFR IDs and Constraint IDs
• Component design (components, responsibilities, interactions)
• SPECIFICATION.md — A summary of the technical specification for all the modules

Example of the technical specification output: ~~~markdown- context

• specification
• <module_1_folder>
• SPEC.md
• <module_2_folder>
• SPEC.md

SPECIFICATION.md ## A summary of the technical specification for all the modules ~~~

Test Specification Generation

_The skill goal is to generate the test specification for the application, which includes the test cases and scenarios to validate the functionality and performance of the application, for you to review before proceeding to next step._

Example skill invocation for test specification generation: ~~~bash /testgen-functional <app_name> ## For generating Playwright E2E test plan and per-module test specifications as Markdown blueprints. ~~~

• Input:
• PRD.md (User Stories, Non-Functional Requirements and Constraints)
• Data Model (to understand the data structure and relationships)
• HTML Mockup (to understand the UI design and user interactions)
• Technical Specification (to understand the technical design and implementation)
• Output:
• Test specification document containing:
• TEST_SPEC.md — A per-module test specification file containing:
• Module overview
• Traceability table mapping back to User Story IDs, NFR IDs and Constraint IDs
• Test cases and scenarios (test case ID, description, preconditions, steps, expected results)
• TEST_PLAN.mmd - Summary of all the test cases and scenarios.

Example of the test specification output: ~~~markdown

• context
• test
• <module_1_folder>
• TEST_SPEC.md
• <module_2_folder>
• TEST_SPEC.md

TEST_PLAN.mmd ## A summary of all the test cases and scenarios in Mermaid syntax ~~~

K8s Environment Preparation

_The skill goal is to prepare the Kubernetes infrastructure by generating K8s manifests for all 3rd party supporting applications (databases, message queues, caches, SSO, API gateways, etc.) across all environments defined in CLAUDE.md._

>⚠️ This step should be run before application development to ensure the infrastructure is ready.

Example skill invocation for K8s environment preparation: ~~~bash /util-preparek8senv [environment] ## Generates K8s manifests for all 3rd party apps for one target environment ~~~

• Input:
• CLAUDE.md (environments, 3rd party applications, credential rules)
• DEVTOOL.md (local CLI tools — kubectl, mysql, mongosh, etc.)
• ENVIRONMENT.md (per-environment configs and credentials — created if missing)
• Output:
• ENVIRONMENT.md — Created/updated with per-environment configs for all 3rd party apps
• environment/\<env\>/ — Per-environment folders with K8s manifests:
• namespace.yaml — Project namespace
• <service>.yaml — One StatefulSet-based manifest per 3rd party application (with PVC, ConfigMap, Secret, headless Service, NodePort Service)

Example of the output: ~~~markdown

• environment
• localhost
• namespace.yaml
• hub_cache.yaml
• hub_core_database.yaml
• hub_support_database.yaml
• hub_single_sign_on.yaml
• ...
• home_server
• namespace.yaml
• hub_cache.yaml
• hub_core_database.yaml
• ...
• ENVIRONMENT.md

~~~

Application Development

_The skill goal is to develop the application based on all the context generated above, and you can track the development progress using the output from this skill._

Example skill invocation for application development: ~~~bash /conductor-feature-develop <app_name> ## For orchestrating full-stack application development module-by-module using all generated artifacts. ~~~

• Input:
• PRD.md (User Stories, Non-Functional Requirements and Constraints)
• Data Model (to understand the data structure and relationships)
• HTML Mockup (to understand the UI design and user interactions)
• Technical Specification (to understand the technical design and implementation)
• Test Specification (to understand the test cases and scenarios to validate the functionality and performance of the application)
• Output:
• Source code files for the application, organized by module and component.
• IMPLEMENTATION_MASTER.md — Master tracking file containing:
• Application overview (name, source code path, context path)
• Overall status (PENDING → IN PROGRESS → COMPLETED)
• Execution order (copied from TEST_PLAN.md)
• Pre-implementation checklist (project skeleton, build config, security, layouts, database, error handling, theming, pagination, Playwright setup)
• Module implementation status table (module name, layer, status, start/completion dates)
• Module details with dependencies and resource paths
• IMPLEMENTATION_MODULE.md — Per-module tracking file containing:
• Module overview (name, layer, status, dates)
• Resources table (user story IDs, model/schema/specification/test spec/mockup paths)
• Implementation checklist (entities, repositories, services, mappers, controllers, views, tests)
• User Stories and NFR completion checklists for traceability
• Visual consistency checklist (colors, spacing, layout, typography)
• Source files created table
• Implementation log with timestamped entries
• Playwright E2E test suite — functional and visual consistency tests per module

Deployment Artifacts

_The skill goal is to generate deployment artifacts (Dockerfile and deployment specification) for the application, for you to review before deploying._

>⚠️ This step is automatically invoked by conductor-feature-develop after all modules are completed. You can also invoke it manually.

Example skill invocation for deployment artifact generation: ~~~bash /depgen-k8s <app_name> [environment] ## For generating Dockerfile and Kubernetes manifests ~~~

• Input:
• SPECIFICATION.md (to understand the technology stack and configuration)
• CLAUDE.md (to understand dependencies and 3rd party applications)
• Application source code (to detect stack via pom.xml, composer.json, or package.json)
• Output:
• Dockerfile — Production-ready, multi-stage Docker build file in the application folder
• Kubernetes manifests — Manifests directly in <app_folder>/k8s/ (gitignored, each machine maintains its own copy) containing:
• Namespace, ConfigMap, Secret, Deployment, Service, Ingress (separate YAML files)
• Environment variable mapping from .env to Kubernetes ConfigMap/Secret
• Health check and readiness probe configuration

Example of the deployment artifact output: ~~~markdown

• <application_folder>
• Dockerfile
• k8s
• local_development_environment
• namespace.yaml
• configmap.yaml
• secret.yaml
• deployment.yaml
• service.yaml
• home_server_environment
• namespace.yaml
• configmap.yaml
• secret.yaml
• deployment.yaml
• service.yaml

~~~

Bug Fixing Workflow

Bug Reporting

Report bugs in <app_folder>/context/BUG.md following the module-based structure: ~~~markdown

Business Module

<Module Name>

[v1.0.4]

• Bug description here
• Priority: High
• Steps to Reproduce:
• Expected Result:

~~~

Bug Fixing

Example skill invocation for bug fixing: ~~~bash /conductor-defect <app_name> ## For orchestrating bug fixing from BUG.md ~~~

• Input:
• BUG.md (bug reports organized by module)
• All context artifacts from the development phase (PRD.md, models, mockups, specifications, test specs)
• Flow:

1. Tag untagged bugs — Assign sequential [BUG-XXX] tags to new bug entries in BUG.md
2. Create BUG_MASTER.md — Master tracking checklist with all bugs, statuses and summary counts
3. For each bug (processed sequentially):

• Reproduce — Write and run a Playwright script to reproduce the bug, capture screenshot
• Write test spec — Create BUG_TEST_SPEC.md with verification steps and expected results
• Analyze and plan — Identify root cause, assess impact, create BUG_FIX_PLAN.md with fix checklist
• Apply fix — Make code changes as planned, log progress in fix plan
• Verify fix — Run Playwright verification script, capture post-fix screenshot
• Update artifacts — Sync affected mockups, specifications, models and PRD.md with the fix

1. Completion — Update BUG_MASTER.md status to COMPLETED when all bugs are resolved

• Output:
• BUG_MASTER.md — Master tracking file with bug statuses (NEW, IN_PROGRESS, FIXED, CANNOT_REPRODUCE, HIGH_IMPACT)
• Per-bug folder (<app_folder>/context/bug/<module-slug>/<BUG-XXX>/) containing:
• reproduce.spec.ts — Playwright reproduction script
• screenshot_reproduce.png — Pre-fix screenshot
• BUG_TEST_SPEC.md — Test specification for verification
• BUG_FIX_PLAN.md — Fix plan with checklist, files to modify, and timestamped fix log
• screenshot_fixed.png — Post-fix screenshot

Example of the BUG_MASTER.md structure: ~~~markdown

• context
• bug
• <module_1_folder>
• <BUG-001>
• reproduce.spec.ts
• screenshot_reproduce.png
• BUG_TEST_SPEC.md
• BUG_FIX_PLAN.md
• screenshot_fixed.png
• <BUG-002>

...

• <module_2_folder>
• <BUG-003>

... BUG_MASTER.md ## Master tracking file for all bugs in the application ~~~

Directory Structure

• Each application will have its own root-level folder containing both context and source code.
• The context folder will contain all the artifacts generated in the Context Window Preparation Phase and Development Phase
• The source code files will be generated in the root-level folder of the application.
• The CLAUDE.md and SECRET.md will be in the root-level folder of the project, and they will be used as reference for all the applications in the project.
• Example of the directory structure:

~~~

• <project_folder>
• CLAUDE.md
• DEVTOOL.md (per developer — local CLI tools)
• ENVIRONMENT.md (per developer — per-environment configs/credentials)
• environment (K8s manifests for 3rd party apps — generated by util-preparek8senv; gitignored, each machine has its own copy)
• <application_1_folder>
• context
• model
• <module_1_folder>
• model.md
• erd.mermaid
• <module_2_folder>
• model.md
• erd.mermaid
• mockup
• <role_1_folder>
• screen1.html
• screen2.html
• <role_2_folder>
• screen1.html
• screen2.html

MOCKUP.html

• specification
• <module_1_folder>
• SPEC.md
• <module_2_folder>
• SPEC.md

SPECIFICATION.md

• test
• <module_1_folder>
• TEST_SPEC.md
• <module_2_folder>
• TEST_SPEC.md

TEST_PLAN.mmd

• develop
• bug
• PRD.md
• BUG.md
• CHANGELOG.md (auto-generated — per-application version history; serves as version gate)
• (source code files)

~~~

Community

Contribution

We welcome contributions from the community! Here are some ways you can contribute:

Specification Generator Skills (specgen-*)

This is the highest impact area for contribution. The CO2 workflow is designed to be technology-agnostic, but each specgen-* skill targets a specific technology stack. We currently support:

We are looking for contributors to create new specgen-* skills for other technology stacks, such as:

• Backend: Django, FastAPI, Express.js, NestJS, ASP.NET Core, Ruby on Rails, Phoenix (Elixir), Go (Gin/Echo/Fiber)
• Frontend: Next.js, Nuxt.js, SvelteKit, Remix, Astro
• Mobile: React Native, Swift (iOS), Kotlin (Android)
• Full-stack: T3 Stack, RedwoodJS, Adonis.js, Meteor

Each specgen-* skill takes the same inputs (PRD.md, data models, HTML mockups) and produces a SPECIFICATION.md summary and per-module SPEC.md files tailored to the target stack. If you are experienced in a technology stack not listed above, your contribution would help the community generate specifications for that stack.

Deployment Generator Skills (depgen-*)

We currently support:

We are looking for contributors to create new depgen-* skills for other deployment strategies, such as:

• Container Orchestration: Docker Compose, Docker Swarm, Nomad
• Cloud-native: AWS ECS/Fargate, Google Cloud Run, Azure Container Apps
• Platform-as-a-Service: Heroku, Railway, Fly.io, Render
• Serverless: AWS Lambda + API Gateway, Vercel, Netlify
• Infrastructure-as-Code: Terraform, Pulumi, CDK

Each depgen-* skill takes the same inputs (SPECIFICATION.md, CLAUDE.md, application source code) and produces a Dockerfile and deployment manifests tailored to the target deployment strategy.

Other Contribution Areas

• *Data Model Skills (`modelgen-`)** — Support for additional database types (e.g., graph databases like Neo4j, time-series databases like InfluxDB)
• *Mockup Generator Skills (`mockgen-)** — Currently supports mockgen-tailwind (Node.js + Express + HTMX) and mockgen-shadcn` (React + Vite + shadcn/ui). Contributions welcome for alternative UI frameworks or design systems (e.g., Bootstrap, Material UI, Ant Design)
• *Test Generator Skills (`testgen-`)** — Support for additional testing frameworks (e.g., Cypress, Selenium)
• Bug reports and feature requests — Open an issue at https://github.com/rashidee/co2-skills/issues
• Documentation improvements — Help improve the README, skill documentation, or examples

Example Applications

Below are example applications developed using the CO2 workflow. More examples will be added over time to demonstrate the versatility of the workflow across different domains and technology stacks.:

1. SimpleCMS — A simple content management system built from structured requirements through to working code. Demonstrates the full CO2 workflow end-to-end.

• Admin Portal: Spring Boot 3 + JTE + Tailwind + htmx
• Landing Page: Laravel 12 + Blade + htmx
• Database: PostgreSQL 14
• Repository: co2-example-simplecms

Disclaimer

🤖 Currently only Claude Code Agent is supported, but we are planning to support more AI coding agents in the future.

🪙 This workflow can consume a lot of tokens. It is designed to generate consistent and comprehensive context for the AI coding agent, which may require a large amount of tokens. Please be mindful of the token usage when using this workflow.

🆕 This workflow is currently designed for new application development, not maintenance of existing application. We are planning to support maintenance of existing application in the future, but for now please use this workflow for new application development only.

🚧 **THIS IS STILL A WORK IN PROGRESS**. We are continuously improving the workflow and the skills, so please expect some changes and updates in the future. We welcome any feedback and suggestions for improvement.