context-engineer 1.1.0

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

@@ -0,0 +1,119 @@
+# /dev — Automated Development Workflow Orchestrator
+
+> Orchestrates the full software development pipeline: requirements → PRD → task decomposition → dependency analysis → agent execution → quality gate → commit → knowledge capture.
+
+## Usage
+
+```
+/dev                          # Start full pipeline from P0
+/dev [feature description]    # Start with inline requirements
+/dev --from=prd               # Resume from a specific phase
+/dev --only=decompose         # Run only one phase
+```
+
+## Pipeline Phases
+
+| Phase | Skill | Artifact | Default Checkpoint |
+|-------|-------|----------|--------------------|
+| P0 | `/dev-requirements` | `artifacts/requirements.md` | false |
+| P1 | `/dev-prd` | `artifacts/prd.md` | true |
+| P2 | `/dev-decompose` | `artifacts/tasks.json` | true |
+| P3 | `/dev-deps` | `artifacts/dep-graph.json` | false |
+| P4 | `/dev-execute` | `artifacts/execution-log.md` + code | false |
+| P5 | `/dev-quality` | `artifacts/quality-report.md` | false |
+| P6 | `/dev-commit` | git commits | false |
+| P7 | `/dev-capture` | updated `.context/` files | false |
+
+## Orchestrator Instructions
+
+### Step 1: Load Configuration
+
+Read `.context/workflow/config.md` to get:
+- Pipeline phase definitions (which phases to run)
+- Checkpoint settings (where to pause for human review)
+- Execution settings (max parallelism, isolation strategy)
+- Plugin overrides (custom phase implementations)
+
+If config.md does not exist, use defaults: all phases enabled, checkpoints after P1 and P2.
+
+### Step 2: Parse Arguments
+
+- No arguments → start full pipeline from P0
+- Inline text → treat as requirements input, start from P0 with pre-filled requirements
+- `--from={phase}` → resume from the specified phase (valid values: requirements, prd, decompose, deps, execute, quality, commit, capture)
+- `--only={phase}` → run only the specified phase
+
+### Step 3: Determine Current State
+
+Check which artifacts already exist in `.context/workflow/artifacts/`:
+```
+artifacts/requirements.md exists? → P0 was completed
+artifacts/prd.md exists?          → P1 was completed
+artifacts/tasks.json exists?      → P2 was completed
+artifacts/dep-graph.json exists?  → P3 was completed
+artifacts/execution-log.md exists? → P4 was completed
+artifacts/quality-report.md exists? → P5 was completed
+```
+
+If artifacts from previous phases exist and no `--from` flag is given:
+- Show the user what phases have been completed
+- Ask whether to resume from where it left off or start fresh
+- If starting fresh, delete all existing artifacts first
+
+### Step 4: Resolve Plugin for Each Phase
+
+For each phase about to run, resolve the implementation in this priority order:
+
+1. **Config override**: Check `.context/workflow/config.md` "Plugin Overrides" table
+   - If override type is `skill`: read the SKILL.md at the specified location and follow its instructions
+   - If override type is `mcp`: use the specified MCP server tools
+   - If override type is `script`: run the specified script via Bash
+2. **Convention directory**: Check if `.claude/workflow/phases/{phase-id}/SKILL.md` exists
+   - phase-id mapping: P0=requirements, P1=prd, P2=decompose, P3=deps, P4=execute, P5=quality-gate, P6=commit, P7=capture
+3. **Built-in default**: Use `.claude/skills/dev-{phase}/SKILL.md`
+
+### Step 5: Execute Pipeline
+
+For each phase in order:
+
+1. **Announce**: Tell the user which phase is starting (e.g., "Phase 1: Generating PRD...")
+2. **Execute**: Run the resolved phase implementation
+   - For built-in skills: follow the instructions in the corresponding SKILL.md
+   - For plugin skills: read and follow the plugin SKILL.md
+   - For MCP plugins: call the MCP tools as specified
+   - For script plugins: execute via Bash and capture output
+3. **Validate**: Check that the expected output artifact was produced
+   - If not produced, report the error and pause
+4. **Checkpoint**: If this phase has a checkpoint enabled in config:
+   - Display the output artifact to the user
+   - Ask the user to review: **Approve** / **Revise** (re-run with feedback) / **Abort**
+   - If Revise: re-run the phase incorporating user's feedback
+   - If Abort: stop the pipeline, keep all artifacts for later resumption
+5. **Continue**: Move to the next phase
+
+### Step 6: Completion
+
+After all phases complete:
+
+1. Show a summary report:
+   ```
+   ## Workflow Complete
+   - Feature: [name]
+   - Tasks executed: [count]
+   - Quality: [pass/fail]
+   - Commits: [list]
+   - Context updated: [yes/no]
+   ```
+2. Ask user if they want to clean up workflow artifacts (delete `.context/workflow/artifacts/*`)
+
+## Error Handling
+
+- **Phase failure**: Stop pipeline, show error, preserve artifacts. User can fix and `/dev --from={failed-phase}` to resume.
+- **Quality gate failure**: Attempt one auto-fix retry. If still fails, pause for human guidance.
+- **Merge conflict** (P4 worktree): Show conflict details, pause for human resolution.
+
+## Notes
+
+- The orchestrator does NOT implement phase logic itself — it delegates to phase skills
+- Each `/dev-{phase}` skill can also be called independently outside the orchestrator
+- All artifacts are stored in `.context/workflow/artifacts/` for state persistence and resumability

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

@@ -0,0 +1,111 @@
+# /dev-capture — P7: Knowledge Capture
+
+> Updates the .context/ system to reflect changes made during the workflow. Captures experience and updates architecture docs.
+
+## Input
+- All code changes from the current workflow cycle
+- `.context/workflow/artifacts/tasks.json` (from P2)
+- `.context/workflow/artifacts/execution-log.md` (from P4)
+- Context: Full `.context/` system
+
+## Output
+- Updated `.context/` files (architecture, conventions, experience, progress)
+
+## Instructions
+
+### Step 1: Analyze Changes
+
+1. **Collect all changed files** using a combined approach:
+   - Committed changes: `git diff --name-only HEAD~1..HEAD` (or appropriate 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. Read `.context/workflow/artifacts/tasks.json` for task metadata
+3. Read `.context/workflow/artifacts/execution-log.md` for execution details
+
+### Step 2: Determine What Needs Updating
+
+Use the mapping from `.claude/rules/context-maintenance.md`:
+
+| If changes include... | Then update... |
+|----------------------|----------------|
+| Database models, migrations, schema files | `.context/architecture/data-model.md` |
+| API routes, controllers, endpoints | `.context/architecture/api-surface.md` |
+| Package manifests (package.json, *.csproj, etc.) | `.context/architecture/dependencies.md` |
+| System architecture, major structural changes | `.context/architecture/overview.md` |
+| Module boundaries, added/removed/moved modules | `.context/architecture/module-graph.md` |
+| Data pipelines, processing flows, threading | `.context/architecture/data-flow.md` |
+| Core classes, interfaces, inheritance hierarchies | `.context/architecture/class-index.md` |
+| CI/CD configs, Docker files, deployment configs | `.context/architecture/infrastructure.md` |
+| New design patterns introduced | `.context/conventions/patterns.md` |
+| Changed error handling approach | `.context/conventions/error-handling.md` |
+
+### Step 3: Regenerate Auto-Generated Files
+
+**ALWAYS regenerate these files unconditionally** — they are cheap to rebuild:
+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 includes relevant patterns, analyze and update
+
+### Step 4: Update Human-Maintained Files
+
+For files that require human judgment:
+- Read the current file content
+- Identify what sections need updating based on the changes
+- Make targeted edits (don't rewrite the whole file)
+- Preserve existing content that hasn't changed
+
+### Step 5: Capture Experience (if applicable)
+
+Check if any of these apply:
+
+**Non-trivial bug fixed during execution?**
+→ Append to `.context/experience/debugging.md`:
+```markdown
+### "[Error/Symptom]"
+- **Cause**: [Why this happened]
+- **Fix**: [How it was resolved]
+- **Prevention**: [How to avoid in future]
+```
+
+**Significant architectural decision made?**
+→ Create a new ADR in `.context/architecture/decisions/`:
+- Find the next available number
+- Use the template from `001-template.md`
+
+**New pattern or anti-pattern discovered?**
+→ Append to `.context/experience/lessons.md`
+
+### Step 6: Update Progress
+
+Update `.context/progress/status.md` with:
+- What was completed in this workflow cycle
+- The feature name and task IDs
+- Date of completion
+
+### Step 7: Cleanup (Optional)
+
+Ask the user whether to:
+- **Keep** workflow artifacts (for reference/debugging)
+- **Clean** workflow artifacts (delete `.context/workflow/artifacts/*` except `.gitkeep`)
+
+### Step 8: Report
+
+Show a summary:
+```
+## Knowledge Capture Summary
+
+### Context Files Updated
+- [list of .context/ files that were updated]
+
+### Experience Captured
+- [any debugging/lessons/ADR entries added]
+
+### Progress Updated
+- [what was recorded in status.md]
+
+### Artifacts
+- [kept/cleaned]
+```

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

@@ -0,0 +1,90 @@
+# /dev-commit — P6: Commit & Integration
+
+> Creates well-structured git commits for the workflow's code changes, following project conventions.
+
+## Input
+- Verified code changes (in the working tree, quality-checked)
+- `.context/workflow/artifacts/quality-report.md` (from P5)
+- `.context/workflow/artifacts/tasks.json` (from P2)
+- Context: `.context/conventions/git.md`
+
+## Output
+- Git commits (one or more)
+
+## Instructions
+
+### Step 1: Load Context
+
+1. Read `.context/conventions/git.md` to understand the project's git conventions:
+   - Branch naming strategy
+   - Commit message format (conventional commits, etc.)
+   - PR process
+2. Read `.context/workflow/artifacts/tasks.json` to get task IDs and titles
+3. Read `.context/workflow/artifacts/quality-report.md` to confirm quality status
+4. If quality report shows FAIL, **stop** — do not commit failing code. Report this to the user.
+
+### Step 2: Review Changes
+
+Run `git status` and `git diff` to see all changes made during the workflow.
+
+Categorize changes:
+- Which task produced which file changes (cross-reference with tasks.json `files_to_modify` / `files_to_create`)
+- Are there any unexpected changes (files not in any task's scope)?
+
+### Step 3: Determine Commit Strategy
+
+Based on the project's git conventions and the nature of changes:
+
+**Option A — Single commit** (default for MVP):
+- Stage all changes
+- Write a commit message that summarizes the feature with task references
+
+**Option B — Per-task commits** (if project conventions prefer atomic commits):
+- Stage and commit changes for each task separately
+- Each commit message references the task ID
+
+Use the commit message format from `conventions/git.md`. If no convention is defined, use:
+```
+feat: [feature description]
+
+Tasks completed:
+- T1: [title]
+- T2: [title]
+...
+```
+
+### Step 4: Create Commits
+
+**Important rules:**
+- Do NOT push to remote — the user decides when to push
+- Do NOT use `--no-verify` — let pre-commit hooks run
+- Do NOT amend existing commits
+- Check for files that should NOT be committed (.env, credentials, large binaries)
+- Use `git add` with specific file paths, not `git add -A`
+
+Stage and commit:
+```bash
+git add [specific files]
+git commit -m "[message]"
+```
+
+If pre-commit hooks fail:
+- Read the hook output
+- Fix the issue (formatting, lint, etc.)
+- Stage the fixes
+- Create a NEW commit (do not amend)
+
+### Step 5: Report
+
+Show the user:
+```
+## Commits Created
+
+- [commit hash] [commit message]
+- ...
+
+Branch: [current branch name]
+Push status: NOT pushed (run `git push` when ready)
+```
+
+If running independently, confirm with the user before creating commits.

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

@@ -0,0 +1,113 @@
+# /dev-decompose — P2: Task Decomposition
+
+> Breaks a PRD into discrete, actionable development tasks with file scope and acceptance criteria.
+
+## Input
+- `.context/workflow/artifacts/prd.md` (from P1)
+- Context: `.context/architecture/overview.md`, `.context/architecture/module-graph.md`, `.context/conventions/patterns.md`
+
+## Output
+- `.context/workflow/artifacts/tasks.json`
+
+## Instructions
+
+### Step 1: Load Inputs
+
+1. Read `.context/workflow/artifacts/prd.md` — the PRD from P1
+2. Read the following context files (skip any that don't exist):
+   - `.context/architecture/overview.md` — system architecture and tech stack
+   - `.context/architecture/module-graph.md` — module dependencies
+   - `.context/architecture/data-model.md` — current data model
+   - `.context/architecture/api-surface.md` — current API surface
+   - `.context/architecture/class-index.md` — core classes and interfaces
+   - `.context/conventions/patterns.md` — design patterns used in the project
+   - `.context/conventions/testing.md` — testing strategy and conventions
+   - `.context/conventions/code-style.md` — coding conventions
+
+### Step 2: Analyze the Codebase
+
+Use Glob and Grep to understand the relevant parts of the codebase:
+- Identify which files and directories correspond to the modules mentioned in the PRD
+- Find existing code that will need modification
+- Identify patterns used in similar features
+- Locate existing tests for affected areas
+
+### Step 3: Decompose into Tasks
+
+Break the PRD's functional requirements into tasks. For each task:
+
+1. **Keep tasks atomic**: Each task should be completable by a single agent in one session
+2. **Define file scope**: List specific files that need modification or creation
+3. **Set dependencies**: Identify which tasks must complete before others can start
+4. **Write acceptance criteria**: Make them specific and testable
+5. **Specify test requirements**: What tests should be written
+
+**Task sizing guidance:**
+- `small`: Single file change, < 50 lines, straightforward
+- `medium`: 2-5 files, 50-200 lines, follows existing patterns
+- `large`: 5+ files, 200+ lines, may require new patterns or significant refactoring
+
+**Task type guidance:**
+- `feature`: New functionality
+- `bugfix`: Fix broken behavior
+- `refactor`: Restructure without changing behavior
+- `test`: Add or improve tests
+- `docs`: Documentation changes
+- `infra`: CI/CD, build, deployment changes
+
+### Step 4: Generate tasks.json
+
+Write `.context/workflow/artifacts/tasks.json` following this schema:
+
+```json
+{
+  "feature": "feature-name-kebab-case",
+  "created_at": "ISO-8601 timestamp",
+  "source_prd": ".context/workflow/artifacts/prd.md",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Short imperative title",
+      "description": "What to implement, why, and key implementation notes",
+      "type": "feature",
+      "scope": "backend",
+      "files_to_modify": ["src/path/to/file.ts"],
+      "files_to_create": ["src/path/to/new-file.ts"],
+      "depends_on": [],
+      "acceptance_criteria": [
+        "Specific testable criterion 1",
+        "Specific testable criterion 2"
+      ],
+      "context_files": ["architecture/api-surface.md"],
+      "complexity": "medium",
+      "test_requirements": "Unit tests for [what], integration test for [what]"
+    }
+  ]
+}
+```
+
+### Step 5: Validate Task List
+
+Check for:
+- **Coverage**: Every functional requirement in the PRD maps to at least one task
+- **No orphan dependencies**: All `depends_on` IDs reference existing tasks
+- **File scope clarity**: Every task has at least one file to modify or create
+- **No circular dependencies**: The dependency graph is a DAG
+- **Reasonable sizing**: No single task has complexity `large` with 10+ files (split it)
+
+### Step 6: Present Summary
+
+Show a human-readable summary of the task breakdown:
+
+```
+## Task Breakdown: [Feature Name]
+Total tasks: N
+
+| ID | Title | Type | Complexity | Depends On |
+|----|-------|------|-----------|------------|
+| T1 | ... | feature | medium | — |
+| T2 | ... | feature | small | T1 |
+| T3 | ... | test | small | T1 |
+```
+
+If running independently, ask the user for feedback and update the artifact.

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

@@ -0,0 +1,108 @@
+# /dev-deps — P3: Dependency Analysis
+
+> Analyzes task dependencies and file overlap to produce an execution plan with parallel groups and isolation strategy.
+
+## Input
+- `.context/workflow/artifacts/tasks.json` (from P2)
+- Context: `.context/architecture/module-graph.md`
+
+## Output
+- `.context/workflow/artifacts/dep-graph.json`
+
+## Instructions
+
+### Step 1: Load Tasks
+
+Read `.context/workflow/artifacts/tasks.json` to get the full task list with dependencies and file scopes.
+
+Optionally read `.context/architecture/module-graph.md` for module-level dependency information.
+
+### Step 2: Build Dependency Graph
+
+1. Parse the `depends_on` field of each task to build a directed acyclic graph (DAG)
+2. Verify there are no circular dependencies — if found, report the cycle and stop
+3. Perform topological sort to determine execution order
+
+### Step 3: Identify Parallel Groups
+
+Group tasks into execution waves (parallel groups):
+
+1. **Group 1**: All tasks with no dependencies (`depends_on: []`)
+2. **Group 2**: All tasks whose dependencies are entirely in Group 1
+3. **Group N**: All tasks whose dependencies are entirely in Groups 1 through N-1
+
+Tasks in the same group can potentially execute in parallel.
+
+### Step 4: Analyze File Overlap (Isolation Strategy)
+
+For each parallel group, check file overlap between tasks:
+
+1. For each pair of tasks (Ti, Tj) in the same group:
+   - Compute the intersection of `files_to_modify` ∪ `files_to_create`
+   - If intersection is empty → both tasks can use `isolation: "none"` (direct parallel)
+   - If intersection is non-empty → record the conflict, assign `isolation: "worktree"` to one or both
+
+2. **Isolation decision logic**:
+   - If no files overlap in the group → all tasks get `isolation: "none"`
+   - If some files overlap → tasks involved in overlap get `isolation: "worktree"`, others get `"none"`
+
+3. Read the `max_parallel_agents` setting from `.context/workflow/config.md` (default: 3)
+   - If a group has more tasks than `max_parallel_agents`, split into sub-groups
+
+### Step 5: Compute Critical Path
+
+The critical path is the longest sequence of dependent tasks by total complexity weight:
+- `small` = 1, `medium` = 2, `large` = 3
+- Critical path = the dependency chain with the highest total weight
+
+### Step 6: Generate dep-graph.json
+
+Write `.context/workflow/artifacts/dep-graph.json`:
+
+```json
+{
+  "groups": [
+    {
+      "order": 1,
+      "tasks": ["T1", "T2"],
+      "isolation": {
+        "T1": "none",
+        "T2": "none"
+      }
+    },
+    {
+      "order": 2,
+      "tasks": ["T3", "T4"],
+      "isolation": {
+        "T3": "worktree",
+        "T4": "none"
+      }
+    }
+  ],
+  "critical_path": ["T1", "T3"],
+  "file_conflicts": {
+    "T3-T4": ["src/shared/utils.ts"]
+  },
+  "total_groups": 2,
+  "max_parallelism": 2
+}
+```
+
+### Step 7: Present Summary
+
+Show the execution plan:
+
+```
+## Execution Plan
+
+### Group 1 (parallel)
+- T1: [title] (no isolation)
+- T2: [title] (no isolation)
+
+### Group 2 (parallel with isolation)
+- T3: [title] (worktree — conflicts with T4 on src/shared/utils.ts)
+- T4: [title] (no isolation)
+
+Critical path: T1 → T3 (weight: 4)
+Estimated parallelism: 2 agents max
+```