instruqt

A sophisticated CLI tool for deploying context documentation to AI agents across multiple platforms. Features a quad context system (Common, MERN, NPM, FastAPI), automatic file flow generation, and smart deployment that protects your customizations while keeping documentation synchronized.

Features

• Quad Context System: Common shared docs + MERN/NPM/FastAPI specific contexts
• Automatic File Flow Generation: Analyzes and documents your entire codebase structure
• Smart File Protection: Never overwrites existing files (protects your customizations)
• Four-Phase Deployment: Directories → Common context → Specific context → File flows
• Multi-Platform Support: Deploys to .roo/rules, .kilocode/rules, .clinerules directories
• Template Discovery: List available templates with instruqt list-templates <context> command
• Comprehensive Testing: Enhanced error handling with qerrors and qtests integration
• Global Installation: Install once, use across all your projects

Installation

Install globally via NPM:

npm install -g instruqt

Usage

Navigate to any project directory and run (context mode is required):

# Deploy MERN stack context
instruqt instruct mern

# Deploy NPM package context
instruqt instruct npm

# Deploy FastAPI context
instruqt instruct fastapi

# List available template files for a specific context
instruqt list-templates mern
instruqt list-templates npm
instruqt list-templates fastapi

# Show help
instruqt --help

What It Does

When you run instruqt instruct <context>, the tool executes a four-phase deployment:

1. Phase 1 - Directory Creation (if they don't exist):

   • .roo/rules/ for Roo Code
   • .kilocode/rules/ for Cline/Kilo Code
   • .clinerules/ for other AI agents

2. Phase 2 - Common Context Deployment:

   • Deploys shared files from contexts/common/ to all target directories
   • Special handling: AGENTS.md → project root as both AGENTS.md and replit.md
   • Common files: code quality, security, git workflow, performance guidelines

3. Phase 3 - Context-Specific Deployment:

   • MERN: Full-stack patterns, backend/frontend architecture, database schema
   • NPM: NPM package patterns, clean exports, testing strategies
   • FastAPI: Python backend patterns, API design, async/await best practices
   • Never overwrites existing files - protects your customizations

4. Phase 4 - File Flow Generation:

   • Analyzes your entire codebase with semantic parsing
   • Generates FILE_FLOWS.md with 67 files organized into flow groups
   • Only file that overwrites - always fresh analysis

Context Modes

Common Context (Always Deployed First)

Shared documentation deployed to all contexts:

• Code quality standards
• Security guidelines
• Git workflow patterns
• Performance optimization
• Universal development practices

MERN Context

Perfect for full-stack web applications using:

• MongoDB - NoSQL database
• Express.js - Backend framework
• React - Frontend library
• Node.js - JavaScript runtime

Includes documentation for:

• RESTful API design patterns
• React component architecture
• Feature-first organization
• Database schema design
• Backend/frontend separation
• Authentication & security

NPM Context

Ideal for NPM packages, libraries, and utility modules:

• Single responsibility architecture
• Clean module exports
• Co-located testing
• Utility function patterns
• NPM publication standards

FastAPI Context

Designed for Python API backends:

• Async/await patterns
• Pydantic model validation
• OpenAPI documentation
• Dependency injection
• Python best practices

File Protection Policy

Protected Files (Never Overwritten)

All template files are never overwritten if they already exist:

• AGENTS.md and replit.md in project root
• All files in .roo/rules/, .kilocode/rules/, .clinerules/
• Any custom files you create

Generated Files (Always Overwritten)

Only one file gets refreshed on each deployment:

• FILE_FLOWS.md - Always regenerated with fresh codebase analysis

Template Files Available

Common Context (deployed to all):

• AGENTS.md - Master AI agent documentation (promoted to root)
• Code quality, security, git workflow guidelines

MERN Context:

• 00-AGENTS.md - MERN-specific agent documentation
• 01-STACK_RULES.md - MERN stack guidelines
• 02-MERN_backend_architecture.md - Backend patterns
• 03-MERN_frontend_architecture.md - Frontend patterns
• 04-MERN_backend_naming_conventions.md - Naming standards
• Additional workflow and database documentation

NPM Context:

• 00-AGENTS.md - NPM-specific agent documentation
• architecture.md - NPM architecture guidelines
• features&files.md - Features documentation
• workflows.md - Development workflows

FastAPI Context:

• 00-AGENTS.md - FastAPI-specific agent documentation
• Python backend architecture patterns
• API design guidelines
• Async/await best practices

Examples

Setting Up a New MERN Project

cd my-web-app
instruqt instruct mern
# Deploys Common + MERN context, generates file flows

Setting Up a New NPM Package

cd my-utility-library  
instruqt instruct npm
# Deploys Common + NPM context, generates file flows

Setting Up a FastAPI Project

cd my-python-api
instruqt instruct fastapi
# Deploys Common + FastAPI context, generates file flows

Updating Documentation Across Projects

# After updating instruqt globally
npm update -g instruqt

# Check available templates for each context
instruqt list-templates mern
instruqt list-templates npm
instruqt list-templates fastapi

# Refresh all your projects (context required)
cd project1 && instruqt instruct mern
cd ../project2 && instruqt instruct npm  
cd ../project3 && instruqt instruct fastapi

Advanced Usage - Pack System

For teams and organizations that need to customize or extend the built-in contexts, instruqt provides a powerful pack system that allows you to add custom documentation without modifying the core module.

Quick Pack Example

1. Create a pack folder:

my-team-pack/
├── pack.json
└── files/
    └── team-rules.md

2. Define pack.json:

{
  "name": "my-team-pack",
  "version": "1.0.0",
  "files": [
    {
      "src": "files/team-rules.md",
      "dest": "docs/context/team-rules.md",
      "mode": "create"
    }
  ]
}

3. Apply the pack:

instruqt apply ./my-team-pack --plan  # Preview changes
instruqt apply ./my-team-pack          # Apply changes

Pack System Features

• Multiple pack sources: Local folders, npm packages, aliases, home directory
• Safe file operations: Won't overwrite files unless explicitly allowed
• Inheritance: Extend existing packs with additional files
• Dry run: Preview changes before applying with --plan flag
• Project configuration: Use aliases for commonly used packs

Common Pack Use Cases

Team Guidelines Add team-specific coding standards and workflows that extend the base contexts:

instruqt apply my-team-standards

Project Templates Create project-specific context that includes architecture decisions:

instruqt apply ./project-templates/microservice-pack

Organization Standards Share organization-wide development practices via npm packages:

instruqt apply @mycompany/dev-standards

Personal Preferences Store personal development preferences:

instruqt apply personal-setup  # Resolves to ~/.config/instruqt/packs/personal-setup

Pack Resolution Order

1. Local path: ./my-pack or /absolute/path/to/pack
2. Project alias: Defined in instruqt.config.json
3. NPM package: @scope/pack-name or pack-name
4. Home directory: ~/.config/instruqt/packs/pack-name

Write Modes

• create - Create file, error if exists
• create_if_missing - Create only if missing
• replace_if_tagged - Replace only if file contains <!-- instruqt-managed -->

Directory Structure After Deployment

your-project/
├── AGENTS.md                    # Promoted from contexts/common/AGENTS.md
├── replit.md                    # Copy of AGENTS.md for Replit agents
├── FILE_FLOWS.md                # Generated codebase analysis (67 files, 45 groups)
├── .roo/
│   └── rules/
│       ├── 00-AGENTS.md         # Common or context-specific agent docs
│       ├── 01-STACK_RULES.md    # (MERN context)
│       ├── 02-MERN_backend_architecture.md (MERN context)
│       ├── 03-MERN_frontend_architecture.md (MERN context)
│       ├── 04-MERN_backend_naming_conventions.md (MERN context)
│       ├── architecture.md      # (npm context)
│       ├── features&files.md    # (npm context)
│       ├── workflows.md         # (npm context)
│       └── [FastAPI context files] # (fastapi context)
├── .kilocode/
│   └── rules/
│       └── [same files as .roo/rules/]
└── .clinerules/
    └── [same files as .roo/rules/]

Commands Reference

| Command | Description | |---------|-------------| | instruqt instruct mern | Deploy Common + MERN context + file flows | | instruqt instruct npm | Deploy Common + NPM context + file flows | | instruqt instruct fastapi | Deploy Common + FastAPI context + file flows | | instruqt list-templates <context> | List template files for specific context | | instruqt apply <pack> | Apply custom pack from various sources | | instruqt apply <pack> --plan | Preview pack changes without applying | | instruqt --help | Show usage information and available commands |

Note: Context mode is required for built-in commands - no defaults provided for safety.

Pack Command Examples

# Local pack folder
instruqt apply ./my-team-pack

# NPM package
instruqt apply @mycompany/standards

# Home directory pack
instruqt apply personal-setup

# Project alias (defined in instruqt.config.json)
instruqt apply team-standards

# Preview changes first
instruqt apply ./custom-pack --plan

Error Handling

The tool provides clear error messages for common issues:

• Invalid context mode: Shows available modes and usage examples
• Missing context directory: Indicates which template directory is missing
• Permission errors: Reports file system permission issues
• Invalid arguments: Displays help information

Use Cases

For Development Teams

• Ensure consistent AI agent context across all team members
• Standardize coding patterns and architectural decisions
• Maintain up-to-date development workflows

For Individual Developers

• Quickly onboard AI assistants to new projects
• Switch between different project types seamlessly
• Keep all AI tools synchronized with your coding standards

For Open Source Projects

• Provide contributors with clear development guidelines
• Ensure AI-assisted contributions follow project standards
• Maintain consistent code quality across contributions

Contributing

This tool is designed to be simple and focused. The template files in mern_context/ and npm_context/ can be customized for your specific needs.

Licensing

• Core package: Apache-2.0 (see /LICENSE). You can use it freely under OSS terms.
• Commercial/OEM options (optional): If you want redistribution, OEM embedding, or enterprise features, use our Commercial EULA (see /legal/COMMERCIAL-EULA.md). Contact: you@email

Version History

• 2.0.0 - Enhanced modernization release

  • Quad context system (Common + MERN/NPM/FastAPI contexts)
  • Automatic file flow generation with semantic analysis (67 files → 45 groups)
  • Smart file protection - never overwrites existing files
  • Four-phase deployment pipeline with common context sharing
  • Enhanced error handling with qerrors and qtests integration
  • Async/await architecture with comprehensive testing
  • Breaking Change: Context mode now required (no defaults for safety)
  • Advanced AST parsing for JavaScript/TypeScript code analysis

• 1.0.0 - Production release with complete feature set

  • Dual context mode system (MERN stack and module development)
  • Multi-platform AI agent support (.roo/rules, .kilocode/rules, .clinerules)
  • Template discovery with list-templates command
  • 100% test coverage (71/71 tests passing)
  • Robust configuration loading with fallback mechanisms
  • Global NPM installation and CLI access
  • Published to npm registry for global distribution