---
slug: "noop"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/HDeibler/noop@main/README.md"
repo: "https://github.com/HDeibler/noop"
source_file: "README.md"
branch: "main"
---
# noop

> A Claude Code plugin for generating and maintaining production-ready Express + TypeScript + PostgreSQL + Redis backends.

**noop** is a complete development toolkit that helps you:
- **Generate** new backend projects with a proven architecture
- **Review** code against architectural patterns
- **Add** new domain entities with full CRUD
- **Tend** to infrastructure with health checks and maintenance

## Installation

```bash
# Clone the plugin
git clone https://github.com/deibler/noop.git

# Use with Claude Code
claude --plugin-dir /path/to/noop
```

Or add to your Claude Code settings for permanent installation.

## Commands

| Command | Description |
|---------|-------------|
| `/noop:make` | Generate a new project |
| `/noop:review` | Review code against architecture patterns |
| `/noop:entity-add` | Add a new domain entity with CRUD |
| `/noop:tend` | Infrastructure maintenance and health checks |

### `/noop:make`

Generate a complete, production-ready backend:

```bash
/noop:make my-service --entities=Product,Order --port=3010
```

**What you get:**
- Express 5 with TypeScript (ESM)
- PostgreSQL with pgvector
- Redis/Valkey caching
- Multi-tenant architecture
- Automatic migrations
- Docker Compose setup
- Health checks & graceful shutdown
- Zod configuration validation
- Structured logging

### `/noop:review`

Review code for architectural compliance:

```bash
/noop:review src/handlers/
```

**Checks for:**
- Silent fallbacks (critical)
- `any` types (critical)
- Missing organization scoping
- Business logic in handlers
- Non-RESTful routes
- Direct `process.env` access

### `/noop:entity-add`

Add new entities to existing projects:

```bash
/noop:entity-add Product --fields=price:number,sku:string
```

**Generates:**
- Type definitions
- Database Ops class
- HTTP handlers
- Migration SQL
- Route registration

### `/noop:tend`

Infrastructure maintenance:

```bash
/noop:tend health    # Full health check
/noop:tend deps      # Dependency updates
/noop:tend security  # Security audit
/noop:tend docker    # Docker maintenance
/noop:tend all       # Run everything
```

## Architecture

noop enforces a **function-first, layered architecture**:

```
src/
├── handlers/           # HTTP orchestration only
│   └── services/       # Business logic
├── db/pg/
│   └── *Ops.ts        # Database operations
├── middleware/         # Auth, error handling
├── types/             # Domain types
└── utils/             # Shared utilities
```

### Key Principles

1. **Handlers orchestrate, services execute** - No business logic in handlers
2. **Explicit dependencies** - Pass `dbStore` as parameter, no globals
3. **Organization scoping** - Every DB operation requires `organizationId`
4. **No fallbacks** - Errors are explicit, never hidden
5. **Type safety** - Never use `any` or unnarrowed `unknown`
6. **Fail fast** - Validate configuration at startup

## Plugin Structure

```
noop/
├── .claude-plugin/
│   └── plugin.json         # Plugin manifest
├── commands/
│   ├── make.md            # /noop:make
│   ├── review.md          # /noop:review
│   ├── entity-add.md      # /noop:entity-add
│   └── tend.md            # /noop:tend
├── agents/
│   ├── architect.md       # Architecture planning
│   ├── reviewer.md        # Code review
│   ├── entity-builder.md  # Entity generation
│   └── tender.md          # Infrastructure maintenance
├── skills/
│   ├── scaffold-generator/  # Auto-invoked for generation
│   ├── architecture-guide/  # Auto-invoked for patterns
│   └── entity-generator/    # Auto-invoked for entities
├── hooks/
│   ├── hooks.json           # Plugin hooks config
│   └── architecture-guardian.sh  # Auto-lint & pattern checks
├── docs/universal-framework/  # Architecture documentation
└── scaffold-template/         # Project template
```

## Hooks

noop includes automated hooks:

- **PostToolUse (Write/Edit)**: Runs architecture-guardian.sh for:
  - TypeScript type checking
  - ESLint validation
  - Anti-pattern detection
  - Context-aware guidelines

- **PreToolUse (Bash)**: Blocks `npm run dev/start` (user manages server)

## Custom Agents

Spawn specialized agents for complex tasks:

| Agent | Use Case |
|-------|----------|
| `noop-architect` | API design, schema planning |
| `noop-reviewer` | PR reviews, compliance checks |
| `noop-entity-builder` | Generate full entity CRUD |
| `noop-tender` | DevOps, maintenance tasks |

## Generated Project Structure

When you run `/noop:make`, you get:

```
my-service/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Zod-validated config
│   ├── routes.ts             # Route registration
│   ├── handlers/
│   │   ├── widgetHandler.ts  # CRUD handlers
│   │   └── services/
│   │       └── WidgetService.ts
│   ├── db/
│   │   ├── index.ts
│   │   └── pg/
│   │       ├── PgClient.ts
│   │       ├── PgClientStore.ts
│   │       ├── WidgetOps.ts
│   │       └── migrations/sql/
│   ├── middleware/
│   │   ├── auth.ts
│   │   └── error.ts
│   ├── types/
│   │   └── widget.types.ts
│   └── utils/
│       ├── logger.ts
│       ├── errors.ts
│       └── standardResponse.ts
├── .claude/
│   ├── CLAUDE.md             # Project instructions
│   └── hooks/
│       └── architecture-guardian.sh
├── docker-compose.yml
├── Dockerfile
└── package.json
```

## Documentation

The `docs/universal-framework/` directory contains:

| Document | Purpose |
|----------|---------|
| `PHILOSOPHY.md` | Core architectural principles |
| `ARCHITECTURE_SPEC.md` | Layer specifications |
| `CONVENTIONS.md` | Coding standards |
| `SCAFFOLDING_SPEC.md` | Template structure |
| `GENERATOR_INSTRUCTIONS.md` | Generation guide |
| `CHECKLIST.md` | Quality verification |

## License

MIT