@aksp/opencrew 1.0.0

package/templates/skills/instagram-publisher/scripts/publish.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Instagram Carousel Publisher
+// Usage: node --env-file=.env publish.js --images "slide1.jpg,slide2.jpg" --caption "..." [--dry-run]
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ── Argument parsing ──────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const args = { images: [], caption: '', dryRun: false };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--images') {
+      if (i + 1 < argv.length) args.images = argv[++i].split(',').map(s => s.trim());
+    }
+    else if (argv[i] === '--caption') {
+      if (i + 1 < argv.length) args.caption = argv[++i];
+    }
+    else if (argv[i] === '--dry-run') args.dryRun = true;
+  }
+  return args;
+}
+
+// ── Image upload (imgBB) ──────────────────────────────────────
+
+export async function uploadToImgBB(imagePath, apiKey) {
+  const absolutePath = resolve(imagePath);
+  const fileBuffer = readFileSync(absolutePath);
+  const base64Image = fileBuffer.toString('base64');
+  const form = new FormData();
+  form.append('key', apiKey);
+  form.append('image', base64Image);
+  const res = await fetch('https://api.imgbb.com/1/upload', {
+    method: 'POST',
+    body: form,
+  });
+  if (!res.ok) throw new Error(`imgBB upload failed [${res.status}]: ${await res.text()}`);
+  const json = await res.json();
+  if (!json.success) throw new Error(`imgBB upload failed: ${JSON.stringify(json)}`);
+  return json.data.url;
+}
+
+// ── Instagram Graph API ───────────────────────────────────────
+
+const IG_BASE = 'https://graph.facebook.com/v21.0';
+
+export async function createChildContainer(userId, imageUrl, accessToken) {
+  const params = new URLSearchParams({
+    image_url: imageUrl,
+    is_carousel_item: 'true',
+    access_token: accessToken,
+  });
+  const res = await fetch(`${IG_BASE}/${userId}/media?${params}`, { method: 'POST' });
+  if (!res.ok) throw new Error(`createChildContainer failed [${res.status}]: ${await res.text()}`);
+  return (await res.json()).id;
+}
+
+export async function getContainerStatus(containerId, accessToken) {
+  const params = new URLSearchParams({ fields: 'status_code', access_token: accessToken });
+  const res = await fetch(`${IG_BASE}/${containerId}?${params}`);
+  if (!res.ok) throw new Error(`getContainerStatus failed [${res.status}]: ${await res.text()}`);
+  return (await res.json()).status_code;
+}
+
+export async function pollUntilFinished(containerId, accessToken, timeoutMs = 60_000, intervalMs = 3_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const status = await getContainerStatus(containerId, accessToken);
+    if (status === 'FINISHED') return;
+    if (status === 'ERROR') throw new Error(`Container ${containerId} entered ERROR state`);
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  throw new Error(`Container ${containerId} timed out after ${timeoutMs}ms`);
+}
+
+export async function createCarouselContainer(userId, childIds, caption, accessToken) {
+  const params = new URLSearchParams({
+    media_type: 'CAROUSEL',
+    children: childIds.join(','),
+    caption,
+    access_token: accessToken,
+  });
+  const res = await fetch(`${IG_BASE}/${userId}/media?${params}`, { method: 'POST' });
+  if (!res.ok) throw new Error(`createCarouselContainer failed [${res.status}]: ${await res.text()}`);
+  return (await res.json()).id;
+}
+
+export async function publishMedia(userId, containerId, accessToken) {
+  const params = new URLSearchParams({ creation_id: containerId, access_token: accessToken });
+  const res = await fetch(`${IG_BASE}/${userId}/media_publish?${params}`, { method: 'POST' });
+  if (!res.ok) throw new Error(`publishMedia failed [${res.status}]: ${await res.text()}`);
+  return (await res.json()).id;
+}
+
+export async function getPermalink(mediaId, accessToken) {
+  const params = new URLSearchParams({ fields: 'permalink', access_token: accessToken });
+  const res = await fetch(`${IG_BASE}/${mediaId}?${params}`);
+  if (!res.ok) return null; // non-fatal — just skip the URL display
+  const json = await res.json();
+  return json.permalink ?? null;
+}
+
+// ── Main ──────────────────────────────────────────────────────
+
+async function main() {
+  const { images, caption, dryRun } = parseArgs(process.argv);
+
+  if (!images.length) throw new Error('--images is required (e.g. --images "slide1.jpg,slide2.jpg")');
+  if (!caption) throw new Error('--caption is required');
+  if (images.length < 2 || images.length > 10) {
+    throw new Error(`Instagram carousels require 2–10 images (got ${images.length})`);
+  }
+  if (caption.length > 2200) {
+    throw new Error(`Caption exceeds Instagram's 2200-character limit (got ${caption.length})`);
+  }
+
+  const { INSTAGRAM_ACCESS_TOKEN, INSTAGRAM_USER_ID, IMGBB_API_KEY } = process.env;
+  if (!INSTAGRAM_ACCESS_TOKEN) throw new Error('INSTAGRAM_ACCESS_TOKEN is not set in environment');
+  if (!INSTAGRAM_USER_ID) throw new Error('INSTAGRAM_USER_ID is not set in environment');
+  if (!IMGBB_API_KEY) throw new Error('IMGBB_API_KEY is not set in environment. Get one at https://api.imgbb.com/');
+
+  console.log(`📸 Uploading ${images.length} image(s) to imgBB...`);
+  const imageUrls = await Promise.all(images.map(p => uploadToImgBB(p, IMGBB_API_KEY)));
+  imageUrls.forEach((url, i) => console.log(`   [${i + 1}] ${url}`));
+
+  console.log('\n📦 Creating Instagram media containers...');
+  const childIds = await Promise.all(
+    imageUrls.map(url => createChildContainer(INSTAGRAM_USER_ID, url, INSTAGRAM_ACCESS_TOKEN))
+  );
+  console.log(`   Container IDs: ${childIds.join(', ')}`);
+
+  console.log('\n⏳ Waiting for containers to finish processing...');
+  await Promise.all(childIds.map(id => pollUntilFinished(id, INSTAGRAM_ACCESS_TOKEN)));
+  console.log('   All containers ready.');
+
+  console.log('\n🎠 Creating carousel container...');
+  const carouselId = await createCarouselContainer(
+    INSTAGRAM_USER_ID, childIds, caption, INSTAGRAM_ACCESS_TOKEN
+  );
+  await pollUntilFinished(carouselId, INSTAGRAM_ACCESS_TOKEN);
+  console.log(`   Carousel container ID: ${carouselId}`);
+
+  if (dryRun) {
+    console.log('\n✅ DRY RUN complete — skipping final publish call.');
+    console.log(`   Carousel container ready: ${carouselId}`);
+    return;
+  }
+
+  console.log('\n🚀 Publishing to Instagram...');
+  const postId = await publishMedia(INSTAGRAM_USER_ID, carouselId, INSTAGRAM_ACCESS_TOKEN);
+  const permalink = await getPermalink(postId, INSTAGRAM_ACCESS_TOKEN);
+  console.log(`\n✅ Published successfully!`);
+  console.log(`   Post ID: ${postId}`);
+  if (permalink) console.log(`   URL: ${permalink}`);
+}
+
+// Run only when executed directly (not when imported for tests)
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch(err => {
+    console.error(`\n❌ ${err.message}`);
+    process.exit(1);
+  });
+}

package/templates/skills/opencrew-best-practice-creator/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: "Best-Practice Creator"
+description: >
+  Guides creation and maintenance of best-practice files for the opencrew best-practices library.
+  Handles format validation, cross-references, versioning, and catalog consistency.
+description_pt-BR: >
+  Guia a criação e manutenção de arquivos de best-practice na biblioteca de best-practices do opencrew.
+  Cuida de validação de formato, referências cruzadas, versionamento e consistência do catálogo.
+description_es: >
+  Guía la creación y mantenimiento de archivos de best-practice en la biblioteca de best-practices de opencrew.
+  Maneja validación de formato, referencias cruzadas, versionamiento y consistencia del catálogo.
+type: prompt
+version: "2.0.0"
+---
+
+# Best-Practice Creator — Workflow
+
+Use this workflow when creating a new best-practice file for the `_opencrew/core/best-practices/` library.
+
+## Pre-flight Checks
+
+1. **Scan existing best-practice files**: Read `_opencrew/core/best-practices/_catalog.yaml`. Extract `id`, `name`, `whenToUse`, `file` from each entry.
+2. **Check for overlap**: Verify the new best-practice file doesn't duplicate an existing entry's `whenToUse` scope. If there's overlap, clarify the differentiation before proceeding.
+3. **List available skills**: Read all `skills/*/SKILL.md` files. Extract `name`, `description`, `type` from each — these may inform the best-practice file's content.
+
+## Creation Checklist
+
+For each new best-practice file, ensure ALL of the following:
+
+### Frontmatter (YAML)
+
+- [ ] `id`: lowercase kebab-case (e.g., `copywriting`)
+- [ ] `name`: Display name for catalog listing (e.g., `"Copywriting & Persuasive Writing"`)
+- [ ] `whenToUse`: Multi-line with positive scope AND "NOT for: ..." negative scope referencing other best-practice IDs
+- [ ] `version`: `"1.0.0"` for new best-practice files
+
+### Body (Markdown) — All sections mandatory
+
+- [ ] **Core Principles**: 6+ numbered domain-specific decision rules, each with a bold title and detailed explanation
+- [ ] **Techniques & Frameworks**: Concrete methods, models, or processes practitioners use in this discipline (e.g., diagnostic steps, framework selections, structural patterns)
+- [ ] **Quality Criteria**: 4+ checkable criteria as `- [ ]` list that can be used to evaluate output
+- [ ] **Output Examples**: 2+ complete examples, 15+ lines each, realistic NOT template-like
+- [ ] **Anti-Patterns**: Never Do (4+) + Always Do (3+), each with explanation
+- [ ] **Vocabulary Guidance**: Terms/phrases to Always Use (5+), Terms/phrases to Never Use (3+), Tone Rules (2+)
+
+### Quality Minimums
+
+| Section | Minimum |
+|---------|---------|
+| Total file lines | 200+ |
+| Core Principles | 6+ numbered rules |
+| Techniques & Frameworks | 3+ concrete techniques |
+| Vocabulary Always Use | 5+ terms |
+| Vocabulary Never Use | 3+ terms |
+| Output Examples | 2 complete, 15+ lines each |
+| Anti-Patterns (Never Do) | 4+ |
+| Anti-Patterns (Always Do) | 3+ |
+| Quality Criteria | 4+ checkable items |
+
+## Post-Creation Steps
+
+### 1. Update existing best-practice files' `whenToUse`
+
+For each existing best-practice file whose scope overlaps with the new one:
+- Add a "NOT for: {overlapping-scope} → See {new-best-practice-id}" line to their `whenToUse`
+- Bump their version (patch increment)
+
+### 2. Update `_catalog.yaml`
+
+Add a new entry to `_opencrew/core/best-practices/_catalog.yaml` with:
+- `id`: matching the frontmatter `id`
+- `name`: matching the frontmatter `name`
+- `whenToUse`: single-line summary of the scope (positive only, no "NOT for")
+- `file`: `{id}.md`
+
+Place it under the appropriate section comment (Discipline or Platform best practices).
+
+### 3. File placement
+
+Save to `_opencrew/core/best-practices/{id}.md`.
+
+### 4. Validation
+
+Re-read the created file and verify:
+- [ ] All checklist items above are present
+- [ ] YAML frontmatter parses correctly (no syntax errors)
+- [ ] `whenToUse` references only existing best-practice IDs
+- [ ] Output examples are realistic, not template placeholders
+- [ ] File exceeds 200 lines
+- [ ] Corresponding entry exists in `_catalog.yaml`
+
+---
+
+# Best-Practice Updater — Workflow
+
+Use this workflow when updating best-practice files in the `_opencrew/core/best-practices/` library.
+
+## Versioning Rules (Semver)
+
+| Change Type | Version Bump | Examples |
+|-------------|-------------|----------|
+| **Patch** (x.x.X) | Fix typos, adjust wording, minor refinements | Fix anti-pattern phrasing, correct a vocabulary term |
+| **Minor** (x.X.0) | Add new content, extend capabilities | Add new principle, new output example, new technique |
+| **Major** (X.0.0) | Rewrite or restructure significantly | Rewrite core principles, fundamentally change scope |
+
+Always update the `version` field in the YAML frontmatter after any change.
+
+## Update Scenarios
+
+### When a best-practice file is removed from the library
+
+1. Get the removed best-practice file's `id`
+2. Remove its entry from `_opencrew/core/best-practices/_catalog.yaml`
+3. Scan ALL remaining best-practice files in `_opencrew/core/best-practices/*.md`
+4. For each file, check if the removed ID is referenced in `whenToUse`
+   - Look for patterns: "NOT for: ... → See {removed-id}"
+5. If found, remove that "NOT for" line
+6. Bump the affected files' version (patch: x.x.X)
+
+### When a new best-practice file is added to the library
+
+The Best-Practice Creator workflow (above) handles the initial `whenToUse` cross-references during creation. This section is only needed if cross-references were missed or need adjustment after the fact.
+
+1. Read the new best-practice file's `whenToUse` — identify its scope
+2. Scan existing best-practice files for overlapping scope
+3. Add "NOT for: {new-scope} → See {new-id}" where appropriate
+4. Bump affected files' version (patch)
+5. Ensure the new entry exists in `_catalog.yaml`
+
+### When updating a best-practice file's content
+
+1. Make the content changes
+2. Verify ALL mandatory sections still exist:
+   - [ ] Core Principles (6+ rules)
+   - [ ] Techniques & Frameworks (3+ techniques)
+   - [ ] Quality Criteria (4+ checkable items)
+   - [ ] Output Examples (2+ complete examples)
+   - [ ] Anti-Patterns (Never Do + Always Do)
+   - [ ] Vocabulary Guidance (Always Use, Never Use, Tone Rules)
+3. Bump version according to semver rules above
+4. If the `whenToUse` scope changed, update cross-references in other best-practice files and in `_catalog.yaml`
+
+### When updating a best-practice file's `whenToUse` scope
+
+This is the most impactful change — it affects how the Architect selects best practices during crew creation.
+
+1. Document the old scope and new scope
+2. Update the best-practice file's `whenToUse` field
+3. Scan ALL other best-practice files' `whenToUse` for references to this ID
+4. Update cross-references to reflect the new scope
+5. Update the `whenToUse` summary in `_catalog.yaml`
+6. Bump version (minor if scope expanded, patch if scope narrowed)
+
+## Validation Checklist
+
+After ANY update, verify:
+
+- [ ] Version was bumped correctly (patch/minor/major per rules above)
+- [ ] All mandatory sections still present and non-empty
+- [ ] `whenToUse` cross-references are consistent across ALL best-practice files
+- [ ] No broken cross-references to removed best-practice IDs
+- [ ] Output examples are still realistic and complete
+- [ ] File still exceeds 200 lines minimum
+- [ ] `_catalog.yaml` entry is in sync with frontmatter (`id`, `name`, `whenToUse`)
+
+## Bulk Operations
+
+### Verify catalog consistency
+
+```
+Read _opencrew/core/best-practices/_catalog.yaml
+For each entry in catalog:
+  1. Verify _opencrew/core/best-practices/{entry.file} exists
+  2. Read the file's frontmatter
+  3. Verify entry.id matches frontmatter id
+  4. Verify entry.name matches frontmatter name
+  5. Flag any mismatches
+
+For each .md file in _opencrew/core/best-practices/ (excluding _catalog.yaml):
+  1. Verify a corresponding entry exists in _catalog.yaml
+  2. Flag any orphaned files with no catalog entry
+```
+
+### Verify cross-reference consistency
+
+```
+For each best-practice file A in _opencrew/core/best-practices/*.md:
+  For each "NOT for: ... → See {id}" in A.whenToUse:
+    1. Verify _opencrew/core/best-practices/{id}.md exists
+    2. Verify {id}'s whenToUse covers the referenced scope
+    3. Flag inconsistencies
+```