# SmartStack Skills — Index

> Organized by business phase. Each skill has a `SKILL.md` + optionally a `cli/`.
> A sub-context loads only the relevant skill + 1-2 JSON spec files.

> **Language rule**: All skills must be written in English.

## Scope

This directory ships **only the skills deployed by the SmartStack CLI** into
`~/.claude/skills/` (or `./.claude/skills/` with `--local`). Each skill exists
to **analyze**, **develop**, **audit**, or **validate** a client
SmartStack.app project.

Skills that operate on the SmartStack.Studio source itself (Studio self-audit,
EPCT workflow for Studio features, Electron app debugging, Studio runtime
internals) are **not deployed by the CLI** — they live in the Studio repo.

## Architecture — Skills + colocalized CLIs (no MCP)

The legacy `SmartStack.mcp` server was removed in v5. Every operation it used
to perform is now implemented as a skill with a colocalized CLI:

```
skills/
├── lib/              # Shared TypeScript utilities (detector, dotnet, fs, git, …)
├── efcore/           # EF Core migrations (5 CLIs)
├── gitflow/          # GitFlow workflow (10 CLIs)
├── external/         # Wrappers around external tools (ctx7, dev-browser)
├── business-analyse/             # 28 BA skills (audit, define, generate, modeling, design)
├── ba-develop/     # PRD-driven phased pipeline (Domain → Data → API → Frontend)
├── development/
│   ├── backend/        # entity, dto, repository, business-layer, controller, …
│   ├── frontend/       # theme, layout, routes, component, api-client, …
│   ├── audit-dev-*/    # 12 per-layer audit rules
│   ├── debug/, run/, testing/
├── validation/         # conventions, cross-validate, eslint, roslyn, readiness-report, project-inventory
├── conventions/        # SmartStack.app conventions reference
├── init/, upgrade/, review/   # Project lifecycle skills
├── check-version/      # Verify package.json ↔ docs alignment
├── cli-app-sync/       # Detect template drift between SmartStack.app and CLI
├── dev-start/          # `ss dev` orchestrator (backend + frontend + admin credentials)
├── quick-search/       # Fast codebase Q&A
├── smoke-generation/   # Static analysis of CLI templates against SmartStack.app
├── utils/              # Utility sub-skills for CLI development
└── validate-feature/   # End-to-end validation of a scaffolded feature
```

Internal CLIs are invoked via:

```bash
npx tsx skills/<phase>/<skill>/cli/<cli>/index.ts --spec '<JSON>'
```

Each CLI returns a JSON envelope on stdout (see `lib/output.ts`).

## Infrastructure skills

The following skills provide cross-cutting infrastructure (not a business phase):

| Skill | Role |
|-------|------|
| `efcore` | EF Core migration workflow (`create`, `squash`, `rebase-snapshot`, `list`, `status`) |
| `external` | Wrappers around external tools (`context7`, `dev-browser`) |
| `gitflow` | GitFlow workflow (10 CLIs covering init → finish) |
| `lib` | Shared TypeScript utilities for CLIs |

## lib (shared utilities)

| File | Role |
|------|------|
| `fs.ts` | File system helpers — findFiles (minimatch-based), read/write, path security |
| `git.ts` | Git commands — branch, diff, changed/staged files |
| `detector.ts` | `findSmartStackStructure()` — locates Domain/Application/Infrastructure/Api/web/migrations |
| `dotnet.ts` | `.csproj` parsing, DbContext detection, `detectNamespaces()` |
| `navroute-parser.ts` | Extracts `[NavRoute]` attributes from C# controllers |
| `string-utils.ts` | kebab/camel/pascal/singular/plural helpers |
| `template-loader.ts` | Handlebars wrapper with registered helpers |
| `output.ts` | Standardized stdout JSON envelope for dev CLIs |
| `frontend-fixers.ts` | Tailwind / theme auto-fix utilities for the frontend audit chain |

Import from CLIs via relative path: `import { … } from '../../../../lib/<file>.js'`

## external (external tool wrappers)

| Skill | Role |
|-------|------|
| `context7` | Wraps the `ctx7` CLI (Upstash Context7) — fetches up-to-date library docs via Bash. Replaces the legacy MCP server. |
| `dev-browser` | Points to the SawyerHood/dev-browser plugin (browser automation via sandboxed QuickJS WASM). Installed via `/plugin marketplace add sawyerhood/dev-browser`. |

## gitflow (workflow)

| Skill | CLI | Role |
|-------|-----|------|
| `gitflow` | `cli/` (10 colocalized CLIs) | Drives the GitFlow workflow |

Sub-files: `_shared.md`, `agents/*.md` (10 agents).
CLIs: `cli/{init,start,commit,sync,pr,merge,finish,status,cleanup,abort}/` — each with `types.ts` (Zod), `validate.ts`, `execute.ts`, `index.ts`.
Shared lib: `cli/lib/` — self-contained git utilities.
Config stored at `.claude/gitflow/config.json` (provisioned by `ss install`).

## efcore (EF Core migrations)

| Skill | CLI | Role |
|-------|-----|------|
| `efcore` | `cli/` (5 colocalized CLIs) | EF Core migration workflow |

Sub-files: `_shared.md` (naming, `dotnet-ef` PATH, dual DbContext), `agents/*.md` (list, status, create, squash, rebase-snapshot, db-update).
CLIs: `cli/{list,status,create,squash,rebase-snapshot}/` — each with `types.ts` (Zod), `validate.ts`, `execute.ts`, `index.ts`.
Shared lib: `cli/lib/` — `detect-dbcontexts`, `parse-csproj-version`, `migration-name`, `ef-runner`.

Naming convention: `{prefix}_v{version}_{seq3}_{Description}` — computed by `cli/lib/migration-name.ts`.

## business-analyse/  →  deployed as top-level `/ba-*` commands

File-based business analysis (native Claude Code — **no Studio, no JSON
envelopes, no `[ACTION]`/`[QUESTION]` blocks**). Each skill reads/writes the
**`.smartstack/ba/` markdown tree** (Application → Module → Section → Resource;
each node folder holds `index.md` + `acteur.md`, `entité.md`, `use-case.md`,
`règles-métier.md`, `rbac.md`, `screen.md`). The shared file model + doc
skeletons live in `_workflow/ba-files.md` and `_workflow/doc-templates.md`.
Authored under `business-analyse/<name>/`, the installer **flattens + prefixes**
each to `ba-<name>/` so it is invocable as `/ba-<name>` (`_workflow/` and any
index are repo-only, not deployed).

| Skill (invoked as) | Phase | Writes |
|--------------------|-------|--------|
| `/ba-create-menu` | 1 menu | the node tree (`index.md` per node) |
| `/ba-create-ba-order` | 1.5 BA order | `_plan/ba-order.md` + `.json` + `depends=` in module `index.md` |
| `/ba-loop` | 2-7 auto | Orchestrator: chains all phases via subagents (create → audit → fix) |
| `/ba-create-actors` | 2 actors | `acteur.md` (app) |
| `/ba-create-use-case` | 3 use cases | `use-case.md` (section) |
| `/ba-create-business-rules` | 4 rules | `règles-métier.md` (valid/invalid examples) |
| `/ba-create-rbac` | 5 RBAC | `rbac.md` (module) |
| `/ba-create-data-model` | 6 data model | `entité.md` (module) |
| `/ba-create-screen` | 7 screens | `screen.md` (section/resource) |
| `/ba-create-prd` | synthesis | `prd.md` + 3 phase slices + `pagespecs/*.md` + `claude.md` |
| `/ba-audit-menu` … `/ba-audit-screens`, `/ba-audit-cross-dimension`, `/ba-audit-cross-ref-code` | per-dimension audits | `<scope>/_audit/<dim>.md` verdict |
| `/ba-audit-prd` | PRD audit (~48 checks; US/AC checks moved to /ba-audit-use-cases UC-012..018) | `<MODULE>/_audit/prd.md` with the GO/NO-GO dev gate (score ≥ 80) |
| `/ba-audit-pre-dev` | readiness orchestrator | aggregates `_audit/*.md` → `_audit/pre-dev.md` (GO/NO-GO) |
| `/ba-modeling-inventory`, `/ba-modeling-detail` | optional 2-pass fast modeling | `_inventory.md` → UC/BR docs |

Audits keep their rule sets verbatim (MENU/ACT/UC/BR/RBAC/DM/SCR/PRD-NNN); only
the I/O is file-based. Then `/ba-develop` consumes the module's PRD
files to generate code. (The Studio-era `create-prd-{scaffold,stories,refs,
pagespecs}` and `_fallback-summary` were folded/removed in the v5 file migration.)

## development/backend/

| Skill | CLI | Role |
|-------|-----|------|
| `structure` | — | .NET Clean Architecture 4 layers (reference doc) |
| `core-seed` | scaffold-core-seed | Bootstrap navigation, applications, modules, sections in `CoreSeedData` |
| `seed-data` | scaffold-seed-data | Feature-scoped DevData seed |
| `data-layer` | scaffold-migration | EF Core migration generation |
| `business-layer` | scaffold-business | Service/MediatR + FluentValidation |
| `controller` | scaffold-controller | **Integration** controller (`/api/v1/integration/...`, Swagger group `integration`) — CRUD + UC transitions for machine-to-machine consumers |
| `screen-controller` | scaffold-screen-controller | **Screen-driven** controller (`/api/screens/{plural}/...`, Swagger group `screens`) — one endpoint per BA pagespec, payload shaped from `pagespecs/<Entity>.<view>.md`. Phase 2b of `/ba-develop`, fans out per (section, entity). |

## development/frontend/

| Skill | CLI | Role |
|-------|-----|------|
| `structure` | — | React + Vite + Tailwind (reference doc) |
| `theme` | scaffold-theme | Bootstrap `src/index.css` with CSS vars + Shoelace tokens + design tokens. Idempotent; honors `/* @customised */` marker. |
| `layout` | scaffold-layout | Scaffold `src/components/{PageTemplate,AppShell,Sidebar}.tsx` (nav from `/api/navigation/menu`). Idempotent; honors `// @customised` marker. |
| `ui-primitives` | scaffold-ui-primitives | Scaffold theme-compliant primitives into `src/components/ui/` (today: `EntityLookup.tsx` — debounced+paginated FK combobox; tomorrow: `EnumSelect`, `DateInput`). Idempotent; honors `// @customised`. Closes the historical EntityLookup paradox. |
| `routes` | scaffold-routes | Dynamic routes driven by `GET /api/navigation/menu` |
| `component` | scaffold-component (7 patterns) | React TypeScript component |
| `api-client` | scaffold-api-client | TypeScript services + React Query hooks consuming `/api/{module}/{plural}` |
| `auth` | scaffold-frontend-auth | useAuth hook (Zustand) + PermissionGuard component — wiring for `[RequirePermission]` gating |
| `extension-config` | scaffold-extension-config | `ExtensionConfig` with slot catalog mirroring component emits |
| `ui-polish` | ui-polish (audit-apply) | CSS tokens / design rules audit + mechanical fix |

## development/audit-dev-*

12 audit rules per layer, each callable independently:

- `audit-dev-domain` — DEV-DOMAIN-001..N
- `audit-dev-data` — DEV-DATA-001..N
- `audit-dev-core` — DEV-CORE-001..N (seed data, navigation)
- `audit-dev-api` — DEV-API-001..N
- `audit-dev-frontend` — DEV-UI-001..022 (incl. theme tokens, dark prefix, hex in className, EntityLookup FK gate)
- `audit-dev-tests` — DEV-TEST-001..003 (BA AC ↔ generated [Trait("AC",…)] coverage + no `// TODO[AC-` markers + no stale traits). BLOCKING gate after /ba-develop Phase 4.

Each `audit-dev-*` skill has a deterministic CLI sibling for orchestrator-driven
auto-apply on re-run (`audit-apply` mode). `audit-dev-tests` is read-only (no
auto-apply — findings route back to /ba-develop Phase 4 for remediation).

## development/{debug, run, testing, audit, smoke-test}

- `debug` — Systematic bug debugging with deep analysis
- `run` — Launch dev environment helpers (orchestrated by top-level `dev-start`)
- `testing` — .NET 8 infrastructure tests (4 layers): `scaffold-test-projects`, `scaffold-test-examples`, `validate-test-infra`, `generate-coverage`. **`scaffold-tests-from-ac`** (Wave 2, 2026-05-27): emits one xUnit `[Fact]` per BA Acceptance Criterion (`<UC-code>#AC-NN` trait), TODO-skeleton body filled by `/ba-develop` Phase 4. Audit `DEV-TEST-001` (Wave 3) blocks merge on remaining TODOs.
- `audit` — Cross-cutting audits (routing-dynamic, …)
- `smoke-test` (CLI `run-smoke`) — Runtime gate. Boots backend (`dotnet run`) + frontend (`npm run dev`) in background, probes every page route + API endpoint, fails on any 4xx/5xx or missing page. Designed as the final gate of `ba-develop`.

## validation/

CLI-driven skills invoked by Claude via Bash. Every CLI returns a structured
JSON report on stdout (see `lib/output.ts`).

| Skill | CLI | Role |
|-------|-----|------|
| `conventions` | validate-conventions | Audit namespaces, entities, controllers against SmartStack conventions |
| `cross-validate` | — | Backend ↔ frontend consistency |
| `readiness-report` | — | GO/NO-GO score /100 |
| `roslyn` | — | Static C# analysis by layer |
| `eslint` | — | 5-layer React architecture rules |
| `project-inventory` | — | Lists existing entities, controllers, routes |

## Lifecycle & support skills

| Skill | Role |
|-------|------|
| `ba-develop` | PRD-driven phased development. Consumes the PRD (devReady gate ≥ 80), orchestrates 4 sub-agents (Domain → Data → API → Frontend), each loaded with ONE slice only. Gates between phases (build + tests). |
| `init` | Project initialization (`ss init`) |
| `upgrade` | Project update (`ss upgrade`) |
| `review` | Code review across 9 categories |
| `conventions` | SmartStack.app conventions reference (read-only) |
| `check-version` | Verify `package.json` ↔ documentation alignment |
| `cli-app-sync` | Detect template drift between SmartStack.app and the CLI templates |
| `dev-start` | `ss dev` orchestrator (backend + frontend + admin credentials) |
| `quick-search` | Fast codebase Q&A |
| `smoke-generation` | Static analysis catching documented imports/types/signatures that don't exist in SmartStack.app |
| `validate-feature` | End-to-end validation of a scaffolded feature (compile + tests + API smoke test) |
| `ui-components` | Verify a page (or the whole app) respects the theme — zero hardcoded colors — and auto-fix. Thin orchestrator over the `development/frontend/ui-polish` engine (no duplicated logic). |
| `utils` | Utility sub-skills for CLI development |

## Loading rules

- Never more than 2 skills in a sub-context
- One skill + 1–2 JSON spec files = 5–10 k tokens max
- Each `SKILL.md` has a YAML frontmatter (`name`, `description`, `argument-hint`, `allowed-tools`, …)
- `dev-cli` skills: code lives in `skills/<phase>/<skill>/cli/<cli-name>/`, invoked via `npx tsx`
