R2 Dev Page

r2-dev-page

Generate frontend page code from requirements. Frontend only - no backend code.

Role

Frontend Developer - Generate production-ready page code and API client integration only.

Scope

✅ Frontend Development:

• UI components (framework-specific)
• State management (hooks/composables/signals)
• API client (HTTP calls to backend)
• Type definitions (from API schemas)
• Frontend validation
• Error handling and loading states

❌ NOT in Scope:

• Backend API implementation
• Database operations
• Server-side logic
• API route handlers
• Authentication middleware
• Business logic on server

Input

• requirement.page.md - Page requirements (primary, Section 4 for APIs)
• page.yaml - Lifecycle configuration (6 phases)
• requirement.module.md - Module context (parent)
• metadata.yaml - Module configuration
• api.yaml - Module APIs (generated by extract-api.py, if exists)
• schemas.yaml - Module schemas (generated by extract-schema.py, if exists)
• {PROJECT_ROOT}/.r2mo/requirements/project.md - Tech stack definition
• {PROJECT_ROOT}/.r2mo/api/metadata.yaml - Full API definitions (fallback)
• {PROJECT_ROOT}/.r2mo/api/components/schemas/*.md - Data models (fallback)
• {PROJECT_ROOT}/.r2mo/domain/*.proto - Domain models (fallback)
• {PROJECT_ROOT}/.r2mo/design/spec.md - UI specs (optional)
• {PROJECT_ROOT}/.r2mo/api/marker.md - Validation rules (optional)

Output

7 file types (structure depends on detected tech stack):

• Component file
• State management (hook/composable/store)
• API service client (HTTP client only)
• Type definitions
• Constants and enums
• Styles
• Tests

Built-in Tool: extract-api.py

Purpose: Extract module-specific APIs from large OpenAPI metadata.yaml

Location: {SKILL_ROOT}/scripts/extract-api.py

• {SKILL_ROOT} resolves from skill repository or installation path
• Script location depends on how skill is installed/integrated

When to Use:

• Module has > 10 APIs in metadata.yaml
• Need to focus on specific API patterns
• Want faster code generation
• Clear module API boundaries

Usage:

cd {module-dir}

# Locate script from skill root
python {SKILL_ROOT}/scripts/extract-api.py -m {pattern} -o api.yaml

# Example patterns from metadata.yaml api.match
python {SKILL_ROOT}/scripts/extract-api.py -m user -m role -o api.yaml

Output: api.yaml in module directory

• Contains only matched APIs
• Includes referenced schemas automatically
• Smaller file size for AI processing

Built-in Tool: extract-schema.py

Purpose: Extract module-specific data models from schemas and domain definitions

Location: {SKILL_ROOT}/scripts/extract-schema.py

• {SKILL_ROOT} resolves from skill repository or installation path
• Script location depends on how skill is installed/integrated

When to Use:

• Module has > 10 schemas in .r2mo/api/components/schemas/
• Need to focus on specific data models
• Want faster type generation
• Clear module data model boundaries

Usage:

cd {module-dir}

# Locate script from skill root
python {SKILL_ROOT}/scripts/extract-schema.py -m {pattern} -o schemas.yaml

# Example patterns from metadata.yaml schema.match
python {SKILL_ROOT}/scripts/extract-schema.py -m user -m role -o schemas.yaml

Output: schemas.yaml in module directory

• Contains matched Markdown schemas from .r2mo/api/components/schemas/
• Contains matched Proto files from .r2mo/domain/
• Organized by schema name
• Smaller file size for AI processing

Combined Usage:

cd {module-dir}

# Extract both APIs and Schemas
python {SKILL_ROOT}/scripts/extract-api.py -m {pattern} -o api.yaml
python {SKILL_ROOT}/scripts/extract-schema.py -m {pattern} -o schemas.yaml

Process

0. Data Extraction (Optional but Recommended)

When to execute:

• Module has > 10 APIs or > 10 schemas
• metadata.yaml or schemas directory is large
• Need focused scope for code generation

How to execute:

cd {module-dir}

# Read metadata.yaml api.match and schema.match patterns

# Extract APIs (optional)
python {SKILL_ROOT}/scripts/extract-api.py -m {pattern1} -m {pattern2} -o api.yaml

# Extract Schemas (optional)
python {SKILL_ROOT}/scripts/extract-schema.py -m {pattern1} -m {pattern2} -o schemas.yaml

# Verify outputs
ls -lh api.yaml schemas.yaml

Result:

• api.yaml: Module-specific APIs
• schemas.yaml: Module-specific data models

0. API Extraction (Optional but Recommended)

When to execute:

• Module has > 10 APIs
• metadata.yaml > 1MB
• Need focused API scope

How to execute:

cd {module-dir}

# Read metadata.yaml api.match patterns
# Execute: python {SKILL_ROOT}/scripts/extract-api.py -m {pattern1} -m {pattern2} -o api.yaml

# Verify output
# Check: api.yaml exists and is smaller than metadata.yaml

Result: api.yaml created in module directory with module-specific APIs

1. Detect Tech Stack

Read: {PROJECT_ROOT}/.r2mo/requirements/project.md
Extract:
  - frontend_framework (required)
  - ui_library (required)
  - state_management (required)
  - language (required)
  - build_tool (required)
  - http_client (required)
  - test_framework (required)

Validate: All required fields present
Fallback: ERROR if tech stack not defined - cannot proceed

Critical: Tech stack MUST be defined in project.md. No assumptions.

2. Load Specifications

Read: requirement.page.md (8 sections)
  - Section 3: Data models (entities)
  - Section 4: API operations (endpoints, methods)
  - Section 5: Page components
  - Section 6: Form fields (if applicable)
  - Section 7: Permissions
  - Section 8: Lifecycle phases

Read: page.yaml (6 lifecycle phases)
  - init, query, action, validate, event, cleanup

Check: change_history field
  - Empty: Mode 1 (0-1 complete generation)
  - Not empty: Mode 2 (1-1.1 incremental update)

3. Load API Context (Priority Order)

Priority 1: api.yaml in module directory
  - If exists: Use this (generated by extract-api.py)

Priority 2: {PROJECT_ROOT}/.r2mo/api/metadata.yaml
  - Fallback to full API definitions

Parse from chosen source:
  - API endpoints from requirement.page.md Section 4
  - HTTP methods (GET/POST/PUT/DELETE/PATCH)
  - Request schemas
  - Response schemas
  - Error responses

Critical: Use API paths from requirement.page.md Section 4 exactly
  - DO NOT create new paths
  - DO NOT modify paths
  - DO NOT design paths

4. Load Data Models (Priority Order)

Priority 1: schemas.yaml in module directory
  - If exists: Use this (generated by extract-schema.py)

Priority 2: {PROJECT_ROOT}/.r2mo/api/components/schemas/*.md
  - Fallback to full schema definitions (Markdown format)

Priority 3: {PROJECT_ROOT}/.r2mo/domain/*.proto
  - Fallback to domain models (Proto format)

Parse from chosen source:
  - Entities from requirement.page.md Section 3
  - Entity structures
  - Field types
  - Field constraints
  - Relationships

Purpose: Generate type definitions for frontend

5. Generate Frontend Code Files

Mode 1 (0-1 Complete): Generate all 7 file types Mode 2 (1-1.1 Update): Generate modified files only (based on change_history)

File Structure: Based on detected tech stack from project.md

• Use tech stack conventions
• Follow framework patterns
• Respect project structure

Content Generation Rules:

1. Component File

   • Based on page_type from requirement.page.md (list/form/detail/dashboard)
   • Implement 6 lifecycle phases from page.yaml
   • Use UI library components from project.md
   • Responsive design from design/spec.md

2. State Management

   • Implement 6 lifecycle phases:
     • init: Permission check, data loading, dict loading
     • query: Search validation, API call, render
     • action: CRUD operations from Section 4 APIs
     • validate: Field rules from Section 6, business rules
     • event: User interactions
     • cleanup: Cancel requests, clear listeners
   • Use state management pattern from project.md

3. API Service Client ← CRITICAL: Frontend HTTP client ONLY

   • Generate method for each API from requirement.page.md Section 4
   • Use http_client from project.md (axios/fetch/etc)
   • Use API paths from Section 4 exactly (DO NOT create/modify)
   • Include request/response types
   • Error handling and transformation
   • Loading state management

   // Example structure (NOT actual code)
   function callAPI(endpoint, method, params) {
     // HTTP call to backend
     // Error handling
     // Return typed response
   }
   

4. Type Definitions

   • From schemas/*.md (Section 3 entities)
   • Query/Filter types
   • Request/Response types
   • Error types
   • Use language from project.md (TypeScript/Flow/JSDoc/etc)

5. Constants

   • Status enums from data models
   • Validation rules from Section 6 + marker.md
   • Error messages (Chinese)
   • Page size options
   • Config values

6. Styles

   • From design/spec.md
   • Responsive design
   • Framework-specific styling approach
   • Component styles

7. Tests

   • Use test_framework from project.md
   • State management tests
   • API client tests (mock HTTP)
   • Component tests (if applicable)

Rules

1. Frontend only - Generate UI and API client, NO backend implementation
2. Use existing APIs - API paths from requirement.page.md Section 4, DO NOT create
3. Follow tech stack - Use framework from project.md, NO assumptions
4. Chinese comments - Code comments in Chinese, variables in English
5. Type safe - Use type system properly
6. Error handling - Comprehensive client-side error handling
7. Follow lifecycle - Implement all 6 phases from page.yaml
8. Production ready - Include tests, error handling, loading states
9. API client only - HTTP calls to backend, not API implementation
10. No assumptions - If tech stack undefined, ERROR - do not proceed

API Integration Guidelines

✅ DO Generate (Frontend HTTP Client):

• HTTP client methods using http_client from project.md
• Request parameter types
• Response data types
• Error handling and transformation
• Loading state management
• Retry logic (frontend)
• Request cancellation

❌ DO NOT Generate (Backend Implementation):

• API route handlers
• Database queries
• Business logic on server
• Authentication middleware
• API route definitions
• Server-side validation
• Backend error handling

Example Structure (Conceptual):

From requirement.page.md Section 4:

| 操作 | 端点 | 方法 | 说明 |
| 查询列表 | /api/users | GET | 获取用户列表 |

Generate (Frontend client structure):

HTTP Client Method:
  - Function: fetch user list
  - Endpoint: /api/users (from Section 4)
  - Method: GET
  - Request: Query parameters (typed)
  - Response: User list (typed)
  - Error: Handle and transform

DO NOT Generate (Backend):

Backend route handler
Database query
Business logic
Authentication check

Validation

• Tech stack detected from project.md (all required fields)
• All 7 file types generated (Mode 1) or modified files (Mode 2)
• 6 lifecycle phases implemented
• API client code only (no backend implementation)
• API paths from requirement.page.md Section 4 (not created/modified)
• Types from schemas/*.md
• Validation rules from Section 6 + marker.md
• Chinese comments, English code
• Code follows tech stack conventions
• Compiles without errors
• Tests pass
• No backend route handlers generated
• No assumptions about tech stack

Context Paths Reference

Page Directory: {page-dir}
├── requirement.page.md              ← Primary input (Section 4: API operations)
├── page.yaml                        ← Lifecycle config (6 phases)
└── src/                             ← Generated code output
│
Module Directory: {module-dir}
├── requirement.module.md            ← Module context
├── metadata.yaml                    ← Module config (api.match, schema.match patterns)
├── api.yaml                         ← Extracted APIs (optional, by extract-api.py)
└── schemas.yaml                     ← Extracted schemas (optional, by extract-schema.py)
│
Project Root: {PROJECT_ROOT}/.r2mo/
├── requirements/project.md          ← Tech stack definition (REQUIRED)
├── api/
│   ├── metadata.yaml               ← Full API definitions (fallback)
│   ├── operations/**/*.md          ← API operations (reference only)
│   ├── components/schemas/*.md     ← Data models (fallback)
│   └── marker.md                   ← Validation rules
├── domain/*.proto                  ← Domain models (fallback)
└── design/spec.md                  ← UI/UX specs (optional)
│
Skill Root: {SKILL_ROOT}
└── scripts/
    ├── extract-api.py               ← API extraction tool
    └── extract-schema.py            ← Schema extraction tool

Tool Path Resolution

Built-in tools location:

• {SKILL_ROOT}/scripts/extract-api.py - API extraction
• {SKILL_ROOT}/scripts/extract-schema.py - Schema extraction
• {SKILL_ROOT} is resolved from skill installation location
• User must locate scripts based on their setup

Usage in different projects:

# Project A
cd /project-a/modules/user
python {path-to-skill}/scripts/extract-api.py -m user -o api.yaml
python {path-to-skill}/scripts/extract-schema.py -m user -o schemas.yaml

# Project B
cd /project-b/modules/order
python {path-to-skill}/scripts/extract-api.py -m order -o api.yaml
python {path-to-skill}/scripts/extract-schema.py -m order -o schemas.yaml

Success Criteria

• All files generated and compile successfully
• Tech stack from project.md applied correctly
• 6 lifecycle phases implemented correctly
• API client integrates with backend (HTTP calls only)
• API paths match requirement.page.md Section 4 exactly
• Types match schemas/*.md
• Validation rules applied
• Production-ready frontend code
• NO backend implementation generated
• NO tech stack assumptions made
• Ready for backend integration

Converted and distributed by TomeVault — claim your Tome and manage your conversions.