agency-rules 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0](https://github.com/deuriib/agency-rules/compare/v0.4.1...v0.5.0) (2026-10-31)
+
+
+### Features
+
+* **cli:** add 'list' command to display available rules ([15a7302](https://github.com/deuriib/agency-rules/commit/15a73025cd8ae1f90ab4a8602ac68817306aa128))
+
+## [0.4.1](https://github.com/deuriib/agency-rules/compare/v0.4.0...v0.4.1) (2026-10-31)
+
+
+### Bug Fixes
+
+* **pkg:** include rules directory in npm bundle and resolve package paths ([3877a97](https://github.com/deuriib/agency-rules/commit/3877a97e22ec5b79c183c47f3ed7b026171684e5))
+
 ## [0.4.0](https://github.com/deuriib/agency-rules/compare/v0.3.2...v0.4.0) (2026-10-31)
 
 

package/README.md

@@ -4,7 +4,7 @@
 
 `agency-rules` compiles a single set of generic Markdown rules into the
 native formats expected by **Google Antigravity**, **pi-agent**,
-**oh-my-pi (omp)**, and **OpenCode** (via the `opencode-rules` plugin).
+**oh-my-pi (omp)**, and **OpenCode** (via the [opencode-rules]("https://github.com/frap129/opencode-rules") plugin).
 
 The whole pipeline — toolchain, environment, and tasks — is managed by
 [mise](https://mise.jdx.dev), so every collaborator and CI runner uses the
@@ -21,7 +21,7 @@ Every coding agent has its own rule format:
 | Google Antigravity | YAML frontmatter with `trigger` | `.agents/rules/*.md` |
 | pi-agent | Per-rule directory with `RULES.md` | `.pi/rules/<slug>/RULES.md` |
 | oh-my-pi (omp) | Markdown with frontmatter | `.omp/rules/*.{md,mdc}` |
-| OpenCode | Markdown via `opencode-rules` plugin | `.opencode/rules/*.md` |
+| OpenCode | Markdown via [opencode-rules]("https://github.com/frap129/opencode-rules") plugin | `.opencode/rules/*.md` |
 
 Writing the same rule four times is a maintenance nightmare. `agency-rules`
 lets you write it **once** in a neutral format and compile it to all four

package/bin/agency-rules.mjs

@@ -29,17 +29,18 @@ Write rules once. Run them in every harness.
   $ agency-rules <command> [options]
 
 \x1b[33mCommands:\x1b[0m
-  \x1b[32mconvert\x1b[0m     Compile rules/ into each harness's native format
-  \x1b[32minstall\x1b[0m     Install compiled artifacts into detected harnesses
-  \x1b[32mvalidate\x1b[0m    Validate each rule's frontmatter against the schema
+  \x1b[32mlist\x1b[0m         List all available rules
+  \x1b[32mconvert\x1b[0m      Compile rules/ into each harness's native format
+  \x1b[32minstall\x1b[0m      Install compiled artifacts into detected harnesses
+  \x1b[32mvalidate\x1b[0m     Validate each rule's frontmatter against the schema
 
 \x1b[33mGlobal Options:\x1b[0m
   -h, --help      Show this help message
   -v, --version   Show version number
 
 \x1b[33mExamples:\x1b[0m
+  $ agency-rules list
   $ agency-rules validate
-  $ agency-rules convert
   $ agency-rules convert --dry-run
   $ agency-rules install --scope user --harness opencode
 `);
@@ -47,6 +48,17 @@ Write rules once. Run them in every harness.
 
 const showCommandHelp = (cmd) => {
     const helps = {
+        list: `
+\x1b[36magency-rules list\x1b[0m
+List all available rules and their descriptions.
+
+\x1b[33mOptions:\x1b[0m
+  --json            Output the list in JSON format (useful for scripting)
+
+\x1b[33mExamples:\x1b[0m
+  $ agency-rules list
+  $ agency-rules list --json | jq '.'
+`,
         convert: `
 \x1b[36magency-rules convert\x1b[0m
 Compile rules/ into each harness's native format.
@@ -101,7 +113,7 @@ if (!command || command === 'help' || command === '--help' || command === '-h')
     process.exit(0);
 }
 
-if (!['convert', 'install', 'validate'].includes(command)) {
+if (!['list', 'convert', 'install', 'validate'].includes(command)) {
     console.error(`\x1b[31mError:\x1b[0m Unknown command '${command}'`);
     showHelp();
     process.exit(1);
@@ -114,7 +126,6 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
 }
 
 // ── Execute ───────────────────────────────────────────────────────────
-// Remove the command from argv so the downstream script's parseArgs works cleanly
 process.argv.splice(2, 1);
 
 const scriptPath = resolve(import.meta.dirname, '..', 'scripts', `${command}.mjs`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-rules",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Write rules once. Run them in every harness.",
   "type": "module",
   "license": "MIT",
@@ -29,9 +29,10 @@
     "node": ">=20.12"
   },
   "files": [
+    "bin/",
     "scripts/",
     "tools.json",
-    "rules/_schema.json",
+    "rules/",
     "docs/",
     "README.md",
     "LICENSE",

package/rules/base/coding-standards.md

@@ -0,0 +1,12 @@
+---
+name: coding-standards
+description: Baseline rules applied to every edit regardless of file type.
+alwaysApply: true
+tags: [base]
+---
+
+# Coding Standards
+
+- Keep functions under 40 lines.
+- Prefer named exports over default exports.
+- Never commit `console.log` or debug prints.

package/rules/base/commit-convention.md

@@ -0,0 +1,53 @@
+---
+name: commit-conventions
+description: Enforce Conventional Commits format for all git commit messages.
+alwaysApply: true
+tags: [git, commits, conventional-commits]
+---
+
+# Git Commit Conventions
+
+All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+This is strictly required because automated release tooling (like `release-please`) uses these commits to calculate semantic versioning bumps and generate changelogs.
+
+## Format
+
+```
+<type>(<optional scope>): <subject>
+```
+
+- **type**: Must be one of the following:
+  - `feat`: A new feature (triggers a MINOR version bump).
+  - `fix`: A bug fix (triggers a PATCH version bump).
+  - `docs`: Documentation only changes.
+  - `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc).
+  - `refactor`: A code change that neither fixes a bug nor adds a feature.
+  - `perf`: A code change that improves performance.
+  - `test`: Adding missing tests or correcting existing tests.
+  - `build`: Changes that affect the build system or external dependencies.
+  - `ci`: Changes to CI configuration files and scripts.
+  - `chore`: Other changes that don't modify src or test files.
+- **scope** (optional): A noun describing a section of the codebase (e.g., `rules`, `convert`, `harness`, `docs`).
+- **subject**: A short description in the imperative mood (e.g., "add", not "added").
+
+## Rules
+
+- Use the **imperative, present tense** (e.g., "fix bug" not "fixed bug").
+- Do **not** capitalize the first letter of the subject.
+- Do **not** end the subject line with a period.
+- Keep the subject line under **72 characters**.
+- Separate the subject from the body with a blank line.
+- Use the body to explain *what* and *why* (not *how*).
+- Use footers for referencing issues (e.g., `Closes #123`) or declaring breaking changes (`BREAKING CHANGE: <description>`).
+
+## Examples
+
+```text
+feat(rules): add python async conventions
+fix(antigravity): join globs with comma instead of space
+docs(spec): clarify trigger precedence for model_decision
+chore(deps): bump biome to 2.5.1
+feat(harness): support Cursor rules format
+
+BREAKING CHANGE: The `trigger` field is now required for all Antigravity rules.
+```

package/rules/stacks/pyhton.md

@@ -0,0 +1,12 @@
+---
+name: python
+description: Rules for Python modules.
+globs: ["**/*.py"]
+tags: [language, python]
+---
+
+# Python Rules
+
+- Use type hints on public functions.
+- Prefer `pathlib` over `os.path`.
+- No wildcard imports.

package/rules/stacks/typescript.md

@@ -0,0 +1,25 @@
+---
+name: typescript
+description: Mandatory rules for editing TypeScript and TSX files.
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+alwaysApply: false
+trigger: glob          # preferencia para Antigravity; otros harnesses lo ignoran si no aplica
+tags: [language, typescript]
+---
+
+# TypeScript Rules
+
+- No `any` unless absolutely necessary.
+- Use top-level imports only.
+- Prefer `interface` over `type` for object shapes.
+
+## Examples
+
+```ts
+// ✅ good
+interface User { id: string; name: string; }
+
+// ❌ avoid
+type User = { id: string; name: string; };

package/scripts/convert.mjs

@@ -1,5 +1,5 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { readRules } from './lib/frontmatter.mjs';
 import { renderers } from './lib/renderers/index.mjs';
@@ -14,17 +14,25 @@ const { values: args } = parseArgs({
 const dryRun = args['dry-run'];
 const prefix = dryRun ? '  [dry-run]' : ' ';
 
-const RULES_DIR = process.env.RULES_DIR || 'rules';
+// Resolve paths: Use local if exists, otherwise fallback to the package's bundled files
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+const localRules = resolve(process.cwd(), 'rules');
+const localTools = resolve(process.cwd(), 'tools.json');
+
+const RULES_DIR =
+    process.env.RULES_DIR ||
+    ((await import('node:fs').then((fs) => fs.existsSync(localRules)))
+        ? localRules
+        : resolve(PACKAGE_ROOT, 'rules'));
+const TOOLS_PATH = (await import('node:fs').then((fs) => fs.existsSync(localTools)))
+    ? localTools
+    : resolve(PACKAGE_ROOT, 'tools.json');
+
 const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
 
-const tools = JSON.parse(await readFile('tools.json', 'utf8'));
+const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
 const rules = await readRules(RULES_DIR);
 
-if (rules.length === 0) {
-    console.error(`❌ No rules found in ${RULES_DIR}`);
-    process.exit(1);
-}
-
 console.log(
     `📚 Found ${rules.length} rule(s) in ${RULES_DIR}${dryRun ? ' (dry-run — nothing will be written)' : ''}\n`,
 );

package/scripts/install.mjs

@@ -1,5 +1,6 @@
+import { existsSync } from 'node:fs';
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { stdin as input, stdout as output } from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
@@ -19,7 +20,12 @@ const tag = dryRun ? '[dry-run]' : '     ';
 const log = (msg) => console.log(`  ${tag} ${msg}`);
 
 const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
-const tools = JSON.parse(await readFile('tools.json', 'utf8'));
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+const localTools = resolve(process.cwd(), 'tools.json');
+const TOOLS_PATH = existsSync(localTools) ? localTools : resolve(PACKAGE_ROOT, 'tools.json');
+
+const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
 
 let finalScope = args.scope;
 let finalHarness = args.harness;

package/scripts/list.mjs

@@ -0,0 +1,48 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readRules } from './lib/frontmatter.mjs';
+
+const { values: args } = parseArgs({
+    options: {
+        json: { type: 'boolean', default: false },
+    },
+});
+
+// Resolve paths (local vs package fallback)
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+const localRules = resolve(process.cwd(), 'rules');
+const RULES_DIR =
+    process.env.RULES_DIR || (existsSync(localRules) ? localRules : resolve(PACKAGE_ROOT, 'rules'));
+
+const rules = await readRules(RULES_DIR);
+
+if (rules.length === 0) {
+    console.error(`❌ No rules found in ${RULES_DIR}`);
+    process.exit(1);
+}
+
+// ── JSON Output ───────────────────────────────────────────────────────
+if (args.json) {
+    const output = rules.map((r) => ({
+        name: r.slug,
+        description: r.data.description || 'No description provided',
+        source: r.source,
+    }));
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
+}
+
+// ── Pretty Terminal Output ────────────────────────────────────────────
+// Find the longest name to align the columns perfectly
+const maxSlugLength = Math.max(...rules.map((r) => r.slug.length));
+
+console.log(`\n📚 \x1b[1mAvailable Rules\x1b[0m (${rules.length})\n`);
+
+for (const rule of rules) {
+    const paddedSlug = rule.slug.padEnd(maxSlugLength);
+    // Using Cyan for the rule name
+    console.log(`  \x1b[36m${paddedSlug}\x1b[0m  ${rule.data.description || 'No description'}`);
+}
+
+console.log('\n');