@noanswer/context-compose/README.md

Orchestrate complex AI interactions with Context Compose. A powerful CLI and server for building, validating, and managing context for large language models using the Model Context Protocol (MCP).

# Context Compose

**Composable Contexts for High-Quality, AI-Powered Development**

## Why Context Compose?

While high-level requirements documents (like PRDs) provide overall project goals, they often lack the detailed, task-specific context needed for day-to-day development. Each unit of work—be it a new feature, a bug fix, or a refactor—requires its own focused set of rules, expert perspectives, and guidelines to ensure consistency and quality.

Context Compose provides a simple yet powerful system for defining, composing, and managing these granular contexts. It's like Docker Compose, but for your AI development workflow.

**The Problem:**

- High-level documents are too broad for specific coding tasks.
- Developers constantly switch between tasks that require different mindsets and rules.
- Inconsistent approaches across team members for similar tasks lead to quality issues.
- Repetitive and manual context-setting for AI assistants is time-consuming.

**The Solution:**
Context Compose allows you to define reusable, task-specific contexts that can be composed on demand. This ensures every task is approached with the right expertise and standards, leading to consistent, high-quality results across your entire team.

## Key Features

- 🎯 **Task-Specific Contexts**: Create dedicated contexts for features, bug fixes, refactoring, API design, and more.
- 🧩 **Composable Architecture**: Mix and match components—like expert personas, coding rules, and specialized tools—to build the perfect context for any task.
- 🔧 **Fully Customizable**: The system is built on a simple directory structure. You can override existing assets or create entirely new categories (e.g., `security`, `testing-philosophy`) to fit your project's unique needs.
- ⌨️ **Simple CLI**: A straightforward command-line interface (`start-context`) makes it easy to load contexts and integrate with your existing workflows.
- 📂 **Clear File-Based Structure**: All contexts and assets are managed as simple YAML files, making them easy to version control, share, and edit.

## MCP Server Integration

To integrate Context Compose with an MCP-compatible client (like an IDE extension), you can register it as an MCP server.

For integration with automated tools, use the following configuration in your settings file:

```json
{
  "mcpServers": {
    "context-compose": {
      "command": "npx",
      "args": ["-y", "@noanswer/context-compose@latest"]
    }
  }
}
```

This configuration tells the client how to start the `context-compose` server, ensuring it runs non-interactively.

## Project Initialization

Before using contexts, you need to initialize your project. This sets up the necessary `.contextcompose` directory and default assets.

Copy and paste the following into your prompt to run it.

```
initialize my project using context-compose
```

**What happens**:

- The `init` command runs.
- A `.contextcompose` directory is created in your project root.
- Default assets (personas, rules, etc.) are copied into it, ready for you to use or customize.

## How It Works

Context Compose works by reading a main context file and dynamically assembling a final, detailed prompt from various component files. The entire system is driven by a special directory in your project root: `.contextcompose/`.

1.  **The `.contextcompose/` Directory**: When you start a task, you tell Context Compose which context to use (e.g., `feature`).
2.  **Main Context File**: It looks for a corresponding file, like `.contextcompose/feature-context.yaml`.
3.  **The `context` Block**: Inside this file, a `context` block lists all the components to include. It references other YAML files organized by category (e.g., `personas`, `rules`).
4.  **Dynamic Composition**: The tool reads each referenced file, extracts its prompt, and combines everything into a single, comprehensive prompt.

**The best part? It's fully extensible.** You can create any category you want. If you add a `security:` section to your context file, the tool will automatically look for files in a `.contextcompose/security/` directory.

### Context Structure Example

Here is an example of what a `.contextcompose/api-context.yaml` file might look like. It defines the context for building a new API endpoint.

```yaml
# .contextcompose/api-context.yaml
version: 1
kind: context
name: 'api-development'
description: 'Context for creating new API endpoints.'

# This is the base prompt for the main context file itself.
prompt: 'You are building a new API endpoint. Follow all the guidelines provided.'
enhanced-prompt: 'Your mission is to construct a robust, secure, and well-documented API endpoint. Pay close attention to the expert advice from the persona, adhere strictly to all specified rules, and utilize the recommended tools (MCPs).'

# Here we compose the context from other files.
context:
  personas:
    - personas/uncle-bob.yaml
  rules:
    - rules/api-design.yaml
    - rules/clean-code.yaml
  # This is a custom category!
  security:
    - security/owasp-top-10.yaml
  mcps:
    - mcps/sequential-thinking.yaml
```

## 🛠️ Customization in Detail

Customizing Context Compose is its core strength. You can override built-in assets or create new ones from scratch.

**Scenario**: Let's add a new category for "Company-Wide Principles".

1.  **Create a New Directory**: Inside your project's `.contextcompose/` directory, create a new folder named `principles`.

    ```
    .contextcompose/
    ├── principles/
    └── ...
    ```

2.  **Create Your Asset File**: Inside the new directory, create a YAML file. The `kind` should match the singular version of the directory name.

    ```yaml
    # .contextcompose/principles/team-values.yaml
    version: 1
    kind: principle # Matches the 'principles' directory
    name: 'team-values'
    description: 'The core values our engineering team follows.'
    prompt: |
      - Always prioritize clarity over cleverness.
      - Leave code better than you found it.
      - Communicate proactively.
    ```

3.  **Reference it in Your Context**: Now, you can add `principles` to any `*-context.yaml` file.

    ```yaml

    # .contextcompose/feature-context.yaml

    version: 1
    kind: context
    name: 'feature'

    # ...

    context:
      personas: - personas/frontend-expert.yaml
      rules: - rules/typescript-best-practices.yaml

      # Your new custom category is now part of the context!

      principles: - principles/team-values.yaml
      `When you run`context-compose start-context feature`, the content of `team-values.yaml` will be automatically included in the final prompt.

    ```

4.  **Validate Your Assets**

    After creating or modifying asset files, it's a good practice to validate them. Context Compose provides a `validate` command to check for common errors.

    ```bash
    npx @noanswer/context-compose validate
    ```

    This command will check all your asset files inside the `.contextcompose` directory and verify that:

    - The YAML syntax is correct.
    - All required fields (`version`, `kind`, `name`, `description`, `prompt`) are present.

    This helps you catch errors early and ensures your contexts are correctly structured.

## 🎭 User Scenarios

### 1. Project Initialization

Before using contexts, you need to initialize your project. This sets up the necessary `.contextcompose` directory and default assets.

> initialize my project using context-compose

**What happens**:

- The `init` command runs.
- A `.contextcompose` directory is created in your project root.
- Default assets (personas, rules, etc.) are copied into it, ready for you to use or customize.

### 2. Frontend Developer: Building a New React Component

A developer is tasked with building a new search component using React and TypeScript. They would start by telling their AI assistant:

> start-context react-feature -e using context-compose

**What they get**:

- Guidance from a **React Expert Persona** on component structure and state management.
- Strict **TypeScript Rules** for type safety and best practices.
- Checklists from **Testing Rules** to ensure Jest/RTL coverage.
- A **Sequential Thinking** framework to break down the task.

### 3. Backend Developer: Creating a Secure API Endpoint

A developer needs to create a new RESTful API endpoint for user authentication. They would start by telling their AI assistant:

> start-context secure-api using context-compose

**What they get**:

- Principles from **API Design Rules** for RESTful patterns.
- Critical reminders from custom **Security Rules** based on OWASP guidelines.
- Best practices from **Clean Code Rules** for maintainability.

### 4. Team Lead: Performing a Code Review

A team lead wants to ensure a consistent and thorough code review process. They would start by telling their AI assistant:

> start-context code-review using context-compose

**What they get**:

- A **Code Quality Checklist** from the rules to standardize the review.
- The perspective of an **Architecture Expert Persona** to check for anti-patterns.
- Guidelines on providing constructive feedback.

## 🧪 테스트 자동화

Context Compose는 코드 수정 후 CLI와 MCP 도구의 정상 동작을 자동으로 검증하는 포괄적인 테스트 시스템을 제공합니다.

### 테스트 스위트

- **🔥 Smoke Tests**: 핵심 기능들의 빠른 검증
- **🧩 Unit Tests**: 개별 함수와 모듈의 상세 테스트
- **🔗 Integration Tests**: MCP 서버와 CLI의 통합 테스트
- **🌐 E2E Tests**: 실제 사용자 시나리오 테스트

### 테스트 실행 명령어

```bash
# 모든 테스트 실행
npm run test:all

# 개별 테스트 스위트 실행
npm run test:smoke        # 빠른 검증
npm run test:unit         # 단위 테스트

# 테스트 커버리지 확인
npm run test:coverage

# 자동화 스크립트 실행 (모든 검증 포함)
npm run test:automation
```

### 자동화된 검증 항목

✅ **CLI 명령어 동작 확인**

- `init`, `start-context`, `validate` 명령어 정상 실행
- 에러 케이스 처리 검증
- 다양한 프로젝트 구조에서의 동작 테스트

✅ **MCP 서버 통합 검증**

- 서버 시작/종료 테스트
- 각 도구의 정상 동작 확인
- 스키마 검증 및 에러 처리

✅ **파일 시스템 작업 검증**

- 프로젝트 초기화 확인
- 컨텍스트 파일 생성/읽기 테스트
- 권한 및 경로 처리 검증

✅ **안정성 테스트**

- 동시 실행 안정성
- 메모리 사용량 모니터링

### CI/CD 통합

GitHub Actions를 통해 모든 커밋과 PR에서 자동으로 테스트가 실행됩니다:

1. **코드 품질 검사** - Biome 린팅 및 TypeScript 타입 검사
2. **Smoke 테스트** - 핵심 기능 빠른 검증
3. **병렬 테스트 실행** - 단위 테스트 동시 실행
4. **테스트 결과 요약** - 상세한 결과 리포트 생성

### 개발자를 위한 혜택

🚀 **자신감 있는 배포**: 모든 테스트 통과 시 CLI와 MCP 도구의 정상 동작 보장

🔧 **빠른 피드백**: Smoke 테스트로 핵심 기능 문제를 즉시 발견

📊 **투명한 품질**: 테스트 커버리지로 코드 품질 추적

⚡ **효율적인 개발**: 수동 검증 없이 자동화된 테스트로 개발 속도 향상

## 📦 Built-in Assets Structure

Context Compose comes with a set of pre-built assets to get you started. You can use them as is or override them by creating files with the same name in your project's `.contextcompose/` directory.

- **`assets/personas/`**: Expert personas providing specialized knowledge (e.g., `frontend-expert`, `backend-expert`, `devops-expert`).
- **`assets/rules/`**: Development guidelines and best practices (e.g., `clean-code`, `api-design`, `testing-principles`).
- **`assets/actions/`**: Definitions for specific AI tasks and operations.
- **`assets/mcps/`**: Integrations with Model Context Protocols for enhanced AI capabilities (e.g., `sequential-thinking`, `web-search`).

## 🔗 Links

- [GitHub Repository](https://github.com/weproud/context-compose)
- [Issue Tracker](https://github.com/weproud/context-compose/issues)
- [NPM Package](https://www.npmjs.com/package/@noanswer/context-compose)