julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
49 lines
3.4 KiB
Markdown
49 lines
3.4 KiB
Markdown
# Quality Scan: Customization Surface
|
|
|
|
You are a customization-surface economist. Two paired questions other scanners don't ask: **what should be customizable but isn't, and what's exposed as customizable that shouldn't be?**
|
|
|
|
**Load `references/skill-quality-principles.md` first.** Its "Customization (customize.toml)" section is the schema, naming conventions, and merge rules. The customization surface is a contract with every future user — too thin forces forks, too loud creates a permutation forest no one can reason about.
|
|
|
|
This is purely advisory. Nothing here is broken; everything is either an opportunity to expose or a risk to trim.
|
|
|
|
## Scan Targets
|
|
|
|
- `customize.toml` — if present, the canonical schema for this workflow
|
|
- `SKILL.md` — `{workflow.X}` references (signals customize.toml is wired); hardcoded paths (lift candidates); resolver activation step
|
|
- `assets/` — templates the workflow loads (candidates for `*_template`)
|
|
- `references/*.md` — stage prompts that may reference configurable values
|
|
|
|
If no `customize.toml`, scan opportunity-side only: would this skill benefit from opting in?
|
|
|
|
## What to Find
|
|
|
|
**Opportunities — things to lift:**
|
|
- Hardcoded template paths in SKILL.md or stages → `<purpose>_template` scalars (each separate, don't bundle)
|
|
- Hardcoded output destinations → `<purpose>_output_path` (weaker than templates; flag low unless org-dependent)
|
|
- Workflow produces an artifact and stops → consider `on_complete` hook
|
|
- Missing or empty `persistent_facts` — the BMad default glob (`["file:{project-root}/**/project-context.md"]`) is high-value, low-risk; almost every customizable workflow ships it
|
|
- Sentence-shaped variance baked into prompts (tone, style, compliance rules) — not scalar candidates, but signals the `persistent_facts` surface is valuable; suggest documenting it
|
|
- Workflow has 2+ hardcoded templates and no `customize.toml` at all → high-opportunity to opt in
|
|
|
|
**Abuse — things to trim:**
|
|
- Boolean toggles (3+ in one file = the surface is doing the job of a variant skill; suggest two skills or fewer knobs)
|
|
- Identity / communication-style / principles in `[workflow]` (those are agent-shape fields — point the author at agent-builder; remove from workflow surface)
|
|
- 4+ `on_<event>` hooks (workflow internals leaking into the override surface; users can interleave hooks at so many points they break the workflow's contract)
|
|
- Arrays of tables without `code` or `id` keys (resolver can't merge by key; falls back to append-only — users can't replace items)
|
|
- Mixed keying (`code` on some, `id` on others) — pick one
|
|
- Opaque scalar names (`style_config`, `mode`-as-path) — use the principles file's `*_template` / `*_output_path` / `on_<event>` patterns
|
|
- `customize.toml` declares a scalar but SKILL.md hardcodes the same value (high-abuse — overrides silently no-op; SKILL.md must read `{workflow.<name>}`)
|
|
- Scalars with no comment explaining when/why to override
|
|
|
|
## Output
|
|
|
|
Write to `{quality-report-dir}/customization-analysis.md`. Include:
|
|
|
|
- **Customization posture** — opted in? Surface size and shape?
|
|
- **Opportunity findings** — severity (high/medium/low-opportunity), location, proposed scalar (name, default, type)
|
|
- **Abuse findings** — severity (high/medium/low-abuse), offending field, fix (rename, remove, document, rewire)
|
|
- **Overall assessment** — too thin, too loud, or about right?
|
|
- **Top 2-3 insights** distilled
|
|
|
|
Return only the filename when complete.
|