Understanding must precede generation. A CLI tool that embeds structured AI workflows into your repositories, transforming reactive debt-fixing into proactive, enterprise-grade development.
We've optimized for code generation speed while understanding velocity has remained constant. When you can generate 1000 lines in 30 seconds but need 30 minutes to understand them, you inevitably accumulate incomprehension faster than insight.
This creates a vicious cycle: AI generates code → you discover issues → you over-prompt to fix them → AI generates more code → the cycle repeats. You're not building systems; you're managing technical debt in real-time.
The technical reality: Without structure, AI treats technical debt as architectural requirements. Without guardrails, architectural coherence drifts with each conversational turn. Without context compression, you're constantly rediscovering what you already knew.
The human cost: Stress. Overhead. The constant weight of accumulating debt that you'll have to deal with later.
Speed is fine—even desirable. But clarity of approach is non-negotiable. The fastest path to production-ready code isn't generating more code; it's generating the right code, structured correctly from the start.
Core principle: Compress understanding before expanding code. Think first, generate second.
This manifests as a three-phase workflow:
- Research → Understand the system before teaching AI to modify it
- Plan → Make architectural decisions while you can still see them clearly
- Implement → Execute the validated specification, not invent solutions on the fly
AI cannot distinguish between complexity inherent to the problem and complexity introduced by our solution approach. It treats technical debt as architectural requirements. You must explicitly identify and separate them.
The ownership test: If you can't explain it to a junior engineer, debug it at 3am without internet, and modify it confidently when requirements change—you don't own it yet.
Each conversational turn optimizes for immediate satisfaction, not systemic coherence. AI has no memory of architectural intent across turns. This creates sedimentary layers of abandoned approaches.
Solution: Maintain .ai/ai-context.md as compressed knowledge—the 2000-word specification that represents 5 million tokens of code. Update it after every significant learning. Reference it before every architectural decision.
ai-init isn't just a tool—it's philosophy as infrastructure. It embeds structured workflows, guardrails, and context management directly into your repositories, making consistency automatic and debt prevention systematic.
Templates (.ai/): Research templates, planning frameworks, context compression patterns. The structure that prevents reactive fixing.
Rules (.cursor/rules/): Core principles, three-phase workflow enforcement, security patterns. The guardrails that prevent architectural drift.
Commands (.cursor/commands/): /research, /plan, /implement, /review. The workflows that enforce understanding-first development.
Hooks (.cursor/hooks/): Automatic context injection, post-edit validation, learning extraction. The automation that maintains coherence.
Skills (.cursor/skills/): Architecture decision frameworks, code review methodologies, security audit patterns. The expertise that elevates quality.
Agents (.cursor/agents/): Specialized AI personas for research and verification. The specialization that prevents AI-slop.
When you run ai-init init, you're not just copying files. You're installing:
- Proactive structure instead of reactive fixing
- Context compression instead of constant rediscovery
- Architectural coherence instead of conversational drift
- Ownership validation instead of incomprehension debt
- Stress-free development instead of accumulating overhead
One command. Consistent across all projects. Self-contained binary. No external dependencies.
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/RankJay/ai/main/install.sh | bashWindows (PowerShell):
iwr -useb https://raw.githubusercontent.com/RankJay/ai/main/install.ps1 | iexNote for Windows users: If you encounter execution policy restrictions, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
- Download the appropriate binary for your platform from GitHub Releases
- Verify the checksum against
checksums.txt - Rename to
ai-init(orai-init.exeon Windows) - Make executable (Unix):
chmod +x ai-init - Move to a directory in your PATH
- Verify:
ai-init --version
ai-init upgradeOr re-run the installation script to get the latest version.
Initialize AI workflow templates in the current git repository:
ai-init initOptions:
| Flag | Description |
|---|---|
--only <categories> |
Install specific categories only (comma-separated) |
--skip <categories> |
Skip specific categories |
--force |
Overwrite existing files without prompting |
Available categories: ai, rules, commands, hooks, skills, agents
Examples:
# Install only AI templates and rules
ai-init init --only ai,rules
# Install everything except hooks
ai-init init --skip hooks
# Force overwrite all existing files
ai-init init --forceValidate your repository for missing or broken AI workflow files:
ai-init doctorOptions:
| Flag | Description |
|---|---|
--fix |
Automatically fix detected issues |
Remove AI workflow files from the repository:
ai-init uninstallOptions:
| Flag | Description |
|---|---|
--force |
Remove files without prompting |
Goal: Understand the system before teaching AI to modify it.
# Use the /research command (installed via ai-init)
/research [task description]Output: A validated research document at .ai/active-research.md that maps dependencies, identifies essential vs accidental complexity, and compresses understanding into actionable knowledge.
Technical reality: You're building the foundation. Without this, you're generating code into a void.
Goal: Make architectural decisions while you can still see them clearly.
# Use the /plan command (installed via ai-init)
/planOutput: A validated plan at .ai/active-plan.md with signatures, types, data flow—"paint by numbers" clarity that a junior engineer could execute.
Technical reality: You're compressing architectural intent. Without this, each AI turn optimizes for local satisfaction, not systemic coherence.
Goal: Execute the validated specification.
# Use the /implement command (installed via ai-init)
/implementOutput: Code that follows the plan exactly. Review is conformance verification, not understanding what got invented.
Technical reality: You're generating code from understanding, not generating understanding from code.
| Command | Description |
|---|---|
init |
Initialize AI workflow templates in the current git repository |
doctor |
Check repository for missing or broken AI workflow files |
upgrade |
Upgrade ai-init to the latest version |
uninstall |
Remove AI workflow files from the repository |
- Rust - Systems programming language
- clap - Command line argument parser
- dialoguer - Interactive CLI prompts
- reqwest - HTTP client for downloads
- self-replace - Atomic binary self-replacement
Contributions are welcome and appreciated. Please read CONTRIBUTING.md before submitting changes.
Quick start:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
By contributing, you agree that your contributions will be licensed under the same license as the project and that you assign copyright ownership to the project maintainer.
Security is taken seriously. Please review SECURITY.md for:
- Supported versions
- Reporting vulnerabilities
- Security practices
Do not open public issues for security vulnerabilities. Follow the responsible disclosure process in SECURITY.md.
This project is licensed under the PolyForm Noncommercial License 1.0.0.
You may:
- Use for personal, research, educational, and noncommercial purposes
- Modify and create derivative works
- Distribute copies for noncommercial purposes
You may not:
- Use for commercial purposes or monetization
- Sublicense or transfer your license
See LICENSE for the full license text.
Commercial licensing: Contact the maintainer for commercial use inquiries.
RankJay - Project Maintainer
- GitHub: @RankJay
- Project: https://github.com/RankJay/ai