@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, designed for any team that ships with AI coding agents.

Learn more about the methodology at medtricsacumen.lovable.app.

Quick Start

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

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

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:

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

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.