@rashidee/co2 1.2.5

package/plugin/README.md

@@ -0,0 +1,625 @@
+# Compound Context (CO2) Workflow
+
+> https://compound-context.com
+
+| Logo                | Description                                                                                                                                                                              |
+|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ![co2.svg](co2.svg) | an **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:
+~~~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._
+
+### Project Bootstrap — Brainstorm Session
+
+_For a brand-new project, the context (root `CLAUDE.md` + one `PRD.md` per application) is produced through an iterative, file-based brainstorming session instead of a one-shot generation:_
+
+1. Run `/util-projectinit "<your application idea>"` — sets up the brainstorm kit in the project folder:
+   - `<topic>.brainstorm.md` — your session document (seeded with your idea)
+   - `brainstorm-protocol.md` — the turn-based session protocol
+   - `co2-context-generation-guide.md` — the artifact rules the agent follows when drafting
+   - the `/brainstorm-loop` slash command (ships with the plugin)
+2. Fill in the `# Context` section of `<topic>.brainstorm.md` with your application idea — even one paragraph is enough; the agent probes for the rest.
+3. Run `/brainstorm-loop` — each round the agent refines the drafts (`CLAUDE.md` in Phase A, then every application's `PRD.md` in Phase B) and appends focused questions to the session document; you answer in the document and **flip a status row** to commit your turn.
+4. Flip `Session completion` to COMPLETED when satisfied — the context tree is finalized. Continue with `/util-projectsync`.
+
+> 💡 The loop is token-efficient: it blocks on a 60-second file poll and only acts on your status flip — saves alone never trigger the agent, and idle waiting costs essentially zero tokens. It is **non-destructive** — existing session files are never overwritten.
+
+### 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.
+
+> 💡 For a new project, the initial PRD.md of every application is generated by the brainstorm session above (Phase B). From then on you maintain it manually and evolve it with `/util-updprd`.
+
+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:
+
+| Skill              | Example Skill Invocation                        | Objective                                | Output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+|--------------------|-------------------------------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| util-projectinit   | /util-projectinit "app idea"                    | New Project Bootstrap (Brainstorm Setup) | Sets up a file-based brainstorming session in the project folder: generates `<topic>.brainstorm.md` from the appdev template (seeded with your idea), copies `brainstorm-protocol.md` and `co2-context-generation-guide.md`, and ensures the `/brainstorm-loop` command is installed. You fill in the session document and run `/brainstorm-loop` manually — the loop converges CLAUDE.md (Phase A) and per-application PRD.md (Phase B) round by round. Non-destructive — never overwrites existing session files.                      |
+| util-projectsync   | /util-projectsync                               | Project Structure Sync & Validation      | Validates 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 app1                           | Quality Check                            | Identify 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.3                      | Traceability                             | Each 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-updprd        | /util-updprd "add password reset for all users" | Requirement Change                       | Applies a free-form requirement change to the PRD.md files across the project. Determines the impacted applications, modules and subsections, decides per item whether to add/cancel/modify User Stories, NFRs, Constraints, References and Tests, auto-classifies the change as major/minor/patch, and layers the new/updated items under a NEW version tag on top of the existing versions in each PRD.md (prior versions kept immutable). Tags new items via util-ustagger and appends a CHANGELOG.md entry per impacted application. |
+| util-preparek8senv | /util-preparek8senv [env]                       | K8s Infrastructure Preparation           | Generates 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).                                                                                                                                                                                                                                    |
+
+## Context Artifact Preparation
+
+_The four artifact generation steps below (Data Model → HTML Mockup → Technical Specification → Test Specification) can each be run individually, or orchestrated in one shot:_
+
+~~~bash
+/conductor-feature-prepare <app_name> [version:<version>] [module:<module>] ## Runs util-ustagger, modelgen-*, mockgen-*, specgen-* and testgen-functional in sequence
+~~~
+
+When multiple versions are resolved, they are processed sequentially in ascending semver order — all artifacts for version N are fully generated before version N+1 begins. Say "resume preparation" to continue from where a previous session left off.
+
+## 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 Tailwind CSS + HTMX + Alpine.js
+/mockgen-shadcn <app_name>    ## For generating React + shadcn/ui mockups (Vite + React Router, built to dist/)
+~~~
+
+- Input:
+  - PRD.md (User Stories, Non-Functional Requirements and Constraints)
+  - Data Model (to understand the data structure and relationships)
+- Output:
+  - HTML mockup screens (assets only) in the application's `context/mockup/` folder
+  - **Mockup Hub** at `<root>/mockup` — ONE zero-dependency Node.js server (`npm start`, no install needed) that serves the mockups of ALL applications, with a landing page listing every application and role (roles are unclickable until their mockups are ready) and a configurable port (`PORT` env var or `mockup.config.json`)
+  - **MOCKUP.html** — A per-application screen index (served by the hub at `/{app_slug}`) 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
+- mockup ## At project root — the shared Mockup Hub (ONE Node app serving ALL applications' mockups)
+  - server.js
+  - package.json
+  - mockup.config.json ## Configurable port (or PORT env var)
+- <app_folder>
+  - context
+    - mockup ## Assets only — no per-app server
+      - <role_1_folder>
+        - screen1.html
+        - screen2.html
+      - <role_2_folder>
+        - screen1.html
+        - screen2.html
+      - MOCKUP.html ## Per-application screen index (served by the hub at /{app_slug})
+      - mockup-manifest.json ## Hub discovery manifest (app, stack, roles, version)
+~~~
+
+### 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-nextjs-react-tailwind <app_name> ## For generating Next.js 15 full-stack web application technical specification with App Router, Server Actions, Drizzle + SQLite, tiered auth (OIDC / hand-rolled sessions / Better Auth), Tailwind CSS v4 and shadcn/ui.
+/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.
+/specgen-node-cli-web <app_name> ## For generating self-hosted Node.js web application technical specification distributed as a global npm CLI — Hono, embedded React SPA, Drizzle + SQLite, hand-rolled sessions 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._
+
+>⚠️ Requires the context artifacts (models, mockups, specifications, test specs) to already exist — run `/conductor-feature-prepare <app_name>` first if they don't. Say "resume implementation" to continue from where a previous session left off.
+
+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
+  - **TRACEABILITY.md** — per-application requirement-to-code traceability matrix (generated by `tracegen-matrix` as the final step, see below)
+
+### Traceability Matrix
+
+_The skill goal is to link every PRD requirement ID (User Stories, NFRs, Constraints) and bug code to the source code that implements it._
+
+>⚠️ This step is automatically invoked as the final traceability step of `conductor-feature-develop` and `conductor-defect`. You can also invoke it manually.
+
+Example skill invocation for traceability matrix generation:
+~~~bash
+/tracegen-matrix <app_name> [version] [module] ## Generates/updates the per-application traceability matrix
+~~~
+
+- Input:
+  - PRD.md (requirement IDs) and per-module SPEC.md files (traceability tables)
+  - Application source code — resolves links primarily from the in-source CO2 traceability comments (`Implements:`, `NFR:`, `Constraints:`, `Bug fixes:`) written during development and bug fixing, with a name-based source-scan fallback
+  - (Optional) codebase-memory MCP for precision enrichment — works fully without it
+- Output:
+  - **context/TRACEABILITY.md** — matrix linking every requirement ID and bug code to the implementing source files
+
+### 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
+~~~
+
+| Skill | Technology Stack |
+|-------|-----------------|
+| `depgen-k8s` | Kubernetes (Spring Boot, Laravel, Node.js) |
+
+# 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
+  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:
+~~~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, DEVTOOL.md and ENVIRONMENT.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.
+- The brainstorm kit files (`<topic>.brainstorm.md`, `brainstorm-protocol.md`, `co2-context-generation-guide.md`) also live at the project root when the project was bootstrapped via `/util-projectinit`.
+- Example of the directory structure:
+
+~~~
+- <project_folder>
+  - CLAUDE.md
+  - DEVTOOL.md (per developer — local CLI tools)
+  - ENVIRONMENT.md (per developer — per-environment configs/credentials)
+  - <topic>.brainstorm.md (brainstorm session document — generated by util-projectinit)
+  - brainstorm-protocol.md (brainstorm turn protocol — copied by util-projectinit)
+  - co2-context-generation-guide.md (artifact rules for the brainstorm — copied by util-projectinit)
+  - 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
+
+| Document | Description |
+|----------|-------------|
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Full contributor guide — repository structure, skill anatomy, development workflow, quality checklist, branch strategy and commit conventions |
+| [NEW_SKILL.md](NEW_SKILL.md) | Issue template for proposing a new skill before starting development |
+| [BUG_REPORT.md](BUG_REPORT.md) | Issue template for reporting incorrect behaviour in an existing skill |
+| [FEATURE_REQUEST.md](FEATURE_REQUEST.md) | Issue template for suggesting improvements to the workflow or existing skills |
+| [PULL_REQUEST_TEMPLATE.md](PULL_REQUEST_TEMPLATE.md) | PR 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:
+
+| Skill | Technology Stack |
+|-------|-----------------|
+| `specgen-spring-jpa-jtehtmx` | Spring Boot 3 + JTE + Tailwind + htmx |
+| `specgen-spring-jpa-restapi` | Spring Boot 3 REST API |
+| `specgen-laravel-eloquent-bladehtmx` | Laravel 12 + Blade + Tailwind + htmx |
+| `specgen-react-mui` | React 19 + TypeScript 5 + Vite 6 + Material UI v6 |
+| `specgen-react-tailwind` | React 19 + TypeScript 5 + Vite 6 + Tailwind CSS v3 + Headless UI v2 + Heroicons |
+| `specgen-nextjs-react-tailwind` | Next.js 15 (App Router) + React 19 + TypeScript 5 + Tailwind CSS v4 + shadcn/ui + Drizzle ORM + SQLite + tiered auth (OIDC / hand-rolled sessions / Better Auth) + Biome + Vitest + Playwright |
+| `specgen-flutter-riverpod` | Flutter 3 + Dart 3 + Riverpod 2 + Hive 2 + Dio 5 + go_router 14 + Firebase Messaging |
+| `specgen-ts-cli` | Node.js CLI + TypeScript + Commander.js + tsup + pkg |
+| `specgen-node-cli-web` | Self-hosted Node.js web app as a global npm CLI — Node 22 + commander 12 + Hono 4 + embedded React 19/Vite 6 SPA + Tailwind CSS v4 + shadcn/ui + Drizzle ORM + SQLite + hand-rolled scrypt sessions + tsup + Biome + Vitest + Playwright |
+| `specgen-sdk-java` | Java SDK library — Maven Multi-Release fat JAR (JDK 8 baseline + JDK 11+ overlay) + OkHttp |
+
+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**: 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:
+
+| Skill | Deployment Stack |
+|-------|-----------------|
+| `depgen-k8s` | Kubernetes (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-*`)** — Currently supports `mockgen-tailwind` (Tailwind + HTMX + Alpine.js) and `mockgen-shadcn` (React + Vite + shadcn/ui), both served by the single shared Mockup Hub at `<root>/mockup`. 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](https://github.com/rashidee/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.
+