**Category:** <category> | **ID:** `<hack-id>` ### Problem <problem text> ### Solution <solution text> ### Code <code block> ### Benefit <benefit text> ### When to Use <when-to-use text> --- Found this useful? Share your own: `/genie-hacks contribute` Full docs: https://docs.automagik.dev/genie/hacks ``` If not found: `Hack "<id>" not found. Did you mean: <suggest closest IDs>? Run /genie-hacks list to see all.` ## Command: `help <problem>` Fuzzy-match a problem description to relevant hacks. Extract keywords, score by overlap across all fields, show top 3. **Keyword mapping hints:** - "speed", "fast", "slow" → provider-switching, cost-optimization - "cost", "expensive", "budget", "tokens" → cost-optimization, provider-switching - "team", "parallel", "coordinate", "multiple" → team-coordination, overnight-batch - "overnight", "batch", "sleep", "queue" → overnight-batch, team-coordination - "repeat", "workflow", "automate", "reuse" → custom-skills, hook-automation - "hook", "event", "trigger", "auto" → hook-automation, custom-skills - "slack", "ci", "integrate", "notify" → integration-patterns - "stuck", "debug", "broken", "error", "fail" → debugging-tips - "codex", "claude", "model", "provider" → provider-switching - "dream", "night", "unattended" → overnight-batch **Output format:** ``` Based on your problem: "<problem>" Best matches: 1. [provider-switching] Provider Switching — Right Model for the Job Why: Matches your need for speed/cost optimization across providers Quick tip: Use `genie agent spawn engineer --provider codex` for fast scaffolding 2. [cost-optimization] Cost Optimization Strategies Why: Directly addresses cost reduction techniques Quick tip: Scope wishes tightly and use `/refine` before dispatching 3. [team-coordination] Multi-Team Coordination at Scale Why: Parallel execution reduces wall-clock time Quick tip: Use `/dream` for batch overnight execution Run `/genie-hacks show <id>` for full details on any hack. ``` If no reasonable matches: `No hacks closely match your problem. Try describing it differently, or run /genie-hacks list to browse all. Got a solution? Run /genie-hacks contribute!` ## Command: `contribute` ### Overview Guide the user through contributing a new hack to the community docs via an automated PR to `automagik-dev/docs`. This is the full end-to-end flow. ### Step 1: Gather Hack Details Prompt the user for each field interactively. Wait for each response before proceeding. **Prompt sequence:** 1. **Title**: "What's your hack title? (short, descriptive)" - Example: "Provider Switching for Speed vs Safety" 2. **Problem**: "What problem does it solve? (1-2 sentences)" - Example: "Different tasks need different AI providers — speed for scaffolding, careful reasoning for security-sensitive code." 3. **Solution**: "How does it work? Show the commands, config, or code. (Use code blocks)" - Example: multi-line code block with genie commands 4. **Category**: "What category? Pick one: `providers` | `teams` | `skills` | `hooks` | `cost` | `integration` | `debugging` | `batch` | `other`" - Validate input is one of the allowed categories. If invalid, re-prompt. 5. **Benefit**: "What's the key benefit? (one line)" - Example: "Right tool for each job — 3x faster scaffolding, safer reviews." 6. **When to use**: "When should someone use this? (one line)" - Example: "When your project has both speed-critical and safety-critical tasks." ### Step 2: Preview & Confirm Format the hack in the standard template and show the user: ```markdown ### <Title> **ID:** `<generated-id>` **Category:** <category> **Problem:** <problem> **Solution:** <solution with code blocks> **Benefit:** <benefit> **When to use:** <when> ``` Ask: "Does this look good? (yes/edit/cancel)" - **yes** → proceed to Step 3 - **edit** → ask which field to change, re-prompt for that field, re-preview - **cancel** → abort with "No worries! Run `/genie-hacks contribute` anytime." ### Step 3: GitHub CLI Preflight Run these checks in order. Stop at first failure with a helpful error. ```bash # 1. Check gh is installed command -v gh >/dev/null 2>&1 # If missing: "GitHub CLI (gh) is required. Install: https://cli.github.com/" # 2. Check gh is authenticated gh auth status 2>&1 # If not authenticated: "Run `gh auth login` to authenticate with GitHub first." # 3. Check git is available command -v git >/dev/null 2>&1 # If missing: "git is required but not found in PATH." ``` If any check fails, display the error message and suggest manual steps: ``` Manual contribution steps: 1. Fork https://github.com/automagik-dev/docs 2. Edit genie/hacks.mdx — add your hack in the correct category section 3. Commit: git commit -m "hack: <title>" 4. Open PR to automagik-dev/docs (base: dev) ``` ### Step 4: Fork & Clone ```bash # Cache directory for docs repo DOCS_CACHE="$HOME/.genie/cache/docs-fork" # Fork the docs repo (idempotent — no-op if already forked) gh repo fork automagik-dev/docs --clone=false 2>/dev/null || true # Get the user's GitHub username for the fork URL GH_USER=$(gh api user --jq '.login') # Clone or update the cached fork if [ -d "$DOCS_CACHE/.git" ]; then cd "$DOCS_CACHE" git fetch origin git checkout dev git pull origin dev else gh repo clone "$GH_USER/docs" "$DOCS_CACHE" -- --branch dev cd "$DOCS_CACHE" git remote add upstream https://github.com/automagik-dev/docs.git 2>/dev/null || true git fetch upstream fi # Create a branch for the hack BRANCH="hack/$(echo '<title>' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')" git checkout -b "$BRANCH" origin/dev ``` If clone/fork fails, show the error and fall back to manual steps (same as Step 3 fallback). ### Step 5: Append Hack to hacks.mdx Read `genie/hacks.mdx` from the cloned repo. Find the correct category section (look for `## <Category>` heading — e.g., `## Providers`, `## Teams`, etc.). Append the new hack entry just before the next `## ` heading or at the end of the category section. If the category section doesn't exist (e.g., for `other`), append a new section at the end of the file, before the Contributing section: ```markdown ## Other ### <Title> **ID:** `<generated-id>` **Problem:** <problem> **Solution:** <solution> **Benefit:** <benefit> **When to use:** <when> --- ``` ### Step 6: Commit & Push ```bash cd "$DOCS_CACHE" git add genie/hacks.mdx git commit -m "hack: <title>" git push -u origin "$BRANCH" ``` ### Step 7: Create PR ```bash # Create PR targeting the dev branch of the upstream docs repo PR_URL=$(gh pr create \ --repo automagik-dev/docs \ --base dev \ --head "$GH_USER:$BRANCH" \ --title "hack: <title>" \ --body "$(cat <<'PREOF' ## New Community Hack **Title:** <title> **Category:** <category> **Problem:** <problem> **Solution:** <solution summary> **Benefit:** <benefit> **When to use:** <when> --- *Submitted via `/genie-hacks contribute`* PREOF )") echo "PR created: $PR_URL" ``` ### Step 8: Success Display the result to the user: ``` Your hack has been submitted! PR: <PR_URL> Title: hack: <title> Target: automagik-dev/docs (dev branch) What happens next: - A maintainer will review your hack - They may suggest edits via PR comments - Once approved, it'll appear on the hacks page Thank you for contributing to the Genie community! Join the discussion on Discord: https://discord.gg/automagik ``` ### Error Recovery At any point if a step fails: | Error | Recovery | |-------|----------| | `gh` not installed | Show install URL, fall back to manual steps | | `gh` not authenticated | Show `gh auth login` command | | Fork fails | Check if fork already exists with `gh repo view $GH_USER/docs` | | Clone fails | Remove cache dir and retry: `rm -rf $DOCS_CACHE && gh repo clone ...` | | `hacks.mdx` not found | Create a new one with the standard template header | | Push fails (auth) | Suggest `gh auth refresh` or SSH key setup | | PR creation fails | Show the branch/commit info so user can create PR manually via GitHub web UI | | Editor fails | Write the hack content to a temp file, show the path for manual copy | ### Offline / Manual Fallback If GitHub operations fail entirely, save the hack locally and guide the user: ```bash # Save hack to local file mkdir -p ~/.genie/cache/pending-hacks cat > ~/.genie/cache/pending-hacks/<hack-id>.md << 'EOF' <formatted hack content> EOF ``` Then display: ``` Saved your hack locally at: ~/.genie/cache/pending-hacks/<hack-id>.md To submit manually: 1. Fork https://github.com/automagik-dev/docs 2. Copy the hack content into genie/hacks.mdx under the "<category>" section 3. Commit with message: "hack: <title>" 4. Open PR targeting the `dev` branch ``` ## Categories Reference | Category | ID | Description | |----------|----|-------------| | Providers | `providers` | Provider switching, model selection, BYOA | | Teams | `teams` | Multi-agent coordination, team patterns | | Skills | `skills` | Custom skills, skill chains, automation | | Hooks | `hooks` | Git hooks, auto-spawn, event-driven flows | | Cost | `cost` | Token optimization, model routing, budget control | | Integration | `integration` | External tools, APIs, CI/CD, Slack, etc. | | Debugging | `debugging` | Agent debugging, tracing, fixing bad behavior | | Batch | `batch` | Overnight execution, queued processing | | Other | `other` | Uncategorized community patterns | ## Docs Cache The docs repo is cached at `~/.genie/cache/docs-fork/` to avoid re-cloning on every contribute. The cache is updated (`git pull`) on each contribute invocation. If the cache becomes corrupted, delete it and re-run — the contribute flow will re-clone automatically. ## Rules - All hack IDs are lowercase kebab-case. - Never invent hacks that don't exist in the registry — only show what's listed above. - For `help`, always try to find at least one relevant hack. Only say "no matches" if truly nothing fits. - Keep output concise — tables for `list`, full format only for `show`. - Always end `list` and `show` with a nudge toward `contribute`. - The `contribute` command should be friendly and low-friction — one question at a time. - Link to Discord (https://discord.gg/automagik) for community discussion. - Link to docs (https://docs.automagik.dev/genie/hacks) for the full hacks page. - Always target the `dev` branch for PRs — never `main`/`master`. - Hack IDs must be unique — check existing IDs before appending. - All hacks must be realistic and tested — do not submit aspirational or untested patterns. - Preserve the standard format: problem, solution, code, benefit, when to use. - Keep code examples concise — show the minimum needed to understand the hack. --- > Source: [automagik-dev/genie](https://github.com/automagik-dev/genie) — distributed by [TomeVault](https://tomevault.io). <!-- tomevault:4.0:skill

# Genie Hacks > Browse, search, and contribute community hacks — real-world patterns for provider switching, teams, skills, hooks, cost optimization, and more. Use when this capability is needed. - Skill: `tomevault-io/genie-hacks` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/genie-hacks` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/genie-hacks/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/genie-hacks --- # /genie-hacks — Community Hacks & Patterns Browse real-world Genie patterns contributed by the community. Search by problem, explore by category, or contribute your own. ## When to Use - User wants to discover Genie tips, tricks, or advanced patterns - User asks "how do I optimize costs?", "how do teams work?", or similar problem-oriented questions - User wants to contribute a hack they discovered - User invokes `/genie-hacks` with any subcommand - If no subcommand is given, default to `list` ## Commands | Command | Description | |---------|-------------| | `/genie-hacks` | List all hacks (same as `list`) | | `/genie-hacks list` | List all hacks with title, problem, and category | | `/genie-hacks search ` | Search hacks by keyword in title/problem/solution | | `/genie-hacks show ` | Display full hack details | | `/genie-hacks contribute` | Submit a new hack via automated PR flow | | `/genie-hacks help ` | Describe a problem, get matched to relevant hacks | --- ## Hacks Registry The canonical hacks live in the docs at `genie/hacks.mdx`. Below is the embedded registry for `list`, `search`, `show`, and `help` commands. Use this data directly — do not require an external file. ### hack: provider-switching - **ID:** `provider-switching` - **Title:** Provider Switching — Right Model for the Job - **Category:** providers - **Problem:** You're using one provider for everything, but some tasks need speed (Codex) and others need precision (Claude). - **Solution:** Use `--provider` flag to switch per-task. Configure provider per agent role in team config. - **Code:** ```bash # Fast scaffolding with Codex genie agent spawn engineer --provider codex # Careful review with Claude genie agent spawn reviewer --provider claude # Team-level: set default per role genie team create my-feature --repo . --wish my-slug genie team hire engineer --provider codex genie team hire reviewer --provider claude ``` - **Benefit:** 2-3x faster scaffolding with Codex, higher-quality reviews with Claude. Match the model to the cognitive demand. - **When to use:** Teams with mixed workloads — boilerplate generation vs. nuanced code review. When cost or speed matters per task. ### hack: team-coordination - **ID:** `team-coordination` - **Title:** Multi-Team Coordination at Scale - **Category:** teams - **Problem:** You have multiple wishes that depend on each other, and running them sequentially wastes time. - **Solution:** Use `/dream` to batch-execute wishes with dependency ordering. Same-layer wishes run in parallel. - **Code:** ```bash # Queue wishes for overnight execution /dream # Or manually create parallel teams genie team create auth-refactor --repo . --wish auth-refactor genie team create api-v2 --repo . --wish api-v2 # Monitor both genie wish status auth-refactor genie wish status api-v2 # Cross-team messaging genie agent send 'auth-refactor is done, you can proceed' --to api-v2-team-lead ``` - **Benefit:** Parallel execution of independent wishes. Overnight batch runs that produce PRs by morning. - **When to use:** Projects with 3+ wishes queued. Sprint planning where multiple features can be parallelized. ### hack: overnight-batch - **ID:** `overnight-batch` - **Title:** Overnight Batch Execution with /dream - **Category:** batch - **Problem:** You have a backlog of approved wishes but limited daytime hours to supervise execution. - **Solution:** Use `/dream` to queue SHIP-ready wishes, set dependency order, and let agents execute overnight. Wake up to PRs and a DREAM-REPORT.md. - **Code:** ```bash # 1. Ensure wishes are in brainstorm.md under "Poured" cat .genie/brainstorm.md # 2. Launch dream run /dream # Select wishes: 1 3 5 (or "all") # Confirm DREAM.md execution plan # Go to sleep # 3. Morning: check results cat .genie/DREAM-REPORT.md gh pr list --author @me ``` - **Benefit:** 8+ hours of unattended execution. Multiple PRs ready for review by morning. - **When to use:** End of day with 2+ SHIP-ready wishes. Sprint velocity needs a boost without more human hours. ### hack: custom-skills - **ID:** `custom-skills` - **Title:** Custom Skills for Repeated Workflows - **Category:** skills - **Problem:** You keep typing the same sequence of commands or giving the same instructions repeatedly. - **Solution:** Create a custom skill in `skills//SKILL.md` with YAML frontmatter. Claude loads it when invoked via `/`. - **Code:** ```bash mkdir -p skills/deploy-check cat > skills/deploy-check/SKILL.md << 'EOF' --- name: deploy-check description: "Pre-deploy checklist — tests, migrations, env vars." --- # /deploy-check 1. Run `bun test` 2. Check migrations: `bunx prisma migrate status` 3. Verify env vars are set 4. Build: `bun run build` 5. Report pass/fail table EOF # Use it /deploy-check ``` - **Benefit:** Encode tribal knowledge as reusable skills. New team members get instant access to workflows. - **When to use:** Any workflow you've explained more than twice. CI-like checks you want to run locally before pushing. ### hack: hook-automation - **ID:** `hook-automation` - **Title:** Git Hook Automation with Genie Hooks - **Category:** hooks - **Problem:** You want agents to automatically react to git events — spawning a reviewer on PR creation, running tests on commit. - **Solution:** Use Genie's hook system and Claude Code hooks in `.claude/settings.json` to trigger actions on events. - **Code:** ```bash # Auto-spawn is built in — set GENIE_AGENT_NAME for dispatch: export GENIE_AGENT_NAME=my-agent # Claude Code hook example (.claude/settings.json): { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo 'Tool being used: Bash'" }] }] } } ``` - **Benefit:** Automated reactions to development events. Less manual orchestration. - **When to use:** Teams wanting CI-like automation within the agent workflow. Projects where wish-to-PR should be fully autonomous. ### hack: cost-optimization - **ID:** `cost-optimization` - **Title:** Cost Optimization Strategies - **Category:** cost - **Problem:** Agent usage costs add up, especially with large teams or long-running dream runs. - **Solution:** Provider switching (Codex for bulk, Claude for review), tight wish scoping, `/refine` for prompt optimization, and usage monitoring. - **Code:** ```bash # 1. Cheaper providers for boilerplate genie team hire engineer --provider codex genie team hire reviewer --provider claude # 2. Tight wish scoping # BAD: "Refactor the entire codebase" # GOOD: "Extract auth middleware into src/middleware/auth.ts" # 3. Refine prompts before dispatching /refine # 4. Monitor token usage genie agent log engineer --transcript --ndjson | jq '.tokens' | paste -sd+ | bc ``` - **Benefit:** 30-50% cost reduction by matching provider to task complexity. Tighter scoping means fewer fix loops. - **When to use:** Budget-conscious teams. High agent concurrency. Before scaling to `/dream` batch runs. ### hack: integration-patterns - **ID:** `integration-patterns` - **Title:** Integration Patterns — Connect Genie to Your Stack - **Category:** integration - **Problem:** You want Genie to integrate with existing tools — Slack notifications, CI/CD pipelines, monitoring. - **Solution:** Use shell commands in skills for custom integrations, GitHub CLI for PR/issue management, webhooks for notifications. - **Code:** ```bash # Post to Slack via webhook curl -X POST "$SLACK_WEBHOOK_URL" \ -H 'Content-Type: application/json' \ -d '{"text": "Genie: wish auth-refactor done. PR #123"}' # Create GitHub issues from findings gh issue create --title "Bug: auth token expiry" \ --body "Found during /trace: refresh fails silently" # Trigger CI after PR gh workflow run ci.yml --ref feat/my-feature ``` - **Benefit:** Genie becomes part of your existing workflow. Notifications go where your team already looks. - **When to use:** Teams with Slack/Discord channels. Projects with CI/CD pipelines that should trigger on agent PRs. ### hack: debugging-tips - **ID:** `debugging-tips` - **Title:** Debugging Agent Issues Like a Pro - **Category:** debugging - **Problem:** An agent is stuck, producing wrong output, or a team isn't making progress. - **Solution:** Use `genie agent log --raw` for live output, `genie agent log --transcript` for transcripts, `/trace` for root cause analysis, and `genie wish reset` for recovery. - **Code:** ```bash # Live agent output genie agent log engineer --raw # Compressed timeline genie agent log engineer --transcript # Filter to tool calls genie agent log engineer --transcript --ndjson | jq 'select(.type == "tool_use") | .name' # Systematic investigation /trace # Check team status genie team ls my-team genie wish status my-wish-slug # Unstick a blocked group genie wish reset my-wish-slug#2 ``` - **Benefit:** Full visibility into agent behavior. Systematic debugging instead of guessing. - **When to use:** Agent taking too long. Output quality dropping. Team progress stalled. Post-mortem on failed dream run. --- ## Command: `list` Display all hacks from the registry in a formatted table. **Output format:** ``` Genie Hacks — Community Patterns & Tips | ID | Title | Category | |----------------------|------------------------------------------|-------------| | provider-switching | Provider Switching — Right Model for Job | providers | | team-coordination | Multi-Team Coordination at Scale | teams | | overnight-batch | Overnight Batch Execution with /dream | batch | | custom-skills | Custom Skills for Repeated Workflows | skills | | hook-automation | Git Hook Automation with Genie Hooks | hooks | | cost-optimization | Cost Optimization Strategies | cost | | integration-patterns | Integration Patterns — Connect to Stack | integration | | debugging-tips | Debugging Agent Issues Like a Pro | debugging | 8 hacks available. Run `/genie-hacks show ` for details. Contribute your own: `/genie-hacks contribute` ``` ## Command: `search ` Search hack titles, problems, solutions, and code for the keyword (case-insensitive). Display matching hacks. **Output format:** ``` Search results for "": 1. [provider-switching] Provider Switching — Right Model for the Job Problem: You're using one provider for everything... Category: providers 2. [cost-optimization] Cost Optimization Strategies Problem: Agent usage costs add up... Category: cost 2 hacks matched. Run `/genie-hacks show ` for full details. ``` If no matches: `No hacks found for "". Try broader terms or run /genie-hacks list to browse all.` ## Command: `show ` Display the full hack with all fields. Look up by exact ID (case-insensitive). **Output format:** ``` ## **Category:** <category> | **ID:** `<hack-id>` ### Problem <problem text> ### Solution <solution text> ### Code <code block> ### Benefit <benefit text> ### When to Use <when-to-use text> --- Found this useful? Share your own: `/genie-hacks contribute` Full docs: https://docs.automagik.dev/genie/hacks ``` If not found: `Hack "<id>" not found. Did you mean: <suggest closest IDs>? Run /genie-hacks list to see all.` ## Command: `help <problem>` Fuzzy-match a problem description to relevant hacks. Extract keywords, score by overlap across all fields, show top 3. **Keyword mapping hints:** - "speed", "fast", "slow" → provider-switching, cost-optimization - "cost", "expensive", "budget", "tokens" → cost-optimization, provider-switching - "team", "parallel", "coordinate", "multiple" → team-coordination, overnight-batch - "overnight", "batch", "sleep", "queue" → overnight-batch, team-coordination - "repeat", "workflow", "automate", "reuse" → custom-skills, hook-automation - "hook", "event", "trigger", "auto" → hook-automation, custom-skills - "slack", "ci", "integrate", "notify" → integration-patterns - "stuck", "debug", "broken", "error", "fail" → debugging-tips - "codex", "claude", "model", "provider" → provider-switching - "dream", "night", "unattended" → overnight-batch **Output format:** ``` Based on your problem: "<problem>" Best matches: 1. [provider-switching] Provider Switching — Right Model for the Job Why: Matches your need for speed/cost optimization across providers Quick tip: Use `genie agent spawn engineer --provider codex` for fast scaffolding 2. [cost-optimization] Cost Optimization Strategies Why: Directly addresses cost reduction techniques Quick tip: Scope wishes tightly and use `/refine` before dispatching 3. [team-coordination] Multi-Team Coordination at Scale Why: Parallel execution reduces wall-clock time Quick tip: Use `/dream` for batch overnight execution Run `/genie-hacks show <id>` for full details on any hack. ``` If no reasonable matches: `No hacks closely match your problem. Try describing it differently, or run /genie-hacks list to browse all. Got a solution? Run /genie-hacks contribute!` ## Command: `contribute` ### Overview Guide the user through contributing a new hack to the community docs via an automated PR to `automagik-dev/docs`. This is the full end-to-end flow. ### Step 1: Gather Hack Details Prompt the user for each field interactively. Wait for each response before proceeding. **Prompt sequence:** 1. **Title**: "What's your hack title? (short, descriptive)" - Example: "Provider Switching for Speed vs Safety" 2. **Problem**: "What problem does it solve? (1-2 sentences)" - Example: "Different tasks need different AI providers — speed for scaffolding, careful reasoning for security-sensitive code." 3. **Solution**: "How does it work? Show the commands, config, or code. (Use code blocks)" - Example: multi-line code block with genie commands 4. **Category**: "What category? Pick one: `providers` | `teams` | `skills` | `hooks` | `cost` | `integration` | `debugging` | `batch` | `other`" - Validate input is one of the allowed categories. If invalid, re-prompt. 5. **Benefit**: "What's the key benefit? (one line)" - Example: "Right tool for each job — 3x faster scaffolding, safer reviews." 6. **When to use**: "When should someone use this? (one line)" - Example: "When your project has both speed-critical and safety-critical tasks." ### Step 2: Preview & Confirm Format the hack in the standard template and show the user: ```markdown ### <Title> **ID:** `<generated-id>` **Category:** <category> **Problem:** <problem> **Solution:** <solution with code blocks> **Benefit:** <benefit> **When to use:** <when> ``` Ask: "Does this look good? (yes/edit/cancel)" - **yes** → proceed to Step 3 - **edit** → ask which field to change, re-prompt for that field, re-preview - **cancel** → abort with "No worries! Run `/genie-hacks contribute` anytime." ### Step 3: GitHub CLI Preflight Run these checks in order. Stop at first failure with a helpful error. ```bash # 1. Check gh is installed command -v gh >/dev/null 2>&1 # If missing: "GitHub CLI (gh) is required. Install: https://cli.github.com/" # 2. Check gh is authenticated gh auth status 2>&1 # If not authenticated: "Run `gh auth login` to authenticate with GitHub first." # 3. Check git is available command -v git >/dev/null 2>&1 # If missing: "git is required but not found in PATH." ``` If any check fails, display the error message and suggest manual steps: ``` Manual contribution steps: 1. Fork https://github.com/automagik-dev/docs 2. Edit genie/hacks.mdx — add your hack in the correct category section 3. Commit: git commit -m "hack: <title>" 4. Open PR to automagik-dev/docs (base: dev) ``` ### Step 4: Fork & Clone ```bash # Cache directory for docs repo DOCS_CACHE="$HOME/.genie/cache/docs-fork" # Fork the docs repo (idempotent — no-op if already forked) gh repo fork automagik-dev/docs --clone=false 2>/dev/null || true # Get the user's GitHub username for the fork URL GH_USER=$(gh api user --jq '.login') # Clone or update the cached fork if [ -d "$DOCS_CACHE/.git" ]; then cd "$DOCS_CACHE" git fetch origin git checkout dev git pull origin dev else gh repo clone "$GH_USER/docs" "$DOCS_CACHE" -- --branch dev cd "$DOCS_CACHE" git remote add upstream https://github.com/automagik-dev/docs.git 2>/dev/null || true git fetch upstream fi # Create a branch for the hack BRANCH="hack/$(echo '<title>' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')" git checkout -b "$BRANCH" origin/dev ``` If clone/fork fails, show the error and fall back to manual steps (same as Step 3 fallback). ### Step 5: Append Hack to hacks.mdx Read `genie/hacks.mdx` from the cloned repo. Find the correct category section (look for `## <Category>` heading — e.g., `## Providers`, `## Teams`, etc.). Append the new hack entry just before the next `## ` heading or at the end of the category section. If the category section doesn't exist (e.g., for `other`), append a new section at the end of the file, before the Contributing section: ```markdown ## Other ### <Title> **ID:** `<generated-id>` **Problem:** <problem> **Solution:** <solution> **Benefit:** <benefit> **When to use:** <when> --- ``` ### Step 6: Commit & Push ```bash cd "$DOCS_CACHE" git add genie/hacks.mdx git commit -m "hack: <title>" git push -u origin "$BRANCH" ``` ### Step 7: Create PR ```bash # Create PR targeting the dev branch of the upstream docs repo PR_URL=$(gh pr create \ --repo automagik-dev/docs \ --base dev \ --head "$GH_USER:$BRANCH" \ --title "hack: <title>" \ --body "$(cat <<'PREOF' ## New Community Hack **Title:** <title> **Category:** <category> **Problem:** <problem> **Solution:** <solution summary> **Benefit:** <benefit> **When to use:** <when> --- *Submitted via `/genie-hacks contribute`* PREOF )") echo "PR created: $PR_URL" ``` ### Step 8: Success Display the result to the user: ``` Your hack has been submitted! PR: <PR_URL> Title: hack: <title> Target: automagik-dev/docs (dev branch) What happens next: - A maintainer will review your hack - They may suggest edits via PR comments - Once approved, it'll appear on the hacks page Thank you for contributing to the Genie community! Join the discussion on Discord: https://discord.gg/automagik ``` ### Error Recovery At any point if a step fails: | Error | Recovery | |-------|----------| | `gh` not installed | Show install URL, fall back to manual steps | | `gh` not authenticated | Show `gh auth login` command | | Fork fails | Check if fork already exists with `gh repo view $GH_USER/docs` | | Clone fails | Remove cache dir and retry: `rm -rf $DOCS_CACHE && gh repo clone ...` | | `hacks.mdx` not found | Create a new one with the standard template header | | Push fails (auth) | Suggest `gh auth refresh` or SSH key setup | | PR creation fails | Show the branch/commit info so user can create PR manually via GitHub web UI | | Editor fails | Write the hack content to a temp file, show the path for manual copy | ### Offline / Manual Fallback If GitHub operations fail entirely, save the hack locally and guide the user: ```bash # Save hack to local file mkdir -p ~/.genie/cache/pending-hacks cat > ~/.genie/cache/pending-hacks/<hack-id>.md << 'EOF' <formatted hack content> EOF ``` Then display: ``` Saved your hack locally at: ~/.genie/cache/pending-hacks/<hack-id>.md To submit manually: 1. Fork https://github.com/automagik-dev/docs 2. Copy the hack content into genie/hacks.mdx under the "<category>" section 3. Commit with message: "hack: <title>" 4. Open PR targeting the `dev` branch ``` ## Categories Reference | Category | ID | Description | |----------|----|-------------| | Providers | `providers` | Provider switching, model selection, BYOA | | Teams | `teams` | Multi-agent coordination, team patterns | | Skills | `skills` | Custom skills, skill chains, automation | | Hooks | `hooks` | Git hooks, auto-spawn, event-driven flows | | Cost | `cost` | Token optimization, model routing, budget control | | Integration | `integration` | External tools, APIs, CI/CD, Slack, etc. | | Debugging | `debugging` | Agent debugging, tracing, fixing bad behavior | | Batch | `batch` | Overnight execution, queued processing | | Other | `other` | Uncategorized community patterns | ## Docs Cache The docs repo is cached at `~/.genie/cache/docs-fork/` to avoid re-cloning on every contribute. The cache is updated (`git pull`) on each contribute invocation. If the cache becomes corrupted, delete it and re-run — the contribute flow will re-clone automatically. ## Rules - All hack IDs are lowercase kebab-case. - Never invent hacks that don't exist in the registry — only show what's listed above. - For `help`, always try to find at least one relevant hack. Only say "no matches" if truly nothing fits. - Keep output concise — tables for `list`, full format only for `show`. - Always end `list` and `show` with a nudge toward `contribute`. - The `contribute` command should be friendly and low-friction — one question at a time. - Link to Discord (https://discord.gg/automagik) for community discussion. - Link to docs (https://docs.automagik.dev/genie/hacks) for the full hacks page. - Always target the `dev` branch for PRs — never `main`/`master`. - Hack IDs must be unique — check existing IDs before appending. - All hacks must be realistic and tested — do not submit aspirational or untested patterns. - Preserve the standard format: problem, solution, code, benefit, when to use. - Keep code examples concise — show the minimum needed to understand the hack. --- > Source: [automagik-dev/genie](https://github.com/automagik-dev/genie) — distributed by [TomeVault](https://tomevault.io).