{"id":31759004,"url":"https://github.com/vikdotdev/ai-ruleset-manager","last_synced_at":"2025-10-09T20:53:02.649Z","repository":{"id":317098161,"uuid":"1065954084","full_name":"vikdotdev/ai-ruleset-manager","owner":"vikdotdev","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-28T21:07:51.000Z","size":21,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-28T21:20:49.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vikdotdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-28T19:04:24.000Z","updated_at":"2025-09-28T19:47:50.000Z","dependencies_parsed_at":"2025-09-28T21:20:51.217Z","dependency_job_id":"3d8dfe4f-5457-41b4-9968-d6b3ed75e4f0","html_url":"https://github.com/vikdotdev/ai-ruleset-manager","commit_stats":null,"previous_names":["vikdotdev/llm-ruleset-manager"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/vikdotdev/ai-ruleset-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikdotdev%2Fai-ruleset-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikdotdev%2Fai-ruleset-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikdotdev%2Fai-ruleset-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikdotdev%2Fai-ruleset-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vikdotdev","download_url":"https://codeload.github.com/vikdotdev/ai-ruleset-manager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikdotdev%2Fai-ruleset-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001962,"owners_count":26083259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T20:53:00.823Z","updated_at":"2025-10-09T20:53:02.644Z","avatar_url":"https://github.com/vikdotdev.png","language":"Shell","readme":"# AI Ruleset Manager\n\nA template repository for managing reusable rule fragments (plain `*.md` files) that can be composed into comprehensive LLM instruction documentation. Perfect for individuals who want to manage their LLM instructions with `git` and compose specific rulesets from personal rule databases.\n\n## Problem\nOften projects have their own `*.md` rule/context files that provide LLMs with context about the project (architecture/design/styling/etc). This leaves no place for user-defined instructions that don't belong in the project (user-specific workflows/preferences/etc).\n\n_A way_ out of this problem is to have a git-ignored `*.local.md` file that contains such user preferences. Keeping such ignored files outside of version control can get messy, especially if user wishes to carry their LLM instructions across multiple machines.\n\n## Solution\nSplit LLM rule/context file into individual `*.md` rule files and build specific context file for specific project/LLM tool. Here's an example of what a repository could look like with this template:\n```\nmy-ai-ruleset/\n├── scripts/\n│   ├── ai-rules            # Main CLI tool, copied from the template\n│   └── test                # Test runner, copied from the template\n├── rules/\n│   ├── ruby                # Database of specific user rules for Ruby\n│   ├── rails               # Database of specific user rules for Rails\n│   └── my_rails_project    # Database of specific user project rules\n├── build/\n│   └── my_rails_project.md # Stores compiled artifacts (in case of using symlinks)\n└── test/                   # Comprehensive test suite\n    ├── fixtures/           # Test data\n    └── *.sh                # Test scripts, automatically invoked by scripts/test\n```\n\n## 🚀 Quick Start\n\n1. **Use this template**: Click \"Use this template\" on GitHub to create your own repository\n2. **Clone your repository**: Clone your repository to your local machine\n2. **Install the CLI**:\n   ```bash\n   ./scripts/ai-rules install # Creates `ai-rules` CLI command at your PATH\n   ```\n   \n   Or as custom binary command:\n   ```bash\n   ./scripts/ai-rules install --bin-name \u003cbinary command name of your choice\u003e\n   ```\n3. **Create your first rule database**:\n   ```bash\n   ai-rules new --database rails\n   ```\n4. **Add rules** to `rules/\u003cdatabase-name\u003e/rules/`, e.g. specific rules for Rails projects:\n   ```bash\n   echo \"Classes should always be defined as one-liners, e.g. `MyModule::AnotherModule::MyClass`.\" \u003e rules/ruby/rules/class-definitions.md\n   echo \"# Callbacks\\nNever use callbacks on models.\" \u003e rules/rails/rules/models.md\n   echo \"# Testing\\nAlways start writing tests with a basic outline and let me review it.\" \u003e rules/rails/rules/testing.md\n   echo \"# Testing controllers\\nNever do ...\" \u003e rules/rails/rules/testing-controllers.md\n   ```\n5. **Create a manifest** in `rules/\u003cdatabase-name\u003e/manifest`:\n   ```\n   | ruby/class-definitions\n   | rails/models\n   | rails/testing\n   || rails/testing-controllers\n   ```\n   Every rule fragment creates properly indented entry in the resulting `*.local.md` file.\n6. **Compile your ruleset**:\n   ```bash\n   ai-rules build --manifest rules/\u003cdatabase-name\u003e/manifest --out ~/my_project/CLAUDE.local.md\n   ```\n\n## 🛠️ CLI Commands\n\n### Install CLI\n```bash\n./scripts/ai-rules install [--prefix \u003cpath\u003e]\n```\nInstalls the CLI tool to your system.\n\n### Create New Database\n```bash\nai-rules new --database \u003cname\u003e\n```\nCreates a new rule database with proper directory structure.\n\n**Example:**\n```bash\nai-rules new --database react\n```\n\n### Validate Manifest\n```bash\nai-rules validate --manifest \u003cpath\u003e\n```\nValidates manifest syntax and checks that all referenced rules exist. Validation is also run before `ai-rules build`.\n\n**Example:**\n```bash\nai-rules validate --manifest rules/myproject/manifest\n```\n\n### Compile ruleset\n```bash\nai-rules build --manifest \u003cpath\u003e [--out \u003cfile\u003e]\n```\nCompiles rules from a manifest into a single markdown file at destination, or in `build/` directory.\n\n**Examples:**\n```bash\n# Build with default output location\nai-rules build --manifest rules/myproject/manifest\n\n# Build with custom output\nai-rules build --manifest rules/myproject/manifest --out path/to/myproject/ai-context.md\n```\n\n### Deploy Documentation\n```bash\nai-rules build-link --manifest \u003cpath\u003e --out \u003csymlink path\u003e\n```\nBuilds documentation and creates a symlink for easy access.\n\n## 🪢 Dependencies\n\n**Runtime dependencies**:\n- POSIX-compliant shell (`/bin/sh`)\n- `cat`\n- `sed`\n- `cut`\n- `wc`\n- `basename`\n- `dirname`\n- `pwd`\n- `cd`\n- `mkdir`\n- `ln`\n- `mv`\n- `rm`\n- `read`\n\n**Development dependencies**:\n- `diff`\n- `grep`\n\n## 📋 Manifest Format\n\nManifests use simple text-based hierarchical format:\n\n```\n# Comments start with #\n| top-level-rule\n|| nested-rule\n||| deeply-nested-rule\n| another-top-level-rule\n```\n\n**Nesting Rules:**\n- `|` = Level 1 (becomes `# Rule: name`)\n- `||` = Level 2 (becomes `## Rule: name`)\n- `|||` = Level 3 (becomes `### Rule: name`)\n- Up to 6 levels supported\n- Each level must increase by exactly 1 (no skipping levels)\n\n### Rationale\n\n**Why not YAML/JSON/TOML?:**\n- There's no easy way to parse any of those formats (that I know of) without external dependencies that are not written in POSIX shell script\n\n**Why `|`?:**\n- Because if you squint, it makes the hierarchy look like a tree\n- For easy parsing\n\n## 📝 Writing Rules\n\n- Rules are standard Markdown files stored in `rules/\u003cdatabase\u003e/rules/*.md`\n- Use any heading levels you want - they'll be automatically normalized based on hierarchy\n- Each rule file becomes a titled section in the output (e.g. `# Rule: my_rule`)\n- Try to keep rules small and focused for easy composition \u0026 re-use in the manifest\n\n## 🔤 Glossary\n- **Rule/Fragment**: A markdown file with instructions for LLMs on highly specific topic\n- **Database**: A folder containing `rules/*.md` and `manifest` file\n- **Manifest**: A file that describes the hierarchy of rules make it into the final compiled output file for LLMs to consume\n\n## 🤝 Contributing\n\n1. Fork this template repository\n2. Create your rule databases in the `rules/` directory\n3. Add tests for new functionality in `test/`\n4. Ensure all tests pass: `./scripts/test`\n5. Submit a pull request\n\n### 🧪 Testing\nWhen it comes to development of the template itself, here's the files contributor should care about:\n```\nai-ruleset-manager/\n├── scripts/\n│   ├── ai-rules            # Main CLI tool, runned by automated tests\n│   └── test                # Test runner, runs test/*.sh test scripts\n└── test/                   # Comprehensive test suite\n    ├── tmp/                # Place for test build artifacts\n    ├── fixtures/           # Test data\n    └── *.sh                # Test scripts, automatically invoked by scripts/test\n```\nTo test the project, run `./scripts/test`. Run specific test file with `./scripts/test build-01-basic`.\n\n## 🗺️ Roadmap\n- Include full rule-name in built template\n- Shell completions\n- More comprehensive tests with combination of features (comments + deep nesting + rules from various databases)\n- Better folder structure semantics\n  - Search for rules in `rules/\u003cdatabase/*.md`\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikdotdev%2Fai-ruleset-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvikdotdev%2Fai-ruleset-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikdotdev%2Fai-ruleset-manager/lists"}