TRUST 5 Quality Principles and Enforcement
This skill provides background knowledge on MoAI's quality model: the five
TRUST 5 principles, how agents enforce them, the 3-level harness, and the
language-aware toolchains that /moai gate runs. MoAI does NOT ship a
quality-validation library — quality is enforced through agents
(manager-develop, sync-auditor), slash commands (/moai gate,
/moai review), and the harness (minimal/standard/thorough).
Quick Reference
TRUST 5 Principles (Tested, Readable, Unified, Secured, Trackable) are
quality dimensions, not code objects. Every code change is evaluated against
all five.
Quality Mechanisms (the real enforcement layer):
/moai gate — runs lint + format + type-check + test in parallel as a
pre-commit quality gate (<30s). Auto-detects the project language and runs
the appropriate toolchain.
manager-develop (run-phase) — implements via cycle_type ∈ {tdd, ddd,
autofix}; the chosen cycle shapes how tests and behavior are produced.
sync-auditor — independent skeptical quality assessment with 4-dimension
scoring (Functionality, Security, Craft, Consistency), scored as the
harmonic mean of dimensions, not the average.
- 3-level harness — minimal (fast validation), standard (default checks),
thorough (full sync-auditor + TRUST 5). Auto-determined by the Complexity
Estimator based on SPEC scope.
- LSP quality gates — phase-specific thresholds (run: zero errors/type-errors/
lint-errors; sync: zero errors, max 10 warnings, clean LSP).
The MoAI Quality Model
MoAI does not provide a Python SDK or any library for quality validation.
Quality is enforced through the workflow, the agents, and the gate commands.
This skill documents how those pieces fit together so a Claude invocation
can reason about quality correctly.
How TRUST 5 is enforced per phase
| Phase |
Quality check |
Owner |
| plan |
Capture LSP baseline; identify quality risks in the plan |
manager-spec |
| run |
Zero errors/type-errors/lint-errors; tests pass; coverage met |
manager-develop (cycle_type shapes the approach) |
| sync |
Lint clean (≤10 warnings); docs updated; TRUST 5 re-affirmed |
manager-docs, then sync-auditor scores |
| audit |
Independent 4-dimension scoring (Functionality/Security/Craft/Consistency) |
sync-auditor |
cycle_type and quality (manager-develop)
The run-phase cycle_type selects how quality is built in:
- tdd — Test-Driven Development (RED-GREEN-REFACTOR). Behavior is
specified by a failing test first, then implemented. Best for new features.
- ddd — Domain-Driven refactoring (ANALYZE-PRESERVE-IMPROVE).
Behavior-preserving transformation of existing code. Best for refactoring
and debt reduction.
- autofix — diagnostic-driven fixing (LSP / lint / type errors). Best for
/moai fix and regression recovery.
See Skill("moai-workflow-tdd"), Skill("moai-workflow-ddd"), and
Skill("moai-workflow-loop") for the per-cycle mechanics.
TRUST 5 Principles
TRUST 5 is a mnemonic for five quality dimensions. Treat each as a question
to ask of any change, not a score to compute.
- T — Tested: Does the change have tests? Are they green? Is coverage at
or above the project threshold (85%+ by default)? For existing untested
code, are characterization tests capturing current behavior?
- R — Readable: Is naming clear? Are comments in English (or the
configured code-comments language)? Could a new contributor follow the
logic without a walkthrough?
- U — Unified: Does the change match the file's existing conventions
(naming, error handling, imports)? Is it formatted with the project's
formatter? Consistency within a file beats personal preference.
- S — Secured: Are all external inputs validated? Does it follow OWASP
guidance for web security? Are credentials kept out of version control
(environment variables instead)? See moai-ref-owasp-checklist.
- T — Trackable: Does the commit follow Conventional Commits? Does it
reference the SPEC / issue it implements? Can the change be traced back to
a requirement?
For the per-principle assessment checklist and the "not applicable" guard,
see TRUST 5 Principles.
Quality Gates and the 3-Level Harness
The harness level controls how deep quality validation goes. It is
auto-determined by the Complexity Estimator based on SPEC scope.
| Level |
What runs |
When |
| minimal |
Fast validation only (lint + type + test) |
Small SPECs, low risk |
| standard |
Default checks (lint + type + test + format) |
Most SPECs |
| thorough |
Full sync-auditor + 4-dimension TRUST 5 scoring |
Large SPECs, high risk |
/moai gate is the lightweight pre-commit entry point: it runs lint +
format + type-check + test in parallel and applies no fixes. It is the
fastest way to get a quality signal. For deeper review use /moai review.
Language-Aware Toolchains
The quality gate auto-detects the project language and runs the appropriate
toolchain. Tools that are not installed are skipped gracefully; projects
with no recognized language marker pass the gate silently. This skill is
language-neutral — the 16 supported languages are treated equally.
| Language |
Lint |
Format |
Test |
| Go |
go vet → golangci-lint |
gofmt |
go test |
| Python |
ruff |
black |
pytest |
| TypeScript / JavaScript |
eslint |
prettier |
jest / mocha |
| Rust |
cargo clippy |
rustfmt |
cargo test |
| Java / Kotlin |
(per project linter) |
(per project) |
junit |
| Ruby |
rubocop |
rubocop |
rspec |
| PHP |
phpstan / phpcs |
php-cs-fixer |
pest / phpunit |
| ... |
(16 languages supported; auto-detected) |
|
|
For the full toolchain mapping and how /moai gate detects the language,
see Language-Aware Toolchains.
Module Reference
Each module is loaded on demand. Load the one relevant to the current task.
- TRUST 5 Principles — the five dimensions as
assessment questions, per-principle checklists, and the "not applicable"
guard.
- Proactive Analysis — how
/moai gate,
/moai review, and /moai loop surface quality issues proactively, and
how to triage findings.
- Best Practices — using WebSearch / WebFetch for
up-to-date framework/library best practices, and validating against them.
- Integration Patterns — how quality fits
into the SPEC workflow phases (plan/run/sync) and the harness levels.
Reference Files
- examples.md — worked TRUST 5 assessment examples
and gate/review triage walkthroughs. Load when applying TRUST 5 to a
concrete change.
- reference.md — the quality-mechanism reference:
harness level detail, language toolchain table, agent roles, and the
sync-auditor scoring model. Load when you need the authoritative mapping.
Works Well With
Agents (see CLAUDE.md §4 for the 11-agent catalog):
manager-develop — run-phase implementation; owns the Tested and Unified
principles through cycle_type.
sync-auditor — independent 4-dimension quality scoring (Functionality /
Security / Craft / Consistency).
Explore (Anthropic built-in) — read-only codebase exploration before
assessing quality.
Skills:
moai-foundation-core — TRUST 5 framework cross-reference and SPEC
workflow foundations.
moai-ref-testing-pyramid — test-pyramid strategy, coverage targets, and
test patterns.
moai-ref-owasp-checklist — OWASP Top 10 security checklist for the
Secured principle.
moai-workflow-tdd / moai-workflow-ddd / moai-workflow-loop — the
cycle_type workflows that manager-develop uses.
Commands:
/moai gate — pre-commit quality gate (lint + format + type + test).
/moai review — code review with security and MX-tag compliance.
/moai fix — auto-detect and fix LSP/lint/type errors.
/moai loop — iterative fix loop until resolved or max iterations.
Common Rationalizations
| Rationalization |
Reality |
| "The linter warnings are false positives" |
False positives should be suppressed with inline comments. Ignoring them trains the team to ignore real issues. |
| "Security scanning can wait until before release" |
Security vulnerabilities compound. Late discovery means expensive rework. Scan continuously. |
| "Coverage is high enough, the remaining 15% is edge cases" |
Edge cases are where production bugs live. The uncovered code is the riskiest code. |
| "Code review is subjective, automation is sufficient" |
Automation catches syntax and patterns. Reviews catch design flaws, naming confusion, and missing abstractions. |
| "TRUST 5 is too bureaucratic for a hotfix" |
Hotfixes without quality gates introduce the next hotfix. TRUST 5 on a hotfix is the minimum, not the maximum. |
Chesterton's Fence: Before removing a quality check, understand why it was added. Removing a gate without understanding its history repeats the failure it was designed to prevent.
Shift Left: The earlier a defect is found, the cheaper it is to fix. Quality checks belong in the development loop, not at the end of it.
Red Flags
- Linter or type-checker warnings suppressed globally instead of per-line
- OWASP checklist not consulted when handling user input or authentication
- Coverage report not generated for a commit that adds new functionality
- TRUST 5 dimension skipped with "not applicable" without justification
- Quality report generated but no action taken on identified issues
Verification
1---
2name: moai-foundation-quality
3description: >
4 TRUST 5 quality principles and how MoAI enforces them through agents,
5 the 3-level harness, /moai gate, and sync-auditor scoring. Use for code
6 review, quality gate checks, coverage targets, or TRUST 5 compliance.
7
8when_to_use: >
9 Use for code-quality guidance: TRUST 5 principles (Tested, Readable,
10 Unified, Secured, Trackable), the 3-level harness (minimal/standard/
11 thorough), /moai gate (lint+format+type+test), coverage targets,
12 security checks, language-aware toolchains, code-smell detection, and
13 technical-debt triage.
14
15license: Apache-2.0
16compatibility: Designed for Claude Code
17allowed-tools: Read, Grep, Glob
18user-invocable: false
19metadata:
20 source: https://skillmd.com/skills/modu-ai/moai-foundation-quality
21 version: "3.0.0"
22 category: "foundation"
23 status: "active"
24 updated: "2026-07-10"
25 modularized: "true"
26 tags: "foundation, quality, testing, validation, trust-5, best-practices, code-review"
27 aliases: "moai-foundation-quality"
28
29# MoAI Extension: Progressive Disclosure
30progressive_disclosure:
31 enabled: true
32 level1_tokens: 100
33 level2_tokens: 5000
34---
35
36# TRUST 5 Quality Principles and Enforcement
37
38This skill provides background knowledge on MoAI's quality model: the five
39TRUST 5 principles, how agents enforce them, the 3-level harness, and the
40language-aware toolchains that `/moai gate` runs. MoAI does NOT ship a
41quality-validation library — quality is enforced through agents
42(`manager-develop`, `sync-auditor`), slash commands (`/moai gate`,
43`/moai review`), and the harness (minimal/standard/thorough).
44
45## Quick Reference
46
47**TRUST 5 Principles** (Tested, Readable, Unified, Secured, Trackable) are
48quality dimensions, not code objects. Every code change is evaluated against
49all five.
50
51**Quality Mechanisms** (the real enforcement layer):
52
53- `/moai gate` — runs lint + format + type-check + test in parallel as a
54 pre-commit quality gate (<30s). Auto-detects the project language and runs
55 the appropriate toolchain.
56- `manager-develop` (run-phase) — implements via `cycle_type` ∈ {tdd, ddd,
57 autofix}; the chosen cycle shapes how tests and behavior are produced.
58- `sync-auditor` — independent skeptical quality assessment with 4-dimension
59 scoring (Functionality, Security, Craft, Consistency), scored as the
60 harmonic mean of dimensions, not the average.
61- 3-level harness — minimal (fast validation), standard (default checks),
62 thorough (full sync-auditor + TRUST 5). Auto-determined by the Complexity
63 Estimator based on SPEC scope.
64- LSP quality gates — phase-specific thresholds (run: zero errors/type-errors/
65 lint-errors; sync: zero errors, max 10 warnings, clean LSP).
66
67## The MoAI Quality Model
68
69MoAI does not provide a Python SDK or any library for quality validation.
70Quality is enforced through the workflow, the agents, and the gate commands.
71This skill documents how those pieces fit together so a Claude invocation
72can reason about quality correctly.
73
74### How TRUST 5 is enforced per phase
75
76| Phase | Quality check | Owner |
77|-------|--------------|-------|
78| plan | Capture LSP baseline; identify quality risks in the plan | manager-spec |
79| run | Zero errors/type-errors/lint-errors; tests pass; coverage met | manager-develop (cycle_type shapes the approach) |
80| sync | Lint clean (≤10 warnings); docs updated; TRUST 5 re-affirmed | manager-docs, then sync-auditor scores |
81| audit | Independent 4-dimension scoring (Functionality/Security/Craft/Consistency) | sync-auditor |
82
83### cycle_type and quality (manager-develop)
84
85The run-phase `cycle_type` selects how quality is built in:
86
87- **tdd** — Test-Driven Development (RED-GREEN-REFACTOR). Behavior is
88 specified by a failing test first, then implemented. Best for new features.
89- **ddd** — Domain-Driven refactoring (ANALYZE-PRESERVE-IMPROVE).
90 Behavior-preserving transformation of existing code. Best for refactoring
91 and debt reduction.
92- **autofix** — diagnostic-driven fixing (LSP / lint / type errors). Best for
93 `/moai fix` and regression recovery.
94
95See Skill("moai-workflow-tdd"), Skill("moai-workflow-ddd"), and
96Skill("moai-workflow-loop") for the per-cycle mechanics.
97
98## TRUST 5 Principles
99
100TRUST 5 is a mnemonic for five quality dimensions. Treat each as a question
101to ask of any change, not a score to compute.
102
103- **T — Tested**: Does the change have tests? Are they green? Is coverage at
104 or above the project threshold (85%+ by default)? For existing untested
105 code, are characterization tests capturing current behavior?
106- **R — Readable**: Is naming clear? Are comments in English (or the
107 configured code-comments language)? Could a new contributor follow the
108 logic without a walkthrough?
109- **U — Unified**: Does the change match the file's existing conventions
110 (naming, error handling, imports)? Is it formatted with the project's
111 formatter? Consistency within a file beats personal preference.
112- **S — Secured**: Are all external inputs validated? Does it follow OWASP
113 guidance for web security? Are credentials kept out of version control
114 (environment variables instead)? See moai-ref-owasp-checklist.
115- **T — Trackable**: Does the commit follow Conventional Commits? Does it
116 reference the SPEC / issue it implements? Can the change be traced back to
117 a requirement?
118
119For the per-principle assessment checklist and the "not applicable" guard,
120see [TRUST 5 Principles](modules/trust5-validation.md).
121
122## Quality Gates and the 3-Level Harness
123
124The harness level controls how deep quality validation goes. It is
125auto-determined by the Complexity Estimator based on SPEC scope.
126
127| Level | What runs | When |
128|-------|-----------|------|
129| minimal | Fast validation only (lint + type + test) | Small SPECs, low risk |
130| standard | Default checks (lint + type + test + format) | Most SPECs |
131| thorough | Full sync-auditor + 4-dimension TRUST 5 scoring | Large SPECs, high risk |
132
133`/moai gate` is the lightweight pre-commit entry point: it runs lint +
134format + type-check + test in parallel and applies no fixes. It is the
135fastest way to get a quality signal. For deeper review use `/moai review`.
136
137## Language-Aware Toolchains
138
139The quality gate auto-detects the project language and runs the appropriate
140toolchain. Tools that are not installed are skipped gracefully; projects
141with no recognized language marker pass the gate silently. This skill is
142language-neutral — the 16 supported languages are treated equally.
143
144| Language | Lint | Format | Test |
145|----------|------|--------|------|
146| Go | go vet → golangci-lint | gofmt | go test |
147| Python | ruff | black | pytest |
148| TypeScript / JavaScript | eslint | prettier | jest / mocha |
149| Rust | cargo clippy | rustfmt | cargo test |
150| Java / Kotlin | (per project linter) | (per project) | junit |
151| Ruby | rubocop | rubocop | rspec |
152| PHP | phpstan / phpcs | php-cs-fixer | pest / phpunit |
153| ... | (16 languages supported; auto-detected) | | |
154
155For the full toolchain mapping and how `/moai gate` detects the language,
156see [Language-Aware Toolchains](references/reference.md#language-aware-toolkchains).
157
158## Module Reference
159
160Each module is loaded on demand. Load the one relevant to the current task.
161
162- [TRUST 5 Principles](modules/trust5-validation.md) — the five dimensions as
163 assessment questions, per-principle checklists, and the "not applicable"
164 guard.
165- [Proactive Analysis](modules/proactive-analysis.md) — how `/moai gate`,
166 `/moai review`, and `/moai loop` surface quality issues proactively, and
167 how to triage findings.
168- [Best Practices](modules/best-practices.md) — using WebSearch / WebFetch for
169 up-to-date framework/library best practices, and validating against them.
170- [Integration Patterns](modules/integration-patterns.md) — how quality fits
171 into the SPEC workflow phases (plan/run/sync) and the harness levels.
172
173## Reference Files
174
175- [examples.md](references/examples.md) — worked TRUST 5 assessment examples
176 and gate/review triage walkthroughs. Load when applying TRUST 5 to a
177 concrete change.
178- [reference.md](references/reference.md) — the quality-mechanism reference:
179 harness level detail, language toolchain table, agent roles, and the
180 sync-auditor scoring model. Load when you need the authoritative mapping.
181
182## Works Well With
183
184Agents (see CLAUDE.md §4 for the 11-agent catalog):
185
186- `manager-develop` — run-phase implementation; owns the Tested and Unified
187 principles through cycle_type.
188- `sync-auditor` — independent 4-dimension quality scoring (Functionality /
189 Security / Craft / Consistency).
190- `Explore` (Anthropic built-in) — read-only codebase exploration before
191 assessing quality.
192
193Skills:
194
195- `moai-foundation-core` — TRUST 5 framework cross-reference and SPEC
196 workflow foundations.
197- `moai-ref-testing-pyramid` — test-pyramid strategy, coverage targets, and
198 test patterns.
199- `moai-ref-owasp-checklist` — OWASP Top 10 security checklist for the
200 Secured principle.
201- `moai-workflow-tdd` / `moai-workflow-ddd` / `moai-workflow-loop` — the
202 cycle_type workflows that manager-develop uses.
203
204Commands:
205
206- `/moai gate` — pre-commit quality gate (lint + format + type + test).
207- `/moai review` — code review with security and MX-tag compliance.
208- `/moai fix` — auto-detect and fix LSP/lint/type errors.
209- `/moai loop` — iterative fix loop until resolved or max iterations.
210
211<!-- moai:evolvable-start id="rationalizations" -->
212## Common Rationalizations
213
214| Rationalization | Reality |
215|---|---|
216| "The linter warnings are false positives" | False positives should be suppressed with inline comments. Ignoring them trains the team to ignore real issues. |
217| "Security scanning can wait until before release" | Security vulnerabilities compound. Late discovery means expensive rework. Scan continuously. |
218| "Coverage is high enough, the remaining 15% is edge cases" | Edge cases are where production bugs live. The uncovered code is the riskiest code. |
219| "Code review is subjective, automation is sufficient" | Automation catches syntax and patterns. Reviews catch design flaws, naming confusion, and missing abstractions. |
220| "TRUST 5 is too bureaucratic for a hotfix" | Hotfixes without quality gates introduce the next hotfix. TRUST 5 on a hotfix is the minimum, not the maximum. |
221
222**Chesterton's Fence**: Before removing a quality check, understand why it was added. Removing a gate without understanding its history repeats the failure it was designed to prevent.
223
224**Shift Left**: The earlier a defect is found, the cheaper it is to fix. Quality checks belong in the development loop, not at the end of it.
225
226<!-- moai:evolvable-end -->
227
228<!-- moai:evolvable-start id="red-flags" -->
229## Red Flags
230
231- Linter or type-checker warnings suppressed globally instead of per-line
232- OWASP checklist not consulted when handling user input or authentication
233- Coverage report not generated for a commit that adds new functionality
234- TRUST 5 dimension skipped with "not applicable" without justification
235- Quality report generated but no action taken on identified issues
236
237<!-- moai:evolvable-end -->
238
239<!-- moai:evolvable-start id="verification" -->
240## Verification
241
242- [ ] Linter runs clean or remaining warnings have inline suppression comments with reasons (show the command output)
243- [ ] OWASP checklist reviewed for security-relevant changes (show checklist references)
244- [ ] Coverage report generated and threshold met (show tool output)
245- [ ] All five TRUST 5 dimensions assessed (show assessment for each)
246- [ ] Quality findings triaged with a resolution plan for each
247- [ ] No global rule disabling in linter configuration
248
249<!-- moai:evolvable-end -->