@agent-profile/cli 0.1.5 → 0.2.0

package/dist/index.js

@@ -20,12 +20,15 @@ function getDefaultTargetIds() {
     "lockfile",
     "tabnine-guidelines",
     "tabnine-mcp-config",
+    "tabnine-subagents",
     "codex-config",
     "codex-workflow-skills",
+    "codex-subagents",
     "claude-settings",
     "claude-mcp",
     "claude-md",
-    "claude-workflow-skills"
+    "claude-workflow-skills",
+    "claude-subagents"
   ];
 }
 function createGeneratedTextFile(path6, target, templateId, text) {
@@ -466,6 +469,33 @@ var ai_profile_schema_default = {
         },
         finalReview: {
           type: "boolean"
+        },
+        codeReview: {
+          type: "boolean"
+        },
+        refactoring: {
+          type: "boolean"
+        },
+        documentation: {
+          type: "boolean"
+        },
+        subagentDrivenDevelopment: {
+          type: "boolean"
+        }
+      }
+    },
+    capabilities: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        delegation: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            subagents: {
+              $ref: "#/definitions/subagents"
+            }
+          }
         }
       }
     },
@@ -573,11 +603,342 @@ var ai_profile_schema_default = {
       items: {
         $ref: "#/definitions/slug"
       }
+    },
+    subagents: {
+      type: "object",
+      additionalProperties: false,
+      required: ["enabled"],
+      properties: {
+        enabled: {
+          type: "boolean"
+        },
+        defaults: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            maxConcurrent: {
+              type: "integer",
+              minimum: 1
+            },
+            maxDepth: {
+              type: "integer",
+              minimum: 1
+            }
+          }
+        },
+        agents: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/subagent"
+          }
+        }
+      },
+      if: {
+        properties: {
+          enabled: {
+            const: true
+          }
+        },
+        required: ["enabled"]
+      },
+      then: {
+        required: ["agents"],
+        properties: {
+          agents: {
+            type: "array",
+            minItems: 1,
+            items: {
+              $ref: "#/definitions/subagent"
+            }
+          }
+        }
+      }
+    },
+    subagent: {
+      oneOf: [
+        { $ref: "#/definitions/subagentTemplateRef" },
+        { $ref: "#/definitions/subagentInline" }
+      ]
+    },
+    subagentTemplateRef: {
+      type: "object",
+      additionalProperties: false,
+      required: ["useTemplate"],
+      properties: {
+        useTemplate: {
+          type: "string",
+          enum: ["implementer", "spec-reviewer", "code-quality-reviewer"]
+        }
+      }
+    },
+    subagentInline: {
+      type: "object",
+      additionalProperties: false,
+      required: ["name", "description", "purpose", "prompt", "toolScope"],
+      properties: {
+        name: {
+          type: "string",
+          minLength: 1,
+          pattern: "^[a-z0-9][a-z0-9-]*$",
+          not: {
+            enum: [
+              "default",
+              "worker",
+              "explorer",
+              "explore",
+              "plan",
+              "general-purpose",
+              "codebase_investigator",
+              "remote-codebase-investigator",
+              "generalist",
+              "browser_agent"
+            ]
+          }
+        },
+        description: {
+          type: "string",
+          minLength: 1,
+          pattern: "^[^\\r\\n]+$"
+        },
+        purpose: {
+          type: "string",
+          minLength: 1,
+          pattern: "^[^\\r\\n]+$"
+        },
+        prompt: {
+          type: "string",
+          minLength: 1
+        },
+        toolScope: {
+          type: "string",
+          enum: ["read-only", "workspace-write"]
+        },
+        modelPreference: {
+          type: "string",
+          enum: ["inherit", "fast", "balanced", "capable"]
+        },
+        maxTurns: {
+          type: "integer",
+          minimum: 1
+        },
+        timeoutMinutes: {
+          type: "integer",
+          minimum: 1
+        },
+        mcpServers: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          maxItems: 0
+        }
+      }
     }
   }
 };
 
 // ../../packages/core/src/profile.ts
+var SUBAGENT_TEMPLATE_NAMES = [
+  "implementer",
+  "spec-reviewer",
+  "code-quality-reviewer"
+];
+function isSubagentTemplateRef(entry) {
+  return typeof entry.useTemplate === "string";
+}
+function freezeTemplate(template) {
+  if (template.mcpServers !== void 0) {
+    Object.freeze(template.mcpServers);
+  }
+  return Object.freeze(template);
+}
+function cloneTemplate(template) {
+  const clone = {
+    name: template.name,
+    description: template.description,
+    purpose: template.purpose,
+    prompt: template.prompt,
+    toolScope: template.toolScope
+  };
+  if (template.modelPreference !== void 0)
+    clone.modelPreference = template.modelPreference;
+  if (template.maxTurns !== void 0) clone.maxTurns = template.maxTurns;
+  if (template.timeoutMinutes !== void 0)
+    clone.timeoutMinutes = template.timeoutMinutes;
+  if (template.mcpServers !== void 0)
+    clone.mcpServers = [...template.mcpServers];
+  return clone;
+}
+var SUBAGENT_TEMPLATES_RAW = {
+  implementer: {
+    name: "implementer",
+    description: "Use for a bounded implementation task after the parent agent has provided the full task text, relevant spec excerpts, file ownership, constraints, and expected tests. Returns an explicit status and does not commit or push unless the parent request includes that requirement.",
+    purpose: "Implement one scoped task with tests, self-review, and honest escalation when requirements or architecture are unclear.",
+    prompt: `You are implementing one bounded task.
+
+Work only from the task text, spec excerpts, file ownership, constraints,
+and allowed commands provided in the prompt. Do not assume hidden chat
+history. If essential context is missing, report NEEDS_CONTEXT instead of
+guessing.
+
+Before editing, restate the goal, non-goals, acceptance criteria, and files
+you expect to touch. If the task is ambiguous, architectural, or broader than
+the prompt says, stop and report BLOCKED or NEEDS_CONTEXT.
+
+Implement exactly what the task specifies. Follow the repository's SDD/TDD
+workflow. Add or update focused tests where practical, verify RED before
+behavior changes when the task changes behavior, implement the smallest
+passing change, then verify GREEN. Preserve existing patterns and avoid
+unrelated refactors.
+
+Do not commit, push, create branches, install dependencies, access secrets,
+contact production systems, or upload source unless the parent prompt
+explicitly authorizes that action.
+
+Before reporting back, self-review for completeness, quality, scope control,
+and test validity. Fix issues you find if they are inside the assigned scope.
+
+Report exactly:
+- Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+- What changed
+- Tests run and results
+- Files changed
+- Self-review findings
+- Concerns, missing context, or follow-up work`,
+    toolScope: "workspace-write",
+    modelPreference: "balanced",
+    maxTurns: 18,
+    timeoutMinutes: 20,
+    mcpServers: []
+  },
+  "spec-reviewer": {
+    name: "spec-reviewer",
+    description: "Use after an implementation worker reports DONE or DONE_WITH_CONCERNS to verify the actual changed files against the task text, approved spec, acceptance criteria, and claimed result. Reads code and docs only; does not edit.",
+    purpose: "Catch missing requirements, extra scope, and misunderstandings before code-quality review.",
+    prompt: `You are reviewing whether an implementation matches its specification.
+
+Work only from the full task text, approved spec excerpts, acceptance
+criteria, changed-file list, and implementer report provided in the prompt.
+Do not assume hidden chat history and do not trust the implementer report
+without checking the actual files.
+
+Read the changed code and documentation. Compare actual behavior against the
+requested behavior line by line. Look for missing requirements, extra
+unrequested work, changed contracts, wrong interpretation, and fixture or
+documentation drift.
+
+Do not edit files, run broad commands, install dependencies, read secrets,
+contact production systems, or upload source. If the prompt lacks enough
+context to review, report NEEDS_CONTEXT.
+
+Report exactly:
+- Status: COMPLIANT | ISSUES_FOUND | NEEDS_CONTEXT
+- Requirements checked
+- Findings with severity, path, and line or symbol when available
+- Extra or out-of-scope work, if any
+- Missing tests or docs tied to acceptance criteria
+- Recommendation: proceed to code-quality review, fix first, or request context`,
+    toolScope: "read-only",
+    modelPreference: "capable",
+    maxTurns: 10,
+    timeoutMinutes: 8,
+    mcpServers: []
+  },
+  "code-quality-reviewer": {
+    name: "code-quality-reviewer",
+    description: "Use only after spec review passes to assess maintainability, decomposition, tests, naming, risky mocks, and local code quality in the changed files. Reads code and docs only; does not edit.",
+    purpose: "Catch maintainability and test-quality risks after the implementation is known to match the spec.",
+    prompt: `You are reviewing code quality after spec compliance has passed.
+
+Work only from the full task text, approved spec excerpts, changed-file list,
+spec-review result, test results, and implementer report provided in the
+prompt. Do not assume hidden chat history.
+
+Review only the change's contribution. Do not flag pre-existing file size or
+architecture unless the change makes it materially worse. Check whether each
+touched file has a clear responsibility, whether names describe intent,
+whether complex predicates should be named, whether tests verify behavior
+rather than mocks, whether mocks preserve required real side effects, and
+whether new APIs exist only for tests.
+
+Do not edit files, run broad commands, install dependencies, read secrets,
+contact production systems, or upload source. If the prompt lacks enough
+context to review, report NEEDS_CONTEXT.
+
+Report exactly:
+- Status: ACCEPTABLE | ISSUES_FOUND | NEEDS_CONTEXT
+- Strengths
+- Issues grouped as Critical, Important, or Minor
+- Test-quality concerns
+- Maintainability concerns
+- Assessment: ready, fix first, or request context`,
+    toolScope: "read-only",
+    modelPreference: "capable",
+    maxTurns: 10,
+    timeoutMinutes: 8,
+    mcpServers: []
+  }
+};
+var SUBAGENT_TEMPLATES = {
+  implementer: freezeTemplate(SUBAGENT_TEMPLATES_RAW.implementer),
+  "spec-reviewer": freezeTemplate(SUBAGENT_TEMPLATES_RAW["spec-reviewer"]),
+  "code-quality-reviewer": freezeTemplate(
+    SUBAGENT_TEMPLATES_RAW["code-quality-reviewer"]
+  )
+};
+function expandSubagentEntry(entry) {
+  if (isSubagentTemplateRef(entry)) {
+    return cloneTemplate(SUBAGENT_TEMPLATES[entry.useTemplate]);
+  }
+  return entry;
+}
+function getSubagentTemplateRefs(profile) {
+  const block = profile.capabilities?.delegation?.subagents;
+  if (!block || block.enabled !== true) {
+    return [];
+  }
+  const refs = [];
+  for (const entry of block.agents ?? []) {
+    if (isSubagentTemplateRef(entry)) {
+      refs.push(entry.useTemplate);
+    }
+  }
+  return refs;
+}
+var DEFAULT_SUBAGENT_MAX_CONCURRENT = 3;
+var DEFAULT_SUBAGENT_MAX_DEPTH = 1;
+function normalizeSubagentName(name) {
+  return name.toLowerCase().replace(/_/gu, "-");
+}
+function getSubagentDefaults(profile) {
+  const defaults = profile.capabilities?.delegation?.subagents?.defaults;
+  return {
+    maxConcurrent: defaults?.maxConcurrent ?? DEFAULT_SUBAGENT_MAX_CONCURRENT,
+    maxDepth: defaults?.maxDepth ?? DEFAULT_SUBAGENT_MAX_DEPTH
+  };
+}
+function getEnabledSubagents(profile) {
+  const block = profile.capabilities?.delegation?.subagents;
+  if (!block || block.enabled !== true) {
+    return [];
+  }
+  return (block.agents ?? []).map((entry) => expandSubagentEntry(entry));
+}
+var SUBAGENT_BUILTIN_NAMES_NORMALIZED = /* @__PURE__ */ new Set([
+  "default",
+  "worker",
+  "explorer",
+  "explore",
+  "plan",
+  "general-purpose",
+  "codebase-investigator",
+  "remote-codebase-investigator",
+  "generalist",
+  "browser-agent"
+]);
+function isSubagentBuiltinNameCollision(name) {
+  return SUBAGENT_BUILTIN_NAMES_NORMALIZED.has(normalizeSubagentName(name));
+}
 var compiledValidator;
 var DEFAULT_SAFETY = {
   mode: "guarded",
@@ -653,6 +1014,13 @@ function validateProfileValue(value) {
   const validate = getValidator();
   if (validate(value)) {
     const profile = value;
+    const subagentIssues = validateSubagentSemantics(profile);
+    if (subagentIssues.length > 0) {
+      return {
+        ok: false,
+        issues: subagentIssues.sort((left, right) => compareIssues(left, right))
+      };
+    }
     return {
       ok: true,
       profile,
@@ -665,6 +1033,49 @@ function validateProfileValue(value) {
     issues: toValidationIssues(validate.errors ?? [], value)
   };
 }
+function validateSubagentSemantics(profile) {
+  const subagents = profile.capabilities?.delegation?.subagents;
+  if (!subagents || subagents.enabled !== true) {
+    return [];
+  }
+  const entries = subagents.agents ?? [];
+  const issues = [];
+  const seenRaw = /* @__PURE__ */ new Map();
+  const seenNormalized = /* @__PURE__ */ new Map();
+  entries.forEach((entry, index) => {
+    const expanded = expandSubagentEntry(entry);
+    const name = expanded.name;
+    const rawIndex = seenRaw.get(name);
+    if (rawIndex !== void 0) {
+      issues.push({
+        code: "schema_validation_error",
+        path: `/capabilities/delegation/subagents/agents/${index}/name`,
+        expected: "unique subagent name",
+        actual: "duplicate",
+        message: `/capabilities/delegation/subagents/agents/${index}/name duplicates the name used at index ${rawIndex}.`
+      });
+    } else {
+      seenRaw.set(name, index);
+    }
+    const normalized = normalizeSubagentName(name);
+    const normalizedIndex = seenNormalized.get(normalized);
+    if (normalizedIndex !== void 0 && normalizedIndex !== index) {
+      const isPureDuplicate = rawIndex !== void 0;
+      if (!isPureDuplicate) {
+        issues.push({
+          code: "schema_validation_error",
+          path: `/capabilities/delegation/subagents/agents/${index}/name`,
+          expected: "unique normalized subagent id",
+          actual: "duplicate after hyphen/underscore folding",
+          message: `/capabilities/delegation/subagents/agents/${index}/name collides with the name used at index ${normalizedIndex} after normalization.`
+        });
+      }
+    } else if (normalizedIndex === void 0) {
+      seenNormalized.set(normalized, index);
+    }
+  });
+  return issues;
+}
 function normalizeSafety(profile) {
   return {
     mode: profile.safety?.mode ?? DEFAULT_SAFETY.mode,
@@ -1432,11 +1843,239 @@ function tokenError(code, message) {
   return { ok: false, code, message };
 }
 
+// ../../packages/compiler/src/guidance-content.ts
+var REACT_STACK_TOPIC = {
+  tabnineTitle: "TypeScript and React Stack",
+  agentsMdTitle: "Stack Guidance \u2014 React",
+  intro: "Use the existing TypeScript and React conventions in the repository.",
+  subsections: [
+    {
+      heading: "TypeScript Discipline",
+      bullets: [
+        "Do not use `any` without a documented reason.",
+        "Declare explicit types for exported functions, props, and return values.",
+        "Reuse existing types and utilities before adding new ones."
+      ]
+    },
+    {
+      heading: "Component Conventions",
+      bullets: [
+        "Use function components with typed props.",
+        "Co-locate components with the modules that own them.",
+        "Keep render-only components free of side effects."
+      ]
+    },
+    {
+      heading: "Hook Discipline",
+      bullets: [
+        "Add memoization (`useMemo`, `useCallback`) only when a measured re-render or referential-identity problem exists.",
+        "Keep state local; do not introduce a global store by default.",
+        "Honor the rules of hooks; never call hooks conditionally."
+      ]
+    },
+    {
+      heading: "Styling",
+      bullets: [
+        "Follow the existing styling approach in the repository.",
+        "Do not introduce a new CSS framework or component library."
+      ]
+    },
+    {
+      heading: "API Calls",
+      bullets: [
+        "Reuse existing client utilities for HTTP and data access.",
+        "Type both request payloads and response bodies.",
+        "Handle error and loading states explicitly."
+      ]
+    },
+    {
+      heading: "SDD and TDD Focus",
+      bullets: [
+        "Cover state transitions, API success, error, and loading paths.",
+        "Cover accessibility-affecting behavior (focus, keyboard, ARIA).",
+        "Add or update focused tests before changing observable behavior."
+      ]
+    }
+  ],
+  tabnineChecklistReference: "See `90-final-review.md` for the shared final-review checklist.",
+  agentsMdChecklistReference: "See the `## Completion Checklist` section for shared review steps."
+};
+var CODE_REVIEW_TOPIC = {
+  tabnineTitle: "Code Review",
+  agentsMdTitle: "Code Review",
+  intro: "Use these rules when reviewing a pull request or proposed change.",
+  subsections: [
+    {
+      heading: "Review Focus",
+      bullets: [
+        "Correctness and edge cases.",
+        "Security, including input validation and secret handling.",
+        "Performance hotspots and obvious complexity regressions.",
+        "Unnecessary complexity or premature abstraction.",
+        "Consistency with existing project style.",
+        "Missing or weakened tests.",
+        "Weak typing or unjustified `any`.",
+        "Accessibility-affecting behavior in user-facing changes.",
+        "Error handling and observability gaps.",
+        "Dependency risk and license concerns.",
+        "Spec compliance."
+      ]
+    },
+    {
+      heading: "Severity Labels",
+      bullets: [
+        "Blocker: must fix before merge (correctness, security, contract break).",
+        "High: must fix before merge unless explicitly deferred.",
+        "Medium: should fix before merge or open a tracked follow-up.",
+        "Low: nit or polish; safe to defer."
+      ]
+    },
+    {
+      heading: "Output Format",
+      bullets: [
+        "Summary: one paragraph of intent and overall verdict.",
+        "Spec Compliance: cite the spec and any deviation.",
+        "Findings: grouped by severity, each with file, function, and concrete suggestion.",
+        "Tests: list coverage gaps and whether tests were run.",
+        "Safety Review: secrets, production access, dependency installs, network access.",
+        "Final recommendation: approve, request changes, or block with reason."
+      ]
+    },
+    {
+      heading: "Review Discipline",
+      bullets: [
+        "Skip nitpicks the autoformatter or linter already handles.",
+        "Do not propose broad rewrites; keep suggestions actionable.",
+        "Reference the specific file, function, or component in every finding."
+      ]
+    }
+  ],
+  tabnineChecklistReference: "See `90-final-review.md` for the shared final-review checklist.",
+  agentsMdChecklistReference: "See the `## Completion Checklist` section for shared review steps."
+};
+var REFACTORING_TOPIC = {
+  tabnineTitle: "Refactoring",
+  agentsMdTitle: "Refactoring",
+  intro: "Use these rules when restructuring code without changing observable behavior.",
+  subsections: [
+    {
+      heading: "Principles",
+      bullets: [
+        "Refactor to remove duplication, clarify intent, or unlock a planned change.",
+        "Do not refactor for style preference alone or to chase a new pattern.",
+        "Keep refactoring commits separate from behavior changes."
+      ]
+    },
+    {
+      heading: "Safe Refactoring Workflow",
+      bullets: [
+        "Identify the code smell or constraint that motivates the change.",
+        "Check existing abstractions before introducing a new one.",
+        "Define expected behavior in tests before restructuring.",
+        "Make the smallest extraction that solves the problem.",
+        "Preserve public behavior; run tests and golden fixtures after each step.",
+        "Summarize what was intentionally not changed in the review notes."
+      ]
+    },
+    {
+      heading: "Restrictions",
+      bullets: [
+        "Do not rename public APIs without explicit approval.",
+        "Do not move files across modules without explicit approval.",
+        "Do not change schemas, endpoint contracts, or build tooling without explicit approval.",
+        "Do not refactor and add features in the same change."
+      ]
+    }
+  ],
+  tabnineChecklistReference: "See `90-final-review.md` for the shared final-review checklist.",
+  agentsMdChecklistReference: "See the `## Completion Checklist` section for shared review steps."
+};
+var DOCUMENTATION_TOPIC = {
+  tabnineTitle: "Documentation",
+  agentsMdTitle: "Documentation",
+  intro: "Use these rules when adding or updating project documentation.",
+  subsections: [
+    {
+      heading: "When to Update Documentation",
+      bullets: [
+        "Setup or onboarding steps changed.",
+        "Workflow, command, or build step changed.",
+        "Public API surface changed.",
+        "Configuration or environment variables changed.",
+        "Testing command changed.",
+        "Deployment or release procedure changed.",
+        "Troubleshooting guidance is newly known."
+      ]
+    },
+    {
+      heading: "Style",
+      bullets: [
+        "Write for maintainers, not marketing.",
+        "Provide copy-pasteable commands where applicable.",
+        "Keep examples current; remove examples that no longer run.",
+        "Reference file paths when they help a reader navigate."
+      ]
+    },
+    {
+      heading: "README Rules",
+      bullets: [
+        "Keep the existing structure intact.",
+        "Add only relevant new sections.",
+        "Do not rewrite the README without an explicit request."
+      ]
+    },
+    {
+      heading: "Code Comment Policy",
+      bullets: [
+        "Comment non-obvious business rules and invariants.",
+        "Comment tricky edge cases the code alone does not reveal.",
+        "Comment surprising technical constraints and security-sensitive behavior.",
+        "Do not write comments that restate the code."
+      ]
+    }
+  ],
+  tabnineChecklistReference: "See `90-final-review.md` for the shared final-review checklist.",
+  agentsMdChecklistReference: "See the `## Completion Checklist` section for shared review steps."
+};
+function renderTopicAsTabnineGuideline(topic) {
+  const sections = topic.subsections.map(
+    (subsection) => `## ${subsection.heading}
+
+${subsection.bullets.map((bullet) => `- ${bullet}`).join("\n")}
+`
+  ).join("\n");
+  return `<!-- Generated by Agent Profile Compiler. Do not edit by hand. -->
+
+# ${topic.tabnineTitle}
+
+${topic.intro}
+
+${sections}
+${topic.tabnineChecklistReference}
+`;
+}
+function renderTopicAsAgentsMdSection(topic) {
+  const subsections = topic.subsections.map(
+    (subsection) => `**${subsection.heading}**
+
+${subsection.bullets.map((bullet) => `- ${bullet}`).join("\n")}`
+  ).join("\n\n");
+  return `## ${topic.agentsMdTitle}
+
+${topic.intro}
+
+${subsections}
+
+${topic.agentsMdChecklistReference}
+`;
+}
+
 // ../../packages/compiler/src/compiler.ts
 var WORKFLOW_SKILLS = [
   { id: "sdd-change", workflowFlag: "sdd" },
   { id: "tdd-change", workflowFlag: "tdd" },
-  { id: "final-review", workflowFlag: "finalReview" }
+  { id: "final-review", workflowFlag: "finalReview" },
+  { id: "subagent-driven-change", workflowFlag: "subagentDrivenDevelopment" }
 ];
 var TEMPLATE_SOURCES = [
   {
@@ -1445,6 +2084,22 @@ var TEMPLATE_SOURCES = [
     version: "1",
     source: renderAgentsMdTemplateSource()
   },
+  agentsMdTopicTemplateSource(
+    "targets/agents-md/30-stack-typescript-react@1",
+    REACT_STACK_TOPIC
+  ),
+  agentsMdTopicTemplateSource(
+    "targets/agents-md/60-code-review@1",
+    CODE_REVIEW_TOPIC
+  ),
+  agentsMdTopicTemplateSource(
+    "targets/agents-md/70-refactoring@1",
+    REFACTORING_TOPIC
+  ),
+  agentsMdTopicTemplateSource(
+    "targets/agents-md/80-documentation@1",
+    DOCUMENTATION_TOPIC
+  ),
   {
     id: "targets/lockfile@1",
     target: "lockfile",
@@ -1467,6 +2122,10 @@ var TEMPLATE_SOURCES = [
     "targets/tabnine-guidelines/30-stack-typescript-svelte@1",
     renderTypeScriptSvelteGuideline
   ),
+  guidelineTemplateSource(
+    "targets/tabnine-guidelines/30-stack-typescript-react@1",
+    renderTypeScriptReactGuideline
+  ),
   guidelineTemplateSource(
     "targets/tabnine-guidelines/40-stack-java-spring@1",
     renderJavaSpringGuideline
@@ -1475,6 +2134,18 @@ var TEMPLATE_SOURCES = [
     "targets/tabnine-guidelines/50-testing-playwright-junit@1",
     renderPlaywrightJunitGuideline
   ),
+  guidelineTemplateSource(
+    "targets/tabnine-guidelines/60-code-review@1",
+    renderCodeReviewGuideline
+  ),
+  guidelineTemplateSource(
+    "targets/tabnine-guidelines/70-refactoring@1",
+    renderRefactoringGuideline
+  ),
+  guidelineTemplateSource(
+    "targets/tabnine-guidelines/80-documentation@1",
+    renderDocumentationGuideline
+  ),
   guidelineTemplateSource(
     "targets/tabnine-guidelines/90-final-review@1",
     renderFinalReviewGuideline
@@ -1497,7 +2168,7 @@ var TEMPLATE_SOURCES = [
     "sdd-change"
   ),
   workflowSkillTemplateSource(
-    "targets/codex-workflow-skills/tdd-change@1",
+    "targets/codex-workflow-skills/tdd-change@2",
     "codex-workflow-skills",
     "tdd-change"
   ),
@@ -1506,6 +2177,11 @@ var TEMPLATE_SOURCES = [
     "codex-workflow-skills",
     "final-review"
   ),
+  workflowSkillTemplateSource(
+    "targets/codex-workflow-skills/subagent-driven-change@1",
+    "codex-workflow-skills",
+    "subagent-driven-change"
+  ),
   {
     id: "targets/claude-settings@1",
     target: "claude-settings",
@@ -1530,7 +2206,7 @@ var TEMPLATE_SOURCES = [
     "sdd-change"
   ),
   workflowSkillTemplateSource(
-    "targets/claude-workflow-skills/tdd-change@1",
+    "targets/claude-workflow-skills/tdd-change@2",
     "claude-workflow-skills",
     "tdd-change"
   ),
@@ -1538,6 +2214,11 @@ var TEMPLATE_SOURCES = [
     "targets/claude-workflow-skills/final-review@1",
     "claude-workflow-skills",
     "final-review"
+  ),
+  workflowSkillTemplateSource(
+    "targets/claude-workflow-skills/subagent-driven-change@1",
+    "claude-workflow-skills",
+    "subagent-driven-change"
   )
 ];
 function getDefaultTemplates() {
@@ -1552,7 +2233,7 @@ function compileProfile(request) {
   const targets = uniqueTargets(
     request.targets ?? getEnabledTargetIds(request.profile)
   );
-  const templates = request.templates ?? getDefaultTemplates();
+  const templates = request.templates ?? mergeTemplates(getDefaultTemplates(), getSubagentTemplates(request.profile));
   const issues = validateTargets(request.profile, targets, templates);
   if (issues.length > 0) {
     return {
@@ -1563,15 +2244,81 @@ function compileProfile(request) {
   const files = targets.flatMap(
     (target) => renderTarget(target, request.profile)
   );
+  const requiredTemplateIds = getRequiredTemplateIdSet(targets, request.profile);
   return {
     ok: true,
     files: files.sort(compareGeneratedFiles),
-    templates: templates.filter((template) => targets.includes(template.target)).sort(compareTemplates)
+    templates: templates.filter((template) => requiredTemplateIds.has(template.id)).sort(compareTemplates)
   };
 }
+function mergeTemplates(base, extra) {
+  const seen = new Set(base.map((template) => template.id));
+  const result = [...base];
+  for (const template of extra) {
+    if (!seen.has(template.id)) {
+      seen.add(template.id);
+      result.push(template);
+    }
+  }
+  return result.sort(compareTemplates);
+}
+function getSubagentTemplates(profile) {
+  const agents = getEnabledSubagents(profile);
+  if (agents.length === 0) {
+    return [];
+  }
+  const effective = deriveEffectivePermissions(profile);
+  const templates = [];
+  if (profile.clients.claude.enabled) {
+    for (const agent of agents) {
+      templates.push({
+        id: `targets/claude-subagents/${agent.name}@1`,
+        target: "claude-subagents",
+        version: "1",
+        sha256: sha256Hex(
+          normalizeGeneratedText(renderClaudeSubagent(agent, effective))
+        )
+      });
+    }
+  }
+  if (profile.clients.codex.enabled) {
+    for (const agent of agents) {
+      templates.push({
+        id: `targets/codex-subagents/${agent.name}@1`,
+        target: "codex-subagents",
+        version: "1",
+        sha256: sha256Hex(
+          normalizeGeneratedText(renderCodexSubagent(agent, effective))
+        )
+      });
+    }
+  }
+  if (profile.clients.tabnine.enabled) {
+    for (const agent of agents) {
+      if (agent.toolScope !== "read-only") {
+        continue;
+      }
+      templates.push({
+        id: `targets/tabnine-subagents/${agent.name}@1`,
+        target: "tabnine-subagents",
+        version: "1",
+        sha256: sha256Hex(normalizeGeneratedText(renderTabnineSubagent(agent)))
+      });
+    }
+  }
+  return templates;
+}
 function renderAgentsMd(profile) {
   const effectivePermissions = deriveEffectivePermissions(profile);
   const enabledClients2 = renderEnabledClients(profile);
+  const reactSection = profile.stack.frameworks.includes("react") ? `
+${renderTopicAsAgentsMdSection(REACT_STACK_TOPIC)}` : "";
+  const codeReviewSection = profile.workflow.codeReview === true ? `
+${renderTopicAsAgentsMdSection(CODE_REVIEW_TOPIC)}` : "";
+  const refactoringSection = profile.workflow.refactoring === true ? `
+${renderTopicAsAgentsMdSection(REFACTORING_TOPIC)}` : "";
+  const documentationSection = profile.workflow.documentation === true ? `
+${renderTopicAsAgentsMdSection(DOCUMENTATION_TOPIC)}` : "";
   return normalizeGeneratedText(`# AGENTS.md
 
 ## Project
@@ -1586,7 +2333,7 @@ Description: ${escapeMarkdownText(profile.profile.description)}
 - Frameworks: ${renderList(profile.stack.frameworks)}
 - Package managers: ${renderList(profile.stack.packageManagers)}
 - Testing: ${renderList(profile.stack.testing)}
-
+${reactSection}
 ## Enabled AI Clients
 
 ${enabledClients2}
@@ -1596,7 +2343,7 @@ ${enabledClients2}
 - SDD: ${renderRequired(profile.workflow.sdd)}
 - TDD: ${renderRequired(profile.workflow.tdd)}
 - Final implementation review: ${renderRequired(profile.workflow.finalReview)}
-
+${codeReviewSection}${refactoringSection}${documentationSection}
 ## Permissions
 
 | Permission         | Mode  |
@@ -1688,9 +2435,15 @@ function renderTarget(target, profile) {
           ".codex/config.toml",
           "codex-config",
           "targets/codex-config@1",
-          renderCodexConfigToml()
+          renderCodexConfigToml(profile)
         )
       ];
+    case "codex-subagents":
+      return renderCodexSubagentFiles(profile);
+    case "claude-subagents":
+      return renderClaudeSubagentFiles(profile);
+    case "tabnine-subagents":
+      return renderTabnineSubagentFiles(profile);
     case "codex-workflow-skills":
       return renderWorkflowSkillFiles(
         profile,
@@ -1774,6 +2527,16 @@ function renderTabnineGuidelines(profile) {
       )
     );
   }
+  if (hasStack(profile, "frameworks", "react")) {
+    files.push(
+      createGeneratedTextFile(
+        ".tabnine/guidelines/30-stack-typescript-react.md",
+        common.target,
+        "targets/tabnine-guidelines/30-stack-typescript-react@1",
+        renderTypeScriptReactGuideline()
+      )
+    );
+  }
   if (hasStack(profile, "languages", "java") && hasStack(profile, "frameworks", "spring-boot")) {
     files.push(
       createGeneratedTextFile(
@@ -1794,6 +2557,36 @@ function renderTabnineGuidelines(profile) {
       )
     );
   }
+  if (profile.workflow.codeReview === true) {
+    files.push(
+      createGeneratedTextFile(
+        ".tabnine/guidelines/60-code-review.md",
+        common.target,
+        "targets/tabnine-guidelines/60-code-review@1",
+        renderCodeReviewGuideline()
+      )
+    );
+  }
+  if (profile.workflow.refactoring === true) {
+    files.push(
+      createGeneratedTextFile(
+        ".tabnine/guidelines/70-refactoring.md",
+        common.target,
+        "targets/tabnine-guidelines/70-refactoring@1",
+        renderRefactoringGuideline()
+      )
+    );
+  }
+  if (profile.workflow.documentation === true) {
+    files.push(
+      createGeneratedTextFile(
+        ".tabnine/guidelines/80-documentation.md",
+        common.target,
+        "targets/tabnine-guidelines/80-documentation@1",
+        renderDocumentationGuideline()
+      )
+    );
+  }
   if (profile.workflow.finalReview) {
     files.push(
       createGeneratedTextFile(
@@ -1813,11 +2606,15 @@ function renderWorkflowSkillFiles(profile, target, rootPath) {
     (skill) => createGeneratedTextFile(
       `${rootPath}/${skill.id}/SKILL.md`,
       target,
-      `targets/${target}/${skill.id}@1`,
+      getWorkflowSkillTemplateId(target, skill.id),
       renderWorkflowSkill(skill.id)
     )
   );
 }
+function getWorkflowSkillTemplateId(target, skill) {
+  const version = skill === "tdd-change" ? "2" : "1";
+  return `targets/${target}/${skill}@${version}`;
+}
 function renderWorkflowSkill(skill) {
   switch (skill) {
     case "sdd-change":
@@ -1849,7 +2646,7 @@ description: Use when implementing a meaningful repository change that requires
     case "tdd-change":
       return `---
 name: tdd-change
-description: Use when changing behavior where a focused failing test or golden fixture should lead the implementation.
+description: Use when changing behavior where a focused failing test or golden fixture must prove RED before implementation and GREEN after the minimal fix.
 ---
 
 <!-- Generated by Agent Profile Compiler. Do not edit by hand. -->
@@ -1859,11 +2656,24 @@ description: Use when changing behavior where a focused failing test or golden f
 ## Instructions
 
 1. Identify the smallest observable behavior covered by the approved spec.
-2. Add or update the focused failing test first when practical.
-3. For generated outputs, add or review the golden fixture intentionally.
-4. Implement the smallest change that satisfies the test and spec.
-5. Run the relevant test command and report any test that cannot be run.
-6. Do not update golden files only to hide an unexplained behavior change.
+2. Add or update one focused failing test or golden fixture before changing behavior code.
+3. Run the narrowest relevant test command and confirm RED: the test fails for the expected reason, not because of a typo, setup error, or unrelated failure.
+4. Implement the smallest change that satisfies the failing test and the spec.
+5. Run the same focused test command and confirm GREEN: the test passes without new warnings or unrelated failures.
+6. Refactor only after GREEN, then rerun the focused test command.
+7. Do not update golden files only to hide an unexplained behavior change.
+
+## Testing Anti-Patterns
+
+- Do not assert on mock elements or mock call counts when a real behavior assertion is possible.
+- Do not add production methods, flags, or exports that exist only for tests.
+- Do not mock a dependency until you understand the side effects the test needs.
+- Keep test doubles structurally complete enough to match the real data shape consumed by the code.
+- If mock setup is larger than the behavior under test, consider a narrower integration test or a simpler production boundary.
+
+## Output
+
+Report the RED command and expected failure, the GREEN command and passing result, any refactor rerun, and any TDD exception that required human approval.
 
 ## Safety
 
@@ -1893,6 +2703,56 @@ description: Use before handing off an implementation to compare the diff agains
 ## Output
 
 Return a concise final review with spec compliance, tests run, contract impact, security impact, and remaining risks.
+`;
+    case "subagent-driven-change":
+      return `---
+name: subagent-driven-change
+description: Use when a scoped implementation can be delegated to an implementation subagent and then independently reviewed for spec compliance before code quality.
+---
+
+<!-- Generated by Agent Profile Compiler. Do not edit by hand. -->
+
+# Subagent-Driven Change
+
+## Preconditions
+
+Use this workflow only when the task has a clear spec, acceptance criteria, and file ownership. Keep tightly coupled or architectural decisions in the parent session unless the user explicitly asks for delegation.
+
+Required subagents: \`implementer\`, \`spec-reviewer\`, and \`code-quality-reviewer\`.
+
+## Fresh Context
+
+Each subagent prompt must include the full task text, relevant spec excerpts, non-goals, acceptance criteria, file ownership, constraints, expected tests, and any command limits. Do not rely on hidden chat history or a previous subagent's memory.
+
+## Flow
+
+1. Dispatch \`implementer\` with one bounded task and the complete context it needs.
+2. If \`implementer\` returns \`BLOCKED\` or \`NEEDS_CONTEXT\`, resolve that before continuing.
+3. If \`implementer\` returns \`DONE_WITH_CONCERNS\`, read the concerns before review and decide whether to fix, narrow scope, or continue.
+4. Dispatch \`spec-reviewer\` with the original task, relevant spec excerpts, changed files, and implementer report.
+5. Fix or escalate every spec-review issue before requesting code-quality review.
+6. Dispatch \`code-quality-reviewer\` only after spec review reports compliance.
+7. Fix Critical and Important code-quality issues before handoff, or document why a finding is intentionally deferred.
+8. Run the relevant tests, golden tests, and doctor/check commands required by the spec before final response.
+
+## Status Values
+
+Implementation worker status values: \`DONE\`, \`DONE_WITH_CONCERNS\`, \`BLOCKED\`, \`NEEDS_CONTEXT\`.
+
+Spec reviewer status values: \`COMPLIANT\`, \`ISSUES_FOUND\`, \`NEEDS_CONTEXT\`.
+
+Code-quality reviewer status values: \`ACCEPTABLE\`, \`ISSUES_FOUND\`, \`NEEDS_CONTEXT\`.
+
+## Safety
+
+- Do not ask subagents to commit, push, create branches, install dependencies, read secrets, contact production systems, or upload source unless the user explicitly requested that action.
+- Do not accept an implementation report without reading reviewer findings.
+- Do not run code-quality review before spec-compliance review passes.
+- Keep generated files deterministic and lockfile-tracked.
+
+## Output
+
+Final handoff must list what changed, tests run, contract impact, security impact, remaining risks or TODOs, and whether the spec acceptance criteria are fully met.
 `;
   }
 }
@@ -1958,6 +2818,18 @@ Test-driven development is required for this project.
 - Do not update golden fixtures to hide an unexplained behavior change.
 `;
 }
+function renderTypeScriptReactGuideline() {
+  return renderTopicAsTabnineGuideline(REACT_STACK_TOPIC);
+}
+function renderCodeReviewGuideline() {
+  return renderTopicAsTabnineGuideline(CODE_REVIEW_TOPIC);
+}
+function renderRefactoringGuideline() {
+  return renderTopicAsTabnineGuideline(REFACTORING_TOPIC);
+}
+function renderDocumentationGuideline() {
+  return renderTopicAsTabnineGuideline(DOCUMENTATION_TOPIC);
+}
 function renderTypeScriptSvelteGuideline() {
   return `<!-- Generated by Agent Profile Compiler. Do not edit by hand. -->
 
@@ -2016,14 +2888,165 @@ Final implementation review is required for this project.
 - List remaining risks or TODOs before considering the task complete.
 `;
 }
-function renderCodexConfigToml() {
-  return `approval_policy = "on-request"
+function renderCodexConfigToml(profile) {
+  const base = `approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 allow_login_shell = false
 
 [sandbox_workspace_write]
 network_access = false
 `;
+  if (!profile || getEnabledSubagents(profile).length === 0) {
+    return base;
+  }
+  const defaults = getSubagentDefaults(profile);
+  return `${base}
+[agents]
+max_threads = ${defaults.maxConcurrent}
+max_depth = ${defaults.maxDepth}
+`;
+}
+function renderClaudeSubagentFiles(profile) {
+  const agents = getEnabledSubagents(profile);
+  const effective = deriveEffectivePermissions(profile);
+  return agents.map(
+    (agent) => createGeneratedTextFile(
+      `.claude/agents/${agent.name}.md`,
+      "claude-subagents",
+      `targets/claude-subagents/${agent.name}@1`,
+      renderClaudeSubagent(agent, effective)
+    )
+  );
+}
+function renderCodexSubagentFiles(profile) {
+  const agents = getEnabledSubagents(profile);
+  const effective = deriveEffectivePermissions(profile);
+  return agents.map(
+    (agent) => createGeneratedTextFile(
+      `.codex/agents/${agent.name}.toml`,
+      "codex-subagents",
+      `targets/codex-subagents/${agent.name}@1`,
+      renderCodexSubagent(agent, effective)
+    )
+  );
+}
+function renderTabnineSubagentFiles(profile) {
+  const agents = getEnabledSubagents(profile).filter(
+    (agent) => agent.toolScope === "read-only"
+  );
+  return agents.map(
+    (agent) => createGeneratedTextFile(
+      `.tabnine/agent/agents/${agent.name}.md`,
+      "tabnine-subagents",
+      `targets/tabnine-subagents/${agent.name}@1`,
+      renderTabnineSubagent(agent)
+    )
+  );
+}
+function titleCaseFromKebab(name) {
+  return name.split("-").filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function renderClaudeSubagent(agent, effective) {
+  const lines = ["---", `name: ${yamlScalarSafe(agent.name)}`];
+  lines.push(`description: ${yamlScalarSafe(agent.description)}`);
+  if (agent.toolScope === "read-only") {
+    lines.push("tools: Read, Glob, Grep");
+  } else {
+    const tools = ["Read", "Glob", "Grep"];
+    if (effective.filesystem.write === "allow") {
+      tools.push("Edit", "Write");
+    }
+    if (effective.shell.run === "allow") {
+      tools.push("Bash");
+    }
+    if (effective.network.external === "allow") {
+      tools.push("WebFetch");
+    }
+    lines.push(`tools: ${tools.join(", ")}`);
+  }
+  const model = agent.modelPreference ?? "inherit";
+  lines.push(`model: ${model === "inherit" ? "inherit" : "inherit"}`);
+  if (agent.toolScope === "read-only") {
+    lines.push("permissionMode: plan");
+  }
+  if (agent.maxTurns !== void 0) {
+    lines.push(`maxTurns: ${agent.maxTurns}`);
+  }
+  lines.push("---", "");
+  lines.push("<!-- Generated by Agent Profile Compiler. Do not edit by hand. -->");
+  lines.push("");
+  lines.push(`# ${titleCaseFromKebab(agent.name)}`);
+  lines.push("");
+  lines.push(agent.prompt.trim());
+  lines.push("");
+  return lines.join("\n");
+}
+function renderCodexSubagent(agent, effective) {
+  const lines = [
+    "# Generated by Agent Profile Compiler. Do not edit by hand.",
+    "",
+    `name = "${escapeTomlString(agent.name)}"`,
+    `description = "${escapeTomlString(agent.description)}"`
+  ];
+  if (agent.toolScope === "workspace-write" && effective.filesystem.write !== "deny") {
+    lines.push(`sandbox_mode = "workspace-write"`);
+  } else {
+    lines.push(`sandbox_mode = "read-only"`);
+  }
+  if (agent.prompt.includes(`"""`)) {
+    throw new Error(
+      `Codex subagent ${agent.name} prompt contains a TOML triple-quote sequence; compile validation should have rejected this.`
+    );
+  }
+  lines.push('developer_instructions = """');
+  for (const promptLine of agent.prompt.trim().split(/\r?\n/u)) {
+    lines.push(promptLine);
+  }
+  lines.push('"""');
+  lines.push("");
+  return lines.join("\n");
+}
+function renderTabnineSubagent(agent) {
+  const lines = ["---", `name: ${yamlScalarSafe(agent.name)}`];
+  lines.push(`description: ${yamlScalarSafe(agent.description)}`);
+  lines.push("kind: local");
+  lines.push("tools:");
+  for (const tool of ["grep_search", "read_file"].sort()) {
+    lines.push(`  - ${tool}`);
+  }
+  if (agent.maxTurns !== void 0) {
+    lines.push(`max_turns: ${agent.maxTurns}`);
+  }
+  if (agent.timeoutMinutes !== void 0) {
+    lines.push(`timeout_mins: ${agent.timeoutMinutes}`);
+  }
+  lines.push("---", "");
+  lines.push("<!-- Generated by Agent Profile Compiler. Do not edit by hand. -->");
+  lines.push("");
+  lines.push(`# ${titleCaseFromKebab(agent.name)}`);
+  lines.push("");
+  lines.push(agent.prompt.trim());
+  lines.push("");
+  return lines.join("\n");
+}
+function escapeTomlString(value) {
+  return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
+}
+function yamlScalarSafe(value) {
+  if (yamlScalarNeedsQuoting(value)) {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+function yamlScalarNeedsQuoting(value) {
+  if (value.length === 0) return true;
+  if (/[\r\n\t]/u.test(value)) return true;
+  if (/^\s|\s$/u.test(value)) return true;
+  if (/^[\-?:,\[\]{}#&*!|>'"%@`]/u.test(value)) return true;
+  if (value.includes(": ") || value.includes(" #")) return true;
+  if (/^(?:true|false|null|yes|no|on|off|~)$/iu.test(value)) return true;
+  if (/^[+\-]?\d+(?:\.\d+)?(?:[eE][+\-]?\d+)?$/u.test(value)) return true;
+  return false;
 }
 function renderAgentsMdTemplateSource() {
   return `# AGENTS.md
@@ -2062,6 +3085,14 @@ function guidelineTemplateSource(id, render) {
     source: render()
   };
 }
+function agentsMdTopicTemplateSource(id, topic) {
+  return {
+    id,
+    target: "agents-md",
+    version: "1",
+    source: renderTopicAsAgentsMdSection(topic)
+  };
+}
 function workflowSkillTemplateSource(id, target, skill) {
   return {
     id,
@@ -2100,11 +3131,18 @@ function renderClaudeSettingsJson() {
 }
 function getEnabledTargetIds(profile) {
   const targets = ["agents-md"];
+  const subagentsEnabled = getEnabledSubagents(profile).length > 0;
   if (profile.clients.tabnine.enabled) {
     targets.push("tabnine-guidelines", "tabnine-mcp-config");
+    if (subagentsEnabled) {
+      targets.push("tabnine-subagents");
+    }
   }
   if (profile.clients.codex.enabled) {
     targets.push("codex-config", "codex-workflow-skills");
+    if (subagentsEnabled) {
+      targets.push("codex-subagents");
+    }
   }
   if (profile.clients.claude.enabled) {
     targets.push(
@@ -2113,6 +3151,9 @@ function getEnabledTargetIds(profile) {
       "claude-md",
       "claude-workflow-skills"
     );
+    if (subagentsEnabled) {
+      targets.push("claude-subagents");
+    }
   }
   return targets;
 }
@@ -2121,6 +3162,70 @@ function validateTargets(profile, targets, templates) {
   const templateIds = new Set(templates.map((template) => template.id));
   const enabledTargets = new Set(getEnabledTargetIds(profile));
   const issues = [];
+  if (profile.workflow.subagentDrivenDevelopment === true) {
+    const refs = new Set(getSubagentTemplateRefs(profile));
+    const missing = SUBAGENT_TEMPLATE_NAMES.filter((name) => !refs.has(name));
+    if (missing.length > 0) {
+      issues.push({
+        code: "missing_required_template_reference",
+        path: "/workflow/subagentDrivenDevelopment",
+        expected: `useTemplate references for ${SUBAGENT_TEMPLATE_NAMES.join(", ")}`,
+        actual: `missing ${missing.join(", ")}`,
+        message: `workflow.subagentDrivenDevelopment requires capabilities.delegation.subagents.agents[].useTemplate references for ${missing.join(", ")}.`
+      });
+    }
+  }
+  if (targets.includes("tabnine-subagents")) {
+    const writeAgents = getEnabledSubagents(profile).filter(
+      (agent) => agent.toolScope === "workspace-write"
+    );
+    for (const agent of writeAgents) {
+      issues.push({
+        code: "unsafe_generated_content",
+        path: `.tabnine/agent/agents/${agent.name}.md`,
+        expected: "read-only Tabnine subagent",
+        actual: "workspace-write Tabnine subagent",
+        message: `tabnine-subagents cannot emit workspace-write agent ${agent.name} while Tabnine subagents are experimental/no-confirmation.`
+      });
+    }
+  }
+  if (targets.includes("codex-subagents")) {
+    const effective = deriveEffectivePermissions(profile);
+    for (const agent of getEnabledSubagents(profile)) {
+      if (agent.toolScope === "workspace-write" && effective.filesystem.write === "deny") {
+        issues.push({
+          code: "unsafe_generated_content",
+          path: `.codex/agents/${agent.name}.toml`,
+          expected: "narrower than effectivePermissions",
+          actual: "workspace-write subagent under filesystem.write=deny",
+          message: `codex-subagents cannot emit workspace-write agent ${agent.name} because effectivePermissions.filesystem.write is deny.`
+        });
+      }
+      if (agent.prompt.includes(`"""`)) {
+        issues.push({
+          code: "unsafe_generated_content",
+          path: `.codex/agents/${agent.name}.toml`,
+          expected: "prompt without TOML triple-quote sequence",
+          actual: 'prompt contains """ delimiter',
+          message: `codex-subagents prompt for ${agent.name} contains a TOML triple-quote sequence that would break developer_instructions.`
+        });
+      }
+    }
+  }
+  if (targets.includes("claude-subagents")) {
+    const effective = deriveEffectivePermissions(profile);
+    for (const agent of getEnabledSubagents(profile)) {
+      if (agent.toolScope === "workspace-write" && effective.filesystem.write === "deny") {
+        issues.push({
+          code: "unsafe_generated_content",
+          path: `.claude/agents/${agent.name}.md`,
+          expected: "narrower than effectivePermissions",
+          actual: "workspace-write subagent under filesystem.write=deny",
+          message: `claude-subagents cannot emit workspace-write agent ${agent.name} because effectivePermissions.filesystem.write is deny.`
+        });
+      }
+    }
+  }
   for (const target of targets) {
     if (!supportedTargets.has(target)) {
       issues.push({
@@ -2142,7 +3247,7 @@ function validateTargets(profile, targets, templates) {
       });
       continue;
     }
-    for (const templateId of getRequiredTemplateIds(target)) {
+    for (const templateId of getRequiredTemplateIds(target, profile)) {
       if (!templateIds.has(templateId)) {
         issues.push({
           code: "missing_template",
@@ -2156,11 +3261,101 @@ function validateTargets(profile, targets, templates) {
   }
   return issues;
 }
-function getRequiredTemplateIds(target) {
-  return TEMPLATE_SOURCES.filter((template) => template.target === target).map(
-    (template) => template.id
+function getRequiredTemplateIdSet(targets, profile) {
+  return new Set(
+    targets.flatMap((target) => getRequiredTemplateIds(target, profile))
   );
 }
+function getRequiredTemplateIds(target, profile) {
+  switch (target) {
+    case "agents-md":
+      return [
+        "targets/agents-md@1",
+        ...getRequiredAgentsMdTopicTemplateIds(profile)
+      ];
+    case "tabnine-guidelines":
+      return getRequiredTabnineGuidelineTemplateIds(profile);
+    case "codex-workflow-skills":
+      return getRequiredWorkflowSkillTemplateIds(
+        profile,
+        "codex-workflow-skills"
+      );
+    case "claude-workflow-skills":
+      return getRequiredWorkflowSkillTemplateIds(
+        profile,
+        "claude-workflow-skills"
+      );
+    case "claude-subagents":
+      return getEnabledSubagents(profile).map(
+        (agent) => `targets/claude-subagents/${agent.name}@1`
+      );
+    case "codex-subagents":
+      return getEnabledSubagents(profile).map(
+        (agent) => `targets/codex-subagents/${agent.name}@1`
+      );
+    case "tabnine-subagents":
+      return getEnabledSubagents(profile).filter((agent) => agent.toolScope === "read-only").map((agent) => `targets/tabnine-subagents/${agent.name}@1`);
+    default:
+      return TEMPLATE_SOURCES.filter(
+        (template) => template.target === target
+      ).map((template) => template.id);
+  }
+}
+function getRequiredAgentsMdTopicTemplateIds(profile) {
+  const ids = [];
+  if (hasStack(profile, "frameworks", "react")) {
+    ids.push("targets/agents-md/30-stack-typescript-react@1");
+  }
+  if (profile.workflow.codeReview === true) {
+    ids.push("targets/agents-md/60-code-review@1");
+  }
+  if (profile.workflow.refactoring === true) {
+    ids.push("targets/agents-md/70-refactoring@1");
+  }
+  if (profile.workflow.documentation === true) {
+    ids.push("targets/agents-md/80-documentation@1");
+  }
+  return ids;
+}
+function getRequiredTabnineGuidelineTemplateIds(profile) {
+  const ids = ["targets/tabnine-guidelines/00-general-agent-behavior@1"];
+  if (profile.workflow.sdd) {
+    ids.push("targets/tabnine-guidelines/10-sdd-workflow@1");
+  }
+  if (profile.workflow.tdd) {
+    ids.push("targets/tabnine-guidelines/20-tdd-workflow@1");
+  }
+  if (hasStack(profile, "languages", "typescript") && hasStack(profile, "frameworks", "sveltekit")) {
+    ids.push("targets/tabnine-guidelines/30-stack-typescript-svelte@1");
+  }
+  if (hasStack(profile, "frameworks", "react")) {
+    ids.push("targets/tabnine-guidelines/30-stack-typescript-react@1");
+  }
+  if (hasStack(profile, "languages", "java") && hasStack(profile, "frameworks", "spring-boot")) {
+    ids.push("targets/tabnine-guidelines/40-stack-java-spring@1");
+  }
+  if (hasAnyStack(profile, "testing", ["playwright", "junit"])) {
+    ids.push("targets/tabnine-guidelines/50-testing-playwright-junit@1");
+  }
+  if (profile.workflow.codeReview === true) {
+    ids.push("targets/tabnine-guidelines/60-code-review@1");
+  }
+  if (profile.workflow.refactoring === true) {
+    ids.push("targets/tabnine-guidelines/70-refactoring@1");
+  }
+  if (profile.workflow.documentation === true) {
+    ids.push("targets/tabnine-guidelines/80-documentation@1");
+  }
+  if (profile.workflow.finalReview) {
+    ids.push("targets/tabnine-guidelines/90-final-review@1");
+  }
+  return ids;
+}
+function getRequiredWorkflowSkillTemplateIds(profile, target) {
+  return WORKFLOW_SKILLS.filter(
+    (skill) => profile.workflow[skill.workflowFlag]
+  ).map((skill) => getWorkflowSkillTemplateId(target, skill.id));
+}
 function uniqueTargets(targets) {
   return Array.from(new Set(targets));
 }
@@ -2331,6 +3526,7 @@ function isNodeError(error) {
 // ../../packages/scanner/src/stack.ts
 import fsPromises2 from "node:fs/promises";
 import path2 from "node:path";
+import { parse as parseYaml } from "yaml";
 var EMPTY_STACK = {
   languages: [],
   frameworks: [],
@@ -2391,6 +3587,9 @@ async function detectStack(rootDir) {
   if (await anyFileExists(rootPath, PLAYWRIGHT_CONFIGS)) {
     stack.testing.push("playwright");
   }
+  if (await fileExists(rootPath, "pubspec.yaml")) {
+    await detectPubspecYaml(rootPath, stack, warnings);
+  }
   return {
     stack: sortStack(stack),
     warnings: warnings.sort(compareWarnings)
@@ -2450,6 +3649,118 @@ async function detectPackageJson(rootPath, stack, warnings) {
     }
   }
 }
+var RIVERPOD_PACKAGES = /* @__PURE__ */ new Set([
+  "riverpod",
+  "flutter_riverpod",
+  "hooks_riverpod",
+  "riverpod_annotation",
+  "riverpod_generator"
+]);
+var DRIFT_PACKAGES = /* @__PURE__ */ new Set(["drift", "drift_flutter", "drift_dev"]);
+var DOTLOTTIE_PACKAGES = /* @__PURE__ */ new Set([
+  "dotlottie_loader",
+  "dotlottie_flutter"
+]);
+var FIREBASE_PACKAGES = /* @__PURE__ */ new Set([
+  "cloud_firestore",
+  "cloud_functions",
+  "firebase_ai",
+  "firebase_analytics",
+  "firebase_app_check",
+  "firebase_app_installations",
+  "firebase_auth",
+  "firebase_core",
+  "firebase_crashlytics",
+  "firebase_data_connect",
+  "firebase_database",
+  "firebase_dynamic_links",
+  "firebase_in_app_messaging",
+  "firebase_messaging",
+  "firebase_ml_model_downloader",
+  "firebase_performance",
+  "firebase_remote_config",
+  "firebase_storage",
+  "firebase_vertexai"
+]);
+async function detectPubspecYaml(rootPath, stack, warnings) {
+  let value;
+  try {
+    value = parseYaml(
+      await fsPromises2.readFile(path2.join(rootPath, "pubspec.yaml"), "utf8")
+    );
+  } catch {
+    warnings.push({
+      code: "metadata_parse_error",
+      path: "pubspec.yaml",
+      expected: "valid YAML metadata",
+      actual: "parse error",
+      message: "pubspec.yaml could not be parsed for stack detection."
+    });
+    return;
+  }
+  const record = getRecord(value);
+  if (!record) {
+    warnings.push({
+      code: "metadata_parse_error",
+      path: "pubspec.yaml",
+      expected: "object metadata",
+      actual: describeValue3(value),
+      message: "pubspec.yaml does not contain object metadata."
+    });
+    return;
+  }
+  stack.packageManagers.push("pub");
+  const environment = getRecord(record.environment);
+  if (environment && environment.sdk !== void 0) {
+    stack.languages.push("dart");
+  }
+  const dependencyKeys = /* @__PURE__ */ new Set();
+  for (const key of ["dependencies", "dev_dependencies", "dependency_overrides"]) {
+    const map = getRecord(record[key]);
+    if (!map) {
+      continue;
+    }
+    for (const dependencyKey of Object.keys(map)) {
+      dependencyKeys.add(dependencyKey);
+    }
+  }
+  if (dependencyKeys.has("flutter")) {
+    stack.languages.push("dart");
+    stack.frameworks.push("flutter");
+  }
+  if (dependencyKeys.has("flutter_test")) {
+    stack.testing.push("flutter-test");
+  }
+  if (hasAny(dependencyKeys, RIVERPOD_PACKAGES)) {
+    stack.frameworks.push("riverpod");
+  }
+  if (dependencyKeys.has("go_router")) {
+    stack.frameworks.push("go-router");
+  }
+  if (hasAny(dependencyKeys, DRIFT_PACKAGES)) {
+    stack.frameworks.push("drift");
+  }
+  if (hasAny(dependencyKeys, FIREBASE_PACKAGES)) {
+    stack.frameworks.push("firebase");
+  }
+  if (dependencyKeys.has("rive")) {
+    stack.frameworks.push("rive");
+  }
+  if (dependencyKeys.has("lottie")) {
+    stack.frameworks.push("lottie");
+  }
+  if (hasAny(dependencyKeys, DOTLOTTIE_PACKAGES)) {
+    stack.frameworks.push("dotlottie");
+  }
+}
+function hasAny(keys, allowlist) {
+  for (const allowed of allowlist) {
+    if (keys.has(allowed)) {
+      return true;
+    }
+  }
+  return false;
+}
 async function detectJavaMetadata(rootPath, relativePath, stack) {
   const source = await fsPromises2.readFile(
     path2.join(rootPath, relativePath),
@@ -2813,6 +4124,14 @@ async function runDoctor(request = {}) {
     });
   }
   await checkPermissionPosture(rootDir, profileResult.profile, issues);
+  await checkSubagentArtifacts({
+    rootDir,
+    profile: profileResult.profile,
+    effective: deriveEffectivePermissions(profileResult.profile),
+    generatedFiles: compileResult.files,
+    lockfile,
+    issues
+  });
   return toResult(issues);
 }
 async function checkGeneratedArtifactsExist(rootDir, files, issues) {
@@ -3802,6 +5121,320 @@ function reportRuntimeUnverifiable(profile, issues) {
     );
   }
 }
+var SUBAGENT_ROOTS = [
+  ".claude/agents",
+  ".codex/agents",
+  ".tabnine/agent/agents"
+];
+var GENERATED_HEADER_MARKER = "Generated by Agent Profile Compiler";
+var TABNINE_UNSAFE_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "run_shell_command",
+  "write_file",
+  "browser_agent",
+  "browser",
+  "open_url",
+  "fetch_url",
+  "http_request",
+  "network"
+]);
+var CLAUDE_WRITE_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "NotebookEdit"]);
+async function checkSubagentArtifacts(input) {
+  const { rootDir, profile, effective, generatedFiles, lockfile, issues } = input;
+  const enabled = getEnabledSubagents(profile);
+  const generatedSubagentPaths = new Set(
+    generatedFiles.filter(
+      (file) => file.target === "claude-subagents" || file.target === "codex-subagents" || file.target === "tabnine-subagents"
+    ).map((file) => file.path)
+  );
+  const lockfileSubagentPaths = new Set(
+    (lockfile?.outputs ?? []).filter(
+      (output) => output.target === "claude-subagents" || output.target === "codex-subagents" || output.target === "tabnine-subagents"
+    ).map((output) => output.path)
+  );
+  for (const agent of enabled) {
+    if (isSubagentBuiltinNameCollision(agent.name)) {
+      issues.push(
+        issue(
+          "LINT-SUBAGENT-005",
+          "warning",
+          `/capabilities/delegation/subagents/agents/${agent.name}`,
+          "name distinct from built-ins",
+          "collides with built-in after normalization",
+          `Subagent ${agent.name} collides with a documented built-in after hyphen/underscore normalization.`,
+          "Rename the subagent to avoid shadowing client built-ins."
+        )
+      );
+    }
+  }
+  for (const root of SUBAGENT_ROOTS) {
+    const files = await collectSubagentFilesUnder(rootDir, root);
+    for (const relativePath of files) {
+      const file = await readKnownFile(rootDir, relativePath);
+      if (!file.ok) continue;
+      const text = decodeUtf8(file.bytes);
+      const isGenerated = text.includes(GENERATED_HEADER_MARKER);
+      if (containsSecretLikeLiteral(text)) {
+        issues.push(
+          issue(
+            "LINT-SUBAGENT-002",
+            "error",
+            relativePath,
+            "no literal secret-like values",
+            "secret-like value present",
+            `${relativePath} contains a literal secret-like value.`,
+            "Remove literal secrets from the subagent file; use environment variable references only."
+          )
+        );
+      }
+      if (root === ".codex/agents") {
+        checkCodexSubagentFile(relativePath, text, effective, issues);
+      } else if (root === ".claude/agents") {
+        checkClaudeSubagentFile(relativePath, text, effective, issues);
+      } else if (root === ".tabnine/agent/agents") {
+        checkTabnineSubagentFile(relativePath, text, effective, issues);
+      }
+      if (isGenerated && !generatedSubagentPaths.has(relativePath) && !lockfileSubagentPaths.has(relativePath)) {
+        issues.push(
+          issue(
+            "LINT-SUBAGENT-006",
+            "warning",
+            relativePath,
+            "claimed by current compile output or lockfile",
+            "orphan generated subagent",
+            `${relativePath} carries the generated-file header but is not produced by the current profile and not recorded in ai-profile.lock.`,
+            "Remove the orphan generated subagent file or restore the matching profile intent."
+          )
+        );
+      }
+    }
+  }
+  if (profile.clients.tabnine.enabled && enabled.some((agent) => agent.toolScope === "read-only")) {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-008",
+        "info",
+        ".tabnine/agent/settings.json",
+        "experimental.enableAgents verifiable",
+        "not verifiable",
+        "Tabnine experimental.enableAgents cannot be verified because Agent Profile Compiler does not write .tabnine/agent/settings.json.",
+        "Manually enable experimental.enableAgents in .tabnine/agent/settings.json to use the generated Tabnine subagent files."
+      )
+    );
+  }
+}
+function checkCodexSubagentFile(relativePath, text, effective, issues) {
+  const sandboxMatch = /^\s*sandbox_mode\s*=\s*"([^"]+)"/mu.exec(text);
+  const sandboxMode = sandboxMatch?.[1];
+  if (sandboxMode === "danger-full-access") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-003",
+        "error",
+        relativePath,
+        "sandboxed Codex subagent",
+        "danger-full-access",
+        `${relativePath} declares danger-full-access, which is never allowed.`,
+        "Remove danger-full-access from the Codex subagent and use read-only or workspace-write instead."
+      )
+    );
+  }
+  if (sandboxMode === "workspace-write" && effective.filesystem.write === "deny") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "narrower than effectivePermissions.filesystem.write=deny",
+        "workspace-write",
+        `${relativePath} grants workspace-write while effectivePermissions deny filesystem writes.`,
+        'Set sandbox_mode = "read-only" or tighten the subagent intent.'
+      )
+    );
+  }
+  if (/^\s*approval_policy\s*=\s*"never"/mu.test(text)) {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "interactive approval policy",
+        "never",
+        `${relativePath} declares approval_policy = "never", which is never allowed for generated Codex subagents.`,
+        'Remove approval_policy = "never" from the Codex subagent.'
+      )
+    );
+  }
+}
+function checkClaudeSubagentFile(relativePath, text, effective, issues) {
+  const frontmatter = parseMarkdownFrontmatter(text);
+  if (frontmatter.permissionMode === "bypassPermissions") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-004",
+        "error",
+        relativePath,
+        "non-bypass Claude permission mode",
+        "bypassPermissions",
+        `${relativePath} declares permissionMode: bypassPermissions, which is never allowed.`,
+        "Remove bypassPermissions from the Claude subagent and use plan or default mode."
+      )
+    );
+  }
+  const tools = parseClaudeToolList(frontmatter.tools);
+  if (tools.includes("Bash") && effective.shell.run !== "allow") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "tools narrower than effectivePermissions.shell.run",
+        "Bash tool granted",
+        `${relativePath} grants the Bash tool while effectivePermissions.shell.run is ${effective.shell.run}.`,
+        "Remove Bash from the Claude subagent tools list or tighten effectivePermissions."
+      )
+    );
+  }
+  if (tools.some((tool) => CLAUDE_WRITE_TOOLS.has(tool)) && effective.filesystem.write !== "allow") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "tools narrower than effectivePermissions.filesystem.write",
+        "Edit/Write tool granted",
+        `${relativePath} grants write tools while effectivePermissions.filesystem.write is ${effective.filesystem.write}.`,
+        "Remove Edit/Write from the Claude subagent tools list or tighten effectivePermissions."
+      )
+    );
+  }
+  if (tools.includes("WebFetch") && effective.network.external !== "allow") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "tools narrower than effectivePermissions.network.external",
+        "WebFetch tool granted",
+        `${relativePath} grants the WebFetch tool while effectivePermissions.network.external is ${effective.network.external}.`,
+        "Remove WebFetch from the Claude subagent tools list or tighten effectivePermissions."
+      )
+    );
+  }
+}
+function checkTabnineSubagentFile(relativePath, text, effective, issues) {
+  const frontmatter = parseMarkdownFrontmatter(text);
+  const tools = parseTabnineToolList(text, frontmatter.tools);
+  const unsafe = tools.filter(
+    (tool) => TABNINE_UNSAFE_TOOL_NAMES.has(tool)
+  );
+  if (unsafe.length > 0) {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-007",
+        "warning",
+        relativePath,
+        "read-only Tabnine subagent tools",
+        `declares ${unsafe.join(", ")}`,
+        `${relativePath} declares write/shell/browser/network-capable tool ${unsafe[0]} while Tabnine subagents are experimental/no-confirmation.`,
+        "Restrict generated Tabnine subagents to read-only tools until safer Tabnine semantics are documented."
+      )
+    );
+  }
+  if (tools.includes("write_file") && effective.filesystem.write !== "allow") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "tools narrower than effectivePermissions.filesystem.write",
+        "write_file tool granted",
+        `${relativePath} grants write_file while effectivePermissions.filesystem.write is ${effective.filesystem.write}.`,
+        "Remove write_file from the Tabnine subagent tools list or tighten effectivePermissions."
+      )
+    );
+  }
+  if (tools.includes("run_shell_command") && effective.shell.run !== "allow") {
+    issues.push(
+      issue(
+        "LINT-SUBAGENT-001",
+        "error",
+        relativePath,
+        "tools narrower than effectivePermissions.shell.run",
+        "run_shell_command tool granted",
+        `${relativePath} grants run_shell_command while effectivePermissions.shell.run is ${effective.shell.run}.`,
+        "Remove run_shell_command from the Tabnine subagent tools list or tighten effectivePermissions."
+      )
+    );
+  }
+}
+function parseMarkdownFrontmatter(text) {
+  if (!text.startsWith("---\n")) return {};
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return {};
+  const block = text.slice(4, end);
+  const result = {};
+  for (const line of block.split("\n")) {
+    const match = /^([A-Za-z][A-Za-z0-9_]*)\s*:\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    if (key === void 0) continue;
+    result[key] = (rawValue ?? "").trim();
+  }
+  return result;
+}
+function parseClaudeToolList(value) {
+  if (!value) return [];
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function parseTabnineToolList(text, inlineValue) {
+  if (inlineValue && inlineValue.length > 0 && inlineValue !== "") {
+    if (inlineValue.startsWith("[") && inlineValue.endsWith("]")) {
+      return inlineValue.slice(1, -1).split(",").map((item) => item.trim().replace(/^["']|["']$/gu, "")).filter((item) => item.length > 0);
+    }
+  }
+  if (!text.startsWith("---\n")) return [];
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) return [];
+  const block = text.slice(4, end).split("\n");
+  const tools = [];
+  let inToolsBlock = false;
+  for (const line of block) {
+    if (/^tools\s*:\s*$/u.test(line)) {
+      inToolsBlock = true;
+      continue;
+    }
+    if (inToolsBlock) {
+      const itemMatch = /^\s+-\s+(.+?)\s*$/u.exec(line);
+      if (itemMatch && itemMatch[1] !== void 0) {
+        tools.push(itemMatch[1].replace(/^["']|["']$/gu, ""));
+        continue;
+      }
+      if (/^\S/u.test(line)) {
+        inToolsBlock = false;
+      }
+    }
+  }
+  return tools;
+}
+async function collectSubagentFilesUnder(rootDir, relativeRoot) {
+  let entries;
+  try {
+    entries = await readdir2(path4.join(rootDir, relativeRoot), {
+      withFileTypes: true
+    });
+  } catch (error) {
+    if (isNodeError4(error) && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    results.push(`${relativeRoot}/${entry.name}`);
+  }
+  return results.sort();
+}
 async function collectSkillFiles(rootDir) {
   const files = [];
   for (const skillRoot of SKILL_ROOTS) {
@@ -5339,7 +6972,7 @@ function formatInitRefusalFacts(input) {
     return [
       `refused: ${message}`,
       "schema v1 requires at least one stack.languages entry.",
-      "add a language manually or re-run inside a recognized project."
+      "create ai-profile.yaml manually or add supported stack metadata and re-run init."
     ].join("\n");
   }
   return [