aigent-team 0.1.0 → 0.2.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.
 
@@ -165,40 +166,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 +312,16 @@ 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 |
+|---|---|
+| [Architecture](docs/architecture.md) | System design, data flow, module map, compiler pattern |
+| [Agent Reference](docs/agents.md) | All 6 agents — roles, capabilities, reference file catalog |
+| [Vision & Roadmap](docs/vision.md) | Future plans, design principles, platform expansion |
+| [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-U3NGK2UZ.js}

@@ -21,6 +21,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({
@@ -112,6 +113,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 +138,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 +154,8 @@ function loadBuiltinAgent(role) {
     workflows: agentDef.workflows || [],
     sharedKnowledge: agentDef.sharedKnowledge || [],
     references,
+    rulesContent,
+    skills,
     globs: agentDef.globs || []
   };
 }
@@ -158,9 +180,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 +198,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 +227,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,6 +307,9 @@ ${knowledge}`);
 function assembleReference(ref) {
   return ref.content;
 }
+function assembleSkill(skill) {
+  return skill.content;
+}
 
 export {
   PLATFORMS,
@@ -263,5 +319,6 @@ export {
   loadAgents,
   assembleSkillIndex,
   assembleAgentMarkdown,
-  assembleReference
+  assembleReference,
+  assembleSkill
 };

package/dist/cli.js

@@ -3,11 +3,12 @@ import { createRequire } from 'module'; const require = createRequire(import.met
 import {
   PLATFORMS,
   assembleReference,
+  assembleSkill,
   assembleSkillIndex,
   configExists,
   loadAgents,
   loadConfig
-} from "./chunk-N3RYHWTR.js";
+} from "./chunk-U3NGK2UZ.js";
 
 // bin/cli.ts
 import { Command } from "commander";
@@ -83,6 +84,18 @@ var BaseCompiler = class {
       overwriteStrategy: "replace"
     }));
   }
+  /**
+   * Compile skill files for an agent into a given directory.
+   * Returns CompiledOutput[] for each skill file.
+   */
+  compileSkills(agent, baseDir, extension = ".md") {
+    if (!agent.skills?.length) return [];
+    return agent.skills.map((skill) => ({
+      filePath: `${baseDir}/${skill.id}${extension}`,
+      content: assembleSkill(skill) + "\n",
+      overwriteStrategy: "replace"
+    }));
+  }
   formatFrontmatter(data) {
     const lines = ["---"];
     for (const [key, value] of Object.entries(data)) {
@@ -127,6 +140,11 @@ ${body}
         `.claude/agents/${agent.id}-agent/references`
       );
       outputs.push(...refs);
+      const skills = this.compileSkills(
+        agent,
+        `.claude/agents/${agent.id}-agent/skills`
+      );
+      outputs.push(...skills);
     }
     const agentList = agents.map((a) => `- **${a.name}** (\`${a.id}\`): ${a.description.trim().split("\n")[0]}`).join("\n");
     const claudeMd = [
@@ -154,7 +172,7 @@ ${body}
     const errors = [];
     const warnings = [];
     for (const output of outputs) {
-      if (output.filePath.includes("/references/")) continue;
+      if (output.filePath.includes("/references/") || output.filePath.includes("/skills/")) continue;
       const lineCount = output.content.split("\n").length;
       if (lineCount > 300) {
         warnings.push(
@@ -203,6 +221,23 @@ ${body}
             content: `${refFrontmatter}
 
 ${ref.content}
+`,
+            overwriteStrategy: "replace"
+          });
+        }
+      }
+      if (agent.skills?.length) {
+        for (const skill of agent.skills) {
+          const skillFrontmatter = this.formatFrontmatter({
+            description: `${agent.name} skill: ${skill.name}`,
+            alwaysApply: false,
+            globs: globs || void 0
+          });
+          outputs.push({
+            filePath: `.cursor/rules/${agent.id}-skills/${skill.id}.mdc`,
+            content: `${skillFrontmatter}
+
+${skill.content}
 `,
             overwriteStrategy: "replace"
           });
@@ -289,6 +324,11 @@ ${body}
         `.codex/agents/${agent.id}-agent/references`
       );
       outputs.push(...refs);
+      const skills = this.compileSkills(
+        agent,
+        `.codex/agents/${agent.id}-agent/skills`
+      );
+      outputs.push(...skills);
     }
     return outputs;
   }
@@ -355,6 +395,11 @@ ${body}
         `.agents/skills/${agent.id}-agent/references`
       );
       outputs.push(...refs);
+      const skills = this.compileSkills(
+        agent,
+        `.agents/skills/${agent.id}-agent/skills`
+      );
+      outputs.push(...skills);
     }
     return outputs;
   }

package/dist/index.d.ts

@@ -11,6 +11,13 @@ interface ReferenceFile {
     whenToRead: string;
     content: string;
 }
+interface SkillFile {
+    id: string;
+    name: string;
+    description: string;
+    trigger: string;
+    content: string;
+}
 interface TechStackConfig {
     languages: string[];
     frameworks: string[];
@@ -40,6 +47,8 @@ interface AgentDefinition {
     workflows: WorkflowDefinition[];
     sharedKnowledge: string[];
     references: ReferenceFile[];
+    rulesContent: string;
+    skills: SkillFile[];
     globs?: string[];
 }
 declare const ConfigSchema: z.ZodObject<{
@@ -78,6 +87,7 @@ declare const ConfigSchema: z.ZodObject<{
             allowed?: string[] | undefined;
             denied?: string[] | undefined;
         }>>;
+        rules: z.ZodOptional<z.ZodString>;
         globs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         name?: string | undefined;
@@ -95,6 +105,7 @@ declare const ConfigSchema: z.ZodObject<{
             allowed?: string[] | undefined;
             denied?: string[] | undefined;
         } | undefined;
+        rules?: string | undefined;
         globs?: string[] | undefined;
     }, {
         name?: string | undefined;
@@ -112,6 +123,7 @@ declare const ConfigSchema: z.ZodObject<{
             allowed?: string[] | undefined;
             denied?: string[] | undefined;
         } | undefined;
+        rules?: string | undefined;
         globs?: string[] | undefined;
     }>>>;
     shared: z.ZodOptional<z.ZodObject<{
@@ -154,6 +166,7 @@ declare const ConfigSchema: z.ZodObject<{
             allowed?: string[] | undefined;
             denied?: string[] | undefined;
         } | undefined;
+        rules?: string | undefined;
         globs?: string[] | undefined;
     }>> | undefined;
     shared?: {
@@ -184,6 +197,7 @@ declare const ConfigSchema: z.ZodObject<{
             allowed?: string[] | undefined;
             denied?: string[] | undefined;
         } | undefined;
+        rules?: string | undefined;
         globs?: string[] | undefined;
     }>> | undefined;
     shared?: {

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   configExists,
   loadAgents,
   loadConfig
-} from "./chunk-N3RYHWTR.js";
+} from "./chunk-U3NGK2UZ.js";
 
 // src/index.ts
 function defineConfig(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aigent-team",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cross-platform AI agent team plugin for Claude Code, Cursor, Codex, and Antigravity",
   "type": "module",
   "main": "./dist/index.js",

package/templates/teams/ba/rules.md

@@ -0,0 +1,26 @@
+# Rules (Hard Constraints)
+
+## Scope Rules
+- **DO NOT** modify source code, test files, or infrastructure configs
+- **DO NOT** make implementation decisions — define the "what", not the "how"
+- You may read any file to understand current behavior, but only produce specifications and documentation
+
+## Action Rules
+- **NEVER** write acceptance criteria without Given/When/Then format
+- **NEVER** approve a requirement that has no measurable acceptance criteria
+- **NEVER** assume missing requirements — ask for clarification instead
+- **DO NOT** specify technical implementation details (database schemas, API frameworks, UI libraries)
+- **DO NOT** skip edge cases — every user story must address error scenarios and boundary conditions
+
+## Escalation Rules — Stop and Ask
+- Conflicting requirements from different stakeholders
+- Requirement that contradicts existing system behavior
+- Missing stakeholder input needed to proceed
+- Scope creep detected: requirement is growing beyond the original intent
+- Non-functional requirement (performance, security) that needs specialist input
+
+## Output Rules
+- Every user story must follow: "As a [role], I want [action], so that [benefit]"
+- Every acceptance criterion must follow Given/When/Then format
+- API contracts must specify request/response schemas, status codes, and error formats
+- All stories must be estimated for complexity before implementation begins

package/templates/teams/ba/skills/requirement-validation.md

@@ -0,0 +1,42 @@
+# Skill: Requirement Validation
+
+**Trigger**: When validating that requirements are complete, consistent, and implementable before development starts.
+
+## Steps
+
+1. **Completeness check** — For each requirement:
+   - Is the "who" defined? (which user persona)
+   - Is the "what" specific? (observable behavior, not vague goals)
+   - Is the "why" stated? (business value or user need)
+   - Are error scenarios covered? (what happens when things go wrong)
+   - Are boundary conditions defined? (limits, edge cases, empty states)
+
+2. **Consistency check** — Across all requirements:
+   - Do any requirements contradict each other?
+   - Are terms used consistently? (same entity name everywhere)
+   - Do data types and formats match between related requirements?
+   - Are permissions/roles consistent across features?
+
+3. **Feasibility check** — With the technical team:
+   - Can each requirement be implemented within the current architecture?
+   - Are there technical constraints that limit the requirement?
+   - Are third-party dependencies available and reliable?
+   - Is the performance target achievable with current infrastructure?
+
+4. **Testability check** — For each acceptance criterion:
+   - Can it be verified automatically?
+   - Is the expected result measurable and unambiguous?
+   - Is the precondition reproducible in a test environment?
+
+5. **Gap analysis** — Identify what's missing:
+   - Non-functional requirements (performance, security, accessibility)
+   - Error handling and recovery flows
+   - Data migration needs (if changing existing behavior)
+   - Internationalization / localization considerations
+
+## Expected Output
+
+- Validation report: pass/fail per requirement
+- List of gaps and missing requirements
+- Contradictions or ambiguities found
+- Questions for stakeholders to resolve before development

package/templates/teams/ba/skills/story-decomposition.md

@@ -0,0 +1,47 @@
+# Skill: Story Decomposition
+
+**Trigger**: When breaking an epic or large feature into implementable user stories.
+
+## Steps
+
+1. **Understand the epic**:
+   - What is the business goal?
+   - Who are the users/personas involved?
+   - What is the scope boundary? (what's in, what's explicitly out)
+
+2. **Identify user workflows**:
+   - Map the primary user journey (happy path)
+   - Map alternative paths (edge cases, error scenarios)
+   - Map admin/system workflows (background jobs, notifications)
+
+3. **Slice vertically** — Each story should deliver user-visible value:
+   - **Bad**: "Create database schema", "Build API", "Build UI" (horizontal slices)
+   - **Good**: "User can register with email", "User can reset password" (vertical slices)
+   - Each story should be independently deployable and testable
+
+4. **Apply INVEST criteria** to each story:
+   - **I**ndependent: can be developed without other stories
+   - **N**egotiable: details can be discussed
+   - **V**aluable: delivers value to user or business
+   - **E**stimable: team can estimate the effort
+   - **S**mall: fits in one sprint (ideally 1-3 days of work)
+   - **T**estable: has clear acceptance criteria
+
+5. **Write acceptance criteria** for each story:
+   ```
+   Given [precondition]
+   When [action]
+   Then [expected result]
+   ```
+
+6. **Define dependencies and order**:
+   - Which stories must be done first?
+   - Which can be parallelized?
+   - Where are the integration points between FE/BE?
+
+## Expected Output
+
+- List of user stories with title, description, and acceptance criteria
+- Dependency graph showing implementation order
+- Estimation notes (complexity, unknowns, risks)
+- API contract drafts for stories involving FE+BE integration

package/templates/teams/be/rules.md

@@ -0,0 +1,28 @@
+# Rules (Hard Constraints)
+
+## Scope Rules
+- **DO NOT** modify frontend files (components, styles, client-side state, UI tests)
+- **DO NOT** modify infrastructure files (Dockerfile, K8s manifests, CI/CD pipelines) unless the task explicitly requires it
+- **DO NOT** modify database schemas or run migrations without explicit approval
+- You may read any file for context, but only write backend code and tests
+
+## Action Rules
+- **NEVER** log PII (emails, passwords, tokens, IP addresses) — use structured logging with redaction
+- **NEVER** write raw SQL without parameterized queries — no string concatenation for queries
+- **NEVER** catch exceptions and return HTTP 200 — use proper error status codes
+- **NEVER** store secrets in code, config files, or environment variable defaults
+- **DO NOT** add new service dependencies (Redis, queues, external APIs) without stating the reason
+- **DO NOT** bypass the repository/service layer to access the database directly from controllers
+
+## Escalation Rules — Stop and Ask
+- Database migration that alters or drops existing columns — requires explicit approval
+- New external API dependency or third-party service integration
+- Breaking change to an API contract that frontend consumes
+- Performance concern: query estimated to scan > 10K rows without index
+- Security decision: authentication/authorization flow changes
+
+## Output Rules
+- Every new API endpoint must have request/response validation (Zod, Joi, or equivalent)
+- Every database query must have a LIMIT or pagination — no unbounded queries
+- Error responses must follow a consistent format: `{ error: string, code: string, details?: unknown }`
+- All async operations must have timeout and retry configuration

package/templates/teams/be/skills/api-load-test.md

@@ -0,0 +1,45 @@
+# Skill: API Load Test
+
+**Trigger**: When validating endpoint performance under load, before a release with traffic expectations, or investigating latency issues.
+
+## Steps
+
+1. **Identify target endpoints** — Focus on:
+   - High-traffic endpoints (homepage, search, API gateways)
+   - Endpoints with database queries (list, search, aggregation)
+   - Endpoints with external dependencies (third-party APIs, file uploads)
+
+2. **Define load profile**:
+   - Expected concurrent users
+   - Requests per second target
+   - Ramp-up period
+   - Test duration (minimum 5 minutes for stable results)
+
+3. **Run load test**:
+   ```bash
+   # Using k6
+   k6 run --vus 50 --duration 5m load-test.js
+   # Using autocannon
+   npx autocannon -c 50 -d 300 http://localhost:3000/api/endpoint
+   # Using hey
+   hey -n 10000 -c 50 http://localhost:3000/api/endpoint
+   ```
+
+4. **Collect metrics** — Measure during the test:
+   - Response time: p50, p95, p99
+   - Throughput: requests/second
+   - Error rate: 4xx, 5xx percentage
+   - Resource usage: CPU, memory, DB connections, open file descriptors
+
+5. **Analyze results**:
+   - Compare against SLA targets (e.g., p95 < 200ms)
+   - Identify bottlenecks (slow queries, connection pool exhaustion, CPU saturation)
+   - Check for memory leaks (growing memory over test duration)
+
+6. **Document findings** — Record baseline for future comparison
+
+## Expected Output
+
+- Performance summary table (p50, p95, p99, throughput, error rate)
+- Identified bottlenecks with specific recommendations
+- Baseline metrics for regression tracking

package/templates/teams/be/skills/database-migration.md

@@ -0,0 +1,50 @@
+# Skill: Database Migration
+
+**Trigger**: When schema changes are needed — new tables, column changes, index additions, or data migrations.
+
+## Steps
+
+1. **Assess impact** — Before writing the migration:
+   - Which tables are affected?
+   - Is this additive (safe) or destructive (column drop, type change)?
+   - Estimate rows affected and lock duration
+   - Does this require backfill of existing data?
+
+2. **Generate migration file**:
+   ```bash
+   # Prisma
+   npx prisma migrate dev --name descriptive_name
+   # Knex
+   npx knex migrate:make descriptive_name
+   # TypeORM
+   npx typeorm migration:generate -n DescriptiveName
+   ```
+
+3. **Write migration** — Follow these rules:
+   - Additive changes first (add column with default), destructive changes in a later migration
+   - Always include a `down()` / rollback function
+   - Add indexes in a separate migration with `CONCURRENTLY` if supported
+   - For large tables (>1M rows), use batched updates instead of single ALTER
+
+4. **Test locally**:
+   ```bash
+   # Apply migration
+   npx prisma migrate dev   # or equivalent
+   # Verify schema
+   npx prisma db pull --print
+   # Test rollback
+   npx prisma migrate reset  # on dev only
+   ```
+
+5. **Validate** — After migration:
+   - All existing queries still work
+   - New columns have appropriate defaults or are nullable
+   - Indexes are used (check EXPLAIN on key queries)
+   - Application code handles both old and new schema during deployment window
+
+## Expected Output
+
+- Migration file with up/down functions
+- Impact assessment (tables affected, estimated lock time, data volume)
+- Rollback procedure
+- Verification queries

package/templates/teams/devops/rules.md

@@ -0,0 +1,28 @@
+# Rules (Hard Constraints)
+
+## Scope Rules
+- **DO NOT** modify application business logic (controllers, services, models, UI components)
+- **DO NOT** modify test files unless they are infrastructure/deployment tests
+- You may read any file for context, but only write infrastructure, CI/CD, and deployment configs
+
+## Action Rules
+- **NEVER** store secrets in plaintext — use secret managers (Vault, AWS Secrets Manager, etc.)
+- **NEVER** use `:latest` tags in production container images — always pin specific versions
+- **NEVER** run containers as root in production — use non-root users
+- **NEVER** use `kubectl exec` in production as a fix — create a proper deployment
+- **NEVER** force-push to main/master or delete protected branches
+- **DO NOT** make infrastructure changes without idempotency — every apply must be safe to re-run
+
+## Escalation Rules — Stop and Ask
+- Production incident — alert immediately, don't attempt silent fixes
+- Cost increase > 20% from infrastructure changes
+- Security group or firewall rule change that opens new ports to public
+- Database backup/restore operations in production
+- Certificate rotation or DNS changes that could cause downtime
+
+## Output Rules
+- All IaC must be idempotent — `terraform apply` or equivalent must be safe to run multiple times
+- Every deployment must have a rollback procedure documented
+- Container images must have health checks defined
+- CI/CD pipelines must not have hardcoded secrets — use pipeline variables or secret refs
+- Monitoring alerts must have runbook links

package/templates/teams/devops/skills/health-check.md

@@ -0,0 +1,61 @@
+# Skill: Health Check Verification
+
+**Trigger**: When verifying service health after deployment, setting up monitoring, or debugging availability issues.
+
+## Steps
+
+1. **Check application health endpoints**:
+   ```bash
+   # Basic health
+   curl -sf http://localhost:3000/health | jq .
+   # Detailed health (with dependency checks)
+   curl -sf http://localhost:3000/health/ready | jq .
+   # Liveness probe
+   curl -sf http://localhost:3000/health/live | jq .
+   ```
+
+2. **Verify dependency connectivity**:
+   ```bash
+   # Database
+   curl -sf http://localhost:3000/health/ready | jq '.checks.database'
+   # Redis/Cache
+   curl -sf http://localhost:3000/health/ready | jq '.checks.cache'
+   # External APIs
+   curl -sf http://localhost:3000/health/ready | jq '.checks.external'
+   ```
+
+3. **Check container/pod status**:
+   ```bash
+   # Docker
+   docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
+   # Kubernetes
+   kubectl get pods -l app=service-name -o wide
+   kubectl describe pod <pod-name> | grep -A5 "Conditions"
+   ```
+
+4. **Verify resource usage**:
+   ```bash
+   # Container resources
+   docker stats --no-stream
+   # K8s resources
+   kubectl top pods -l app=service-name
+   # Check for OOM kills
+   kubectl get events --field-selector reason=OOMKilling
+   ```
+
+5. **Validate traffic flow**:
+   - Check load balancer targets are healthy
+   - Verify DNS resolution points to correct endpoints
+   - Confirm TLS certificates are valid and not near expiry
+
+6. **Smoke test critical paths**:
+   - Authentication endpoint responds with 200
+   - Key API endpoints return expected data shapes
+   - Static assets are served with correct cache headers
+
+## Expected Output
+
+- Health status summary (all services green/red)
+- Dependency connectivity matrix
+- Resource usage snapshot
+- List of any failing checks with remediation steps

package/templates/teams/devops/skills/rollback-procedure.md

@@ -0,0 +1,56 @@
+# Skill: Rollback Procedure
+
+**Trigger**: When a deployment needs to be reverted due to errors, performance regression, or unexpected behavior in production.
+
+## Steps
+
+1. **Assess the situation**:
+   - What symptoms are observed? (errors, latency, data corruption)
+   - When did the issue start? (correlate with deployment time)
+   - What was deployed? (commit hash, image tag, config changes)
+   - Is this a full outage or degraded service?
+
+2. **Decide rollback strategy**:
+   - **Application rollback**: revert to previous container image/build
+   - **Database rollback**: run down-migration (only if migration was part of deploy)
+   - **Config rollback**: revert environment variables or feature flags
+   - **Infrastructure rollback**: revert IaC changes via previous state
+
+3. **Execute application rollback**:
+   ```bash
+   # Kubernetes
+   kubectl rollout undo deployment/service-name
+   kubectl rollout status deployment/service-name
+
+   # Docker Compose
+   docker compose up -d --no-build  # with previous image tag in .env
+
+   # AWS ECS
+   aws ecs update-service --cluster prod --service service-name --task-definition service-name:PREVIOUS_VERSION
+   ```
+
+4. **Verify rollback succeeded**:
+   - Run health checks (use health-check skill)
+   - Check error rates in monitoring dashboard
+   - Verify the previous version is running:
+     ```bash
+     kubectl get deployment service-name -o jsonpath='{.spec.template.spec.containers[0].image}'
+     ```
+
+5. **Communicate status**:
+   - Notify stakeholders: rollback completed, service restored
+   - Create incident ticket with timeline
+   - Document: what was deployed, what broke, what was rolled back
+
+6. **Post-rollback**:
+   - Do NOT re-deploy the broken version
+   - Root cause analysis before next attempt
+   - Add test coverage for the failure scenario
+   - Update deployment checklist if a step was missed
+
+## Expected Output
+
+- Confirmation that previous version is running
+- Health check results showing service is healthy
+- Incident timeline documentation
+- Root cause investigation action items

package/templates/teams/fe/rules.md

@@ -0,0 +1,28 @@
+# Rules (Hard Constraints)
+
+## Scope Rules
+- **DO NOT** modify backend files (API routes, database models, migrations, server configs)
+- **DO NOT** modify infrastructure files (Dockerfile, K8s manifests, CI/CD pipelines)
+- **DO NOT** modify files outside your glob patterns unless explicitly instructed
+- You may read any file for context, but only write frontend code and tests
+
+## Action Rules
+- **NEVER** add new npm dependencies without stating the reason and bundle size impact
+- **NEVER** disable ESLint rules, TypeScript strict checks, or accessibility linting
+- **NEVER** use `any`, `@ts-ignore`, or `as unknown as T` — find the correct type
+- **DO NOT** refactor code outside the scope of the current task
+- **DO NOT** add features, optimizations, or abstractions that weren't requested
+- **DO NOT** create utility files or helper functions for one-time use
+
+## Escalation Rules — Stop and Ask
+- API contract doesn't match what the backend provides — escalate to Lead
+- Accessibility requirement is unclear or conflicts with design — escalate to Lead
+- Performance budget would be exceeded (component > 50KB, page LCP > 2.5s)
+- Breaking change needed to a shared component used by other features
+- Need to introduce a new state management pattern not already in the codebase
+
+## Output Rules
+- Components must not exceed 300 lines — split if larger
+- Every interactive element must have keyboard navigation and ARIA attributes
+- No barrel file re-exports (`index.ts`) in new code
+- Tests must use `getByRole`/`getByLabelText`, not `getByTestId`

package/templates/teams/fe/skills/analyze-bundle.md

@@ -0,0 +1,42 @@
+# Skill: Analyze Bundle Size
+
+**Trigger**: When adding new dependencies, investigating slow page loads, or performing a performance audit.
+
+## Steps
+
+1. **Check current bundle** — Run the project's build with analysis:
+   ```bash
+   # Next.js
+   ANALYZE=true npx next build
+   # Vite
+   npx vite build --report
+   # Webpack
+   npx webpack-bundle-analyzer dist/stats.json
+   ```
+
+2. **Identify large dependencies** — Look for packages > 50KB gzipped:
+   ```bash
+   npx source-map-explorer dist/**/*.js --json | jq '.results[] | select(.totalBytes > 51200)'
+   ```
+
+3. **Check for duplicates** — Multiple versions of the same package:
+   ```bash
+   npx depcheck
+   npm ls --all | grep -E "deduped|invalid"
+   ```
+
+4. **Evaluate alternatives** — For each large dependency:
+   - Can it be lazy-loaded with `dynamic()` or `React.lazy()`?
+   - Is there a lighter alternative (e.g., `date-fns` vs `moment`)?
+   - Can tree-shaking be improved by changing import style?
+
+5. **Measure impact** — Compare before/after:
+   - Total JS transferred (gzipped)
+   - Largest chunk size
+   - Number of chunks
+
+## Expected Output
+
+- Table of top 10 largest dependencies with sizes
+- Specific recommendations (lazy-load, replace, tree-shake)
+- Before/after size comparison if changes were made

package/templates/teams/fe/skills/component-audit.md

@@ -0,0 +1,41 @@
+# Skill: Component Audit
+
+**Trigger**: When reviewing component library health, finding duplicates, or preparing for a design system migration.
+
+## Steps
+
+1. **Inventory components** — List all component files:
+   ```bash
+   find src/components -name "*.tsx" -o -name "*.jsx" | sort
+   ```
+
+2. **Check for duplicates** — Find components with similar names or functionality:
+   - Search for components with overlapping names (e.g., `Button`, `Btn`, `ActionButton`)
+   - Compare prop interfaces for similarity
+   - Check for copy-pasted components across feature directories
+
+3. **Measure usage** — For each component, count imports:
+   ```bash
+   grep -r "from.*ComponentName" src/ --include="*.tsx" --include="*.ts" | wc -l
+   ```
+
+4. **Assess quality** — For each component check:
+   - Has proper TypeScript props interface (no `any`)
+   - Has `ref` forwarding where appropriate
+   - Handles all visual states (loading, error, empty, disabled)
+   - Has ARIA attributes for interactive elements
+   - Has tests
+
+5. **Identify dead components** — Components with 0 imports (excluding entry points and stories)
+
+6. **Generate report** — Categorize components as:
+   - **Healthy**: typed, tested, accessible, used
+   - **Needs attention**: missing tests, missing a11y, or partial types
+   - **Candidate for removal**: unused or duplicated
+
+## Expected Output
+
+- Component inventory table (name, location, import count, quality score)
+- List of duplicate/overlapping components with merge recommendations
+- List of dead components safe to remove
+- Priority list of components needing quality improvements

package/templates/teams/lead/rules.md

@@ -0,0 +1,25 @@
+# Rules (Hard Constraints)
+
+## Scope Rules
+- **DO NOT** write implementation code directly — delegate to specialist agents (FE, BE, QA, DevOps)
+- **DO NOT** modify test files, infrastructure configs, or CI/CD pipelines — those belong to specialist agents
+- You may read any file for analysis, but only write planning/coordination artifacts
+
+## Action Rules
+- **NEVER** assign a task without providing the full context template (Task, Context, Scope, Constraints, Related, Acceptance criteria)
+- **NEVER** skip quality gates — every agent output must be reviewed before integration
+- **NEVER** merge or approve work that hasn't passed the Definition of Done
+- **DO NOT** parallelize dependent tasks — BA specs must be complete before FE/BE start coding
+- **DO NOT** spawn more than 3 agents simultaneously without explicit user approval
+
+## Escalation Rules — Stop and Ask
+- Scope change detected: new requirements emerged during implementation
+- Cross-team conflict: FE and BE disagree on API contract
+- Timeline risk: estimated effort exceeds what was planned
+- Ambiguous requirements: cannot determine acceptance criteria from available information
+- Security concern: any agent flags a potential vulnerability
+
+## Output Rules
+- Task assignments must use the structured context template, never free-form
+- Status updates at every milestone (spec done, implementation done, tests done, review done)
+- Every coordinated feature must have a dependency graph before work begins

package/templates/teams/lead/skills/parallel-orchestration.md

@@ -0,0 +1,46 @@
+# Skill: Parallel Agent Orchestration
+
+**Trigger**: When implementing a feature that requires multiple specialist agents working simultaneously.
+
+## Steps
+
+1. **Map the dependency graph**:
+   - List all subtasks and which agent owns each
+   - Identify dependencies: which tasks must complete before others can start
+   - Group independent tasks that can run in parallel
+   - Example:
+     ```
+     BA (specs) → [FE (UI) + BE (API)] → QA (integration tests) → DevOps (deploy config)
+     ```
+
+2. **Define the API contract first** (if FE + BE are both involved):
+   - Have BA produce the API contract specification
+   - Both FE and BE must acknowledge the contract before starting
+   - Contract includes: endpoints, request/response schemas, error codes, auth requirements
+
+3. **Spawn parallel agents with full context**:
+   - Each agent gets: task description, relevant specs, file scope, acceptance criteria
+   - Each agent gets: the API contract (if applicable)
+   - Each agent gets: constraints and deadlines
+
+4. **Monitor and coordinate**:
+   - Check agent outputs at each milestone
+   - If one agent's output changes the contract, pause and realign all affected agents
+   - Resolve conflicts immediately — don't let agents proceed on divergent assumptions
+
+5. **Integration checkpoint**:
+   - After parallel work completes, verify FE and BE outputs match the same contract
+   - Have QA write integration tests that exercise the full flow
+   - Run all unit tests from all agents together
+
+6. **Final review**:
+   - Review combined diff for consistency
+   - Verify no duplicate code or conflicting patterns across agent outputs
+   - Confirm all acceptance criteria are met
+
+## Expected Output
+
+- Dependency graph (which tasks depend on which)
+- Agent assignments with full context templates
+- Integration verification results
+- Combined review summary

package/templates/teams/lead/skills/sprint-review.md

@@ -0,0 +1,38 @@
+# Skill: Sprint Review
+
+**Trigger**: When reviewing completed work at the end of a sprint or milestone, assessing quality and completeness.
+
+## Steps
+
+1. **Gather deliverables** — Collect all outputs from the sprint:
+   - List all PRs merged or in review
+   - List all tasks completed and their acceptance criteria status
+   - Identify any tasks that were carried over (incomplete)
+
+2. **Quality assessment** — For each deliverable:
+   - Does it meet the acceptance criteria defined by BA?
+   - Has it passed code review by the relevant specialist agent?
+   - Are tests written and passing (unit, integration, E2E as appropriate)?
+   - Are there any open review comments or unresolved discussions?
+
+3. **Cross-team alignment check**:
+   - FE and BE APIs match — no mismatched contracts
+   - Shared components modified by one team don't break another
+   - Database changes are compatible with both current and previous app versions
+
+4. **Technical debt assessment**:
+   - Were any shortcuts taken that need follow-up tickets?
+   - Are there TODO comments that should be tracked?
+   - Were any rules or constraints violated with justification?
+
+5. **Produce sprint summary**:
+   - Completed: what was delivered and working
+   - Carried over: what wasn't finished and why
+   - Risks: what might cause issues in the next sprint
+   - Improvements: what went well, what should change
+
+## Expected Output
+
+- Sprint summary document with completed/carried/risks sections
+- Quality scorecard per deliverable
+- Follow-up tickets for technical debt or unfinished work

package/templates/teams/qa/rules.md

@@ -0,0 +1,27 @@
+# Rules (Hard Constraints)
+
+## Scope Rules
+- **DO NOT** modify production source code — only test files, test utilities, and test configuration
+- **DO NOT** modify infrastructure or deployment configs
+- You may read any source file to understand behavior, but only write test code
+
+## Action Rules
+- **NEVER** commit `.only` or `.skip` on tests — all tests must run in CI
+- **NEVER** use `sleep()` or fixed delays in tests — use explicit waits and polling
+- **NEVER** disable or delete existing tests without documenting the reason
+- **NEVER** mock what you can test against a real implementation (prefer integration over mocking)
+- **DO NOT** write tests that depend on execution order or shared mutable state
+- **DO NOT** assert on implementation details (internal state, private methods, CSS classes)
+
+## Escalation Rules — Stop and Ask
+- Test coverage would drop below the project threshold after changes
+- Flaky test requires infrastructure fix (timing, race condition, external dependency)
+- Cannot write meaningful test because the source code has no testable interface
+- Security test reveals an actual vulnerability — report immediately, don't just log it
+- Performance test shows regression > 20% from baseline
+
+## Output Rules
+- Every test must have a clear description that reads as a behavior specification
+- No empty test bodies or placeholder tests — every `it()` must assert something
+- Test data must be self-contained — no dependency on external fixtures or seed data that isn't in the test
+- E2E tests must clean up after themselves (created records, uploaded files, etc.)

package/templates/teams/qa/skills/flaky-test-diagnosis.md

@@ -0,0 +1,50 @@
+# Skill: Diagnose Flaky Test
+
+**Trigger**: When a test is intermittently failing in CI or locally, passing on retry but failing inconsistently.
+
+## Steps
+
+1. **Reproduce the flake** — Run the test in a loop to confirm:
+   ```bash
+   # Run 20 times, stop on first failure
+   for i in $(seq 1 20); do npx vitest run path/to/test.ts || break; done
+   # Or with Jest
+   npx jest --forceExit --runInBand path/to/test.ts --repeat=20
+   ```
+
+2. **Classify the flake** — Common root causes:
+   - **Timing**: test depends on setTimeout, animation frames, or network delays
+   - **Shared state**: tests modify global/module state that leaks between runs
+   - **Order dependency**: test passes alone but fails when run with others
+   - **Race condition**: async operations complete in unpredictable order
+   - **External dependency**: test hits a real API, database, or file system
+   - **Resource exhaustion**: port conflicts, file descriptor leaks, memory pressure
+
+3. **Isolate** — Narrow down the cause:
+   ```bash
+   # Run the failing test alone
+   npx vitest run --testNamePattern "specific test name"
+   # Run with the test before it
+   npx vitest run path/to/test.ts --sequence
+   # Check for shared state
+   npx vitest run --isolate path/to/test.ts
+   ```
+
+4. **Fix by category**:
+   - **Timing**: Replace `sleep()` with explicit waits (`waitFor`, `waitForElement`, polling)
+   - **Shared state**: Add proper `beforeEach`/`afterEach` cleanup, avoid global mutations
+   - **Order dependency**: Make each test fully self-contained with its own setup
+   - **Race condition**: Use proper async/await, avoid fire-and-forget promises
+   - **External dependency**: Mock the external service, use test containers for databases
+
+5. **Verify the fix** — Run the loop again to confirm stability:
+   ```bash
+   for i in $(seq 1 50); do npx vitest run path/to/test.ts || { echo "FAILED on run $i"; exit 1; }; done
+   echo "All 50 runs passed"
+   ```
+
+## Expected Output
+
+- Root cause classification (timing, shared state, race condition, etc.)
+- Specific fix applied with explanation
+- Verification that the test passes 50 consecutive runs

package/templates/teams/qa/skills/generate-test-data.md

@@ -0,0 +1,56 @@
+# Skill: Generate Test Data
+
+**Trigger**: When setting up test fixtures, creating seed data for E2E tests, or testing edge cases and boundary conditions.
+
+## Steps
+
+1. **Analyze data requirements**:
+   - Read the schema/types for entities involved
+   - Identify required fields, constraints (unique, foreign keys, enums)
+   - Identify edge cases: empty strings, max-length values, unicode, special characters
+
+2. **Create factory functions** — Use the project's factory pattern:
+   ```typescript
+   // Example with factory pattern
+   function createUser(overrides?: Partial<User>): User {
+     return {
+       id: crypto.randomUUID(),
+       name: `Test User ${Date.now()}`,
+       email: `test-${Date.now()}@example.com`,
+       role: 'user',
+       createdAt: new Date(),
+       ...overrides,
+     };
+   }
+   ```
+
+3. **Generate edge case data sets**:
+   - **Boundary values**: empty string, 1 char, max length
+   - **Unicode**: emoji, CJK characters, RTL text, zero-width characters
+   - **Numeric edges**: 0, -1, MAX_SAFE_INTEGER, NaN, Infinity
+   - **Date edges**: epoch, far future, timezone boundaries, DST transitions
+   - **Null/undefined**: every nullable field tested with null
+
+4. **Create relationship data** — For entities with foreign keys:
+   - Build parent entities before children
+   - Create both happy-path and orphan scenarios
+   - Test cascade delete/update behavior
+
+5. **Seed data for E2E**:
+   ```typescript
+   async function seedTestDatabase() {
+     const admin = await createUser({ role: 'admin' });
+     const users = await Promise.all(
+       Array.from({ length: 10 }, () => createUser())
+     );
+     // Create related entities...
+     return { admin, users };
+   }
+   ```
+
+## Expected Output
+
+- Factory functions for each entity involved
+- Edge case data sets organized by category
+- Seed script for E2E test environment
+- Cleanup function to reset test data after runs