@jiggai/recipes 0.2.11

package/recipes/default/social-team.md

@@ -0,0 +1,205 @@
+---
+id: social-team
+name: Social Media Team
+version: 0.1.0
+description: A small social media team with a shared workspace (lead, research, writer, editor).
+kind: team
+cronJobs:
+  - id: lead-triage-loop
+    name: "Lead triage loop"
+    schedule: "*/30 7-23 * * 1-5"
+    timezone: "America/New_York"
+    message: "Automated lead triage loop: triage inbox/tickets, assign work, and update notes/status.md."
+    enabledByDefault: false
+  - id: execution-loop
+    name: "Execution loop"
+    schedule: "*/30 7-23 * * 1-5"
+    timezone: "America/New_York"
+    message: "Automated execution loop: make progress on in-progress tickets, keep changes small/safe, and update notes/status.md."
+    enabledByDefault: false
+  # pr-watcher omitted (enable only when a real PR integration exists)
+requiredSkills: []
+team:
+  teamId: social-team
+agents:
+  - role: lead
+    name: Social Team Lead
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web", "group:runtime"]
+      deny: ["exec"]
+  - role: research
+    name: Social Trend Researcher
+  - role: writer
+    name: Social Content Writer
+  - role: editor
+    name: Social Editor
+
+# For team recipes, template keys are namespaced by role, e.g. lead.soul
+templates:
+  lead.soul: |
+    # SOUL.md
+
+    You are the Team Lead / Dispatcher for {{teamId}}.
+
+    Your job:
+    - Read new requests in {{teamDir}}/inbox
+    - Break them into assignments for the specialist agents
+    - Keep a lightweight plan in {{teamDir}}/notes/plan.md
+    - Consolidate deliverables into {{teamDir}}/outbox
+
+  lead.agents: |
+    # AGENTS.md
+
+    ## Shared team workspace
+
+    Team: {{teamId}}
+    Team directory: {{teamDir}}
+
+    Workflow (mapped to canonical lanes):
+    - backlog → in-progress → testing → done
+    - Intake: check `inbox/` and write tickets into work/backlog/
+    - Drafting: use work/in-progress/ for active drafting
+    - Approval/review: use work/testing/ for review + final checks
+    - Done: move to work/done/ and publish/schedule into outbox/
+
+    QA verification:
+    - Use notes/QA_CHECKLIST.md
+    - Preferred record: work/testing/<ticket>.testing-verified.md
+
+  research.soul: |
+    # SOUL.md
+
+    You are a Social Trend Researcher on {{teamId}}.
+    You produce concise, sourced research for the writer and lead.
+
+  research.agents: |
+    # AGENTS.md
+
+    Shared team directory: {{teamDir}}
+
+    Output conventions:
+    - Write findings to `work/research/` with clear filenames.
+    - Include links and bullet summaries.
+
+  writer.soul: |
+    # SOUL.md
+
+    You are a Social Content Writer on {{teamId}}.
+    Turn research + prompts into drafts with strong hooks.
+
+  writer.agents: |
+    # AGENTS.md
+
+    Shared team directory: {{teamDir}}
+
+    Output conventions:
+    - Drafts go in `work/drafts/`.
+    - Keep tone consistent with the request.
+
+  editor.soul: |
+    # SOUL.md
+
+    You are a Social Editor on {{teamId}}.
+    Polish drafts for clarity, structure, and punch.
+
+  editor.agents: |
+    # AGENTS.md
+
+    Shared team directory: {{teamDir}}
+
+    Output conventions:
+    - Edited drafts go in `work/edited/`.
+    - Provide a short changelog at the top.
+
+    ## QA verification (approval)
+    Before moving a deliverable to done/scheduled:
+    - Record verification using notes/QA_CHECKLIST.md.
+    - Preferred: create work/testing/<ticket>.testing-verified.md.
+
+  lead.tools: |
+    # TOOLS.md
+
+    (empty)
+
+  lead.status: |
+    # STATUS.md
+
+    - (empty)
+
+  lead.notes: |
+    # NOTES.md
+
+    - (empty)
+
+  research.tools: |
+    # TOOLS.md
+
+    (empty)
+
+  research.status: |
+    # STATUS.md
+
+    - (empty)
+
+  research.notes: |
+    # NOTES.md
+
+    - (empty)
+
+  writer.tools: |
+    # TOOLS.md
+
+    (empty)
+
+  writer.status: |
+    # STATUS.md
+
+    - (empty)
+
+  writer.notes: |
+    # NOTES.md
+
+    - (empty)
+
+  editor.tools: |
+    # TOOLS.md
+
+    (empty)
+
+  editor.status: |
+    # STATUS.md
+
+    - (empty)
+
+  editor.notes: |
+    # NOTES.md
+
+    - (empty)
+
+
+files:
+  - path: SOUL.md
+    template: soul
+    mode: createOnly
+  - path: AGENTS.md
+    template: agents
+    mode: createOnly
+  - path: TOOLS.md
+    template: tools
+    mode: createOnly
+  - path: STATUS.md
+    template: status
+    mode: createOnly
+  - path: NOTES.md
+    template: notes
+    mode: createOnly
+
+tools:
+  profile: "coding"
+  allow: ["group:fs", "group:web"]
+  deny: ["exec"]
+---
+# Social Team Recipe
+
+Scaffolds a shared team workspace and four namespaced agents.

package/recipes/default/writing-team.md

@@ -0,0 +1,228 @@
+---
+id: writing-team
+name: Writing Team
+version: 0.1.0
+description: A writing pipeline (lead, outliner, writer, editor) that produces drafts and polished deliverables.
+kind: team
+cronJobs:
+  - id: lead-triage-loop
+    name: "Lead triage loop"
+    schedule: "*/30 7-23 * * 1-5"
+    timezone: "America/New_York"
+    message: "Automated lead triage loop: triage inbox/tickets, assign work, and update notes/status.md."
+    enabledByDefault: false
+  - id: execution-loop
+    name: "Execution loop"
+    schedule: "*/30 7-23 * * 1-5"
+    timezone: "America/New_York"
+    message: "Automated execution loop: make progress on in-progress tickets, keep changes small/safe, and update notes/status.md."
+    enabledByDefault: false
+  # pr-watcher omitted (enable only when a real PR integration exists)
+requiredSkills: []
+team:
+  teamId: writing-team
+agents:
+  - role: lead
+    name: Writing Lead
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web", "group:runtime"]
+      deny: ["exec"]
+  - role: outliner
+    name: Outliner
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: writer
+    name: Writer
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: editor
+    name: Editor
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+
+templates:
+  lead.soul: |
+    # SOUL.md
+
+    You are the Writing Lead / Editor-in-Chief for {{teamId}}.
+
+    Core job:
+    - Turn requests into briefs + tickets.
+    - Ensure tone + audience are specified.
+    - Keep the pipeline moving and enforce quality.
+
+  lead.agents: |
+    # AGENTS.md
+
+    Team: {{teamId}}
+    Team directory: {{teamDir}}
+
+    ## Shared workspace
+    - inbox/ — requests
+    - work/backlog/ — tickets (0001-...)
+    - work/in-progress/ — active tickets
+    - work/testing/ — review/edit/QA (verification before publishing)
+    - work/done/ — completed tickets + DONE notes
+    - work/briefs/ — writing briefs
+    - work/outlines/ — outlines
+    - work/drafts/ — drafts
+    - work/edited/ — edited drafts
+    - outbox/ — finalized deliverables
+
+    ## Dispatch loop
+    1) Intake in inbox/
+    2) Brief in work/briefs/
+    3) Assign outline → draft
+    4) Move to work/testing/ for edit/review
+    5) After verification (see notes/QA_CHECKLIST.md), move to work/done/ and finalize to outbox/
+
+  outliner.soul: |
+    # SOUL.md
+
+    You are an Outliner on {{teamId}}.
+
+    You produce strong structure before drafting.
+
+  outliner.agents: |
+    # AGENTS.md
+
+    Team directory: {{teamDir}}
+
+    Output conventions:
+    - Write outlines in work/outlines/
+    - Include:
+      - target audience
+      - thesis
+      - sections (H2/H3)
+      - key points per section
+
+  writer.soul: |
+    # SOUL.md
+
+    You are a Writer on {{teamId}}.
+
+    You draft quickly and clearly, matching the requested tone.
+
+  writer.agents: |
+    # AGENTS.md
+
+    Team directory: {{teamDir}}
+
+    Output conventions:
+    - Drafts go in work/drafts/
+    - Put assumptions and open questions at the top.
+
+  editor.soul: |
+    # SOUL.md
+
+    You are an Editor on {{teamId}}.
+
+    You polish drafts for clarity, structure, and punch.
+
+  editor.agents: |
+    # AGENTS.md
+
+    Team directory: {{teamDir}}
+
+    Output conventions:
+    - Edited drafts go in work/edited/
+    - Provide a short changelog at the top.
+    - Flag any factual claims that need citations.
+
+    ## QA verification
+    Before a deliverable is marked done/published:
+    - Record verification using notes/QA_CHECKLIST.md.
+    - Preferred: create work/testing/<ticket>.testing-verified.md.
+
+  lead.tools: |
+    # TOOLS.md
+
+    # Agent-local notes for lead (paths, conventions, env quirks).
+
+  lead.status: |
+    # STATUS.md
+
+    - (empty)
+
+  lead.notes: |
+    # NOTES.md
+
+    - (empty)
+
+  outliner.tools: |
+    # TOOLS.md
+
+    # Agent-local notes for outliner (paths, conventions, env quirks).
+
+  outliner.status: |
+    # STATUS.md
+
+    - (empty)
+
+  outliner.notes: |
+    # NOTES.md
+
+    - (empty)
+
+  writer.tools: |
+    # TOOLS.md
+
+    # Agent-local notes for writer (paths, conventions, env quirks).
+
+  writer.status: |
+    # STATUS.md
+
+    - (empty)
+
+  writer.notes: |
+    # NOTES.md
+
+    - (empty)
+
+  editor.tools: |
+    # TOOLS.md
+
+    # Agent-local notes for editor (paths, conventions, env quirks).
+
+  editor.status: |
+    # STATUS.md
+
+    - (empty)
+
+  editor.notes: |
+    # NOTES.md
+
+    - (empty)
+
+files:
+  - path: SOUL.md
+    template: soul
+    mode: createOnly
+  - path: AGENTS.md
+    template: agents
+    mode: createOnly
+  - path: TOOLS.md
+    template: tools
+    mode: createOnly
+  - path: STATUS.md
+    template: status
+    mode: createOnly
+  - path: NOTES.md
+    template: notes
+    mode: createOnly
+
+tools:
+  profile: "coding"
+  allow: ["group:fs", "group:web"]
+  deny: ["exec"]
+---
+# Writing Team Recipe
+
+A lightweight writing pipeline that pairs briefs/outlines/drafts/edits with a file-first ticket workflow.

package/src/lib/bindings.ts

@@ -0,0 +1,59 @@
+// Minimal extracted binding helper so we can test precedence without running the CLI.
+
+import crypto from 'node:crypto';
+
+export type BindingMatch = {
+  channel?: string;
+  peer?: string;
+  [k: string]: any;
+};
+
+export type BindingSnippet = {
+  agentId: string;
+  match: BindingMatch;
+  to: any;
+  enabled?: boolean;
+};
+
+function stableStringify(obj: any) {
+  const seen = new WeakSet();
+  const walk = (x: any): any => {
+    if (x && typeof x === 'object') {
+      if (seen.has(x)) return '[Circular]';
+      seen.add(x);
+      if (Array.isArray(x)) return x.map(walk);
+      const keys = Object.keys(x).sort();
+      const out: any = {};
+      for (const k of keys) out[k] = walk(x[k]);
+      return out;
+    }
+    return x;
+  };
+  return JSON.stringify(walk(obj));
+}
+
+export function upsertBindingInConfig(cfgObj: any, binding: BindingSnippet) {
+  if (!Array.isArray(cfgObj.bindings)) cfgObj.bindings = [];
+  const list: any[] = cfgObj.bindings;
+
+  const sigPayload = stableStringify({ agentId: binding.agentId, match: binding.match });
+  const sig = crypto.createHash('sha256').update(sigPayload).digest('hex');
+
+  const idx = list.findIndex((b: any) => {
+    const payload = stableStringify({ agentId: b.agentId, match: b.match });
+    const bsig = crypto.createHash('sha256').update(payload).digest('hex');
+    return bsig === sig;
+  });
+
+  if (idx >= 0) {
+    // Update in place (preserve ordering)
+    list[idx] = { ...list[idx], ...binding };
+    return { changed: false as const, note: 'already-present' as const };
+  }
+
+  // Most-specific-first: if a peer match is specified, insert at front so it wins.
+  if (binding.match?.peer) list.unshift(binding);
+  else list.push(binding);
+
+  return { changed: true as const, note: 'added' as const };
+}

package/src/lib/cleanup-workspaces.ts

@@ -0,0 +1,173 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export type CleanupDecision =
+  | { kind: 'candidate'; teamId: string; dirName: string; absPath: string }
+  | { kind: 'skip'; teamId?: string; dirName: string; absPath: string; reason: string };
+
+export type CleanupPlan = {
+  rootDir: string;
+  prefixes: string[];
+  protectedTeamIds: string[];
+  decisions: CleanupDecision[];
+};
+
+export const DEFAULT_ALLOWED_PREFIXES = ['smoke-', 'qa-', 'tmp-', 'test-'] as const;
+export const DEFAULT_PROTECTED_TEAM_IDS = ['development-team'] as const;
+
+async function isDir(p: string) {
+  try {
+    const st = await fs.stat(p);
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Refuse to operate on symlinks (for safety). */
+async function isSymlink(p: string) {
+  try {
+    const st = await fs.lstat(p);
+    return st.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export function parseTeamIdFromWorkspaceDirName(dirName: string) {
+  if (!dirName.startsWith('workspace-')) return null;
+  const teamId = dirName.slice('workspace-'.length);
+  return teamId || null;
+}
+
+export function isEligibleTeamId(opts: { teamId: string; prefixes: string[]; protectedTeamIds: string[] }) {
+  const { teamId, prefixes, protectedTeamIds } = opts;
+
+  if (!teamId.endsWith('-team')) return { ok: false, reason: 'teamId does not end with -team' } as const;
+
+  if (protectedTeamIds.includes(teamId.replace(/-team$/, ''))) {
+    // Back-compat: protect by base id too if someone passes development-team-team etc.
+    return { ok: false, reason: 'protected teamId' } as const;
+  }
+  if (protectedTeamIds.includes(teamId)) return { ok: false, reason: 'protected teamId' } as const;
+
+  const okPrefix = prefixes.some((p) => teamId.startsWith(p));
+  if (!okPrefix) return { ok: false, reason: `teamId does not start with an allowed prefix (${prefixes.join(', ')})` } as const;
+
+  return { ok: true } as const;
+}
+
+/**
+ * Build a safe cleanup plan for workspace-<teamId> directories under rootDir.
+ *
+ * Safety rails:
+ * - only directories named workspace-<teamId>
+ * - teamId must end with -team and start with an allowed prefix
+ * - protected teamIds are always skipped
+ * - refuses symlinks
+ * - resolved path must remain within rootDir
+ */
+export async function planWorkspaceCleanup(opts: {
+  rootDir: string;
+  prefixes?: string[];
+  protectedTeamIds?: string[];
+}) {
+  const rootDir = path.resolve(opts.rootDir);
+  const prefixes = (opts.prefixes?.length ? opts.prefixes : [...DEFAULT_ALLOWED_PREFIXES]) as string[];
+  const protectedTeamIds = (opts.protectedTeamIds?.length ? opts.protectedTeamIds : [...DEFAULT_PROTECTED_TEAM_IDS]) as string[];
+
+  const decisions: CleanupDecision[] = [];
+
+  let entries: string[] = [];
+  try {
+    entries = await fs.readdir(rootDir);
+  } catch (e: any) {
+    return {
+      rootDir,
+      prefixes,
+      protectedTeamIds,
+      decisions: [
+        {
+          kind: 'skip',
+          dirName: rootDir,
+          absPath: rootDir,
+          reason: `failed to read rootDir: ${e?.message ? String(e.message) : String(e)}`,
+        },
+      ],
+    } satisfies CleanupPlan;
+  }
+
+  for (const dirName of entries) {
+    if (!dirName.startsWith('workspace-')) continue;
+
+    const absPath = path.join(rootDir, dirName);
+
+    if (!(await isDir(absPath))) continue;
+
+    const teamId = parseTeamIdFromWorkspaceDirName(dirName);
+    if (!teamId) {
+      decisions.push({ kind: 'skip', dirName, absPath, reason: 'could not parse teamId' });
+      continue;
+    }
+
+    if (await isSymlink(absPath)) {
+      decisions.push({ kind: 'skip', teamId, dirName, absPath, reason: 'refusing to operate on symlink' });
+      continue;
+    }
+
+    const real = await fs.realpath(absPath);
+    const rootReal = await fs.realpath(rootDir);
+    if (!real.startsWith(rootReal + path.sep) && real !== rootReal) {
+      decisions.push({ kind: 'skip', teamId, dirName, absPath, reason: 'resolved path escapes rootDir' });
+      continue;
+    }
+
+    const elig = isEligibleTeamId({ teamId, prefixes, protectedTeamIds });
+    if (!elig.ok) {
+      decisions.push({ kind: 'skip', teamId, dirName, absPath, reason: elig.reason });
+      continue;
+    }
+
+    decisions.push({ kind: 'candidate', teamId, dirName, absPath });
+  }
+
+  return { rootDir, prefixes, protectedTeamIds, decisions } satisfies CleanupPlan;
+}
+
+export async function executeWorkspaceCleanup(plan: CleanupPlan, opts: { yes: boolean }) {
+  const candidates = plan.decisions.filter((d): d is Extract<CleanupDecision, { kind: 'candidate' }> => d.kind === 'candidate');
+  const skipped = plan.decisions.filter((d): d is Extract<CleanupDecision, { kind: 'skip' }> => d.kind === 'skip');
+
+  if (!opts.yes) {
+    return {
+      ok: true,
+      dryRun: true,
+      rootDir: plan.rootDir,
+      candidates,
+      skipped,
+      deleted: [] as string[],
+    };
+  }
+
+  const deleted: string[] = [];
+  const deleteErrors: Array<{ path: string; error: string }> = [];
+
+  for (const c of candidates) {
+    try {
+      await fs.rm(c.absPath, { recursive: true, force: true });
+      deleted.push(c.absPath);
+    } catch (e: any) {
+      deleteErrors.push({ path: c.absPath, error: e?.message ? String(e.message) : String(e) });
+    }
+  }
+
+  return {
+    ok: deleteErrors.length === 0,
+    dryRun: false,
+    rootDir: plan.rootDir,
+    candidates,
+    skipped,
+    deleted,
+    deleteErrors,
+  };
+}

package/src/lib/index.ts

@@ -0,0 +1,5 @@
+export * from './scaffold-templates';
+export * from './bindings';
+export * from './ticket-workflow';
+export * from './recipe-frontmatter';
+export * from './shared-context';