ginskill-init 1.0.0

package/skills/ai-asset-generator/scripts/scaffold-generator.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/**
+ * Asset Generator Scaffold
+ *
+ * Creates a new generation script from a template with the proper
+ * project structure, imports, and pipeline phases.
+ *
+ * Usage:
+ *   node scripts/scaffold-generator.mjs <name> [--assets <count>]
+ *
+ * Example:
+ *   node scripts/scaffold-generator.mjs onboarding --assets 3
+ *   → Creates generate-onboarding-assets.mjs
+ */
+
+import { writeFile, access } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+
+const name = process.argv[2];
+const assetCount = parseInt(process.argv.find((a, i) => process.argv[i - 1] === "--assets") || "2");
+
+if (!name) {
+  console.log(`
+  Usage: node scripts/scaffold-generator.mjs <name> [--assets <count>]
+
+  Examples:
+    node scripts/scaffold-generator.mjs onboarding --assets 3
+    node scripts/scaffold-generator.mjs referral-icon --assets 1
+
+  This creates a new generate-<name>-assets.mjs file with:
+    - Proper imports from lib/
+    - Asset definition array
+    - 4-phase pipeline (submit → poll → download → bg-remove)
+    - Brand color placeholders
+  `);
+  process.exit(0);
+}
+
+const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+const filename = `generate-${slug}-assets.mjs`;
+const filepath = join(ROOT, filename);
+
+// Check if file already exists
+try {
+  await access(filepath);
+  console.error(`  [error] ${filename} already exists. Pick a different name or delete it first.`);
+  process.exit(1);
+} catch {
+  // File doesn't exist — good
+}
+
+// Generate asset placeholders
+const assets = Array.from({ length: assetCount }, (_, i) => {
+  const num = i + 1;
+  return `  {
+    name: "asset-${num}",
+    filename: "asset-${num}.png",
+    aspect_ratio: "${i === 0 ? "16:9" : "1:1"}",
+    resolution: "${i === 0 ? "2K" : "1K"}",
+    removeBg: ${i > 0},
+    prompt: [
+      // TODO: Write a detailed prompt for asset ${num}
+      // Tips:
+      //   - Include specific hex colors: "rose-gold (#EC4899)"
+      //   - Describe composition: "centered on pure white background"
+      //   - Specify render style: "Photorealistic 3D render"
+      //   - Always end with exclusions:
+      "No text, no typography, no logos, no people, no watermarks.",
+    ].join(" "),
+  }`;
+}).join(",\n");
+
+const template = `#!/usr/bin/env node
+
+/**
+ * ${name.charAt(0).toUpperCase() + name.slice(1)} Asset Generator
+ *
+ * Generates assets for the ${name} feature using KIE AI API.
+ *
+ * Brand palette:
+ *   TODO: Fill in brand colors
+ *   Primary: #EC4899 (Rose)
+ *   Gradient: #FFF1F3 → #FFE4E9 → #FECDD6 → #FDA4B8
+ *
+ * Assets:
+ * ${Array.from({ length: assetCount }, (_, i) => `*   ${i + 1}. asset-${i + 1}.png — TODO: describe`).join("\n ")}
+ *
+ * Usage:
+ *   node ${filename}
+ */
+
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { loadEnv } from "./lib/env.mjs";
+import { createTask, pollUntilDone, downloadFile, log } from "./lib/kie-client.mjs";
+import { removeBackground } from "./lib/bg-remove.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// TODO: Set the correct output directory
+const OUTPUT_DIR = join(__dirname, "..", "styai-mobile", "src", "assets", "images", "${slug}");
+
+// ─── Asset Definitions ──────────────────────────────────────
+const IMAGE_ASSETS = [
+${assets}
+];
+
+// ─── Main ───────────────────────────────────────────────────
+async function main() {
+  await loadEnv();
+
+  if (!process.env.KIE_AI_API_KEY) {
+    console.error("Error: KIE_AI_API_KEY not found. Check .env");
+    process.exit(1);
+  }
+
+  console.log("\\n========================================");
+  console.log("  ${name.charAt(0).toUpperCase() + name.slice(1)} Asset Generator");
+  console.log("========================================\\n");
+
+  // Phase 1: Submit all tasks in parallel
+  log("--- Phase 1: Submitting image tasks ---\\n");
+
+  const jobs = await Promise.all(
+    IMAGE_ASSETS.map(async (asset) => {
+      log(\`  [submit] \${asset.name}  (\${asset.aspect_ratio} \${asset.resolution})\`);
+      const taskId = await createTask({
+        model: "nano-banana-pro",
+        input: {
+          prompt: asset.prompt,
+          aspect_ratio: asset.aspect_ratio,
+          resolution: asset.resolution,
+          output_format: "png",
+        },
+      });
+      log(\`  [queued] \${asset.name}  taskId=\${taskId}\`);
+      return { ...asset, taskId };
+    })
+  );
+
+  // Phase 2: Poll all tasks in parallel
+  log(\`\\n--- Phase 2: Polling \${jobs.length} image tasks ---\\n\`);
+
+  const results = await Promise.all(
+    jobs.map(async (job) => {
+      const url = await pollUntilDone(job.taskId, job.name);
+      return { ...job, resultUrl: url };
+    })
+  );
+
+  // Phase 3: Download images
+  log("\\n--- Phase 3: Downloading images ---\\n");
+
+  for (const r of results) {
+    const dest = join(OUTPUT_DIR, r.filename);
+    await downloadFile(r.resultUrl, dest);
+  }
+
+  // Phase 4: Remove backgrounds where needed
+  const bgRemoveJobs = results.filter((r) => r.removeBg);
+  if (bgRemoveJobs.length > 0) {
+    log("\\n--- Phase 4: Removing backgrounds ---\\n");
+    for (const r of bgRemoveJobs) {
+      const src = join(OUTPUT_DIR, r.filename);
+      const noBgName = r.filename.replace(".png", "-nobg.png");
+      const dest = join(OUTPUT_DIR, noBgName);
+      try {
+        await removeBackground(src, dest);
+      } catch (err) {
+        log(\`  [warn] Background removal failed for \${r.name}: \${err.message}\`);
+        log(\`  [skip] Keeping original \${r.filename}\`);
+      }
+    }
+  }
+
+  console.log("\\n========================================");
+  console.log("  All done!");
+  console.log("========================================");
+  console.log(\`\\nGenerated assets in \${OUTPUT_DIR}:\`);
+  for (const r of results) {
+    console.log(\`  - \${r.filename}  (\${r.name})\`);
+    if (r.removeBg) {
+      console.log(\`  - \${r.filename.replace(".png", "-nobg.png")}  (\${r.name} no bg)\`);
+    }
+  }
+  console.log("");
+}
+
+main().catch((err) => {
+  console.error(\`\\nFatal: \${err.message}\`);
+  process.exit(1);
+});
+`;
+
+await writeFile(filepath, template);
+console.log(`  [created] ${filename}`);
+console.log(`  [info]    ${assetCount} asset placeholder(s) ready`);
+console.log(`  [next]    Edit the prompts and OUTPUT_DIR, then run: node ${filename}`);

package/skills/ai-build-ai/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ai-build-ai
+description: |
+  **AI Build AI**: Master guide for extending Claude Code — creating skills, custom subagents (agents), MCP servers, hooks, plugins, agent teams, running Claude programmatically, and more.
+  - MANDATORY TRIGGERS: create skill, new skill, add skill, write skill, build skill, create agent, new agent, add subagent, custom agent, create MCP, add MCP server, connect MCP, build MCP, headless mode, agent SDK, run claude programmatically, claude -p, how to extend claude, claude extensibility, how to create, how to build, hooks, plugin, agent team, sandbox, checkpoint, rewind, output style
+  - Use this skill when the user wants to: create or design a new Claude Code skill, build a custom subagent/agent, connect an MCP server or build their own, run Claude programmatically via CLI or SDK, configure hooks, build a plugin, set up agent teams, configure sandboxing, use checkpointing, or change output styles.
+  - Invoke the correct tutorial based on the topic argument.
+argument-hint: "[skill | agent | mcp | headless | hooks | plugins | teams | memory | permissions | sandbox | checkpoint | output-styles]"
+disable-model-invocation: false
+---
+
+# AI Build AI
+
+You are an expert guide for extending Claude Code. Load the right tutorial based on what the user wants to build.
+
+## Tutorial Routing
+
+Run this to load the relevant tutorial:
+
+!`bash ginstudio-skills/skills/ai-build-ai/scripts/load-tutorial.sh $ARGUMENTS`
+
+---
+
+## How to Use This Skill
+
+After reading the tutorial above, help the user build their extension by:
+
+1. **Understanding their goal** — What do they want to create? What problem does it solve?
+2. **Choosing the right type** — Skill vs Agent vs MCP vs Headless (see decision table below)
+3. **Following the tutorial** — Apply the patterns from the loaded tutorial
+4. **Creating files** — Write the actual SKILL.md / agent .md / scripts / config
+5. **Testing** — Guide them through testing the new extension
+
+---
+
+## Decision Table: What Should I Build?
+
+| Goal | Build This |
+|------|-----------|
+| Teach Claude a repeatable workflow (code review, PR creation, deploy) | **Skill** |
+| Add domain knowledge Claude should always apply (API conventions, style guide) | **Skill** (`user-invocable: false`) |
+| Run heavy/verbose operations without polluting main context | **Subagent** |
+| Give Claude access to GitHub, Slack, databases, external APIs | **MCP Server** |
+| Run Claude in CI/CD, scripts, or automation | **Headless / Agent SDK** |
+| Run Claude in GitHub Actions | **Headless** (`/ai-build-ai headless`) |
+| Build an app that uses Claude as the AI backend | **Agent SDK** |
+| Isolate tool access (read-only, specific commands) | **Subagent** |
+| Auto-format files, block dangerous commands, send notifications | **Hooks** |
+| Distribute extensions to a team or community | **Plugin** |
+| Parallel work where teammates need to communicate | **Agent Teams** |
+| Persist coding standards across sessions | **CLAUDE.md / Memory** |
+| Restrict what files/commands Claude can touch | **Permissions** |
+| Add OS-level protection for bash commands | **Sandbox** |
+| Undo mistakes or experiment safely | **Checkpointing** |
+| Change Claude's tone, verbosity, or teaching style | **Output Style** |
+
+---
+
+## Topic Commands
+
+The user can invoke with a specific topic to load the deep tutorial immediately:
+
+| Command | What Loads |
+|---------|-----------|
+| `/ai-build-ai skill` | Create SKILL.md, frontmatter, arguments, dynamic context, supporting files |
+| `/ai-build-ai agent` | Create subagents, tools, models, memory, hooks, worktree isolation |
+| `/ai-build-ai mcp` | Connect remote/local MCP servers, build your own MCP server |
+| `/ai-build-ai headless` | `claude -p`, output formats, GitHub Actions, CI/CD, Python/TypeScript SDK |
+| `/ai-build-ai hooks` | All hook events, types, exit codes, matchers, notification matchers, recipes |
+| `/ai-build-ai plugins` | Plugin manifest, structure, skills/agents/hooks/MCP in plugins, distribution |
+| `/ai-build-ai teams` | Agent teams: enable, start, control, display modes, use cases |
+| `/ai-build-ai memory` | CLAUDE.md, .claude/rules/, auto memory, imports, monorepo setup |
+| `/ai-build-ai permissions` | Allow/deny rules, modes, Bash/Read/Edit/WebFetch/MCP/Agent rules |
+| `/ai-build-ai sandbox` | OS-level enforcement, filesystem rules, network filtering |
+| `/ai-build-ai checkpoint` | Rewind, fork, session management, summarize from here |
+| `/ai-build-ai output-styles` | Built-in styles, custom styles, keep-coding-instructions |
+| `/ai-build-ai` | Overview of all 12 extension types + decision table |
+
+---
+
+## Supporting Files
+
+- `docs/overview.md` — Overview + decision table (loaded when no topic given)
+- `docs/create-skill.md` — Complete skill creation guide with examples
+- `docs/create-agent.md` — Complete agent creation guide with examples
+- `docs/create-mcp.md` — MCP server setup + building your own
+- `docs/headless-mode.md` — Programmatic usage, GitHub Actions, CI/CD, Agent SDK
+- `docs/hooks.md` — All hook events, types, matchers, notification matchers, recipes
+- `docs/plugins.md` — Plugin manifest, structure, distribution
+- `docs/agent-teams.md` — Team architecture, display modes, use cases
+- `docs/memory-claude-md.md` — CLAUDE.md, rules/, auto memory, imports
+- `docs/permissions.md` — Permission modes, rule syntax, examples
+- `docs/sandbox.md` — OS-level sandboxing, filesystem and network rules
+- `docs/checkpointing.md` — Rewind, fork, session management
+- `docs/output-styles.md` — Built-in and custom output styles
+- `scripts/load-tutorial.sh` — Routes to the right doc based on argument
+
+---
+
+## After Creating an Extension
+
+### For Skills
+1. Test auto-trigger: describe your use case naturally, confirm Claude loads the skill
+2. Test direct invoke: `/skill-name [args]`
+3. Check `SKILL.md` is under 500 lines — move excess to `docs/`
+4. Add to `ginstudio-skills/skills/` to share with the team (this repo)
+
+### For Agents
+1. Run `/agents` to verify the agent appears
+2. Ask Claude: "Use the [agent-name] agent to [task]"
+3. Check tool restrictions work correctly
+4. Enable `memory` if the agent should learn across sessions
+
+### For MCP Servers
+1. Run `claude mcp list` to confirm the server is registered
+2. In Claude Code, type `/mcp` to check server status
+3. Try using an MCP tool naturally: "Check GitHub for open PRs"
+4. Use `--scope project` + commit `.mcp.json` to share with your team
+
+### For Headless
+1. Test with a simple prompt first: `claude -p "hello" --output-format json`
+2. Verify tool permissions: use `--allowedTools` explicitly
+3. Check output format: pipe through `jq` to validate JSON structure
+4. Add to CI/CD workflow as a step

package/skills/ai-build-ai/docs/agent-teams.md

@@ -0,0 +1,293 @@
+# Tutorial: Agent Teams
+
+Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the **team lead**, assigning tasks. Teammates work independently in their own context windows and can communicate directly with each other.
+
+---
+
+## Step 1: Agent Teams vs Subagents
+
+| | Subagents | Agent Teams |
+|--|-----------|-------------|
+| **Context** | Own window, reports back to main | Own window, fully independent |
+| **Communication** | One-way: report results to main agent | Direct messaging between teammates |
+| **Coordination** | Main agent manages all work | Shared task list, self-coordinating |
+| **Best for** | Focused tasks where only result matters | Complex work needing inter-agent discussion |
+| **Token cost** | Lower | Higher (each teammate = separate Claude instance) |
+
+**Use agent teams when:**
+- Teammates need to share findings and challenge each other (e.g., parallel hypothesis testing)
+- Work spans multiple independent domains (frontend + backend + tests)
+- You need sustained parallelism that exceeds one context window
+
+**Use subagents when:**
+- You just need parallel execution of isolated tasks
+- Workers only need to report back, not communicate
+- You want lower token cost
+
+---
+
+## Step 2: Enable Agent Teams
+
+Agent teams are **experimental** and disabled by default. Enable via `.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+Or set in your shell environment:
+```bash
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+claude
+```
+
+---
+
+## Step 3: Start a Team
+
+Just describe the task and ask for a team:
+
+```
+Create an agent team to explore this codebase from different angles:
+one teammate on security, one on performance, one on maintainability.
+Have them each analyze and report findings.
+```
+
+Claude creates the team, spawns teammates, assigns tasks, and synthesizes results.
+
+You can also specify details:
+```
+Create a team with 4 teammates to refactor these modules in parallel.
+Use Sonnet for each teammate.
+```
+
+Claude won't create a team without your approval.
+
+---
+
+## Step 4: Display Modes
+
+**In-process (default):** all teammates run inside your terminal.
+- Press `Shift+Down` to cycle through teammates
+- Type to message the selected teammate
+- Press `Enter` to view a teammate's session, `Escape` to interrupt
+- Press `Ctrl+T` to toggle the task list
+
+**Split-panes:** each teammate gets its own pane (requires tmux or iTerm2).
+- See all teammates' output simultaneously
+- Click a pane to interact directly
+
+Configure in settings:
+```json
+{
+  "teammateMode": "in-process"
+}
+```
+
+Or for one session:
+```bash
+claude --teammate-mode in-process
+```
+
+**Auto** (default): uses split-panes if already in tmux, in-process otherwise.
+
+Install tmux for split-pane mode:
+```bash
+brew install tmux  # macOS
+```
+
+---
+
+## Step 5: Control the Team
+
+### Talk to teammates directly
+
+In in-process mode: press `Shift+Down` to cycle to the teammate, then type.
+In split-pane mode: click their pane.
+
+### Assign tasks
+
+Tell the lead to assign specific work:
+```
+Ask the security teammate to focus only on the auth module
+```
+
+Or teammates can self-claim from the shared task list.
+
+### Require plan approval before implementation
+
+```
+Spawn an architect teammate to refactor the auth module.
+Require plan approval before they make any changes.
+```
+
+The teammate stays in read-only plan mode until the lead approves. If rejected, they revise and resubmit.
+
+### Broadcast to all teammates
+
+```
+Tell all teammates to focus on critical issues only
+```
+
+Use sparingly — costs scale with team size.
+
+### Shut down a teammate
+
+```
+Ask the researcher teammate to shut down
+```
+
+### Clean up the team when done
+
+```
+Clean up the team
+```
+
+Always use the lead for cleanup. The lead checks all teammates have shut down first.
+
+---
+
+## Step 6: Architecture Details
+
+**Components:**
+- **Team lead**: the main Claude Code session, spawns and coordinates teammates
+- **Teammates**: separate Claude Code instances, each with their own context window
+- **Task list**: shared work items (`~/.claude/tasks/{team-name}/`)
+- **Mailbox**: direct messaging between agents (delivered automatically)
+
+**Team config stored at:** `~/.claude/teams/{team-name}/config.json`
+
+**Context each teammate gets:**
+- CLAUDE.md from project
+- MCP servers
+- Skills
+- The spawn prompt from the lead
+- Does NOT get the lead's conversation history
+
+**Permissions:** teammates inherit the lead's permission settings. If lead uses `--dangerously-skip-permissions`, all teammates do too.
+
+---
+
+## Step 7: Quality Gates with Hooks
+
+Use hooks to enforce rules across the team:
+
+```json
+{
+  "hooks": {
+    "TeammateIdle": [{
+      "hooks": [{
+        "type": "prompt",
+        "prompt": "Check if the teammate has completed all assigned tasks. If incomplete work remains, respond with {\"ok\": false, \"reason\": \"what still needs to be done\"}."
+      }]
+    }],
+    "TaskCompleted": [{
+      "hooks": [{
+        "type": "agent",
+        "prompt": "Verify the task was actually completed: run tests for the changed files and confirm they pass. Return {\"ok\": false, \"reason\": \"failing tests\"} if tests fail.",
+        "timeout": 60
+      }]
+    }]
+  }
+}
+```
+
+- `TeammateIdle` — fires when teammate goes idle. Exit code 2 / `"ok": false` sends feedback and keeps them working.
+- `TaskCompleted` — fires when a task is marked complete. Can block completion.
+
+---
+
+## Step 8: Use Case Examples
+
+### Parallel code review
+
+```
+Create an agent team to review PR #142. Spawn three reviewers:
+- One focused on security implications
+- One checking performance impact
+- One validating test coverage
+Have them each review and report findings.
+```
+
+### Competing hypotheses debugging
+
+```
+Users report the app exits after one message instead of staying connected.
+Spawn 5 agent teammates to investigate different hypotheses. Have them talk
+to each other to try to disprove each other's theories, like a scientific debate.
+Update the findings doc with whatever consensus emerges.
+```
+
+### Cross-layer feature implementation
+
+```
+Implement the new payment flow across:
+- Backend: API endpoints and service logic
+- Frontend: UI components and state management
+- Mobile: React Native screens
+- Tests: E2E test coverage
+
+Create a team with 4 teammates, one per layer. Have the backend teammate
+finish the API contracts first, then the others can work in parallel.
+```
+
+---
+
+## Step 9: Best Practices
+
+**Team size:** start with 3-5 teammates. More teammates = more coordination overhead and higher token cost.
+
+**Task sizing:**
+- Too small: coordination overhead exceeds benefit
+- Too large: teammates work too long without check-ins, risk wasted effort
+- Ideal: 5-6 tasks per teammate, each producing a clear deliverable
+
+**Avoid file conflicts:** two teammates editing the same file causes overwrites. Assign each teammate different files.
+
+**Give enough context in spawn prompt:** teammates don't inherit conversation history — include task-specific details in the prompt.
+
+**Monitor and steer:** check in on progress, redirect approaches not working, synthesize findings as they come in.
+
+**Wait for teammates:** if the lead starts implementing instead of waiting:
+```
+Wait for your teammates to complete their tasks before proceeding
+```
+
+---
+
+## Step 10: Known Limitations (Experimental)
+
+- **No session resumption with in-process teammates**: `/resume` doesn't restore them. Spawn new teammates if needed.
+- **Task status can lag**: teammates sometimes fail to mark tasks complete. Check manually if stuck.
+- **Shutdown can be slow**: teammates finish current tool call before shutting down.
+- **One team per session**: a lead can only manage one team at a time.
+- **No nested teams**: teammates cannot spawn their own teams.
+- **Lead is fixed**: the session that creates the team leads forever.
+- **Split panes don't work in**: VS Code integrated terminal, Windows Terminal, Ghostty.
+
+---
+
+## Quick Reference
+
+```bash
+# Enable agent teams
+echo '{"env":{"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"1"}}' > .claude/settings.json
+
+# Start a team (in Claude Code):
+"Create an agent team with 3 teammates to research X, Y, Z in parallel"
+
+# Navigate between teammates (in-process mode):
+Shift+Down         # Cycle to next teammate
+Ctrl+T             # Toggle task list
+Enter              # View teammate's session
+Escape             # Interrupt current teammate turn
+
+# Control the team:
+"Ask teammate [name] to focus on [specific area]"
+"Require plan approval before any teammate makes changes"
+"Ask all teammates to shut down"
+"Clean up the team"
+```