菜单
Frontend development cycle orchestrator with 9 gates. Loads tasks from PM team output or backend handoff and executes through implementation → devops → accessibility → unit testing → visual testing → E2E testing → performance testing → review → validation.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Main orchestrator for the 8-gate development cycle system. Loads tasks/subtasks from PM team output and executes through implementation → devops → SRE → unit testing → integration testing (write) → chaos testing (write) → review → validation gates (Gates 0-7), with state persistence and metrics collection. Gates 4-5 (integration/chaos) write and update test code per unit but only execute tests at end of cycle (deferred execution). Multi-tenant dual-mode is implemented during Gate 0 and verified at Gate 0.5G (no separate post-cycle step).
Gate 3 of development cycle - ensures unit test coverage meets threshold (85%+) for all acceptance criteria using TDD methodology.
Gate 5 of development cycle - ensures chaos tests exist using Toxiproxy to verify graceful degradation under connection loss, latency, and partitions.
Gate 1 of the development cycle. Creates/updates Docker configuration, docker-compose setup, and environment variables for local development and deployment readiness.
Gate 4 of development cycle - ensures integration tests pass for all external dependency interactions using real containers via testcontainers.
Gate 4 of development cycle - dispatches 7 specialized reviewers (code, business-logic, security, test, nil-safety, consequences, dead-code) in parallel for comprehensive code review feedback.
| name | marsai:dev-cycle-frontend |
| description | Frontend development cycle orchestrator with 9 gates. Loads tasks from PM team output or backend handoff and executes through implementation → devops → accessibility → unit testing → visual testing → E2E testing → performance testing → review → validation. |
| trigger | - Starting a new frontend development cycle with a task file - Resuming an interrupted frontend development cycle (--resume flag) - After backend dev cycle completes (consuming handoff) |
| prerequisites | - Tasks file exists with structured subtasks - Not already in a specific gate skill execution |
| skip_when | - "Task is simple" → Simple ≠ risk-free. Execute gates. - "Tests already pass" → Tests ≠ review. Different concerns. - "Backend already tested this" → Frontend has different quality concerns. |
| sequence | {"before":["marsai:dev-feedback-loop"]} |
| related | {"complementary":["marsai:dev-frontend-accessibility","marsai:dev-unit-testing","marsai:dev-frontend-visual","marsai:dev-frontend-e2e","marsai:dev-frontend-performance","marsai:requesting-code-review","marsai:dev-validation","marsai:dev-feedback-loop"]} |
| verification | {"automated":[{"command":"test -f docs/marsai:dev-cycle-frontend/current-cycle.json","description":"State file exists","success_pattern":"exit 0"}],"manual":["All gates for current task show PASS in state file"]} |
Before any gate execution, you MUST load MarsAI standards:
<fetch_required> https://raw.githubusercontent.com/V4-Company/marsai/main/CLAUDE.md https://raw.githubusercontent.com/V4-Company/marsai/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>
If any condition is true, STOP and report blocker. Cannot proceed without MarsAI standards.
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):
Unlike the backend marsai: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 marsai:dev-cycle-frontend skill to orchestrate frontend task execution through 9 gates (Gate 0-8). All gates execute per unit."
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.
This section defines exactly what the orchestrator CAN and CANNOT do.
| Action | Tool | Purpose |
|---|---|---|
| Read task files | Read | Load task definitions from docs/pre-dev/*/tasks-frontend.md or docs/pre-dev/*/tasks.md |
| Read state files | Read | Load/verify docs/marsai:dev-cycle-frontend/current-cycle.json |
| Read PROJECT_RULES.md | Read | Load project-specific rules |
| Read backend handoff | Read | Load docs/marsai:dev-cycle/handoff-frontend.json if available |
| Write state files | Write | Persist cycle state to JSON |
| Track progress | TodoWrite | Maintain task list |
| Dispatch agents | Task | Send work to specialist agents |
| Ask user questions | AskUserQuestion | Get execution mode, approvals |
| WebFetch standards | WebFetch | Load MarsAI standards |
Any of these actions by orchestrator = IMMEDIATE VIOLATION. Dispatch agent instead.
If a task requires editing MORE than 3 files, MUST dispatch specialist agent.
This is not negotiable:
*.ts, *.tsx, *.jsx, *.css) - MUST dispatch agent+------------------------------------------------------------------+
| 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 MarsAI 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) |
| ================================================================ |
+------------------------------------------------------------------+
Before any gate execution, detect the project's UI library configuration:
Read tool: package.json
Parse the JSON content:
- If "dependencies" or "devDependencies" contains "@V4-Company/sindarian-ui"
→ ui_library_mode = "sindarian-ui"
- Otherwise
→ ui_library_mode = "fallback-only"
Store result in state file under ui_library_mode.
@V4-Company/sindarian-ui is PRIMARY. shadcn/ui + Radix is FALLBACK for missing components.
| Mode | Meaning | Agent Behavior |
|---|---|---|
sindarian-ui | Sindarian UI detected in package.json | Use Sindarian components first, shadcn/ui only for gaps |
fallback-only | No Sindarian UI detected | Use shadcn/ui + Radix as primary component library |
Anti-Rationalization for UI Library Mode:
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Skip detection, just use shadcn" | Project may have Sindarian UI. Skipping = wrong components. | MUST detect before Gate 0 |
| "Mode doesn't matter for this task" | Mode affects every component decision in Gate 0. | MUST detect and store in state |
If the frontend cycle follows a backend marsai:dev-cycle, load the handoff file:
Check: Does docs/marsai: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.
Before dispatching any agent, you MUST load the corresponding sub-skill first.
<cannot_skip>
Skill("marsai:dev-implementation") → then Task(subagent_type="marsai:frontend-engineer" or "marsai:ui-engineer" or "marsai:frontend-bff-engineer-typescript")Skill("marsai:dev-devops") → then Task(subagent_type="marsai:devops-engineer")Skill("marsai:dev-frontend-accessibility") → then Task(subagent_type="marsai:qa-analyst-frontend", test_mode="accessibility")Skill("marsai:dev-unit-testing") → then Task(subagent_type="marsai:qa-analyst-frontend", test_mode="unit")Skill("marsai:dev-frontend-visual") → then Task(subagent_type="marsai:qa-analyst-frontend", test_mode="visual")Skill("marsai:dev-frontend-e2e") → then Task(subagent_type="marsai:qa-analyst-frontend", test_mode="e2e")Skill("marsai:dev-frontend-performance") → then Task(subagent_type="marsai:qa-analyst-frontend", test_mode="performance")Skill("marsai:requesting-code-review") → then 5x Task(...) in parallelSkill("marsai: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
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: "marsai:frontend-engineer"
prompt: |
**CUSTOM CONTEXT (from user):**
{state.custom_prompt}
---
**Standard Instructions:**
[... rest of agent prompt ...]
Rules for custom prompt:
custom_prompt from state file and inject into their agent dispatches (no explicit parameter passing needed)Example custom prompts and their effect:
| Custom Prompt | Effect on Agents |
|---|---|
| "Use dark mode as default theme" | Agents implement dark mode first, light as secondary |
| "Focus on mobile-first responsive design" | Gate 4 visual tests prioritize mobile breakpoints |
| "Integrate with existing auth context from backend" | Gate 0 uses backend handoff auth pattern |
| "Prioritize accessibility over animations" | Gate 2 gets more attention, animations simplified |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "I know what the sub-skill does" | Knowledge ≠ execution. Sub-skill has iteration logic. | Load Skill() first |
| "Task() directly is faster" | Faster ≠ correct. Sub-skill has validation rules. | Load Skill() first |
| "Sub-skill just wraps Task()" | Sub-skills have retry logic, fix dispatch, validation. | Load Skill() first |
| "I'll follow the pattern manually" | Manual = error-prone. Sub-skill is the pattern. | Load Skill() first |
Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "It's just one small component" | File count doesn't determine agent need. Standards do. | DISPATCH specialist agent |
| "I already loaded the standards" | Loading standards ≠ permission to implement. Standards are for AGENTS. | DISPATCH specialist agent |
| "Agent dispatch adds overhead" | Overhead ensures compliance. Skip = skip verification. | DISPATCH specialist agent |
| "I can write React/TypeScript" | Knowing framework ≠ having MarsAI standards loaded. Agent has them. | DISPATCH specialist agent |
| "Just a quick CSS fix" | "Quick" is irrelevant. All source changes require specialist. | DISPATCH specialist agent |
| "I'll read the component first to understand" | Reading source = temptation to edit. Agent reads for you. | DISPATCH specialist agent |
| "Let me check if tests pass first" | Agent runs tests in TDD cycle. You don't run tests. | DISPATCH specialist agent |
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.
If you violated orchestrator boundaries:
git checkout -- .)Sunk cost of direct work is IRRELEVANT. Agent dispatch is MANDATORY.
<block_condition>
You CANNOT proceed when blocked. Report and wait for resolution.
<cannot_skip>
No exceptions. User cannot override. Time pressure cannot override.
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Blocks deployment, accessibility violation, security risk | Gate violation, WCAG AA failure, XSS vulnerability |
| HIGH | Major functionality broken, standards violation | Missing tests, wrong agent dispatched, performance regression |
| MEDIUM | Code quality, maintainability issues | Incomplete documentation, minor gaps, non-ideal patterns |
| LOW | Best practices, optimization | Style improvements, minor refactoring, cosmetic issues |
Report all severities. Let user prioritize.
MEDIUM issues found in Gate 7 MUST be fixed. No exceptions.
| Request | Why It's WRONG | Required Action |
|---|---|---|
| "Can reviewer clarify if MEDIUM can defer?" | Reviewer already decided. MEDIUM means FIX. | Fix the issue, re-run reviewers |
| "Ask if this specific case is different" | Reviewer verdict accounts for context already. | Fix the issue, re-run reviewers |
| "Request exception for business reasons" | Reviewers know business context. Verdict is final. | Fix the issue, re-run reviewers |
Severity mapping is absolute:
No negotiation. No exceptions. No "special cases".
| Gate | Skill | Purpose | Agent | Standards Module |
|---|---|---|---|---|
| 0 | marsai:dev-implementation | Write code following TDD | marsai:frontend-engineer / marsai:ui-engineer / marsai:frontend-bff-engineer-typescript | frontend.md |
| 1 | marsai:dev-devops | Docker/compose/Nginx setup | marsai:devops-engineer | devops.md |
| 2 | marsai:dev-frontend-accessibility | WCAG 2.1 AA compliance | marsai:qa-analyst-frontend (test_mode: accessibility) | testing-accessibility.md |
| 3 | marsai:dev-unit-testing | Unit tests 85%+ coverage | marsai:qa-analyst-frontend (test_mode: unit) | frontend.md |
| 4 | marsai:dev-frontend-visual | Snapshot/visual regression tests | marsai:qa-analyst-frontend (test_mode: visual) | testing-visual.md |
| 5 | marsai:dev-frontend-e2e | E2E tests with Playwright | marsai:qa-analyst-frontend (test_mode: e2e) | testing-e2e.md |
| 6 | marsai:dev-frontend-performance | Core Web Vitals + Lighthouse | marsai:qa-analyst-frontend (test_mode: performance) | testing-performance.md |
| 7 | marsai:requesting-code-review | Parallel code review (5 reviewers) | marsai:code-reviewer, marsai:business-logic-reviewer, marsai:security-reviewer, marsai:test-reviewer, marsai:frontend-engineer (review mode) | N/A |
| 8 | marsai:dev-validation | Final acceptance validation | N/A (verification) | N/A |
All gates are MANDATORY. No exceptions. No skip reasons.
| Condition | Agent to Dispatch |
|---|---|
| React/Next.js component implementation | marsai:frontend-engineer |
| Design system / Sindarian UI component | marsai:ui-engineer |
| BFF / API aggregation layer | marsai:frontend-bff-engineer-typescript |
| Mixed (component + BFF) | Dispatch marsai:frontend-engineer first, then marsai:frontend-bff-engineer-typescript |
UI library mode (detected in Step 0) MUST be passed to the agent as context.
TDD (RED→GREEN) applies to behavioral logic. Visual/presentational components use test-after.
| Component Layer | TDD Required? | Where Tests Are Created | Rationale |
|---|---|---|---|
| Custom hooks | YES - TDD RED→GREEN | Gate 0 (implementation) | Test defines the hook contract before code |
| Form validation | YES - TDD RED→GREEN | Gate 0 (implementation) | Test defines validation rules before code |
| State management | YES - TDD RED→GREEN | Gate 0 (implementation) | Test defines state transitions before code |
| Conditional rendering | YES - TDD RED→GREEN | Gate 0 (implementation) | Test defines when elements show/hide |
| API integration / data fetching | YES - TDD RED→GREEN | Gate 0 (implementation) | Test defines expected request/response |
| Layout / styling | NO - test-after | Gate 4 (visual testing) | Visual output is exploratory; snapshot locks it |
| Animations / transitions | NO - test-after | Gate 4 (visual testing) | Motion is iterative; test captures final state |
| Static presentational components | NO - test-after | Gate 4 (visual testing) | No logic to drive with RED phase |
Rules:
Anti-Rationalization:
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "This hook is simple, skip TDD" | Simple hooks still need contract verification. | TDD RED→GREEN for all hooks |
| "Form validation is visual" | Validation rules are logic, not presentation. | TDD RED→GREEN for validation |
| "This component has onClick, skip TDD" | Event handlers contain logic. TDD for the handler behavior. | TDD RED→GREEN for behavioral logic |
| "Layout needs TDD too" | Snapshot test written before layout exists is meaningless. | Test-after in Gate 4 |
| "Skip all tests, Gate 4 handles it" | Gate 4 covers visual snapshots only. Behavioral tests are Gate 0+3. | TDD for behavior in Gate 0 |
For the frontend cycle, the 5 parallel reviewers are:
| # | Reviewer | Focus Area |
|---|---|---|
| 1 | marsai:code-reviewer | Code quality, patterns, maintainability, React best practices |
| 2 | marsai:business-logic-reviewer | Business logic correctness, domain rules, acceptance criteria |
| 3 | marsai:security-reviewer | XSS, CSRF, auth handling, sensitive data exposure, CSP |
| 4 | marsai:test-reviewer | Test quality, coverage gaps, test patterns, assertion quality |
| 5 | marsai:frontend-engineer (review mode) | Accessibility compliance, frontend standards, component architecture |
NOTE: The 5th reviewer slot uses marsai:frontend-engineer in review mode instead of marsai:nil-safety-reviewer. 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: "marsai:code-reviewer", ... }
Task 2: { subagent_type: "marsai:business-logic-reviewer", ... }
Task 3: { subagent_type: "marsai:security-reviewer", ... }
Task 4: { subagent_type: "marsai:test-reviewer", ... }
Task 5: { subagent_type: "marsai:frontend-engineer", prompt: "REVIEW MODE: Review accessibility compliance and frontend standards adherence...", ... }
A gate is COMPLETE only when all components finish successfully:
| Gate | Components Required | Partial = FAIL |
|---|---|---|
| 0.1 | TDD-RED: Failing test written + failure output captured (behavioral components only - see Frontend TDD Policy) | Test exists but no failure output = FAIL. Visual-only components skip to 0.2 |
| 0.2 | TDD-GREEN: Implementation passes test (behavioral) OR implementation complete (visual) | Code exists but test fails = FAIL |
| 0 | Both 0.1 and 0.2 complete (behavioral) OR 0.2 complete (visual - snapshots deferred to Gate 4) | 0.1 done without 0.2 = FAIL |
| 1 | Dockerfile + docker-compose/nginx + .env.example | Missing any = FAIL |
| 2 | 0 WCAG AA violations + keyboard navigation tested + screen reader tested | Any violation = FAIL |
| 3 | Unit test coverage >= 85% + all AC tested | 84% = FAIL |
| 4 | All state snapshots pass + responsive breakpoints covered | Missing snapshots = FAIL |
| 5 | All user flows tested + cross-browser (Chromium, Firefox, WebKit) + 3x stable pass | Flaky = FAIL |
| 6 | LCP < 2.5s + CLS < 0.1 + INP < 200ms + Lighthouse >= 90 | Any threshold missed = FAIL |
| 7 | All 5 reviewers PASS | 4/5 reviewers = FAIL |
| 8 | Explicit "APPROVED" from user | "Looks good" = not approved |
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:
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "4 of 5 reviewers passed" | Gate 7 requires all 5. 4/5 = 0/5. | Re-run all 5 reviewers |
| "Gate mostly complete" | Mostly ≠ complete. Binary: done or not done. | Complete all components |
| "Can finish remaining in next cycle" | Gates don't carry over. Complete NOW. | Finish current gate |
| "No component is optional within a gate" | Every component is required. | Complete all components |
| "Accessibility can be fixed later" | WCAG compliance is mandatory NOW. Later = never. | Fix accessibility in Gate 2 |
| "Visual tests are flaky, skip them" | Fix flakiness, don't skip verification. | Stabilize and pass Gate 4 |
| "Lighthouse score is 88, close enough" | Close enough ≠ passing. Threshold is >= 90. | Optimize until threshold met |
Gates MUST execute in order: 0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8. All 9 gates are MANDATORY.
| Violation | Why It's WRONG | Consequence |
|---|---|---|
| Skip Gate 1 (DevOps) | "No infra changes" | App without container = works on my machine only |
| Skip Gate 2 (Accessibility) | "It's internal tool" | Internal tools MUST be accessible. Legal requirement. |
| Skip Gate 3 (Unit Testing) | "E2E covers it" | E2E is slow, unit tests catch logic bugs faster |
| Skip Gate 4 (Visual) | "Snapshots are brittle" | Fix brittleness, don't skip regression detection |
| Skip Gate 5 (E2E) | "Manual testing done" | Manual testing is not reproducible or automated |
| Skip Gate 6 (Performance) | "Optimize later" | Later = never. Performance budgets apply NOW |
| Reorder Gates | "Review before test" | Reviewing untested code wastes reviewer time |
| Parallel Gates | "Run 2 and 3 together" | Dependencies exist. Order is intentional. |
All testing gates (2-6) are MANDATORY. No exceptions. No skip reasons.
Gates are not parallelizable across different gates. Sequential execution is MANDATORY.
Core Principle: Each execution unit passes through all 9 gates. All gates execute and complete per unit.
Per-Unit Flow: Unit -> Gate 0->1->2->3->4->5->6->7->8 -> Unit Checkpoint -> Task Checkpoint -> Next Unit
| Scenario | Execution Unit | Gates Per Unit |
|---|---|---|
| Task without subtasks | Task itself | 9 gates |
| Task with subtasks | Each subtask | 9 gates per subtask |
User selects when commits happen (during initialization).
| Option | When Commit Happens | Use Case |
|---|---|---|
| (a) Per subtask | After each subtask passes Gate 8 | Fine-grained history, easy rollback per subtask |
| (b) Per task | After all subtasks of a task complete | Logical grouping, one commit per feature chunk |
| (c) At the end | After entire cycle completes | Single commit with all changes, clean history |
| Timing | Message Format | Example |
|---|---|---|
| Per subtask | feat({subtask_id}): {subtask_title} | feat(ST-001-02): implement transaction list component |
| Per task | feat({task_id}): {task_title} | feat(T-001): implement dashboard page |
| At the end | feat({cycle_id}): complete frontend dev cycle for {feature} | feat(cycle-abc123): complete frontend dev cycle for dashboard |
| Execution Mode | Commit Timing | Behavior |
|---|---|---|
| Manual per subtask | Per subtask | Commit + checkpoint after each subtask |
| Manual per subtask | Per task | Checkpoint after subtask, commit after task |
| Manual per subtask | At end | Checkpoint after subtask, commit at cycle end |
| Manual per task | Per subtask | Commit after subtask, checkpoint after task |
| Manual per task | Per task | Commit + checkpoint after task |
| Manual per task | At end | Checkpoint after task, commit at cycle end |
| Automatic | Per subtask | Commit after each subtask, no checkpoints |
| Automatic | Per task | Commit after task, no checkpoints |
| Automatic | At end | Single commit at cycle end, no checkpoints |
Note: Checkpoints (user approval pauses) are controlled by execution_mode. Commits are controlled by commit_timing. They are independent settings.
| Task Source | State Path |
|---|---|
| Any source | docs/marsai:dev-cycle-frontend/current-cycle.json |
State is persisted to docs/marsai:dev-cycle-frontend/current-cycle.json:
{
"version": "1.0.0",
"cycle_id": "uuid",
"started_at": "ISO timestamp",
"updated_at": "ISO timestamp",
"source_file": "path/to/tasks-frontend.md",
"state_path": "docs/marsai:dev-cycle-frontend/current-cycle.json",
"cycle_type": "frontend",
"ui_library_mode": "sindarian-ui | fallback-only",
"backend_handoff": {
"loaded": true,
"source": "docs/marsai: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"
}
],
"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": "marsai: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": "marsai: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": "marsai: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": "marsai: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": "marsai: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": "marsai: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": "marsai: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": "marsai:code-reviewer",
"output": "...",
"verdict": "PASS",
"issues": []
},
"business_logic_reviewer": {
"agent": "marsai:business-logic-reviewer",
"output": "...",
"verdict": "PASS",
"issues": []
},
"security_reviewer": {
"agent": "marsai:security-reviewer",
"output": "...",
"verdict": "PASS",
"issues": []
},
"test_reviewer": {
"agent": "marsai:test-reviewer",
"output": "...",
"verdict": "PASS",
"issues": []
},
"frontend_engineer_reviewer": {
"agent": "marsai:frontend-engineer",
"mode": "review",
"output": "...",
"verdict": "PASS",
"issues": []
}
},
"validation": {
"result": "approved|rejected",
"timestamp": "ISO timestamp"
}
}
}
],
"metrics": {
"total_duration_ms": 0,
"gate_durations": {},
"review_iterations": 0,
"testing_iterations": 0
}
}
Each gate MUST populate its structured fields when saving to state:
| Gate | Fields to Populate |
|---|---|
| Gate 0 (Implementation) | standards_compliance (total, compliant, gaps[]) |
| Gate 1 (DevOps) | standards_compliance + verification_errors[] |
| Gate 2 (Accessibility) | wcag_violations + keyboard_nav_issues + screen_reader_issues |
| Gate 3 (Unit Testing) | standards_compliance + coverage_actual + failures[] |
| Gate 4 (Visual Testing) | snapshots_total + snapshots_passed + responsive_breakpoints_covered[] |
| Gate 5 (E2E Testing) | flows_tested + browsers_tested[] + stability_runs |
| Gate 6 (Performance) | lcp_ms + cls + inp_ms + lighthouse_score |
| Gate 7 (Review) | issues[] per reviewer + verdict per reviewer |
Empty arrays [] indicate no issues found - this is valid data for feedback-loop.
"Update state" means BOTH update the object and write to file. Not just in-memory.
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/marsai:dev-cycle-frontend/current-cycle.json"
content: [full JSON state]
# Step 3: Verify persistence (MANDATORY - use Read tool)
Read tool:
file_path: "docs/marsai:dev-cycle-frontend/current-cycle.json"
# Confirm current_gate and gate_progress match expected values
| After | MUST Update | MUST Write File |
|---|---|---|
| Gate 0.1 (TDD-RED) | tdd_red.status, tdd_red.failure_output | YES |
| Gate 0.2 (TDD-GREEN) | tdd_green.status, implementation.status | YES |
| Gate 1 (DevOps) | devops.status, agent_outputs.devops | YES |
| Gate 2 (Accessibility) | accessibility.status, agent_outputs.accessibility | YES |
| Gate 3 (Unit Testing) | unit_testing.status, agent_outputs.unit_testing | YES |
| Gate 4 (Visual Testing) | visual_testing.status, agent_outputs.visual_testing | YES |
| Gate 5 (E2E Testing) | e2e_testing.status, agent_outputs.e2e_testing | YES |
| Gate 6 (Performance) | performance_testing.status, agent_outputs.performance_testing | YES |
| Gate 7 (Review) | review.status, agent_outputs.review | YES |
| Gate 8 (Validation) | validation.status, task status | YES |
| Unit Approval | status = "paused_for_approval" | YES |
| Task Approval | status = "paused_for_task_approval" | YES |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "I'll save state at the end" | Crash/timeout loses all progress | Save after each gate |
| "State is in memory, that's updated" | Memory is volatile. File is persistent. | Write to JSON file |
| "Only save on checkpoints" | Gates without saves = unrecoverable on resume | Save after every gate |
| "Write tool is slow" | Write takes <100ms. Lost progress takes hours. | Write after every gate |
| "I updated the state variable" | Variable ≠ file. Without Write tool, nothing persists. | Use Write tool explicitly |
User selects checkpoint mode during initialization.
| Mode | Checkpoint Behavior | Gate Behavior |
|---|---|---|
| Manual per subtask | Pause after each subtask completes all 9 gates | All 9 gates execute without pause |
| Manual per task | Pause after all subtasks of a task complete | All 9 gates execute without pause |
| Automatic | No pauses | All 9 gates execute without pause |
CRITICAL: Execution mode affects CHECKPOINTS (user approval pauses), not GATES (quality checks). All gates execute regardless of mode.
Unit Checkpoint (after subtask completes Gate 8):
VISUAL CHANGE REPORT (MANDATORY - before checkpoint question):
Skill("marsai:visual-explainer") to generate a code-diff HTML report for this execution unitdefault/skills/visual-explainer/templates/code-diff.html to absorb the patterns before generatingagent_outputs for the current unit:
tdd_red (failing test) + tdd_green (implementation)git diff data from the implementation (do not read source files directly — use diff output provided by the implementation agent)docs/marsai:dev-cycle-frontend/reports/unit-{unit_id}-report.htmlmacOS: open docs/marsai:dev-cycle-frontend/reports/unit-{unit_id}-report.html
Linux: xdg-open docs/marsai:dev-cycle-frontend/reports/unit-{unit_id}-report.html
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):
Skill("marsai:visual-explainer") to generate an aggregate code-diff HTML report for all subtasksdefault/skills/visual-explainer/templates/code-diff.html to absorb the patterns before generatingdocs/marsai:dev-cycle-frontend/reports/task-{task_id}-report.htmlmacOS: open docs/marsai:dev-cycle-frontend/reports/task-{task_id}-report.html
Linux: xdg-open docs/marsai:dev-cycle-frontend/reports/task-{task_id}-report.html
Task {id} complete. All subtasks passed all gates.
(a) Continue to next task
(b) Pause cycle
(c) Abort cycle
NON-NEGOTIABLE. Cycle CANNOT proceed without project standards.
Same flow as backend marsai: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 marsai: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 /marsai:pre-dev-full or /marsai:pre-dev-feature first"
Input: Direct prompt without a task file path (e.g., /marsai:dev-cycle-frontend Implement dashboard with transaction list)
marsai:codebase-explorer to understand project structureInput: path/to/tasks-frontend.md or path/to/pre-dev/{feature}/ with optional second argument for custom instructions
Examples:
/marsai:dev-cycle-frontend tasks.md/marsai:dev-cycle-frontend tasks.md "Use shadcn/ui components"docs/marsai:dev-cycle/handoff-frontend.json existscommit_timing field in statedocs/marsai:dev-cycle-frontend/current-cycle.json
| Status | Action |
|---|---|
paused_for_approval | Re-present unit checkpoint |
paused_for_task_approval | Re-present task checkpoint |
paused (generic) | Ask user to confirm resume |
in_progress | Resume from current gate |
REQUIRED SUB-SKILL: Skill("marsai:dev-implementation")
Dispatch appropriate frontend agent based on task type. Agent follows TDD (RED then GREEN) with frontend.md standards.
REQUIRED SUB-SKILL: Skill("marsai:dev-devops")
Dispatch marsai:devops-engineer for Dockerfile, docker-compose, Nginx configuration, and .env.example.
REQUIRED SUB-SKILL: Skill("marsai:dev-frontend-accessibility")
Dispatch marsai:qa-analyst-frontend with test_mode="accessibility". MUST verify:
REQUIRED SUB-SKILL: Skill("marsai:dev-unit-testing")
Dispatch marsai:qa-analyst-frontend with test_mode="unit". MUST verify:
REQUIRED SUB-SKILL: Skill("marsai:dev-frontend-visual")
Dispatch marsai:qa-analyst-frontend with test_mode="visual". MUST verify:
REQUIRED SUB-SKILL: Skill("marsai:dev-frontend-e2e")
Dispatch marsai:qa-analyst-frontend with test_mode="e2e". MUST verify:
REQUIRED SUB-SKILL: Skill("marsai:dev-frontend-performance")
Dispatch marsai:qa-analyst-frontend with test_mode="performance". MUST verify:
REQUIRED SUB-SKILL: Skill("marsai:requesting-code-review")
Dispatch all 5 reviewers in parallel (see Gate 7: Code Review Adaptation above).
REQUIRED SUB-SKILL: Skill("marsai:dev-validation")
Present implementation summary to user. Require explicit "APPROVED" response. "Looks good" or silence ≠ approved.
Base metrics per shared-patterns/output-execution-report.md:
| Metric | Value |
|---|---|
| Duration | Xm Ys |
| Iterations | N |
| Result | PASS/FAIL/PARTIAL |
| Metric | Value |
|---|---|
| UI Library Mode | sindarian-ui / fallback-only |
| Backend Handoff | loaded / not found |
| WCAG Violations | 0 |
| Unit Coverage | XX.X% |
| Visual Snapshots | X/Y passed |
| E2E Stability | 3/3 runs |
| LCP | Xms |
| CLS | X.XX |
| INP | Xms |
| Lighthouse | XX |
| Reviewers | 5/5 PASS |
See shared-patterns/shared-pressure-resistance.md for universal pressure scenarios.
Frontend-specific pressure scenarios:
| Pressure Type | Request | Agent Response |
|---|---|---|
| Accessibility | "Skip accessibility, it's an internal tool" | "FORBIDDEN. Internal tools MUST be accessible. WCAG AA is a legal requirement in many jurisdictions. Gate 2 executes fully." |
| Browser Coverage | "Only test Chromium, it's the main browser" | "All 3 browsers (Chromium, Firefox, WebKit) are REQUIRED. Cross-browser issues are the most common production bugs." |
| Performance | "Performance will be optimized later" | "Performance thresholds apply NOW. LCP < 2.5s, CLS < 0.1, INP < 200ms, Lighthouse >= 90. Later = never." |
| Visual Tests | "Snapshots are too brittle to maintain" | "Fix the brittleness (use threshold tolerances), don't skip regression detection. Gate 4 is MANDATORY." |
| Design System | "We'll align with design system later" | "Design system compliance is part of Gate 0. Components MUST use Sindarian UI (or shadcn fallback) from the start." |
Gate-specific note: Execution mode selection affects CHECKPOINTS (user approval pauses), not GATES (quality checks). All gates execute regardless of mode.
See shared-patterns/shared-anti-rationalization.md for universal anti-rationalizations.
Frontend-specific rationalizations:
| Excuse | Reality |
|---|---|
| "Backend already tested this endpoint" | Backend tests verify API logic. Frontend tests verify UI rendering, state management, user interaction, and accessibility. Different concerns entirely. |
| "Accessibility is optional for MVP" | Accessibility is NEVER optional. WCAG AA compliance is mandatory. Building without it means expensive retrofitting later. |
| "Snapshots are brittle and slow down development" | Snapshots catch visual regressions that no other test type detects. Fix brittleness with tolerances, don't skip the gate. |
| "E2E tests are slow, unit tests are enough" | Unit tests verify components in isolation. E2E tests verify user flows end-to-end. Both are MANDATORY because they catch different issues. |
| "Lighthouse score is close enough at 88" | Close enough ≠ passing. Threshold is >= 90. Optimize bundle size, lazy load, compress images until threshold is met. |
| "Automatic mode means faster" | Automatic mode skips CHECKPOINTS, not GATES. Same quality, less interruption. |
| "Only desktop matters, skip mobile testing" | Responsive design is mandatory. Visual tests MUST cover mobile, tablet, and desktop breakpoints. |
| "This component is reused from design system" | Reused components still need tests in context. Integration point testing is required. |
See shared-patterns/shared-red-flags.md for universal red flags.
Frontend-specific red flags:
If you catch yourself thinking any of those patterns, STOP immediately and return to gate execution.
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:
Task files are generated by /marsai:pre-dev-* or backend handoff. The marsai:dev-cycle-frontend performs basic format checks:
| Check | Validation | Action |
|---|---|---|
| File exists | Task file path is readable | Error: abort |
| Task headers | At least one ## Task: found | Error: abort |
| Task ID format | ## Task: {ID} - {Title} | Warning: use line number as ID |
| Acceptance criteria | At least one - [ ] per task | Warning: task may fail validation gate |