aigent-team 0.1.0 → 0.3.0

package/README.md

@@ -49,9 +49,10 @@ Each agent is a senior-level specialist (8+ years expertise) with deep knowledge
        └─────┘  └─────┘ └─────┘ └──────┘  └───────┘
 ```
 
-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.
+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.
 
 This keeps the always-loaded context slim while providing access to thousands of lines of senior expertise when needed.
 
@@ -80,13 +81,102 @@ Interactive wizard that:
 2. Lets you pick which team agents to enable
 3. Creates `aigent-team.config.json`
 
+> **Note:** `init` only creates the config file. Run `aigent-team generate` to generate platform configs.
+
 ### Generate
 
 ```bash
 npx aigent-team generate
 ```
 
-Generates agent configs for all configured platforms. Run this after changing your config or updating aigent-team.
+When run without flags, an interactive wizard lets you choose:
+- **Generate mode**: Platform configs or Plugin bundle
+- **Scopes**: Agents, Skills, References
+- **Team agents**: which roles to generate
+- **Target platforms**: which platforms to generate for
+
+You can also pass flags to skip the wizard:
+
+#### Scope filtering
+
+Generate only specific output types:
+
+```bash
+# Only agent skill index files (no references or skills)
+npx aigent-team generate --scope agents
+
+# Only executable skill files
+npx aigent-team generate --scope skills
+
+# Only reference docs
+npx aigent-team generate --scope references
+
+# Combine scopes
+npx aigent-team generate --scope agents,skills
+```
+
+#### Team filtering
+
+Override the config's `teams` array from the CLI:
+
+```bash
+# Generate only for FE and BE agents
+npx aigent-team generate --team fe,be
+
+# Combine with scope: only skills for QA
+npx aigent-team generate --scope skills --team qa
+```
+
+### Plugin system
+
+Create a self-contained plugin bundle:
+
+```bash
+# Generate plugin bundle
+npx aigent-team generate --scope plugin
+
+# Or select "Plugin bundle" in the interactive wizard
+npx aigent-team generate
+```
+
+This creates a `.aigent-team-plugin/` directory (configurable via `output.pluginDir`) with self-contained per-platform bundles:
+
+```
+.aigent-team-plugin/
+├── manifest.json              # Metadata: version, roles, platforms, agent info
+├── claude-code-plugin/        # Self-contained Claude Code bundle
+│   ├── rules/                 # Hub file (CLAUDE.md)
+│   ├── agents/                # Agent skill indexes
+│   ├── skills/{agent}/        # Executable skill files
+│   └── kb/                    # References + shared knowledge
+│       ├── {agent}/           # Per-agent reference docs
+│       └── shared/            # Shared knowledge files
+├── cursor-ide-plugin/         # Self-contained Cursor bundle
+│   ├── .cursor-plugin/        # Plugin manifest
+│   ├── rules/                 # Shared conventions
+│   ├── agents/                # Agent .mdc files
+│   ├── skills/                # Skill files
+│   └── kb/                    # References
+└── ...                        # Other platform bundles
+```
+
+Each platform bundle is fully self-contained — all agents, skills, references, and shared knowledge are inside. Users can distribute or install any bundle independently.
+
+Install a plugin into a project:
+
+```bash
+# Install plugin — converts to platform-native formats
+npx aigent-team install ./path/to/plugin
+
+# Install for specific platform only
+npx aigent-team install ./plugin --platform cursor
+
+# Overwrite existing files
+npx aigent-team install ./plugin --force
+
+# Uninstall — removes all files installed by the plugin
+npx aigent-team uninstall my-plugin-name
+```
 
 ### Validate
 
@@ -131,6 +221,7 @@ Create `aigent-team.config.json` (or `.ts` / `.js`) in your project root:
 | `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` |
+| `output.pluginDir` | `string` | No | Plugin output directory (default: `.aigent-team-plugin/`) |
 
 ### Programmatic config
 
@@ -152,11 +243,15 @@ export default defineConfig({
 });
 ```
 
-### Platform-specific flags
+### CLI flags
 
 ```bash
-# Generate only for a specific platform
-npx aigent-team generate --platform claude-code
+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 install ./plugin --force           # Install plugin
+npx aigent-team uninstall my-app                   # Remove plugin
 ```
 
 ## Generated output
@@ -165,40 +260,113 @@ 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/
+.claude/agents/fe-agent.md               # Rules + skill index (always loaded)
+.claude/agents/fe-agent/references/       # Deep reference docs
   ├── component-architecture.md
   ├── state-management.md
-  ├── performance.md
-  ├── accessibility.md
-  ├── security.md
-  ├── testing.md
-  ├── css-styling.md
-  ├── forms.md
-  └── review-checklist.md
-...
+  └── ...
+.claude/agents/fe-agent/skills/           # Executable procedures
+  ├── analyze-bundle.md
+  └── component-audit.md
 CLAUDE.md                                 # Agent team overview
 
 # Cursor
-.cursor/rules/fe-agent.mdc               # Glob-scoped skill
+.cursor/rules/fe-agent.mdc               # Glob-scoped skill (includes rules)
 .cursor/rules/fe-refs/                    # Glob-scoped references
-...
+.cursor/rules/fe-skills/                  # Glob-scoped skills
 
 # Codex
 AGENTS.md                                 # Combined agent doc
 .codex/agents/fe-agent.md                 # Individual agent
 .codex/agents/fe-agent/references/        # References
-...
+.codex/agents/fe-agent/skills/            # Skills
 
 # Antigravity
 GEMINI.md                                 # Agent overview
 .agents/skills/fe-agent/SKILL.md          # Skill file
 .agents/skills/fe-agent/references/       # References
-...
+.agents/skills/fe-agent/skills/           # Skills
 ```
 
+## How agents are loaded by each platform
+
+After `aigent-team generate`, the files are placed in each platform's expected directories. Here's how each AI tool discovers and uses them:
+
+### Claude Code
+
+Files in `.claude/agents/` are **automatically available** as specialized agents. Claude Code discovers them on startup.
+
+**How to use:**
+```
+# In Claude Code, just ask — it will pick the right agent based on the task
+> Review this React component for accessibility issues
+  → Claude spawns fe-agent, which reads references/accessibility.md
+
+# Or explicitly request an agent
+> Use the fe-agent to review my frontend code
+> Ask the qa-agent to write E2E tests for this feature
+
+# The Lead agent can orchestrate multiple agents
+> Implement the user registration feature
+  → Lead analyzes → spawns BA (specs) → FE + BE (code) → QA (tests)
+```
+
+`CLAUDE.md` is loaded as project context automatically — it tells Claude which agents are available.
+
+### Cursor
+
+Files in `.cursor/rules/` are **loaded automatically** based on frontmatter settings:
+- `alwaysApply: true` → always active (Lead, BA agents)
+- `globs: "**/*.tsx, **/*.ts"` → activated when you open matching files
+
+**How it works:** When you open a `.tsx` file, Cursor loads `fe-agent.mdc` automatically. The agent's knowledge applies to Cursor's suggestions, completions, and chat responses. Reference files in `fe-refs/` are also glob-scoped and loaded when relevant.
+
+No manual action needed — just open files and use Cursor as normal.
+
+### Codex (OpenAI)
+
+`AGENTS.md` is **read automatically** as the project instruction file. Individual agents in `.codex/agents/` are available as subagents.
+
+**How to use:**
+```
+# Codex reads AGENTS.md on startup for project context
+# Use subagents in conversations:
+> @fe-agent review this component
+> @devops-agent check my Dockerfile
+```
+
+### Antigravity (Google)
+
+`GEMINI.md` is loaded as project context. Skills in `.agents/skills/` are **auto-discovered**.
+
+**How to use:**
+```
+# Antigravity loads skills from .agents/skills/ automatically
+# Reference the skill by name:
+> Use the fe-agent skill to review this code
+> Run the qa-agent skill to generate tests
+```
+
+### Reference files — on-demand loading
+
+Reference files are **not** loaded into context by default (that would bloat the context window). Instead:
+
+1. The **skill index** (always loaded) contains a table of available references
+2. When the agent encounters a relevant task, it **reads the reference file** on-demand
+3. Example: FE agent working on forms → reads `references/forms.md` for validation patterns
+
+This is why the skill index includes a "When to read" table:
+
+```markdown
+| Reference | When to read |
+|-----------|-------------|
+| component-architecture.md | Creating or reviewing components |
+| state-management.md | Choosing state solution |
+| performance.md | Optimizing or auditing performance |
+```
+
+The agent decides which references to load based on the task — you don't need to do anything manually.
+
 ## 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:
@@ -238,6 +406,18 @@ The Lead agent acts as orchestrator. When it receives a task, it:
 
 This mirrors how a real tech lead operates — delegating to specialists and ensuring alignment.
 
+## Documentation
+
+| Document | Description |
+|---|---|
+| [Docs Index](docs/INDEX.md) | Entry point for all documentation, version history, RFC tracker |
+| [Architecture](docs/base/architecture.md) | System design, data flow, module map, compiler pattern |
+| [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 |
+| [Contributing](CONTRIBUTING.md) | Development setup, how to add agents/compilers |
+| [Changelog](CHANGELOG.md) | Release history |
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

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

@@ -4,6 +4,13 @@ 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 PLUGIN_BUNDLE_DIRS = {
+  "claude-code": "claude-code-plugin",
+  cursor: "cursor-ide-plugin",
+  codex: "codex-plugin",
+  antigravity: "antigravity-plugin"
+};
 var TechStackSchema = z.object({
   languages: z.array(z.string()).optional(),
   frameworks: z.array(z.string()).optional(),
@@ -21,6 +28,7 @@ var AgentOverrideSchema = z.object({
     allowed: z.array(z.string()).optional(),
     denied: z.array(z.string()).optional()
   }).optional(),
+  rules: z.string().optional(),
   globs: z.array(z.string()).optional()
 });
 var ConfigSchema = z.object({
@@ -34,7 +42,8 @@ var ConfigSchema = z.object({
     architecture: z.string().optional()
   }).optional(),
   output: z.object({
-    directory: z.string().optional()
+    directory: z.string().optional(),
+    pluginDir: z.string().optional()
   }).optional()
 });
 
@@ -112,6 +121,23 @@ function loadReferences(refsDir) {
   }
   return refs;
 }
+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 id = file.replace(".md", "");
+    skills.push({
+      id,
+      name: id.replace(/-/g, " "),
+      description: "",
+      trigger: "",
+      content
+    });
+  }
+  return skills;
+}
 function loadBuiltinAgent(role) {
   const teamDir = resolve2(TEMPLATES_DIR, "teams", role);
   const agentYaml = readFileSync2(resolve2(teamDir, "agent.yaml"), "utf-8");
@@ -120,6 +146,8 @@ function loadBuiltinAgent(role) {
   const conventions = readIfExists(resolve2(teamDir, "conventions.md"));
   const reviewChecklist = readIfExists(resolve2(teamDir, "review-checklist.md"));
   const references = loadReferences(resolve2(teamDir, "references"));
+  const rulesContent = readIfExists(resolve2(teamDir, "rules.md"));
+  const skills = loadSkills(resolve2(teamDir, "skills"));
   return {
     id: agentDef.id,
     name: agentDef.name,
@@ -134,6 +162,8 @@ function loadBuiltinAgent(role) {
     workflows: agentDef.workflows || [],
     sharedKnowledge: agentDef.sharedKnowledge || [],
     references,
+    rulesContent,
+    skills,
     globs: agentDef.globs || []
   };
 }
@@ -158,9 +188,14 @@ function loadAgents(config, cwd = process.cwd()) {
       if (override.conventions && existsSync2(resolve2(cwd, override.conventions))) {
         conventions = readFileSync2(resolve2(cwd, override.conventions), "utf-8").trim();
       }
+      let rulesContent = agent.rulesContent;
+      if (override.rules && existsSync2(resolve2(cwd, override.rules))) {
+        rulesContent = readFileSync2(resolve2(cwd, override.rules), "utf-8").trim();
+      }
       agent = deepmerge(agent, {
         ...override,
-        conventions
+        conventions,
+        rulesContent
       });
     }
     const localDir = resolve2(cwd, ".aigent-team", "teams", role);
@@ -171,10 +206,16 @@ function loadAgents(config, cwd = process.cwd()) {
       if (localConventions) agent.conventions = localConventions;
       if (localChecklist) agent.reviewChecklist = localChecklist;
       if (localSkill) agent.skillContent = localSkill;
+      const localRules = readIfExists(resolve2(localDir, "rules.md"));
+      if (localRules) agent.rulesContent = localRules;
       const localRefs = loadReferences(resolve2(localDir, "references"));
       if (localRefs.length) {
         agent.references = [...agent.references, ...localRefs];
       }
+      const localSkills = loadSkills(resolve2(localDir, "skills"));
+      if (localSkills.length) {
+        agent.skills = [...agent.skills, ...localSkills];
+      }
     }
     const resolvedShared = [];
     for (const ref of agent.sharedKnowledge) {
@@ -194,10 +235,30 @@ function loadAgents(config, cwd = process.cwd()) {
 
 // src/core/template-engine.ts
 function assembleSkillIndex(agent) {
+  const parts = [];
+  if (agent.rulesContent) {
+    parts.push(agent.rulesContent);
+  }
   if (agent.skillContent) {
-    return agent.skillContent;
+    parts.push(agent.skillContent);
+  } else {
+    parts.push(assembleAgentMarkdown(agent));
   }
-  return assembleAgentMarkdown(agent);
+  if (agent.skills?.length) {
+    const skillLines = agent.skills.map(
+      (s) => `| \`${s.id}\` | ${s.name} |`
+    );
+    parts.push([
+      "## Executable Skills",
+      "",
+      "Load the relevant skill file when performing these procedures:",
+      "",
+      "| Skill | Name |",
+      "|-------|------|",
+      ...skillLines
+    ].join("\n"));
+  }
+  return parts.join("\n\n");
 }
 function assembleAgentMarkdown(agent) {
   const sections = [];
@@ -254,14 +315,20 @@ ${knowledge}`);
 function assembleReference(ref) {
   return ref.content;
 }
+function assembleSkill(skill) {
+  return skill.content;
+}
 
 export {
   PLATFORMS,
   TEAM_ROLES,
+  GENERATE_SCOPES,
+  PLUGIN_BUNDLE_DIRS,
   loadConfig,
   configExists,
   loadAgents,
   assembleSkillIndex,
   assembleAgentMarkdown,
-  assembleReference
+  assembleReference,
+  assembleSkill
 };