Spec System - Project Coding Standards Auto-Injection

The Spec system ensures your project’s coding standards are automatically injected into every sub-agent — both external model calls (Codex/Gemini) and Team Builders — without manually pasting specs into each invocation.

Directory Structure

<project-root>/
└── .ccg/spec/
    ├── backend/
    │   └── index.md        # Backend coding standards
    ├── frontend/
    │   └── index.md        # Frontend coding standards
    └── guides/
        └── index.md        # Cross-module general guidelines

Example Spec File

backend/index.md:

# Backend Coding Standards

## API Design
- RESTful style, plural nouns in paths
- Unified response format: { code, data, message }
- Use standard HTTP status codes for errors

## Database
- All tables must have created_at / updated_at
- Soft delete via deleted_at field
- Index naming: idx_tablename_fieldname

## Authentication
- JWT Bearer Token in Authorization header
- Token expiry 2h, Refresh Token 7d

Automatic Injection Mechanism

context.jsonl

Each task directory contains a context.jsonl file that defines which spec files that task requires:

{"type": "spec", "path": ".ccg/spec/backend/index.md"}
{"type": "spec", "path": ".ccg/spec/guides/index.md"}
{"type": "plan", "path": ".ccg/tasks/add-jwt-auth/plan.md"}

Injection Timing

The subagent-context.js hook triggers injection at two moments:

1. During codeagent-wrapper calls — When Claude invokes the wrapper to run Codex/Gemini analysis, relevant specs are injected into the prompt
2. During TeamCreate — When spawning Builder teammates, the specs for each Builder’s assigned module are injected automatically

Injection Flow

Claude calls codeagent-wrapper --backend codex
    ↓
subagent-context.js hook intercepts (PreToolUse)
    ↓
Reads current task's context.jsonl
    ↓
Loads .ccg/spec/backend/index.md content
    ↓
Injects into wrapper's prompt prefix
    ↓
Codex executes already "knowing" the project's backend standards

Spec Routing

The engine automatically selects which spec files to inject based on the task’s domain classification:

Task Domain	Injected Specs
backend	spec/backend/index.md + spec/guides/index.md
frontend	spec/frontend/index.md + spec/guides/index.md
fullstack	All spec files

Creating Spec Files

Manual Creation

Create the .ccg/spec/ structure in your project root and write standards following the format above.

Via /ccg:init

The /ccg:init command scans your codebase during project initialization and generates an initial spec skeleton:

# Run in the project root
/ccg:init

The generated skeleton contains common standard templates matching the detected tech stack.

Team Collaboration

Tip

The .ccg/spec/ directory should be committed to Git. It represents your project’s coding standards and should be shared across the team. Meanwhile, .ccg/tasks/ is transient execution state and belongs in .gitignore.

Recommended .gitignore configuration:

# CCG task state (transient)
.ccg/tasks/

# CCG specs (do NOT ignore — commit to Git)
# .ccg/spec/  ← do not add this line

The Impact of Specs

Comparison with and without the spec system:

Without specs: Codex/Gemini write code according to their own “habits” — inconsistent naming (snake_case vs camelCase), varied error formats, and no alignment with your existing codebase.

With specs: All sub-agents produce code that follows unified naming conventions, API formats, and error handling patterns consistent with the rest of your project.