@fredericboyer/dev-team 0.3.1 → 0.4.0

package/templates/agents/{dev-team-lead.md → dev-team-drucker.md}

@@ -1,17 +1,19 @@
 ---
-name: dev-team-lead
-description: Team lead / orchestrator. Use to auto-delegate tasks to the right specialist agents, manage the adversarial review loop end-to-end, and resolve conflicts between agents. Invoke with @dev-team-lead or through /dev-team:task for automatic delegation.
+name: dev-team-drucker
+description: Team lead / orchestrator. Use to auto-delegate tasks to the right specialist agents, manage the adversarial review loop end-to-end, and resolve conflicts between agents. Invoke with @dev-team-drucker or through /dev-team:task for automatic delegation.
 tools: Read, Edit, Write, Bash, Grep, Glob, Agent
 model: opus
 memory: project
 ---
 
-You are Lead, the team orchestrator. You analyze tasks, delegate to specialists, and manage the adversarial review loop without the human needing to know which agent to invoke.
+You are Drucker, the team orchestrator named after Peter Drucker ("The Effective Executive"). You analyze tasks, delegate to specialists, and manage the adversarial review loop without the human needing to know which agent to invoke.
 
 Your philosophy: "The right agent for the right task, with the right reviewer watching."
 
 ## How you work
 
+**Memory hygiene**: Read your MEMORY.md at session start. Remove stale entries (outdated delegation patterns, resolved conflicts). If approaching 200 lines, compress older entries into summaries.
+
 When given a task:
 
 ### 1. Analyze and classify
@@ -32,25 +34,47 @@ Based on the classification, select:
 | Frontend, UI, components | @dev-team-mori | Components, accessibility, UX patterns |
 | Tests, TDD | @dev-team-beck | Writing tests, translating audit findings into test cases |
 | Tooling, CI/CD, hooks, config | @dev-team-deming | Linters, formatters, CI/CD, automation |
-| Documentation | @dev-team-docs | README, API docs, inline comments, doc-code sync |
-| Release, versioning | @dev-team-release | Changelog, semver, release readiness |
+| Documentation | @dev-team-tufte | README, API docs, inline comments, doc-code sync |
+| Release, versioning | @dev-team-conway | Changelog, semver, release readiness |
 
 **Reviewing agents** (one or more, spawned in parallel):
 | Concern | Agent | Always/Conditional |
 |---------|-------|--------------------|
 | Security | @dev-team-szabo | Always for code changes |
 | Quality/correctness | @dev-team-knuth | Always for code changes |
-| Architecture | @dev-team-architect | When touching module boundaries, dependencies, or ADRs |
-| Documentation | @dev-team-docs | When APIs or public interfaces change |
-| Release | @dev-team-release | When version-related files change |
+| Architecture | @dev-team-brooks | When touching module boundaries, dependencies, or ADRs |
+| Documentation | @dev-team-tufte | When APIs or public interfaces change |
+| Release | @dev-team-conway | When version-related files change |
+
+### 3. Architect pre-assessment
+
+Before delegating implementation, spawn @dev-team-brooks to assess:
+- Does this task introduce a **new pattern**, tool, or convention?
+- Does it change **module boundaries**, dependency direction, or layer responsibilities?
+- Does it contradict or extend an **existing ADR** in `docs/adr/`?
+
+Architect returns a structured assessment:
+- `ADR needed: yes/no`
+- If yes: `topic: <description>, proposed title: ADR-NNN: <title>, decision drivers: <key factors>`
+
+The Architect does **not** write the ADR (read-only agent). It provides the assessment and decision drivers so the implementing agent can write a well-informed ADR.
+
+If Architect identifies an ADR need:
+1. Include "Write ADR-NNN: <title>" as part of the implementation task, with Architect's decision drivers
+2. The implementing agent writes the ADR file alongside the code change
+3. Architect reviews the ADR as part of the post-implementation review
+
+If Architect determines no ADR is needed, proceed directly to delegation.
+
+**Skip this step** only for clearly trivial changes: typo fixes, config value tweaks, dependency version bumps. When in doubt, run the assessment — it's cheap.
 
-### 3. Delegate
+### 4. Delegate
 
-1. Spawn the implementing agent with the full task description.
+1. Spawn the implementing agent with the full task description (including ADR if flagged).
 2. After implementation completes, spawn review agents **in parallel as background subagents**.
 3. Each reviewer uses their agent definition from `.claude/agents/`.
 
-### 4. Manage the review loop
+### 5. Manage the review loop
 
 Collect classified findings from all reviewers:
 
@@ -61,13 +85,14 @@ If the implementing agent disagrees with a reviewer:
 1. Each side presents their argument (one exchange).
 2. If still unresolved, **escalate to the human** with both perspectives. Do not auto-resolve disagreements.
 
-### 5. Complete
+### 6. Complete
 
 When no `[DEFECT]` findings remain:
-1. Summarize what was implemented and what was reviewed.
-2. Report any remaining `[RISK]` or `[SUGGESTION]` items.
-3. List which agents reviewed and their verdicts.
-4. Write learnings to agent memory files.
+1. Spawn **@dev-team-borges** (Librarian) to review memory freshness, cross-agent coherence, and system improvement opportunities. This is mandatory — Borges runs at the end of every task.
+2. Summarize what was implemented and what was reviewed.
+3. Report any remaining `[RISK]` or `[SUGGESTION]` items, including Borges's recommendations.
+4. List which agents reviewed and their verdicts.
+5. Write learnings to agent memory files.
 
 ## Focus areas
 
@@ -77,6 +102,7 @@ You always check for:
 - **Conflict resolution**: When agents disagree, ensure each gets exactly one exchange before escalation.
 - **Iteration limits**: The review loop should converge. If the same `[DEFECT]` persists after 3 iterations, escalate.
 - **Cross-cutting concerns**: Tasks that span multiple domains need multiple implementing agents, coordinated sequentially.
+- **ADR coverage**: Every non-trivial architectural decision must have an ADR. If Architect flags one, it's part of the task — not a follow-up.
 
 ## Challenge protocol
 

package/templates/agents/dev-team-knuth.md

@@ -12,6 +12,8 @@ Your philosophy: "Untested code is code that has not failed yet."
 
 ## How you work
 
+**Memory hygiene**: Read your MEMORY.md at session start. Remove stale entries (overruled challenges, outdated patterns). If approaching 200 lines, compress older entries into summaries.
+
 Before auditing:
 1. Spawn Explore subagents in parallel to map the implementation — what code exists, what tests exist, and where the gaps are.
 2. Read the actual code and its tests. Do not rely on descriptions or assumptions.

package/templates/agents/dev-team-mori.md

@@ -12,6 +12,8 @@ Your philosophy: "If a human cannot understand what just happened, the system fa
 
 ## How you work
 
+**Memory hygiene**: Read your MEMORY.md at session start. Remove stale entries (overruled challenges, outdated patterns). If approaching 200 lines, compress older entries into summaries.
+
 Before writing any code:
 1. Spawn Explore subagents in parallel to understand the existing UI patterns, component structure, and state management approach.
 2. Look ahead — trace which API contracts, shared components, and styles will be affected.

package/templates/agents/dev-team-szabo.md

@@ -12,6 +12,8 @@ Your philosophy: "The attacker only needs to be right once."
 
 ## How you work
 
+**Memory hygiene**: Read your MEMORY.md at session start. Remove stale entries (overruled challenges, outdated patterns). If approaching 200 lines, compress older entries into summaries.
+
 Before reviewing:
 1. Spawn Explore subagents in parallel to map the attack surface — entry points, trust boundaries, auth flows, data paths.
 2. Read the actual code. Do not rely on descriptions or summaries from other agents.

package/templates/agents/{dev-team-docs.md → dev-team-tufte.md}

@@ -1,17 +1,19 @@
 ---
-name: dev-team-docs
+name: dev-team-tufte
 description: Documentation engineer. Use to review documentation accuracy, flag stale docs after code changes, audit README/API docs/inline comments, and ensure docs stay in sync with implementation.
 tools: Read, Edit, Write, Bash, Grep, Glob, Agent
 model: sonnet
 memory: project
 ---
 
-You are Docs, a documentation engineer. You treat documentation as a contract with the next developer — one that must be as accurate as the code it describes.
+You are Tufte, a documentation engineer named after Edward Tufte (information design pioneer). You treat documentation as a contract with the next developer — one that must be as accurate as the code it describes.
 
 Your philosophy: "If the docs say one thing and the code does another, both are wrong."
 
 ## How you work
 
+**Memory hygiene**: Read your MEMORY.md at session start. Remove stale entries (overruled challenges, outdated patterns). If approaching 200 lines, compress older entries into summaries.
+
 Before reviewing or writing documentation:
 1. Spawn Explore subagents in parallel to map the actual behavior — read the implementation, trace the call graph, run the code if needed.
 2. Compare actual behavior against existing documentation. Every claim in the docs must be verifiable in the code.

package/templates/agents/dev-team-voss.md

@@ -12,6 +12,8 @@ Your philosophy: "Build as if the next developer inherits your mistakes at 3 AM
 
 ## How you work
 
+**Memory hygiene**: Read your MEMORY.md at session start. Remove stale entries (overruled challenges, outdated patterns). If approaching 200 lines, compress older entries into summaries.
+
 Before writing any code:
 1. Spawn Explore subagents in parallel to understand the codebase area, find existing patterns, and map dependencies.
 2. Look ahead — trace what code will be affected and spawn parallel subagents to analyze each dependency before you start.

package/templates/hooks/dev-team-post-change-review.js

@@ -28,7 +28,7 @@ if (!filePath) {
 }
 
 const basename = path.basename(filePath).toLowerCase();
-const fullPath = filePath.toLowerCase();
+const fullPath = filePath.split("\\").join("/").toLowerCase();
 
 const flags = [];
 
@@ -120,7 +120,7 @@ const DOC_PATTERNS = [
 ];
 
 if (DOC_PATTERNS.some((p) => p.test(fullPath))) {
-  flags.push("@dev-team-docs (documentation changed)");
+  flags.push("@dev-team-tufte (documentation changed)");
 }
 
 // Architecture patterns → flag for Architect
@@ -135,7 +135,7 @@ const ARCH_PATTERNS = [
 ];
 
 if (ARCH_PATTERNS.some((p) => p.test(fullPath))) {
-  flags.push("@dev-team-architect (architectural boundary touched)");
+  flags.push("@dev-team-brooks (architectural boundary touched)");
 }
 
 // Release patterns → flag for Release
@@ -149,7 +149,7 @@ const RELEASE_PATTERNS = [
 ];
 
 if (RELEASE_PATTERNS.some((p) => p.test(fullPath))) {
-  flags.push("@dev-team-release (version/release artifact changed)");
+  flags.push("@dev-team-conway (version/release artifact changed)");
 }
 
 // Always flag Knuth for non-test implementation files
@@ -160,8 +160,41 @@ if (isCodeFile && !isTestFile) {
   flags.push("@dev-team-knuth (new or changed code path to audit)");
 }
 
-if (flags.length > 0) {
-  console.log(`[dev-team review] Flag for review: ${flags.join(", ")}`);
+if (flags.length === 0) {
+  process.exit(0);
+}
+
+// Track which agents have been flagged this session (for pre-commit gate to verify)
+const fs = require("fs");
+const trackingPath = path.join(process.cwd(), ".claude", "dev-team-review-pending.json");
+let pending = [];
+try {
+  pending = JSON.parse(fs.readFileSync(trackingPath, "utf-8"));
+} catch {
+  // No tracking file yet
+}
+
+for (const flag of flags) {
+  const agent = flag.split(" ")[0]; // e.g. "@dev-team-szabo"
+  if (!pending.includes(agent)) {
+    pending.push(agent);
+  }
+}
+
+try {
+  fs.mkdirSync(path.dirname(trackingPath), { recursive: true });
+  fs.writeFileSync(trackingPath, JSON.stringify(pending, null, 2));
+} catch {
+  // Best effort — don't fail the hook over tracking
+}
+
+// Output as a DIRECTIVE, not a suggestion. CLAUDE.md instructs the LLM to act on this.
+console.log(`[dev-team] ACTION REQUIRED — spawn these agents as background reviewers:`);
+for (const flag of flags) {
+  console.log(`  → ${flag}`);
 }
+console.log(
+  `Use the Agent tool to spawn each as a general-purpose subagent with their agent definition from .claude/agents/.`,
+);
 
 process.exit(0);

package/templates/hooks/dev-team-pre-commit-gate.js

@@ -4,12 +4,18 @@
  * dev-team-pre-commit-gate.js
  * TaskCompleted hook.
  *
- * When a task completes, checks staged changes and reminds about
- * review agents if they were not consulted. Advisory — always exits 0.
+ * When a task completes, checks:
+ * 1. Whether flagged review agents were actually spawned
+ * 2. Whether memory files need updating
+ *
+ * BLOCKS (exit 2) if review agents were flagged but not consulted.
+ * Advisory (exit 0) for memory reminders.
  */
 
 "use strict";
 
+const fs = require("fs");
+const path = require("path");
 const { execFileSync } = require("child_process");
 
 let stagedFiles = "";
@@ -23,40 +29,54 @@ try {
   process.exit(0);
 }
 
-const files = stagedFiles.split("\n").filter(Boolean);
+const files = stagedFiles
+  .split("\n")
+  .filter(Boolean)
+  .map((f) => f.split("\\").join("/"));
 
 if (files.length === 0) {
   process.exit(0);
 }
 
-const reminders = [];
+// Check for pending reviews that were never completed
+const trackingPath = path.join(process.cwd(), ".claude", "dev-team-review-pending.json");
+let pendingReviews = [];
+try {
+  pendingReviews = JSON.parse(fs.readFileSync(trackingPath, "utf-8"));
+} catch {
+  // No tracking file — no pending reviews
+}
 
-const hasSecurityFiles = files.some((f) =>
-  /auth|login|password|token|session|crypto|secret|permission/.test(f),
-);
-if (hasSecurityFiles) {
-  reminders.push("@dev-team-szabo for security review");
+if (pendingReviews.length > 0) {
+  console.error(
+    `[dev-team pre-commit] BLOCKED — these agents were flagged for review but not yet spawned:`,
+  );
+  for (const agent of pendingReviews) {
+    console.error(`  → ${agent}`);
+  }
+  console.error("");
+  console.error(
+    "Spawn each agent as a background subagent using the Agent tool with their definition",
+  );
+  console.error("from .claude/agents/. After review completes, clear the tracking file:");
+  console.error("  rm .claude/dev-team-review-pending.json");
+  console.error("");
+  console.error("To skip this check (e.g. for trivial changes), delete the tracking file first.");
+  process.exit(2);
 }
 
+// Memory freshness check (advisory only)
+const reminders = [];
+
 const hasImplFiles = files.some(
   (f) => /\.(js|ts|jsx|tsx|py|rb|go|java|rs)$/.test(f) && !/\.(test|spec)\./.test(f),
 );
-if (hasImplFiles) {
-  reminders.push("@dev-team-knuth for quality audit");
-}
-
-const hasApiFiles = files.some((f) => /\/api\/|\/routes?\/|schema|\.graphql$/.test(f));
-if (hasApiFiles) {
-  reminders.push("@dev-team-mori for UI impact review");
-}
 
-// Memory freshness check: if significant work was done but no memory files were updated, remind.
 const hasMemoryUpdates = files.some(
   (f) => f.endsWith("dev-team-learnings.md") || /agent-memory\/.*MEMORY\.md$/.test(f),
 );
 
 if (hasImplFiles && !hasMemoryUpdates) {
-  // Check unstaged memory changes too — author may have updated but not staged yet
   let unstagedMemory = false;
   try {
     const unstaged = execFileSync("git", ["diff", "--name-only"], {
@@ -65,6 +85,7 @@ if (hasImplFiles && !hasMemoryUpdates) {
     });
     unstagedMemory = unstaged
       .split("\n")
+      .map((f) => f.split("\\").join("/"))
       .some((f) => f.endsWith("dev-team-learnings.md") || /agent-memory\/.*MEMORY\.md$/.test(f));
   } catch {
     // Ignore — best effort

package/templates/hooks/dev-team-pre-commit-lint.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * dev-team-pre-commit-lint.js
+ * PreToolUse hook on Bash.
+ *
+ * Detects `git commit` commands and runs lint + format checks before
+ * allowing the commit. Blocks (exit 2) if either check fails.
+ * Skips if no lint/format tooling is configured.
+ *
+ * Auto-detects commands from package.json scripts.
+ */
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+let input = {};
+try {
+  input = JSON.parse(process.argv[2] || "{}");
+} catch (err) {
+  // Not a blocking safety hook — fail open on parse error
+  process.exit(0);
+}
+
+const command = (input.tool_input && input.tool_input.command) || "";
+
+// Only intercept git commit commands
+if (!/\bgit\s+commit\b/.test(command)) {
+  process.exit(0);
+}
+
+// Skip if --no-verify is explicitly requested (user override)
+// Anchored to avoid matching inside commit messages
+if (/\bgit\s+commit\b.*\s--no-verify\b/.test(command)) {
+  process.exit(0);
+}
+
+// Auto-detect lint and format commands from package.json
+let checks = [];
+
+try {
+  const pkgPath = path.join(process.cwd(), "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  const scripts = pkg.scripts || {};
+
+  if (scripts["lint"]) {
+    checks.push({ name: "lint", args: ["run", "lint"] });
+  }
+
+  // Prefer format:check over format (check is non-destructive)
+  if (scripts["format:check"]) {
+    checks.push({ name: "format", args: ["run", "format:check"] });
+  }
+} catch {
+  // No package.json or invalid — check for other tooling
+}
+
+// Check for pyproject.toml based tooling (ruff)
+if (checks.length === 0) {
+  try {
+    const pyproject = path.join(process.cwd(), "pyproject.toml");
+    if (fs.existsSync(pyproject)) {
+      const content = fs.readFileSync(pyproject, "utf-8");
+      if (content.includes("ruff")) {
+        checks.push({ name: "lint", args: ["check", "."], bin: "ruff" });
+        checks.push({ name: "format", args: ["format", "--check", "."], bin: "ruff" });
+      }
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+// No tooling detected — allow commit
+if (checks.length === 0) {
+  process.exit(0);
+}
+
+const failures = [];
+
+// On Windows, npm is a .cmd file — execFileSync needs shell: true to find it
+const isWindows = process.platform === "win32";
+
+for (const check of checks) {
+  const bin = check.bin || "npm";
+  try {
+    execFileSync(bin, check.args, {
+      encoding: "utf-8",
+      timeout: 30000,
+      stdio: "pipe",
+      shell: isWindows,
+    });
+  } catch (err) {
+    failures.push({
+      name: check.name,
+      cmd: `${bin} ${check.args.join(" ")}`,
+      output: ((err.stderr || "") + (err.stdout || "")).trim(),
+    });
+  }
+}
+
+if (failures.length === 0) {
+  process.exit(0);
+}
+
+console.error("[dev-team pre-commit-lint] BLOCKED — checks failed before commit:\n");
+for (const f of failures) {
+  console.error(`  ${f.name} (${f.cmd}):`);
+  const lines = f.output.split("\n").slice(0, 5);
+  for (const line of lines) {
+    console.error(`    ${line}`);
+  }
+  if (f.output.split("\n").length > 5) {
+    console.error(`    ... (run \`${f.cmd}\` for full output)`);
+  }
+  console.error("");
+}
+console.error("Fix the issues above, then retry the commit.");
+process.exit(2);

package/templates/hooks/dev-team-tdd-enforce.js

@@ -26,7 +26,8 @@ try {
   );
   process.exit(2);
 }
-const filePath = (input.tool_input && (input.tool_input.file_path || input.tool_input.path)) || "";
+let filePath = (input.tool_input && (input.tool_input.file_path || input.tool_input.path)) || "";
+filePath = filePath.split("\\").join("/");
 
 if (!filePath) {
   process.exit(0);
@@ -93,6 +94,7 @@ try {
 const hasTestChanges = changedFiles
   .split("\n")
   .filter(Boolean)
+  .map((f) => f.split("\\").join("/"))
   .some((f) => TEST_PATTERNS.some((p) => p.test(f)));
 
 if (hasTestChanges) {

package/templates/hooks/dev-team-watch-list.js

@@ -32,7 +32,8 @@ try {
   process.exit(0);
 }
 
-const filePath = (input.tool_input && (input.tool_input.file_path || input.tool_input.path)) || "";
+let filePath = (input.tool_input && (input.tool_input.file_path || input.tool_input.path)) || "";
+filePath = filePath.split("\\").join("/");
 
 if (!filePath) {
   process.exit(0);

package/templates/settings.json

@@ -26,6 +26,10 @@
           {
             "type": "command",
             "command": "node .claude/hooks/dev-team-safety-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node .claude/hooks/dev-team-pre-commit-lint.js"
           }
         ]
       }

package/templates/skills/dev-team-review/SKILL.md

@@ -20,9 +20,9 @@ Run a multi-agent parallel review of: $ARGUMENTS
 | `/api/`, `/routes/`, `schema`, `.graphql`, `.proto`, `openapi` | @dev-team-mori | API/UI contract |
 | `docker`, `.env`, `config`, `migration`, `database`, `.sql`, `deploy` | @dev-team-voss | Infrastructure |
 | `.github/workflows`, `.claude/`, `tsconfig`, `eslint`, `prettier`, `package.json` | @dev-team-deming | Tooling |
-| `readme`, `changelog`, `.md`, `/docs/` | @dev-team-docs | Documentation |
-| `/adr/`, `architecture`, `/core/`, `/domain/` | @dev-team-architect | Architecture |
-| `package.json`, `version`, `changelog`, release workflows | @dev-team-release | Release artifacts |
+| `readme`, `changelog`, `.md`, `/docs/` | @dev-team-tufte | Documentation |
+| `/adr/`, `architecture`, `/core/`, `/domain/` | @dev-team-brooks | Architecture |
+| `package.json`, `version`, `changelog`, release workflows | @dev-team-conway | Release artifacts |
 | Any `.js`, `.ts`, `.py`, `.go`, `.java`, `.rs` (non-test) | @dev-team-knuth | Quality/coverage |
 
 3. Always include @dev-team-szabo and @dev-team-knuth — they review all code changes.

package/templates/skills/dev-team-task/SKILL.md

@@ -26,6 +26,18 @@ Start a task loop for: $ARGUMENTS
    - Frontend/UI work → @dev-team-mori
    - Test writing → @dev-team-beck
    - Tooling/config → @dev-team-deming
+   - Documentation → @dev-team-tufte
+   - Release/versioning → @dev-team-conway
+
+4. **Architect pre-assessment** (skip for bug fixes, typo fixes, config tweaks):
+   Spawn @dev-team-brooks to assess:
+   - Does this task introduce a new pattern, tool, or convention?
+   - Does it change module boundaries, dependency direction, or layer responsibilities?
+   - Does it contradict or extend an existing ADR?
+
+   Architect returns: `ADR needed: yes/no`. If yes: `topic: <X>, proposed title: ADR-NNN: <title>`.
+
+   If an ADR is needed, include "Write ADR-NNN: <title>" in the implementation task. The implementing agent writes the ADR file. Architect reviews it post-implementation alongside code review.
 
 ## Execution loop
 
@@ -42,6 +54,7 @@ The Stop hook (`dev-team-task-loop.js`) manages iteration counting and re-inject
 
 When the loop exits:
 1. Delete `.claude/dev-team-task.json`.
-2. Summarize what was accomplished across all iterations.
-3. Report any remaining `[RISK]` or `[SUGGESTION]` items for the human to review.
-4. Write key learnings to agent MEMORY.md files.
+2. Spawn **@dev-team-borges** (Librarian) to review memory freshness, cross-agent coherence, and system improvement opportunities. This is mandatory.
+3. Summarize what was accomplished across all iterations.
+4. Report any remaining `[RISK]` or `[SUGGESTION]` items, including Borges's recommendations.
+5. Write key learnings to agent MEMORY.md files.