Compound Context (CO2) Workflow

An opinionated workflow for AI-driven software development that emphasizes structured context.

Compound Context (CO2) Workflow

https://compound-context.com

LogoDescription
co2.svgan OPINIONATED approach to software development using AI coding agents. It emphasizes the importance of comprehensive and structured context to reduce AI hallucination and AI slop:

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:

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

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:

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

SkillExample Skill InvocationObjectiveOutput
util-projectsync/util-projectsyncProject Structure Sync & ValidationValidates dependencies (circular, missing, logical) across all applications in CLAUDE.md. Creates missing application folders, scaffolds PRD.md and BUG.md from templates, and adds missing module sections. Inserts [TODO] annotations in CLAUDE.md for validation failures.
util-usanalyzer/util-usanalyzer app1Quality CheckIdentify any quality issues in the PRD.md such as incomplete stories, bad references, contradictions and duplicates. Output a report with the identified issues and suggestions for improvement. Example: "User Story 1 is incomplete because it does not have the acceptance criteria."
util-ustagger/util-ustagger app1 v1.0.3TraceabilityEach newly added point in PRD.md will be tagged with a unique 9-character ID code, which can be used for traceability in the later stages of the development. Example: [USL000009], [NFRL000009], [CONL000009], [REFL000009]
util-preparek8senv/util-preparek8senv [env]K8s Infrastructure PreparationGenerates K8s StatefulSet manifests for all 3rd party supporting applications for a single target environment. Creates/updates ENVIRONMENT.md with per-environment configs. Output directly in environment/ folder (no per-environment subfolders — gitignored, each machine maintains its own copy).

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:

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

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

/mockgen-tailwind <app_name> ## For generating HTML mockup using Tailwind CSS
  • 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:

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

/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-ts-cli <app_name> ## For generating Node.js CLI application technical specification with TypeScript, Commander.js and tsup.
/specgen-react-mui <app_name> ## For generating React 19 SPA technical specification with TypeScript, Vite, Material UI.
/specgen-ts-cli <app_name> ## For generating Node.js CLI application technical specification with TypeScript, Commander.js.
  • 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:

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

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

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

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

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

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

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

- <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
SkillTechnology Stack
depgen-k8sKubernetes (Spring Boot, Laravel, Node.js)

Bug Fixing Workflow

Bug Reporting

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

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

/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
    4. 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:

- 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

DocumentDescription
CONTRIBUTING.mdFull contributor guide — repository structure, skill anatomy, development workflow, quality checklist, branch strategy and commit conventions
NEW_SKILL.mdIssue template for proposing a new skill before starting development
BUG_REPORT.mdIssue template for reporting incorrect behaviour in an existing skill
FEATURE_REQUEST.mdIssue template for suggesting improvements to the workflow or existing skills
PULL_REQUEST_TEMPLATE.mdPR template with checklists for structure, content, output contract and testing

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:

SkillTechnology Stack
specgen-spring-jpa-jtehtmxSpring Boot 3 + JTE + Tailwind + htmx
specgen-spring-jpa-restapiSpring Boot 3 REST API
specgen-laravel-eloquent-bladehtmxLaravel 12 + Blade + Tailwind + htmx
specgen-react-muiReact 19 + TypeScript 5 + Vite 6 + Material UI v6
specgen-ts-cliNode.js CLI + TypeScript + Commander.js + tsup + pkg

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: Flutter, 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:

SkillDeployment Stack
depgen-k8sKubernetes (Spring Boot, Laravel, Node.js)

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-*) — 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.