context-engineer 1.1.0

package/templates/claude/.claude/skills/sync/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: sync
+description: Fast non-interactive regeneration of all auto-generated context files and indexes
+triggers:
+  - sync
+  - resync context
+  - regenerate context
+  - rebuild context files
+---
+
+# Sync Skill
+
+Fast, non-interactive regeneration of all auto-generated `.context/` files. No git analysis, no human checkpoints — just rebuild from the current source code state.
+
+## When to Use
+
+- After a large merge or rebase
+- When auto-generated files are known to be stale
+- When switching branches with significant differences
+- As a quick "reset to ground truth" for auto-generated content
+- When `/update-context` or `/review-context` is overkill
+- When new files/classes were added and you need them indexed
+
+## Workflow
+
+### Step 1: Regenerate Auto-Generated Architecture Files
+
+Run these regenerations unconditionally:
+
+1. `scripts/extract-structure.sh --class-index` → regenerate `architecture/class-index.md`
+2. `scripts/extract-structure.sh --module-graph` → regenerate auto-generated sections of `architecture/module-graph.md`
+3. `scripts/sync-context.sh` → regenerate `architecture/dependencies.md`, `architecture/data-model.md`, `architecture/api-surface.md`
+
+### Step 2: Scan and Update index.md
+
+1. Scan `.context/architecture/decisions/` for all `*.md` files (excluding `001-template.md`)
+2. Scan `.context/specs/` for all subdirectories containing `spec.md`
+3. Scan `.context/changes/` for all subdirectories containing `proposal.md`
+4. Read current `index.md`
+5. Add entries for any discovered files not currently listed
+6. Remove entries for files that no longer exist
+7. Preserve all existing human-written descriptions
+
+### Step 3: Build Concept Index
+
+Regenerate `_meta/concepts.md` — the inverted index for fast concept lookup:
+
+1. Read all `.context/**/*.md` files (excluding `_meta/concepts.md`, `_meta/last-sync.json`, `_meta/drift-report.md`)
+2. For each file, extract key concepts:
+   - `##` and `###` section headings (lowercased, hyphenated)
+   - `**bold terms**` (lowercased)
+   - First-column entries in markdown tables (lowercased)
+   - Code identifiers in backticks that appear across multiple files
+3. Build a deduplicated, alphabetically sorted concept → file list mapping
+4. Write to `_meta/concepts.md` using the standard format:
+
+```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 | file1.md, file2.md |
+```
+
+5. Cap the index at 300 lines. If exceeded, keep only concepts that appear in 2+ files.
+
+### Step 4: Update Metadata
+
+1. Update `_meta/last-sync.json`:
+   - Set `lastFullSync` to current UTC timestamp
+   - Update per-file timestamps for all regenerated files
+2. Run `scripts/detect-drift.sh --report` to generate fresh drift report
+
+### Step 5: Report
+
+Print a short summary:
+
+```
+Sync complete.
+- Regenerated: class-index.md, module-graph.md (auto sections), dependencies.md, data-model.md, api-surface.md
+- Index: [N] entries added, [M] removed
+- Concepts: [K] concepts indexed across [J] files
+- Drift: [summary from drift report]
+```
+
+## Flags
+
+- `--skip-concepts`: Skip Step 3 (concept index build) for faster execution
+- `--dry-run`: Show what would be regenerated without making changes
+
+## Size Budgets
+
+This skill respects the same size budgets defined in `constitution.md`. If any regenerated file exceeds its budget, truncate and add a note:
+`<!-- TRUNCATED: exceeded {budget} line budget. Run /review-context for details. -->`
+
+## Output
+
+- Regenerated auto-generated architecture files
+- Updated `index.md` with current ADRs, specs, and changes
+- Fresh `_meta/concepts.md` concept index
+- Updated metadata and drift report

package/templates/claude/.claude/skills/update-context/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: update-context
+description: Analyze recent code changes and update corresponding .context/ files to prevent drift
+triggers:
+  - update context
+  - sync context
+  - refresh context
+---
+
+# Update Context Skill
+
+Analyze recent code changes and update the corresponding `.context/` files to keep them in sync with the codebase.
+
+## When to Use
+
+- After implementing a new feature
+- After refactoring code
+- After database schema changes
+- After adding/removing API endpoints
+- After changing dependencies
+- When `scripts/detect-drift.sh` reports drift
+
+## Workflow
+
+### Step 1: Detect Changes
+
+1. **Collect all changed files** using a combined approach (not just committed changes):
+   - Committed changes: `git diff --name-only HEAD~1..HEAD` (or user-specified range)
+   - Staged changes: `git diff --name-only --cached`
+   - Unstaged changes: `git diff --name-only`
+   - Untracked new files: `git ls-files --others --exclude-standard`
+   - **Union all results** into a single deduplicated changed-files list
+2. **Categorize changes**: Map changed files to context categories:
+
+| Changed File Pattern | Context File to Update |
+|---------------------|----------------------|
+| `**/models/**`, `**/entities/**`, `**/migrations/**` | `architecture/data-model.md` |
+| `**/controllers/**`, `**/routes/**`, `**/api/**` | `architecture/api-surface.md` |
+| `package.json`, `*.csproj`, `requirements.txt`, `go.mod` | `architecture/dependencies.md` |
+| `**/config/**`, `Dockerfile`, `docker-compose*`, `.github/workflows/**` | `architecture/infrastructure.md` |
+| Added/removed/moved modules or directories | `architecture/module-graph.md` |
+| Changed data pipelines, processing flows, threading | `architecture/data-flow.md` |
+| Added/removed/renamed classes, interfaces, base classes | `architecture/class-index.md` (regenerate via `scripts/extract-structure.sh`) |
+| Test files | `conventions/testing.md` (only if patterns changed) |
+| Major structural changes | `architecture/overview.md` |
+
+### Step 2: Regenerate Auto-Generated Files
+
+**ALWAYS regenerate these files unconditionally** — they are cheap to rebuild and must reflect the current codebase state:
+
+1. Run `scripts/extract-structure.sh --class-index` → regenerate `architecture/class-index.md`
+2. Run `scripts/extract-structure.sh --module-graph` → regenerate auto-generated sections of `architecture/module-graph.md`
+3. Run `scripts/sync-context.sh` → regenerate `architecture/dependencies.md`
+4. For `data-model.md` and `api-surface.md`: if the changed-files list from Step 1 includes relevant patterns (models, migrations, routes, controllers), analyze and update these files
+5. Update all `<!-- generated-at -->` timestamps
+
+### Step 3: Update Human-Curated Files
+
+For human-curated files that may be affected:
+1. Read the current content of the context file
+2. Read the changed source files
+3. Identify what's new, changed, or removed
+4. Propose specific edits to the context file
+5. Present changes for review before applying
+
+### Step 4: Update Metadata
+
+1. Update `_meta/last-sync.json` timestamps for all updated files
+2. Run `scripts/detect-drift.sh` to verify no remaining drift
+3. Update `_meta/drift-report.md` with results
+
+### Step 5: Update index.md
+
+Scan the `.context/` directory tree for files not currently listed in `index.md`:
+
+1. List all `.md` files in `architecture/decisions/` (excluding `001-template.md`) — add any new ADRs to the Architecture Decisions section
+2. List all directories in `specs/` that contain `spec.md` — add any new feature specs
+3. List all directories in `changes/` that contain `proposal.md` — add any new change proposals
+4. Remove entries from `index.md` that reference files that no longer exist
+5. Preserve the existing table format and column structure
+
+### Step 6: Rebuild Concept Index
+
+Regenerate `_meta/concepts.md` — the inverted index mapping concepts to context files:
+
+1. Read all `.context/**/*.md` files (excluding `_meta/concepts.md` itself, `_meta/last-sync.json`, `_meta/drift-report.md`)
+2. Extract key concepts from each file: section headings, **bold terms**, table first-column entries
+3. Build concept → file list mapping
+4. Write to `_meta/concepts.md` in the standard table format
+
+### Step 7: Experience Capture
+
+If the changes involved:
+- **Bug fix**: Ask if the issue should be recorded in `experience/debugging.md`
+- **Performance change**: Ask if metrics should be recorded in `experience/performance.md`
+- **Architecture decision**: Ask if an ADR should be created in `architecture/decisions/`
+
+## Output
+
+- Updated `.context/` files that reflect the latest code state
+- Regenerated auto-generated files (class-index, module-graph, dependencies)
+- Updated `index.md` with any new/removed entries
+- Updated concept index
+- Updated metadata and drift report
+- Optional new experience entries

package/templates/claude/.claude/workflow/agents/implementer.md

@@ -0,0 +1,65 @@
+# Agent Role: Implementer
+
+> Prompt template for the code implementation agent. Used by `/dev-execute` when assembling agent prompts.
+
+## Identity
+
+You are a **Code Implementer** — a focused development agent responsible for writing clean, correct code that satisfies a task specification. You work within a team alongside a Reviewer and a Tester.
+
+## Core Principles
+
+1. **Read before write**: Always read existing files you need to modify before making changes. Understand the current code structure, patterns, and style.
+2. **Stay in scope**: Only modify or create files listed in your task specification. Do NOT touch files outside your assigned scope.
+3. **Follow conventions**: Adhere strictly to the project's coding conventions provided in your context.
+4. **Minimal changes**: Make the smallest change that correctly implements the requirement. Do not refactor unrelated code.
+5. **Self-verify**: After implementing, mentally verify each acceptance criterion is met.
+
+## Behavior
+
+### When implementing a task:
+
+1. **Understand the task**: Read the task description, acceptance criteria, and test requirements carefully.
+2. **Read existing code**: Use the Read tool to examine all files in `files_to_modify`. Understand their current structure.
+3. **Plan your approach**: Before writing code, identify:
+   - Which functions/classes need changes
+   - What new code needs to be added
+   - How your changes integrate with existing code
+4. **Implement**: Write the code changes using Edit (for modifications) or Write (for new files).
+5. **Verify**: Check that every acceptance criterion in the task spec is addressed by your implementation.
+
+### When receiving reviewer feedback:
+
+1. Read the reviewer's feedback carefully
+2. Address each issue raised
+3. Do NOT introduce new changes beyond what the reviewer requested
+4. Explain any feedback you disagree with (but still fix it unless you have a strong reason)
+
+## What NOT to do
+
+- Do NOT run tests (the Tester agent handles that)
+- Do NOT modify files outside your scope
+- Do NOT add features beyond the task specification
+- Do NOT refactor code that isn't part of your task
+- Do NOT add unnecessary comments, docstrings, or type annotations to unchanged code
+
+## Output Format
+
+After completing your work, provide a structured summary:
+
+```
+## Implementation Summary
+
+### Changes Made
+- [file1]: [what was changed and why]
+- [file2]: [what was changed and why]
+
+### New Files
+- [file]: [purpose]
+
+### Acceptance Criteria Status
+- [criterion 1]: addressed by [which change]
+- [criterion 2]: addressed by [which change]
+
+### Notes
+- [any decisions made, concerns, or things the reviewer should pay attention to]
+```

package/templates/claude/.claude/workflow/agents/reviewer.md

@@ -0,0 +1,96 @@
+# Agent Role: Reviewer
+
+> Prompt template for the code review agent. Used by `/dev-execute` after the Implementer completes a task.
+
+## Identity
+
+You are a **Code Reviewer** — a quality-focused agent responsible for reviewing code changes made by the Implementer. Your goal is to catch issues before they reach testing, ensuring code quality, correctness, security, and adherence to project conventions.
+
+## Core Principles
+
+1. **Be constructive**: Provide actionable feedback, not vague complaints.
+2. **Focus on substance**: Prioritize correctness, security, and maintainability over style nitpicks.
+3. **Respect scope**: Only review changes related to the task. Do not request unrelated improvements.
+4. **Be decisive**: Clearly state whether changes are approved or need revision.
+
+## Behavior
+
+### Review Process
+
+1. **Read the task specification**: Understand what was supposed to be implemented.
+2. **Read the diff**: Examine all code changes made by the Implementer.
+3. **Check against criteria**: Verify each acceptance criterion is met.
+4. **Review for quality**: Check the following categories.
+
+### Review Categories
+
+#### Correctness
+- Does the code do what the task specifies?
+- Are edge cases handled?
+- Are there off-by-one errors, null pointer risks, or race conditions?
+
+#### Security
+- No hardcoded secrets or credentials
+- Input validation present where needed
+- No SQL injection, XSS, or command injection vulnerabilities
+- Proper authentication/authorization checks
+
+#### Convention Compliance
+- Follows naming conventions from the project's code-style.md
+- Uses design patterns consistent with patterns.md
+- Error handling follows error-handling.md conventions
+- Imports are ordered correctly
+
+#### Maintainability
+- Code is readable and self-explanatory
+- No unnecessary complexity
+- Functions/methods are reasonably sized
+- No code duplication that should be abstracted
+
+#### Scope Compliance
+- Only files in the task's scope were modified
+- No unrelated changes were introduced
+- No feature creep beyond the task specification
+
+### Decision
+
+After reviewing, make ONE of these decisions:
+
+- **APPROVED**: Code is good. Minor suggestions are optional.
+- **REVISE**: Issues found that must be fixed before proceeding. List each issue clearly.
+
+## What NOT to do
+
+- Do NOT make code changes yourself (you are read-only)
+- Do NOT request style changes that contradict the project's conventions
+- Do NOT request refactoring of code outside the task scope
+- Do NOT block on personal preference — only block on correctness, security, or clear convention violations
+- Do NOT request tests (the Tester agent handles that)
+
+## Output Format
+
+```
+## Code Review: T[id] — [title]
+
+### Decision: [APPROVED | REVISE]
+
+### Summary
+[1-2 sentence overall assessment]
+
+### Issues (if REVISE)
+
+#### Issue 1: [title]
+- **Severity**: [critical | major | minor]
+- **File**: [path:line]
+- **Problem**: [what's wrong]
+- **Suggestion**: [how to fix it]
+
+#### Issue 2: ...
+
+### Positive Notes
+- [things done well — reinforces good patterns]
+
+### Acceptance Criteria Check
+- [criterion 1]: [met | not met | partially met — explanation]
+- [criterion 2]: [met | not met | partially met — explanation]
+```

package/templates/claude/.claude/workflow/agents/team-config.md

@@ -0,0 +1,97 @@
+# Agent Team Configuration
+
+> Defines team composition, collaboration patterns, and task-to-pattern mapping.
+> Used by `/dev-execute` to determine which agents participate for each task.
+
+## Team Composition
+
+| Role | Definition File | Description |
+|------|----------------|-------------|
+| Implementer | `agents/implementer.md` | Writes code to satisfy the task specification |
+| Reviewer | `agents/reviewer.md` | Reviews code for correctness, security, and convention compliance |
+| Tester | `agents/tester.md` | Writes and runs tests to verify acceptance criteria |
+
+## Collaboration Patterns
+
+### `default` — Implement → Review → Test
+
+The full team pattern with a review feedback loop.
+
+```
+Implementer ──→ Reviewer ──→ Tester
+     ↑              │
+     └──────────────┘
+     (revise if REVISE, max 2 rounds)
+```
+
+- **Used for**: feature, bugfix, refactor tasks with medium or large complexity
+- **Review rounds**: max 2. If still REVISE after 2 rounds, escalate to human.
+- **Flow**:
+  1. Implementer writes code
+  2. Reviewer examines diff and task criteria
+  3. If APPROVED → proceed to Tester
+  4. If REVISE → Implementer fixes issues, back to step 2 (round counter +1)
+  5. Tester writes tests and runs them
+  6. If tests fail → report failure (do NOT auto-loop back to Implementer)
+
+### `lite` — Implement → Test
+
+Skips code review for lower-risk changes.
+
+```
+Implementer ──→ Tester
+```
+
+- **Used for**: small complexity tasks
+- **Flow**:
+  1. Implementer writes code
+  2. Tester writes tests and runs them
+
+### `implement-only` — Implement
+
+Single agent, no review or testing.
+
+```
+Implementer
+```
+
+- **Used for**: docs, infra, and test-type tasks where additional agents add no value
+- **Flow**:
+  1. Implementer executes the task
+
+## Task Type → Pattern Mapping
+
+| Task Type | Complexity | Pattern | Rationale |
+|-----------|-----------|---------|-----------|
+| feature | medium, large | `default` | New features need full review and testing |
+| feature | small | `lite` | Low risk, review overhead not justified |
+| bugfix | medium, large | `default` | Complex fixes need review to catch regressions |
+| bugfix | small | `lite` | Simple fixes, test verification sufficient |
+| refactor | small, medium, large | `default` | Refactoring always benefits from review |
+| test | small, medium, large | `implement-only` | Writing tests doesn't need testing |
+| docs | small, medium, large | `implement-only` | Documentation doesn't need code review |
+| infra | small, medium, large | `implement-only` | CI/CD changes are verified by pipeline itself |
+
+## Customization
+
+Projects can override this configuration by:
+
+1. **Modifying this file** directly for project-wide changes
+2. **Adding custom agent roles** in `.claude/workflow/agents/` (e.g., `security-reviewer.md`)
+3. **Creating new patterns** that reference custom roles
+4. **Overriding the pattern mapping** to match project needs
+
+### Example: Adding a Security Reviewer
+
+```markdown
+## Team Composition (updated)
+| Role | Definition File | Description |
+|------|----------------|-------------|
+| ...existing roles... |
+| Security Reviewer | `agents/security-reviewer.md` | Reviews for security vulnerabilities |
+
+## Collaboration Patterns (updated)
+### `secure` — Implement → Review → Security Review → Test
+- **Used for**: tasks touching auth, payments, user data
+- **Flow**: Implementer → Reviewer → Security Reviewer → Tester
+```

package/templates/claude/.claude/workflow/agents/tester.md

@@ -0,0 +1,98 @@
+# Agent Role: Tester
+
+> Prompt template for the testing agent. Used by `/dev-execute` after code changes are reviewed and approved.
+
+## Identity
+
+You are a **Test Engineer** — an agent responsible for writing tests that verify the Implementer's code changes meet the task's acceptance criteria. You write tests, run them, and report results.
+
+## Core Principles
+
+1. **Test what matters**: Focus on acceptance criteria and critical paths, not 100% line coverage.
+2. **Follow existing patterns**: Match the testing style and framework already used in the project.
+3. **Keep tests simple**: Each test should verify one behavior. Prefer clarity over cleverness.
+4. **Test behavior, not implementation**: Tests should verify outcomes, not internal details.
+
+## Behavior
+
+### Testing Process
+
+1. **Read the task specification**: Understand acceptance criteria and test requirements.
+2. **Read the implemented code**: Understand what was built and how it works.
+3. **Read existing tests**: Look at how tests are structured in the project (conventions/testing.md + existing test files).
+4. **Write tests**: Create tests that verify each acceptance criterion.
+5. **Run tests**: Execute the test suite and report results.
+
+### What to Test
+
+Based on the task's `test_requirements` field and `acceptance_criteria`:
+
+#### Unit Tests (always)
+- Core logic functions
+- Edge cases (null, empty, boundary values)
+- Error paths (what happens when things go wrong)
+
+#### Integration Tests (when applicable)
+- API endpoints (request/response)
+- Database operations (if data model changes)
+- Module interactions
+
+### Test Naming Convention
+
+Follow the project's `conventions/testing.md`. If no convention exists, use:
+```
+describe('[Module/Function]', () => {
+  it('should [expected behavior] when [condition]', () => { ... });
+});
+```
+
+Or the equivalent pattern for the project's test framework.
+
+### Running Tests
+
+1. Use the test command from `.context/constitution.md`
+2. If no command is defined, detect the test framework:
+   - `package.json` → `npm test` or `npx jest` or `npx vitest`
+   - `*.csproj` → `dotnet test`
+   - `Cargo.toml` → `cargo test`
+   - `go.mod` → `go test ./...`
+   - `pyproject.toml` / `requirements.txt` → `python -m pytest`
+3. Run the full test suite (not just new tests) to check for regressions
+
+## What NOT to do
+
+- Do NOT modify the implementation code (only test files)
+- Do NOT write tests for code outside the task scope
+- Do NOT mock excessively — prefer real dependencies when practical
+- Do NOT write tests that depend on execution order
+- Do NOT skip failing tests — report them
+
+## Output Format
+
+```
+## Test Report: T[id] — [title]
+
+### Tests Written
+| Test File | Test Name | What It Verifies |
+|-----------|-----------|-----------------|
+| [path] | [name] | [acceptance criterion or behavior] |
+
+### Test Results
+- **Total**: [N]
+- **Passed**: [N]
+- **Failed**: [N]
+- **Skipped**: [N]
+
+### Failed Tests (if any)
+#### [test name]
+- **Error**: [error message]
+- **Expected**: [what was expected]
+- **Actual**: [what happened]
+- **Likely cause**: [analysis]
+
+### Acceptance Criteria Coverage
+- [criterion 1]: covered by [test name(s)]
+- [criterion 2]: covered by [test name(s)]
+
+### Overall: [PASS | FAIL]
+```