ring%3adev-cycle-frontend（Ring%3adev 循环前端）

Frontend Development Cycle Orchestrator

Standards Loading (MANDATORY)

Before any gate execution, you MUST load Ring standards:

<fetch_required> https://raw.githubusercontent.com/LerianStudio/ring/main/CLAUDE.md https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md </fetch_required>

Fetch URLs above and extract: Agent Modification Verification requirements, Anti-Rationalization Tables requirements, Critical Rules, and Frontend Standards.

<block_condition>

• WebFetch fails or returns empty
• CLAUDE.md not accessible
• frontend.md not accessible </block_condition>

If any condition is true, STOP and report blocker. Cannot proceed without Ring standards.

Overview

The frontend development cycle orchestrator loads tasks/subtasks from PM team output (or manual task files) and executes through 9 gates (Gate 0-8) with all gates executing per unit (no deferred execution):

• Gates 0-8 (per unit): Write code + run tests/checks per task/subtask
• All 9 gates are sequential and mandatory

Unlike the backend ring:dev-cycle (which defers integration/chaos test execution), the frontend cycle executes all gates fully per unit. Frontend testing tools (Playwright, Storybook, Lighthouse) do not require heavy container infrastructure.

MUST announce at start: "I'm using the ring:dev-cycle-frontend skill to orchestrate frontend task execution through 9 gates (Gate 0-8). All gates execute per unit."

CRITICAL: Specialized Agents Perform All Tasks

See shared-patterns/shared-orchestrator-principle.md for full ORCHESTRATOR principle, role separation, forbidden/required actions, gate-to-agent mapping, and anti-rationalization table.

Summary: You orchestrate. Agents execute. If using Read/Write/Edit/Bash on source code, STOP. Dispatch agent.

ORCHESTRATOR BOUNDARIES (HARD GATE)

This section defines exactly what the orchestrator CAN and CANNOT do.

What Orchestrator CAN Do (PERMITTED)

What Orchestrator CANNOT Do (FORBIDDEN)

Any of these actions by orchestrator = IMMEDIATE VIOLATION. Dispatch agent instead.

The 3-FILE RULE

If a task requires editing MORE than 3 files, MUST dispatch specialist agent.

This is not negotiable:

• 1-3 files of non-source content (markdown, json, yaml) - Orchestrator MAY edit directly
• 1+ source code files (*.ts, *.tsx, *.jsx, *.css) - MUST dispatch agent
• 4+ files of any type - MUST dispatch agent

Orchestrator Workflow Order (MANDATORY)

+------------------------------------------------------------------+
|  CORRECT WORKFLOW ORDER                                           |
+------------------------------------------------------------------+
|                                                                   |
|  1. Load task file (Read docs/pre-dev/*/tasks-frontend.md)        |
|  2. Detect UI library mode (Step 0)                               |
|  3. Load backend handoff if available                             |
|  4. Ask execution mode (AskUserQuestion)                          |
|  5. Determine state path + Check/Load state                       |
|  6. WebFetch Ring Standards (CLAUDE.md + frontend.md)             |
|  7. LOAD SUB-SKILL for current gate (Skill tool)                  |
|  8. Execute sub-skill instructions (dispatch agent via Task)      |
|  9. Wait for agent completion                                     |
|  10. Verify agent output (Standards Coverage Table)               |
|  11. Update state (Write to JSON)                                 |
|  12. Proceed to next gate                                         |
|                                                                   |
|  ================================================================ |
|  WRONG: Load -> Mode -> Standards -> Task(agent) directly         |
|  RIGHT: Load -> Mode -> Standards -> Skill(sub) -> Task(agent)    |
|  ================================================================ |
+------------------------------------------------------------------+

UI Library Mode Detection (MANDATORY - Step 0)

Before any gate execution, detect the project's UI library configuration:

Read tool: package.json

Parse the JSON content:
  - If "dependencies" or "devDependencies" contains "@lerianstudio/sindarian-ui"
    → ui_library_mode = "sindarian-ui"
  - Otherwise
    → ui_library_mode = "fallback-only"

Store result in state file under ui_library_mode.

@lerianstudio/sindarian-ui is PRIMARY. shadcn/ui + Radix is FALLBACK for missing components.

Anti-Rationalization for UI Library Mode:

Step 1.5: Standards Pre-Cache (MANDATORY)

Cache all standards URLs the cycle will need, ONCE, into state.cached_standards. Sub-skills read from this cache instead of calling WebFetch themselves.

Required URLs to pre-fetch (MUST succeed all):

1. https://raw.githubusercontent.com/LerianStudio/ring/main/CLAUDE.md
2. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md
3. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend/testing-accessibility.md
4. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend/testing-visual.md
5. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend/testing-e2e.md
6. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend/testing-performance.md
7. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/devops.md
8. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md
9. https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/typescript.md (if BFF layer detected)

Protocol:

For each URL in the required list:
  WebFetch: [URL]
  Write to state.cached_standards[URL] = {
    "fetched_at": current_iso_timestamp,
    "content": <fetched content>
  }

MANDATORY: Save state to file after cache populated — Write tool → [state.state_path]

Blocker: If ANY URL fails to fetch, STOP cycle and report. Cache MUST be complete. Sub-skills downstream rely on state.cached_standards being populated; a partial cache causes WebFetch fallback warnings and defeats the purpose of pre-caching.

Rationale: Before this step existed, every sub-skill dispatch triggered its own WebFetch of the same standards. The 5-minute prompt cache TTL is regularly exceeded, producing 15–25+ redundant network fetches per cycle. A single pre-cache at cycle start reduces that to one fetch per unique URL.

Backend Handoff Loading (Optional)

If the frontend cycle follows a backend ring:dev-cycle, load the handoff file:

Check: Does docs/ring:dev-cycle/handoff-frontend.json exist?

  YES -> Load and parse:
    - endpoints: API endpoints implemented by backend
    - types: TypeScript types/interfaces exported by backend
    - contracts: Request/response schemas
    - auth_pattern: Authentication approach (JWT, session, etc.)
    Store in state.backend_handoff

  NO -> Proceed without handoff (standalone frontend development)

Handoff contents are CONTEXT for agents, not requirements. Agents MUST still follow all gate requirements regardless of handoff content.

SUB-SKILL LOADING IS MANDATORY (HARD GATE)

Before dispatching any agent, you MUST load the corresponding sub-skill first.

<cannot_skip>

• Gate 0: Skill("ring:dev-implementation") → then Task(subagent_type="ring:frontend-engineer" or "ring:ui-engineer" or "ring:frontend-bff-engineer-typescript")
• Gate 1: Skill("ring:dev-devops") → then Task(subagent_type="ring:devops-engineer")
• Gate 2: Skill("ring:dev-frontend-accessibility") → then Task(subagent_type="ring:qa-analyst-frontend", test_mode="accessibility")
• Gate 3: Skill("ring:dev-unit-testing") → then Task(subagent_type="ring:qa-analyst-frontend", test_mode="unit")
• Gate 4: Skill("ring:dev-frontend-visual") → then Task(subagent_type="ring:qa-analyst-frontend", test_mode="visual")
• Gate 5: Skill("ring:dev-frontend-e2e") → then Task(subagent_type="ring:qa-analyst-frontend", test_mode="e2e")
• Gate 6: Skill("ring:dev-frontend-performance") → then Task(subagent_type="ring:qa-analyst-frontend", test_mode="performance")
• Gate 7: Skill("ring:codereview") → then 5x Task(...) in parallel
• Gate 8: Skill("ring:dev-validation") → N/A (verification only) </cannot_skip>

Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".

The workflow for each gate is:

1. Skill("[sub-skill-name]")     <- Load sub-skill instructions
2. Follow sub-skill instructions  <- Sub-skill tells you HOW to dispatch
3. Task(subagent_type=...)       <- Dispatch agent as sub-skill instructs
4. Validate agent output          <- Per sub-skill validation rules
5. Update state                   <- Record results

Custom Instructions (Optional Second Argument)

Validation: See shared-patterns/custom-prompt-validation.md for max length (500 chars), sanitization rules, gate protection, and conflict handling.

If custom_prompt is set in state, inject it into all agent dispatches:

Task tool:
  subagent_type: "ring:frontend-engineer"
  prompt: |
    **CUSTOM CONTEXT (from user):**
    {state.custom_prompt}

    ---

    **Standard Instructions:**
    [... rest of agent prompt ...]

Rules for custom prompt:

1. Inject at TOP of prompt - User context takes precedence
2. Preserve in state - custom_prompt persists for resume
3. Include in execution report - Document what context was used
4. Forward via state - Sub-skills read custom_prompt from state file and inject into their agent dispatches (no explicit parameter passing needed)

Example custom prompts and their effect:

Anti-Rationalization for Skipping Sub-Skills

Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".

Anti-Rationalization for Direct Coding

Red Flags - Orchestrator Violation in Progress

If you catch yourself doing any of these, STOP IMMEDIATELY:

RED FLAG: About to Read *.tsx or *.ts file
   -> STOP. Dispatch agent instead.

RED FLAG: About to Write/Create source code
   -> STOP. Dispatch agent instead.

RED FLAG: About to Edit source code or CSS
   -> STOP. Dispatch agent instead.

RED FLAG: About to run "npm test" or "npx playwright test"
   -> STOP. Agent runs tests, not you.

RED FLAG: Thinking "I'll just..."
   -> STOP. "Just" is the warning word. Dispatch agent.

RED FLAG: Thinking "This is simple enough..."
   -> STOP. Simplicity is irrelevant. Dispatch agent.

RED FLAG: Standards loaded, but next action is not Task tool
   -> STOP. After standards, IMMEDIATELY dispatch agent.

Recovery from Orchestrator Violation

If you violated orchestrator boundaries:

1. STOP current execution immediately
2. DISCARD any direct changes (git checkout --.)
3. DISPATCH the correct specialist agent
4. Agent implements from scratch following TDD
5. Document the violation for feedback loop

Sunk cost of direct work is IRRELEVANT. Agent dispatch is MANDATORY.

Blocker Criteria - STOP and Report

<block_condition>

• Gate Failure: Tests not passing, review failed -> STOP, cannot proceed to next gate
• Missing Standards: No PROJECT_RULES.md -> STOP, report blocker and wait
• Agent Failure: Specialist agent returned errors -> STOP, diagnose and report
• User Decision Required: Component library choice, design system variance -> STOP, present options
• Accessibility Blocker: WCAG AA violations found -> STOP, fix before proceeding </block_condition>

You CANNOT proceed when blocked. Report and wait for resolution.

Cannot Be Overridden

<cannot_skip>

• All 9 gates must execute (0->1->2->3->4->5->6->7->8) - Each gate catches different issues
• All testing gates (2-6) are MANDATORY - Comprehensive test coverage ensures quality
• Gates execute in order (0->1->2->3->4->5->6->7->8) - Dependencies exist between gates
• Gate 7 requires all 5 reviewers - Different review perspectives are complementary
• Unit test coverage threshold >= 85% - Industry standard for quality code
• WCAG 2.1 AA compliance is non-negotiable - Accessibility is a legal requirement
• Core Web Vitals thresholds are non-negotiable - Performance affects user experience
• PROJECT_RULES.md must exist - Cannot verify standards without target </cannot_skip>

No exceptions. User cannot override. Time pressure cannot override.

Severity Calibration

Report all severities. Let user prioritize.

Reviewer Verdicts Are Final

MEDIUM issues found in Gate 7 MUST be fixed. No exceptions.

Severity mapping is absolute:

• CRITICAL/HIGH/MEDIUM -> Fix NOW, re-run all 5 reviewers
• LOW -> Add TODO(review): comment
• Cosmetic -> Add FIXME(nitpick): comment

No negotiation. No exceptions. No "special cases".

The 9 Gates

Cadence column: subtask = runs once per subtask (execution unit). task = runs ONCE per task, after all subtasks complete their Gate 0/3/8.

All gates are MANDATORY. No exceptions. No skip reasons.

Gate 0: Agent Selection Logic

UI library mode (detected in Step 0) MUST be passed to the agent as context.

Gate 0: Frontend TDD Policy

TDD (RED→GREEN) applies to behavioral logic. Visual/presentational components use test-after.

Rules:

1. Behavioral components in Gate 0 MUST produce TDD RED failure output before implementation
2. Visual/presentational components in Gate 0 are implemented without RED phase; Gate 4 creates their snapshot tests
3. Mixed components (behavior + visual): TDD for the behavioral part, test-after for the visual part
4. Gate 3 (Unit Testing) coverage threshold (85%) still applies to ALL component types - the distinction is only about WHEN tests are written, not WHETHER

Anti-Rationalization:

Gate 7: Code Review Adaptation (5 Reviewers)

For the frontend cycle, the 5 parallel reviewers are:

NOTE: The 5th reviewer slot uses ring:frontend-engineer in review mode instead of ring:nil-safety-reviewer (which is Go-specific). The frontend engineer reviews accessibility compliance and frontend standards adherence.

All 5 reviewers MUST be dispatched in a single message with 5 parallel Task calls.

# Gate 7: Dispatch all 5 reviewers in parallel (SINGLE message)
Task 1: { subagent_type: "ring:code-reviewer", ... }
Task 2: { subagent_type: "ring:business-logic-reviewer", ... }
Task 3: { subagent_type: "ring:security-reviewer", ... }
Task 4: { subagent_type: "ring:test-reviewer", ... }
Task 5: { subagent_type: "ring:frontend-engineer", prompt: "REVIEW MODE: Review accessibility compliance and frontend standards adherence...", ... }

Gate Completion Definition (HARD GATE)

A gate is COMPLETE only when all components finish successfully:

Cadence column: subtask = runs per subtask. task = runs ONCE per task on the UNION of all subtasks' changed files. All quality thresholds (WCAG AA, 85% coverage, CWV, Lighthouse ≥ 90) remain unchanged — only the execution frequency changes.

CRITICAL for Gate 7: Running 4 of 5 reviewers is not a partial pass - it's a FAIL. Re-run all 5 reviewers.

Anti-Rationalization for Partial Gates:

Gate Order Enforcement (HARD GATE)

Gates MUST execute in order: 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8. All 9 gates are MANDATORY.

All testing gates (2-6) are MANDATORY. No exceptions. No skip reasons.

Gates are not parallelizable across different gates. Sequential execution is MANDATORY.

Execution Order

Core Principle: Each task passes through all 9 gates. Gates 0, 3, 8 execute per subtask (execution unit). Gates 1, 2, 4, 5, 6, 7 execute ONCE per task after all subtasks complete their subtask-level gates.

Per-Task Flow:

Task → (for each subtask: Gate 0 → Gate 3 → Gate 8)
     → Gate 1 → Gate 2 → Gate 4 → Gate 5 → Gate 6 → Gate 7
     → Task-level visual report → Task Checkpoint → Next Task

Execution Loop Structure (cadence model)

for each task in state.tasks:
  # ===== SUBTASK-LEVEL GATES =====
  for each subtask in task.subtasks:
    Execute Gate 0 (Implementation)
    Execute Gate 3 (Unit Testing)
    Execute Gate 8 (Validation)
    [per-subtask visual report — OPT-IN only via state.visual_report_granularity]
  end for

  # ===== TASK-LEVEL GATES =====
  # Input aggregation: implementation_files = UNION across subtasks
  Execute Gate 1 (DevOps)
  Execute Gate 2 (Accessibility)
  Execute Gate 4 (Visual)
  Execute Gate 5 (E2E)
  Execute Gate 6 (Performance)
  Execute Gate 7 (Review — 5 parallel reviewers on cumulative task diff)

  Generate task-level visual report
  Accumulate metrics into state.tasks[i].accumulated_metrics
  [task checkpoint]
end for

# Cycle-level (minimal for frontend)
Final Commit

Key properties:

• Subtask-level gates (0, 3, 8) establish working, tested, validated code per subtask.
• Task-level gates (1, 2, 4, 5, 6, 7) run on the UNION of all subtasks' changed files — one pass per task, not N passes.
• Reviewers at Gate 7 see the cumulative task diff, so cross-subtask interaction bugs become MORE visible, not less.
• Per-subtask visual reports are opt-in; the default task-level aggregate report covers all subtasks' diffs.

Commit Timing

User selects when commits happen (during initialization).

Commit Message Format

Commit Timing vs Execution Mode

Note: Checkpoints (user approval pauses) are controlled by execution_mode. Commits are controlled by commit_timing. They are independent settings.

State Management

State Path

State File Structure

State is persisted to docs/ring:dev-cycle-frontend/current-cycle.json:

{
  "version": "1.1.0",
  "cycle_id": "uuid",
  "started_at": "ISO timestamp",
  "updated_at": "ISO timestamp",
  "source_file": "path/to/tasks-frontend.md",
  "state_path": "docs/ring:dev-cycle-frontend/current-cycle.json",
  "cycle_type": "frontend",
  "ui_library_mode": "sindarian-ui | fallback-only",
  "_comment_cached_standards": "Populated by Step 1.5 (Standards Pre-Cache). Dictionary of URL → {fetched_at, content}. Sub-skills MUST read from here instead of calling WebFetch.",
  "cached_standards": {},
  "_comment_visual_report_granularity": "Default 'task' (generate visual report once per task). Opt-in 'subtask' to generate per-subtask reports.",
  "visual_report_granularity": "task",
  "backend_handoff": {
    "loaded": true,
    "source": "docs/ring:dev-cycle/handoff-frontend.json",
    "endpoints": [],
    "types": [],
    "contracts": []
  },
  "execution_mode": "manual_per_subtask|manual_per_task|automatic",
  "commit_timing": "per_subtask|per_task|at_end",
  "custom_prompt": {
    "type": "string",
    "optional": true,
    "max_length": 500,
    "description": "User-provided context for agents (from second positional argument). Max 500 characters.",
    "validation": "Max 500 chars (truncated with warning if exceeded); whitespace trimmed; control chars stripped (except newlines)."
  },
  "status": "in_progress|completed|failed|paused|paused_for_approval|paused_for_task_approval",
  "feedback_loop_completed": false,
  "current_task_index": 0,
  "current_gate": 0,
  "current_subtask_index": 0,
  "tasks": [
    {
      "id": "T-001",
      "title": "Task title",
      "status": "pending|in_progress|completed|failed|blocked",
      "feedback_loop_completed": false,
      "subtasks": [
        {
          "id": "ST-001-01",
          "file": "subtasks/T-001/ST-001-01.md",
          "status": "pending|completed",
          "_comment_subtask_gate_progress": "Per-subtask tracking of subtask-level gates (0, 3, 8). Task-level gates (1,2,4,5,6,7) live on state.tasks[i].gate_progress instead.",
          "gate_progress": {
            "implementation": {"status": "pending|completed"},
            "unit_testing": {"status": "pending|completed", "coverage_actual": 0.0},
            "validation": {"status": "pending|completed", "result": "approved|rejected"}
          }
        }
      ],
      "_comment_task_gate_progress": "Task-level gates (1, 2, 4, 5, 6, 7) run ONCE per task on the UNION of all subtasks' changed files. Subtask-level gates (0, 3, 8) live on state.tasks[i].subtasks[j].gate_progress.",
      "gate_progress": {
        "implementation": {
          "status": "pending|in_progress|completed",
          "started_at": "...",
          "tdd_red": {
            "status": "pending|in_progress|completed",
            "test_file": "path/to/test_file.spec.tsx",
            "failure_output": "FAIL: expected element not found",
            "completed_at": "ISO timestamp"
          },
          "tdd_green": {
            "status": "pending|in_progress|completed",
            "implementation_file": "path/to/Component.tsx",
            "test_pass_output": "PASS: 12 tests passed",
            "completed_at": "ISO timestamp"
          }
        },
        "devops": {"status": "pending"},
        "accessibility": {
          "status": "pending|in_progress|completed",
          "wcag_violations": 0,
          "keyboard_nav_tested": false,
          "screen_reader_tested": false
        },
        "unit_testing": {
          "status": "pending|in_progress|completed",
          "coverage_actual": 0,
          "coverage_threshold": 85
        },
        "visual_testing": {
          "status": "pending|in_progress|completed",
          "snapshots_total": 0,
          "snapshots_passed": 0,
          "responsive_breakpoints_covered": []
        },
        "e2e_testing": {
          "status": "pending|in_progress|completed",
          "flows_tested": 0,
          "browsers_tested": [],
          "stability_runs": 0
        },
        "performance_testing": {
          "status": "pending|in_progress|completed",
          "lcp_ms": 0,
          "cls": 0,
          "inp_ms": 0,
          "lighthouse_score": 0
        },
        "review": {"status": "pending"},
        "validation": {"status": "pending"}
      },
      "agent_outputs": {
        "implementation": {
          "agent": "ring:frontend-engineer",
          "output": "## Summary\n...",
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "iterations": 1,
          "standards_compliance": {
            "total_sections": 12,
            "compliant": 12,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "devops": {
          "agent": "ring:devops-engineer",
          "output": "## Summary\n...",
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "iterations": 1,
          "artifacts_created": ["Dockerfile", "nginx.conf", ".env.example"],
          "verification_errors": [],
          "standards_compliance": {}
        },
        "accessibility": {
          "agent": "ring:qa-analyst-frontend",
          "test_mode": "accessibility",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "wcag_violations": 0,
          "keyboard_nav_issues": 0,
          "screen_reader_issues": 0,
          "iterations": 1,
          "timestamp": "ISO timestamp"
        },
        "unit_testing": {
          "agent": "ring:qa-analyst-frontend",
          "test_mode": "unit",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "coverage_actual": 87.5,
          "coverage_threshold": 85,
          "iterations": 1,
          "timestamp": "ISO timestamp"
        },
        "visual_testing": {
          "agent": "ring:qa-analyst-frontend",
          "test_mode": "visual",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "snapshots_total": 15,
          "snapshots_passed": 15,
          "iterations": 1,
          "timestamp": "ISO timestamp"
        },
        "e2e_testing": {
          "agent": "ring:qa-analyst-frontend",
          "test_mode": "e2e",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "flows_tested": 5,
          "browsers_tested": ["chromium", "firefox", "webkit"],
          "stability_runs": 3,
          "iterations": 1,
          "timestamp": "ISO timestamp"
        },
        "performance_testing": {
          "agent": "ring:qa-analyst-frontend",
          "test_mode": "performance",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "lcp_ms": 2100,
          "cls": 0.05,
          "inp_ms": 150,
          "lighthouse_score": 93,
          "iterations": 1,
          "timestamp": "ISO timestamp"
        },
        "review": {
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "code_reviewer": {
            "agent": "ring:code-reviewer",
            "output": "...",
            "verdict": "PASS",
            "issues": []
          },
          "business_logic_reviewer": {
            "agent": "ring:business-logic-reviewer",
            "output": "...",
            "verdict": "PASS",
            "issues": []
          },
          "security_reviewer": {
            "agent": "ring:security-reviewer",
            "output": "...",
            "verdict": "PASS",
            "issues": []
          },
          "test_reviewer": {
            "agent": "ring:test-reviewer",
            "output": "...",
            "verdict": "PASS",
            "issues": []
          },
          "frontend_engineer_reviewer": {
            "agent": "ring:frontend-engineer",
            "mode": "review",
            "output": "...",
            "verdict": "PASS",
            "issues": []
          }
        },
        "validation": {
          "result": "approved|rejected",
          "timestamp": "ISO timestamp"
        }
      },
      "_comment_accumulated_metrics": "Task-level rollup of gate metrics. Populated after the task-level gates complete. Cycle-end dev-report reads accumulated_metrics from all tasks.",
      "accumulated_metrics": {
        "gate_durations_ms": {},
        "review_iterations": 0,
        "testing_iterations": 0,
        "issues_by_severity": {"CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0}
      },
      "feedback_loop_completed": false
    }
  ],
  "metrics": {
    "total_duration_ms": 0,
    "gate_durations": {},
    "review_iterations": 0,
    "testing_iterations": 0
  }
}

Populating Structured Data

Each gate MUST populate its structured fields when saving to state:

Empty arrays [] indicate no issues found - this is valid data for feedback-loop.

State Persistence Rule (MANDATORY)

"Update state" means BOTH update the object and write to file. Not just in-memory.

After every Gate Transition

You MUST execute these steps after completing any gate:

# Step 1: Update state object with gate results
state.tasks[current_task_index].gate_progress.[gate_name].status = "completed"
state.tasks[current_task_index].gate_progress.[gate_name].completed_at = "[ISO timestamp]"
state.current_gate = [next_gate_number]
state.updated_at = "[ISO timestamp]"

# Step 2: Write to file (MANDATORY - use Write tool)
Write tool:
  file_path: "docs/ring:dev-cycle-frontend/current-cycle.json"
  content: [full JSON state]

State Persistence Checkpoints

Anti-Rationalization for State Persistence

Checkpoint Modes

User selects checkpoint mode during initialization.

CRITICAL: Execution mode affects CHECKPOINTS (user approval pauses), not GATES (quality checks). All gates execute regardless of mode.

Checkpoint Questions

Unit Checkpoint (after subtask completes Gate 8):

VISUAL CHANGE REPORT (subtask-level — OPT-IN ONLY):

• Default: SKIP per-subtask visual report. Task-level aggregate report is generated at the Task Checkpoint below.
• Opt-in: If state.visual_report_granularity == "subtask", generate per-subtask report. Default value is "task".
• Rationale: Task-level aggregate covers all subtasks' diffs; per-subtask reports are rarely consumed and cost one visualize dispatch each.

Subtask {id} complete. All 9 gates passed.
(a) Continue to next subtask
(b) Pause cycle (save state for --resume)
(c) Abort cycle

Task Checkpoint (after all subtasks of a task complete):

VISUAL CHANGE REPORT (MANDATORY - before task checkpoint question):

• MANDATORY: Invoke Skill("ring:visualize") to generate an aggregate code-diff HTML report for all subtasks
• Read default/skills/visualize/templates/code-diff.html to absorb the patterns before generating
• Content aggregated from all subtask executions:

- Task Overview: Task ID, title, all subtask IDs and their gate statuses - Combined File Changes: All files modified across all subtasks with before/after diff panels - Aggregate Metrics: Total tests added, total review iterations, total lines changed, accessibility score, performance score

• Save to: docs/ring:dev-cycle-frontend/reports/task-{task_id}-report.html
• Open in browser: macOS: open docs/ring:dev-cycle-frontend/reports/task-{task_id}-report.html Linux: xdg-open docs/ring:dev-cycle-frontend/reports/task-{task_id}-report.html
• Tell the user the file path
• See shared-patterns/anti-rationalization-visual-report.md for anti-rationalization table

Task {id} complete. All subtasks passed all gates.
(a) Continue to next task
(b) Pause cycle
(c) Abort cycle

Step 0: Verify PROJECT_RULES.md Exists (HARD GATE)

NON-NEGOTIABLE. Cycle CANNOT proceed without project standards.

Same flow as backend ring:dev-cycle:

Check: Does docs/PROJECT_RULES.md exist?

  YES -> Proceed to Step 1 (Initialize or Resume)

  NO -> ASK: "Is this a LEGACY project?"
    YES (legacy) -> Dispatch ring:codebase-explorer + ask 3 questions + generate PROJECT_RULES.md
    NO (new) -> Check for PM documents (PRD/TRD/Feature Map)
      HAS PM docs -> Generate PROJECT_RULES.md from PM docs
      NO PM docs -> HARD BLOCK: "Run /ring:pre-dev-full or /ring:pre-dev-feature first"

Step 1: Initialize or Resume

Prompt-Only Mode (no task file)

Input: Direct prompt without a task file path (e.g., /ring:dev-cycle-frontend Implement dashboard with transaction list)

1. Detect prompt-only mode: No task file argument provided
2. Analyze prompt: Extract intent, scope, and frontend requirements
3. Explore codebase: Dispatch ring:codebase-explorer to understand project structure
4. Generate tasks: Create task structure internally based on prompt + codebase analysis
5. Present generated tasks: Show user the auto-generated task breakdown
6. Confirm with user: "I generated X tasks from your prompt. Proceed?"
7. Continue to execution mode selection

New Cycle (with task file path)

Input: path/to/tasks-frontend.md or path/to/pre-dev/{feature}/ with optional second argument for custom instructions

Examples:

• /ring:dev-cycle-frontend tasks.md
• /ring:dev-cycle-frontend tasks.md "Use shadcn/ui components"

1. Detect input: File -> Load directly | Directory -> Load tasks-frontend.md + discover subtasks/
2. Build order: Read tasks, check for subtasks (ST-XXX-01, 02...)
3. Detect UI library mode (Step 0 above)
4. Load backend handoff if docs/ring:dev-cycle/handoff-frontend.json exists
5. Capture and validate custom instructions: If second argument provided
6. Initialize state: Generate cycle_id, create state file, set indices to 0
7. Display plan: "Loaded X tasks with Y subtasks. UI mode: {mode}. Backend handoff: {loaded/not found}."
8. ASK EXECUTION MODE (MANDATORY - AskUserQuestion):

- Options: (a) Manual per subtask (b) Manual per task (c) Automatic - Do not skip: User hints ≠ mode selection. Only explicit a/b/c is valid.

1. ASK COMMIT TIMING (MANDATORY - AskUserQuestion):

- Options: (a) Per subtask (b) Per task (c) At the end - Store in commit_timing field in state

1. Start: Display mode + commit timing, proceed to Gate 0

Resume Cycle (--resume flag)

1. Find existing state file: Check docs/ring:dev-cycle-frontend/current-cycle.json

- If not found -> Error: "No frontend cycle to resume"

1. Load state file, validate
2. Display: cycle started, tasks completed/total, current task/subtask/gate, paused reason
3. Handle paused states:

Step 2-10: Gate Execution

See Execution Loop Structure below for the full subtask/task cadence model. Step headings below indicate cadence explicitly.

Step 2: Gate 0 - Implementation (Per Execution Unit)

Cadence: Runs once per subtask (execution unit = subtask, or task-itself if no subtasks).

REQUIRED SUB-SKILL: Skill("ring:dev-implementation")

Dispatch appropriate frontend agent based on task type. Agent follows TDD (RED then GREEN) with frontend.md standards.

Step 3: Gate 1 - DevOps (Per Task — after all subtasks complete 0/3/8)

⛔ CADENCE: This gate runs ONCE per task, NOT per subtask. Input implementation_files is the UNION of all subtasks' changed files.

REQUIRED SUB-SKILL: Skill("ring:dev-devops")

Prepare Input (task-level aggregation):

devops_input = {
  unit_id: state.tasks[current_task_index].id,  # TASK id
  implementation_files: [
    ...flatten(state.tasks[current_task_index].subtasks.map(st =>
      st.gate_progress.implementation.files_changed
    ))
  ],
  gate0_handoffs: state.tasks[current_task_index].subtasks.map(st =>
    st.gate_progress.implementation
  ),
  # preserve other fields (language, service_type, ui_library_mode, etc.)
}

Dispatch ring:devops-engineer for Dockerfile, docker-compose, Nginx configuration, and.env.example.

Step 4: Gate 2 - Accessibility (Per Task)

⛔ CADENCE: This gate runs ONCE per task, NOT per subtask. Input implementation_files is the UNION of all subtasks' changed files.

REQUIRED SUB-SKILL: Skill("ring:dev-frontend-accessibility")

Prepare Input (task-level aggregation):

accessibility_input = {
  unit_id: state.tasks[current_task_index].id,  # TASK id
  implementation_files: [
    ...flatten(state.tasks[current_task_index].subtasks.map(st =>
      st.gate_progress.implementation.files_changed
    ))
  ],
  gate0_handoffs: state.tasks[current_task_index].subtasks.map(st =>
    st.gate_progress.implementation
  ),
  # preserve other fields
}

Dispatch ring:qa-analyst-frontend with test_mode="accessibility". MUST verify:

• 0 WCAG 2.1 AA violations (axe-core scan)
• Keyboard navigation works for all interactive elements
• Screen reader announcements are correct
• Focus management is proper
• Color contrast ratios meet AA thresholds

Step 5: Gate 3 - Unit Testing (Per Execution Unit)

Cadence: Runs once per subtask (unchanged). Coverage threshold (85%) applies per subtask.

REQUIRED SUB-SKILL: Skill("ring:dev-unit-testing")

Dispatch ring:qa-analyst-frontend with test_mode="unit". MUST verify:

• Coverage >= 85%
• All acceptance criteria have corresponding tests
• Component rendering, state management, and event handlers tested
• Edge cases covered (empty states, error states, loading states)

Step 6: Gate 4 - Visual Testing (Per Task)

⛔ CADENCE: This gate runs ONCE per task, NOT per subtask. Input implementation_files is the UNION of all subtasks' changed files.

REQUIRED SUB-SKILL: Skill("ring:dev-frontend-visual")

Prepare Input (task-level aggregation):

visual_input = {
  unit_id: state.tasks[current_task_index].id,  # TASK id
  implementation_files: [
    ...flatten(state.tasks[current_task_index].subtasks.map(st =>
      st.gate_progress.implementation.files_changed
    ))
  ],
  gate0_handoffs: state.tasks[current_task_index].subtasks.map(st =>
    st.gate_progress.implementation
  ),
  # preserve other fields
}

Dispatch ring:qa-analyst-frontend with test_mode="visual". MUST verify:

• All component states have snapshots (default, hover, active, disabled, error, loading)
• Responsive breakpoints covered (mobile, tablet, desktop)
• Design system compliance verified
• Visual regression baseline established

Step 7: Gate 5 - E2E Testing (Per Task)

⛔ CADENCE: This gate runs ONCE per task, NOT per subtask. Input implementation_files is the UNION of all subtasks' changed files.

REQUIRED SUB-SKILL: Skill("ring:dev-frontend-e2e")

Prepare Input (task-level aggregation):

e2e_input = {
  unit_id: state.tasks[current_task_index].id,  # TASK id
  implementation_files: [
    ...flatten(state.tasks[current_task_index].subtasks.map(st =>
      st.gate_progress.implementation.files_changed
    ))
  ],
  gate0_handoffs: state.tasks[current_task_index].subtasks.map(st =>
    st.gate_progress.implementation
  ),
  # preserve other fields
}

Dispatch ring:qa-analyst-frontend with test_mode="e2e". MUST verify:

• All user flows tested end-to-end
• Cross-browser: Chromium, Firefox, WebKit
• 3x consecutive stable pass (no flakiness)
• Page object pattern used for maintainability

Step 8: Gate 6 - Performance Testing (Per Task)

⛔ CADENCE: This gate runs ONCE per task, NOT per subtask. Input implementation_files is the UNION of all subtasks' changed files.

REQUIRED SUB-SKILL: Skill("ring:dev-frontend-performance")

Prepare Input (task-level aggregation):

performance_input = {
  unit_id: state.tasks[current_task_index].id,  # TASK id
  implementation_files: [
    ...flatten(state.tasks[current_task_index].subtasks.map(st =>
      st.gate_progress.implementation.files_changed
    ))
  ],
  gate0_handoffs: state.tasks[current_task_index].subtasks.map(st =>
    st.gate_progress.implementation
  ),
  # preserve other fields
}

Dispatch ring:qa-analyst-frontend with test_mode="performance". MUST verify:

• LCP (Largest Contentful Paint) < 2.5s
• CLS (Cumulative Layout Shift) < 0.1
• INP (Interaction to Next Paint) < 200ms
• Lighthouse Performance score >= 90
• Bundle size within budget (if defined in PROJECT_RULES.md)

Step 9: Gate 7 - Code Review (Per Task)

⛔ CADENCE: This gate runs ONCE per task, NOT per subtask. Input implementation_files is the UNION of all subtasks' changed files. Reviewers see CUMULATIVE diff of all subtasks; cross-subtask bugs more visible.

REQUIRED SUB-SKILL: Skill("ring:codereview")

Prepare Input (task-level aggregation):

review_input = {
  unit_id: state.tasks[current_task_index].id,  # TASK id
  implementation_files: [
    ...flatten(state.tasks[current_task_index].subtasks.map(st =>
      st.gate_progress.implementation.files_changed
    ))
  ],
  gate0_handoffs: state.tasks[current_task_index].subtasks.map(st =>
    st.gate_progress.implementation
  ),
  # preserve other fields
}

Dispatch all 5 reviewers in parallel (see Gate 7: Code Review Adaptation above).

Step 10: Gate 8 - Validation (Per Execution Unit)

Cadence: Runs once per subtask (unchanged). User approval is per subtask.

REQUIRED SUB-SKILL: Skill("ring:dev-validation")

Present implementation summary to user. Require explicit "APPROVED" response. "Looks good" or silence ≠ approved.

Execution Report

Base metrics per shared-patterns/output-execution-report.md:

Frontend-Specific Metrics

Pressure Resistance

See shared-patterns/shared-pressure-resistance.md for universal pressure scenarios.

Frontend-specific pressure scenarios:

Gate-specific note: Execution mode selection affects CHECKPOINTS (user approval pauses), not GATES (quality checks). All gates execute regardless of mode.

Common Rationalizations - REJECTED

See shared-patterns/shared-anti-rationalization.md for universal anti-rationalizations.

Frontend-specific rationalizations:

Red Flags - STOP

See shared-patterns/shared-red-flags.md for universal red flags.

Frontend-specific red flags:

• "Skip accessibility, we'll add ARIA labels later"
• "Only test happy path in E2E"
• "Performance optimization is a separate ticket"
• "Visual tests will be added when design stabilizes"
• "The designer didn't provide mobile mockups, skip responsive"
• "This browser doesn't matter for our users"
• "It works in Chromium, ship it"

If you catch yourself thinking any of those patterns, STOP immediately and return to gate execution.

Incremental Compromise Prevention

The "just this once" pattern leads to complete gate erosion:

Day 1: "Skip accessibility just this once" -> Approved (precedent set)
Day 2: "Skip visual tests, we did it last time" -> Approved (precedent extended)
Day 3: "Skip performance, pattern established" -> Approved (gates meaningless)
Day 4: Production incident: inaccessible UI + layout regression + 5s load time

Prevention rules:

1. No incremental exceptions - Each exception becomes the new baseline
2. Document every pressure - Log who requested, why, outcome
3. Escalate patterns - If same pressure repeats, escalate to team lead
4. Gates are binary - Complete or incomplete. No "mostly done".

Input Validation

Task files are generated by /ring:pre-dev-* or backend handoff. The ring:dev-cycle-frontend performs basic format checks:

Format Checks