aigent-team 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Đức Trần Xuân (ducsatthu)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# aigent-team
+
+[![npm version](https://img.shields.io/npm/v/aigent-team)](https://www.npmjs.com/package/aigent-team)
+[![license](https://img.shields.io/npm/l/aigent-team)](LICENSE)
+[![node](https://img.shields.io/node/v/aigent-team)](package.json)
+
+One config, six AI agents, four platforms. Generate senior-level AI coding agent configurations from a single source of truth.
+
+```
+aigent-team generate
+```
+
+> Requires **Node.js >= 18**
+
+## What it does
+
+aigent-team compiles YAML+Markdown templates into platform-native agent configs for:
+
+| Platform | Output format |
+|---|---|
+| **Claude Code** | `.claude/agents/*.md` with YAML frontmatter |
+| **Cursor** | `.cursor/rules/*.mdc` with MDC frontmatter + globs |
+| **Codex** | `AGENTS.md` + `.codex/agents/*.md` |
+| **Antigravity** | `GEMINI.md` + `.agents/skills/*/SKILL.md` |
+
+Each agent is a senior-level specialist (8+ years expertise) with deep knowledge baked into reference files:
+
+| Agent | Role | Reference topics |
+|---|---|---|
+| **Lead** | Tech Lead / PM orchestrator | Task decomposition, cross-team coordination, quality gates |
+| **BA** | Business Analyst | Requirements analysis, acceptance criteria, API contracts, story mapping |
+| **FE** | Frontend Engineer | Components, state, performance, a11y, security, CSS, forms, testing |
+| **BE** | Backend Engineer | API design, database, auth, error handling, observability, caching, async |
+| **QA** | QA Engineer | Test strategy, E2E, test data, mocking, perf testing, security testing, CI |
+| **DevOps** | DevOps / SRE | IaC, Docker, K8s, CI/CD, monitoring, security, DR, cost optimization |
+
+## Architecture
+
+```
+                    ┌─────────────────┐
+                    │   Lead Agent    │  orchestrator
+                    │   (Tech Lead)   │
+                    └───────┬─────────┘
+                            │ spawn & assign
+          ┌─────────┬───────┼───────┬──────────┐
+          ▼         ▼       ▼       ▼          ▼
+       ┌─────┐  ┌─────┐ ┌─────┐ ┌──────┐  ┌───────┐
+       │ BA  │  │ FE  │ │ BE  │ │  QA  │  │DevOps │
+       └─────┘  └─────┘ └─────┘ └──────┘  └───────┘
+```
+
+Each agent has:
+- **Skill index** (~80-150 lines) — always loaded in context. Core principles, anti-patterns, decision frameworks.
+- **Reference files** (3-9 per agent) — loaded on-demand when the task requires deep knowledge.
+
+This keeps the always-loaded context slim while providing access to thousands of lines of senior expertise when needed.
+
+## Quick start
+
+### Install
+
+```bash
+npm install -D aigent-team
+```
+
+Or use directly:
+
+```bash
+npx aigent-team init
+```
+
+### Initialize
+
+```bash
+npx aigent-team init
+```
+
+Interactive wizard that:
+1. Detects which AI tools you have installed (Claude Code, Cursor, Codex, Antigravity)
+2. Lets you pick which team agents to enable
+3. Creates `aigent-team.config.json`
+
+### Generate
+
+```bash
+npx aigent-team generate
+```
+
+Generates agent configs for all configured platforms. Run this after changing your config or updating aigent-team.
+
+### Validate
+
+```bash
+npx aigent-team validate
+```
+
+Checks generated files against each platform's constraints (file size, frontmatter format, naming).
+
+## Configuration
+
+Create `aigent-team.config.json` (or `.ts` / `.js`) in your project root:
+
+```json
+{
+  "projectName": "my-app",
+  "platforms": ["claude-code", "cursor"],
+  "teams": ["lead", "fe", "be", "qa"],
+  "overrides": {
+    "fe": {
+      "techStack": {
+        "frameworks": ["Next.js 15", "React 19"],
+        "libraries": ["Tailwind CSS 4", "Zustand", "TanStack Query"]
+      }
+    },
+    "be": {
+      "techStack": {
+        "frameworks": ["NestJS", "Prisma"],
+        "libraries": ["PostgreSQL", "Redis", "BullMQ"]
+      }
+    }
+  }
+}
+```
+
+### Config options
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `projectName` | `string` | Yes | Your project name |
+| `platforms` | `string[]` | Yes | Target platforms: `claude-code`, `cursor`, `codex`, `antigravity` |
+| `teams` | `string[]` | Yes | Agent teams to enable: `lead`, `ba`, `fe`, `be`, `qa`, `devops` |
+| `overrides` | `object` | No | Per-team overrides for `techStack`, `tools`, `globs` |
+| `overrides.<team>.techStack` | `object` | No | Override `languages`, `frameworks`, `libraries`, `buildTools` |
+
+### Programmatic config
+
+```typescript
+// aigent-team.config.ts
+import { defineConfig } from 'aigent-team';
+
+export default defineConfig({
+  projectName: 'my-app',
+  platforms: ['claude-code', 'cursor'],
+  teams: ['lead', 'fe', 'be', 'qa'],
+  overrides: {
+    fe: {
+      techStack: {
+        frameworks: ['Next.js 15'],
+      },
+    },
+  },
+});
+```
+
+### Platform-specific flags
+
+```bash
+# Generate only for a specific platform
+npx aigent-team generate --platform claude-code
+```
+
+## Generated output
+
+After running `aigent-team generate`, you'll see:
+
+```
+# Claude Code
+.claude/agents/lead-agent.md              # Skill index (always loaded)
+.claude/agents/lead-agent/references/     # Deep reference docs
+.claude/agents/fe-agent.md
+.claude/agents/fe-agent/references/
+  ├── component-architecture.md
+  ├── state-management.md
+  ├── performance.md
+  ├── accessibility.md
+  ├── security.md
+  ├── testing.md
+  ├── css-styling.md
+  ├── forms.md
+  └── review-checklist.md
+...
+CLAUDE.md                                 # Agent team overview
+
+# Cursor
+.cursor/rules/fe-agent.mdc               # Glob-scoped skill
+.cursor/rules/fe-refs/                    # Glob-scoped references
+...
+
+# Codex
+AGENTS.md                                 # Combined agent doc
+.codex/agents/fe-agent.md                 # Individual agent
+.codex/agents/fe-agent/references/        # References
+...
+
+# Antigravity
+GEMINI.md                                 # Agent overview
+.agents/skills/fe-agent/SKILL.md          # Skill file
+.agents/skills/fe-agent/references/       # References
+...
+```
+
+## What to commit
+
+Generated files **should be committed** to your repo — they are the actual agent configs your AI tools read. Add this to your workflow:
+
+```bash
+npx aigent-team generate
+git add .claude/ .cursor/ .codex/ .agents/ CLAUDE.md AGENTS.md GEMINI.md
+git commit -m "chore: regenerate agent configs"
+```
+
+Only `.aigent-team/` (local overrides) and `aigent-team.config.json` are your source files. Everything else is generated output.
+
+## Local overrides
+
+Create a `.aigent-team/` directory in your project to override any template locally:
+
+```
+.aigent-team/
+├── teams/
+│   └── fe/
+│       └── references/
+│           └── component-architecture.md   # Your custom version
+└── shared/
+    └── git-workflow.md                     # Your git workflow
+```
+
+Local overrides take priority over built-in templates. This lets you customize agent knowledge for your specific project without forking.
+
+## How the Lead agent works
+
+The Lead agent acts as orchestrator. When it receives a task, it:
+
+1. **Analyzes** the requirement — identifies which teams are involved
+2. **Spawns** the right team agents (BA for specs, FE/BE for implementation, QA for tests)
+3. **Coordinates** cross-team work (e.g., FE+BE align on API contract via BA specs)
+4. **Reviews** output quality before delivery
+
+This mirrors how a real tech lead operates — delegating to specialists and ensuring alignment.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+Issues and PRs welcome at [github.com/ducsatthu/aigent-team](https://github.com/ducsatthu/aigent-team).
+
+## Author
+
+**Đức Trần Xuân** ([@ducsatthu](https://github.com/ducsatthu)) — ductranxuan.29710@gmail.com
+
+## License
+
+[MIT](LICENSE)

package/dist/chunk-N3RYHWTR.js

@@ -0,0 +1,267 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+
+// src/core/types.ts
+import { z } from "zod";
+var PLATFORMS = ["claude-code", "cursor", "codex", "antigravity"];
+var TEAM_ROLES = ["lead", "ba", "fe", "be", "qa", "devops"];
+var TechStackSchema = z.object({
+  languages: z.array(z.string()).optional(),
+  frameworks: z.array(z.string()).optional(),
+  libraries: z.array(z.string()).optional(),
+  buildTools: z.array(z.string()).optional()
+});
+var AgentOverrideSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  systemPrompt: z.string().optional(),
+  techStack: TechStackSchema.optional(),
+  conventions: z.string().optional(),
+  reviewChecklist: z.string().optional(),
+  tools: z.object({
+    allowed: z.array(z.string()).optional(),
+    denied: z.array(z.string()).optional()
+  }).optional(),
+  globs: z.array(z.string()).optional()
+});
+var ConfigSchema = z.object({
+  projectName: z.string(),
+  platforms: z.array(z.enum(PLATFORMS)).min(1),
+  teams: z.array(z.enum(TEAM_ROLES)).min(1),
+  overrides: z.record(z.enum(TEAM_ROLES), AgentOverrideSchema).optional(),
+  shared: z.object({
+    conventions: z.string().optional(),
+    apiSpecs: z.string().optional(),
+    architecture: z.string().optional()
+  }).optional(),
+  output: z.object({
+    directory: z.string().optional()
+  }).optional()
+});
+
+// src/core/config-loader.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { pathToFileURL } from "url";
+var CONFIG_FILES = [
+  "aigent-team.config.ts",
+  "aigent-team.config.js",
+  "aigent-team.config.json"
+];
+async function loadConfig(cwd = process.cwd()) {
+  for (const file of CONFIG_FILES) {
+    const filePath = resolve(cwd, file);
+    if (!existsSync(filePath)) continue;
+    if (file.endsWith(".json")) {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+      return ConfigSchema.parse(raw);
+    }
+    const mod = await import(pathToFileURL(filePath).href);
+    const config = mod.default ?? mod;
+    return ConfigSchema.parse(config);
+  }
+  throw new Error(
+    `No aigent-team config found. Run \`aigent-team init\` to create one.`
+  );
+}
+function configExists(cwd = process.cwd()) {
+  return CONFIG_FILES.some((f) => existsSync(resolve(cwd, f)));
+}
+
+// src/core/agent-loader.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync } from "fs";
+import { resolve as resolve2, dirname } from "path";
+import { fileURLToPath } from "url";
+import { parse as parseYaml } from "yaml";
+import { deepmerge } from "deepmerge-ts";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var PACKAGE_ROOT = resolve2(__dirname, "..");
+var TEMPLATES_DIR = existsSync2(resolve2(PACKAGE_ROOT, "templates")) ? resolve2(PACKAGE_ROOT, "templates") : resolve2(__dirname, "../../templates");
+function readIfExists(path) {
+  return existsSync2(path) ? readFileSync2(path, "utf-8").trim() : "";
+}
+function loadReferences(refsDir) {
+  if (!existsSync2(refsDir)) return [];
+  const refs = [];
+  const files = readdirSync(refsDir, { withFileTypes: true });
+  for (const file of files) {
+    if (file.isDirectory()) {
+      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 id = `${file.name}/${subFile.replace(".md", "")}`;
+        refs.push({
+          id,
+          title: subFile.replace(".md", "").replace(/-/g, " "),
+          description: "",
+          whenToRead: "",
+          content
+        });
+      }
+    } else if (file.name.endsWith(".md")) {
+      const content = readFileSync2(resolve2(refsDir, file.name), "utf-8").trim();
+      const id = file.name.replace(".md", "");
+      refs.push({
+        id,
+        title: id.replace(/-/g, " "),
+        description: "",
+        whenToRead: "",
+        content
+      });
+    }
+  }
+  return refs;
+}
+function loadBuiltinAgent(role) {
+  const teamDir = resolve2(TEMPLATES_DIR, "teams", role);
+  const agentYaml = readFileSync2(resolve2(teamDir, "agent.yaml"), "utf-8");
+  const agentDef = parseYaml(agentYaml);
+  const skillContent = readIfExists(resolve2(teamDir, "skill.md"));
+  const conventions = readIfExists(resolve2(teamDir, "conventions.md"));
+  const reviewChecklist = readIfExists(resolve2(teamDir, "review-checklist.md"));
+  const references = loadReferences(resolve2(teamDir, "references"));
+  return {
+    id: agentDef.id,
+    name: agentDef.name,
+    description: agentDef.description,
+    role: agentDef.role,
+    systemPrompt: agentDef.systemPrompt || "",
+    skillContent,
+    techStack: agentDef.techStack || { languages: [], frameworks: [], libraries: [], buildTools: [] },
+    conventions,
+    reviewChecklist,
+    tools: agentDef.tools || { allowed: [] },
+    workflows: agentDef.workflows || [],
+    sharedKnowledge: agentDef.sharedKnowledge || [],
+    references,
+    globs: agentDef.globs || []
+  };
+}
+function loadSharedKnowledge() {
+  const sharedDir = resolve2(TEMPLATES_DIR, "shared");
+  const knowledge = {};
+  const files = ["project-conventions.md", "git-workflow.md"];
+  for (const file of files) {
+    const key = file.replace(".md", "");
+    knowledge[key] = readIfExists(resolve2(sharedDir, file));
+  }
+  return knowledge;
+}
+function loadAgents(config, cwd = process.cwd()) {
+  const sharedKnowledge = loadSharedKnowledge();
+  const agents = [];
+  for (const role of config.teams) {
+    let agent = loadBuiltinAgent(role);
+    const override = config.overrides?.[role];
+    if (override) {
+      let conventions = agent.conventions;
+      if (override.conventions && existsSync2(resolve2(cwd, override.conventions))) {
+        conventions = readFileSync2(resolve2(cwd, override.conventions), "utf-8").trim();
+      }
+      agent = deepmerge(agent, {
+        ...override,
+        conventions
+      });
+    }
+    const localDir = resolve2(cwd, ".aigent-team", "teams", role);
+    if (existsSync2(localDir)) {
+      const localConventions = readIfExists(resolve2(localDir, "conventions.md"));
+      const localChecklist = readIfExists(resolve2(localDir, "review-checklist.md"));
+      const localSkill = readIfExists(resolve2(localDir, "skill.md"));
+      if (localConventions) agent.conventions = localConventions;
+      if (localChecklist) agent.reviewChecklist = localChecklist;
+      if (localSkill) agent.skillContent = localSkill;
+      const localRefs = loadReferences(resolve2(localDir, "references"));
+      if (localRefs.length) {
+        agent.references = [...agent.references, ...localRefs];
+      }
+    }
+    const resolvedShared = [];
+    for (const ref of agent.sharedKnowledge) {
+      if (sharedKnowledge[ref]) {
+        resolvedShared.push(sharedKnowledge[ref]);
+      }
+      if (ref === "project-conventions" && config.shared?.conventions) {
+        const p = resolve2(cwd, config.shared.conventions);
+        if (existsSync2(p)) resolvedShared.push(readFileSync2(p, "utf-8").trim());
+      }
+    }
+    agent.sharedKnowledge = resolvedShared;
+    agents.push(agent);
+  }
+  return agents;
+}
+
+// src/core/template-engine.ts
+function assembleSkillIndex(agent) {
+  if (agent.skillContent) {
+    return agent.skillContent;
+  }
+  return assembleAgentMarkdown(agent);
+}
+function assembleAgentMarkdown(agent) {
+  const sections = [];
+  sections.push(`# ${agent.name}
+
+${agent.description}`);
+  if (agent.systemPrompt) {
+    sections.push(agent.systemPrompt);
+  }
+  const { techStack } = agent;
+  const stackLines = [];
+  if (techStack.languages.length) stackLines.push(`- **Languages**: ${techStack.languages.join(", ")}`);
+  if (techStack.frameworks.length) stackLines.push(`- **Frameworks**: ${techStack.frameworks.join(", ")}`);
+  if (techStack.libraries.length) stackLines.push(`- **Libraries**: ${techStack.libraries.join(", ")}`);
+  if (techStack.buildTools.length) stackLines.push(`- **Build Tools**: ${techStack.buildTools.join(", ")}`);
+  if (stackLines.length) {
+    sections.push(`## Tech Stack
+
+${stackLines.join("\n")}`);
+  }
+  if (agent.conventions) {
+    sections.push(`## Coding Conventions
+
+${agent.conventions}`);
+  }
+  if (agent.reviewChecklist) {
+    sections.push(`## Review Checklist
+
+${agent.reviewChecklist}`);
+  }
+  if (agent.workflows.length) {
+    const wfLines = agent.workflows.map((wf) => {
+      const steps = wf.steps.map((s, i) => `${i + 1}. ${s}`).join("\n");
+      return `### ${wf.name}
+
+${wf.description}
+
+${steps}`;
+    }).join("\n\n");
+    sections.push(`## Workflows
+
+${wfLines}`);
+  }
+  if (agent.sharedKnowledge.length) {
+    const knowledge = agent.sharedKnowledge.filter(Boolean).join("\n\n---\n\n");
+    if (knowledge) {
+      sections.push(`## Project Knowledge
+
+${knowledge}`);
+    }
+  }
+  return sections.join("\n\n");
+}
+function assembleReference(ref) {
+  return ref.content;
+}
+
+export {
+  PLATFORMS,
+  TEAM_ROLES,
+  loadConfig,
+  configExists,
+  loadAgents,
+  assembleSkillIndex,
+  assembleAgentMarkdown,
+  assembleReference
+};