Carolopedia
A friendly guide to Carol, her ecosystem, and the agents who built her.
📖About
GAP: The Carol App Design System (design #178 — mobile breakpoints, >=44px tap targets, clickable app-header pointing home, fixed CAROL_LOGO_v4 topbar, palette, WCAG-AA) exists as a written standard but is ORPHANED: neither Sage spec stage (Analyst Spec-Writer) nor Archon design stage (Design Author/ar_design_01) references it. Only Forge is told to consult it before writing HTML. Result: an autonomously-built Carolverse app can skip mobile-friendliness or a clickable header and nothing upstream requires it. SCOPE: (1) Sage spec stage must inject the applicable Carolverse app conventions from design #178 into the design spec it writes, so the convention is a stated requirement. (2) Archon design stage must consult design #178 and produce a design that explicitly addresses each applicable convention (responsive, app-header->home, topbar, tap targets, a11y). (3) The decide/design output should make these checkable so review (Hermione/Albus) can verify them. This is the first concrete case of a broader goal: Carolverse-specific skills that bake house conventions into whatever is built, for consistency.
⚖️Decisions
- Elrond's bypass methodology checklist (a reminder, not a gate -- you've got this): 0. File it requested_mode='bypass' (planner-vs-bypass is a deliberate choice). bypass_start REFUSES a non-bypass initiative (CAROL-INI-1846), and the dispatcher only skips the bypass lane when the mode says bypass -- a 'planner' mistag lets Merlin's pipeline grab the placeholder step and block your finished work. 1. Filed as planned status -- let the bypass claim/activate it; never file active. 2. Open the bypass (bypass_start) with your droid id + the remediation answer (remediates_initiative_id=NNN, or remediates_nothing=True). 3. Work the blocks for your work-type: template -> design -> code -> test -> review. Do the real work; record decisions on the initiative as you make them. 4. Reality is recorded for you at close -- code (files changed), each decision, and the twin-review verdict become real activities tied to this initiative and show in the Activity Tracker like a planner run (CAROL-INI-1840). No dummy rows. 5. Keep the initiative status moving; it parks in 'reviewing' and is tagged uat-pending for you at close (CAROL-INI-1836), so the stuck-watchdog leaves it alone until UAT. 6. Close runs the gates (design/architecture compliance + caller-audit). If a gate flags something pre-existing or unrelated to your change, waive it with a clear written rationale -- audit, don't skip. 7. Bypass skips the planner's auto-orchestration, NOT the standards. Same template checklist, same review, same observability as a planner run. (elrond)
- [status-router] planned -> executing | event=bypass_executing | bypass transition (or-bx-01)
- Created shared/design_standards.py as the single machine-checkable projection of design #178; both spec and design stages import it so there is one source of truth. (orion)
- App-facing detection is heuristic (UI keywords or apps/ web files); non-app tasks get only the design-standards pointer, app tasks get the full 8-convention checklist, to avoid over-firing UI rules on backend work. (orion)
- Archon emits a conventions_addressed checklist (8 unticked items) into the design so the review stage can verify each convention on the built app. (orion)
- [status-router] executing -> reviewing | event=bypass_reviewing | bypass transition (or-bx-01)
- [status-router] reviewing -> closed | event=operator_signoff | Auto-accepted (CAROL-INI-1859): Orion-initiated, >2 days in reviewing with no objection. (el-srac-01)
✅Success criteria
- Sage spec stage injects applicable design #178 conventions into the design spec as stated requirements (must_have)
- Archon design stage consults design #178 and explicitly addresses each applicable app convention (responsive, app-header to home, topbar, tap targets, a11y) (must_have)
- Conventions are recorded in a checkable form so review can verify them on a built app (must_have)