agent-eng 0.13.0 → 0.14.0

package/package.json

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

package/src/init.js

@@ -6,15 +6,20 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = join(__dirname, "templates");
 
-const STRUCTURE = [
+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",
@@ -22,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) => {
@@ -60,13 +67,18 @@ export async function init(options) {
 
   const existing = [];
   const fresh = [];
+  const protectedFiles = [];
 
   for (const file of allFiles) {
     const dest = join(target, file);
-    if (existsSync(dest) && !options.force) {
-      existing.push(file);
-    } else {
+    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);
     }
   }
 
@@ -151,6 +163,14 @@ export async function init(options) {
     }
   }
 
+  if (protectedFiles.length > 0) {
+    console.log("");
+    console.log("Protected (project state — use --force to overwrite):");
+    for (const f of protectedFiles) {
+      console.log(`  ${f}`);
+    }
+  }
+
   console.log("");
   console.log("✔ Agentic workflow initialized");
   console.log("");

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