aigent-team 0.3.0 → 0.4.0

package/README.md

@@ -49,10 +49,19 @@ Each agent is a senior-level specialist (8+ years expertise) with deep knowledge
        └─────┘  └─────┘ └─────┘ └──────┘  └───────┘
 ```
 
-Each agent has three layers of knowledge:
-- **Rules** (~30-50 lines) — always loaded, top of context. Hard constraints: scope limits, prohibited actions, escalation triggers, output requirements.
-- **Skill index** (~80-150 lines) — always loaded. Core principles, anti-patterns, decision frameworks, reference + skill catalogs.
-- **Reference files** (3-9 per agent) + **Skill files** (2+ per agent) — loaded on-demand when the task requires deep knowledge or executable procedures.
+Each agent has a 9-layer content architecture (L0–L8):
+
+| Layer | Content | Loading |
+|-------|---------|---------|
+| **L0** Use Case | Agent identity + role description | Always |
+| **L1** Metadata | Frontmatter: name, trigger, tags, whenToRead | Always (catalog) |
+| **L2** Core Skill | Rules (~30-50 lines) + skill index (~80-150 lines) | Always |
+| **L3** References | Deep reference docs (3-9 per agent) | On-demand |
+| **L4** Examples | Few-shot examples for output quality | On-demand |
+| **L5** Scripts | Automation and validation scripts | On-demand |
+| **L6** Assets | Templates, report formats, checklists | On-demand |
+| **L7** Output Contracts | Self-validation rubrics | On-demand |
+| **L8** Governance | Version, owner, review status (manifest only) | Never (audit) |
 
 This keeps the always-loaded context slim while providing access to thousands of lines of senior expertise when needed.
 
@@ -91,7 +100,7 @@ npx aigent-team generate
 
 When run without flags, an interactive wizard lets you choose:
 - **Generate mode**: Platform configs or Plugin bundle
-- **Scopes**: Agents, Skills, References
+- **Scopes**: Agents, Skills, References, Examples, Output Contracts, Scripts, Assets
 - **Team agents**: which roles to generate
 - **Target platforms**: which platforms to generate for
 
@@ -186,6 +195,31 @@ npx aigent-team validate
 
 Checks generated files against each platform's constraints (file size, frontmatter format, naming).
 
+### Audit
+
+```bash
+npx aigent-team audit
+```
+
+Reports skill governance status across all agents:
+- **Status breakdown**: active, draft, review-needed, deprecated
+- **Errors**: deprecated skills (exits with code 1 for CI integration)
+- **Warnings**: skills needing review, missing governance metadata
+- **Info**: draft skills, missing version/owner
+
+Skills opt into governance via frontmatter:
+
+```yaml
+---
+name: Analyze Bundle Size
+governance:
+  version: "1.0.0"
+  owner: fe-team
+  status: active
+  lastReviewedAt: "2025-03-15"
+---
+```
+
 ## Configuration
 
 Create `aigent-team.config.json` (or `.ts` / `.js`) in your project root:
@@ -250,8 +284,10 @@ npx aigent-team generate --platform claude-code    # Single platform
 npx aigent-team generate --scope skills            # Only skill files
 npx aigent-team generate --team fe,be              # Only FE + BE agents
 npx aigent-team generate --scope plugin            # Plugin bundle
+npx aigent-team generate --scope examples,scripts  # Only examples + scripts
 npx aigent-team install ./plugin --force           # Install plugin
 npx aigent-team uninstall my-app                   # Remove plugin
+npx aigent-team audit                              # Governance audit
 ```
 
 ## Generated output
@@ -261,13 +297,17 @@ After running `aigent-team generate`, you'll see:
 ```
 # Claude Code
 .claude/agents/fe-agent.md               # Rules + skill index (always loaded)
-.claude/agents/fe-agent/references/       # Deep reference docs
+.claude/agents/fe-agent/references/       # Deep reference docs (L3)
   ├── component-architecture.md
   ├── state-management.md
   └── ...
-.claude/agents/fe-agent/skills/           # Executable procedures
+.claude/agents/fe-agent/skills/           # Executable procedures (L2)
   ├── analyze-bundle.md
   └── component-audit.md
+.claude/agents/fe-agent/examples/         # Few-shot examples (L4)
+.claude/agents/fe-agent/contracts/        # Output contracts (L7)
+.claude/agents/fe-agent/scripts/          # Automation scripts (L5)
+.claude/agents/fe-agent/assets/           # Templates & resources (L6)
 CLAUDE.md                                 # Agent team overview
 
 # Cursor
@@ -415,6 +455,7 @@ This mirrors how a real tech lead operates — delegating to specialists and ens
 | [Agent Reference](docs/base/agents.md) | All 6 agents — roles, capabilities, reference file catalog |
 | [Vision & Roadmap](docs/base/vision.md) | Future plans, design principles, platform expansion |
 | [RFC-001: Scope & Plugin](docs/rfcs/rfc-001-generate-scope.md) | `--scope`, `--team`, plugin system design |
+| [RFC-002: Content Layers](docs/rfcs/rfc-002-skill-content-layers.md) | 9-layer architecture (L0–L8), frontmatter, governance |
 | [Contributing](CONTRIBUTING.md) | Development setup, how to add agents/compilers |
 | [Changelog](CHANGELOG.md) | Release history |
 

package/dist/{chunk-RH4B2QFX.js → chunk-OMO7OMKB.js}

@@ -4,7 +4,7 @@ import { createRequire } from 'module'; const require = createRequire(import.met
 import { z } from "zod";
 var PLATFORMS = ["claude-code", "cursor", "codex", "antigravity"];
 var TEAM_ROLES = ["lead", "ba", "fe", "be", "qa", "devops"];
-var GENERATE_SCOPES = ["all", "agents", "skills", "references", "plugin"];
+var GENERATE_SCOPES = ["all", "agents", "skills", "references", "examples", "output-contracts", "scripts", "assets", "plugin"];
 var PLUGIN_BUNDLE_DIRS = {
   "claude-code": "claude-code-plugin",
   cursor: "cursor-ide-plugin",
@@ -81,6 +81,7 @@ import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync }
 import { resolve as resolve2, dirname } from "path";
 import { fileURLToPath } from "url";
 import { parse as parseYaml } from "yaml";
+import matter from "gray-matter";
 import { deepmerge } from "deepmerge-ts";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var PACKAGE_ROOT = resolve2(__dirname, "..");
@@ -88,6 +89,13 @@ var TEMPLATES_DIR = existsSync2(resolve2(PACKAGE_ROOT, "templates")) ? resolve2(
 function readIfExists(path) {
   return existsSync2(path) ? readFileSync2(path, "utf-8").trim() : "";
 }
+function parseFrontmatter(raw) {
+  if (!raw.trimStart().startsWith("---")) {
+    return { data: {}, content: raw };
+  }
+  const { data, content } = matter(raw);
+  return { data, content: content.trim() };
+}
 function loadReferences(refsDir) {
   if (!existsSync2(refsDir)) return [];
   const refs = [];
@@ -97,47 +105,158 @@ function loadReferences(refsDir) {
       const subDir = resolve2(refsDir, file.name);
       const subFiles = readdirSync(subDir).filter((f) => f.endsWith(".md"));
       for (const subFile of subFiles) {
-        const content = readFileSync2(resolve2(subDir, subFile), "utf-8").trim();
+        const raw = readFileSync2(resolve2(subDir, subFile), "utf-8").trim();
+        const { data, content } = parseFrontmatter(raw);
         const id = `${file.name}/${subFile.replace(".md", "")}`;
         refs.push({
           id,
-          title: subFile.replace(".md", "").replace(/-/g, " "),
-          description: "",
-          whenToRead: "",
-          content
+          title: data.title || subFile.replace(".md", "").replace(/-/g, " "),
+          description: data.description || "",
+          whenToRead: data.whenToRead || "",
+          content,
+          tags: data.tags || void 0
         });
       }
     } else if (file.name.endsWith(".md")) {
-      const content = readFileSync2(resolve2(refsDir, file.name), "utf-8").trim();
+      const raw = readFileSync2(resolve2(refsDir, file.name), "utf-8").trim();
+      const { data, content } = parseFrontmatter(raw);
       const id = file.name.replace(".md", "");
       refs.push({
         id,
-        title: id.replace(/-/g, " "),
-        description: "",
-        whenToRead: "",
-        content
+        title: data.title || id.replace(/-/g, " "),
+        description: data.description || "",
+        whenToRead: data.whenToRead || "",
+        content,
+        tags: data.tags || void 0
       });
     }
   }
   return refs;
 }
+var GOVERNANCE_STATUSES = ["draft", "active", "review-needed", "deprecated"];
+function parseGovernance(data) {
+  const gov = data.governance;
+  if (!gov) return void 0;
+  const result = {};
+  if (typeof gov.version === "string") result.version = gov.version;
+  if (typeof gov.owner === "string") result.owner = gov.owner;
+  if (typeof gov.status === "string" && GOVERNANCE_STATUSES.includes(gov.status)) {
+    result.status = gov.status;
+  }
+  if (typeof gov.lastReviewedAt === "string") result.lastReviewedAt = gov.lastReviewedAt;
+  if (typeof gov.deprecatedReason === "string") result.deprecatedReason = gov.deprecatedReason;
+  return Object.keys(result).length > 0 ? result : void 0;
+}
 function loadSkills(skillsDir) {
   if (!existsSync2(skillsDir)) return [];
   const skills = [];
   const files = readdirSync(skillsDir).filter((f) => f.endsWith(".md"));
   for (const file of files) {
-    const content = readFileSync2(resolve2(skillsDir, file), "utf-8").trim();
+    const raw = readFileSync2(resolve2(skillsDir, file), "utf-8").trim();
+    const { data, content } = parseFrontmatter(raw);
     const id = file.replace(".md", "");
     skills.push({
       id,
-      name: id.replace(/-/g, " "),
-      description: "",
-      trigger: "",
-      content
+      name: data.name || id.replace(/-/g, " "),
+      description: data.description || "",
+      trigger: data.trigger || "",
+      content,
+      useCases: data.useCases || void 0,
+      tags: data.tags || void 0,
+      governance: parseGovernance(data)
     });
   }
   return skills;
 }
+function loadExamples(examplesDir) {
+  if (!existsSync2(examplesDir)) return [];
+  return readdirSync(examplesDir).filter((f) => f.endsWith(".md")).map((f) => {
+    const raw = readFileSync2(resolve2(examplesDir, f), "utf-8").trim();
+    const { data, content } = parseFrontmatter(raw);
+    const id = f.replace(".md", "");
+    return {
+      id,
+      name: data.name || id.replace(/-/g, " "),
+      description: data.description || "",
+      skillRef: data.skillRef || void 0,
+      content,
+      tags: data.tags || void 0
+    };
+  });
+}
+function loadOutputContracts(contractsDir) {
+  if (!existsSync2(contractsDir)) return [];
+  return readdirSync(contractsDir).filter((f) => f.endsWith(".md")).map((f) => {
+    const raw = readFileSync2(resolve2(contractsDir, f), "utf-8").trim();
+    const { data, content } = parseFrontmatter(raw);
+    const id = f.replace(".md", "");
+    return {
+      id,
+      name: data.name || id.replace(/-/g, " "),
+      description: data.description || "",
+      skillRef: data.skillRef || void 0,
+      format: data.format || void 0,
+      content,
+      tags: data.tags || void 0
+    };
+  });
+}
+var SCRIPT_EXTENSIONS = [".md", ".sh", ".py", ".js", ".ts"];
+function inferLanguage(filename) {
+  const ext = filename.slice(filename.lastIndexOf("."));
+  const map = {
+    ".sh": "bash",
+    ".py": "python",
+    ".js": "javascript",
+    ".ts": "typescript",
+    ".md": "markdown"
+  };
+  return map[ext] || "unknown";
+}
+function loadScripts(scriptsDir) {
+  if (!existsSync2(scriptsDir)) return [];
+  return readdirSync(scriptsDir).filter((f) => SCRIPT_EXTENSIONS.some((ext) => f.endsWith(ext))).map((f) => {
+    const raw = readFileSync2(resolve2(scriptsDir, f), "utf-8").trim();
+    const { data, content } = parseFrontmatter(raw);
+    const id = f.replace(/\.[^.]+$/, "");
+    return {
+      id,
+      name: data.name || id.replace(/-/g, " "),
+      description: data.description || "",
+      language: data.language || inferLanguage(f),
+      content,
+      tags: data.tags || void 0
+    };
+  });
+}
+var ASSET_EXTENSIONS = [".md", ".json", ".yaml", ".yml", ".html"];
+function inferFormat(filename) {
+  const ext = filename.slice(filename.lastIndexOf("."));
+  const map = {
+    ".md": "markdown",
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".html": "html"
+  };
+  return map[ext] || "unknown";
+}
+function loadAssets(assetsDir) {
+  if (!existsSync2(assetsDir)) return [];
+  return readdirSync(assetsDir).filter((f) => ASSET_EXTENSIONS.some((ext) => f.endsWith(ext))).map((f) => {
+    const raw = readFileSync2(resolve2(assetsDir, f), "utf-8").trim();
+    const { data, content } = parseFrontmatter(raw);
+    const id = f.replace(/\.[^.]+$/, "");
+    return {
+      id,
+      name: data.name || id.replace(/-/g, " "),
+      description: data.description || "",
+      format: data.format || inferFormat(f),
+      content,
+      tags: data.tags || void 0
+    };
+  });
+}
 function loadBuiltinAgent(role) {
   const teamDir = resolve2(TEMPLATES_DIR, "teams", role);
   const agentYaml = readFileSync2(resolve2(teamDir, "agent.yaml"), "utf-8");
@@ -148,6 +267,10 @@ function loadBuiltinAgent(role) {
   const references = loadReferences(resolve2(teamDir, "references"));
   const rulesContent = readIfExists(resolve2(teamDir, "rules.md"));
   const skills = loadSkills(resolve2(teamDir, "skills"));
+  const examples = loadExamples(resolve2(teamDir, "examples"));
+  const outputContracts = loadOutputContracts(resolve2(teamDir, "output-contracts"));
+  const scripts = loadScripts(resolve2(teamDir, "scripts"));
+  const assets = loadAssets(resolve2(teamDir, "assets"));
   return {
     id: agentDef.id,
     name: agentDef.name,
@@ -164,6 +287,10 @@ function loadBuiltinAgent(role) {
     references,
     rulesContent,
     skills,
+    examples,
+    outputContracts,
+    scripts,
+    assets,
     globs: agentDef.globs || []
   };
 }
@@ -216,6 +343,22 @@ function loadAgents(config, cwd = process.cwd()) {
       if (localSkills.length) {
         agent.skills = [...agent.skills, ...localSkills];
       }
+      const localExamples = loadExamples(resolve2(localDir, "examples"));
+      if (localExamples.length) {
+        agent.examples = [...agent.examples, ...localExamples];
+      }
+      const localContracts = loadOutputContracts(resolve2(localDir, "output-contracts"));
+      if (localContracts.length) {
+        agent.outputContracts = [...agent.outputContracts, ...localContracts];
+      }
+      const localScripts = loadScripts(resolve2(localDir, "scripts"));
+      if (localScripts.length) {
+        agent.scripts = [...agent.scripts, ...localScripts];
+      }
+      const localAssets = loadAssets(resolve2(localDir, "assets"));
+      if (localAssets.length) {
+        agent.assets = [...agent.assets, ...localAssets];
+      }
     }
     const resolvedShared = [];
     for (const ref of agent.sharedKnowledge) {
@@ -244,20 +387,92 @@ function assembleSkillIndex(agent) {
   } else {
     parts.push(assembleAgentMarkdown(agent));
   }
-  if (agent.skills?.length) {
-    const skillLines = agent.skills.map(
-      (s) => `| \`${s.id}\` | ${s.name} |`
+  if (agent.references?.length) {
+    const refsWithMeta = agent.references.filter((r) => r.whenToRead);
+    if (refsWithMeta.length) {
+      const refLines = refsWithMeta.map(
+        (r) => `| \`${r.id}\` | ${r.title} | ${r.whenToRead} |`
+      );
+      parts.push([
+        "## Reference Files",
+        "",
+        "Load the relevant reference file when you need deep knowledge:",
+        "",
+        "| Reference | Title | When to read |",
+        "|-----------|-------|-------------|",
+        ...refLines
+      ].join("\n"));
+    }
+  }
+  if (agent.examples?.length) {
+    const exampleLines = agent.examples.map(
+      (e) => `| \`${e.id}\` | ${e.name} | ${e.skillRef || "\u2014"} |`
     );
+    parts.push([
+      "## Examples",
+      "",
+      "Load the relevant example file for few-shot guidance:",
+      "",
+      "| Example | Name | Skill Ref |",
+      "|---------|------|-----------|",
+      ...exampleLines
+    ].join("\n"));
+  }
+  if (agent.outputContracts?.length) {
+    const contractLines = agent.outputContracts.map(
+      (c) => `| \`${c.id}\` | ${c.name} | ${c.format || "\u2014"} |`
+    );
+    parts.push([
+      "## Output Contracts",
+      "",
+      "Validate your output against the relevant contract:",
+      "",
+      "| Contract | Name | Format |",
+      "|----------|------|--------|",
+      ...contractLines
+    ].join("\n"));
+  }
+  if (agent.skills?.length) {
+    const hasTriggers = agent.skills.some((s) => s.trigger);
+    const skillLines = hasTriggers ? agent.skills.map((s) => `| \`${s.id}\` | ${s.name} | ${s.trigger || "\u2014"} |`) : agent.skills.map((s) => `| \`${s.id}\` | ${s.name} |`);
+    const header = hasTriggers ? ["| Skill | Name | Trigger |", "|-------|------|---------|"] : ["| Skill | Name |", "|-------|------|"];
     parts.push([
       "## Executable Skills",
       "",
       "Load the relevant skill file when performing these procedures:",
       "",
-      "| Skill | Name |",
-      "|-------|------|",
+      ...header,
       ...skillLines
     ].join("\n"));
   }
+  if (agent.scripts?.length) {
+    const scriptLines = agent.scripts.map(
+      (s) => `| \`${s.id}\` | ${s.name} | ${s.language} |`
+    );
+    parts.push([
+      "## Scripts",
+      "",
+      "Available automation and validation scripts:",
+      "",
+      "| Script | Name | Language |",
+      "|--------|------|----------|",
+      ...scriptLines
+    ].join("\n"));
+  }
+  if (agent.assets?.length) {
+    const assetLines = agent.assets.map(
+      (a) => `| \`${a.id}\` | ${a.name} | ${a.format} |`
+    );
+    parts.push([
+      "## Assets",
+      "",
+      "Available templates and resource files:",
+      "",
+      "| Asset | Name | Format |",
+      "|-------|------|--------|",
+      ...assetLines
+    ].join("\n"));
+  }
   return parts.join("\n\n");
 }
 function assembleAgentMarkdown(agent) {
@@ -318,6 +533,18 @@ function assembleReference(ref) {
 function assembleSkill(skill) {
   return skill.content;
 }
+function assembleExample(example) {
+  return example.content;
+}
+function assembleOutputContract(contract) {
+  return contract.content;
+}
+function assembleScript(script) {
+  return script.content;
+}
+function assembleAsset(asset) {
+  return asset.content;
+}
 
 export {
   PLATFORMS,
@@ -326,9 +553,14 @@ export {
   PLUGIN_BUNDLE_DIRS,
   loadConfig,
   configExists,
+  parseFrontmatter,
   loadAgents,
   assembleSkillIndex,
   assembleAgentMarkdown,
   assembleReference,
-  assembleSkill
+  assembleSkill,
+  assembleExample,
+  assembleOutputContract,
+  assembleScript,
+  assembleAsset
 };