ramenos 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI & Publish
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.x"
+      - name: Run tests
+        run: npm test
+
+  publish:
+    needs: test
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.x"
+          registry-url: "https://registry.npmjs.org"
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,177 @@
+# 🤖 Ramenos CLI
+
+[![npm version](https://img.shields.io/npm/v/ramenos.svg?style=flat-square)](https://www.npmjs.com/package/ramenos)
+[![0 dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](https://www.npmjs.com/package/ramenos)
+[![CI Tests](https://img.shields.io/github/actions/workflow/status/maxylev/ramenos/ci.yml?style=flat-square)](https://github.com/maxylev/ramenos/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+A lightning-fast, **zero-dependency** CLI to share and install AI multi-agent orchestration configurations directly from GitHub into your local workspace.
+
+Designed for modern AI coding assistants like [OpenCode](https://opencode.ai/). Bootstrapping an elite multi-agent AI team is now just one command away.
+
+---
+
+## ✨ Features
+
+- 🚀 **Zero Dependencies**: Built with native Node.js. Incredibly fast execution.
+- 🔗 **Smart Caching**: Uses local caching to safely symlink agent files without cluttering your project.
+- 🐙 **Flexible Git Support**: Supports GitHub shorthand, raw HTTPS, SSH, and deep folder trees.
+- 🎯 **Dynamic Frameworks**: By default targets `opencode`, but supports dynamic path generation for *any* agent framework you provide.
+
+## 🚀 Quick Start
+
+No global install required! Just run it via `npx` inside your project directory:
+
+```bash
+# Add an AI agent team to your current project (defaults to OpenCode)
+npx ramenos add maxylev/ramenos
+
+# Add agents globally to your machine
+npx ramenos add maxylev/ramenos --global
+```
+
+## 📖 Usage Options
+
+```text
+Usage: ramenos add <repository> [options]
+
+Options:
+  -g, --global              Install to user directory instead of project workspace
+  -a, --agent <agents...>   Target specific agent frameworks (defaults to 'opencode')
+  --copy                    Copy files instead of symlinking (useful to modify them locally)
+  -y, --yes                 Skip all confirmation prompts
+  -h, --help                Display help message
+```
+
+## 🎯 Dynamic Target Paths
+
+`ramenos` dynamically generates file paths based on the `--agent` parameter you pass. If omitted, it gracefully defaults to `opencode`.
+
+| Command | Local Path Generated | Global Path Generated (`-g`) |
+| :--- | :--- | :--- |
+| `ramenos add repo` | `.opencode/agents/` | `~/.config/opencode/agents/` |
+| `ramenos add repo -a myapp` | `.myapp/agents/` | `~/.config/myapp/agents/` |
+| `ramenos add repo -a foo bar` | `.foo/agents/` & `.bar/agents/` | `~/.config/foo/agents/` & `~/.config/bar/agents/` |
+
+## 🔗 Supported Repository Formats
+
+Ramenos looks for an `agents/` folder by default in the root of the repository, but supports deep links if you want to pull a specific sub-folder.
+
+**1. GitHub Shorthand**:
+```bash
+npx ramenos add my-labs/my-awesome-agents
+```
+
+**2. Direct Sub-folder Links** (Grab specific agents from a larger monorepo):
+```bash
+npx ramenos add https://github.com/ai-labs/my-agents/tree/main/agents/orchestration
+```
+
+**3. SSH Formats** (For private repositories, assuming SSH keys are configured):
+```bash
+npx ramenos add git@github.com:my-company/internal-agents.git
+```
+
+## 💡 Examples
+
+**Install to multiple AI assistant structures at once:**
+```bash
+npx ramenos add maxylev/ramenos -a opencode claude-code codex
+```
+
+**Copy files instead of symlinking (so you can edit the prompts):**
+```bash
+npx ramenos add maxylev/ramenos --copy
+```
+
+**CI/CD or Automated Scripting (Skip all prompts):**
+```bash
+npx ramenos add maxylev/ramenos --yes
+```
+
+## 🛠️ Creating Your Own Agent Repo
+
+Want to share your own agents via `ramenos`? Just create a public GitHub repository and place your markdown (`.md`) or JSON config files inside an `agents/` directory at the root.
+
+```text
+my-awesome-agents/
+├── README.md
+└── agents/
+    ├── orchestrator.md
+    ├── developer.md
+    └── tester.md
+```
+
+Then anyone can install your setup using: `npx ramenos add your-username/my-awesome-agents`
+
+## Use 9router
+
+Run the following command to start the 9router:
+
+```bash
+npm install -g 9router
+9router
+```
+
+- Configure 9router:
+
+`http://localhost:20128`
+
+Create model combos with fallback support:
+- chef
+- cook
+- coordinator
+- critic
+- innovator
+- logistician
+- master
+- taster
+
+- Configure opencode:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "router": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "router",
+      "options": {
+        "baseURL": "http://localhost:20128/v1"
+      },
+      "models": {
+        "chef": {
+          "name": "chef"
+        },
+        "cook": {
+          "name": "cook"
+        },
+        "coordinator": {
+          "name": "coordinator"
+        },
+        "critic": {
+          "name": "critic"
+        },
+        "innovator": {
+          "name": "innovator"
+        },
+        "logistician": {
+          "name": "logistician"
+        },
+        "master": {
+          "name": "master"
+        },
+        "taster": {
+          "name": "taster"
+        }
+      }
+    }
+  }
+}
+```
+
+Run opencode with websearch:
+
+```bash
+OPENCODE_ENABLE_EXA=1 opencode
+```

package/agents/chef.md

@@ -0,0 +1,41 @@
+---
+description: Orchestrator. Manages all agents, delegates tasks, maintains full context, evaluates responses, and strictly enforces zero-trust best practices.
+mode: primary
+color: "#27CCF5"
+model: router/chef
+temperature: 0.1
+permission:
+  task: allow
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+  websearch_*: allow
+  webfetch_*: allow
+---
+
+You are the Orchestrator, a strict, stern, and fair perfectionist managing a highly autonomous AI engineering team. You are strictly accountable to the human user.
+
+**MISSION:** 
+To conceptualize, build, test, and deploy a self-sustaining, subsistence-profitable startup (generating just enough revenue to cover VPS rental, LLM tokens, and utility bills to buy time for growth without VC funding). The business MUST be entirely crypto-native (EVM, SVM, Bitcoin, etc.) and bypass the traditional banking system entirely. All payments and receipts must be in cryptocurrency.
+
+**YOUR WORKFLOW:**
+At the start of the session, ALWAYS ask the user for their preference: 
+1. Do they want you to report back and ask for approval after every single stage?
+2. Or should you remain completely autonomous until the final deployment is operational?
+
+You manage the following pipeline via subagents:
+1. `@innovator` -> Brainstorms in `1_AMAZING_IDEAS.md`
+2. `@taster` -> Validates/filters ideas in `2_REALISTIC_IDEAS.md`
+3. `@master` -> Architect. Chooses an idea, builds `.agents/skills/[package]/SKILL.md` references, writes `3_IDEA_SPECIFICATION.md`
+4. `@coordinator` -> Creates task breakdown in `4_IMPLEMENTATION_PLAN.md`
+5. `@cook` -> Developer. Implements code and marks off plan tasks.
+6. `@critic` -> Tester. Creates `5_E2E_TESTING.md` and runs real-data tests.
+7. `@logistician` -> DevOps. Writes `6_PROJECT_DEPLOYMENT.md` and automates release.
+
+**ZERO-TRUST POLICY:**
+- You trust NO ONE. You double-check all work returned by subagents.
+- NO MOCKS, NO PLACEHOLDERS, NO HARDCODED DATA. If a subagent uses them, you immediately reject the work and send it back for revision.
+- If the output does not meet enterprise-grade best practices, send it back with stern feedback.
+- You do not do the work yourself. You delegate to your specialized subagents using the task tool and evaluate their output.

package/agents/cook.md

@@ -0,0 +1,24 @@
+---
+description: Developer. Lead software engineer implementing project tasks based strictly on the plan.
+mode: subagent
+model: router/cook
+temperature: 0.2
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the Developer. You are the lead software engineer responsible for writing the actual production code.
+
+Your tasks:
+1. Follow `4_IMPLEMENTATION_PLAN.md` sequentially. Do not skip steps.
+2. Write real, production-ready code. 
+3. **CRITICAL RULE:** Zero mocks. Zero placeholders like "TODO: implement later". Zero hardcoded business logic data. You write the actual working implementation. 
+4. Read `.agents/skills/[package]/SKILL.md` before using any library to ensure you conform to the Architect's gathered best practices.
+5. Write unit tests for your code as you go.
+6. Update `4_IMPLEMENTATION_PLAN.md` meticulously, changing states to `[~]`, `[x]`, or `[!]` as you work.
+7. If you encounter an impossible hurdle, mark it `[!]` and report back to the Orchestrator with terminal outputs and error logs.

package/agents/coordinator.md

@@ -0,0 +1,27 @@
+---
+description: Planner. Analyzes specs and skills to create a rigorous, step-by-step implementation plan.
+mode: subagent
+model: router/coordinator
+temperature: 0.1
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the Planner. Your goal is to translate abstract architecture into a concrete, executable roadmap for the Developer.
+
+Your tasks:
+1. Deeply analyze `3_IDEA_SPECIFICATION.md` and all files inside `.agents/skills/`.
+2. Create a comprehensive implementation roadmap in `4_IMPLEMENTATION_PLAN.md`.
+3. Break every single technical requirement into atomic subtasks. 
+4. You MUST format the task states precisely using checkboxes:
+   - `[ ]` Pending
+   - `[x]` Completed
+   - `[~]` In Progress
+   - `[!]` Blocked / Error
+5. Order tasks strictly by dependency (e.g., environment setup -> database -> core logic -> API -> crypto integrations -> frontend).
+6. State explicitly that mocks, placeholders, and hardcoded values are banned from the codebase.

package/agents/critic.md

@@ -0,0 +1,22 @@
+---
+description: Tester. QA engineer focused on executing end-to-end tests using real data and network environments.
+mode: subagent
+model: router/critic
+temperature: 0.1
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the Tester. Your responsibility is to ensure the software works in reality, not just in isolated unit tests.
+
+Your tasks:
+1. Once the Developer achieves major milestones, formulate a rigorous testing plan in `5_E2E_TESTING.md`.
+2. Your E2E plan must connect to real APIs, real testnets (for crypto transactions), and use real data.
+3. Mocks are explicitly forbidden during your validation phase. 
+4. Execute the tests via bash commands. Verify that cryptocurrency transactions are correctly indexed, recognized, and trigger the proper business logic.
+5. If an E2E test fails, aggressively document the failure, capture the trace, and report it back to the Orchestrator so the Developer can be disciplined and fix it.

package/agents/innovator.md

@@ -0,0 +1,26 @@
+---
+description: Dreamer. Conceives highly original, unique, and out-of-the-box startup ideas.
+mode: subagent
+model: router/innovator
+temperature: 0.9
+top_p: 0.9
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the Dreamer. Your goal is to conceptualize the most unusual, incredible, completely original, and unique startup ideas.
+
+Your constraints are:
+1. The business must be capable of reaching subsistence-profitability (covering basic running costs like VPS, LLM API tokens, utilities) quickly.
+2. It MUST operate completely outside the traditional banking system. Only cryptocurrency operations (EVM, SVM, Bitcoin, etc.) are permitted for revenue generation and operational payments.
+
+Your tasks:
+- Brainstorm wildly. Do not restrict yourself to what is currently normal.
+- Create or update the file `1_AMAZING_IDEAS.md`.
+- Detail the core premise, the crypto-monetization loop, and why the idea is extraordinary.
+- Provide a wide array of options (at least 10). Do not worry about technical feasibility; your only job is maximum originality.

package/agents/logistician.md

@@ -0,0 +1,23 @@
+---
+description: DevOps. Automates CI/CD processes, deployment pipelines, and sets up hosting.
+mode: subagent
+model: router/logistician
+temperature: 0.1
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the DevOps Engineer. You handle the bridge between the codebase and the public internet.
+
+Your tasks:
+1. Draft the deployment strategy in `6_PROJECT_DEPLOYMENT.md`.
+2. Configure automated pipelines (e.g., GitHub Actions, GitLab CI) for linting, testing, and building.
+3. Configure deployment manifests (Docker, PM2, systemd, etc.) for a Linux VPS environment.
+4. Keep in mind the strict requirement: we must pay for the infrastructure using cryptocurrency. If applicable, configure deployments leveraging decentralized hosting (like IPFS, Arweave, Akash, or crypto-accepting VPS providers).
+5. Ensure environment variables and secrets are handled securely without exposing them in the repository.
+6. Do the actual execution to test the build and deployment processes. Ensure the final product is live and functional.

package/agents/master.md

@@ -0,0 +1,22 @@
+---
+description: Architect. Selects the idea, gathers latest tech details via web, builds technical specification and dependency skills.
+mode: subagent
+model: router/master
+temperature: 0.1
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the Architect. You define how the software will actually be built, ensuring the team uses modern, exact, and error-free tooling.
+
+Your tasks:
+1. Read `2_REALISTIC_IDEAS.md`. Optionally ask the Orchestrator for the final selection, or pick the highest feasibility score if told to proceed autonomously.
+2. Once the idea is locked, research the absolute latest versions of all required libraries, packages, frameworks, and crypto SDKs.
+3. For every core dependency, create a dedicated skill file in `.agents/skills/[package_name]/SKILL.md`. This file MUST contain the most critical, up-to-date best practices, initialization snippets, and anti-patterns for that specific package based on current documentation.
+4. Write a highly detailed, rigid technical specification into `3_IDEA_SPECIFICATION.md`.
+5. The specification must define the exact tech stack, database schema, smart contract architectures (if applicable), and strictly mandate how crypto payments will be processed and verified.

package/agents/taster.md

@@ -0,0 +1,23 @@
+---
+description: Realist. Researches the potential of wild ideas online, filters them, and identifies viable solutions for the real world.
+mode: subagent
+model: router/taster
+temperature: 0.3
+permission:
+  edit: allow
+  bash: allow
+  websearch: allow
+  webfetch: allow
+  question: allow
+hidden: true
+---
+
+You are the Realist. Your job is to bring the Dreamer's ideas down to earth using data and research.
+
+Your tasks:
+1. Read `1_AMAZING_IDEAS.md`.
+2. Conduct deep web research to validate the market potential, existing competitors, and technological viability of the ideas.
+3. Filter out ideas that are impossible or technically unachievable for a AI agent team.
+4. Modify and refine the surviving ideas into actionable, practical business models.
+5. Ensure the crypto-native payment requirement (EVM, SVM, Bitcoin, etc.) is fully viable without relying on traditional fiat off-ramps/on-ramps that require KYC/banking.
+6. Output the refined list of viable ideas to `2_REALISTIC_IDEAS.md`. Include a strict feasibility score and required core technologies for each.

package/bin/ramenos.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import {
+  parseArgs,
+  parseInput,
+  fetchRepo,
+  installAgents,
+  colorize,
+} from "../src/index.js";
+
+function printHelp() {
+  console.log(`
+${colorize("cyan", "🤖 Ramenos CLI")}
+A fast, zero-dependency CLI to share and install AI multi-agent orchestration files.
+
+${colorize("yellow", "Usage:")}
+  ramenos add <repository> [options]
+
+${colorize("yellow", "Options:")}
+  -g, --global              Install globally to user directory (~/.config/) instead of local project
+  -a, --agent <agents...>   Target frameworks. Defaults to 'opencode' if omitted.
+                            (e.g., '-a xxx yyy' creates .xxx/agents and .yyy/agents)
+  --copy                    Copy files completely instead of creating symlinks
+  -y, --yes                 Skip all confirmation prompts
+  -h, --help                Display this help message
+
+${colorize("yellow", "Examples:")}
+  ramenos add ai-labs/my-agents
+  ramenos add ./my-labs/my-awesome-agents
+  ramenos add ai-labs/my-agents -g -a opencode codex claude-code
+  ramenos add https://github.com/ai-labs/my-agents/tree/main/agents/my --copy
+`);
+}
+
+async function run() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  if (options.help || !options.command) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (options.command === "add") {
+    if (!options.repository) {
+      console.error(
+        colorize("red", "\n❌ Error: Repository argument is required."),
+      );
+      console.log(colorize("gray", "   Try: ramenos add user/repo\n"));
+      process.exit(1);
+    }
+
+    try {
+      const repoConfig = parseInput(options.repository);
+      if (!repoConfig) throw new Error("Invalid repository format provided.");
+
+      const sourcePath = fetchRepo(repoConfig);
+      await installAgents(sourcePath, options);
+
+      console.log(
+        colorize("green", "\n✨ Done! Agent files successfully installed.\n"),
+      );
+    } catch (err) {
+      console.error(colorize("red", `\n❌ Fatal Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  } else {
+    console.error(
+      colorize("red", `\n❌ Error: Unknown command '${options.command}'\n`),
+    );
+    process.exit(1);
+  }
+}
+
+run();

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "ramenos",
+  "version": "1.0.0",
+  "description": "A fast CLI to share and install AI multi-agent orchestration files",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "ramenos": "bin/ramenos.js"
+  },
+  "scripts": {
+    "start": "node bin/ramenos.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxylev/ramenos.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "opencode",
+    "cli"
+  ],
+  "author": "Max Ylev",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,313 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+import readline from "readline";
+
+export const RAMENOS_CACHE_DIR = path.join(os.homedir(), ".ramenos", "cache");
+
+export const colors = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+
+/**
+ * Applies terminal colors to text
+ */
+export function colorize(color, text) {
+  return `${colors[color]}${text}${colors.reset}`;
+}
+
+/**
+ * Dynamically resolves global and local paths based on the agent/framework name
+ * @param {string} framework - The framework name (e.g., 'opencode', 'claude')
+ * @returns {{ global: string, local: string }}
+ */
+export function getTargetPaths(framework) {
+  // Sanitize to prevent directory traversal (e.g., ../)
+  const safeName = framework.toLowerCase().replace(/[^a-z0-9-]/g, "");
+
+  return {
+    global: path.join(os.homedir(), ".config", safeName, "agents"),
+    local: path.join(process.cwd(), `.${safeName}`, "agents"),
+  };
+}
+
+/**
+ * Parses CLI arguments manually to keep the CLI zero-dependency
+ */
+export function parseArgs(args) {
+  const options = {
+    global: false,
+    agent: [],
+    copy: false,
+    yes: false,
+    command: null,
+    repository: null,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "add" && !options.command) {
+      options.command = "add";
+      if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        options.repository = args[++i];
+      }
+    } else if (arg === "-g" || arg === "--global") {
+      options.global = true;
+    } else if (arg === "-y" || arg === "--yes") {
+      options.yes = true;
+    } else if (arg === "--copy") {
+      options.copy = true;
+    } else if (arg === "-a" || arg === "--agent") {
+      while (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        options.agent.push(args[++i]);
+      }
+    }
+  }
+  return options;
+}
+
+/**
+ * Extracts URL, branch, and subpaths from Git input, OR resolves local directories
+ */
+export function parseInput(input) {
+  if (!input) return null;
+
+  // 1. Resolve local path
+  let resolvedPath = input;
+  if (input.startsWith("~/")) {
+    resolvedPath = path.join(os.homedir(), input.slice(2));
+  } else {
+    resolvedPath = path.resolve(input);
+  }
+
+  // 2. Check if it's explicitly a local path OR if the directory actually exists
+  const isExplicitLocal =
+    input.startsWith("./") ||
+    input.startsWith("../") ||
+    input.startsWith("/") ||
+    input.startsWith("~/") ||
+    input.startsWith(".\\") || // Windows relative
+    input.startsWith("..\\") || // Windows relative
+    /^[A-Za-z]:[\\/]/.test(input); // Windows absolute (e.g. C:\)
+
+  if (
+    isExplicitLocal ||
+    (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isDirectory())
+  ) {
+    // If the folder contains an "agents" subdirectory, use it automatically!
+    const agentsSubdir = path.join(resolvedPath, "agents");
+    if (
+      fs.existsSync(agentsSubdir) &&
+      fs.statSync(agentsSubdir).isDirectory()
+    ) {
+      resolvedPath = agentsSubdir;
+    }
+
+    return {
+      isLocal: true,
+      sourcePath: resolvedPath,
+    };
+  }
+
+  // 3. Matches: https://github.com/user/repo/tree/branch/path
+  const treeMatch = input.match(
+    /github\.com\/([^/]+\/[^/]+)\/tree\/([^/]+)\/(.+)/,
+  );
+  if (treeMatch) {
+    return {
+      url: `https://github.com/${treeMatch[1]}.git`,
+      branch: treeMatch[2],
+      subpath: treeMatch[3],
+      id: treeMatch[1].replace("/", "_"),
+    };
+  }
+
+  // 4. Matches SSH or raw HTTPs
+  if (input.startsWith("git@") || input.startsWith("http")) {
+    const idMatch = input.match(/([^/:]+\/[^/.]+)(\.git)?$/);
+    return {
+      url: input,
+      branch: null,
+      subpath: "agents",
+      id: idMatch
+        ? idMatch[1].replace("/", "_").replace(".git", "")
+        : "custom_repo",
+    };
+  }
+
+  // 5. Matches shorthand: user/repo
+  return {
+    url: `https://github.com/${input}.git`,
+    branch: null,
+    subpath: "agents",
+    id: input.replace("/", "_"),
+  };
+}
+
+/**
+ * Creates an interactive Yes/No prompt
+ */
+export function askConfirm(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(`${question} (Y/n) `, (answer) => {
+      rl.close();
+      const clean = answer.trim().toLowerCase();
+      resolve(clean === "" || clean === "y" || clean === "yes");
+    });
+  });
+}
+
+/**
+ * Clones the repository into cache, OR returns the local directory path
+ */
+export function fetchRepo(repoConfig) {
+  // If it's a local directory, bypass git and cache entirely
+  if (repoConfig.isLocal) {
+    if (!fs.existsSync(repoConfig.sourcePath)) {
+      throw new Error(`Local path does not exist: ${repoConfig.sourcePath}`);
+    }
+    console.log(
+      colorize("cyan", `\n📁 Using local directory: ${repoConfig.sourcePath}`),
+    );
+    return repoConfig.sourcePath;
+  }
+
+  // Otherwise, handle remote git repository
+  if (!fs.existsSync(RAMENOS_CACHE_DIR)) {
+    fs.mkdirSync(RAMENOS_CACHE_DIR, { recursive: true });
+  }
+
+  const targetDir = path.join(RAMENOS_CACHE_DIR, repoConfig.id);
+  console.log(
+    colorize("cyan", `\n📥 Fetching repository: ${repoConfig.url}...`),
+  );
+
+  try {
+    if (fs.existsSync(targetDir)) {
+      execSync(`git fetch --all`, { cwd: targetDir, stdio: "ignore" });
+      if (repoConfig.branch) {
+        execSync(`git reset --hard origin/${repoConfig.branch}`, {
+          cwd: targetDir,
+          stdio: "ignore",
+        });
+      } else {
+        execSync(`git reset --hard HEAD`, { cwd: targetDir, stdio: "ignore" });
+        execSync(`git pull`, { cwd: targetDir, stdio: "ignore" });
+      }
+    } else {
+      const branchFlag = repoConfig.branch ? `-b ${repoConfig.branch}` : "";
+      execSync(`git clone ${branchFlag} ${repoConfig.url} ${targetDir}`, {
+        stdio: "ignore",
+      });
+    }
+  } catch (error) {
+    throw new Error(
+      "Failed to fetch repository. Ensure it exists, is public/accessible, and git is installed.",
+    );
+  }
+
+  const sourcePath = path.join(targetDir, repoConfig.subpath);
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(
+      `Could not find path '${repoConfig.subpath}' inside the repository.`,
+    );
+  }
+
+  return sourcePath;
+}
+
+/**
+ * Installs (symlinks or copies) the agents to the specified target directories
+ */
+export async function installAgents(sourcePath, options) {
+  // Default strictly to "opencode" if no explicit agents provided
+  const targetFrameworks =
+    options.agent.length > 0 ? options.agent : ["opencode"];
+  const scopeName = options.global ? "Global" : "Project Local";
+
+  for (const framework of targetFrameworks) {
+    const paths = getTargetPaths(framework);
+    const destDir = options.global ? paths.global : paths.local;
+
+    console.log(
+      colorize("blue", `\n🚀 Target Framework: [${framework}] -> ${destDir}`),
+    );
+
+    if (!options.yes) {
+      const isConfirmed = await askConfirm(
+        `Install agents to ${scopeName} ${framework} directory?`,
+      );
+      if (!isConfirmed) {
+        console.log(colorize("gray", "  Skipped."));
+        continue;
+      }
+    }
+
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    const files = fs.readdirSync(sourcePath);
+    let installedCount = 0;
+
+    for (const file of files) {
+      // Ignore hidden files like .git
+      if (file.startsWith(".")) continue;
+
+      const srcFile = path.join(sourcePath, file);
+      const destFile = path.join(destDir, file);
+
+      // Clean existing target files/symlinks
+      if (
+        fs.existsSync(destFile) ||
+        fs.lstatSync(destFile, { throwIfNoEntry: false })
+      ) {
+        fs.unlinkSync(destFile);
+      }
+
+      try {
+        if (options.copy) {
+          fs.cpSync(srcFile, destFile, { recursive: true });
+          console.log(colorize("green", `  ✓ Copied: ${file}`));
+        } else {
+          fs.symlinkSync(srcFile, destFile);
+          console.log(colorize("green", `  ✓ Symlinked: ${file}`));
+        }
+        installedCount++;
+      } catch (err) {
+        // Handle Windows permission issues with symlinks gracefully
+        if (err.code === "EPERM" && !options.copy) {
+          fs.cpSync(srcFile, destFile, { recursive: true });
+          console.log(
+            colorize("green", `  ✓ Copied (Symlink fallback): ${file}`),
+          );
+          installedCount++;
+        } else {
+          console.error(
+            colorize("red", `  ❌ Failed to install ${file}: ${err.message}`),
+          );
+        }
+      }
+    }
+
+    if (installedCount === 0) {
+      console.log(
+        colorize("yellow", `  ⚠️ No valid files found in source directory.`),
+      );
+    }
+  }
+}

package/test/index.test.js

@@ -0,0 +1,105 @@
+import test from "node:test";
+import assert from "node:assert";
+import path from "path";
+import os from "os";
+import { parseInput, parseArgs, getTargetPaths } from "../src/index.js";
+
+test("getTargetPaths: Default opencode", () => {
+  const paths = getTargetPaths("opencode");
+  assert.strictEqual(
+    paths.global,
+    path.join(os.homedir(), ".config", "opencode", "agents"),
+  );
+  assert.strictEqual(
+    paths.local,
+    path.join(process.cwd(), ".opencode", "agents"),
+  );
+});
+
+test("getTargetPaths: Dynamic sanitized names", () => {
+  const paths = getTargetPaths("My-Agent_123!");
+  // Should lowercase and strip non-alphanumeric (except dashes)
+  assert.strictEqual(
+    paths.local,
+    path.join(process.cwd(), ".my-agent123", "agents"),
+  );
+});
+
+test("parseInput: Shorthand syntax", () => {
+  const res = parseInput("maxylev/ramenos");
+  assert.strictEqual(res.url, "https://github.com/maxylev/ramenos.git");
+  assert.strictEqual(res.id, "maxylev_ramenos");
+  assert.strictEqual(res.subpath, "agents");
+});
+
+test("parseInput: Full HTTPS syntax", () => {
+  const res = parseInput("https://github.com/my-labs/agent.git");
+  assert.strictEqual(res.url, "https://github.com/my-labs/agent.git");
+  assert.strictEqual(res.id, "my-labs_agent");
+  assert.strictEqual(res.subpath, "agents");
+});
+
+test("parseInput: SSH syntax", () => {
+  const res = parseInput("git@github.com:ai-labs/my-agents.git");
+  assert.strictEqual(res.url, "git@github.com:ai-labs/my-agents.git");
+  assert.strictEqual(res.id, "ai-labs_my-agents");
+  assert.strictEqual(res.subpath, "agents");
+});
+
+test("parseInput: Deep tree path", () => {
+  const res = parseInput(
+    "https://github.com/ai-labs/my-agents/tree/main/agents/my",
+  );
+  assert.strictEqual(res.url, "https://github.com/ai-labs/my-agents.git");
+  assert.strictEqual(res.branch, "main");
+  assert.strictEqual(res.subpath, "agents/my");
+  assert.strictEqual(res.id, "ai-labs_my-agents");
+});
+
+test("parseArgs: Basic add command", () => {
+  const opts = parseArgs(["add", "maxylev/ramenos"]);
+  assert.strictEqual(opts.command, "add");
+  assert.strictEqual(opts.repository, "maxylev/ramenos");
+  assert.strictEqual(opts.global, false);
+  assert.deepStrictEqual(opts.agent, []); // Empty defaults to opencode down the line
+});
+
+test("parseArgs: Multiple flags and agents", () => {
+  const opts = parseArgs([
+    "add",
+    "maxylev/ramenos",
+    "-g",
+    "-y",
+    "-a",
+    "opencode",
+    "codex",
+    "--copy",
+  ]);
+  assert.strictEqual(opts.command, "add");
+  assert.strictEqual(opts.global, true);
+  assert.strictEqual(opts.yes, true);
+  assert.strictEqual(opts.copy, true);
+  assert.deepStrictEqual(opts.agent, ["opencode", "codex"]);
+});
+
+test("parseArgs: Help flag", () => {
+  const opts1 = parseArgs(["-h"]);
+  const opts2 = parseArgs(["--help"]);
+  assert.strictEqual(opts1.help, true);
+  assert.strictEqual(opts2.help, true);
+});
+
+test("parseInput: Explicit local relative path", () => {
+  const res = parseInput("./my-labs/my-awesome-agents");
+  assert.strictEqual(res.isLocal, true);
+  assert.strictEqual(
+    res.sourcePath,
+    path.resolve("./my-labs/my-awesome-agents"),
+  );
+});
+
+test("parseInput: Explicit local absolute path", () => {
+  const res = parseInput("/usr/local/agents");
+  assert.strictEqual(res.isLocal, true);
+  assert.strictEqual(res.sourcePath, path.resolve("/usr/local/agents"));
+});