context-engineer 1.1.0 → 1.3.0

package/lib/update.mjs

@@ -30,6 +30,24 @@ function detectInstalledGroups(targetDir) {
   return groups;
 }
 
+/**
+ * Framework files are the "engine" of context-engineer — skills, scripts, agent roles.
+ * These should always be updated, even if the user's copy differs (e.g., bootstrap touched them).
+ * Content files (.context/ project docs) contain user knowledge and should be preserved.
+ */
+function isFrameworkFile(relPath) {
+  const normalized = relPath.replace(/\\/g, '/');
+  if (normalized.startsWith('.claude/')) return true;
+  if (normalized.startsWith('.cursor/')) return true;
+  if (normalized.startsWith('scripts/')) return true;
+  if (normalized.startsWith('.github/')) return true;
+  if (normalized === 'CLAUDE.md') return true;
+  if (normalized === '.cursorrules') return true;
+  if (normalized === '.context/_meta/schema.md') return true;
+  if (normalized === '.context/_meta/drift-report.md') return true;
+  return false;
+}
+
 function loadInstalledChecksums(targetDir) {
   const checksumPath = join(targetDir, '.context', '_meta', '.ce-checksums.json');
   if (!existsSync(checksumPath)) return {};
@@ -70,8 +88,9 @@ export async function runUpdate(flags) {
   const installedGroups = detectInstalledGroups(targetDir);
   const installedChecksums = loadInstalledChecksums(targetDir);
 
-  // Categorize files: new, modified (user untouched), modified (user customized)
+  // Categorize files into: new, framework (always update), updatable, customized (skip)
   const newFiles = [];
+  const frameworkUpdates = [];
   const updatable = [];
   const customized = [];
 
@@ -95,15 +114,20 @@ export async function runUpdate(flags) {
           continue;
         }
 
-        // Check if user has customized the file since install
-        // Compare user's file against the hash saved at install time
+        // Framework files (skills, scripts, agent roles) are always updated
+        if (isFrameworkFile(relPath)) {
+          frameworkUpdates.push(relPath);
+          continue;
+        }
+
+        // Content files: check if user has customized since install
         const originalHash = installedChecksums[relPath];
 
         if (originalHash && currentHash === originalHash) {
           // User hasn't modified it since install — safe to update
           updatable.push(relPath);
         } else {
-          // User has customized this file, or no install record — don't touch
+          // User has customized this content file — don't touch
           customized.push(relPath);
         }
       }
@@ -117,19 +141,26 @@ export async function runUpdate(flags) {
     console.log('');
   }
 
+  if (frameworkUpdates.length > 0) {
+    console.log(`  Framework updates (${frameworkUpdates.length}):`);
+    for (const f of frameworkUpdates) console.log(`    ^ ${f}`);
+    console.log('');
+  }
+
   if (updatable.length > 0) {
-    console.log(`  Updatable files (${updatable.length}):`);
+    console.log(`  Updatable content (${updatable.length}):`);
     for (const f of updatable) console.log(`    ~ ${f}`);
     console.log('');
   }
 
   if (customized.length > 0) {
-    console.log(`  Customized files — skipped (${customized.length}):`);
+    console.log(`  Customized content — preserved (${customized.length}):`);
     for (const f of customized) console.log(`    ! ${f}`);
     console.log('');
   }
 
-  if (newFiles.length === 0 && updatable.length === 0) {
+  const totalUpdates = newFiles.length + frameworkUpdates.length + updatable.length;
+  if (totalUpdates === 0) {
     console.log('  No updates to apply.\n');
     return;
   }
@@ -140,14 +171,13 @@ export async function runUpdate(flags) {
   }
 
   // Confirm
-  const totalUpdates = newFiles.length + updatable.length;
   const proceed = force || (await confirm(`Apply ${totalUpdates} update(s)?`));
   if (!proceed) {
     console.log('  Cancelled.\n');
     return;
   }
 
-  // Apply updates — copy new and updatable files
+  // Apply updates — new + framework (always) + updatable content + (force: customized content)
   let applied = 0;
   const newChecksums = { ...installedChecksums };
 
@@ -155,7 +185,12 @@ export async function runUpdate(flags) {
     const groupDir = join(TEMPLATES_DIR, groupId);
     if (!existsSync(groupDir)) continue;
 
-    const filesToUpdate = new Set([...newFiles, ...(force ? [...updatable, ...customized] : updatable)]);
+    const filesToUpdate = new Set([
+      ...newFiles,
+      ...frameworkUpdates,
+      ...updatable,
+      ...(force ? customized : []),
+    ]);
 
     for (const relPath of walkDir(groupDir)) {
       if (!filesToUpdate.has(relPath)) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-engineer",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Structured context management for AI coding agents. One command to install the .context/ system into any project.",
   "type": "module",
   "bin": {

package/templates/checksums.json

@@ -42,21 +42,21 @@
   "claude/.claude/skills/bootstrap/SKILL.md": "7a1bda7ab0376188e261269a5d058083e21facc4834e6dd4c9190cc159695eb6",
   "claude/.claude/skills/dev-capture/SKILL.md": "724bd8bbedb7f8b7311155f5e209c3964bc02ea39685973e7d22fd16f3f2bfd4",
   "claude/.claude/skills/dev-commit/SKILL.md": "dc6b42e1f5264086d32a9942c820f8cf263408acdfb337a49d8d26eef7543424",
-  "claude/.claude/skills/dev-decompose/SKILL.md": "a4437cc742a11f6983bdaa4ad1c4849f5df1c51fa22619213d53190544782986",
+  "claude/.claude/skills/dev-decompose/SKILL.md": "c411822ce2d1de6a174fd91e41b0d05ab116a521cc4f1d9e3db36f65737b61b0",
   "claude/.claude/skills/dev-deps/SKILL.md": "a279612324b00375975ef06b0530fefb5b5734573c78f019ff8d342c3a3067b1",
-  "claude/.claude/skills/dev-execute/SKILL.md": "8b74b031542210f5459d3792ff90069fdab0ab49dd0a4a7cde6a482f66407e1f",
-  "claude/.claude/skills/dev-prd/SKILL.md": "272effef0590d7a78693c2dc32e5f5781e670c2a5ab3131e92d16407ce93bf99",
-  "claude/.claude/skills/dev-quality/SKILL.md": "2ba7700b39fb6f6f37b8f8000a44ac4217d715fcf0d1f64391806f956326fc2d",
-  "claude/.claude/skills/dev-requirements/SKILL.md": "8b17af7c0a381d774ddd9a74d4fa9708498b075d7a7248fa6cbd460ed79c8ca0",
+  "claude/.claude/skills/dev-execute/SKILL.md": "12acf3a18b3aab849224184d4bdc3415a09b595a4c6ebd43778aa2ac2a1567fb",
+  "claude/.claude/skills/dev-prd/SKILL.md": "c313548ef7afdecb4c76d27c879d06e70ea9fb9ee90e804ccf60b2ba7cecf808",
+  "claude/.claude/skills/dev-quality/SKILL.md": "566b127acb901ac857b085757ec3bab777f895326077ab02f361407e292c8392",
+  "claude/.claude/skills/dev-requirements/SKILL.md": "0127c4c10ba47da866b51b4b322f7d33902d44ace4ae3878d461ef297fb37d23",
   "claude/.claude/skills/dev/SKILL.md": "ff82a44d8f9e177fcdee277a9969336457f8bbcd3461a709634bd3d2bee71c78",
   "claude/.claude/skills/review-context/SKILL.md": "49716a96b75d6e78dbe2405bf835ce31e432ee5eb9c146b19c0592707de18231",
   "claude/.claude/skills/sync/SKILL.md": "00c51e26c8b945810901831324086344d7ca9bb391796fb14afe0ee2a4c8ed33",
   "claude/.claude/skills/update-context/SKILL.md": "203be9a9ba9dcaf97ef04973d3107192cb5bc3a98ba5a2a23409f676a6208c44",
   "claude/.claude/workflow/agents/implementer.md": "ca1329f1a23f6359f4a1167804c9a2c8a0eb749bc3bd06dcdb0eeaf2e0506ba7",
-  "claude/.claude/workflow/agents/reviewer.md": "335c8f2c49ecbd8c8304943c991c68ab8a7e39e8f32a57f522eeaa99dc623c56",
+  "claude/.claude/workflow/agents/reviewer.md": "c2d07df9bd4125fcd7b95af24224f552c37dfcff06e6e1225bf1d5f98c02dc7b",
   "claude/.claude/workflow/agents/team-config.md": "679a73ce17cd4dd0cbabf69ed665e840f4a21dc9b5f659c4bcd20c8e7b15f9a5",
   "claude/.claude/workflow/agents/tester.md": "93b56bd201a6950e5a4cb66f5f0352a18b8c66c5619efd10fa84d7361c6bdff4",
-  "claude/.claude/workflow/interfaces/phase-contract.md": "9bfcb73a9ea23cac0a44a0b8fc77babda24450bd84b12fbe5b115b1c9a3b3b64",
+  "claude/.claude/workflow/interfaces/phase-contract.md": "a01ca8553707035ea4a3f6511269cc527fc9cc49432dea416dae2b5a9a23b9b6",
   "claude/CLAUDE.md": "a81997371fd35fec37fe38367f08d13256f68bd540a8bb126d908bbf4d2cc11d",
   "cursor/.cursor/rules/always.mdc": "e653939afb8638e8ddd3bd081e8209632a8e004b466b8243029ea0fb77d2199f",
   "cursor/.cursor/rules/backend.mdc": "1c42070f1a45ee2eafb2c24b9cc1da8e252c57a55941564134a07a9227e6336f",

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

@@ -41,6 +41,7 @@ Break the PRD's functional requirements into tasks. For each task:
 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
+6. **Provide implementation hints**: Give the implementing agent a head start with key technical details
 
 **Task sizing guidance:**
 - `small`: Single file change, < 50 lines, straightforward
@@ -80,7 +81,8 @@ Write `.context/workflow/artifacts/tasks.json` following this schema:
       ],
       "context_files": ["architecture/api-surface.md"],
       "complexity": "medium",
-      "test_requirements": "Unit tests for [what], integration test for [what]"
+      "test_requirements": "Unit tests for [what], integration test for [what]",
+      "implementation_hints": "Key function signatures, data structures, patterns to follow, or pseudocode for core logic. Optional for small/obvious tasks."
     }
   ]
 }

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

@@ -49,6 +49,11 @@ Create `.context/workflow/artifacts/execution-log.md`:
 
 ### Step 4: Execute Groups in Order
 
+**Progress reporting**: Before each task, output a progress line:
+```
+[Group N/M] Task K/Total: T{id} — {title} ({pattern})
+```
+
 For each group in `dep-graph.json` (ordered by `order` field):
 
 #### 4a. Determine Team Pattern for Each Task
@@ -170,7 +175,7 @@ Append to `execution-log.md` for each task:
 - **Overall**: [PASS | FAIL]
 ```
 
-### Step 5: Handle Failures
+### Step 5: Handle Failures (Task-Level Recovery)
 
 - **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.
@@ -178,6 +183,10 @@ Append to `execution-log.md` for each task:
 - **Build failure after group**: Attempt one fix. If fails, stop and report.
 - **Merge conflict**: Stop, show details, ask user.
 
+**Task-level recovery**: When a task fails, record its status in `execution-log.md` and continue with other independent tasks. Failed tasks are listed in the summary so the user can:
+1. Fix the issue manually, then re-run `/dev --from=execute` (skips already-completed tasks by checking execution-log.md)
+2. Or modify the task in tasks.json and re-run
+
 ### Step 6: Finalize
 
 After all groups complete, update execution log:

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

@@ -32,6 +32,23 @@ Consider:
 - What data model changes might be needed?
 - What API changes are needed?
 
+### Step 2b: Explore Design Alternatives
+
+Before committing to a design, explore **2-3 implementation approaches** and evaluate trade-offs:
+
+1. **Identify candidate approaches**: Based on the architecture and requirements, list 2-3 viable designs
+2. **Evaluate each** against these criteria:
+   - Complexity (how much code/change)
+   - Risk (what could go wrong)
+   - Alignment with existing patterns
+   - Performance implications
+   - Future extensibility
+3. **Recommend one** and explain why, noting trade-offs of alternatives
+
+Include this analysis in the PRD under a "Design Approach" section. This is NOT a full architecture document — keep it concise (5-15 lines), focused on the key decision and rationale.
+
+**When to skip**: If there is only one reasonable approach (e.g., simple CRUD, straightforward bug fix), skip the alternatives analysis and note "Single viable approach — no alternatives analysis needed."
+
 ### Step 3: Generate PRD
 
 Write `.context/workflow/artifacts/prd.md` with this structure:
@@ -67,6 +84,16 @@ Write `.context/workflow/artifacts/prd.md` with this structure:
 - **Scalability**: [Scale expectations]
 - **Compatibility**: [Browser, OS, API version requirements]
 
+## Design Approach
+### Recommended: [Approach Name]
+[Brief description of the chosen approach and why it was selected]
+
+### Alternatives Considered
+| Approach | Pros | Cons |
+|----------|------|------|
+| [Alt 1] | [Pros] | [Cons — why not chosen] |
+| [Alt 2] | [Pros] | [Cons — why not chosen] |
+
 ## Technical Design Notes
 - **Affected modules**: [List of modules/components that need changes]
 - **Data model changes**: [New entities, modified fields, migrations]

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

@@ -63,6 +63,21 @@ If any check fails:
 
 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 3b: Acceptance Verification
+
+After technical checks (build/lint/test), verify that the implementation meets the requirements:
+
+1. Read `.context/workflow/artifacts/tasks.json` for all task acceptance criteria
+2. Read `.context/workflow/artifacts/execution-log.md` for implementation summaries
+3. For each task, check every acceptance criterion:
+   - **Met**: The implementation clearly satisfies the criterion
+   - **Partially met**: Some aspects are implemented but incomplete
+   - **Not met**: The criterion is not addressed
+   - **Untestable**: The criterion cannot be verified from code alone (mark for manual check)
+4. Report overall acceptance rate: `[met count] / [total criteria]`
+
+**This step does NOT re-run the agent team.** It is a read-only verification. If criteria are not met, the report flags them for human review.
+
 ### Step 4: Generate Quality Report
 
 Write `.context/workflow/artifacts/quality-report.md`:
@@ -94,6 +109,18 @@ Write `.context/workflow/artifacts/quality-report.md`:
 - **Tests failed**: [count]
 - **Failed tests**: [list of failing test names and error messages]
 
+## Acceptance Verification
+
+### Overall: [N/M criteria met]
+
+| Task | Criterion | Status |
+|------|-----------|--------|
+| T1 | [criterion text] | [met | partially met | not met | untestable] |
+| T1 | [criterion text] | [met | partially met | not met | untestable] |
+
+### Unmet Criteria (if any)
+- T[id]: [criterion] — [what's missing]
+
 ## Auto-Fix Attempts
 - [Description of any auto-fix attempts and their outcomes]
 

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

@@ -24,15 +24,37 @@ Check if requirements were provided inline (as arguments to `/dev` or `/dev-requ
 
 If requirements were provided inline:
 - Use them directly as the raw input
+- Still proceed to Step 2b (Requirements Exploration) to validate completeness
 
 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 2b: Requirements Exploration
+
+**Proactively explore the requirements** — don't just accept raw input. Ask clarifying questions to fill gaps:
+
+1. **Clarify ambiguity**: Identify vague terms and ask for specifics
+   - "What does 'fast' mean? Under 200ms? Under 1 second?"
+   - "When you say 'users', do you mean all users or a specific role?"
+
+2. **Identify boundaries**: Define what's in and out of scope
+   - "Should this work for mobile/tablet or desktop only?"
+   - "Does this need to handle offline scenarios?"
+
+3. **Explore edge cases**: Ask about non-obvious scenarios
+   - "What happens if the user already has [X]?"
+   - "How should error states be handled?"
+   - "What are the limits? (max items, max file size, concurrent users)"
+
+4. **Assess risks**: Flag potential technical or business risks
+   - "This will require changes to [existing module] — is that acceptable?"
+   - "This introduces a new dependency on [service] — have you considered availability?"
+
+5. **Check integration points**: Understand how this connects to existing features
+   - "How does this interact with [existing feature]?"
+   - "Will this affect any existing API contracts?"
+
+**Important**: Don't over-question. Aim for 3-5 targeted questions that fill the most critical gaps. If requirements are already thorough, acknowledge that and proceed.
 
 ### Step 3: Structure Requirements
 

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

@@ -18,9 +18,10 @@ You are a **Code Reviewer** — a quality-focused agent responsible for reviewin
 ### 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.
+2. **Read the diff**: Run `git diff` to examine all code changes made by the Implementer. Skip files marked `<!-- AUTO-GENERATED -->` — do not review auto-generated files.
+3. **Load conventions**: Read `.context/conventions/code-style.md`, `.context/conventions/patterns.md`, and `.context/conventions/error-handling.md` (skip if they don't exist).
+4. **Check against criteria**: Verify each acceptance criterion is met.
+5. **Review for quality**: Check the following categories.
 
 ### Review Categories
 
@@ -47,6 +48,18 @@ You are a **Code Reviewer** — a quality-focused agent responsible for reviewin
 - Functions/methods are reasonably sized
 - No code duplication that should be abstracted
 
+#### Performance
+- No N+1 query patterns (fetching in loops instead of batching)
+- No unnecessary iterations over large collections
+- No blocking I/O on hot paths
+- No large memory allocations that could be streamed
+- No missing pagination for unbounded result sets
+
+#### API Compatibility
+- Public API signature changes are intentional and documented
+- No accidental breaking changes to existing interfaces
+- Response format changes are backward compatible (or explicitly noted as breaking)
+
 #### Scope Compliance
 - Only files in the task's scope were modified
 - No unrelated changes were introduced

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

@@ -133,7 +133,8 @@ Reference it in `team-config.md` to include it in a collaboration pattern.
       "acceptance_criteria": ["..."],
       "context_files": ["architecture/..."],
       "complexity": "small | medium | large",
-      "test_requirements": "..."
+      "test_requirements": "...",
+      "implementation_hints": "Key function signatures, data structures, patterns to follow. Optional for small tasks."
     }
   ]
 }