ide-agents 0.1.1 → 0.3.0

package/template/.cursor/rules/agents.mdc

@@ -0,0 +1,72 @@
+---
+description: Agent authoring — orchestration, reports, and script-backed generators
+globs: agents/**/*.md
+alwaysApply: false
+---
+
+# Agent authoring
+
+Agents in `agents/*.md` are **orchestrators**: they define role, workflow, and output format. They are not a place for ad-hoc code generation.
+
+## Generators → `scripts/`
+
+For anything that must be **stable, repeatable, and testable** (scanners, profile builders, report writers, stack detectors), put logic in bundled scripts under the **related skill folder**:
+
+```
+skills/<skill-id>/
+├── SKILL.md
+├── scripts/          # node *.mjs — run these, do not re-implement in chat
+└── assets/           # optional JSON/markers the scripts read
+```
+
+Pattern from [repo-audit-skills](https://github.com/sergeychernov/repo-audit-skills):
+
+- `skills/audit-init/scripts/detect-stack.mjs` — read-only scan, writes structured JSON
+- `skills/audit-debt/scripts/run-audit.mjs` — reads profile, runs checks, writes report
+
+### Why agents call scripts
+
+| In chat (avoid) | In `scripts/` (prefer) |
+|-----------------|------------------------|
+| Re-parsing repo layout each turn | Same repo state → same output |
+| Drifting flags and file paths | Documented CLI in script header |
+| Large inline bash one-liners | `#!/usr/bin/env node`, ESM `.mjs` |
+
+Agent body should tell the model to **resolve `<SKILL_DIR>`**, run `node <SKILL_DIR>/scripts/<name>.mjs`, then **read the artifact** (stdout JSON or a known output path). See `scripts.mdc` for script conventions.
+
+## Agent file format
+
+YAML frontmatter (filename stem must match `name`, e.g. `agents/oracle.md` → `name: oracle`):
+
+```yaml
+---
+name: my-agent          # required — lowercase id; Cursor subagent identity (/my-agent)
+description: When to delegate to this subagent. Be specific — the IDE uses this for auto-delegation.
+scope: any              # optional — ide-agents only: global | project | any (default any)
+---
+```
+
+| Field | Required | Used by |
+|-------|----------|---------|
+| `name` | yes | Cursor / Claude / Codex subagent id (defaults to filename if omitted — prefer explicit) |
+| `description` | yes | IDE delegation — when the main agent should hand off to this subagent |
+| `scope` | no | ide-agents UI — which install toggles are enabled |
+
+Subagents are **not** skills: they live in `agents/*.md`, install to `~/.cursor/agents/`, and are invoked by name in Agent mode (e.g. `/oracle …` or “use the oracle subagent”), not via the `/` skill picker.
+
+Body structure:
+
+1. **Role** — one paragraph
+2. **Inputs** — what the user or upstream skill must provide
+3. **Workflow** — numbered steps; step that runs a script must include the exact `node …mjs` command
+4. **Output contract** — fixed sections (e.g. summary, findings, gaps); use consistent severity markers if reporting issues
+
+## Do not
+
+- Embed multi-step filesystem scans or JSON schema logic in the agent markdown
+- Write into the target project except paths documented by the skill (e.g. `.audit/`)
+- Duplicate script behavior in prose — link to `SKILL.md` quick start instead
+
+## Shared helpers
+
+Cross-skill utilities may live in `skills/_shared/` (e.g. `generated-by.mjs`). Import from scripts via relative paths; agents reference the skill that owns the script.

package/template/.cursor/rules/repo-structure.mdc

@@ -0,0 +1,46 @@
+---
+description: Skills and agents repository layout for ide-agents catalogs
+alwaysApply: true
+---
+
+# Repository structure
+
+This repository is an **ide-agents skill catalog** — not an application codebase.
+
+## Directories
+
+| Path | Purpose |
+|------|---------|
+| `skills/<id>/SKILL.md` | Installable skills (required `SKILL.md` per folder) |
+| `skills/<id>/scripts/` | Optional bundled generators (`*.mjs`) — see `scripts.mdc` |
+| `skills/<id>/assets/` | Optional JSON/markers read by scripts |
+| `skills/_shared/` | Optional cross-skill helpers (imported by scripts) |
+| `agents/<id>.md` | Subagent orchestrators — call scripts, do not re-implement generators |
+| `.cursor/rules/` | Cursor project rules (this file) |
+
+## SKILL.md conventions
+
+- YAML frontmatter: `name`, `description`, `scope` (`global`, `project`, or `any`).
+- Body: instructions the IDE agent follows when the skill is invoked.
+- One skill per directory under `skills/`.
+
+## Agents
+
+- One markdown file per agent in `agents/` (e.g. `agents/oracle.md`).
+- YAML frontmatter: `name`, `description`, optional `scope` (`global`, `project`, or `any`).
+- `name` must match the filename stem; used by Cursor/Claude/Codex as the subagent id.
+- Agents **orchestrate**; deterministic generators live in `skills/<id>/scripts/` (see `agents.mdc`).
+
+## Scripts (generators)
+
+Stable scanners and report writers belong in `skills/<skill-id>/scripts/`, not inline in agent prompts. Follow `scripts.mdc` (ESM `.mjs`, stdlib only, `--json` / `--dry-run`, resolve paths via `import.meta.url`).
+
+## Do not
+
+- Put application source code here unless it supports the catalog itself.
+- Rename skill folders casually — `artifactId` in ide-agents matches the directory name.
+- Remove `SKILL.md` from a skill folder (scan ignores directories without it).
+
+## Installing
+
+Use [ide-agents](https://github.com/sergeychernov/ide-agents): add this repo, then toggle **Global** or **Project** on Skills / Agents pages.

package/template/.cursor/rules/scripts.mdc

@@ -0,0 +1,101 @@
+---
+description: Conventions for skill scripts (generators, scanners, report writers)
+globs: skills/**/scripts/**
+alwaysApply: false
+---
+
+# Skill scripts
+
+Bundled under `skills/<skill-id>/scripts/`. Invoked by skills and agents — not installed separately by ide-agents.
+
+Reference implementation: [repo-audit-skills](https://github.com/sergeychernov/repo-audit-skills) (`detect-stack.mjs`, `run-audit.mjs`, modular `checks/`).
+
+## Runtime
+
+- ESM: `*.mjs`, `#!/usr/bin/env node`
+- Node 18+, **zero npm dependencies** in scripts (stdlib only)
+- Resolve skill assets via `import.meta.url` — never assume cwd for skill paths
+
+```javascript
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const assetsDir = join(here, '..', 'assets');
+```
+
+## Target repo discovery
+
+Scripts run **from anywhere inside the user's project** (after skill symlink install). Discover the audited repo root explicitly:
+
+```javascript
+import { execSync } from 'node:child_process';
+
+const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+process.chdir(repoRoot);
+```
+
+Exit `1` with a clear message if not a git repo.
+
+## File header (required)
+
+Every entry script documents usage at the top:
+
+```javascript
+#!/usr/bin/env node
+// my-skill: one-line purpose
+//
+// Usage (from anywhere inside a git repo):
+//   node <SKILL_DIR>/scripts/my-script.mjs
+//   node <SKILL_DIR>/scripts/my-script.mjs --json
+//   node <SKILL_DIR>/scripts/my-script.mjs --dry-run
+```
+
+`<SKILL_DIR>` is the installed skill folder path (global or project symlink).
+
+## CLI flags (standard)
+
+| Flag | Effect |
+|------|--------|
+| `--json` | Machine-readable stdout |
+| `--dry-run` | Run logic without writing output files |
+| `--force` | Overwrite existing generated files (when applicable) |
+
+Add skill-specific flags (`--offline`, `--verbose`, …) only when documented in the header.
+
+## Scan and write rules
+
+- Prefer `git ls-files` over unbounded filesystem walks
+- **Read-only** toward source files in the target repo by default
+- Writable outputs only under paths the skill documents (e.g. `.audit/profile.json`, `.audit/reports/*.json`)
+- Static config and schemas stay in `skills/<id>/assets/` — edit markers here, not in the target project
+- No network calls in scan scripts unless the skill explicitly requires it
+
+## Output
+
+- Human mode: short labeled summary for the terminal
+- JSON mode: stable schema for agents to parse
+- JSON files: 2-space indent, trailing newline
+- Stamp artifacts with `generatedBy`, `version`, `generatedAt` when writing reports
+
+## Layout inside a skill
+
+```
+skills/<name>/
+├── SKILL.md
+├── scripts/
+│   ├── run-*.mjs       # entry points
+│   ├── load-*.mjs      # shared loaders
+│   └── checks/         # optional modular checks
+└── assets/             # JSON registries, markers, schemas
+```
+
+Split large generators into `scripts/checks/` modules (see `audit-debt/scripts/checks/`).
+
+## SKILL.md integration
+
+Each skill with scripts must include in `SKILL.md`:
+
+1. Folder tree showing `scripts/` and `assets/`
+2. **Quick start** — copy-pasteable `node <SKILL_DIR>/scripts/….mjs`
+3. **Agent instructions** — resolve skill dir, run script, read output

package/template/README.md

@@ -0,0 +1,60 @@
+# Skills & agents catalog
+
+A git repository of **IDE skills** and **agents** for Cursor, Claude Code, and Codex.
+
+Managed with [ide-agents](https://github.com/sergeychernov/ide-agents) — clone this repo in the UI, then install artifacts globally or per project.
+
+## Layout
+
+```
+.
+├── skills/
+│   └── <skill-id>/
+│       ├── SKILL.md          # required — frontmatter: name, description, scope
+│       ├── scripts/          # optional — *.mjs generators (see .cursor/rules/scripts.mdc)
+│       └── assets/           # optional — JSON/markers for scripts
+├── agents/
+│   └── <agent-id>.md         # orchestrators — call scripts, not inline generators
+├── .cursor/rules/            # Cursor project rules (repo structure)
+├── .claude/CLAUDE.md         # Claude Code project instructions
+└── .agents/AGENTS.md         # Codex project instructions
+```
+
+## SKILL.md frontmatter
+
+```yaml
+---
+name: my-skill
+description: What this skill does.
+scope: any   # global | project | any
+---
+```
+
+## Agents
+
+Agent files live in `agents/<agent-id>.md`. YAML frontmatter:
+
+```yaml
+---
+name: my-agent
+description: When the IDE should delegate to this subagent.
+scope: any   # global | project | any — ide-agents install toggles only
+---
+```
+
+`name` must match the filename stem (`agents/oracle.md` → `name: oracle`). Subagents install to `~/.cursor/agents/<name>.md` (or project `.cursor/agents/`); invoke in Agent mode by name, not via the `/` skill menu.
+
+## Sample artifacts
+
+This repo was bootstrapped with a demo skill and a starter agent. Extend or replace them as you build your catalog.
+
+| Kind | ID | Purpose |
+|------|-----|---------|
+| skill | `hello` | Install smoke-test + `scripts/now.mjs` (system clock) |
+| agent | `oracle` | Joke fortune-teller — always upbeat predictions |
+
+## Next steps
+
+1. Edit or add skills under `skills/` and agents under `agents/`.
+2. Commit and push to your remote.
+3. In ide-agents, open **Skills** / **Agents** and toggle **Global** or **Project** to symlink into your IDE.

package/template/agents/oracle.md

@@ -0,0 +1,38 @@
+---
+name: oracle
+description: Playful fortune-teller subagent — upbeat predictions only, never doom.
+scope: any
+---
+
+# Oracle
+
+You are a cheerful, slightly theatrical fortune teller for **entertainment only**. You read the vibes, squint at the horizon, and deliver short prophecies — always **optimistic**, never alarming.
+
+This is not financial, medical, or legal advice. Say so once if the user asks about money, health, or lawsuits.
+
+## Workflow
+
+1. Optional anchor in the present: if the `hello` skill is available, run  
+   `node <SKILL_DIR>/scripts/now.mjs --json`  
+   and weave the real timestamp into your opening (“The stars align at …”).
+2. Ask for a topic if missing (career, side project, weekend, coffee, code review — anything goes).
+3. Deliver **one** prophecy in 3–5 sentences: vivid, warm, lightly funny. No hedging, no warnings, no “but on the other hand”.
+4. End with a single lucky token (emoji, silly number, or absurd ritual) — e.g. “lucky semicolon”, “42% more sunshine”.
+
+## Tone
+
+- Warm, playful, confident — like a friend who only owns good news.
+- Never predict failure, illness, layoffs, breakups, or bugs that cannot be fixed.
+- If the user pushes for bad news, reframes it as a plot twist that still ends well.
+
+## Output format
+
+```
+🔮 Oracle says
+
+<prophecy paragraphs>
+
+Lucky sign: <one line>
+```
+
+Keep it under ~120 words unless the user asks for an epic saga.

package/template/skills/hello/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: hello
+description: Demo skill — verifies ide-agents install and reads accurate local time via a bundled script.
+scope: any
+---
+
+# Hello
+
+Smoke-test skill that shows why **scripts beat chat** for deterministic output: the agent runs a bundled Node script that reads the **host system clock** (not model guesswork).
+
+## Skill layout
+
+```
+skills/hello/
+├── SKILL.md
+└── scripts/
+    └── now.mjs
+```
+
+## Quick start
+
+```bash
+node <SKILL_DIR>/scripts/now.mjs
+node <SKILL_DIR>/scripts/now.mjs --json
+```
+
+Replace `<SKILL_DIR>` with the installed skill path (global or project symlink from ide-agents).
+
+## Workflow
+
+When the user invokes this skill or asks for a hello / time check:
+
+1. Resolve `<SKILL_DIR>` (installed `hello` skill folder).
+2. Run `node <SKILL_DIR>/scripts/now.mjs --json`.
+3. Parse the JSON — fields `local`, `timeZone`, `utcOffset`, `iso`, `unixMs`.
+4. Greet the user briefly and **quote the script output** as the authoritative local time.
+5. Do not invent or approximate the time in prose; if the script fails, report the error.
+
+## Agent instructions
+
+- Prefer `--json` so the time is machine-parseable.
+- Human summary example: “Hello — your system clock says … (timezone …).”
+- This skill has no `assets/` folder; the script uses only Node stdlib and `Intl`.

package/template/skills/hello/scripts/now.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// hello: read the host system clock and print accurate local time
+//
+// Usage:
+//   node <SKILL_DIR>/scripts/now.mjs
+//   node <SKILL_DIR>/scripts/now.mjs --json
+
+import process, { argv } from 'node:process';
+
+const flags = new Set(
+  argv.slice(2).filter((a) => a.startsWith('--')).map((a) => a.slice(2)),
+);
+const jsonOut = flags.has('json');
+
+const now = new Date();
+const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+const offsetMinutes = -now.getTimezoneOffset();
+
+function formatUtcOffset(minutes) {
+  const sign = minutes >= 0 ? '+' : '-';
+  const abs = Math.abs(minutes);
+  const hours = String(Math.floor(abs / 60)).padStart(2, '0');
+  const mins = String(abs % 60).padStart(2, '0');
+  return `UTC${sign}${hours}:${mins}`;
+}
+
+const payload = {
+  source: 'system clock',
+  unixMs: now.getTime(),
+  unixSeconds: Math.floor(now.getTime() / 1000),
+  iso: now.toISOString(),
+  local: now.toLocaleString(undefined, {
+    timeZone,
+    dateStyle: 'full',
+    timeStyle: 'long',
+  }),
+  timeZone,
+  utcOffset: formatUtcOffset(offsetMinutes),
+  platform: process.platform,
+};
+
+if (jsonOut) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+} else {
+  process.stdout.write('Local time (system clock)\n');
+  process.stdout.write(`  ${payload.local}\n`);
+  process.stdout.write(`  ${payload.utcOffset} · ${payload.timeZone}\n`);
+  process.stdout.write(`  ISO: ${payload.iso}\n`);
+}