context-engineer 1.1.0

package/templates/claude/.claude/workflow/interfaces/phase-contract.md

@@ -0,0 +1,157 @@
+# Phase Interface Contract
+
+Every workflow phase — built-in or plugin — follows this contract.
+
+## Generic Interface
+
+```
+Input:  [required artifact files] + [.context/ files for reference]
+Output: [artifact files produced]
+Plugin types: skill | mcp | script
+Checkpoint: configurable (true/false in config.md)
+```
+
+## Plugin Resolution Order
+
+```
+1. Config override  → .context/workflow/config.md "Plugin Overrides" table
+2. Convention dir   → .claude/workflow/phases/{phase-id}/SKILL.md
+3. Built-in default → .claude/skills/dev-{phase}/SKILL.md
+```
+
+## Phase Definitions
+
+### P0: Requirements Gathering
+- **Input**: User conversation / issue links / raw text
+- **Output**: `.context/workflow/artifacts/requirements.md`
+- **Context**: `business/overview.md`, `business/domain-model.md`
+
+### P1: PRD Generation
+- **Input**: `artifacts/requirements.md`
+- **Output**: `artifacts/prd.md`
+- **Context**: `business/*`, `architecture/overview.md`, `architecture/api-surface.md`
+
+### P2: Task Decomposition
+- **Input**: `artifacts/prd.md`
+- **Output**: `artifacts/tasks.json`
+- **Context**: `architecture/overview.md`, `architecture/module-graph.md`, `conventions/patterns.md`
+
+### P3: Dependency Analysis
+- **Input**: `artifacts/tasks.json`
+- **Output**: `artifacts/dep-graph.json`
+- **Context**: `architecture/module-graph.md`
+
+### P4: Agent Execution
+- **Input**: `artifacts/dep-graph.json` + `artifacts/tasks.json` + `agents/team-config.md`
+- **Output**: `artifacts/execution-log.md` + code changes
+- **Context**: Per-task `context_files` + `conventions/*`
+- **Agent team**: Uses role definitions from `.claude/workflow/agents/` (implementer, reviewer, tester)
+- **Patterns**: `default` (implement→review→test), `lite` (implement→test), `implement-only`
+
+### P5: Quality Gate
+- **Input**: Code changes from P4
+- **Output**: `artifacts/quality-report.md`
+- **Context**: `conventions/testing.md`, `constitution.md`
+
+### P6: Commit & Integration
+- **Input**: Verified code changes + `artifacts/quality-report.md`
+- **Output**: Git commits
+- **Context**: `conventions/git.md`
+
+### P7: Knowledge Capture
+- **Input**: All changes from this workflow cycle
+- **Output**: Updated `.context/` files
+- **Context**: Full `.context/` system
+
+## Writing a Custom Plugin (Skill Type)
+
+Place a `SKILL.md` file in `.claude/workflow/phases/{phase-id}/`:
+
+```markdown
+---
+phase: quality-gate
+replaces: dev-quality
+requires: [node, playwright]
+---
+
+# Custom Quality Gate
+
+## Input
+- Reads: artifacts/execution-log.md, git diff of changes
+
+## Output
+- Writes: artifacts/quality-report.md
+
+## Implementation
+[Your custom instructions here...]
+```
+
+### Writing a Custom Agent Role
+
+Place a role definition in `.claude/workflow/agents/`:
+
+```markdown
+# Agent Role: [Name]
+
+## Identity
+[Who is this agent and what is its responsibility]
+
+## Core Principles
+[Key behavioral rules]
+
+## Behavior
+[Step-by-step process the agent follows]
+
+## Output Format
+[Structured output the agent must produce]
+```
+
+Reference it in `team-config.md` to include it in a collaboration pattern.
+
+### Rules for Plugins
+1. **Accept** the same input artifacts as the phase it replaces
+2. **Produce** the same output artifacts (same file names, compatible schema)
+3. **Document** requirements in frontmatter (dependencies, env vars, etc.)
+
+## Artifact Schemas
+
+### tasks.json
+```json
+{
+  "feature": "feature-name",
+  "created_at": "ISO-8601",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Short task title",
+      "description": "What to implement and why",
+      "type": "feature | bugfix | refactor | test | docs | infra",
+      "scope": "backend | frontend | fullstack | database | infra",
+      "files_to_modify": ["src/..."],
+      "files_to_create": ["src/..."],
+      "depends_on": [],
+      "acceptance_criteria": ["..."],
+      "context_files": ["architecture/..."],
+      "complexity": "small | medium | large",
+      "test_requirements": "..."
+    }
+  ]
+}
+```
+
+### dep-graph.json
+```json
+{
+  "groups": [
+    {
+      "order": 1,
+      "tasks": ["T1", "T2"],
+      "isolation": { "T1": "none", "T2": "none" }
+    }
+  ],
+  "critical_path": ["T1", "T3"],
+  "file_conflicts": {},
+  "total_groups": 1,
+  "max_parallelism": 2
+}
+```

package/templates/claude/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+> Claude Code-specific configuration. For the full context system, see `.context/`.
+
+## Context System
+
+This project uses a structured context system. Follow this loading protocol:
+
+1. **Read `.context/constitution.md`** for principles and the Context Loading Route Table
+2. **Use the Route Table** to determine which context files to load for your current task
+3. Do NOT load all context files — only load what is relevant
+
+## Available Skills
+
+### Context Management
+- `/bootstrap-context` — Build the .context/ system for a new project
+- `/update-context` — Sync context files after code changes (detects uncommitted + new files)
+- `/review-context` — Audit context system health (auto-fixes by default)
+- `/sync` — Fast regeneration of all auto-generated files + concept index
+
+### Development Workflow (`/dev`)
+- `/dev` — Full automated SDLC pipeline (orchestrator)
+- `/dev-requirements` — P0: Gather and structure requirements
+- `/dev-prd` — P1: Generate PRD from requirements
+- `/dev-decompose` — P2: Break PRD into tasks with file scope
+- `/dev-deps` — P3: Analyze task dependencies, produce execution plan
+- `/dev-execute` — P4: Orchestrate agents to implement tasks in parallel
+- `/dev-quality` — P5: Run build/lint/test quality gates
+- `/dev-commit` — P6: Create git commits following conventions
+- `/dev-capture` — P7: Update .context/ with new knowledge
+
+## Rules
+
+- When modifying code that affects architecture, data models, or APIs, update corresponding `.context/` files
+- When fixing non-trivial bugs, record in `.context/experience/debugging.md`
+- When making significant decisions, create an ADR in `.context/architecture/decisions/`
+- Files marked `<!-- AUTO-GENERATED -->` should not be edited manually
+
+## Quick Reference
+
+```bash
+# Build
+[BUILD_COMMAND]
+
+# Test
+[TEST_COMMAND]
+
+# Check context drift
+bash scripts/detect-drift.sh
+```

package/templates/core/.context/_meta/concepts.md

@@ -0,0 +1,9 @@
+# Concept Index
+
+<!-- AUTO-GENERATED: Run /sync to regenerate. -->
+<!-- generated-at: N/A -->
+
+> Inverted index mapping concepts to context files.
+> Search this file to find which context files discuss a topic without loading all files.
+
+No concept index generated yet. Run `/sync` to build.

package/templates/core/.context/_meta/drift-report.md

@@ -0,0 +1,16 @@
+# Drift Detection Report
+
+<!-- AUTO-GENERATED by scripts/detect-drift.sh -->
+<!-- generated-at: N/A -->
+
+## Status: No report generated yet
+
+Run `scripts/detect-drift.sh` to generate a drift detection report.
+
+## Report Format
+
+When generated, this file will contain:
+
+| File | Status | Details |
+|------|--------|---------|
+| [context file] | [OK / STALE / DRIFT] | [Description of drift] |

package/templates/core/.context/_meta/last-sync.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0",
+  "contextEngineerVersion": "__CE_VERSION__",
+  "lastFullSync": null,
+  "files": {}
+}

package/templates/core/.context/_meta/schema.md

@@ -0,0 +1,242 @@
+# Context File Schema
+
+> Self-documenting schema that defines the format, conventions, and size budgets for all context files.
+
+## General Rules
+
+1. **Format**: All context files are Markdown (`.md`), except `last-sync.json`
+2. **Encoding**: UTF-8
+3. **Line Endings**: LF (Unix-style)
+4. **Size Budget**: Each file has a maximum line count (see constitution.md). When exceeded, the file must be split or compacted.
+5. **Self-Contained**: Each file should be understandable on its own without requiring other context files to be loaded simultaneously.
+
+## Metadata Comments
+
+Every context file should include these HTML comments near the top:
+
+```markdown
+<!-- confidence: high|medium|low -->
+<!-- source: [list of files/sources analyzed to generate this content] -->
+<!-- last-updated: YYYY-MM-DD -->
+```
+
+- `confidence`: How reliable the content is (set during bootstrap, updated during validation)
+- `source`: Traceability — which code files or documents were analyzed
+- `last-updated`: When the content was last modified
+
+## Auto-Generated Files
+
+Files that can be 100% generated from code must include this header:
+
+```markdown
+<!-- AUTO-GENERATED: Do not edit manually. Run scripts/sync-context.sh to regenerate. -->
+<!-- generated-from: [source files/patterns] -->
+<!-- generated-at: YYYY-MM-DDTHH:MM:SSZ -->
+```
+
+Auto-generated files:
+- `architecture/data-model.md` — from ORM models / migration files
+- `architecture/api-surface.md` — from route definitions / OpenAPI specs
+- `architecture/dependencies.md` — from package manifest files
+- `architecture/class-index.md` — from source code class/struct/interface definitions (via `scripts/extract-structure.sh`)
+- `_meta/concepts.md` — inverted concept-to-file index (via `/sync`)
+
+## File Templates
+
+### Business Files
+
+```markdown
+# [Title]
+
+<!-- confidence: medium -->
+<!-- source: [analyzed files] -->
+<!-- last-updated: YYYY-MM-DD -->
+
+## Summary
+[3-5 line summary of this file's content]
+
+## [Content Sections...]
+[Structured content relevant to the file's purpose]
+```
+
+### Architecture Decision Record (ADR)
+
+```markdown
+# ADR-{NNN}: [Title]
+
+<!-- last-updated: YYYY-MM-DD -->
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[What is the issue that we're seeing that is motivating this decision?]
+
+## Decision
+[What is the change that we're proposing and/or doing?]
+
+## Consequences
+[What becomes easier or more difficult to do because of this change?]
+```
+
+### Experience Entry
+
+```markdown
+### YYYY-MM-DD: [Short Title]
+- **Context**: [What was happening when this was discovered]
+- **Root Cause**: [Why it happened]
+- **Resolution**: [How it was fixed]
+- **Prevention**: [What was done to prevent recurrence]
+- **Tags**: #tag1 #tag2
+```
+
+### Feature Spec (OpenSpec-style)
+
+```markdown
+# Feature: [Feature Name]
+
+<!-- confidence: high -->
+<!-- last-updated: YYYY-MM-DD -->
+
+## Overview
+[What this feature does and why it exists]
+
+## User Stories
+- As a [role], I want to [action], so that [benefit]
+
+## Requirements
+### Functional
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+
+### Non-Functional
+- [ ] [Performance, security, etc.]
+
+## Data Model Changes
+[Any new entities, fields, or relationships]
+
+## API Changes
+[New or modified endpoints]
+
+## Design Notes
+[Implementation approach, trade-offs considered]
+```
+
+### Module Graph
+
+```markdown
+# Module Graph
+
+<!-- confidence: medium -->
+<!-- source: [analyzed files] -->
+<!-- last-updated: YYYY-MM-DD -->
+
+## Subsystems
+[Table: Module | Directory | Responsibility | Key Classes]
+
+## Dependency Graph
+[ASCII diagram of module dependencies]
+
+## Module Interfaces
+[Per-module: public entry points, depends on, depended by]
+
+## Namespace / Directory Mapping
+[Table: Namespace | Directory | File Count]
+```
+
+### Data Flow
+
+```markdown
+# Data Flow & Pipelines
+
+<!-- confidence: medium -->
+<!-- source: [analyzed files] -->
+<!-- last-updated: YYYY-MM-DD -->
+
+## Application Lifecycle
+[Startup → Main Loop → Shutdown]
+
+## Core Pipelines
+[Per-pipeline: purpose, trigger, stage diagram, data transformations]
+
+## Threading / Concurrency Model
+[Table: Thread/Task | Responsibility | Communicates With]
+
+## Event / Message Flow
+[Table: Event | Producer | Consumer(s) | Payload]
+```
+
+### Class Index (Auto-Generated)
+
+```markdown
+# Class Index
+
+<!-- AUTO-GENERATED: Run scripts/extract-structure.sh to regenerate. -->
+
+## Core Classes by Module
+[Per-module table: Class | File | Role | Description]
+[Role categories: Base class, Interface, Facade, Core, Enum]
+
+## Inheritance Trees
+[ASCII trees for classes with 3+ descendants]
+
+## Key Interfaces
+[Table: Interface | File | Implemented By | Purpose]
+```
+
+### Change Proposal
+
+```markdown
+# Change: [Change Name]
+
+<!-- last-updated: YYYY-MM-DD -->
+
+## Motivation
+[Why this change is needed]
+
+## Proposal
+[What we want to do]
+
+## Impact Analysis
+- **Files affected**: [list]
+- **Breaking changes**: [yes/no, details]
+- **Context files to update**: [list of .context/ files that need updating]
+```
+
+### Concept Index (Auto-Generated)
+
+```markdown
+# Concept Index
+
+<!-- AUTO-GENERATED: Run /sync to regenerate. -->
+<!-- generated-at: YYYY-MM-DDTHH:MM:SSZ -->
+
+> Inverted index mapping concepts to context files.
+> Search this file to find which context files discuss a topic without loading all files.
+
+| Concept | Discussed In |
+|---------|-------------|
+| concept-name | relative/path/to/file1.md, relative/path/to/file2.md |
+```
+
+Concept extraction rules:
+- `##` and `###` headings → lowercased, spaces replaced with hyphens
+- `**bold terms**` → lowercased
+- First-column entries in markdown tables → lowercased
+- Cap at 300 lines; if exceeded, keep only concepts appearing in 2+ files
+
+## last-sync.json Schema
+
+```json
+{
+  "version": "1.0",
+  "lastFullSync": "YYYY-MM-DDTHH:MM:SSZ",
+  "files": {
+    "business/overview.md": {
+      "lastUpdated": "YYYY-MM-DDTHH:MM:SSZ",
+      "sourceHash": "sha256-of-source-files",
+      "confidence": "high"
+    }
+  }
+}
+```

package/templates/core/.context/architecture/api-surface.md

@@ -0,0 +1,52 @@
+<!-- AUTO-GENERATED: Do not edit manually. Run scripts/sync-context.sh to regenerate. -->
+<!-- generated-from: [route definitions / OpenAPI spec] -->
+<!-- generated-at: YYYY-MM-DDTHH:MM:SSZ -->
+
+# API Surface
+
+## Summary
+
+<!-- API contracts, endpoints, authentication, and protocols -->
+
+[PLACEHOLDER: Run `scripts/sync-context.sh` or `/bootstrap-context` to auto-generate from route definitions and OpenAPI specs.]
+
+## Base URL
+
+- Development: `http://localhost:[PORT]`
+- Production: `[PROD_URL]`
+
+## Authentication
+
+- Method: [e.g., JWT Bearer, OAuth 2.0, API Key]
+- Header: `Authorization: Bearer <token>`
+
+## Endpoints
+
+### [Module/Controller 1]
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | `/api/v1/[resource]` | [Description] | [Yes/No] |
+| POST | `/api/v1/[resource]` | [Description] | [Yes/No] |
+| PUT | `/api/v1/[resource]/:id` | [Description] | [Yes/No] |
+| DELETE | `/api/v1/[resource]/:id` | [Description] | [Yes/No] |
+
+### [Module/Controller 2]
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | `/api/v1/[resource]` | [Description] | [Yes/No] |
+
+## Common Response Formats
+
+```json
+// Success
+{ "data": {...}, "message": "OK" }
+
+// Error
+{ "error": { "code": "ERROR_CODE", "message": "Description" } }
+```
+
+## Rate Limiting
+
+[Rate limiting rules if applicable]

package/templates/core/.context/architecture/class-index.md

@@ -0,0 +1,49 @@
+# Class Index
+
+<!-- AUTO-GENERATED: Do not edit manually. Run scripts/extract-structure.sh to regenerate. -->
+<!-- generated-from: source code analysis -->
+<!-- generated-at: YYYY-MM-DDTHH:MM:SSZ -->
+
+## Summary
+
+<!-- Auto-generated index of core classes, interfaces, and key data structures per module.
+     Only includes: base classes, abstract classes, interfaces, facade/manager/system classes,
+     and core data structures. Internal implementation classes are excluded. -->
+
+[PLACEHOLDER: Run `/bootstrap-context` or `scripts/extract-structure.sh` to auto-generate.]
+
+## Core Classes by Module
+
+### [module_name/] ([N] core classes out of [M] total)
+
+| Class | File | Role | Description |
+|-------|------|------|-------------|
+| [ClassName] | [path/file.ext] | [Base class / Interface / Facade / Core] | [One-line description] |
+
+<!-- Role categories:
+     - Base class: Abstract/virtual base that others inherit from
+     - Interface: Pure interface / trait / protocol
+     - Facade: Entry point class for a module (Manager, System, Service)
+     - Core: Key data structure or essential class
+     - Enum: Important enumeration type
+-->
+
+## Inheritance Trees
+
+<!-- Key inheritance hierarchies (only for classes with 3+ descendants) -->
+
+```
+[BaseClass]
+├── [DerivedA]
+│   ├── [DerivedA1]
+│   └── [DerivedA2]
+└── [DerivedB]
+```
+
+## Key Interfaces
+
+<!-- Interfaces/traits/protocols that define module boundaries -->
+
+| Interface | File | Implemented By | Purpose |
+|-----------|------|---------------|---------|
+| [IInterface] | [path/file.ext] | [Class1, Class2] | [What this contract defines] |

package/templates/core/.context/architecture/data-flow.md

@@ -0,0 +1,103 @@
+# Data Flow & Pipelines
+
+<!-- confidence: low -->
+<!-- source: [TO BE FILLED BY BOOTSTRAP] -->
+<!-- last-updated: YYYY-MM-DD -->
+
+## Summary
+
+<!-- Key data flows, processing pipelines, and execution sequences in the system -->
+
+[PLACEHOLDER: Run `/bootstrap-context` to auto-generate from codebase analysis.]
+
+## Application Lifecycle
+
+<!-- The main execution flow from startup to shutdown -->
+
+```
+[Entry Point] → [Initialization] → [Main Loop / Request Handling] → [Shutdown / Cleanup]
+```
+
+### Startup Sequence
+
+1. [Step 1 — e.g., Parse config, initialize logging]
+2. [Step 2 — e.g., Initialize subsystems]
+3. [Step 3 — e.g., Load resources]
+4. [Step 4 — e.g., Enter main loop / start listening]
+
+### Shutdown Sequence
+
+1. [Step 1 — e.g., Signal shutdown]
+2. [Step 2 — e.g., Flush buffers, save state]
+3. [Step 3 — e.g., Release resources]
+4. [Step 4 — e.g., Destroy subsystems]
+
+## Core Pipelines
+
+<!-- Major data processing pipelines. Use ASCII flow diagrams. -->
+
+### [Pipeline Name 1]
+
+**Purpose**: [What this pipeline does]
+**Trigger**: [What initiates this pipeline — e.g., per frame, per request, on event]
+
+```
+[Stage 1] → [Stage 2] → [Stage 3] → [Stage 4] → [Output]
+                │
+                └─→ [Branch/Error path]
+```
+
+**Key data transformations**:
+- Stage 1 → Stage 2: [Input type] → [Output type]
+- Stage 2 → Stage 3: [Transformation description]
+
+---
+
+### [Pipeline Name 2]
+
+**Purpose**: [What this pipeline does]
+**Trigger**: [What initiates this pipeline]
+
+```
+[Stage 1] → [Stage 2] → [Stage 3] → [Output]
+```
+
+## Threading / Concurrency Model
+
+<!-- How work is distributed across threads, processes, or async tasks -->
+
+| Thread / Task | Responsibility | Communicates With |
+|--------------|----------------|-------------------|
+| [Main thread] | [Description] | [Other threads via mechanism] |
+| [Worker pool] | [Description] | [Queue/channel/shared state] |
+
+### Synchronization Points
+
+- [Sync point 1 — e.g., Frame boundary: main thread waits for render thread]
+- [Sync point 2 — e.g., Resource loading: async callback on main thread]
+
+## Event / Message Flow
+
+<!-- If the system uses events, signals, or message passing -->
+
+### Key Events
+
+| Event | Producer | Consumer(s) | Payload |
+|-------|----------|-------------|---------|
+| [EventName] | [Module] | [Module1, Module2] | [Data description] |
+
+## External Data Flow
+
+<!-- Data flow with external systems (files, network, databases, hardware) -->
+
+```
+[External Source] ──→ [Input Processing] ──→ [Internal Representation]
+                                                      │
+[External Sink]  ←── [Output Processing] ←──────────┘
+```
+
+| External System | Direction | Format | Module Responsible |
+|----------------|-----------|--------|-------------------|
+| [FileSystem] | In/Out | [Format] | [ModuleName] |
+| [Network/API] | In/Out | [Protocol] | [ModuleName] |
+| [Hardware/GPU] | Out | [Commands] | [ModuleName] |