@snowdreamtech/unirtm

v0.0.10

Published

2 hours ago

UniRTM - Universal Runtime Manager: enterprise-grade foundational toolchain for multi-AI IDE collaboration

0High
0Medium
0Low

snowdream

unirtm runtime manager toolchain ai ide

UniRTM (Universal Runtime Manager)

Inspired by mise (licensed under MIT). Special thanks to jdx and the mise community for the great ideas.

English | 简体中文

An enterprise-grade, foundational template designed for multi-AI IDE collaboration. This repository serves as a Single Source of Truth for AI agent rules, workflows, and project configurations, supporting over 50 different AI-assisted IDEs with massive multi-language support.

🌟 Features

Multi-IDE Compatibility: Out-of-the-box support for Cursor, Windsurf, GitHub Copilot, Cline, Roo Code, Trae, Gemini, Claude Code, and 50+ other AI editors.
Unified Rule System: Centralized rule definitions in .agent/rules/. Changes propagate automatically to all supported IDEs via a secure symlink/redirect pattern.
80+ Language & Framework Rules: Pre-configured high-quality rules from Rust, Go, TypeScript, Python to Ansible, Kubernetes, and API design.
Smart Workflows (SpecKit): Standardized .agent/workflows/ commands (speckit.plan, speckit.analyze, snowdreamtech.init) that behave consistently across all supported environments.
Triple Guarantee Quality: 100% code purity enforced through Pre-commit and GitHub Actions integrated quality gates.
Cross-Platform Ready: Runs seamlessly on macOS (Homebrew/MacPorts), Linux, and Windows.

🏗️ Section 1 — Design & Architecture

Overview

The Snowdream Tech Template is a foundational scaffold engineered to solve the "N-IDE Fragmentation" problem. It standardizes the development environment, AI agent rules, and automation pipelines across varied platforms and languages.

Key Capabilities:

Provides a Unified Rule Engine that governs AI behavior consistently across 50+ IDEs.
Enforces Cross-Platform Portability through dynamically adapting POSIX shell automation.
Implements a Triple Guarantee Quality Gate (IDE, CLI, CI) to prevent regressions.
Supports Massive Multi-Language Stacks with modular onboarding logic.

Architecture

graph TD
    A["Developers & Agents"] -->|Operates via| IDE["Cursor / Windsurf / Copilot / 50+ Others"]
    IDE -->|Reads Rules via Redirects| R1[".vscode/"]
    IDE -->|Reads Rules via Redirects| R2[".github/"]
    IDE -->|Reads Rules via Redirects| R3[".cline/ .trae/ etc."]

    R1 -.->|SSoT Pointer| CoreRules[".agent/rules/"]
    R2 -.->|SSoT Pointer| CoreRules
    R3 -.->|SSoT Pointer| CoreRules

    CoreRules -->|Governs| Src["Source Code"]
    CoreRules -->|Governs| Scripts["CI/CD & Shell Scripts"]

Design Principles

Single Source of Truth (SSoT): All AI rules, commands, and Git hooks live in one place. No duplicated IDE configurations.
Cross-Platform Portability: Heavy automation logic is written in POSIX Shell, with thin wrappers for Windows PowerShell/Batch.
Triple Guarantee Quality: Linting and formatting form an impenetrable wall, enforced at the IDE layer, pre-commit layer, and CI/CD GitHub Actions layer.

Responsibilities

.agent/rules/: Owns the definitive behavioral logic for AI agents across all supported languages.
scripts/: Owns the cross-platform automation and lifecycle logic.
.agent/workflows/: Owns the interactive AI commands (SpecKit).

📖 Section 2 — Usage Guide

Prerequisites

Runtime: Node.js (>= 20.x), Python (>= 3.10.x).
Git: Global git installation required.

Quick Start

Initialize & Install: unirtm install (installs all project tools and dependencies).
Verify: make verify (ensures everything is green).

Configuration Reference

File Structure

project-root/
├── .agent/              # 🤖 Canonical AI configuration (The Brain)
│   ├── rules/           # 📏 Unified AI behavioral rules (80+ sets, SSoT)
│   └── workflows/       # 🛠️ Unified commands & AI workflows (SpecKit)
├── .agents/             # 🧩 Shared command sources (Auto-managed symlinks)
├── .github/             # 🐙 GitHub integration & Copilot settings
├── .vscode/             # 💻 Optimized VS Code configurations
└── src/                 # 📦 Your actual application source code

🛠️ Section 3 — Operations Guide

Pre-deployment Checklist

Run make verify to ensure all quality gates are green.
Run make audit to verify security compliance.
Ensure CHANGELOG.md is updated.

Performance Considerations

Linting Speed: Pre-commit hooks target < 5s by scanning staged files only.
CI Throughput: GitHub Actions use matrix builds for parallel testing across OS types.

Troubleshooting

Problem: unirtm install fails on Windows.
- Diagnosis: Check if ExecutionPolicy allows script execution.
- Solution: Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.
Problem: Gitleaks detects false positives.
- Diagnosis: Check .gitleaks.toml allowlist.
- Solution: Add fingerprint to .gitleaksignore.
Problem: Pre-commit hooks fail on macOS after unirtm install with Python errors.
- Diagnosis: Check if the venv exists: ls .venv/bin/python.
- Solution: Rebuild the venv: rm -rf .venv && unirtm install.

🔒 Section 4 — Security Considerations

Security Model

Secret Management: All secrets must be injected via environment variables or handled by HashiCorp Vault. Never commit .env files.
Audit Logging: All critical operations (commits, releases, state changes) are traced via Git and CI logs.
Supply Chain: All CI actions are pinned to exact versions/SHAs.

Best Practices

🧑‍💻 Section 5 — Development Guide

Code Organization

project-root/
├── .agent/               # AI configuration (Single Source of Truth)
│   ├── rules/            # 88 behavioral rule files for AI agents
│   └── workflows/        # SpecKit slash-command definitions
├── .github/              # GitHub ecosystem (Actions, templates, Dependabot)
│   └── workflows/        # CI/CD pipelines (lint, verify, release, security)
├── .devcontainer/        # DevContainer configuration for reproducible environments
├── docs/                 # Project documentation
│   ├── adr/              # Architecture Decision Records
│   ├── runbooks/         # Operations and recovery runbooks
│   └── glossary.md       # Bilingual term glossary
├── scripts/              # POSIX shell automation (setup, install, verify)
│   └── lib/              # Shared shell library functions
└── Makefile              # Task orchestration (setup, install, lint, verify, audit)

Naming Conventions: Rule files use NN-kebab-case.md (core rules) or technology.md (language stacks). Workflow files use namespace.verb.md. Shell scripts use kebab-case.sh.

Extension Points

Adding Rules: Create a new .md file in .agent/rules/ and link it in 00-index.md.
Adding Commands: Add .md files to .agent/workflows/.
Adding IDE Support: Create a redirect folder (e.g., .myide/) following the symlink pattern in Rule 03.

Local Development Setup

git clone <repo>
cd <repo>
git config core.ignorecase false  # MANDATORY for Mac/Windows
unirtm install

References

🚀 Proxy Usage Scenarios

The GITHUB_PROXY (default: https://gh-proxy.sn0wdr1am.com/) is optimized for specific network acceleration scenarios. Misusing it for unsupported protocols (like Git) will result in errors.

[!IMPORTANT] To prevent breaking toolchains (like mise or asdf), this template explicitly disables Git redirection via this proxy. Use it only for direct HTTP downloads in scripts.