# AI Toolkit

AI guardrails and productivity enhancements for secure development with Claude Code, Cursor IDE, Codex CLI, and GitHub Copilot.

## Quick Start

```bash
# Run installer without installing package
npx -y @northbridge-security/ai-toolkit@latest install

# Or using bun
bunx @northbridge-security/ai-toolkit@latest install
```

For detailed installation instructions, configuration options, and troubleshooting, see [Installation Guide](docs/installer.md).

## Commands

| Command                                           | Description                                |
| ------------------------------------------------- | ------------------------------------------ |
| `npx -y @northbridge-security/ai-toolkit`         | Run installer without installing package   |
| `bunx @northbridge-security/ai-toolkit`           | Run installer using bun                    |
| `npm install -g @northbridge-security/ai-toolkit` | Install globally with npm                  |
| `ai-toolkit install`                              | Run installer (interactive tool selection) |
| `ai-toolkit install -t claude cursor`             | Install specific tools                     |
| `ai-toolkit list-services`                        | List available services                    |
| `ai-toolkit add-secret anthropic`                 | Add secret to 1Password                    |
| `ai-toolkit setup-secrets`                        | Setup secrets interactively                |
| `ai-toolkit markdown lint`                        | Lint markdown files                        |
| `ai-toolkit markdown lint --fix`                  | Auto-fix markdown issues                   |
| `ai-toolkit markdown setup`                       | Install markdownlint and create config     |
| `ai-toolkit yaml lint`                            | Lint YAML files                            |
| `ai-toolkit yaml lint --fix`                      | Auto-fix YAML issues                       |
| `ai-toolkit yaml setup`                           | Install prettier for YAML                  |
| `ai-toolkit json lint`                            | Lint JSON files                            |
| `ai-toolkit json lint --fix`                      | Auto-fix JSON formatting                   |
| `ai-toolkit bash lint`                            | Lint bash scripts with shellcheck          |
| `ai-toolkit bash format`                          | Format bash scripts with shfmt             |
| `ai-toolkit bash format --check`                  | Check bash formatting                      |
| `ai-toolkit bash setup`                           | Install shellcheck and shfmt               |
| `ai-toolkit --help`                               | Show help and available commands           |

## Components

| Component                                     | Description                                           |
| --------------------------------------------- | ----------------------------------------------------- |
| [Task Library](tasks/README.md)               | GoTask automation scripts for development workflows   |
| [Slash Commands](docs/commands/README.md)     | Reusable command templates for AI agents              |
| [Best Practice Guides](docs/guides/README.md) | Standards and best practices for AI-generated content |

## Documentation

- [Installation Guide](docs/installer.md) - Detailed installation and configuration
- [1Password Integration](docs/1password.md) - Secret management setup
- [MCP Integration](docs/mcp-integration.md) - Model Context Protocol details

## Contributing

Interested in contributing? See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for development setup, coding standards, and contribution guidelines.

## License

This software is proprietary and confidential to Northbridge Security AB. See [LICENSE](LICENSE) for full terms.

**Important**: This is NOT open-source software. Usage is restricted to authorized Northbridge Security, Northbridge AB, and TechStars portfolio personnel only.

## Features

The AI Toolkit installer configures security and quality guardrails across supported AI development tools:

### Code Quality & Standards

- **Conventional Commits** - Enforced commit message format via git hooks
- **Linting & Formatting** - ESLint, Prettier, and language-specific linters
- **Type Safety** - TypeScript strict mode and type checking
- **Code Coverage** - >80% test coverage targets with automated reporting

These rules are enforced at both the repository and AI tooling levels through automated hooks, ensuring consistent team practices and standards.

### Security Controls

- **Secret Management** - 1Password CLI integration, prevents secret commits
- **Security Scanning** - Semgrep static analysis for vulnerability detection
- **Tool Allowlists** - Restrict AI tool permissions via `.claude/settings.json`
- **PreToolUse Hooks** - Validate and audit AI tool actions before execution

These controls limit AI agent access to GitHub operations. While you retain full access using your SSH key, AI agents can only read repositories and create pull requests. Semgrep static analysis prevents secrets from being committed to Git. The 1Password integration requires biometric authentication at runtime to access secrets mapped from environment files, ensuring you're always notified when AI agents request secret access.

### Permission & Access

- **MCP Server Policies** - Controlled access to Model Context Protocol servers
- **Privilege Escalation** - User-space first, explicit sudo requests when needed
- **API Key Management** - Environment-based configuration, never committed

Common MCP servers are pre-installed for task management, repository operations, and tool integrations. AI agents require explicit user approval to access resources or perform actions.

### AI-Specific Protections

- **No AI Attribution** - Blocked "Co-authored-by: AI" in commits via hooks
- **Prompt Injection Guards** - Input validation in AI-facing interfaces
- **Action Logging** - Comprehensive logging for AI operations and decisions

### Development Workflow

- **Git Integration** - Safe branching, PR templates, and workflow automation
- **Dependency Validation** - Task dependency checking and circular reference prevention
- **Cross-Platform Safety** - Consistent behavior across macOS, Linux, and Windows

These guardrails are automatically configured during installation and can be customized per project via configuration files in `.claude/`, `.taskmaster/`, and root-level dotfiles.