@fredericboyer/dev-team 0.5.0 → 0.7.0

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

@@ -74,20 +74,14 @@ if (API_PATTERNS.some((p) => p.test(fullPath))) {
   flags.push("@dev-team-mori (API contract may affect UI)");
 }
 
-// Config/infra patterns → flag for Voss
-const INFRA_PATTERNS = [
-  /docker/,
-  /\.env/,
-  /config/,
-  /migration/,
-  /database/,
-  /\.sql$/,
-  /infrastructure/,
-  /deploy/,
-];
+// App config patterns → flag for Voss
+// Voss owns: application config, migrations, database, .env (app-specific)
+// Intentional overlap: Docker files trigger Hamilton below; .env files trigger
+// Voss here for app-config review. Both perspectives are valuable.
+const APP_CONFIG_PATTERNS = [/\.env/, /config/, /migration/, /database/, /\.sql$/];
 
-if (INFRA_PATTERNS.some((p) => p.test(fullPath))) {
-  flags.push("@dev-team-voss (architectural/config change)");
+if (APP_CONFIG_PATTERNS.some((p) => p.test(fullPath))) {
+  flags.push("@dev-team-voss (app config/data change)");
 }
 
 // Tooling patterns → flag for Deming
@@ -123,7 +117,29 @@ if (DOC_PATTERNS.some((p) => p.test(fullPath))) {
   flags.push("@dev-team-tufte (documentation changed)");
 }
 
-// Architecture patterns → flag for Architect
+// Doc-drift patterns → flag Tufte for implementation changes that may need doc updates
+const DOC_DRIFT_PATTERNS = [
+  /(?:^|\/)src\/.*\.(ts|js)$/, // New or changed source files
+  /(?:^|\/)templates\/agents\//, // New or changed agent definitions
+  /(?:^|\/)templates\/skills\//, // New or changed skill definitions
+  /(?:^|\/)templates\/hooks\//, // New or changed hook definitions
+  /(?:^|\/)src\/init\.(ts|js)$/, // Installer changes
+  /(?:^|\/)src\/cli\.(ts|js)$/, // CLI entry point changes
+  /(?:^|\/)bin\//, // CLI shim changes
+  /(?:^|\/)package\.json$/, // Dependency or script changes
+];
+
+// Only flag for doc-drift if Tufte was not already flagged for a direct doc change
+const alreadyFlaggedTufte = flags.some((f) => f.startsWith("@dev-team-tufte"));
+if (!alreadyFlaggedTufte && DOC_DRIFT_PATTERNS.some((p) => p.test(fullPath))) {
+  flags.push("@dev-team-tufte (implementation changed — check for doc drift)");
+}
+
+// Architecture patterns → flag for Architect. For architectural boundary files,
+// Brooks is flagged here with the "architectural boundary touched" reason. The
+// dedupe check below skips the generic "quality attribute review" reason for
+// these files — this is intentional because Brooks's expanded agent definition
+// already includes quality attribute assessment in every review.
 const ARCH_PATTERNS = [
   /\/adr\//,
   /architecture/,
@@ -163,12 +179,49 @@ if (RELEASE_PATTERNS.some((p) => p.test(fullPath))) {
   flags.push("@dev-team-conway (version/release artifact changed)");
 }
 
-// Always flag Knuth for non-test implementation files
+// Operations/infra patterns → flag for Hamilton
+// NOTE: Docker and .env patterns intentionally overlap with INFRA_PATTERNS (Voss).
+// Voss reviews Docker files for infrastructure correctness (base images, build stages, networking),
+// while Hamilton reviews them for operational concerns (resource limits, health checks, image optimization).
+// This dual-review is by design — both perspectives add value.
+const OPS_PATTERNS = [
+  /dockerfile/,
+  /docker-compose/,
+  /\.dockerignore$/,
+  /\.github\/workflows\//,
+  /\.gitlab-ci/,
+  /jenkinsfile/i,
+  /terraform\//,
+  /pulumi\//,
+  /cloudformation\//,
+  /helm\//,
+  /k8s\//,
+  /\.tf$/,
+  /\.tfvars$/,
+  /health[-_]?check/,
+  /(?:^|\/)(?:monitoring|prometheus|grafana|datadog)\.(?:ya?ml|json|conf|config|toml)$/, // monitoring config files (not src/monitoring.ts)
+  /(?:^|\/)(?:logging|logs)\.(?:ya?ml|json|conf|config|toml)$/, // logging config files (not src/logging.ts)
+  /(?:^|\/)(?:alerting|alerts?)\.(?:ya?ml|json|conf|config|toml)$/, // alerting config files
+  /(?:^|\/)(?:observability|otel|opentelemetry)\.(?:ya?ml|json|conf|config|toml)$/, // observability config files
+  /(?<!\/src)\/(?:monitoring|logging|alerting|observability)\//, // ops directories (but not under src/)
+  /\.env\.example$/,
+  /\.env\.template$/,
+  /env\.template$/,
+];
+
+if (OPS_PATTERNS.some((p) => p.test(fullPath) || p.test(basename))) {
+  flags.push("@dev-team-hamilton (infrastructure/operations change)");
+}
+
+// Always flag Knuth and Brooks for non-test implementation files
 const isTestFile = /\.(test|spec)\.|__tests__|\/tests?\//.test(fullPath);
 const isCodeFile = /\.(js|ts|jsx|tsx|py|rb|go|java|rs|c|cpp|cs)$/.test(fullPath);
 
 if (isCodeFile && !isTestFile) {
   flags.push("@dev-team-knuth (new or changed code path to audit)");
+  if (!flags.some((f) => f.startsWith("@dev-team-brooks"))) {
+    flags.push("@dev-team-brooks (quality attribute review)");
+  }
 }
 
 // Flag Beck for test file changes (test quality review)
@@ -180,37 +233,13 @@ 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/.`,
+  `Use the Agent tool to spawn each as a general-purpose subagent with their agent definition from .dev-team/agents/.`,
 );
 
 process.exit(0);

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

@@ -2,14 +2,12 @@
 
 /**
  * dev-team-pre-commit-gate.js
- * TaskCompleted hook.
+ * Pre-commit hook — memory freshness gate.
  *
- * 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.
+ * Runs before each commit. Checks whether memory files need updating.
+ * Blocks (exit 1) when implementation files are staged without memory updates.
+ * Override: create an empty `.dev-team/.memory-reviewed` file to acknowledge
+ * that memory was reviewed and nothing needs updating.
  */
 
 "use strict";
@@ -29,19 +27,40 @@ function cachedGitDiff(args, timeoutMs) {
   const cwdHash = createHash("md5").update(process.cwd()).digest("hex").slice(0, 8);
   const argsKey = args.join("-").replace(/[^a-zA-Z0-9-]/g, "");
   const cacheFile = path.join(os.tmpdir(), `dev-team-git-cache-${cwdHash}-${argsKey}.txt`);
+  let skipWrite = false;
   try {
-    const stat = fs.statSync(cacheFile);
-    if (Date.now() - stat.mtimeMs < 5000) {
+    const stat = fs.lstatSync(cacheFile);
+    // Reject symlinks to prevent symlink attacks (attacker could point cache
+    // file at a sensitive path and have us overwrite it on the next write)
+    if (stat.isSymbolicLink()) {
+      try {
+        fs.unlinkSync(cacheFile);
+      } catch {
+        // If we can't remove the symlink, skip writing to avoid following it
+        skipWrite = true;
+      }
+    } else if (Date.now() - stat.mtimeMs < 5000) {
       return fs.readFileSync(cacheFile, "utf-8");
     }
   } catch {
     // No cache or stale — fall through to git call
   }
   const result = execFileSync("git", args, { encoding: "utf-8", timeout: timeoutMs });
-  try {
-    fs.writeFileSync(cacheFile, result);
-  } catch {
-    // Best effort — don't fail the hook over caching
+  if (!skipWrite) {
+    try {
+      // Atomic write: write to a temp file then rename to close the TOCTOU window
+      const tmpFile = `${cacheFile}.${process.pid}.tmp`;
+      fs.writeFileSync(tmpFile, result, { mode: 0o600 });
+      fs.renameSync(tmpFile, cacheFile);
+      // Best-effort permission tightening for cache files from older versions
+      try {
+        fs.chmodSync(cacheFile, 0o600);
+      } catch {
+        /* best effort */
+      }
+    } catch {
+      // Best effort — don't fail the hook over caching
+    }
   }
   return result;
 }
@@ -63,69 +82,63 @@ if (files.length === 0) {
   process.exit(0);
 }
 
-// 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
-}
-
-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 = [];
+// Memory freshness check (blocking unless overridden)
 
 const hasImplFiles = files.some(
   (f) => /\.(js|ts|jsx|tsx|py|rb|go|java|rs)$/.test(f) && !/\.(test|spec)\./.test(f),
 );
 
 const hasMemoryUpdates = files.some(
-  (f) => f.endsWith("dev-team-learnings.md") || /agent-memory\/.*MEMORY\.md$/.test(f),
+  (f) => f.endsWith("learnings.md") || /agent-memory\/.*MEMORY\.md$/.test(f),
 );
 
 if (hasImplFiles && !hasMemoryUpdates) {
+  // Check for .memory-reviewed override marker
+  const markerPath = path.join(process.cwd(), ".dev-team", ".memory-reviewed");
+  let hasOverride = false;
+  try {
+    const stat = fs.lstatSync(markerPath);
+    // Require regular file — reject symlinks, directories, FIFOs, etc.
+    hasOverride = stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    // No marker file
+  }
+
+  if (hasOverride) {
+    // Override acknowledged — clean up the marker file after this commit
+    try {
+      fs.unlinkSync(markerPath);
+    } catch {
+      // Best effort — don't fail the hook over cleanup
+    }
+    process.exit(0);
+  }
+
   let unstagedMemory = false;
   try {
     const unstaged = cachedGitDiff(["diff", "--name-only"], 2000);
     unstagedMemory = unstaged
       .split("\n")
       .map((f) => f.split("\\").join("/"))
-      .some((f) => f.endsWith("dev-team-learnings.md") || /agent-memory\/.*MEMORY\.md$/.test(f));
+      .some((f) => f.endsWith("learnings.md") || /agent-memory\/.*MEMORY\.md$/.test(f));
   } catch {
     // Ignore — best effort
   }
 
   if (unstagedMemory) {
-    reminders.push(
-      "Memory files were updated but not staged — run `git add .claude/dev-team-learnings.md .claude/agent-memory/` if learnings should be included",
+    console.error(
+      "[dev-team pre-commit] BLOCKED: Memory files were updated but not staged. " +
+        "Run `git add .dev-team/learnings.md .dev-team/agent-memory/` to include learnings, " +
+        "or create an empty `.dev-team/.memory-reviewed` file to acknowledge that memory was reviewed.",
     );
   } else {
-    reminders.push(
-      "Update .claude/dev-team-learnings.md or agent memory with any patterns, conventions, or decisions from this work",
+    console.error(
+      "[dev-team pre-commit] BLOCKED: Implementation files staged without memory updates. " +
+        "Update .dev-team/learnings.md or agent memory with any patterns, conventions, or decisions from this work. " +
+        "If no learnings apply, create an empty `.dev-team/.memory-reviewed` file to acknowledge.",
     );
   }
-}
-
-if (reminders.length > 0) {
-  console.log(`[dev-team pre-commit] Before committing, consider: ${reminders.join("; ")}`);
+  process.exit(1);
 }
 
 process.exit(0);

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

@@ -29,19 +29,40 @@ function cachedGitDiff(args, timeoutMs) {
   const cwdHash = createHash("md5").update(process.cwd()).digest("hex").slice(0, 8);
   const argsKey = args.join("-").replace(/[^a-zA-Z0-9-]/g, "");
   const cacheFile = path.join(os.tmpdir(), `dev-team-git-cache-${cwdHash}-${argsKey}.txt`);
+  let skipWrite = false;
   try {
-    const stat = fs.statSync(cacheFile);
-    if (Date.now() - stat.mtimeMs < 5000) {
+    const stat = fs.lstatSync(cacheFile);
+    // Reject symlinks to prevent symlink attacks (attacker could point cache
+    // file at a sensitive path and have us overwrite it on the next write)
+    if (stat.isSymbolicLink()) {
+      try {
+        fs.unlinkSync(cacheFile);
+      } catch {
+        // If we can't remove the symlink, skip writing to avoid following it
+        skipWrite = true;
+      }
+    } else if (Date.now() - stat.mtimeMs < 5000) {
       return fs.readFileSync(cacheFile, "utf-8");
     }
   } catch {
     // No cache or stale — fall through to git call
   }
   const result = execFileSync("git", args, { encoding: "utf-8", timeout: timeoutMs });
-  try {
-    fs.writeFileSync(cacheFile, result);
-  } catch {
-    // Best effort — don't fail the hook over caching
+  if (!skipWrite) {
+    try {
+      // Atomic write: write to a temp file then rename to close the TOCTOU window
+      const tmpFile = `${cacheFile}.${process.pid}.tmp`;
+      fs.writeFileSync(tmpFile, result, { mode: 0o600 });
+      fs.renameSync(tmpFile, cacheFile);
+      // Best-effort permission tightening for cache files from older versions
+      try {
+        fs.chmodSync(cacheFile, 0o600);
+      } catch {
+        /* best effort */
+      }
+    } catch {
+      // Best effort — don't fail the hook over caching
+    }
   }
   return result;
 }

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

@@ -4,11 +4,11 @@
  * dev-team-watch-list.js
  * PostToolUse hook on Edit/Write.
  *
- * Reads configurable file-pattern-to-agent mappings from .claude/dev-team.json
+ * Reads configurable file-pattern-to-agent mappings from .dev-team/config.json
  * and outputs structured spawn recommendations when patterns match.
  * Advisory only — always exits 0.
  *
- * Config format in dev-team.json:
+ * Config format in config.json:
  * {
  *   "watchLists": [
  *     { "pattern": "src/db/", "agents": ["dev-team-codd"], "reason": "database code changed" },
@@ -42,7 +42,7 @@ if (!filePath) {
 // Read watch list config
 let watchLists = [];
 try {
-  const prefsPath = path.join(process.cwd(), ".claude", "dev-team.json");
+  const prefsPath = path.join(process.cwd(), ".dev-team", "config.json");
   const prefs = JSON.parse(fs.readFileSync(prefsPath, "utf-8"));
   watchLists = prefs.watchLists || [];
 } catch {

package/templates/settings.json

@@ -6,15 +6,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/dev-team-post-change-review.js"
+            "command": "node .dev-team/hooks/dev-team-post-change-review.js"
           },
           {
             "type": "command",
-            "command": "node .claude/hooks/dev-team-tdd-enforce.js"
+            "command": "node .dev-team/hooks/dev-team-tdd-enforce.js"
           },
           {
             "type": "command",
-            "command": "node .claude/hooks/dev-team-watch-list.js"
+            "command": "node .dev-team/hooks/dev-team-watch-list.js"
           }
         ]
       }
@@ -25,11 +25,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/dev-team-safety-guard.js"
+            "command": "node .dev-team/hooks/dev-team-safety-guard.js"
           },
           {
             "type": "command",
-            "command": "node .claude/hooks/dev-team-pre-commit-lint.js"
+            "command": "node .dev-team/hooks/dev-team-pre-commit-lint.js"
           }
         ]
       }
@@ -39,17 +39,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/dev-team-pre-commit-gate.js"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/dev-team-task-loop.js"
+            "command": "node .dev-team/hooks/dev-team-pre-commit-gate.js"
           }
         ]
       }

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

@@ -0,0 +1,167 @@
+---
+name: dev-team:assess
+description: Audit the health of your project's dev-team knowledge base — learnings, agent memory, and CLAUDE.md. Finds stale entries, contradictions, enforcement gaps, and promotion opportunities. Use periodically or after major changes.
+---
+
+Assess the health of the dev-team knowledge base for: $ARGUMENTS
+
+## Scope
+
+This skill audits **only update-safe files** — files that survive `dev-team update`:
+
+- `.dev-team/learnings.md` — shared project learnings
+- `.dev-team/agent-memory/*/MEMORY.md` — per-agent calibration memory
+- Project `CLAUDE.md` — project instructions (content outside `<!-- dev-team:begin/end -->` markers)
+
+**NEVER modify** agent definitions (`.dev-team/agents/`), hook scripts (`.dev-team/hooks/`), skill definitions (`.dev-team/skills/`), or settings (`.claude/settings.json`). These are managed by templates and get overwritten on `dev-team update`.
+
+## Setup
+
+1. Read the following files to build a complete picture:
+   - `.dev-team/learnings.md`
+   - All `.dev-team/agent-memory/*/MEMORY.md` files (use Glob to discover them)
+   - The project's `CLAUDE.md` (root of repo)
+   - `.dev-team/config.json` (to know which agents are installed)
+
+2. If `$ARGUMENTS` specifies a focus area (e.g., "learnings", "memory", "claude.md"), scope the audit to that area only. Otherwise, audit all three.
+
+## Phase 1: Learnings audit (`.dev-team/learnings.md`)
+
+Check for:
+
+### Staleness
+- Entries that reference removed files, deprecated patterns, or old tool versions
+- Entries contradicted by current code (e.g., "We use Express" when the codebase uses Fastify)
+- Date-stamped entries older than 6 months without recent revalidation
+
+### Contradictions
+- Entries that contradict each other (e.g., one says "always use snake_case" and another says "we adopted camelCase")
+- Entries that contradict the project's `CLAUDE.md` instructions
+- Entries that contradict agent memory files
+
+### Enforcement gaps
+- Learnings that state a rule but have no corresponding hook, linter rule, or agent check to enforce it
+- Learnings about process that are not reflected in `CLAUDE.md`
+
+### Promotion opportunities
+- Learnings that are mature enough to become formal project instructions in `CLAUDE.md`
+- Learnings that should be elevated to an ADR in `docs/adr/`
+- Learnings that are really agent-specific calibration and should move to the appropriate agent's `MEMORY.md`
+
+## Phase 2: Agent memory audit (`.dev-team/agent-memory/*/MEMORY.md`)
+
+Check each agent's memory file for:
+
+### Empty or boilerplate files
+- Memory files that are empty or contain only the initial template header
+- Agents that have been active (based on learnings references or git history) but have no memory entries
+
+### Staleness
+- Memory entries that reference files, patterns, or decisions that no longer exist
+- Calibration notes about overruled findings when the underlying code has since changed
+- Entries that duplicate what is already in `.dev-team/learnings.md` (should be deduplicated)
+
+### Inconsistencies
+- Agent memory that contradicts `.dev-team/learnings.md`
+- Agent memory that contradicts another agent's memory (e.g., Szabo says "auth uses sessions" but Voss says "auth uses JWT")
+- Agent memory that contradicts `CLAUDE.md`
+
+### Coverage gaps
+- Installed agents (from `config.json`) with no meaningful memory — suggests the agent has not been calibrated
+- Agents referenced in learnings but missing a memory file
+
+## Phase 3: CLAUDE.md audit
+
+Check the project's `CLAUDE.md` for:
+
+### Accuracy
+- Instructions that do not match actual project behavior (verify claims against code)
+- Workflow descriptions that reference tools, commands, or patterns not present in the repo
+- Agent descriptions or hook triggers that are outdated
+
+### Completeness
+- Important patterns from `.dev-team/learnings.md` that should be in `CLAUDE.md` but are not
+- Missing sections that a new developer would need (build commands, test commands, architecture overview)
+- Installed agents or hooks not mentioned in `CLAUDE.md`
+
+### Staleness
+- Content outside the `<!-- dev-team:begin/end -->` markers that references old patterns
+- References to removed dependencies, deprecated APIs, or old file paths
+
+### Learnings promotion
+- Mature learnings that have been stable for multiple sessions and should be promoted to `CLAUDE.md` instructions
+
+## Report
+
+Produce a structured health report:
+
+### Executive summary
+
+One paragraph: overall knowledge base health, number of issues found by severity.
+
+### Findings by area
+
+For each area (learnings, agent memory, CLAUDE.md), list findings using classified severity:
+
+```
+**[DEFECT]** area — description
+Concrete impact: what goes wrong if this is not fixed.
+Suggested fix: specific action to take.
+```
+
+```
+**[RISK]** area — description
+Why this matters and what could go wrong.
+```
+
+```
+**[SUGGESTION]** area — description
+Specific improvement with expected benefit.
+```
+
+### Cross-cutting issues
+
+Issues that span multiple files:
+- Contradictions between learnings and agent memory
+- Information that exists in the wrong file
+- Patterns documented in multiple places with divergent descriptions
+
+### Recommended actions
+
+Numbered list of concrete actions, ordered by priority:
+
+1. **Fix [DEFECT] items** — these represent actively wrong information
+2. **Address [RISK] items** — these will cause problems soon
+3. **Consider [SUGGESTION] items** — these improve overall health
+
+For each action, specify which file to edit and what change to make.
+
+### Health score
+
+Provide a simple health score:
+
+| Area | Status | Issues |
+|------|--------|--------|
+| Learnings | healthy / needs attention / unhealthy | count by severity |
+| Agent Memory | healthy / needs attention / unhealthy | count by severity |
+| CLAUDE.md | healthy / needs attention / unhealthy | count by severity |
+| **Overall** | **status** | **total** |
+
+Thresholds:
+- **Healthy**: 0 defects, 0-2 risks
+- **Needs attention**: 0 defects, 3+ risks OR 1 defect
+- **Unhealthy**: 2+ defects
+
+## Completion
+
+After the health report is delivered:
+1. Spawn **@dev-team-borges** (Librarian) to review memory freshness and capture any learnings from the assessment findings. This is mandatory.
+2. Include Borges's recommendations in the final report.
+
+## When to run
+
+- **Periodically** — monthly or after a burst of activity
+- **After major refactors** — code changes may invalidate learnings
+- **Before onboarding** — ensure the knowledge base is accurate for new team members
+- **After resolving many review findings** — learnings and memory may need cleanup
+- **On request** — `/dev-team:assess`

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

@@ -22,7 +22,7 @@ Run a comprehensive audit of: $ARGUMENTS
 1. Spawn all three agents as **parallel background subagents** using the Agent tool with `subagent_type: "general-purpose"`.
 
 2. Each agent's prompt must include:
-   - The agent's full definition (read from `.claude/agents/<agent>.md`)
+   - The agent's full definition (read from `.dev-team/agents/<agent>.md`)
    - The scope (directory/pattern or "full codebase")
    - Instruction to produce classified findings: `[DEFECT]`, `[RISK]`, `[QUESTION]`, `[SUGGESTION]`
    - Instruction to read the actual code and tests for full context
@@ -84,8 +84,13 @@ Same grouping. Include actionable recommendations.
 
 Numbered list of concrete actions, ordered by priority. Each action should reference the specific finding it addresses.
 
+### Security preamble
+
+Before starting the audit, check for open security alerts: run `/dev-team:security-status` if available, or check `gh api repos/{owner}/{repo}/code-scanning/alerts?state=open` and `gh api repos/{owner}/{repo}/dependabot/alerts?state=open`. Include these in the audit scope.
+
 ### Completion
 
 After the audit report is delivered:
-1. Spawn **@dev-team-borges** (Librarian) to review memory freshness and capture learnings from the audit findings. This is mandatory.
-2. Include Borges's recommendations in the final report.
+1. You MUST spawn **@dev-team-borges** (Librarian) as the final step to review memory freshness and capture learnings from the audit findings. Do NOT skip this.
+2. If Borges was not spawned, the audit is INCOMPLETE.
+3. Include Borges's recommendations in the final report.