context-engineer 1.1.0

package/lib/update.mjs

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { copyTemplateGroup, walkDir, fileHash } from './copy.mjs';
+import { confirm } from './prompts.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const PKG = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+function loadInstalledVersion(targetDir) {
+  const syncPath = join(targetDir, '.context', '_meta', 'last-sync.json');
+  if (!existsSync(syncPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(syncPath, 'utf8'));
+    return data.contextEngineerVersion || null;
+  } catch {
+    return null;
+  }
+}
+
+function detectInstalledGroups(targetDir) {
+  const groups = [];
+  if (existsSync(join(targetDir, '.context'))) groups.push('core');
+  if (existsSync(join(targetDir, '.claude'))) groups.push('claude');
+  if (existsSync(join(targetDir, '.cursor'))) groups.push('cursor');
+  if (existsSync(join(targetDir, '.github', 'copilot-instructions.md'))) groups.push('github');
+  return groups;
+}
+
+function loadInstalledChecksums(targetDir) {
+  const checksumPath = join(targetDir, '.context', '_meta', '.ce-checksums.json');
+  if (!existsSync(checksumPath)) return {};
+  try {
+    return JSON.parse(readFileSync(checksumPath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveInstalledChecksums(targetDir, checksums) {
+  const checksumPath = join(targetDir, '.context', '_meta', '.ce-checksums.json');
+  writeFileSync(checksumPath, JSON.stringify(checksums, null, 2) + '\n');
+}
+
+export async function runUpdate(flags) {
+  const targetDir = flags.dir || process.cwd();
+  const { force = false, check = false } = flags;
+
+  console.log(`\n  context-engineer v${PKG.version}`);
+  console.log('  Checking for updates...\n');
+
+  const installedVersion = loadInstalledVersion(targetDir);
+  if (!installedVersion) {
+    console.log('  No context-engineer installation detected in this directory.');
+    console.log('  Run "context-engineer init" first.\n');
+    process.exit(1);
+  }
+
+  console.log(`  Installed version: ${installedVersion}`);
+  console.log(`  Available version: ${PKG.version}\n`);
+
+  if (installedVersion === PKG.version && !force) {
+    console.log('  Already up to date!\n');
+    return;
+  }
+
+  const installedGroups = detectInstalledGroups(targetDir);
+  const installedChecksums = loadInstalledChecksums(targetDir);
+
+  // Categorize files: new, modified (user untouched), modified (user customized)
+  const newFiles = [];
+  const updatable = [];
+  const customized = [];
+
+  for (const groupId of installedGroups) {
+    const groupDir = join(TEMPLATES_DIR, groupId);
+    if (!existsSync(groupDir)) continue;
+
+    for (const relPath of walkDir(groupDir)) {
+      const destPath = join(targetDir, relPath);
+      const srcPath = join(groupDir, relPath);
+
+      if (!existsSync(destPath)) {
+        newFiles.push(relPath);
+      } else {
+        // Compare current file with new template
+        const currentHash = fileHash(destPath);
+        const templateHash = fileHash(srcPath);
+
+        if (currentHash === templateHash) {
+          // File already matches new template — no update needed
+          continue;
+        }
+
+        // Check if user has customized the file since install
+        // Compare user's file against the hash saved at install time
+        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
+          customized.push(relPath);
+        }
+      }
+    }
+  }
+
+  // Report
+  if (newFiles.length > 0) {
+    console.log(`  New files (${newFiles.length}):`);
+    for (const f of newFiles) console.log(`    + ${f}`);
+    console.log('');
+  }
+
+  if (updatable.length > 0) {
+    console.log(`  Updatable files (${updatable.length}):`);
+    for (const f of updatable) console.log(`    ~ ${f}`);
+    console.log('');
+  }
+
+  if (customized.length > 0) {
+    console.log(`  Customized files — skipped (${customized.length}):`);
+    for (const f of customized) console.log(`    ! ${f}`);
+    console.log('');
+  }
+
+  if (newFiles.length === 0 && updatable.length === 0) {
+    console.log('  No updates to apply.\n');
+    return;
+  }
+
+  if (check) {
+    console.log('  Run without --check to apply updates.\n');
+    return;
+  }
+
+  // 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
+  let applied = 0;
+  const newChecksums = { ...installedChecksums };
+
+  for (const groupId of installedGroups) {
+    const groupDir = join(TEMPLATES_DIR, groupId);
+    if (!existsSync(groupDir)) continue;
+
+    const filesToUpdate = new Set([...newFiles, ...(force ? [...updatable, ...customized] : updatable)]);
+
+    for (const relPath of walkDir(groupDir)) {
+      if (!filesToUpdate.has(relPath)) continue;
+      const srcPath = join(groupDir, relPath);
+      const destPath = join(targetDir, relPath);
+
+      // Read and apply version replacement
+      let content = readFileSync(srcPath);
+      let text = content.toString('utf8');
+      text = text.split('__CE_VERSION__').join(PKG.version);
+      content = Buffer.from(text, 'utf8');
+
+      const { mkdirSync } = await import('fs');
+      const { dirname: dirnameFn } = await import('path');
+      mkdirSync(dirnameFn(destPath), { recursive: true });
+      writeFileSync(destPath, content);
+      applied++;
+
+      // Record new checksum for this file
+      newChecksums[relPath] = fileHash(destPath);
+    }
+  }
+
+  // Save updated checksums
+  saveInstalledChecksums(targetDir, newChecksums);
+
+  // Update version in last-sync.json
+  const syncPath = join(targetDir, '.context', '_meta', 'last-sync.json');
+  if (existsSync(syncPath)) {
+    try {
+      const data = JSON.parse(readFileSync(syncPath, 'utf8'));
+      data.contextEngineerVersion = PKG.version;
+      writeFileSync(syncPath, JSON.stringify(data, null, 2) + '\n');
+    } catch {
+      // If corrupted, just leave it
+    }
+  }
+
+  console.log(`  Updated ${applied} file(s) to v${PKG.version}\n`);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "context-engineer",
+  "version": "1.1.0",
+  "description": "Structured context management for AI coding agents. One command to install the .context/ system into any project.",
+  "type": "module",
+  "bin": {
+    "context-engineer": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "bash ../scripts/build-templates.sh"
+  },
+  "keywords": [
+    "ai",
+    "context",
+    "coding-agent",
+    "claude",
+    "cursor",
+    "copilot",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/humanrace-ai/context-engineer"
+  }
+}

package/templates/checksums.json

@@ -0,0 +1,68 @@
+{
+  "core/.context/_meta/concepts.md": "74bde5d63183ce8c97d0c95fb3024e3996874d7b79e347d6b7351be8ef71838e",
+  "core/.context/_meta/drift-report.md": "670756bfdabc3d65fe627c52af5a6191aea91eca27323a0fcfbe85bc9efa9303",
+  "core/.context/_meta/last-sync.json": "c0ebaccd9763f9ae5213ac7fecfffba5569b8603370f27486d7313bf7f3b2edd",
+  "core/.context/_meta/schema.md": "4dd77777dc3e04aeef13a7e2475d85648cd772c519ab33eed871876a32eef9ee",
+  "core/.context/architecture/api-surface.md": "516c8b014d44267c840a299f78c6313e4df8419cfac500fcb75ff98cff62da52",
+  "core/.context/architecture/class-index.md": "b61d6aa3334ac737671c36c1c4ad5e250d50fa4cc4e9e3821baddf880a7d6e5a",
+  "core/.context/architecture/data-flow.md": "ac1b2d00627abfa216e0fb890fd8fbcf42547e133cf4b09d733da53c9a380558",
+  "core/.context/architecture/data-model.md": "fbfc1d2efb0927c32b543ad907e42791023a3123f35fd2a18da87468a03079e4",
+  "core/.context/architecture/decisions/001-template.md": "4f1e6b3295c2bd56feba0cd73816e574cbc17a58d808941bd592ecfc601ebd7d",
+  "core/.context/architecture/dependencies.md": "3297acf6570e0ad1d52e0aa87657c7c47ddfcdbd03949d59c422b1def4fb2f37",
+  "core/.context/architecture/infrastructure.md": "7eba26389e038d1057bee26776055759213a327a2ebc72cc11811c9043ce1ff3",
+  "core/.context/architecture/module-graph.md": "1c60d91a295628624a082b332c5e667564cc4042263c45a77a249270c1ff4619",
+  "core/.context/architecture/overview.md": "d15222390f55153144b2b0da6ce75565241105200a7b367c972a17af9a02c8a2",
+  "core/.context/business/domain-model.md": "ea5ac20dcce5b511354004c0c8b1c962bc76c707fa16a9457b77862da06bc90e",
+  "core/.context/business/glossary.md": "036af6b3f6cec76c07372d094a6cc0bb10fa4151149e6f65cb19d02bdae2d98c",
+  "core/.context/business/overview.md": "40132a96c4d83fb2b0cd5b8655cb6dc841c55910c2c95cd7f81988ded2267e67",
+  "core/.context/business/workflows.md": "c8ce4c76cc8f1f6d977401defa779f34d408b3d553c27f262469b807f2f8b1f8",
+  "core/.context/constitution.md": "a183a06c165ff88a32c72a966bf4aeec2c25d10ab6b12ac945fa29433469ed1a",
+  "core/.context/conventions/code-style.md": "59eb4f1022a74eaf55abf0135c302d9845187a348576bd048636782883e53766",
+  "core/.context/conventions/error-handling.md": "0d3e8805184fdb72c3dd465348f67cdbeb949f3153e7561f60bb6b07bd1f997b",
+  "core/.context/conventions/git.md": "043bf571cfb9477b9e4c1bf26df850c1ee9335de96bda8f0be4fffcfb3dc3163",
+  "core/.context/conventions/patterns.md": "abeb6602a1d38d7f50ce1c0ee55e63aa8c9b09109b73784416d0d325431b1bd1",
+  "core/.context/conventions/testing.md": "28db44f669a45cdeab8ecb796e621ed155503bdbd0168891d8bf2c94c044f4b4",
+  "core/.context/experience/debugging.md": "4467601549dbee4c3965a0e5857f9bef9877e879d8c7635a0e31676096d814b6",
+  "core/.context/experience/incidents.md": "2592bb9e3ac9cff1d4e642be9b452ac24c5a830b552d8ab61352db7d804c46e3",
+  "core/.context/experience/lessons.md": "920d084c61bc70da67689b43e54effd54038f442460f2f222b11a29c2f85c050",
+  "core/.context/experience/performance.md": "a1c8f4ba4f1dbdf158b78851945aaef299f31e6df4d288d4b9ba7f2be58221b0",
+  "core/.context/index.md": "a68cf7d7ffdc11082d79cbabb7d38e9f5e9f53d3fc2b88945f73062623fb1853",
+  "core/.context/progress/backlog.md": "fae3bdd0cfe38ecd60536325a2e3ab9ce23ac7909afbeb5766244b53180efc47",
+  "core/.context/progress/status.md": "8f3c32fd4f14268195e32d9ba4ef8aaf9aad85773fb5a7490c08db548d99abee",
+  "core/.context/workflow/artifacts/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "core/.context/workflow/config.md": "5dba519335d71b10df8f984ca11a06fa72adef9c864f2bfffc5d49195a1a91a7",
+  "core/AGENTS.md": "b41364e3aac1452a6839e2eff3b245478074a4c4e44d4b2c3f698cb9bb682cb8",
+  "core/scripts/compact-experience.sh": "b115333c6c77c3f76c843c2b6b47a9818d5149937a9c94544d7753947af7110b",
+  "core/scripts/detect-drift.sh": "0ab98593fe021b7e1f44d9d28dd42f6b3ece565b7033f3e084fe22fcda79e917",
+  "core/scripts/extract-structure.sh": "feaa0eea0a1154a1c519cdf213c15e70f28fdb5f6f090bbf4c786576c985b3b9",
+  "core/scripts/sync-context.sh": "b4753ce08c31a9308fd9d57acddfdf610033a70fbce77bd8b34077e056e2b3e7",
+  "claude/.claude/rules/context-maintenance.md": "a712145925641c54430a9cd3d0c56e807335493a1a826fab293e411ae4c7355d",
+  "claude/.claude/rules/experience-capture.md": "594856ba750e021e38c17547d66730538b87d793dc2f4bb02bc5b0766064967f",
+  "claude/.claude/settings.project.json": "1c2bbf83059dd4b0e30327e101ea4bf2c9cd592c7dabc7b3f97f5908fd5c56cc",
+  "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-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/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/team-config.md": "679a73ce17cd4dd0cbabf69ed665e840f4a21dc9b5f659c4bcd20c8e7b15f9a5",
+  "claude/.claude/workflow/agents/tester.md": "93b56bd201a6950e5a4cb66f5f0352a18b8c66c5619efd10fa84d7361c6bdff4",
+  "claude/.claude/workflow/interfaces/phase-contract.md": "9bfcb73a9ea23cac0a44a0b8fc77babda24450bd84b12fbe5b115b1c9a3b3b64",
+  "claude/CLAUDE.md": "a81997371fd35fec37fe38367f08d13256f68bd540a8bb126d908bbf4d2cc11d",
+  "cursor/.cursor/rules/always.mdc": "e653939afb8638e8ddd3bd081e8209632a8e004b466b8243029ea0fb77d2199f",
+  "cursor/.cursor/rules/backend.mdc": "1c42070f1a45ee2eafb2c24b9cc1da8e252c57a55941564134a07a9227e6336f",
+  "cursor/.cursor/rules/database.mdc": "844db9201176eb98281677828515242e6062e99f0e6091ed53660b78a72d3994",
+  "cursor/.cursor/rules/frontend.mdc": "1323496c8bbe14bd313d256282313716b44f5cabbd50ab743fa0e919bf4a3a37",
+  "cursor/.cursorrules": "83a03ad02ee0ebb61e6c9ee2f2a2df87aa2c969bd4bd7776320ac18985e83dba",
+  "github/.github/copilot-instructions.md": "5c9bc4166f203a41c99f99fd6ded0c0fae7ee8586da16db2b7346ff4ab763584",
+  "github/.github/workflows/context-drift.yml": "b434e322a528816f39588e91221d4fc2af100685fd824e5fa70361564ac9d33b"
+}

package/templates/claude/.claude/rules/context-maintenance.md

@@ -0,0 +1,38 @@
+---
+description: "Enforce context file maintenance when code changes affect documented areas"
+---
+
+# Context Maintenance Rule
+
+## When Modifying Code
+
+After writing or editing files, check if the changes affect any documented areas:
+
+| If you changed... | 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` (regenerate via `scripts/extract-structure.sh`) |
+| CI/CD configs, Docker files, deployment configs | `.context/architecture/infrastructure.md` |
+| Introduced new design patterns | `.context/conventions/patterns.md` |
+| Changed error handling approach | `.context/conventions/error-handling.md` |
+
+## For Auto-Generated Files
+
+Files marked with `<!-- AUTO-GENERATED -->` should be regenerated using `scripts/sync-context.sh` rather than edited manually. These include:
+- `architecture/data-model.md`
+- `architecture/api-surface.md`
+- `architecture/dependencies.md`
+- `architecture/class-index.md` (also regenerable via `scripts/extract-structure.sh`)
+
+## Update Progress
+
+Before ending a session or when context compaction occurs, update `.context/progress/status.md` with:
+- Current task status
+- What was done
+- What remains
+- Key decisions made

package/templates/claude/.claude/rules/experience-capture.md

@@ -0,0 +1,46 @@
+---
+description: "Capture development experience and knowledge after significant events"
+---
+
+# Experience Capture Rule
+
+## After Fixing a Non-Trivial Bug
+
+Append an entry to `.context/experience/debugging.md`:
+```markdown
+### "[Error Message or Symptom]"
+- **Cause**: [Why this happened]
+- **Fix**: [How it was resolved]
+- **Prevention**: [How to avoid in future]
+```
+
+## After Resolving a Performance Issue
+
+Append an entry to `.context/experience/performance.md`:
+```markdown
+### YYYY-MM-DD: [Optimization Title]
+- **Before**: [Metric before]
+- **After**: [Metric after]
+- **What Changed**: [What was optimized]
+- **Tags**: #tag1 #tag2
+```
+
+## After Making a Significant Architectural Decision
+
+Create a new ADR file in `.context/architecture/decisions/`:
+- Use the next available number (e.g., `002-decision-name.md`)
+- Follow the template in `001-template.md`
+
+## After Discovering a Lesson or Anti-Pattern
+
+Append to `.context/experience/lessons.md`:
+```markdown
+### YYYY-MM-DD: [Short Title]
+- **Context**: [What was happening]
+- **Root Cause**: [Why it happened]
+- **Resolution**: [How it was fixed]
+- **Prevention**: [Steps taken to prevent recurrence]
+- **Tags**: #tag1 #tag2
+```
+
+If a lesson reveals a pattern worth codifying, also add it to `.context/conventions/patterns.md`.

package/templates/claude/.claude/settings.project.json

@@ -0,0 +1,22 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "echo '[Context Reminder] If this change affects architecture, data models, APIs, or conventions, remember to update the corresponding .context/ file.'"
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "command": "cat .context/constitution.md 2>/dev/null || echo 'No constitution.md found. Run /bootstrap-context to initialize.'"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash(git commit*)",
+        "command": "bash scripts/detect-drift.sh 2>/dev/null || echo '[Drift Detection] Script not found or failed. Consider running: bash scripts/detect-drift.sh'"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,223 @@
+---
+name: bootstrap-context
+description: Build the .context/ system for a new or undocumented project by analyzing the existing codebase
+triggers:
+  - bootstrap context
+  - setup context
+  - initialize context
+  - build context
+---
+
+# Bootstrap Context Skill
+
+Build a comprehensive `.context/` system for the current project by analyzing the existing codebase, documentation, and git history. This follows the ACE-FCA Research-Plan-Implement pattern.
+
+## Prerequisites
+
+- The `.context/` directory structure must exist (copy from the ContextEngineer template)
+- The project should have existing source code to analyze
+
+## Workflow
+
+Execute bootstrap in **3 rounds with human checkpoints** between each round. This prevents errors from compounding and ensures the foundation is correct before building on it.
+
+---
+
+### Round 1: Foundation (Skeleton)
+
+**Goal**: Establish project identity, tech stack, and high-level architecture.
+
+#### 1a. Discovery
+
+1. **Project Structure Scan**
+   - Use Glob to map the complete directory structure
+   - Identify source code directories, test directories, config files, documentation
+
+2. **Tech Stack Detection**
+   - Scan for manifest files to identify languages and frameworks:
+     - `package.json` → Node.js/TypeScript (check for Express, NestJS, React, Vue, Angular)
+     - `*.csproj` / `*.sln` → .NET/C# (check for ASP.NET Core, EF Core)
+     - `requirements.txt` / `pyproject.toml` / `setup.py` → Python (check for Django, FastAPI, Flask)
+     - `go.mod` → Go
+     - `Cargo.toml` → Rust
+     - `pom.xml` / `build.gradle` → Java (check for Spring Boot)
+   - Read the manifest files to extract dependency lists
+
+3. **Existing Documentation**
+   - Read README.md, CONTRIBUTING.md, docs/ folder
+   - Check for existing CLAUDE.md, AGENTS.md, .cursorrules
+   - Check for OpenAPI/Swagger specs
+
+#### 1b. Generate
+
+1. **`.context/constitution.md`** — Fill in:
+   - Project Identity (name, tech stack, language, repo)
+   - Non-negotiable Principles (inferred from code patterns + linting config)
+   - Build & Test Commands (from manifest files and scripts)
+   - Keep the Context Loading Route Table as-is (it's universal)
+
+2. **`.context/architecture/overview.md`** — Fill in:
+   - Tech stack table
+   - System architecture diagram (ASCII)
+   - Directory structure description
+   - Subsystem breakdown (one-line per subsystem)
+   - Key interfaces between subsystems
+   - Threading/concurrency model
+   - Key design decisions
+
+#### 1c. Checkpoint
+
+**STOP and present to the user:**
+- Show the generated `constitution.md` and `overview.md`
+- Ask the user to verify: project identity, tech stack, build commands, architecture description
+- Ask: "Are the non-negotiable principles correct? Anything to add or remove?"
+- **Do NOT proceed to Round 2 until the user confirms Round 1 is accurate.**
+
+---
+
+### Round 2: Architecture & Conventions (Detail)
+
+**Goal**: Fill in detailed architecture docs and coding conventions.
+
+#### 2a. Discovery
+
+4. **Code Pattern Analysis**
+   - Sample 5-10 representative source files across different layers
+   - Identify: naming conventions, file organization, error handling patterns
+   - Look for architectural patterns (MVC, Clean Architecture, CQRS, etc.)
+
+5. **Data Model Extraction**
+   - Search for ORM models, migration files, schema definitions
+   - Extract entities, relationships, key fields
+
+6. **API Surface Mapping**
+   - Search for route/controller definitions
+   - Extract endpoints, HTTP methods, path patterns
+
+7. **Git History Analysis**
+   - Check recent 20-50 commits for: commit message conventions, branch patterns
+   - Identify active contributors and development pace
+
+8. **Module Boundary Discovery**
+   - Scan all top-level source directories to identify subsystems/modules
+   - Analyze namespace, package, and directory structure
+   - Map directory → module → namespace relationships
+
+9. **Dependency Graph Extraction**
+   - Analyze #include / import / using statements across the codebase
+   - Build a module-level dependency graph (not file-level)
+   - Use `scripts/extract-structure.sh --module-graph` for automated extraction
+
+10. **Data Flow Analysis**
+    - Identify key execution paths (main → initialization → main loop → cleanup)
+    - Trace data transformation pipelines
+    - Identify async/multi-threaded data flows and synchronization points
+
+11. **Core Interface Extraction**
+    - Identify each module's public interface classes/functions
+    - Extract key inheritance hierarchies
+    - Use `scripts/extract-structure.sh --class-index` for automated extraction
+    - Focus on core classes only (5-15 per module)
+
+#### 2b. Generate
+
+3. **`.context/architecture/module-graph.md`** — Fill in human-curated sections:
+   - Subsystems table (module, directory, responsibility, key classes)
+   - ASCII dependency graph
+   - Module interfaces (public entry points, depends on, depended by)
+   - Auto-generated sections via `scripts/extract-structure.sh`
+
+4. **`.context/architecture/data-flow.md`** — Fill in:
+   - Application lifecycle (startup → run → shutdown)
+   - Core pipelines with stage diagrams
+   - Threading/concurrency model with synchronization points
+   - Event/message flow if applicable
+
+5. **`.context/architecture/class-index.md`** — Auto-generate:
+   - Run `scripts/extract-structure.sh --class-index`
+   - Mark as `<!-- AUTO-GENERATED -->`
+
+6. **`.context/architecture/data-model.md`** — Auto-generate:
+   - Tables/collections list and relationships
+   - Mark as `<!-- AUTO-GENERATED -->`
+
+7. **`.context/architecture/api-surface.md`** — Auto-generate:
+   - Endpoints list with methods, paths, descriptions
+   - Mark as `<!-- AUTO-GENERATED -->`
+
+8. **`.context/architecture/dependencies.md`** — Auto-generate:
+   - Runtime and dev dependency lists
+   - Mark as `<!-- AUTO-GENERATED -->`
+
+9. **`.context/conventions/code-style.md`** — Infer from code:
+   - Naming conventions, formatting rules, import ordering
+
+10. **`.context/conventions/patterns.md`** — Infer from code:
+    - Identified architectural patterns and common code patterns
+
+11. **`.context/conventions/testing.md`** — Infer from test files:
+    - Testing framework, test file naming, test structure
+
+12. **`.context/conventions/git.md`** — Infer from git history:
+    - Commit message convention, branch naming patterns
+
+13. **`.context/business/overview.md`** — Infer from README + code:
+    - Product description (note: usually needs human input)
+
+14. **`.context/business/workflows.md`** — Fill in:
+    - Core business workflows (for web/business apps)
+    - Technical pipelines (for engines/frameworks/tools)
+
+#### 2c. Checkpoint
+
+**STOP and present to the user:**
+- Summary of all generated files with confidence levels (high/medium/low)
+- Highlight areas that need human input (especially business context)
+- Note any uncertainties or ambiguities found
+- Ask: "Please review the architecture and conventions. Any corrections?"
+- **Do NOT proceed to Round 3 until the user confirms Round 2 is acceptable.**
+
+---
+
+### Round 3: Finalize (Adapters & Metadata)
+
+**Goal**: Generate tool-specific adapters, update metadata, establish baseline.
+
+#### 3a. Generate
+
+15. **`.context/index.md`** — Update to reflect actual content generated
+
+16. **Tool Adapters** — Generate after human validation:
+    - Update AGENTS.md with project-specific information
+    - Update CLAUDE.md with Claude-specific guidance
+    - Update .cursor/rules/*.mdc with Cursor-specific rules
+
+#### 3b. Metadata
+
+- Update `.context/_meta/last-sync.json` with timestamps
+- Run `scripts/detect-drift.sh --semantic` to establish baseline
+
+#### 3c. Final Report
+
+Present completion summary:
+- Total files generated, with confidence levels
+- Remaining action items (files needing human input)
+- Baseline drift report status
+
+---
+
+## File Markers
+
+For each generated file, always add:
+- `<!-- confidence: high|medium|low -->` based on analysis certainty
+- `<!-- source: [files analyzed] -->` for traceability
+- `<!-- last-updated: YYYY-MM-DD -->` with today's date
+
+## Output
+
+The skill produces a fully populated `.context/` system with:
+- All context files filled with analyzed content
+- Confidence markers on every file
+- Source traceability comments
+- Tool-specific adapter files configured
+- Updated metadata and baseline drift report