ide-agents 0.2.0 → 0.4.0

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`);
+}