context-engineer 1.1.0

package/templates/claude/.claude/skills/dev-execute/SKILL.md

@@ -0,0 +1,196 @@
+# /dev-execute — P4: Agent Execution
+
+> Orchestrates an agent team (Implementer → Reviewer → Tester) to execute tasks according to the dependency graph, managing parallelism, isolation, and collaboration patterns.
+
+## Input
+- `.context/workflow/artifacts/dep-graph.json` (from P3)
+- `.context/workflow/artifacts/tasks.json` (from P2)
+- `.claude/workflow/agents/team-config.md` — team composition and patterns
+- `.claude/workflow/agents/*.md` — agent role definitions
+- Context: Per-task `context_files` from tasks.json + `.context/conventions/*`
+
+## Output
+- `.context/workflow/artifacts/execution-log.md`
+- Actual code changes in the repository
+
+## Instructions
+
+### Step 1: Load Configuration
+
+1. Read `.context/workflow/artifacts/dep-graph.json` — parallel groups and isolation strategy
+2. Read `.context/workflow/artifacts/tasks.json` — full task specifications
+3. Read `.claude/workflow/agents/team-config.md` — team patterns and task type mapping
+4. Read `.context/workflow/config.md` for `max_parallel_agents` (default: 3)
+
+### Step 2: Load Agent Role Definitions
+
+Read the following agent role files:
+- `.claude/workflow/agents/implementer.md`
+- `.claude/workflow/agents/reviewer.md`
+- `.claude/workflow/agents/tester.md`
+
+These are prompt templates that define how each agent behaves.
+
+### Step 3: Prepare Execution Log
+
+Create `.context/workflow/artifacts/execution-log.md`:
+
+```markdown
+# Execution Log
+
+- **Feature**: [feature name from tasks.json]
+- **Started**: [ISO-8601 timestamp]
+- **Total tasks**: [count]
+- **Total groups**: [count]
+- **Team pattern**: using agent team (implementer/reviewer/tester)
+
+## Execution Progress
+```
+
+### Step 4: Execute Groups in Order
+
+For each group in `dep-graph.json` (ordered by `order` field):
+
+#### 4a. Determine Team Pattern for Each Task
+
+For each task in the group, look up the team pattern using the mapping in `team-config.md`:
+- Match on `task.type` + `task.complexity`
+- Result: `default`, `lite`, or `implement-only`
+
+#### 4b. Prepare Context for Agents
+
+For each task, read the shared context that all agents for this task will receive:
+1. Project conventions: `.context/conventions/code-style.md`, `.context/conventions/patterns.md`
+2. Testing conventions: `.context/conventions/testing.md`
+3. Task-specific context: each file in the task's `context_files` array
+
+#### 4c. Execute Task Team (per task)
+
+For each task, run the agent team according to the determined pattern:
+
+**Pattern: `default` (implement → review → test)**
+
+```
+Round 0:
+  1. IMPLEMENTER AGENT
+     Prompt = implementer.md role + task spec + context + conventions
+     Launch: Agent(prompt=..., subagent_type="general-purpose", isolation=per dep-graph)
+     → Code changes produced
+
+  2. REVIEWER AGENT
+     Prompt = reviewer.md role + task spec + git diff of implementer's changes
+     Launch: Agent(prompt=..., subagent_type="general-purpose")
+     → Decision: APPROVED or REVISE with feedback
+
+  3. If REVISE and round < 2:
+     IMPLEMENTER AGENT (revision)
+     Prompt = implementer.md role + task spec + reviewer feedback
+     Launch: Agent(prompt=..., subagent_type="general-purpose")
+     → Go to step 2 (round + 1)
+
+  4. If REVISE and round >= 2:
+     Log "Review escalation needed" → pause for human
+
+  5. If APPROVED:
+     TESTER AGENT
+     Prompt = tester.md role + task spec + current code state
+     Launch: Agent(prompt=..., subagent_type="general-purpose")
+     → Test results: PASS or FAIL
+```
+
+**Pattern: `lite` (implement → test)**
+
+```
+  1. IMPLEMENTER AGENT (same as above)
+  2. TESTER AGENT (same as step 5 above)
+```
+
+**Pattern: `implement-only`**
+
+```
+  1. IMPLEMENTER AGENT (same as above)
+```
+
+#### 4d. Parallelism Within Groups
+
+Tasks within the same group can run in parallel, but the agent team for each task runs **sequentially** (implementer → reviewer → tester).
+
+**How to parallelize:**
+- For tasks with `isolation: "none"` — launch Implementer agents for all tasks in parallel
+- Wait for all Implementers to complete
+- Launch Reviewer agents in parallel (each reviewing its own task's changes)
+- Wait for all Reviewers to complete
+- Handle any REVISE loops
+- Launch Tester agents in parallel
+- Wait for all Testers to complete
+
+**For tasks with `isolation: "worktree"`:**
+- Launch the full team pipeline inside the worktree (the Implementer agent uses `isolation: "worktree"`)
+- Reviewer and Tester run in the same worktree context
+- After the full team pipeline completes, merge the worktree branch
+
+Respect `max_parallel_agents` — if a group has more tasks than the limit, split into sub-batches.
+
+#### 4e. Post-Group Validation
+
+After all tasks in a group complete:
+1. Run a quick build check using the build command from `.context/constitution.md`
+2. If build fails:
+   - Attempt one auto-fix (read error, fix, rebuild)
+   - If still fails → stop and report
+3. If worktree branches were used → merge them into the current branch
+   - If merge conflict → stop, report conflict details, ask user
+
+#### 4f. Update Execution Log
+
+Append to `execution-log.md` for each task:
+
+```markdown
+### Group [N]
+- **Status**: [completed | failed | partial]
+
+#### T[id]: [title]
+- **Pattern**: [default | lite | implement-only]
+- **Status**: [completed | failed]
+- **Isolation**: [none | worktree]
+
+##### Implementer
+- **Files changed**: [list]
+- **Summary**: [agent's summary]
+
+##### Reviewer (if applicable)
+- **Decision**: [APPROVED | REVISE]
+- **Rounds**: [1 | 2]
+- **Issues found**: [count]
+
+##### Tester (if applicable)
+- **Tests written**: [count]
+- **Tests passed**: [count]
+- **Tests failed**: [count]
+- **Overall**: [PASS | FAIL]
+```
+
+### Step 5: Handle Failures
+
+- **Implementer failure**: Log error, mark task failed. Dependent tasks in later groups cannot proceed.
+- **Reviewer escalation** (2 rounds exceeded): Pause, show reviewer's feedback, ask human to decide.
+- **Tester failure** (tests fail): Log failing tests. Do NOT auto-loop back to Implementer. Report and continue with next task (the quality gate in P5 will catch this).
+- **Build failure after group**: Attempt one fix. If fails, stop and report.
+- **Merge conflict**: Stop, show details, ask user.
+
+### Step 6: Finalize
+
+After all groups complete, update execution log:
+
+```markdown
+## Summary
+- **Completed**: [ISO-8601 timestamp]
+- **Tasks completed**: [N/total]
+- **Tasks failed**: [N]
+- **Review rounds total**: [N]
+- **Tests written**: [N]
+- **Tests passed**: [N]
+- **Build status**: [pass/fail]
+```
+
+Show the user a summary of execution results.

package/templates/claude/.claude/skills/dev-prd/SKILL.md

@@ -0,0 +1,100 @@
+# /dev-prd — P1: PRD Generation
+
+> Generates a Product Requirements Document from structured requirements and project context.
+
+## Input
+- `.context/workflow/artifacts/requirements.md` (from P0)
+- Context: `.context/business/*`, `.context/architecture/overview.md`, `.context/architecture/api-surface.md`
+
+## Output
+- `.context/workflow/artifacts/prd.md`
+
+## Instructions
+
+### Step 1: Load Inputs
+
+1. Read `.context/workflow/artifacts/requirements.md` — the structured requirements from P0
+2. Read the following context files (skip any that don't exist):
+   - `.context/business/overview.md` — product vision and positioning
+   - `.context/business/domain-model.md` — domain entities and relationships
+   - `.context/business/workflows.md` — existing business processes
+   - `.context/architecture/overview.md` — current system architecture
+   - `.context/architecture/api-surface.md` — existing API endpoints
+   - `.context/architecture/data-model.md` — current data model
+
+### Step 2: Analyze Requirements in Context
+
+Consider:
+- How does this feature fit into the existing architecture?
+- Which existing modules/components are affected?
+- Are there existing patterns that should be followed?
+- Are there potential conflicts with current functionality?
+- What data model changes might be needed?
+- What API changes are needed?
+
+### Step 3: Generate PRD
+
+Write `.context/workflow/artifacts/prd.md` with this structure:
+
+```markdown
+# PRD: [Feature Name]
+
+## Overview
+[2-3 sentence description of the feature, its purpose, and expected impact]
+
+## Background
+[Why this feature is needed — business context, user pain points, strategic alignment]
+
+## Goals & Success Criteria
+- [ ] [Measurable goal 1]
+- [ ] [Measurable goal 2]
+
+## Functional Requirements
+
+### [Requirement Group 1]
+- **FR-1.1**: [Detailed requirement]
+  - Acceptance: [How to verify this is done correctly]
+- **FR-1.2**: [Detailed requirement]
+  - Acceptance: [How to verify]
+
+### [Requirement Group 2]
+- **FR-2.1**: [Detailed requirement]
+  - Acceptance: [How to verify]
+
+## Non-Functional Requirements
+- **Performance**: [Specific targets, e.g., "< 200ms response time"]
+- **Security**: [Security considerations]
+- **Scalability**: [Scale expectations]
+- **Compatibility**: [Browser, OS, API version requirements]
+
+## Technical Design Notes
+- **Affected modules**: [List of modules/components that need changes]
+- **Data model changes**: [New entities, modified fields, migrations]
+- **API changes**: [New endpoints, modified endpoints]
+- **Dependencies**: [New libraries or services needed]
+
+## Scope Boundaries
+### In Scope
+- [Explicit list of what's included]
+
+### Out of Scope
+- [Explicit list of what's NOT included]
+
+## Risks & Mitigations
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [Risk 1] | [H/M/L] | [H/M/L] | [How to mitigate] |
+
+## Open Questions
+- [ ] [Question that needs resolution]
+```
+
+### Step 4: Validate
+
+- Ensure every user story from requirements.md is covered by at least one functional requirement
+- Ensure acceptance criteria are testable and specific
+- Flag any requirements that seem contradictory or incomplete
+
+If running independently (not through `/dev` orchestrator):
+- Present the PRD to the user for review
+- Incorporate feedback and update the artifact

package/templates/claude/.claude/skills/dev-quality/SKILL.md

@@ -0,0 +1,109 @@
+# /dev-quality — P5: Quality Gate
+
+> Runs quality checks on code changes: build, lint, test. Reports pass/fail with details.
+
+## Input
+- Code changes from P4 (in the working tree)
+- `.context/workflow/artifacts/execution-log.md` (from P4)
+- Context: `.context/conventions/testing.md`, `.context/constitution.md`
+
+## Output
+- `.context/workflow/artifacts/quality-report.md`
+
+## Instructions
+
+### Step 1: Determine Quality Commands
+
+Read `.context/constitution.md` to find the build, test, and lint commands:
+- Look for the `## Build & Test Commands` section
+- Extract: BUILD_COMMAND, TEST_COMMAND, LINT_COMMAND
+
+If commands are placeholder (`[BUILD_COMMAND]` etc.), check common patterns:
+- `package.json` exists → try `npm run build`, `npm test`, `npm run lint`
+- `*.csproj` exists → try `dotnet build`, `dotnet test`
+- `Cargo.toml` exists → try `cargo build`, `cargo test`
+- `go.mod` exists → try `go build ./...`, `go test ./...`
+- `requirements.txt` / `pyproject.toml` exists → try `python -m pytest`
+
+If no commands can be determined, skip automated checks and note this in the report.
+
+### Step 2: Run Quality Checks
+
+Execute each check in order. For each check, capture stdout/stderr and exit code.
+
+#### Check 1: Build
+```bash
+[BUILD_COMMAND]
+```
+- Pass: exit code 0
+- Fail: capture error output
+
+#### Check 2: Lint (if available)
+```bash
+[LINT_COMMAND]
+```
+- Pass: exit code 0 (or only warnings)
+- Fail: capture lint errors
+
+#### Check 3: Test
+```bash
+[TEST_COMMAND]
+```
+- Pass: exit code 0, all tests pass
+- Fail: capture failing test names and output
+
+### Step 3: Handle Failures
+
+If any check fails:
+
+1. **First attempt**: Analyze the error output. If the error is clearly caused by the recent changes and looks fixable (syntax error, missing import, type error):
+   - Attempt to fix the issue
+   - Re-run the failed check
+   - If it passes now, record as "fixed on retry" in the report
+
+2. **Second failure**: Do NOT attempt further fixes. Record the failure in the report and let the orchestrator handle it (pause for human guidance).
+
+### Step 4: Generate Quality Report
+
+Write `.context/workflow/artifacts/quality-report.md`:
+
+```markdown
+# Quality Report
+
+- **Date**: [ISO-8601]
+- **Overall Status**: [PASS | FAIL]
+
+## Check Results
+
+### Build
+- **Status**: [PASS | FAIL | SKIPPED]
+- **Command**: `[command used]`
+- **Output**: [summary of output, full output if failed]
+
+### Lint
+- **Status**: [PASS | FAIL | SKIPPED]
+- **Command**: `[command used]`
+- **Warnings**: [count]
+- **Errors**: [count, details if any]
+
+### Test
+- **Status**: [PASS | FAIL | SKIPPED]
+- **Command**: `[command used]`
+- **Tests run**: [count]
+- **Tests passed**: [count]
+- **Tests failed**: [count]
+- **Failed tests**: [list of failing test names and error messages]
+
+## Auto-Fix Attempts
+- [Description of any auto-fix attempts and their outcomes]
+
+## Recommendations
+- [Any suggestions for manual fixes if checks failed]
+```
+
+### Step 5: Report
+
+If running independently (not through orchestrator):
+- Show the quality report to the user
+- If FAIL: suggest what needs to be fixed
+- If PASS: confirm all checks passed

package/templates/claude/.claude/skills/dev-requirements/SKILL.md

@@ -0,0 +1,75 @@
+# /dev-requirements — P0: Requirements Gathering
+
+> Collects and structures user requirements into a formal requirements document.
+
+## Input
+- User conversation, issue links, or raw requirements text
+- Context: `.context/business/overview.md`, `.context/business/domain-model.md`
+
+## Output
+- `.context/workflow/artifacts/requirements.md`
+
+## Instructions
+
+### Step 1: Gather Context
+
+Read the following files to understand the project's business domain (skip any that don't exist):
+- `.context/business/overview.md` — product vision, target users
+- `.context/business/domain-model.md` — core entities and domain language
+- `.context/business/glossary.md` — terminology
+
+### Step 2: Collect Requirements
+
+Check if requirements were provided inline (as arguments to `/dev` or `/dev-requirements`).
+
+If requirements were provided inline:
+- Use them directly as the raw input
+
+If no requirements were provided:
+- Ask the user to describe what they want to build or change
+- Ask clarifying questions to understand:
+  - **What**: What is the feature/change/fix?
+  - **Why**: What problem does it solve? What's the motivation?
+  - **Who**: Who are the users affected?
+  - **Scope**: What's in scope and out of scope?
+  - **Constraints**: Any technical constraints, deadlines, or dependencies?
+
+### Step 3: Structure Requirements
+
+Create `.context/workflow/artifacts/requirements.md` with this structure:
+
+```markdown
+# Requirements: [Feature/Change Name]
+
+## Summary
+[1-2 sentence overview of what is needed and why]
+
+## User Stories
+- As a [user type], I want to [action] so that [benefit]
+- ...
+
+## Functional Requirements
+1. [FR-1]: [Description]
+2. [FR-2]: [Description]
+...
+
+## Non-Functional Requirements
+- Performance: [if applicable]
+- Security: [if applicable]
+- Compatibility: [if applicable]
+
+## Constraints
+- [Any technical, business, or timeline constraints]
+
+## Out of Scope
+- [What is explicitly NOT part of this work]
+
+## Open Questions
+- [Any unresolved questions that need answers before proceeding]
+```
+
+### Step 4: Present to User
+
+Show the structured requirements to the user. If running within the `/dev` orchestrator, the orchestrator handles checkpoint logic. If running independently:
+- Ask the user if the requirements look correct
+- Incorporate any feedback and update the artifact

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

@@ -0,0 +1,120 @@
+---
+name: review-context
+description: Audit the health of the .context/ system, detect drift, and report on context quality
+triggers:
+  - review context
+  - audit context
+  - check context health
+  - context status
+---
+
+# Review Context Skill
+
+Perform a comprehensive health check of the `.context/` system to identify drift, staleness, missing information, and quality issues.
+
+## Workflow
+
+### Step 1: Completeness Check
+
+Verify all expected context files exist and are populated:
+
+1. **Required files**: Check that all files listed in `.context/index.md` exist
+2. **Non-placeholder content**: Check that files contain actual content, not just template placeholders
+3. **Confidence levels**: Report the distribution of confidence markers (high/medium/low)
+
+### Step 2: Drift Detection
+
+Run comprehensive drift analysis:
+
+1. **Auto-generated file freshness**:
+   - Compare `architecture/data-model.md` against current ORM models / migrations
+   - Compare `architecture/api-surface.md` against current route definitions
+   - Compare `architecture/dependencies.md` against current package manifests
+   - Compare `architecture/class-index.md` against current source class/interface definitions
+   - Compare `architecture/module-graph.md` against current module structure and imports
+
+2. **Timestamp analysis**:
+   - Compare `_meta/last-sync.json` timestamps against source file modification times
+   - Flag files not updated for more than 30 days if source code has changed
+
+3. **Content consistency**:
+   - Check that entities mentioned in `business/domain-model.md` exist in code
+   - Check that API endpoints in `api-surface.md` match actual routes
+   - Check that build/test commands in `constitution.md` actually work
+
+4. **Index completeness**:
+   - Scan `.context/architecture/decisions/` for ADR files not listed in `index.md`
+   - Scan `.context/specs/` for spec directories not listed in `index.md`
+   - Scan `.context/changes/` for change proposals not listed in `index.md`
+   - Report any orphaned entries (listed in `index.md` but file does not exist)
+
+### Step 3: Size Budget Check
+
+Verify no files exceed their size budgets:
+
+| File Category | Budget |
+|--------------|--------|
+| constitution.md | 200 lines |
+| AGENTS.md | 150 lines |
+| Business files | 500 lines |
+| Architecture overview | 800 lines |
+| Architecture files (other) | 500 lines |
+| Convention files | 400 lines |
+| ADR files | 200 lines |
+| Experience files | 500 lines |
+
+Flag any files exceeding their budget.
+
+### Step 4: Experience Health
+
+1. Check if `experience/lessons.md` needs compaction (> 500 lines)
+2. Check if recent bug fixes have corresponding debugging entries
+3. Check if recent architectural decisions have corresponding ADRs
+
+### Step 5: Generate Report
+
+Produce a health report with:
+
+```markdown
+# Context Health Report — YYYY-MM-DD
+
+## Overall Score: [A/B/C/D/F]
+
+## Completeness: [X/Y files populated]
+- [List of missing or placeholder-only files]
+
+## Drift Detection: [N issues found]
+- [List of drifted files with details]
+
+## Size Budgets: [N files over budget]
+- [List of over-budget files]
+
+## Experience Health: [status]
+- [Compaction needed? Recent bugs tracked?]
+
+## Recommendations
+1. [Most important action item]
+2. [Second action item]
+3. [...]
+```
+
+### Step 6: Auto-Fix (Default)
+
+Unless the user specifies `--report-only`, automatically apply fixes:
+
+1. **Regenerate all auto-generated files**:
+   - Run `scripts/extract-structure.sh --class-index` → rebuild `architecture/class-index.md`
+   - Run `scripts/extract-structure.sh --module-graph` → rebuild auto-generated sections of `architecture/module-graph.md`
+   - Run `scripts/sync-context.sh` → rebuild `architecture/dependencies.md`
+2. **Update index.md**: Add entries for files discovered in Step 2.4 (index completeness), remove orphaned entries
+3. **Rebuild concept index**: Regenerate `_meta/concepts.md` from all context files
+4. **Compact experience files** that exceed budget (using `scripts/compact-experience.sh`)
+5. **Update `_meta/last-sync.json`** timestamps
+6. **Re-run drift detection** to verify fixes
+
+If `--report-only` is specified, skip this step and only output the report from Step 5.
+
+## Output
+
+- Context health report (printed to user and saved to `_meta/drift-report.md`)
+- Auto-fixed files (regenerated auto-generated files, updated index, rebuilt concept index)