Add new agents and skills for enhanced project orchestration and review processes
- Introduced `critic`, an independent adversarial reviewer for security and correctness. - Added `fable-orchestrator` to manage task routing and verification. - Implemented `gauntlet-critic` for fresh-context evaluation of gauntlet rounds. - Created `planner` for generating executable implementation plans with dependencies. - Developed `security-auditor` for application security reviews and audits. - Established `system-steward` to improve agent prompts and skills based on verified failures. - Added `dev-loop` skill for autonomous development loops over repositories. - Implemented `gauntlet-loop` skill for iterative quality benchmarking against reference standards. - Updated project settings to utilize the new orchestrator agent. - Created documentation for `GAUNTLET.md`, `PROGRESS.md`, and `REFERENCE_BAR.md` to track project status and quality benchmarks. - Added detailed prompting style guide to enhance understanding of prompt patterns and agentic loops.
This commit is contained in:
18
.claude/skills/design-review/SKILL.md
Normal file
18
.claude/skills/design-review/SKILL.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
name: design-review
|
||||
description: Heuristic + accessibility review of implemented user-facing UI against its design spec and the design system, AFTER the build. Returns P0–P3 findings with file/line evidence; read-only. Owner: ux-ui-designer; runs concurrently with the verifier. Required at medium+ risk for any user-facing change.
|
||||
allowed-tools: Read Grep Glob
|
||||
---
|
||||
|
||||
Review what was actually built — templates, widgets, copy, states — against the spec (`docs/design/<feature>.md` if present), `docs/DESIGN_SYSTEM.md`, and these lenses. Read-only: findings and smallest fixes, never patches.
|
||||
|
||||
1. **Task efficiency.** Steps/taps to complete the user's job vs the spec's target; unnecessary inputs where a preset, dropdown, or default would do; the primary action visually primary on every screen.
|
||||
2. **State completeness.** Every state the spec names exists in code: empty, loading, error, success, and — for offline-capable surfaces — offline, queued, sync-pending, sync-rejected. Grep for the state handling, don't assume; an unhandled state is at least P1.
|
||||
3. **Consistency.** Components, spacing, and naming match `DESIGN_SYSTEM.md` and neighboring screens; new one-off patterns without a design-system entry are findings.
|
||||
4. **Copy + i18n.** Every user-visible string localized in all supported locales (grep for hardcoded literals in templates/widgets); tone and terminology match the copy rules; errors say what to DO, not just what failed.
|
||||
5. **Accessibility.** Tap targets ≥ 48dp, WCAG AA contrast, focus order, labels on icon-only controls, form errors announced next to their fields.
|
||||
6. **Platform ergonomics.** Mobile: reachability, keyboard types, sunlight-legible contrast, battery-conscious patterns. Web: keyboard navigation, dense-screen scanability, bulk-action affordances.
|
||||
|
||||
Rank findings **P0** (blocks the user's job or data comprehension — e.g. money state invisible), **P1** (missing state, broken i18n/a11y on a core path), **P2** (inconsistency, inefficiency), **P3** (polish). Each finding: evidence (file/line or reproduction), impact, smallest fix. Do not restate the spec, praise the work, or invent P3s to seem thorough — state `none` after meaningful checks if the build holds.
|
||||
|
||||
Return exactly: **Verdict** (accept / accept with follow-ups / return to builder) · **Findings** (P0–P3 or `none`) · **Checks performed** (lenses run, files inspected) · **Design-system delta** (or `none`).
|
||||
44
.claude/skills/design-spec/SKILL.md
Normal file
44
.claude/skills/design-spec/SKILL.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
name: design-spec
|
||||
description: Turn a feature contract into an implementable UX spec BEFORE any user-facing implementation — flows, every screen state, components, complete copy in all supported locales, accessibility, and verifier-checkable acceptance criteria. Owner: ux-ui-designer. Do not use for non-UI work or after the build (that is design-review).
|
||||
allowed-tools: Read Grep Glob Write Edit
|
||||
---
|
||||
|
||||
Produce the binding UX spec the builder implements from. A spec that cannot be verified is an opinion — every requirement here must be checkable.
|
||||
|
||||
1. **Read the inputs.** The task contract, `docs/DESIGN_SYSTEM.md` (create it from the template below if absent), the closest existing screens (templates/widgets), and the user context in `docs/SELF_MODEL.md` / project planning. Reuse existing components and patterns by name; propose a new pattern only when no existing one fits, and record it in `DESIGN_SYSTEM.md`.
|
||||
2. **Write `docs/design/<feature>.md`** (≤ 2 screens), containing:
|
||||
- **User + job:** who uses this and what job it completes; the success moment in one sentence.
|
||||
- **Flow:** entry point → steps → exit, with the step count justified (fewer taps beats more options; name the target, e.g. "receipt in ≤ 3 taps").
|
||||
- **Screen states — all of them:** empty, loading, error, success, and (for offline-capable surfaces) offline / queued / sync-pending / sync-rejected. A state without a design is a bug deferred to production.
|
||||
- **Components:** reused ones by name and path; new ones with their `DESIGN_SYSTEM.md` entry.
|
||||
- **Copy:** every label, button, error, and empty-state message, in every supported locale — no placeholders, no English-only rows where i18n is required.
|
||||
- **Accessibility:** tap-target sizes, contrast, focus order, screen-reader labels for icon-only controls.
|
||||
- **Acceptance criteria:** numbered, observable checks a verifier can run or inspect ("tapping X from state Y shows Z"), including one criterion per non-happy-path state.
|
||||
3. **Stay in scope.** Spec only what the contract includes; list out-of-scope UI you deliberately did not design so nobody infers it was forgotten.
|
||||
4. **Return** the spec path, the design-system delta, and any open decision that changes scope, risk, or cost.
|
||||
|
||||
## docs/DESIGN_SYSTEM.md starter template
|
||||
|
||||
```markdown
|
||||
# Design system
|
||||
|
||||
> Conventions every user-facing change follows. Updated only by ux-ui-designer; violations are design-review findings.
|
||||
|
||||
## Principles
|
||||
- [e.g. fewest taps to complete the money task; offline is a first-class state; all copy ships in en + tl]
|
||||
|
||||
## Foundations
|
||||
- Type scale / spacing / color roles: [tokens or file path]
|
||||
- Tap targets ≥ 48dp; contrast ≥ WCAG AA; focus order follows visual order.
|
||||
|
||||
## Components
|
||||
| Component | Path | Use for | Never for |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
## Screen-state patterns
|
||||
- Empty / loading / error / offline / queued / sync-rejected: [canonical pattern per state]
|
||||
|
||||
## Copy rules
|
||||
- [tone, locale coverage, currency/date formats]
|
||||
```
|
||||
@@ -4,7 +4,7 @@ description: Run a bounded autonomous development loop (Steinberger-style) over
|
||||
allowed-tools: Read Grep Glob Bash Write Edit Skill Agent
|
||||
---
|
||||
|
||||
Operate a controlled maintenance loop that makes steady, verified progress without human babysitting — and without ever landing unverified or unauthorized work. Fable owns routing and acceptance; this skill is the loop discipline. Adapt the cadence to the runtime: a live session iterates continuously; a scheduled run (see the `schedule` skill) executes one pass per trigger.
|
||||
Operate a controlled maintenance loop that makes steady, verified progress without human babysitting — and without ever landing unverified or unauthorized work. Opus owns routing and acceptance; this skill is the loop discipline. Adapt the cadence to the runtime: a live session iterates continuously; a scheduled run (see the `schedule` skill) executes one pass per trigger.
|
||||
|
||||
## Loop
|
||||
|
||||
|
||||
40
.claude/skills/gauntlet-loop/SKILL.md
Normal file
40
.claude/skills/gauntlet-loop/SKILL.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: gauntlet-loop
|
||||
description: Run reference-benchmarked improvement rounds on an outcome that must match or beat a concrete quality bar — decompose into independently judgeable parts, then loop builder → fresh-context gauntlet-critic on the single biggest gap until parity, diminishing returns, or budget. Use for quality-benchmarked deliverables, not routine maintenance (that is dev-loop).
|
||||
allowed-tools: Read Grep Glob Bash Write Edit Skill Agent
|
||||
---
|
||||
|
||||
Iterate work against a concrete reference until a fresh-eyes referee calls parity — the Gauntlet Loop (Matt Shumer's method behind "Claude of Duty"). Opus owns routing and acceptance; this skill is the loop discipline.
|
||||
|
||||
## Preconditions — refuse to start until all three hold
|
||||
|
||||
1. **The bar is concrete.** `docs/REFERENCE_BAR.md` names at least one inspectable reference artifact per part in scope (file, screenshot, URL, sample output, recording) and how to compare against it. An adjective is not a bar; "make it amazing" starts nothing. If the bar is missing, request it from the owner as a decision-ready item — that request never stalls other lanes.
|
||||
2. **A budget exists.** Each part gets a round ceiling (an integer; add wall-clock only if the work is time-bound), written into the orchestration record and the `docs/GAUNTLET.md` row before round 1. A ceiling is a backstop so a stuck part cannot loop forever — never a plan to schedule rounds toward.
|
||||
3. **The bar is not gameable.** The referee judges the artifact as a user would experience it; any single metric is supporting evidence, never the target.
|
||||
|
||||
## Round protocol (per part)
|
||||
|
||||
1. **Decompose once.** Opus splits the outcome into the smallest parts that can be improved and judged separately — coupled work stays one part. Each part gets a row in `docs/GAUNTLET.md`: part, bar row, rounds-left ceiling, status.
|
||||
2. **Build.** One builder owns the part and returns the artifact plus exact instructions to render/run/see it. The builder never assesses its own round against the bar.
|
||||
3. **Referee.** Spawn `gauntlet-critic` fresh. Its packet is the part contract, the bar, and artifact access including the builder's render/run steps — mechanics pass through; the builder's reasoning, summary, or self-assessment never does, and neither do prior round reports (round history lives on the board, not in the referee's context). It returns verdict, single biggest gap weighted material/cosmetic, evidence, also-observed list. Referee effort is `high`; raise to `xhigh` only for a final parity verdict at the high-risk gate.
|
||||
4. **Log.** Append one line to Round history in `docs/GAUNTLET.md` — part, round, verdict, gap (weight) — and decrement the part's rounds-left. If Opus's session lacks write tools, the append rides in the next worker packet.
|
||||
5. **Apply stops, then loop.** Opus checks the stop conditions below against the board's round history — the stateless referee cannot make these calls; its verdict (`parity` or `output wins`) is the only stop it can trigger. If none fires, the builder's next packet targets exactly the named gap (plus any P0 from the also-observed list). Never pre-commit to a round count — "do three rounds and stop" defeats the method; the ceiling is a backstop, not a target.
|
||||
6. **Parallelize across parts** freely: different parts may sit in different rounds, with one builder and one referee per part per round.
|
||||
|
||||
## Stop conditions (per part — Opus applies these at each Log step, from the board's round history; Boundary fires the moment it appears)
|
||||
|
||||
- **Parity or better** — the round's verdict is `parity` or `output wins`.
|
||||
- **Diminishing returns** — two consecutive rounds with an unchanged verdict and a gap weighted `cosmetic`.
|
||||
- **Budget exhausted** — rounds-left hits zero: record the last verdict and open gap on the board; surface to the owner.
|
||||
- **Recurring gap** — the board names the same gap two rounds running and Opus has no new strategy for the next packet: park it decision-ready (short options, recommended default) and move to the next part.
|
||||
- **Boundary** — a round would need a destructive, external, or permission-crossing action: stop and escalate; never proceed on referee authority.
|
||||
|
||||
## Endgame
|
||||
|
||||
When every part has stopped: run one integration pass (integrator merges, verifier re-runs the full checks) so independently polished parts still work as a whole; apply the normal quality gates for the risk level; and if the per-part bars were partial views, run one final whole-artifact referee round against the bar. Record final verdicts on the board, then compress the outcome into `HANDOFF.md` and `PROGRESS.md` in owner language: what reached the bar, what stopped short and why.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Builders never self-grade; referees never see builder narrative; Opus never overrides a verdict without observable evidence.
|
||||
- Evidence is observable — rendered pixels, command output, test results, a cold read of the finished writing — never a summary of them.
|
||||
- Consequential actions (deploy, spend, delete, credentials) stay behind explicit owner authorization regardless of loop momentum.
|
||||
20
.claude/skills/ux-psych-audit/SKILL.md
Normal file
20
.claude/skills/ux-psych-audit/SKILL.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
name: ux-psych-audit
|
||||
description: Behavioral-psychology audit of an implemented user journey — decision cost, effort, momentum, value-before-ask, investment, framing, emotional arc, and trust, grounded in evidence-backed principles. Returns P0–P3 findings with evidence and smallest fix; dark patterns are always defects. Owner: ux-psychologist; read-only. Use on implemented UX; pre-build psychology enters as design-spec constraints.
|
||||
allowed-tools: Read Grep Glob
|
||||
---
|
||||
|
||||
Audit what users actually experience against how people actually decide. Read-only: findings and smallest fixes, never patches. First name the journey, then walk it end to end in the implementation (templates, widgets, copy, defaults, prices): **first-run/onboarding · core task loop · return visit · upgrade/checkout · exit (cancel, error, uninstall)**. Grep for real option counts, defaults, and progress states — never assume them.
|
||||
|
||||
1. **Decision cost.** Count simultaneous choices at each decision point (Hick's law; in the classic jam study 24 options converted ~3%, 6 options ~30%). Every extra option, field, or setting must earn its place; prefer progressive disclosure, and exactly one visually primary action per screen (Von Restorff).
|
||||
2. **Effort & defaults.** Most users never change defaults and read them as recommendations: are forms pre-filled with the most common choice so the task is scan-and-adjust, not create-from-scratch? Is irreducible complexity absorbed by the system rather than the user (Tesler)? Primary targets large and reachable (Fitts).
|
||||
3. **Momentum.** Never start a user at zero: endowed progress (pre-stamped loyalty cards complete at roughly double the rate) and the goal-gradient effect (effort rises near completion) reward visible head starts. Visible incomplete steps pull users back (Zeigarnik); feedback within ~400 ms keeps flow (Doherty threshold).
|
||||
4. **Value before ask (reciprocity).** Deliver a real sample of value before signup, permission, or payment walls — partial results, previews, trial access (Cialdini's reciprocity). A wall before first demonstrated value is at least P1.
|
||||
5. **Investment & ownership.** Early personalization and building (name it, pick goals, assemble the first artifact) raise perceived value (IKEA and endowment effects) and make each return visit richer — the investment step of the Hooked loop. Ask: what does a user own after two minutes?
|
||||
6. **Motivation & framing.** At each conversion moment check Fogg's B=MAP: are motivation, ability, and a well-timed prompt all present, and which one is missing where users drop? Losses weigh roughly twice as much as gains (Kahneman) — frame genuinely at-risk value honestly, never invent risk. Prices and plans need deliberate context and anchors, not isolation (contrast effect).
|
||||
7. **Emotional arc.** People judge an experience by its peak and its end (peak-end rule): audit the best moment and every exit — success, error, empty, and cancellation paths — because the end of a bad journey is where trust is decided. Familiar patterns lower load (Jakob's law); visual polish buys perceived usability (aesthetic-usability effect) but never substitutes for it.
|
||||
8. **Trust screen — always run last.** Dark patterns are defects, not tactics: fake urgency/scarcity, confirmshaming, roach-motel cancellation, hidden costs or drip pricing, forced continuity without warning, disguised ads, guilt loops, nagging re-prompts. Any of these is P0–P1 with the trust and regulatory risk named. Persuasion aligned with the user's chosen goal is good design; persuasion against the user's interest is a defect regardless of conversion lift.
|
||||
|
||||
Rank findings **P0** (trust-destroying mechanic, or the user's job/value blocked before value is demonstrated), **P1** (principle violated on a core conversion/retention path with likely drop-off), **P2** (missed momentum/framing reinforcement), **P3** (polish). Each finding: evidence (file/line or reproduction) · principle · expected behavioral impact · smallest fix · where analytics exist, the metric that would confirm it. Findings are hypotheses about behavior — recommend the measurement, don't promise the lift. Do not invent findings to seem thorough; `none` after meaningful checks is a valid result. Route accepted fixes to the orchestrator as task contracts; durable copy/pattern rules go to the ux-ui-designer for `DESIGN_SYSTEM.md`.
|
||||
|
||||
Return exactly: **Verdict** (behaviorally sound / needs work / trust risk) · **Findings** (P0–P3 or `none`) · **Journey audited** (stages walked, screens/files inspected, lenses applied) · **Top opportunities** (≤ 3: principle → smallest change → metric).
|
||||
Reference in New Issue
Block a user