arcane-cli 0.14.0 → 0.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +253 -253
- package/dist/assets/.arcane/agents/agent-policies-template.md +414 -414
- package/dist/assets/.arcane/governance/agent-policies.md +414 -414
- package/dist/assets/.arcane/governance/agent-work-queue-model.md +61 -61
- package/dist/assets/.arcane/governance/cicd-standards.md +227 -227
- package/dist/assets/.arcane/governance/development-methodology.md +384 -384
- package/dist/assets/.arcane/governance/git-conventions.md +759 -759
- package/dist/assets/.arcane/governance/naming-conventions.md +142 -142
- package/dist/assets/.arcane/governance/new-business-setup.md +182 -182
- package/dist/assets/.arcane/governance/portable-bootstrap.md +101 -101
- package/dist/assets/.arcane/governance/product-excellence-standards.md +211 -211
- package/dist/assets/.arcane/governance/testing-standards.md +158 -158
- package/dist/assets/.arcane/governance/universal-agent-rules.md +108 -108
- package/dist/assets/.arcane/image-prompts/adelaide-image-prompt.md +140 -140
- package/dist/assets/.arcane/image-prompts/alexander-image-prompt.md +138 -138
- package/dist/assets/.arcane/image-prompts/bess-image-prompt.md +139 -139
- package/dist/assets/.arcane/image-prompts/circe-image-prompt.md +143 -143
- package/dist/assets/.arcane/image-prompts/custodio-image-prompt.md +140 -140
- package/dist/assets/.arcane/image-prompts/iris-image-prompt.md +139 -139
- package/dist/assets/.arcane/image-prompts/kellar-image-prompt.md +141 -141
- package/dist/assets/.arcane/image-prompts/lafayette-image-prompt.md +140 -140
- package/dist/assets/.arcane/image-prompts/lince-image-prompt.md +142 -142
- package/dist/assets/.arcane/image-prompts/mercurio-image-prompt.md +140 -140
- package/dist/assets/.arcane/image-prompts/merlin-image-prompt.md +139 -139
- package/dist/assets/.arcane/image-prompts/prospero-image-prompt.md +141 -141
- package/dist/assets/.arcane.json +5 -0
- package/dist/assets/.claude/commands/spell-enchant.md +9 -9
- package/dist/assets/.github/agents/adelaide.agent.md +44 -44
- package/dist/assets/.github/agents/alexander.agent.md +43 -43
- package/dist/assets/.github/agents/bess.agent.md +42 -42
- package/dist/assets/.github/agents/circe.agent.md +43 -43
- package/dist/assets/.github/agents/custodio.agent.md +44 -44
- package/dist/assets/.github/agents/iris.agent.md +43 -43
- package/dist/assets/.github/agents/kellar.agent.md +43 -43
- package/dist/assets/.github/agents/lafayette.agent.md +42 -42
- package/dist/assets/.github/agents/lince.agent.md +43 -43
- package/dist/assets/.github/agents/mercurio.agent.md +43 -43
- package/dist/assets/.github/agents/merlin.agent.md +44 -44
- package/dist/assets/.github/agents/prospero.agent.md +43 -43
- package/dist/assets/.github/prompts/spell-close-session.prompt.md +17 -5
- package/dist/assets/.github/prompts/spell-commit-work.prompt.md +24 -6
- package/dist/assets/.github/prompts/spell-create-pull-request.prompt.md +12 -3
- package/dist/assets/.github/prompts/spell-enchant.prompt.md +385 -385
- package/dist/assets/.github/prompts/spell-feedback.prompt.md +113 -113
- package/dist/assets/.github/prompts/spell-full-cycle.prompt.md +202 -201
- package/dist/assets/.github/prompts/spell-implement.prompt.md +101 -101
- package/dist/assets/.github/prompts/spell-open-session.prompt.md +20 -5
- package/dist/assets/.github/prompts/spell-scope.prompt.md +263 -263
- package/dist/assets/agents/architecture-lead.yaml +61 -61
- package/dist/assets/agents/collaborator.yaml +59 -59
- package/dist/assets/agents/devops.yaml +60 -60
- package/dist/assets/agents/frontend-dev.yaml +60 -60
- package/dist/assets/agents/fullstack-dev.yaml +59 -59
- package/dist/assets/agents/marketing-strategist.yaml +60 -60
- package/dist/assets/agents/mobile-dev.yaml +59 -59
- package/dist/assets/agents/operations-comms.yaml +58 -58
- package/dist/assets/agents/orchestrator.yaml +60 -60
- package/dist/assets/agents/qa-lead.yaml +60 -60
- package/dist/assets/agents/research-analyst.yaml +59 -59
- package/dist/assets/agents/security-ops.yaml +61 -61
- package/dist/index.js +346 -9
- package/dist/index.js.map +1 -1
- package/package.json +72 -72
- package/dist/assets/.claude/commands/spell-eas-ios-deploy.md +0 -9
- package/dist/assets/.github/prompts/spell-eas-ios-deploy.prompt.md +0 -183
|
@@ -1,211 +1,211 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Product Excellence Standards
|
|
3
|
-
audience: both
|
|
4
|
-
last_updated: YYYY-MM-DD
|
|
5
|
-
status: active
|
|
6
|
-
tags:
|
|
7
|
-
[quality, ux, accessibility, performance, security, spell-enchant, ADR-052]
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
# Product Excellence Standards
|
|
11
|
-
|
|
12
|
-
## Purpose
|
|
13
|
-
|
|
14
|
-
Define what "the best version of an app" means across every dimension — UX, accessibility, performance, security, and polish. This document provides the **PRD Quality Scorecard** that [[.github/prompts/spell-enchant.prompt|spell-enchant]] evaluates against when enchanting a PRD from functional to exceptional.
|
|
15
|
-
|
|
16
|
-
## Quality Dimensions
|
|
17
|
-
|
|
18
|
-
### 1. Requirements Completeness
|
|
19
|
-
|
|
20
|
-
| Criterion | Description |
|
|
21
|
-
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
22
|
-
| **Testable acceptance criteria** | Every requirement has ≥1 acceptance criterion that can be verified by an automated test or a concrete manual check |
|
|
23
|
-
| **Priority classification** | All requirements classified as Must Have / Should Have / Won't Have |
|
|
24
|
-
| **Scope boundary** | "Won't Have" section explicitly excludes items to prevent scope creep |
|
|
25
|
-
| **Dependency identification** | External services, APIs, and decisions the feature depends on are listed |
|
|
26
|
-
| **Open questions documented** | Unresolved items are captured — not ignored or assumed |
|
|
27
|
-
|
|
28
|
-
### 2. User Experience (UX)
|
|
29
|
-
|
|
30
|
-
| Criterion | Description |
|
|
31
|
-
| ---------------------- | --------------------------------------------------------------------------------------------------- |
|
|
32
|
-
| **Full user journey** | Every user-facing feature defines: happy path, error states, edge cases, empty states |
|
|
33
|
-
| **Loading states** | Users see meaningful feedback during async operations (skeleton screens, spinners, progress bars) |
|
|
34
|
-
| **Error recovery** | Errors include actionable messages — users know what went wrong and what to do next |
|
|
35
|
-
| **Empty states** | First-use and zero-data states guide users toward the next action rather than showing blank screens |
|
|
36
|
-
| **Success feedback** | Completions are acknowledged (toast, animation, redirect) — users know their action worked |
|
|
37
|
-
| **Onboarding flow** | New users have a clear path from zero to first value delivered |
|
|
38
|
-
| **Consistency** | UI patterns, terminology, and behavior are consistent across features |
|
|
39
|
-
| **Micro-interactions** | Transitions, hover effects, and subtle animations provide polish without slowing users down |
|
|
40
|
-
|
|
41
|
-
### 3. Accessibility (WCAG 2.1 AA Baseline)
|
|
42
|
-
|
|
43
|
-
| Criterion | Description |
|
|
44
|
-
| ------------------------- | ---------------------------------------------------------------------------------- |
|
|
45
|
-
| **Keyboard navigation** | All interactive elements reachable and operable via keyboard alone |
|
|
46
|
-
| **Screen reader support** | Semantic HTML, ARIA labels, live regions for dynamic content |
|
|
47
|
-
| **Color contrast** | Text meets 4.5:1 ratio (normal text) or 3:1 (large text) against background |
|
|
48
|
-
| **Focus indicators** | Visible focus ring on all interactive elements |
|
|
49
|
-
| **Alternative text** | All images, icons, and media have descriptive alt text or are marked decorative |
|
|
50
|
-
| **Form labels** | All form inputs have associated labels; error messages are programmatically linked |
|
|
51
|
-
| **Motion sensitivity** | Animations respect `prefers-reduced-motion`; no content-critical motion |
|
|
52
|
-
| **Text resizing** | UI remains usable at 200% zoom |
|
|
53
|
-
|
|
54
|
-
### 4. Performance
|
|
55
|
-
|
|
56
|
-
| Criterion | Description |
|
|
57
|
-
| ------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
58
|
-
| **Largest Contentful Paint** | Web: < 2.5s; Mobile: < 3.5s |
|
|
59
|
-
| **First Input Delay / Interaction to Next Paint** | Web: < 100ms; Mobile: < 200ms |
|
|
60
|
-
| **Cumulative Layout Shift** | < 0.1 (no unexpected visual shifts during load) |
|
|
61
|
-
| **API response time** | p95 < 500ms for user-facing endpoints; p95 < 2s for batch/report endpoints |
|
|
62
|
-
| **Bundle size** | Web: initial JS bundle < 200KB gzipped; lazy-load non-critical modules |
|
|
63
|
-
| **Offline / degraded** | Define behavior when network is slow or unavailable (if applicable) |
|
|
64
|
-
| **Concurrent users** | Target number documented; load testing plan defined for > 100 concurrent |
|
|
65
|
-
|
|
66
|
-
### 5. Security (Beyond OWASP Baseline)
|
|
67
|
-
|
|
68
|
-
| Criterion | Description |
|
|
69
|
-
| -------------------------- | ------------------------------------------------------------------------------- |
|
|
70
|
-
| **Data classification** | Each data field classified: Public / Internal / Confidential / Restricted |
|
|
71
|
-
| **Auth flows specified** | Authentication and authorization model defined — no "we'll add auth later" |
|
|
72
|
-
| **Input validation depth** | Server-side validation for all user inputs; client-side validation for UX only |
|
|
73
|
-
| **Audit trail** | State-changing actions produce audit log entries (who, what, when) |
|
|
74
|
-
| **Rate limiting** | API endpoints have rate limits to prevent abuse |
|
|
75
|
-
| **Session management** | Session timeout, renewal, and revocation policies defined |
|
|
76
|
-
| **Secret handling** | No hardcoded secrets; all credentials via environment variables or secret store |
|
|
77
|
-
| **Dependency scanning** | Third-party packages audited for known vulnerabilities |
|
|
78
|
-
|
|
79
|
-
### 6. Responsive Design
|
|
80
|
-
|
|
81
|
-
| Criterion | Description |
|
|
82
|
-
| ------------------------- | --------------------------------------------------------------------- |
|
|
83
|
-
| **Breakpoints defined** | Mobile (< 768px), Tablet (768–1024px), Desktop (> 1024px) |
|
|
84
|
-
| **Touch targets** | Interactive elements ≥ 44×44px on mobile |
|
|
85
|
-
| **Layout adaptation** | Content reflows appropriately — no horizontal scrolling on mobile |
|
|
86
|
-
| **Navigation adaptation** | Desktop nav collapses to mobile pattern (hamburger, bottom nav, etc.) |
|
|
87
|
-
|
|
88
|
-
### 7. Competitive Differentiation
|
|
89
|
-
|
|
90
|
-
| Criterion | Description |
|
|
91
|
-
| ------------------------- | -------------------------------------------------------------------------- |
|
|
92
|
-
| **Alternative analysis** | Top 3 alternatives identified; what they do well and where they fall short |
|
|
93
|
-
| **Unique value** | At least one feature or quality that sets this app apart from alternatives |
|
|
94
|
-
| **Table-stakes coverage** | Features that users expect as standard for this category are all present |
|
|
95
|
-
| **Experience premium** | At least one UX element that makes users think "this is well-made" |
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## Quality Profiles
|
|
100
|
-
|
|
101
|
-
Not every product needs Gold in every dimension. Quality profiles set the **target** per dimension based on the product type. The target determines what counts as Must-Add (current → target gap), Should-Add (one tier above target), and Could-Add (aspirational). Gold remains the ceiling shown in the scorecard for all profiles — profiles control what you're _aiming_ for.
|
|
102
|
-
|
|
103
|
-
### Profile Definitions
|
|
104
|
-
|
|
105
|
-
| Profile | When to Use |
|
|
106
|
-
| ------------------- | --------------------------------------------------------------------- |
|
|
107
|
-
| **Internal Tool** | Dashboards, CLIs, admin panels, single-user tools, dev utilities |
|
|
108
|
-
| **Public MVP** | First public launch, market validation, early adopters, beta products |
|
|
109
|
-
| **Production SaaS** | Revenue-generating, public-facing, scaled, established products |
|
|
110
|
-
| **Custom** | User picks target tier per dimension manually |
|
|
111
|
-
|
|
112
|
-
### Target Matrices
|
|
113
|
-
|
|
114
|
-
#### Internal Tool
|
|
115
|
-
|
|
116
|
-
| Dimension | Target | Rationale |
|
|
117
|
-
| ------------- | ------ | ------------------------------------------------------------------ |
|
|
118
|
-
| Requirements | Silver | Clear specs prevent rework even for internal tools |
|
|
119
|
-
| UX | Silver | Operator efficiency matters, but polish is secondary |
|
|
120
|
-
| Accessibility | Bronze | Single known user; invest only if the user has accessibility needs |
|
|
121
|
-
| Performance | Silver | Performance issues waste the operator's time |
|
|
122
|
-
| Security | Gold | Internal tools often handle secrets, tokens, and admin access |
|
|
123
|
-
| Responsive | Bronze | Desktop-only is usually correct for internal tools |
|
|
124
|
-
| Competitive | Bronze | No market competition — it's built for you |
|
|
125
|
-
|
|
126
|
-
#### Public MVP
|
|
127
|
-
|
|
128
|
-
| Dimension | Target | Rationale |
|
|
129
|
-
| ------------- | ------ | -------------------------------------------------------------------- |
|
|
130
|
-
| Requirements | Silver | Must be clear enough for a small team to ship confidently |
|
|
131
|
-
| UX | Gold | First impressions determine adoption; UX is the product at MVP stage |
|
|
132
|
-
| Accessibility | Silver | Legal compliance + wider user reach from day one |
|
|
133
|
-
| Performance | Silver | Must feel fast; fine-tune later with real usage data |
|
|
134
|
-
| Security | Gold | No second chances on security with real user data |
|
|
135
|
-
| Responsive | Silver | Users expect mobile access; at least don't break |
|
|
136
|
-
| Competitive | Silver | Must articulate why users should choose this over alternatives |
|
|
137
|
-
|
|
138
|
-
#### Production SaaS
|
|
139
|
-
|
|
140
|
-
| Dimension | Target | Rationale |
|
|
141
|
-
| ------------- | ------ | -------------------------------------------------------- |
|
|
142
|
-
| Requirements | Gold | Revenue depends on reliability; every edge case matters |
|
|
143
|
-
| UX | Gold | Users paying money expect best-in-class experience |
|
|
144
|
-
| Accessibility | Gold | Legal requirement (ADA/EAA); brand reputation; wider TAM |
|
|
145
|
-
| Performance | Gold | Performance is a feature; slowness causes churn |
|
|
146
|
-
| Security | Gold | Breach = business-ending event at scale |
|
|
147
|
-
| Responsive | Gold | Multi-device is table-stakes for SaaS |
|
|
148
|
-
| Competitive | Gold | Must defend market position with clear differentiation |
|
|
149
|
-
|
|
150
|
-
### Default Profile
|
|
151
|
-
|
|
152
|
-
If the user does not specify a profile, **Public MVP** is the default. Rationale: it provides the strongest quality-to-scope ratio — Gold where it matters most (UX, Security) without over-engineering internal or infrastructure dimensions.
|
|
153
|
-
|
|
154
|
-
### How Profiles Drive Enhancement Tiers
|
|
155
|
-
|
|
156
|
-
| Enhancement Tier | Rule |
|
|
157
|
-
| ---------------- | -------------------------------------------------------------------------- |
|
|
158
|
-
| **Must-Add** | Current score is below the profile's target for that dimension |
|
|
159
|
-
| **Should-Add** | Current score matches the target; enhancement would lift to one tier above |
|
|
160
|
-
| **Could-Add** | Current score already meets or exceeds target; enhancement is aspirational |
|
|
161
|
-
| **Won't-Add** | Explicitly excluded regardless of profile |
|
|
162
|
-
|
|
163
|
-
**Override:** Security and Accessibility gaps are always at least Should-Add regardless of profile. A Bronze Security score is always Must-Add.
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## PRD Quality Scorecard
|
|
168
|
-
|
|
169
|
-
Score each dimension on a three-tier rubric:
|
|
170
|
-
|
|
171
|
-
| Level | Name | Meaning |
|
|
172
|
-
| ---------- | ----------- | ----------------------------------------------------------------------------------------- |
|
|
173
|
-
| **Bronze** | Functional | Meets minimum requirements — works but lacks polish, accessibility, and proactive quality |
|
|
174
|
-
| **Silver** | Polished | Good coverage across all dimensions — professional, accessible, performant |
|
|
175
|
-
| **Gold** | Exceptional | Best-in-class for this app category — delightful UX, proactive security, competitive edge |
|
|
176
|
-
|
|
177
|
-
### Scoring Criteria Per Dimension
|
|
178
|
-
|
|
179
|
-
| Dimension | Bronze | Silver | Gold |
|
|
180
|
-
| ----------------- | --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
181
|
-
| **Requirements** | Has acceptance criteria | Priority classified, scope bounded, deps listed | Open questions documented, traceability matrix ready |
|
|
182
|
-
| **UX** | Happy path defined | Error + empty states covered, loading feedback | Full journey with micro-interactions, onboarding, consistency review |
|
|
183
|
-
| **Accessibility** | Basic semantic HTML | WCAG 2.1 AA compliance stated | Keyboard nav, screen reader, color contrast, motion sensitivity all specified |
|
|
184
|
-
| **Performance** | No targets stated | Core Web Vitals targets defined | Load budgets, lazy loading strategy, offline behavior specified |
|
|
185
|
-
| **Security** | OWASP baseline | Data classification + auth flows specified | Audit trail, rate limiting, session management, dependency scanning all defined |
|
|
186
|
-
| **Responsive** | "Mobile friendly" mentioned | Breakpoints and layout adaptation defined | Touch targets, nav adaptation, and responsive images specified |
|
|
187
|
-
| **Competitive** | No analysis | Top 3 alternatives listed | Unique value articulated, table-stakes confirmed, experience premium identified |
|
|
188
|
-
|
|
189
|
-
### Overall Score
|
|
190
|
-
|
|
191
|
-
- **Bronze overall**: Any dimension scores Bronze
|
|
192
|
-
- **Silver overall**: All dimensions score Silver or above
|
|
193
|
-
- **Gold overall**: All dimensions score Gold
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## How This Is Used
|
|
198
|
-
|
|
199
|
-
1. **`spell-enchant`** asks the user to select a quality profile, scores the incoming PRD against this scorecard, and produces enhancement suggestions to reach the profile's targets per dimension.
|
|
200
|
-
2. **`spell-scope`** performs a quick scorecard check during PRD intake and recommends `spell-enchant` if any dimension scores below the profile's target.
|
|
201
|
-
3. **`spell-plan`** outputs a PRD that starts at Bronze or Silver — `spell-enchant` is the path to the profile's targets.
|
|
202
|
-
4. **`spell-review`** can reference these standards when evaluating whether shipped code meets the quality bar.
|
|
203
|
-
5. **Quality Profiles** control what "good enough" means — Internal Tool, Public MVP (default), Production SaaS, or Custom.
|
|
204
|
-
|
|
205
|
-
## Related
|
|
206
|
-
|
|
207
|
-
- [[DECISIONS#ADR-052|ADR-052 — Product Excellence Standards and spell-enchant]]
|
|
208
|
-
- [[governance/testing-standards|Testing Standards]] — Coverage thresholds and framework selection
|
|
209
|
-
- [[governance/cicd-standards|CI/CD Standards]] — Pipeline quality gates
|
|
210
|
-
- [[security/threat-model|Threat Model]] — Active security concerns
|
|
211
|
-
- [[governance/development-methodology|Development Methodology]] — Spell Loop flow
|
|
1
|
+
---
|
|
2
|
+
title: Product Excellence Standards
|
|
3
|
+
audience: both
|
|
4
|
+
last_updated: YYYY-MM-DD
|
|
5
|
+
status: active
|
|
6
|
+
tags:
|
|
7
|
+
[quality, ux, accessibility, performance, security, spell-enchant, ADR-052]
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Product Excellence Standards
|
|
11
|
+
|
|
12
|
+
## Purpose
|
|
13
|
+
|
|
14
|
+
Define what "the best version of an app" means across every dimension — UX, accessibility, performance, security, and polish. This document provides the **PRD Quality Scorecard** that [[.github/prompts/spell-enchant.prompt|spell-enchant]] evaluates against when enchanting a PRD from functional to exceptional.
|
|
15
|
+
|
|
16
|
+
## Quality Dimensions
|
|
17
|
+
|
|
18
|
+
### 1. Requirements Completeness
|
|
19
|
+
|
|
20
|
+
| Criterion | Description |
|
|
21
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
22
|
+
| **Testable acceptance criteria** | Every requirement has ≥1 acceptance criterion that can be verified by an automated test or a concrete manual check |
|
|
23
|
+
| **Priority classification** | All requirements classified as Must Have / Should Have / Won't Have |
|
|
24
|
+
| **Scope boundary** | "Won't Have" section explicitly excludes items to prevent scope creep |
|
|
25
|
+
| **Dependency identification** | External services, APIs, and decisions the feature depends on are listed |
|
|
26
|
+
| **Open questions documented** | Unresolved items are captured — not ignored or assumed |
|
|
27
|
+
|
|
28
|
+
### 2. User Experience (UX)
|
|
29
|
+
|
|
30
|
+
| Criterion | Description |
|
|
31
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| **Full user journey** | Every user-facing feature defines: happy path, error states, edge cases, empty states |
|
|
33
|
+
| **Loading states** | Users see meaningful feedback during async operations (skeleton screens, spinners, progress bars) |
|
|
34
|
+
| **Error recovery** | Errors include actionable messages — users know what went wrong and what to do next |
|
|
35
|
+
| **Empty states** | First-use and zero-data states guide users toward the next action rather than showing blank screens |
|
|
36
|
+
| **Success feedback** | Completions are acknowledged (toast, animation, redirect) — users know their action worked |
|
|
37
|
+
| **Onboarding flow** | New users have a clear path from zero to first value delivered |
|
|
38
|
+
| **Consistency** | UI patterns, terminology, and behavior are consistent across features |
|
|
39
|
+
| **Micro-interactions** | Transitions, hover effects, and subtle animations provide polish without slowing users down |
|
|
40
|
+
|
|
41
|
+
### 3. Accessibility (WCAG 2.1 AA Baseline)
|
|
42
|
+
|
|
43
|
+
| Criterion | Description |
|
|
44
|
+
| ------------------------- | ---------------------------------------------------------------------------------- |
|
|
45
|
+
| **Keyboard navigation** | All interactive elements reachable and operable via keyboard alone |
|
|
46
|
+
| **Screen reader support** | Semantic HTML, ARIA labels, live regions for dynamic content |
|
|
47
|
+
| **Color contrast** | Text meets 4.5:1 ratio (normal text) or 3:1 (large text) against background |
|
|
48
|
+
| **Focus indicators** | Visible focus ring on all interactive elements |
|
|
49
|
+
| **Alternative text** | All images, icons, and media have descriptive alt text or are marked decorative |
|
|
50
|
+
| **Form labels** | All form inputs have associated labels; error messages are programmatically linked |
|
|
51
|
+
| **Motion sensitivity** | Animations respect `prefers-reduced-motion`; no content-critical motion |
|
|
52
|
+
| **Text resizing** | UI remains usable at 200% zoom |
|
|
53
|
+
|
|
54
|
+
### 4. Performance
|
|
55
|
+
|
|
56
|
+
| Criterion | Description |
|
|
57
|
+
| ------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
58
|
+
| **Largest Contentful Paint** | Web: < 2.5s; Mobile: < 3.5s |
|
|
59
|
+
| **First Input Delay / Interaction to Next Paint** | Web: < 100ms; Mobile: < 200ms |
|
|
60
|
+
| **Cumulative Layout Shift** | < 0.1 (no unexpected visual shifts during load) |
|
|
61
|
+
| **API response time** | p95 < 500ms for user-facing endpoints; p95 < 2s for batch/report endpoints |
|
|
62
|
+
| **Bundle size** | Web: initial JS bundle < 200KB gzipped; lazy-load non-critical modules |
|
|
63
|
+
| **Offline / degraded** | Define behavior when network is slow or unavailable (if applicable) |
|
|
64
|
+
| **Concurrent users** | Target number documented; load testing plan defined for > 100 concurrent |
|
|
65
|
+
|
|
66
|
+
### 5. Security (Beyond OWASP Baseline)
|
|
67
|
+
|
|
68
|
+
| Criterion | Description |
|
|
69
|
+
| -------------------------- | ------------------------------------------------------------------------------- |
|
|
70
|
+
| **Data classification** | Each data field classified: Public / Internal / Confidential / Restricted |
|
|
71
|
+
| **Auth flows specified** | Authentication and authorization model defined — no "we'll add auth later" |
|
|
72
|
+
| **Input validation depth** | Server-side validation for all user inputs; client-side validation for UX only |
|
|
73
|
+
| **Audit trail** | State-changing actions produce audit log entries (who, what, when) |
|
|
74
|
+
| **Rate limiting** | API endpoints have rate limits to prevent abuse |
|
|
75
|
+
| **Session management** | Session timeout, renewal, and revocation policies defined |
|
|
76
|
+
| **Secret handling** | No hardcoded secrets; all credentials via environment variables or secret store |
|
|
77
|
+
| **Dependency scanning** | Third-party packages audited for known vulnerabilities |
|
|
78
|
+
|
|
79
|
+
### 6. Responsive Design
|
|
80
|
+
|
|
81
|
+
| Criterion | Description |
|
|
82
|
+
| ------------------------- | --------------------------------------------------------------------- |
|
|
83
|
+
| **Breakpoints defined** | Mobile (< 768px), Tablet (768–1024px), Desktop (> 1024px) |
|
|
84
|
+
| **Touch targets** | Interactive elements ≥ 44×44px on mobile |
|
|
85
|
+
| **Layout adaptation** | Content reflows appropriately — no horizontal scrolling on mobile |
|
|
86
|
+
| **Navigation adaptation** | Desktop nav collapses to mobile pattern (hamburger, bottom nav, etc.) |
|
|
87
|
+
|
|
88
|
+
### 7. Competitive Differentiation
|
|
89
|
+
|
|
90
|
+
| Criterion | Description |
|
|
91
|
+
| ------------------------- | -------------------------------------------------------------------------- |
|
|
92
|
+
| **Alternative analysis** | Top 3 alternatives identified; what they do well and where they fall short |
|
|
93
|
+
| **Unique value** | At least one feature or quality that sets this app apart from alternatives |
|
|
94
|
+
| **Table-stakes coverage** | Features that users expect as standard for this category are all present |
|
|
95
|
+
| **Experience premium** | At least one UX element that makes users think "this is well-made" |
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Quality Profiles
|
|
100
|
+
|
|
101
|
+
Not every product needs Gold in every dimension. Quality profiles set the **target** per dimension based on the product type. The target determines what counts as Must-Add (current → target gap), Should-Add (one tier above target), and Could-Add (aspirational). Gold remains the ceiling shown in the scorecard for all profiles — profiles control what you're _aiming_ for.
|
|
102
|
+
|
|
103
|
+
### Profile Definitions
|
|
104
|
+
|
|
105
|
+
| Profile | When to Use |
|
|
106
|
+
| ------------------- | --------------------------------------------------------------------- |
|
|
107
|
+
| **Internal Tool** | Dashboards, CLIs, admin panels, single-user tools, dev utilities |
|
|
108
|
+
| **Public MVP** | First public launch, market validation, early adopters, beta products |
|
|
109
|
+
| **Production SaaS** | Revenue-generating, public-facing, scaled, established products |
|
|
110
|
+
| **Custom** | User picks target tier per dimension manually |
|
|
111
|
+
|
|
112
|
+
### Target Matrices
|
|
113
|
+
|
|
114
|
+
#### Internal Tool
|
|
115
|
+
|
|
116
|
+
| Dimension | Target | Rationale |
|
|
117
|
+
| ------------- | ------ | ------------------------------------------------------------------ |
|
|
118
|
+
| Requirements | Silver | Clear specs prevent rework even for internal tools |
|
|
119
|
+
| UX | Silver | Operator efficiency matters, but polish is secondary |
|
|
120
|
+
| Accessibility | Bronze | Single known user; invest only if the user has accessibility needs |
|
|
121
|
+
| Performance | Silver | Performance issues waste the operator's time |
|
|
122
|
+
| Security | Gold | Internal tools often handle secrets, tokens, and admin access |
|
|
123
|
+
| Responsive | Bronze | Desktop-only is usually correct for internal tools |
|
|
124
|
+
| Competitive | Bronze | No market competition — it's built for you |
|
|
125
|
+
|
|
126
|
+
#### Public MVP
|
|
127
|
+
|
|
128
|
+
| Dimension | Target | Rationale |
|
|
129
|
+
| ------------- | ------ | -------------------------------------------------------------------- |
|
|
130
|
+
| Requirements | Silver | Must be clear enough for a small team to ship confidently |
|
|
131
|
+
| UX | Gold | First impressions determine adoption; UX is the product at MVP stage |
|
|
132
|
+
| Accessibility | Silver | Legal compliance + wider user reach from day one |
|
|
133
|
+
| Performance | Silver | Must feel fast; fine-tune later with real usage data |
|
|
134
|
+
| Security | Gold | No second chances on security with real user data |
|
|
135
|
+
| Responsive | Silver | Users expect mobile access; at least don't break |
|
|
136
|
+
| Competitive | Silver | Must articulate why users should choose this over alternatives |
|
|
137
|
+
|
|
138
|
+
#### Production SaaS
|
|
139
|
+
|
|
140
|
+
| Dimension | Target | Rationale |
|
|
141
|
+
| ------------- | ------ | -------------------------------------------------------- |
|
|
142
|
+
| Requirements | Gold | Revenue depends on reliability; every edge case matters |
|
|
143
|
+
| UX | Gold | Users paying money expect best-in-class experience |
|
|
144
|
+
| Accessibility | Gold | Legal requirement (ADA/EAA); brand reputation; wider TAM |
|
|
145
|
+
| Performance | Gold | Performance is a feature; slowness causes churn |
|
|
146
|
+
| Security | Gold | Breach = business-ending event at scale |
|
|
147
|
+
| Responsive | Gold | Multi-device is table-stakes for SaaS |
|
|
148
|
+
| Competitive | Gold | Must defend market position with clear differentiation |
|
|
149
|
+
|
|
150
|
+
### Default Profile
|
|
151
|
+
|
|
152
|
+
If the user does not specify a profile, **Public MVP** is the default. Rationale: it provides the strongest quality-to-scope ratio — Gold where it matters most (UX, Security) without over-engineering internal or infrastructure dimensions.
|
|
153
|
+
|
|
154
|
+
### How Profiles Drive Enhancement Tiers
|
|
155
|
+
|
|
156
|
+
| Enhancement Tier | Rule |
|
|
157
|
+
| ---------------- | -------------------------------------------------------------------------- |
|
|
158
|
+
| **Must-Add** | Current score is below the profile's target for that dimension |
|
|
159
|
+
| **Should-Add** | Current score matches the target; enhancement would lift to one tier above |
|
|
160
|
+
| **Could-Add** | Current score already meets or exceeds target; enhancement is aspirational |
|
|
161
|
+
| **Won't-Add** | Explicitly excluded regardless of profile |
|
|
162
|
+
|
|
163
|
+
**Override:** Security and Accessibility gaps are always at least Should-Add regardless of profile. A Bronze Security score is always Must-Add.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## PRD Quality Scorecard
|
|
168
|
+
|
|
169
|
+
Score each dimension on a three-tier rubric:
|
|
170
|
+
|
|
171
|
+
| Level | Name | Meaning |
|
|
172
|
+
| ---------- | ----------- | ----------------------------------------------------------------------------------------- |
|
|
173
|
+
| **Bronze** | Functional | Meets minimum requirements — works but lacks polish, accessibility, and proactive quality |
|
|
174
|
+
| **Silver** | Polished | Good coverage across all dimensions — professional, accessible, performant |
|
|
175
|
+
| **Gold** | Exceptional | Best-in-class for this app category — delightful UX, proactive security, competitive edge |
|
|
176
|
+
|
|
177
|
+
### Scoring Criteria Per Dimension
|
|
178
|
+
|
|
179
|
+
| Dimension | Bronze | Silver | Gold |
|
|
180
|
+
| ----------------- | --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
181
|
+
| **Requirements** | Has acceptance criteria | Priority classified, scope bounded, deps listed | Open questions documented, traceability matrix ready |
|
|
182
|
+
| **UX** | Happy path defined | Error + empty states covered, loading feedback | Full journey with micro-interactions, onboarding, consistency review |
|
|
183
|
+
| **Accessibility** | Basic semantic HTML | WCAG 2.1 AA compliance stated | Keyboard nav, screen reader, color contrast, motion sensitivity all specified |
|
|
184
|
+
| **Performance** | No targets stated | Core Web Vitals targets defined | Load budgets, lazy loading strategy, offline behavior specified |
|
|
185
|
+
| **Security** | OWASP baseline | Data classification + auth flows specified | Audit trail, rate limiting, session management, dependency scanning all defined |
|
|
186
|
+
| **Responsive** | "Mobile friendly" mentioned | Breakpoints and layout adaptation defined | Touch targets, nav adaptation, and responsive images specified |
|
|
187
|
+
| **Competitive** | No analysis | Top 3 alternatives listed | Unique value articulated, table-stakes confirmed, experience premium identified |
|
|
188
|
+
|
|
189
|
+
### Overall Score
|
|
190
|
+
|
|
191
|
+
- **Bronze overall**: Any dimension scores Bronze
|
|
192
|
+
- **Silver overall**: All dimensions score Silver or above
|
|
193
|
+
- **Gold overall**: All dimensions score Gold
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## How This Is Used
|
|
198
|
+
|
|
199
|
+
1. **`spell-enchant`** asks the user to select a quality profile, scores the incoming PRD against this scorecard, and produces enhancement suggestions to reach the profile's targets per dimension.
|
|
200
|
+
2. **`spell-scope`** performs a quick scorecard check during PRD intake and recommends `spell-enchant` if any dimension scores below the profile's target.
|
|
201
|
+
3. **`spell-plan`** outputs a PRD that starts at Bronze or Silver — `spell-enchant` is the path to the profile's targets.
|
|
202
|
+
4. **`spell-review`** can reference these standards when evaluating whether shipped code meets the quality bar.
|
|
203
|
+
5. **Quality Profiles** control what "good enough" means — Internal Tool, Public MVP (default), Production SaaS, or Custom.
|
|
204
|
+
|
|
205
|
+
## Related
|
|
206
|
+
|
|
207
|
+
- [[DECISIONS#ADR-052|ADR-052 — Product Excellence Standards and spell-enchant]]
|
|
208
|
+
- [[governance/testing-standards|Testing Standards]] — Coverage thresholds and framework selection
|
|
209
|
+
- [[governance/cicd-standards|CI/CD Standards]] — Pipeline quality gates
|
|
210
|
+
- [[security/threat-model|Threat Model]] — Active security concerns
|
|
211
|
+
- [[governance/development-methodology|Development Methodology]] — Spell Loop flow
|