@flitzrrr/agent-skills 1.0.3 → 1.2.0

package/bin/rebuild-symlinks.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Rebuilds all skill symlinks from vendor/ submodules.
+ *
+ * Each SKILL.md found in vendor/<source>/ gets a symlink in skills/ with the
+ * naming convention: <prefix>-<skill_name>
+ *
+ * Prefix mapping is defined explicitly for known sources, with a fallback
+ * to the first segment of the vendor directory name.
+ *
+ * Run: node bin/rebuild-symlinks.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const SKILLS_DIR = path.join(ROOT, "skills");
+const VENDOR_DIR = path.join(ROOT, "vendor");
+
+// Explicit prefix mapping: vendor directory name → skill prefix
+const PREFIX_MAP = {
+  "trailofbits-skills": "tob",
+  "anthropic-skills": "anthropic",
+  "anthropic-finance": "finance",
+  "vercel-agent-skills": "vercel",
+  "getsentry-skills": "sentry",
+  "google-stitch-skills": "google",
+  "cloudflare-skills": "cloudflare",
+  "stripe-skills": "stripe",
+  "expo-skills": "expo",
+  "hashicorp-skills": "hashicorp",
+  "supabase-skills": "supabase",
+  "callstack-skills": "callstack",
+  "scientific-skills": "scientific",
+  "opencode-processing-skills": "opencode",
+  "agentic-seo-skill": "seo",
+  "marketingskills": null, // no prefix, use skill name directly
+  "addyosmani-agent-skills": "addyosmani",
+  "itsmostafa-aws-agent-skills": "aws",
+  "MoizIbnYousaf-Ai-Agent-Skills": "MoizIbnYousaf",
+  "JackyST0-awesome-agent-skills": "JackyST0",
+};
+
+function getPrefix(vendorName) {
+  if (vendorName in PREFIX_MAP) return PREFIX_MAP[vendorName];
+  // Fallback: first segment before first hyphen
+  return vendorName.split("-")[0];
+}
+
+function findSkillMds(dir, maxDepth, results) {
+  if (maxDepth <= 0) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.name === ".git" || e.name === "node_modules") continue;
+    const full = path.join(dir, e.name);
+    if (e.isFile() && e.name.toLowerCase() === "skill.md") {
+      results.push(path.dirname(full));
+    } else if (e.isDirectory()) {
+      findSkillMds(full, maxDepth - 1, results);
+    }
+  }
+}
+
+function main() {
+  // Preserve manually-created skill directories (non-symlinks)
+  const manualSkills = new Set();
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const entry of fs.readdirSync(SKILLS_DIR)) {
+      const entryPath = path.join(SKILLS_DIR, entry);
+      const stat = fs.lstatSync(entryPath);
+      if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        manualSkills.add(entry);
+      }
+    }
+  }
+
+  // Remove all existing symlinks
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const entry of fs.readdirSync(SKILLS_DIR)) {
+      const entryPath = path.join(SKILLS_DIR, entry);
+      if (fs.lstatSync(entryPath).isSymbolicLink()) {
+        fs.unlinkSync(entryPath);
+      }
+    }
+  } else {
+    fs.mkdirSync(SKILLS_DIR);
+  }
+
+  let created = 0;
+  let skipped = 0;
+  const vendors = fs.readdirSync(VENDOR_DIR).filter((d) => {
+    const p = path.join(VENDOR_DIR, d);
+    return !d.startsWith(".") && fs.statSync(p).isDirectory();
+  });
+
+  for (const vendor of vendors) {
+    const vendorPath = path.join(VENDOR_DIR, vendor);
+    const prefix = getPrefix(vendor);
+    const skillDirs = [];
+    findSkillMds(vendorPath, 5, skillDirs);
+
+    // Special case: seo skill — single top-level link
+    if (vendor === "agentic-seo-skill") {
+      const linkName = "seo";
+      const target = `../vendor/${vendor}`;
+      if (!manualSkills.has(linkName)) {
+        fs.symlinkSync(target, path.join(SKILLS_DIR, linkName));
+        created++;
+      }
+      continue;
+    }
+
+    for (const skillDir of skillDirs) {
+      const skillName = path.basename(skillDir);
+      const linkName = prefix ? `${prefix}-${skillName}` : skillName;
+
+      // Don't overwrite manual skills
+      if (manualSkills.has(linkName)) {
+        skipped++;
+        continue;
+      }
+
+      // Relative path from skills/ to the skill directory
+      const relPath = path.relative(SKILLS_DIR, skillDir);
+      const target = `../vendor/${path.relative(VENDOR_DIR, skillDir)}`;
+
+      try {
+        // Check for name collisions
+        const linkPath = path.join(SKILLS_DIR, linkName);
+        if (fs.existsSync(linkPath) || fs.lstatSync(linkPath).isSymbolicLink()) {
+          // Already exists, skip
+          skipped++;
+          continue;
+        }
+      } catch {
+        // lstatSync throws if path doesn't exist — that's what we want
+      }
+
+      try {
+        fs.symlinkSync(target, path.join(SKILLS_DIR, linkName));
+        created++;
+      } catch (err) {
+        // Name collision from a different vendor
+        skipped++;
+      }
+    }
+  }
+
+  console.log(`Rebuilt symlinks: ${created} created, ${skipped} skipped (manual or collision)`);
+  console.log(`Manual skill dirs preserved: ${[...manualSkills].join(", ") || "(none)"}`);
+  console.log(`Total skills/ entries: ${fs.readdirSync(SKILLS_DIR).length}`);
+}
+
+main();

package/bin/sync-docs.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Regenerates README.md badges/counts, sources table, repo structure,
+ * AGENTS.md, CLAUDE.md, and .cursorrules based on current skills/ and vendor/ state.
+ *
+ * Run: node bin/sync-docs.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const SKILLS_DIR = path.join(ROOT, "skills");
+const VENDOR_DIR = path.join(ROOT, "vendor");
+
+// Count skills and sources
+const skills = fs
+  .readdirSync(SKILLS_DIR)
+  .filter((f) => !f.startsWith("."));
+const sources = fs
+  .readdirSync(VENDOR_DIR)
+  .filter((f) => !f.startsWith(".") && fs.statSync(path.join(VENDOR_DIR, f)).isDirectory());
+
+const skillCount = skills.length;
+const sourceCount = sources.length;
+
+console.log(`Found ${skillCount} skills from ${sourceCount} sources`);
+
+// --- Update README.md ---
+const readmePath = path.join(ROOT, "README.md");
+let readme = fs.readFileSync(readmePath, "utf8");
+
+// Update badge counts
+readme = readme.replace(
+  /skills-\d+-blue/,
+  `skills-${skillCount}-blue`
+);
+readme = readme.replace(
+  /sources-\d+-green/,
+  `sources-${sourceCount}-green`
+);
+
+// Update intro line
+readme = readme.replace(
+  /\*\*\d+ agent skills\*\* from \*\*\d+ industry-leading sources\*\*/,
+  `**${skillCount} agent skills** from **${sourceCount} industry-leading sources**`
+);
+
+// Update repo structure counts
+readme = readme.replace(
+  /skills\/\s+\d+ symlinks/,
+  `skills/          ${skillCount} symlinks`
+);
+readme = readme.replace(
+  /vendor\/\s+\d+ Git submodules/,
+  `vendor/          ${sourceCount} Git submodules`
+);
+
+fs.writeFileSync(readmePath, readme, "utf8");
+console.log("Updated README.md");
+
+// --- Update AGENTS.md ---
+const agentsPath = path.join(ROOT, "AGENTS.md");
+if (fs.existsSync(agentsPath)) {
+  let agents = fs.readFileSync(agentsPath, "utf8");
+  agents = agents.replace(/\d+ skills/g, `${skillCount} skills`);
+  agents = agents.replace(/\d+ sources/g, `${sourceCount} sources`);
+  fs.writeFileSync(agentsPath, agents, "utf8");
+  console.log("Updated AGENTS.md");
+}
+
+// --- Update CLAUDE.md ---
+const claudePath = path.join(ROOT, "CLAUDE.md");
+if (fs.existsSync(claudePath)) {
+  let claude = fs.readFileSync(claudePath, "utf8");
+  claude = claude.replace(/\d+ skills/g, `${skillCount} skills`);
+  claude = claude.replace(/\d+ sources/g, `${sourceCount} sources`);
+  fs.writeFileSync(claudePath, claude, "utf8");
+  console.log("Updated CLAUDE.md");
+}
+
+// --- Update .cursorrules ---
+const cursorPath = path.join(ROOT, ".cursorrules");
+if (fs.existsSync(cursorPath)) {
+  let cursor = fs.readFileSync(cursorPath, "utf8");
+  cursor = cursor.replace(/\d+ skills/g, `${skillCount} skills`);
+  cursor = cursor.replace(/\d+ sources/g, `${sourceCount} sources`);
+  fs.writeFileSync(cursorPath, cursor, "utf8");
+  console.log("Updated .cursorrules");
+}
+
+// --- Update .lovable ---
+const lovablePath = path.join(ROOT, ".lovable");
+if (fs.existsSync(lovablePath)) {
+  let lovable = fs.readFileSync(lovablePath, "utf8");
+  lovable = lovable.replace(/\d+ curated AI agent skills/, `${skillCount} curated AI agent skills`);
+  lovable = lovable.replace(/\d+ skills/g, `${skillCount} skills`);
+  lovable = lovable.replace(/\d+ sources/g, `${sourceCount} sources`);
+  fs.writeFileSync(lovablePath, lovable, "utf8");
+  console.log("Updated .lovable");
+}
+
+// --- Update .github/copilot-instructions.md ---
+const copilotPath = path.join(ROOT, ".github", "copilot-instructions.md");
+if (fs.existsSync(copilotPath)) {
+  let copilot = fs.readFileSync(copilotPath, "utf8");
+  copilot = copilot.replace(/\d+ curated AI agent skills/, `${skillCount} curated AI agent skills`);
+  fs.writeFileSync(copilotPath, copilot, "utf8");
+  console.log("Updated .github/copilot-instructions.md");
+}
+
+// --- Update CHEATSHEET.md ---
+const cheatsheetPath = path.join(ROOT, "CHEATSHEET.md");
+if (fs.existsSync(cheatsheetPath)) {
+  let cheatsheet = fs.readFileSync(cheatsheetPath, "utf8");
+  cheatsheet = cheatsheet.replace(/\d+ skills/g, `${skillCount} skills`);
+  cheatsheet = cheatsheet.replace(/\d+ sources/g, `${sourceCount} sources`);
+  fs.writeFileSync(cheatsheetPath, cheatsheet, "utf8");
+  console.log("Updated CHEATSHEET.md");
+}
+
+// --- Generate skills list for AGENTS.md / CLAUDE.md ---
+const skillList = skills.sort().map((s) => `- ${s}`).join("\n");
+const marker = "<!-- SKILL_LIST -->";
+const endMarker = "<!-- /SKILL_LIST -->";
+
+for (const filePath of [agentsPath, claudePath]) {
+  if (!fs.existsSync(filePath)) continue;
+  let content = fs.readFileSync(filePath, "utf8");
+  const startIdx = content.indexOf(marker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx !== -1 && endIdx !== -1) {
+    content =
+      content.substring(0, startIdx + marker.length) +
+      "\n" +
+      skillList +
+      "\n" +
+      content.substring(endIdx);
+    fs.writeFileSync(filePath, content, "utf8");
+    console.log(`Updated skill list in ${path.basename(filePath)}`);
+  }
+}
+
+console.log("Done.");
+

package/bin/sync-skills.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Sync DDM (DasDigitaleMomentum) skills from agent-skills repo to agy
+# Run after: git pull in agent-skills repo
+SKILLS_DIR="/Users/Martin/.gemini/antigravity/skills"
+SOURCE="/Users/Martin/git/agent-skills/vendor/opencode-processing-skills/skills"
+
+# execute-work-package is excluded: local copy has transport extensions (Options A/B/C)
+# that are not yet upstreamed to DasDigitaleMomentum/opencode-processing-skills.
+DDM_SKILLS="archive-legacy-docs author-and-verify-implementation-plan create-plan generate-docs generate-handover resume-plan update-docs update-plan"
+
+for skill in $DDM_SKILLS; do
+    rm -rf "${SKILLS_DIR:?}/${skill:?}"
+    cp -R "$SOURCE/$skill" "$SKILLS_DIR/$skill"
+    echo "Synced: $skill"
+done
+
+echo "Done. Total SKILL.md: $(find $SKILLS_DIR -maxdepth 2 -name SKILL.md | wc -l | tr -d ' ')"

package/bin/test-cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * Tests for bin/cli.js
+ * Run: node bin/test-cli.js
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const assert = require("assert");
+
+const CLI = path.join(__dirname, "cli.js");
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  PASS  ${name}`);
+    passed++;
+  } catch (err) {
+    console.log(`  FAIL  ${name}: ${err.message}`);
+    failed++;
+  }
+}
+
+function run(args) {
+  return execSync(`node "${CLI}" ${args}`, {
+    encoding: "utf8",
+    timeout: 10000,
+  });
+}
+
+console.log("CLI Tests\n");
+
+// Test: no args shows usage
+test("no args shows usage", () => {
+  const out = run("");
+  assert(out.includes("Usage"), "Should show usage");
+  assert(out.includes("install"), "Should mention install command");
+  assert(out.includes("update"), "Should mention update command");
+  assert(out.includes("list"), "Should mention list command");
+});
+
+// Test: unknown platform errors
+test("install unknown platform exits with error", () => {
+  try {
+    run("install nonexistent-platform");
+    assert.fail("Should have thrown");
+  } catch (err) {
+    const output = (err.stdout || "") + (err.stderr || "");
+    assert(output.includes("Unknown platform"), "Should say unknown platform");
+  }
+});
+
+// Test: list shows skills
+test("list command works", () => {
+  try {
+    const out = run("list");
+    assert(out.includes("Available Skills"), "Should show available skills header");
+  } catch {
+    // Skills may not be installed in test env, that's ok
+  }
+});
+
+// Test: cli.js is valid Node
+test("cli.js parses without syntax errors", () => {
+  execSync(`node -c "${CLI}"`, { encoding: "utf8" });
+});
+
+// Test: vscode platform is registered
+test("vscode platform is listed", () => {
+  const out = run("");
+  assert(out.includes("vscode"), "Should list vscode as available platform");
+});
+
+// Test: copilot-instructions.md exists
+test("copilot-instructions.md exists", () => {
+  const copilotPath = path.join(__dirname, "..", ".github", "copilot-instructions.md");
+  assert(
+    fs.existsSync(copilotPath),
+    "Should have .github/copilot-instructions.md"
+  );
+});
+
+// Test: copilot-instructions.md has required content
+test("copilot-instructions.md has skill references", () => {
+  const copilotPath = path.join(__dirname, "..", ".github", "copilot-instructions.md");
+  const content = fs.readFileSync(copilotPath, "utf8");
+  assert(content.includes("skills/"), "Should reference skills/ directory");
+  assert(content.includes("SKILL.md"), "Should mention SKILL.md");
+  assert(content.includes("CHEATSHEET.md"), "Should reference CHEATSHEET.md");
+});
+
+// Test: sync-docs.js is valid Node
+test("sync-docs.js parses without syntax errors", () => {
+  const syncDocs = path.join(__dirname, "sync-docs.js");
+  execSync(`node -c "${syncDocs}"`, { encoding: "utf8" });
+});
+
+// Test: sync-docs.js updates counts correctly
+test("sync-docs.js produces correct counts", () => {
+  const out = execSync(`node "${path.join(__dirname, "sync-docs.js")}"`, {
+    encoding: "utf8",
+    cwd: path.join(__dirname, ".."),
+  });
+  assert(out.includes("Found"), "Should report found skills");
+  assert(out.includes("Updated README.md"), "Should update README");
+  assert(out.includes("copilot-instructions"), "Should update copilot-instructions.md");
+  assert(out.includes("Done"), "Should finish successfully");
+});
+
+console.log(`\n${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);

package/bin/update-wiki.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * Update the GitHub Wiki with current catalog data.
+ * Clones the wiki repo, regenerates the Skills-Catalog page, and pushes.
+ *
+ * Run: node bin/update-wiki.js
+ * Requires: git, SSH access to the wiki repo
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const ROOT = path.join(__dirname, "..");
+const CATALOG = path.join(ROOT, "docs", "catalog.json");
+const WIKI_DIR = "/tmp/agent-skills-wiki";
+const WIKI_REPO = "git@github.com:flitzrrr/agent-skills.wiki.git";
+
+function run(cmd, opts) {
+  return execSync(cmd, { encoding: "utf8", ...opts }).trim();
+}
+
+function groupBy(arr, key) {
+  const map = {};
+  for (const item of arr) {
+    const k = item[key];
+    (map[k] = map[k] || []).push(item);
+  }
+  return map;
+}
+
+function main() {
+  if (!fs.existsSync(CATALOG)) {
+    console.error("catalog.json not found. Run build-catalog.js first.");
+    process.exit(1);
+  }
+
+  const catalog = JSON.parse(fs.readFileSync(CATALOG, "utf8"));
+  const grouped = groupBy(catalog.skills, "source");
+  const sourceEntries = Object.entries(grouped).sort((a, b) => b[1].length - a[1].length);
+
+  // Clone wiki
+  try {
+    if (fs.existsSync(WIKI_DIR)) {
+      run(`rm -rf ${WIKI_DIR}`);
+    }
+    run(`git clone ${WIKI_REPO} ${WIKI_DIR}`);
+  } catch (e) {
+    console.error("Failed to clone wiki repo:", e.message);
+    process.exit(1);
+  }
+
+  // Generate Skills-Catalog.md
+  let md = `# Skills Catalog\n\n`;
+  md += `> Last updated: ${catalog.generated.split("T")[0]} | **${catalog.total} skills** across **${sourceEntries.length} sources**\n\n`;
+  md += `The full searchable catalog with copy-to-clipboard is on the [GitHub Pages site](https://flitzrrr.github.io/agent-skills/#catalog).\n\n`;
+  md += `## Skills by Source\n\n`;
+
+  for (const [source, skills] of sourceEntries) {
+    md += `### ${source} (${skills.length} skills)\n\n`;
+    md += `| Skill | Description |\n`;
+    md += `|-------|-------------|\n`;
+    for (const s of skills) {
+      const desc = s.description || "--";
+      md += `| \`${s.name}\` | ${desc} |\n`;
+    }
+    md += `\n`;
+  }
+
+  fs.writeFileSync(path.join(WIKI_DIR, "Skills-Catalog.md"), md);
+
+  // Update Home page stats
+  const homePath = path.join(WIKI_DIR, "Home.md");
+  if (fs.existsSync(homePath)) {
+    let home = fs.readFileSync(homePath, "utf8");
+    // Update skill count references
+    home = home.replace(/\b\d{2,4}\+?\s+skills\b/gi, `${catalog.total}+ skills`);
+    fs.writeFileSync(homePath, home);
+  }
+
+  // Commit and push
+  try {
+    run("git add -A", { cwd: WIKI_DIR });
+    const diff = run("git diff --cached --stat", { cwd: WIKI_DIR });
+    if (!diff) {
+      console.log("Wiki is already up to date.");
+      return;
+    }
+
+    run(`git config user.name "github-actions[bot]"`, { cwd: WIKI_DIR });
+    run(`git config user.email "github-actions[bot]@users.noreply.github.com"`, { cwd: WIKI_DIR });
+    run(`git commit -m "docs: update skill catalog [${catalog.generated.split("T")[0]}]"`, { cwd: WIKI_DIR });
+    run("git push origin master", { cwd: WIKI_DIR });
+    console.log("Wiki updated and pushed.");
+  } catch (e) {
+    console.error("Failed to push wiki:", e.message);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@flitzrrr/agent-skills",
-  "version": "1.0.3",
-  "description": "121 AI agent skills from 15 industry-leading sources — multiplatform-ready for Claude Code, Codex, Cursor, Antigravity, OpenCode, Lovable, and more.",
+  "version": "1.2.0",
+  "description": "480 AI agent skills from 20 sources — multiplatform-ready for VS Code (GitHub Copilot), Claude Code, Codex, Cursor, Antigravity, OpenCode, Lovable, and more.",
+  "scripts": {
+    "test": "node bin/test-cli.js"
+  },
   "bin": {
     "agent-skills": "bin/cli.js"
   },
@@ -9,6 +12,9 @@
     "ai",
     "agent",
     "skills",
+    "vscode",
+    "github-copilot",
+    "copilot",
     "claude",
     "codex",
     "cursor",
@@ -32,6 +38,7 @@
     "CHEATSHEET.md",
     ".cursorrules",
     ".lovable",
+    ".github/copilot-instructions.md",
     "README.md"
   ]
 }

package/skills/dispatch-parallel-agents/skill.md

@@ -0,0 +1,95 @@
+---
+name: dispatch-parallel-agents
+description: Dispatch independent tasks to parallel subagents when 2+ problems can be solved without shared state or sequential dependencies.
+license: MIT
+compatibility:
+  opencode: ">=0.1"
+metadata:
+  category: execution
+  phase: implementation
+---
+
+# Skill: Dispatch Parallel Agents
+
+This skill parallelizes independent work across multiple subagents. Each agent gets a focused scope, isolated context, and a clear deliverable.
+
+---
+
+## When to Use
+
+Use when:
+
+- 2+ independent tasks exist that do not share state
+- Each task can be understood and completed without context from the others
+- Tasks do not edit the same files
+
+Do **not** use when:
+
+- Failures are related (fixing one might fix others -- investigate together first)
+- Tasks require understanding the full system state
+- Agents would interfere with each other (editing the same files, using the same resources)
+- You are in exploratory mode and do not yet know what is broken
+
+---
+
+## Execution Model
+
+### Roles
+
+- **Primary (coordinator)**
+  - Identifies independent problem domains
+  - Crafts focused prompts for each agent
+  - Reviews results and integrates changes
+  - Resolves conflicts if agents touched overlapping code
+
+- **Subagents (workers)**
+  - Each receives a scoped task with all necessary context
+  - Works independently without knowledge of other agents
+  - Returns a summary of findings and changes
+
+---
+
+## Workflow
+
+### Step 1: Identify Independent Domains
+
+Group tasks by what they affect. Each domain must be independent -- fixing one must not affect the others.
+
+Example:
+- Domain A: Fix stats page header styling
+- Domain B: Update billing page layout
+- Domain C: Add admin role detection
+
+These are independent because they touch different files and different logic.
+
+### Step 2: Craft Agent Prompts
+
+Each agent prompt must be:
+
+- **Focused** -- one clear problem domain, not "fix everything"
+- **Self-contained** -- all context needed to understand the problem (file paths, error messages, expected behavior)
+- **Constrained** -- explicit boundaries on what the agent should and should not change
+- **Output-specific** -- what the agent should return (summary, file list, verification result)
+
+### Step 3: Dispatch
+
+Launch all agents in a single message with multiple Agent tool calls. This ensures true parallel execution.
+
+### Step 4: Review and Integrate
+
+When agents return:
+
+1. Read each agent's summary
+2. Check for conflicts (did agents edit the same code?)
+3. Verify changes work together (run build, run tests)
+4. Integrate all changes
+
+---
+
+## Rules
+
+1. **Independence is mandatory**: If tasks share state or files, do not parallelize. Process sequentially instead.
+2. **Focused prompts**: Each agent gets exactly what it needs. Do not dump full session context into agent prompts.
+3. **Verify after integration**: Always run the build and relevant tests after merging all agent outputs. Agents cannot verify cross-agent interactions.
+4. **Do not over-parallelize**: 2-3 agents is typical. More than 5 agents indicates the tasks should be structured differently (e.g., as a plan with phases).
+5. **Conflicts require manual resolution**: If two agents edited the same file, the primary resolves the conflict -- do not blindly apply both changes.