npm package: @purelykai/blueprint-ai
Description: Automated AI context and skill orchestration for development projects.
Author: Kai Black
Latest version: 0.3.0

# 🧬 Blueprint AI

**Automated AI context and skill orchestration for development projects.**

Blueprint AI solves the **Context Cold-Start Problem** — where AI coding agents (Claude Code, Cursor, Copilot) lack project-specific architectural awareness. It scans your repository, detects your stack, and injects best-practice rules as **Passive Context** that's always-on. It also acts as a headless manager for the **Skills.sh** ecosystem, automatically installing and locking the right skills for your stack.

## How It Works

```
┌─────────────┐    ┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
│  Phase 1     │    │  Phase 2      │    │  Phase 3          │    │  Phase 4      │
│  DNA Scanner │ ─▶ │  Skills.sh    │ ─▶ │  Passive Context  │ ─▶ │  Bridge       │
│  (700+ techs │    │  Automation   │    │  Generator        │    │  Logic        │
│  + folders)  │    │  (headless)   │    │  (folder-aware)   │    │  (cross-stack)│
└─────────────┘    └──────────────┘    └──────────────────┘    └──────────────┘
```

1. **Scan** — Deep structural audit using [`@specfy/stack-analyser`](https://github.com/specfy/stack-analyser) (700+ technology detection) + folder-level tech mapping
2. **Skills** — Maps detected techs to Skills.sh skill IDs, headlessly installs them into `.claude/skills/` and `.agents/skills/`, and locks versions in `skills-lock.json`
3. **Context** — Generates folder-aware `.cursor/rules/*.mdc` files (e.g., `api.mdc` scoped to `api/**/*` with Go rules) and a consolidated `.clauderules` file
4. **Bridge** — Detects cross-stack signatures and injects coordination rules (e.g., "When modifying a model in the Go directory, check for a corresponding interface in the React directory")

## Installation

```bash
npm install -g @purelykai/blueprint-ai
```

## Usage

```bash
# Run in your project root
blueprint-ai

# Scan a specific directory
blueprint-ai ./my-project

# Preview without writing files
blueprint-ai --dry-run

# Generate only specific formats
blueprint-ai --claude-only
blueprint-ai --cursor-only
blueprint-ai --skills-only

# Skip specific formats
blueprint-ai --no-skills

# Verbose output (shows unmatched techs, bridge context, folder map)
blueprint-ai -v
```

## Output Files

| File | Purpose |
|------|---------|
| **`.clauderules`** | Forces Claude to follow the project "Map" from the first message. |
| **`.cursor/rules/api.mdc`** | Sets specific Go/Gin constraints for the `/api` folder. |
| **`.cursor/rules/blueprint-*.mdc`** | Global tech-specific rules for Cursor. |
| **`.claude/skills/*/SKILL.md`** | Skills.sh-format skills for Claude Code. |
| **`.agents/skills/*/SKILL.md`** | Raw `SKILL.md` files following agentskills.io standard. |
| **`skills-lock.json`** | Records the skills and versions used for team parity. |

## Cross-Stack Bridges

The **core differentiator**. When Blueprint AI detects technologies spanning multiple domains, it injects specialized coordination rules:

| Bridge | Trigger | What It Governs |
|--------|---------|-----------------|
| Backend ↔ Frontend API | Express + React, etc. | API contracts, type sync, error shapes |
| Backend ↔ Mobile API | Go + React Native, etc. | Offline-first APIs, auth tokens, versioning |
| Go ↔ React Native | Go/Gin + RN/Expo | Protobuf specs, CORS, Docker Compose dev |
| Full-Stack JavaScript | Express + React, etc. | Monorepo strategy, shared types, tRPC |
| Next.js Full-Stack | Next.js detected | Server/client boundary, Server Actions |
| Backend ↔ Database | Django + PostgreSQL, etc. | Connection pooling, migrations, repositories |
| Containerized App | Docker + any app tech | Multi-stage builds, dev workflow, security |

## Folder-Aware Rules

Blueprint AI scans your top-level directories to detect which technologies each folder uses. It then creates **folder-scoped Cursor rules** with precise glob patterns:

```
.cursor/rules/
├── api.mdc              # glob: api/**/*  → Go, Gin rules
├── frontend.mdc         # glob: frontend/**/*  → React, TypeScript rules
├── blueprint-go.mdc     # Global Go rules (for files outside detected folders)
├── blueprint-react.mdc  # Global React rules
└── blueprint-bridge-backend-frontend-api.mdc  # Cross-stack bridge (always apply)
```

This ensures the AI only thinks about Go/Gin rules when you're working in the `api/` folder, and React rules when you're in `frontend/`.

## Supported Technologies

Blueprint AI includes curated rules for **35+ technologies** across these categories:

- **Languages:** JavaScript, TypeScript, Go, Python, Rust, Java
- **Frontend:** React, Next.js, Vue, Angular, Svelte
- **Mobile:** React Native, Expo, Flutter
- **Backend:** Express, Fastify, NestJS, Django, Flask, FastAPI, Gin
- **Databases:** PostgreSQL, MongoDB, Redis, Prisma
- **Infrastructure:** Docker, Kubernetes, Terraform
- **Styling:** Tailwind CSS
- **Testing:** Jest, Vitest
- **Tooling:** ESLint, Webpack, Vite
- **Runtime:** Node.js, Deno, Bun

Technologies not in the registry are still detected and listed — they just won't have specific rule templates yet.

## Architecture

```
src/
├── cli.js              # Entry point — 4-phase pipeline with commander
├── scanner.js          # Phase 1 — @specfy/stack-analyser + folder-tech detection
├── resolver.js         # Phase 2-4 — Skills mapping, rules, bridges, folder rules
├── writer.js           # Output — Multi-format context writer
├── skills/
│   └── index.js        # Skills.sh tech-key → skill-ID lookup table
├── rules/
│   └── index.js        # Technology rule registry (35+ technologies)
└── bridges/
    └── index.js        # Cross-stack bridge detection & templates
```

## Development

```bash
# Clone and link locally
git clone https://github.com/purelyKai/blueprint-ai.git
cd blueprint-ai
npm install
npm link

# Test on any project
cd /path/to/your/project
blueprint-ai --dry-run -v
```

## License

MIT