npm package: @medtrics/acumen
Description: AI-assisted development workflow — PEBRDT methodology with 16 agent skills
Latest version: 0.2.0

# @medtrics/acumen

AI-assisted development workflow based on the PEBRDT methodology.
16 agent skills that guide your team from spec to ship.

Born at [Medtrics](https://medtricslab.com), designed for any team that ships with AI coding agents.

Learn more about the methodology at [medtricsacumen.lovable.app](https://medtricsacumen.lovable.app/).

## Quick Start

```bash
npx @medtrics/acumen@latest
```

Interactive wizard walks you through template selection, addon installation, and project setup.

> Always use `@latest` to avoid stale npx cache.

## What You Get

```
your-project/
  .agents/
    .acumen-manifest.json    # Install metadata (version, template, addons)
    skills/
      01-PLAN-spec/          # 16 phase skills (SKILL.md in each)
      02-PLAN-mockup/
      ...
  .claude/
    skills -> ../.agents/skills   # Symlink for Claude Code
  AGENTS.md                       # Architecture conventions + skill reference
  CLAUDE.md -> AGENTS.md          # Symlink for Claude Code
  WARP.md -> AGENTS.md            # Symlink for Warp AI
  GEMINI.md -> AGENTS.md          # Symlink for Gemini
```

Skills live in `.agents/skills/`. Symlinks wire them into Claude Code, Warp AI, and Gemini without duplication. Use `--copy` if you prefer hard copies over symlinks.

## Stack Assumptions

This workflow is opinionated for a modern frontend stack:

- **Frontend:** React + TypeScript + Tailwind CSS
- **Backend:** Supabase (PostgreSQL, Auth, Edge Functions, RLS)
- **Build:** Vite
- **Testing:** Vitest (unit) + Playwright (E2E)

Skills 04 (schema) and 05 (edge functions) assume Supabase as the database layer. The optional `REF-supabase` addon provides deeper operational reference.

## The PEBRDT Workflow

```
PLAN --> ENRICH --> BUILD --> REVIEW --> DOCS --> TEST
  |                                                |
  +--<--- repeat per feature ---<------------------+
```

| Phase      | What Happens                                             | Skills         |
| ---------- | -------------------------------------------------------- | -------------- |
| **Plan**   | Define user flows, write specs, create mockups. No code  | 01, 02         |
| **Enrich** | Load architecture rules, review schema, audit edge cases | 03, 04, 05     |
| **Build**  | Fresh session. Paste the spec. Build bottom-up           | 06             |
| **Review** | Code review, browser QA, plan fixes, implement fixes     | 07, 08, 09, 10 |
| **Docs**   | Discover what needs documenting, write it, verify        | 11, 12, 13     |
| **Test**   | Unit tests for logic, E2E for regression                 | 14, 15, 16     |

Key rule: always start a **new session** before BUILD. Planning context (wrong turns, abandoned ideas) pollutes execution.

## Templates

### Lovable

Flat `src/` structure -- no domain boundaries, no service layer, no barrel exports.

```
src/
  components/    # UI components, optionally grouped by feature
  hooks/         # Flat directory -- one hook per file
  pages/         # Route components (lazy-loaded)
  types/         # TypeScript types
  lib/           # Utilities, constants, helpers
  contexts/      # React contexts
  integrations/  # Supabase client + auto-generated types
```

Best for: smaller projects, prototypes, teams that prefer simplicity.

### Domain-Based

Self-contained domain modules with strict boundaries and barrel exports.

```
src/
  domains/
    {name}/          # Self-contained module
      hooks/         # Domain-specific hooks
      services/      # Data layer (*.service.ts)
      types/         # Domain types
      transforms.ts  # DB <-> App type mapping
      index.ts       # Barrel export -- PUBLIC API
  components/        # Shared UI (Atomic Design)
  pages/             # Route components -- thin orchestrators
```

Best for: larger codebases, teams that need clear boundaries, projects with many business domains.

## Addons

Addons install additional reference skills alongside the 16 core workflow skills.

### Supabase

```bash
npx @medtrics/acumen@latest -a supabase
```

Installs `REF-supabase` -- a reference skill covering:

- Migration workflow (create, apply, rollback, consolidation)
- Seeding patterns (SQL-based and script-based)
- Type generation from database schema
- Edge function development, testing, and deployment
- Local vs remote workflows
- Full database reset procedures
- RLS policy patterns
- Troubleshooting guide

### Agent Browser

```bash
npx @medtrics/acumen@latest -a agent-browser
```

Installs `REF-agent-browser` -- a reference skill covering:

- Core workflow (open, snapshot, interact, verify)
- Command reference (navigation, snapshot, interaction, wait, capture, diff)
- Authentication and session persistence
- Command chaining patterns
- Headed mode, annotated screenshots, semantic locators
- JavaScript evaluation, video recording, profiling
- Session management and cleanup
- Troubleshooting guide

## Skills Reference

| #   | Skill               | Phase  | Purpose                             |
| --- | ------------------- | ------ | ----------------------------------- |
| 01  | PLAN-spec           | Plan   | Write feature specification         |
| 02  | PLAN-mockup         | Plan   | Create UI mockups and flows         |
| 03  | ENRICH-architecture | Enrich | Load and apply architecture rules   |
| 04  | ENRICH-schema       | Enrich | Review and enrich database schema   |
| 05  | ENRICH-edge         | Enrich | Audit edge functions and edge cases |
| 06  | BUILD-feature       | Build  | Execute the spec in a fresh session |
| 07  | REVIEW-code         | Review | 9-dimension code review             |
| 08  | REVIEW-clickthrough | Review | Browser-based QA walkthrough        |
| 09  | REVIEW-planfixes    | Review | Plan fixes from review findings     |
| 10  | REVIEW-fixbuild     | Review | Implement planned fixes             |
| 11  | DOCS-discover       | Docs   | Discover what needs documentation   |
| 12  | DOCS-write          | Docs   | Write the documentation             |
| 13  | DOCS-verify         | Docs   | Verify documentation completeness   |
| 14  | TEST-unit-test      | Test   | Write unit tests for logic          |
| 15  | TEST-e2e-discover   | Test   | Discover E2E test scenarios         |
| 16  | TEST-write-e2e      | Test   | Write E2E regression tests          |

Template-specific skills (03, 06, 07) adapt to your chosen architecture. Shared skills (all others) work identically across templates.

## Philosophy

- **Manager mindset** -- Think like a manager instructing a capable intern, not a coder writing code. Communicate intent and constraints, not keystrokes.
- **Three solutions** -- Propose 3 approaches before choosing. Forces trade-off reasoning and surfaces options you would otherwise miss.
- **New session before BUILD** -- Planning context (wrong turns, abandoned ideas) pollutes execution. Start fresh.
- **File deliverables** -- Write into files, not conversation. The output is the plan file, the code, or the report.
- **Review actual code** -- After BUILD, review what was actually written, not what was planned. Reality diverges from plans.

## CLI Options

| Flag                | Short | Purpose                                  | Default     |
| ------------------- | ----- | ---------------------------------------- | ----------- |
| `--template <name>` | `-t`  | Template: `lovable` or `domain-based`    | Interactive |
| `--addon <name>`    | `-a`  | Install addon (repeatable)               | Interactive |
| `--force`           | `-f`  | Overwrite existing files without asking  | false       |
| `--copy`            | `-c`  | Copy files instead of creating symlinks  | false       |
| `--dry-run`         | `-n`  | Show what would be installed, do nothing | false       |
| `--help`            | `-h`  | Show help message                        | --          |

Examples:

```bash
npx @medtrics/acumen@latest                                  # Interactive wizard
npx @medtrics/acumen@latest -t lovable                       # Skip template prompt
npx @medtrics/acumen@latest -t domain-based -a supabase      # Template + addon
npx @medtrics/acumen@latest -a supabase -a agent-browser     # Multiple addons
npx @medtrics/acumen@latest -t domain-based -a supabase -f   # Full flags, overwrite
npx @medtrics/acumen@latest -c                               # Copy instead of symlinks
npx @medtrics/acumen@latest -n                               # Dry run
```

## Contributing

### Adding a Template

1. Create `templates/<name>/AGENTS.md` with architecture conventions
2. Create `templates/<name>/skills/` with template-specific skills (03, 06, 07)
3. Add the name to `TEMPLATE_NAMES` in `src/constants.ts`

### Adding an Addon

1. Create `addons/<name>/` with one or more skill directories (each containing `SKILL.md`)
2. Add the name to `ADDON_NAMES` and `ADDON_DESCRIPTIONS` in `src/constants.ts`

### Adding a Shared Skill

1. Create `templates/shared/skills/<NN-PHASE-name>/SKILL.md`
2. Update the skills reference table in both template `AGENTS.md` files

### Development

```bash
bun install
bun run dev              # Run CLI locally
bun run build            # Build for distribution
bun run check            # Biome lint + TypeScript type-check
bun run format           # Format code + markdown
```

## License

MIT -- see [LICENSE](./LICENSE).