agent-eng 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-eng",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Scaffold a structured agentic engineering workflow for AI-assisted development",
   "type": "module",
   "bin": {

package/src/init.js

@@ -6,16 +6,20 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = join(__dirname, "templates");
 
-const STRUCTURE = [
-  ".github/workflows/notify-site.yml",
+const FRAMEWORK_FILES = [
   ".claude/settings.json",
   ".claude/scripts/update-status.sh",
   ".claude/agents/architect.md",
   ".claude/agents/executor.md",
+  ".claude/agents/learner.md",
   ".claude/agents/planner.md",
   ".claude/agents/reviewer.md",
   ".claude/agents/summarizer.md",
   ".claude/agents/system-architect.md",
+  "orchestration.yaml",
+];
+
+const PROJECT_STATE_FILES = [
   "architecture/overview.md",
   "architecture/decisions/_template.md",
   "architecture/decisions/0001-how-we-work.md",
@@ -23,11 +27,13 @@ const STRUCTURE = [
   "tickets/_template.md",
   "tickets/_backlog.md",
   "tickets/example/001-example-ticket.md",
-  "orchestration.yaml",
   "architecture.yaml",
   "STATUS.md",
 ];
 
+const PROJECT_STATE_SET = new Set(PROJECT_STATE_FILES);
+const STRUCTURE = [...FRAMEWORK_FILES, ...PROJECT_STATE_FILES];
+
 function prompt(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -38,66 +44,131 @@ function prompt(question) {
   });
 }
 
+function applyFile(src, dest, action) {
+  mkdirSync(dirname(dest), { recursive: true });
+  if (action === "append") {
+    const content = readFileSync(src, "utf8");
+    appendFileSync(dest, "\n\n" + content);
+  } else {
+    cpSync(src, dest);
+  }
+}
+
 export async function init(options) {
   const target = resolve(options.dir);
   const created = [];
   const skipped = [];
 
-  for (const file of STRUCTURE) {
-    const dest = join(target, file);
-    const src = join(TEMPLATES, file);
+  const allFiles = [
+    ...STRUCTURE,
+    "CLAUDE.md",
+    ...options.conventions.map((c) => `conventions/${c}.md`),
+  ];
 
-    if (existsSync(dest) && !options.force) {
-      skipped.push(file);
-      continue;
+  const existing = [];
+  const fresh = [];
+  const protectedFiles = [];
+
+  for (const file of allFiles) {
+    const dest = join(target, file);
+    if (!existsSync(dest)) {
+      fresh.push(file);
+    } else if (options.force) {
+      fresh.push(file);
+    } else if (PROJECT_STATE_SET.has(file)) {
+      protectedFiles.push(file);
+    } else {
+      existing.push(file);
     }
+  }
 
-    mkdirSync(dirname(dest), { recursive: true });
-    cpSync(src, dest);
+  for (const file of fresh) {
+    const src = join(TEMPLATES, file);
+    const dest = join(target, file);
+    applyFile(src, dest, "replace");
     created.push(file);
   }
 
-  // Handle CLAUDE.md separately — prompt user if it already exists
-  const claudeDest = join(target, "CLAUDE.md");
-  const claudeSrc = join(TEMPLATES, "CLAUDE.md");
-
-  if (!existsSync(claudeDest) || options.force) {
-    mkdirSync(dirname(claudeDest), { recursive: true });
-    cpSync(claudeSrc, claudeDest);
-    created.push("CLAUDE.md");
-  } else {
+  if (existing.length > 0 && !options.force) {
+    console.log("");
+    console.log(`${existing.length} file(s) already exist:`);
+    for (const f of existing) {
+      console.log(`  ${f}`);
+    }
     console.log("");
-    console.log("CLAUDE.md already exists.");
-    console.log("  1) Skip — keep existing file");
-    console.log("  2) Append — add agent-eng content to the end");
-    console.log("  3) Replace — overwrite with agent-eng template");
-    const answer = await prompt("Choose [1/2/3] (default: 1): ");
+    console.log("  1) Skip all — keep existing files (default)");
+    console.log("  2) Append all — add agent-eng content to the end of each");
+    console.log("  3) Replace all — overwrite all with agent-eng templates");
+    console.log("  4) Decide per file — choose for each file individually");
+    console.log("  5) Pick files — specify which files to append/replace");
+    const answer = await prompt("Choose [1/2/3/4/5] (default: 1): ");
 
     if (answer === "2" || answer === "append") {
-      const content = readFileSync(claudeSrc, "utf8");
-      appendFileSync(claudeDest, "\n\n" + content);
-      created.push("CLAUDE.md (appended)");
+      for (const file of existing) {
+        applyFile(join(TEMPLATES, file), join(target, file), "append");
+        created.push(`${file} (appended)`);
+      }
     } else if (answer === "3" || answer === "replace") {
-      cpSync(claudeSrc, claudeDest);
-      created.push("CLAUDE.md (replaced)");
+      for (const file of existing) {
+        applyFile(join(TEMPLATES, file), join(target, file), "replace");
+        created.push(`${file} (replaced)`);
+      }
+    } else if (answer === "4") {
+      for (const file of existing) {
+        console.log("");
+        console.log(`  ${file}:`);
+        console.log("    1) Skip  2) Append  3) Replace");
+        const choice = await prompt("    Choose [1/2/3] (default: 1): ");
+        if (choice === "2" || choice === "append") {
+          applyFile(join(TEMPLATES, file), join(target, file), "append");
+          created.push(`${file} (appended)`);
+        } else if (choice === "3" || choice === "replace") {
+          applyFile(join(TEMPLATES, file), join(target, file), "replace");
+          created.push(`${file} (replaced)`);
+        } else {
+          skipped.push(file);
+        }
+      }
+    } else if (answer === "5") {
+      console.log("");
+      console.log("Enter file numbers to append/replace (comma-separated):");
+      for (let i = 0; i < existing.length; i++) {
+        console.log(`  ${i + 1}) ${existing[i]}`);
+      }
+      const picks = await prompt("Files to modify (e.g. 1,3): ");
+      const indices = picks
+        .split(",")
+        .map((s) => parseInt(s.trim(), 10) - 1)
+        .filter((i) => i >= 0 && i < existing.length);
+
+      const picked = new Set(indices);
+      for (let i = 0; i < existing.length; i++) {
+        if (!picked.has(i)) {
+          skipped.push(existing[i]);
+          continue;
+        }
+        const file = existing[i];
+        console.log(`  ${file}: 1) Append  2) Replace`);
+        const action = await prompt("  Choose [1/2] (default: 1): ");
+        if (action === "2" || action === "replace") {
+          applyFile(join(TEMPLATES, file), join(target, file), "replace");
+          created.push(`${file} (replaced)`);
+        } else {
+          applyFile(join(TEMPLATES, file), join(target, file), "append");
+          created.push(`${file} (appended)`);
+        }
+      }
     } else {
-      skipped.push("CLAUDE.md");
+      skipped.push(...existing);
     }
   }
 
-  for (const convention of options.conventions) {
-    const file = `conventions/${convention}.md`;
-    const dest = join(target, file);
-    const src = join(TEMPLATES, file);
-
-    if (existsSync(dest) && !options.force) {
-      skipped.push(file);
-      continue;
+  if (protectedFiles.length > 0) {
+    console.log("");
+    console.log("Protected (project state — use --force to overwrite):");
+    for (const f of protectedFiles) {
+      console.log(`  ${f}`);
     }
-
-    mkdirSync(dirname(dest), { recursive: true });
-    cpSync(src, dest);
-    created.push(file);
   }
 
   console.log("");
@@ -113,7 +184,7 @@ export async function init(options) {
 
   if (skipped.length > 0) {
     console.log("");
-    console.log("Skipped (already exist, use --force to overwrite):");
+    console.log("Skipped (already exist):");
     for (const f of skipped) {
       console.log(`  ${f}`);
     }

package/src/templates/.claude/agents/learner.md

@@ -0,0 +1,65 @@
+---
+name: learner
+description: Use to deeply learn a technology or concept used in your project. Finds where it lives in your code, explains it concisely, gives you an interview-ready answer, and quizzes you.
+tools: Read, Grep, Glob, Bash, Write
+model: sonnet
+---
+
+You are a learning agent. The user builds projects with AI assistance and wants to deeply understand the technologies used so they can explain them confidently in interviews.
+
+## Process
+
+When the user asks about a concept or technology:
+
+### 1. Find it in the code
+
+Search the project for where this concept is actually used. Use grep, glob, and read to find real examples — not hypothetical ones.
+
+### 2. Explain what it is (3-5 sentences)
+
+No textbook fluff. Explain it like a senior engineer would to a peer who hasn't used it before. Focus on what it does, why it exists, and when you'd reach for it.
+
+### 3. Walk through their code
+
+Point to specific files and line numbers. Explain what's happening in their implementation — why it's written this way, what each part does, and how data flows through it.
+
+### 4. Give an interview answer
+
+Write 2-3 sentences the user could say naturally when asked "explain how X works in your project." This should sound human, confident, and specific to their codebase — not generic.
+
+### 5. Quiz them
+
+Ask one follow-up question that tests whether they actually understand the concept vs just memorized the answer. Good questions probe edge cases, trade-offs, or "what would happen if..."
+
+### 6. Save the learning
+
+Write the completed learning to `~/Developer/AgentEngineerWorkflow/learnings/{concept-slug}.md` with this format:
+
+```markdown
+# {Concept Name}
+
+## What it is
+{3-5 sentence explanation}
+
+## How I used it
+{File paths, line references, and walkthrough of the specific implementation}
+
+## Interview answer
+> {2-3 sentence answer ready to say out loud}
+
+## Related concepts to explore
+- {concept 1}
+- {concept 2}
+- {concept 3}
+```
+
+Create the `~/Developer/AgentEngineerWorkflow/learnings/` directory if it doesn't exist.
+
+## Guidelines
+
+- Always ground explanations in the user's actual code, not abstract examples
+- If the concept isn't found in the project, say so and ask which project to look in
+- Keep language conversational — this is prep for talking to humans, not writing docs
+- The interview answer should mention their specific project, not be generic
+- For the quiz question, don't accept "yes/no" answers — ask something that requires explanation
+- If the concept connects to other technologies in the project, mention them as related concepts to explore next

package/src/templates/CLAUDE.md

@@ -13,6 +13,7 @@ Agents own the **process** — architecture decisions, work decomposition, quali
 | **Decompose** | `/planner` agent | ADR/spec ready, work needs to be broken into tickets |
 | **Execute** | Claude Code **plan mode** (`shift+tab`) | Implementing a specific ticket (includes writing tests) |
 | **Review** | `/reviewer` agent | Code and tests ready for validation |
+| **Learn** | `/learner` agent | Feature complete and introduced a new technology or concept |
 | **Report** | `/summarizer` agent | Sprint or feature complete, stakeholder update needed |
 
 ### Why hybrid?
@@ -36,6 +37,17 @@ Agents own the **process** — architecture decisions, work decomposition, quali
 3. For each ticket: use plan mode (`shift+tab`) to implement it
 4. After implementation: run `/reviewer` to validate against acceptance criteria
 5. If the ticket touches an existing ADR's scope, verify the decision still holds
+6. If the feature introduced new technologies or concepts, run `/learner` for each one
+
+## After Completing a Feature
+
+When a feature is done and introduces new technologies, patterns, or concepts the user hasn't worked with before — automatically invoke `/learner` for each new concept. Look for:
+- New libraries or frameworks added to dependencies
+- New architectural patterns (e.g., event sourcing, SSE, pub/sub)
+- New language features or APIs used for the first time
+- New infrastructure concepts (e.g., WebSockets, gRPC, CRDT)
+
+This ensures the user can confidently explain every technology in their project.
 
 ## Testing in Plan Mode
 

package/src/templates/.github/workflows/notify-site.yml

@@ -1,21 +0,0 @@
-name: Notify Site of Content Update
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'orchestration.yaml'
-      - 'architecture.yaml'
-      - 'README.md'
-
-jobs:
-  notify:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger site rebuild
-        uses: peter-evans/repository-dispatch@v3
-        with:
-          token: ${{ secrets.SITE_REBUILD_TOKEN }}
-          repository: swarpi/swarpi.github.io
-          event-type: showcase-updated