@julioventura/opensquad 0.1.17

package/src/update.js

@@ -0,0 +1,169 @@
+import { cp, mkdir, readFile, stat } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadLocale, t } from './i18n.js';
+import { getTemplateEntries, loadSavedLocale, copyCanonicalSources } from './init.js';
+import { listAvailable as listAvailableSkills, listInstalled as listInstalledSkills, installSkill, getSkillMeta } from './skills.js';
+import { logEvent } from './logger.js';
+
+async function loadSavedIdes(targetDir) {
+  try {
+    const prefsPath = join(targetDir, '_opensquad', '_memory', 'preferences.md');
+    const content = await readFile(prefsPath, 'utf-8');
+    const match = content.match(/\*\*IDEs:\*\*\s*(.+)/);
+    if (match) {
+      return match[1].trim().split(/,\s*/);
+    }
+  } catch {
+    // No preferences file
+  }
+  return ['claude-code'];
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+
+const PROTECTED_PATHS = [
+  '_opensquad/_memory',
+  'agents',
+  'squads',
+];
+
+function isProtected(relativePath) {
+  const normalized = relativePath.replaceAll('\\', '/');
+  return PROTECTED_PATHS.some(
+    (p) => normalized === p || normalized.startsWith(p + '/')
+  );
+}
+
+async function backupIfExists(destPath) {
+  try {
+    await stat(destPath);
+    const backupPath = destPath + '.bak';
+    await cp(destPath, backupPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function update(targetDir) {
+  console.log('\n  🔄 Opensquad — Update\n');
+
+  // 1. Check initialized
+  try {
+    await stat(join(targetDir, '_opensquad'));
+  } catch {
+    await loadLocale('English');
+    console.log(`  ${t('updateNotInitialized')}`);
+    return { success: false };
+  }
+
+  // 2. Load user's locale
+  await loadSavedLocale(targetDir);
+
+  // 3. Read versions
+  let currentVersion = null;
+  try {
+    currentVersion = (
+      await readFile(join(targetDir, '_opensquad', '.opensquad-version'), 'utf-8')
+    ).trim();
+  } catch {
+    // Legacy install — no version file
+  }
+
+  const newVersion = (
+    await readFile(join(TEMPLATES_DIR, '_opensquad', '.opensquad-version'), 'utf-8')
+  ).trim();
+
+  // 4. Announce
+  if (currentVersion) {
+    console.log(
+      `  ${t('updateStarting', { old: `v${currentVersion}`, new: `v${newVersion}` })}`
+    );
+  } else {
+    console.log(`  ${t('updateStartingUnknown', { new: `v${newVersion}` })}`);
+  }
+
+  // 5. Copy common templates, skipping protected paths and ide-templates/
+  const entries = await getTemplateEntries(TEMPLATES_DIR);
+  let count = 0;
+
+  for (const entry of entries) {
+    const relativePath = relative(TEMPLATES_DIR, entry);
+    if (isProtected(relativePath)) continue;
+    // Skip ide-templates — handled separately below
+    if (relativePath.replaceAll('\\', '/').startsWith('ide-templates/')) continue;
+
+    const destPath = join(targetDir, relativePath);
+    await mkdir(dirname(destPath), { recursive: true });
+    const backed = await backupIfExists(destPath);
+    await cp(entry, destPath);
+    const displayPath = relativePath.replaceAll('\\', '/');
+    if (backed) {
+      console.log(`  ${t('updatedFile', { path: displayPath })} (backup: ${displayPath}.bak)`);
+    } else {
+      console.log(`  ${t('updatedFile', { path: displayPath })}`);
+    }
+    count++;
+  }
+
+  // 6. Copy IDE-specific templates based on saved preferences
+  const ides = await loadSavedIdes(targetDir);
+  for (const ide of ides) {
+    const ideSrcDir = join(TEMPLATES_DIR, 'ide-templates', ide);
+    let ideEntries;
+    try {
+      ideEntries = await getTemplateEntries(ideSrcDir);
+    } catch {
+      continue; // no template dir for this IDE
+    }
+    for (const entry of ideEntries) {
+      const relPath = relative(ideSrcDir, entry);
+      if (isProtected(relPath)) continue;
+
+      const destPath = join(targetDir, relPath);
+      await mkdir(dirname(destPath), { recursive: true });
+      const backed = await backupIfExists(destPath);
+      await cp(entry, destPath);
+      const displayPath = relPath.replaceAll('\\', '/');
+      if (backed) {
+        console.log(`  ${t('updatedFile', { path: displayPath })} (backup: ${displayPath}.bak)`);
+      } else {
+        console.log(`  ${t('updatedFile', { path: displayPath })}`);
+      }
+      count++;
+    }
+  }
+
+  // 6a. Copy canonical sources (core, config, dashboard)
+  count += await copyCanonicalSources(targetDir, {
+    overwrite: true,
+    backupFn: backupIfExists,
+    protectedFn: isProtected,
+  });
+
+  // 6b. Install new non-MCP, non-hybrid bundled skills not already present
+  const availableSkills = await listAvailableSkills();
+  const installedSkills = await listInstalledSkills(targetDir);
+  for (const id of availableSkills) {
+    if (id === 'opensquad-skill-creator') continue;
+    if (installedSkills.includes(id)) continue;
+    const meta = await getSkillMeta(id);
+    if (!meta) continue;
+    if (meta.type === 'mcp' || meta.type === 'hybrid') continue;
+    await installSkill(id, targetDir);
+    console.log(`  ${t('createdFile', { path: `skills/${id}/SKILL.md` })}`);
+    count++;
+  }
+
+  // 7. Summary
+  console.log(`\n  ${t('updateFileCount', { count })}`);
+  console.log(`  ${t('updatePreserved')}`);
+  console.log(`  ${t('updateSuccess', { version: `v${newVersion}` })}`);
+  console.log(`\n  ${t('updateLatestHint')}\n`);
+
+  await logEvent('update', { from: currentVersion || 'unknown', to: newVersion }, targetDir);
+
+  return { success: true };
+}

package/templates/_opensquad/.opensquad-version

@@ -0,0 +1 @@
+0.1.17

package/templates/ide-templates/antigravity/.agent/rules/opensquad.md

@@ -0,0 +1,68 @@
+---
+name: opensquad
+---
+
+# Opensquad — Project Instructions
+
+This project uses **Opensquad**, a multi-agent orchestration framework.
+
+## Quick Start
+
+Type `/opensquad` to open the main menu, or use any of these commands:
+- `/opensquad create` — Create a new squad
+- `/opensquad run <name>` — Run a squad
+- `/opensquad help` — See all commands
+
+## Directory Structure
+
+- `_opensquad/` — Opensquad core files (do not modify manually)
+- `_opensquad/_memory/` — Persistent memory (company context, preferences)
+- `skills/` — Installed skills (integrations, scripts, prompts)
+- `squads/` — User-created squads
+- `squads/{name}/_investigations/` — Sherlock content investigations (profile analyses)
+- `squads/{name}/output/` — Generated content and files
+- `_opensquad/_browser_profile/` — Persistent browser sessions (login cookies, localStorage)
+
+## How It Works
+
+1. The `/opensquad` workflow is the entry point for all interactions
+2. The **Architect** agent creates and modifies squads
+3. During squad creation, the **Sherlock** investigator can analyze reference profiles (Instagram, YouTube, Twitter/X, LinkedIn) to extract real content patterns
+4. The **Pipeline Runner** executes squads automatically
+5. All tasks run inline and sequentially (no background subagents)
+6. Checkpoints pause execution for user input/approval
+
+## Rules
+
+- Always use `/opensquad` commands to interact with the system
+- Do not manually edit files in `_opensquad/core/` unless you know what you're doing
+- Squad YAML files can be edited manually if needed, but prefer using `/opensquad edit`
+- Company context in `_opensquad/_memory/company.md` is loaded for every squad run
+## Execution & Multi-Session Continuity
+
+When running or resuming a squad, follow these rules:
+1. **Check State & Environment**:
+   - Always read `squads/{name}/state.json` first. If a run is in progress (`status: running`), extract the `runId` and the `environment`. Check `squads/{name}/output/{runId}/` to verify generated files, and resume execution from the interrupted step.
+   - If starting a new run, ask the user to select the active environment: 1. Claude Code (`claude-code`), 2. VSCode + GitHub Copilot Pro (`vscode-copilot`), 3. Google Antigravity (`antigravity`), or 4. Codex / OpenCode (`opencode`). Store this selection as `environment` in `state.json`.
+   - If `environment` is `vscode-copilot` or `antigravity`, force all steps to run as `execution: inline` sequentially (override any `execution: subagent` settings).
+2. **JIT Context Loading**: Do not read all files at once. Read the current step md, the active agent's `.agent.md`, referenced formats in `_opensquad/core/best-practices/`, and only the declared skill files in `skills/`.
+3. **Binary Validation Gates**:
+   - Before a step: Run `test -s` on the `inputFile` and `contextFiles`. Halt and prompt the user if files are missing.
+   - After a step: Run `test -s` on `outputFile` and `requiredArtifacts`. If a validation check fails, retry the step once, then halt if it fails again.
+4. **Update state.json**: Update `state.json` before starting a step, during agent handoffs (switch status to `delivering` then `working`), and on run completion.
+5. **Post-Run Cleanup**: Upon completion, copy `state.json` to the output folder, move older run folders to `output/archive/`, update `memories.md` with explicit user corrections only, and generate the run dashboard.
+
+## Antigravity Environment: Subagents
+
+This environment (Google Antigravity) does not support spawning background or parallel subagents. When agent instructions (e.g., from the Architect) say to "use the Task tool with run_in_background: true" or similar, you MUST instead execute all tasks inline and sequentially:
+
+1. Inform the user you will process the tasks one by one
+2. Execute each task in the current conversation — do NOT skip or defer any of them
+3. Complete ALL tasks before asking the next question or moving on
+
+Never announce that you "will do something in parallel" and then skip the work. Always do the actual research inline before continuing.
+
+## Interaction Rules
+
+- NEVER ask more than one question per message — always wait for the user's answer before proceeding to the next question
+- When presenting options, always use a numbered list (1. / 2. / 3.) — tell the user to reply with the option number

package/templates/ide-templates/antigravity/.agent/workflows/opensquad.md

@@ -0,0 +1,102 @@
+---
+description: Opensquad — Create and run AI agent squads for your business
+---
+
+You are now activating the Opensquad system. Follow these steps IN ORDER:
+
+1. Read `_opensquad/_memory/company.md` for company context
+2. Read `_opensquad/_memory/preferences.md` for user preferences
+3. If company.md is empty or contains `<!-- NOT CONFIGURED -->`, run the ONBOARDING flow (see below)
+4. Otherwise, show the MAIN MENU
+
+## Onboarding Flow (first time only)
+
+If `company.md` is empty or contains `<!-- NOT CONFIGURED -->`:
+
+1. Welcome the user warmly to Opensquad
+2. Ask their name (save to preferences.md)
+3. Ask their preferred language for outputs (save to preferences.md)
+4. Ask for their company name/description and website URL
+5. Use WebFetch on their URL + WebSearch with their company name to research:
+   - Company description and sector
+   - Target audience
+   - Products/services offered
+   - Tone of voice (inferred from website copy)
+   - Social media profiles found
+6. Present the findings in a clean summary and ask the user to confirm or correct
+7. Save the confirmed profile to `_opensquad/_memory/company.md`
+8. Show the main menu
+
+## Main Menu
+
+Present the following numbered menu and ask the user to reply with a number:
+
+**Primary menu:**
+1. **Create a new squad** — Describe what you need and I'll build a squad for you
+2. **Run an existing squad** — Execute a squad's pipeline
+3. **My squads** — View, edit, or delete your squads
+4. **More options** — Skills, company profile, settings, and help
+
+If the user replies "4" or types "More options", present a second numbered menu:
+1. **Skills** — Browse, install, create, and manage skills for your squads
+2. **Company profile** — View or update your company information
+3. **Settings & Help** — Language, preferences, configuration, and help
+
+## Command Routing
+
+Parse user input and route to the appropriate action:
+
+| Input Pattern | Action |
+|---------------|--------|
+| `/opensquad` or `/opensquad menu` | Show main menu |
+| `/opensquad help` | Show help text |
+| `/opensquad create <description>` | Load Architect → Create Squad flow |
+| `/opensquad list` | List all squads in `squads/` directory |
+| `/opensquad run <name>` | Load Pipeline Runner → Execute squad |
+| `/opensquad edit <name> <changes>` | Load Architect → Edit Squad flow |
+| `/opensquad skills` | Load Skills Engine → Show skills menu |
+| `/opensquad install <name>` | Install a skill from the catalog |
+| `/opensquad uninstall <name>` | Remove an installed skill |
+| `/opensquad delete <name>` | Confirm and delete squad directory |
+| `/opensquad edit-company` | Re-run company profile setup |
+| `/opensquad show-company` | Display company.md contents |
+| `/opensquad settings` | Show/edit preferences.md |
+| `/opensquad reset` | Confirm and reset all configuration |
+| Natural language about squads | Infer intent and route accordingly |
+
+## Loading Agents
+
+When a specific agent needs to be activated:
+
+1. Read the agent's `.agent.md` file completely
+2. Adopt the agent's persona (role, identity, communication_style, principles)
+3. Follow the agent's menu/workflow instructions
+4. When the agent's task is complete, return to Opensquad main context
+
+## Loading the Pipeline Runner
+
+When running a squad:
+
+1. Read `squads/{name}/squad.yaml` to understand the pipeline
+2. Read `squads/{name}/squad-party.csv` to load all agent personas
+3. For each agent in the party CSV, also read their full `.agent.md` file from agents/ directory
+4. Load company context from `_opensquad/_memory/company.md`
+5. Load squad memory from `squads/{name}/_memory/memories.md`
+6. Read the pipeline runner instructions from `_opensquad/core/runner.pipeline.md`
+7. Execute the pipeline step by step following runner instructions
+
+## Language Handling
+
+- Read `preferences.md` for the user's preferred language
+- All user-facing output should be in the user's preferred language
+- Internal file names and code remain in English
+- Agent personas communicate in the user's language
+
+## Critical Rules
+
+- NEVER skip the onboarding if company.md is not configured
+- ALWAYS load company context before running any squad
+- ALWAYS present checkpoints to the user — never skip them
+- ALWAYS save outputs to the squad's output directory
+- When switching personas (inline execution), clearly indicate which agent is speaking
+- After each pipeline run, update the squad's memories.md with key learnings

package/templates/ide-templates/claude-code/.claude/skills/opensquad/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: opensquad
+description: "Opensquad — Multi-agent orchestration framework. Create and run AI squads for your business."
+---
+
+# Opensquad — Multi-Agent Orchestration
+
+You are now operating as the Opensquad system. Your primary role is to help users create, manage, and run AI agent squads.
+
+## Initialization
+
+On activation, perform these steps IN ORDER:
+
+1. Read the company context file: `{project-root}/_opensquad/_memory/company.md`
+2. Read the preferences file: `{project-root}/_opensquad/_memory/preferences.md`
+3. Check if company.md is empty or contains only the template — if so, trigger ONBOARDING flow
+4. Otherwise, display the MAIN MENU
+
+## Onboarding Flow (first time only)
+
+If `company.md` is empty or contains `<!-- NOT CONFIGURED -->`:
+
+1. Welcome the user warmly to Opensquad
+2. Ask their name (save to preferences.md)
+3. Ask their preferred language for outputs (save to preferences.md)
+4. Ask for their company name/description and website URL
+5. Use WebFetch on their URL + WebSearch with their company name to research:
+   - Company description and sector
+   - Target audience
+   - Products/services offered
+   - Tone of voice (inferred from website copy)
+   - Social media profiles found
+6. Present the findings in a clean summary and ask the user to confirm or correct
+7. Save the confirmed profile to `_opensquad/_memory/company.md`
+8. Show the main menu
+
+## Main Menu
+
+When the user types `/opensquad` or asks for the menu, present an interactive selector using AskUserQuestion with these options (max 4 per question):
+
+**Primary menu (first question):**
+- **Create a new squad** — Describe what you need and I'll build a squad for you
+- **Run an existing squad** — Execute a squad's pipeline
+- **My squads** — View, edit, or delete your squads
+- **More options** — Skills, company profile, settings, and help
+
+If the user selects "More options", present a second AskUserQuestion:
+- **Skills** — Browse, install, create, and manage skills for your squads
+- **Company profile** — View or update your company information
+- **Settings & Help** — Language, preferences, configuration, and help
+
+## Command Routing
+
+Parse user input and route to the appropriate action:
+
+| Input Pattern | Action |
+|---------------|--------|
+| `/opensquad` or `/opensquad menu` | Show main menu |
+| `/opensquad help` | Show help text |
+| `/opensquad create <description>` | Load Architect → Create Squad flow (will ask for reference profile URLs for Sherlock investigation) |
+| `/opensquad list` | List all squads in `squads/` directory |
+| `/opensquad run <name>` | Load Pipeline Runner → Execute squad |
+| `/opensquad edit <name> <changes>` | Load Architect → Edit Squad flow |
+| `/opensquad skills` | Load Skills Engine → Show skills menu |
+| `/opensquad install <name>` | Install a skill from the catalog |
+| `/opensquad uninstall <name>` | Remove an installed skill |
+| `/opensquad delete <name>` | Confirm and delete squad directory |
+| `/opensquad edit-company` | Re-run company profile setup |
+| `/opensquad show-company` | Display company.md contents |
+| `/opensquad settings` | Show/edit preferences.md |
+| `/opensquad reset` | Confirm and reset all configuration |
+| Natural language about squads | Infer intent and route accordingly |
+
+## Help Text
+
+When help is requested, display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📘 Opensquad Help
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+GETTING STARTED
+  /opensquad                  Open the main menu
+  /opensquad help             Show this help
+
+SQUADS
+  /opensquad create           Create a new squad (describe what you need)
+  /opensquad list             List all your squads
+  /opensquad run <name>       Run a squad's pipeline
+  /opensquad edit <name>      Modify an existing squad
+  /opensquad delete <name>    Delete a squad
+
+SKILLS
+  /opensquad skills           Browse installed skills
+  /opensquad install <name>   Install a skill from catalog
+  /opensquad uninstall <name> Remove an installed skill
+
+COMPANY
+  /opensquad edit-company     Edit your company profile
+  /opensquad show-company     Show current company profile
+
+SETTINGS
+  /opensquad settings         Change language, preferences
+  /opensquad reset            Reset Opensquad configuration
+
+EXAMPLES
+  /opensquad create "Instagram carousel content production squad"
+    (provide reference profile URLs when asked for Sherlock investigation)
+  /opensquad create "Weekly data analysis squad for Google Sheets"
+  /opensquad create "Customer email response automation squad"
+  /opensquad run my-squad
+
+💡 Tip: You can also just describe what you need in plain language!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Loading Agents
+
+When a specific agent needs to be activated (Architect, or any squad agent):
+
+1. Read the agent's `.agent.md` file completely (YAML frontmatter for metadata + markdown body for depth)
+2. Adopt the agent's persona (role, identity, communication_style, principles)
+3. Follow the agent's menu/workflow instructions
+4. When the agent's task is complete, return to Opensquad main context
+
+## Loading the Pipeline Runner
+
+When running a squad:
+
+1. Read `squads/{name}/squad.yaml` to understand the pipeline
+2. Read `squads/{name}/squad-party.csv` to load all agent personas
+2b. For each agent in the party CSV, also read their full `.agent.md` file from agents/ directory
+3. Load company context from `_opensquad/_memory/company.md`
+4. Load squad memory from `squads/{name}/_memory/memories.md`
+5. Read the pipeline runner instructions from `_opensquad/core/runner.pipeline.md`
+6. Execute the pipeline step by step following runner instructions
+
+## Loading the Skills Engine
+
+When the user selects "Skills" from the menu or types `/opensquad skills`:
+
+1. Read `_opensquad/core/skills.engine.md` for the skills engine instructions
+2. Present the skills submenu using AskUserQuestion (max 4 options):
+   - **View installed skills** — See what's installed and their status
+   - **Install a skill** — Browse the catalog and install
+   - **Create a custom skill** — Create a new skill (uses opensquad-skill-creator)
+   - **Remove a skill** — Uninstall a skill
+3. Follow the corresponding operation in the skills engine
+4. When done, offer to return to the main menu
+
+## Language Handling
+
+- Read `preferences.md` for the user's preferred language
+- All user-facing output should be in the user's preferred language
+- Internal file names and code remain in English
+- Agent personas communicate in the user's language
+
+## Checkpoint Handling (Claude Code)
+
+This overrides the shared `runner.pipeline.md` checkpoint behavior for Claude Code. Checkpoint steps always execute inline (they require direct user input and are never dispatched as subagents), so this SKILL.md context is always present when a checkpoint runs.
+
+**Rule: ALL checkpoint questions MUST use `AskUserQuestion`.** Never output a question as plain text.
+
+When a checkpoint has multiple user questions, combine them into a single `AskUserQuestion` call (the tool supports up to 4 question slots per call; each slot must still have 2–4 options, per Critical Rules below).
+
+**Free-text questions** (questions with no predefined option list):
+- Extract 2–3 concrete examples from the question's description or bullet list as options
+- The tool always provides an "Other" option for custom text input — no need to add it manually
+
+**Choice questions** (questions with a numbered list of options): use `AskUserQuestion` as usual.
+
+## Critical Rules
+
+- **AskUserQuestion MUST always have 2-4 options.** When presenting a dynamic list (squads, skills, agents, etc.) as AskUserQuestion options and only 1 item exists, ALWAYS add a fallback option like "Cancel" or "Back to menu" to ensure the minimum of 2 options. If 0 items exist, skip AskUserQuestion entirely and inform the user directly.
+- NEVER skip the onboarding if company.md is not configured
+- ALWAYS load company context before running any squad
+- ALWAYS present checkpoints to the user — never skip them
+- ALWAYS save outputs to the squad's output directory
+- When switching personas (inline execution), clearly indicate which agent is speaking
+- When using subagents, inform the user that background work is happening
+- After each pipeline run, update the squad's memories.md only with explicit user feedback, and then re-evaluate whether the run surfaced any reusable cross-squad experience that must be registered in the appropriate shared skill or `_opensquad/core` guidance before closing the pipeline

package/templates/ide-templates/claude-code/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--config", "_opensquad/config/playwright.config.json"]
+    }
+  }
+}

package/templates/ide-templates/claude-code/CLAUDE.md

@@ -0,0 +1,57 @@
+# Opensquad — Project Instructions
+
+This project uses **Opensquad**, a multi-agent orchestration framework.
+
+## Quick Start
+
+Type `/opensquad` to open the main menu, or use any of these commands:
+- `/opensquad create` — Create a new squad
+- `/opensquad run <name>` — Run a squad
+- `/opensquad help` — See all commands
+## Execution & Multi-Session Continuity
+
+When running or resuming a squad, you act as the **Pipeline Runner** (defined in `_opensquad/core/runner.pipeline.md`). You must follow these strict rules:
+1. **Check State & Environment**:
+   - Always read `squads/{name}/state.json` first. If a run is in progress (`status: running`), extract the `runId` and the `environment`. Check `squads/{name}/output/{runId}/` to verify generated files, and resume execution from the interrupted step.
+   - If starting a new run, ask the user to select the active environment: 1. Claude Code (`claude-code`), 2. VSCode + GitHub Copilot Pro (`vscode-copilot`), 3. Google Antigravity (`antigravity`), or 4. Codex / OpenCode (`opencode`). Store this selection as `environment` in `state.json`.
+   - If `environment` is `vscode-copilot` or `antigravity`, force all steps to run as `execution: inline` sequentially (override any `execution: subagent` settings).
+2. **JIT Context Loading**: Do not read all files at once. Read the current step md, the active agent's `.agent.md`, referenced formats in `_opensquad/core/best-practices/`, and only the declared skill files in `skills/`.
+3. **Binary Validation Gates**:
+   - Before a step: Run `test -s` on the `inputFile` and `contextFiles`. Halt and prompt the user if files are missing.
+   - After a step: Run `test -s` on `outputFile` and `requiredArtifacts`. If a validation check fails, retry the step once, then halt if it fails again.
+4. **Update state.json**: Update `state.json` before starting a step, during agent handoffs (switch status to `delivering` then `working`), and on run completion.
+5. **Subagent Execution**: If execution mode is `subagent` but your current IDE workspace does not support background tasks, execute the step inline in the current thread sequentially. Switch personas explicitly (e.g. `[Paula Pauta] - Executing Editorial Planning...`).
+6. **Post-Run Cleanup**: Upon completion, copy `state.json` to the output folder, move older run folders to `output/archive/`, update `memories.md` with explicit user corrections only, and generate the run dashboard.
+
+## Directory Structure
+
+- `_opensquad/` — Opensquad core files (do not modify manually)
+- `_opensquad/_memory/` — Persistent memory (company context, preferences)
+- `squads/` — User-created squads
+- `squads/{name}/_investigations/` — Sherlock content investigations (profile analyses)
+- `squads/{name}/output/` — Generated content and files
+- `_opensquad/_browser_profile/` — Persistent browser sessions (login cookies, localStorage)
+
+## How It Works
+
+1. The `/opensquad` skill is the entry point for all interactions
+2. The **Architect** agent creates and modifies squads
+3. During squad creation, the **Sherlock** investigator can analyze reference profiles (Instagram, YouTube, Twitter/X, LinkedIn) to extract real content patterns
+4. The **Pipeline Runner** executes squads automatically
+5. Agents communicate via persona switching (inline) or subagents (background)
+6. Checkpoints pause execution for user input/approval
+
+## Rules
+
+- Always use `/opensquad` commands to interact with the system
+- Do not manually edit files in `_opensquad/core/` unless you know what you're doing
+- Squad YAML files can be edited manually if needed, but prefer using `/opensquad edit`
+- Company context in `_opensquad/_memory/company.md` is loaded for every squad run
+
+## Browser Sessions
+
+Opensquad uses a persistent Playwright browser profile to keep you logged into social media platforms.
+- Sessions are stored in `_opensquad/_browser_profile/` (gitignored, private to you)
+- First time accessing a platform, you'll log in manually once
+- Subsequent runs will reuse your saved session
+- **Important:** The native Claude Code Playwright plugin must be disabled. Opensquad uses its own `@playwright/mcp` server configured in `.mcp.json`.

package/templates/ide-templates/codex/.agents/skills/opensquad/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: opensquad
+description: Run Opensquad — multi-agent orchestration. Use when the user types /opensquad or asks to create, run, or manage squads.
+---
+
+Read `AGENTS.md` at the project root and adopt the Opensquad system role. Follow all initialization, command routing, and workflow instructions defined there.