Frontend From Backend

Write Frontend Spec From Backend Skill

Version: 1.0 Created: 2026-02-07 Author: Manus AI Purpose: To provide a structured, repeatable process for writing high-quality frontend specifications that are deeply integrated with an existing backend, ensuring seamless development and reducing integration friction.

I. The Philosophy: Grounding Before Building

Frontend development in a full-stack application does not happen in a vacuum. The most common source of bugs, delays, and rework is a disconnect between the frontend implementation and the backend reality. This skill is built on a simple but powerful principle: grounding before building.

By deeply understanding the existing backend architecture, APIs, and data models before writing a single line of frontend specification, we can prevent entire classes of integration problems. This process transforms specification writing from a creative exercise into a disciplined engineering practice, ensuring that what we design is not just beautiful, but buildable.

II. When to Use This Skill

• When planning a new frontend feature that will interact with an existing backend.
• When writing specifications for a UI redesign of a feature that has a backend component.
• When commissioning frontend work to an autonomous agent like Claude Code, Zenflow, or other implementation agents.
• When you feel a disconnect between the frontend vision and the backend reality.
• At the beginning of any major frontend development cycle.

III. The Workflow

This workflow is a 5-step process that takes you from a high-level feature idea to a production-ready, backend-grounded specification.

Step 1: Deep Backend Analysis

Goal: Achieve a comprehensive understanding of the existing backend architecture.

1. Run /repo-context-sync: Generate a comprehensive context map of the repository.
2. Read Key Backend Files:
   • main.go (or equivalent): Understand route registration and server setup.
   • handlers/: Read the handlers for the relevant feature areas.
   • middleware/: Understand the authentication and request lifecycle.
3. Document APIs: Map all relevant API endpoints, including methods, authentication requirements, request bodies, and success/error responses.
4. Identify Integration Points: For each part of the new frontend feature, identify the specific backend endpoint it will interact with.

Step 2: Comprehensive Feature Specification

Goal: Write a production-ready specification for the new feature that leverages the existing backend.

1. Write a Full Feature Spec: Create a detailed document covering:
   • Executive summary and problem statement
   • Goals, non-goals, and user stories
   • Technical architecture (how frontend and backend will interact)
   • UI/UX wireframes and interaction flows
   • API contracts with request/response examples
   • Implementation plan (if multi-phased)
   • Security considerations
2. Leverage Existing Backend: Design the feature to use existing backend infrastructure wherever possible. Avoid proposing new backend features unless absolutely necessary.

Step 3: Integration Guide Creation

Goal: Create a practical guide for developers on how to wire the new frontend to the backend.

1. Create a Track-by-Track Guide: If the feature is being built in parallel tracks, create a guide for each track.
2. Document Authentication Flow: Explain how the frontend should handle authentication (guest mode, API key mode, cloud sync).
3. Explain Streaming Architecture: If the feature uses streaming, document the SSE or WebSocket connection and event handling.
4. Provide Code Examples: Include frontend code snippets for making API calls.
5. Document Error Handling: Specify how the frontend should handle different backend error codes.

Step 4: Track Prompt Enhancement

Goal: Update all development prompts (e.g., for implementation agents like Zenflow or Claude Code) with backend grounding.

1. Add a "Backend Grounding" Section: In each prompt, add a dedicated section that explains the backend context.
2. Document Specific Endpoints: For each part of the implementation, specify the exact API endpoint to use.
3. Reference the Integration Guide: Link to the full integration guide for more details.
4. Ensure Prompts Use Existing Patterns: Explicitly instruct the development agent to follow existing backend patterns.

Step 5: Audit and Deliver

Goal: Ensure all documentation is complete, consistent, and ready for commissioning.

1. Run a Final Audit: Review all documents for gaps, inconsistencies, or missing information.
2. Write Missing Documentation: If any gaps are found (e.g., design system, API contracts), write the missing documents.
3. Push to Repository: Commit all documentation to a dedicated directory (e.g., docs/vX.X.X/).
4. Confirm Readiness: Announce that the specifications are complete and ready for commissioning.

IV. Best Practices

• No Backend Changes is the Goal: The primary goal of this process is to build a frontend that works with the existing backend. Only propose backend changes as a last resort.
• The Backend is the Source of Truth: If there is a discrepancy between the frontend design and the backend API, the backend API is correct. The frontend design must adapt.
• Over-Document the Integration: It is better to provide too much detail on how the frontend and backend should connect than too little.
• Use this Skill Before Writing Code: This process should be completed before any significant frontend development begins.

V. Quality Checklist

Before commissioning the work, ensure you can answer "yes" to all of the following questions:

• Have you read the main entrypoint of the backend application?
• Have you read the handlers for all relevant API endpoints?
• Have you written a comprehensive feature specification that includes API contracts?
• Have you created a backend integration guide with code examples?
• Have all development prompts been updated with a "Backend Grounding" section?
• Have you audited all documentation for completeness and pushed it to the repository?

Output

• A frontend feature specification document grounded in actual backend endpoints and data models (saved to docs/vX.X.X/frontend_spec.md)
• A backend integration guide with code examples for each API call the frontend makes
• Updated implementation prompts for all affected tracks, each containing a "Backend Grounding" section
• An audit summary confirming no new backend routes are required

Examples

Scenario 1: "We have a working Go API and need to spec the settings page for it." → A feature spec mapping each settings field to the exact backend endpoint, with TypeScript fetch examples and error-handling patterns drawn from the actual handler code.

Scenario 2: "The agent keeps building frontend that doesn't match the API." → A backend integration guide extracted from handlers/ and middleware/, then injected into each track prompt so agents reference real endpoint signatures instead of assumptions.

Edge Cases

• When the backend has not been built yet, this skill should not be invoked — use specification-writer to design both layers together instead
• When backend APIs are behind an authentication layer, document the full auth handshake in the integration guide before speccing any authenticated endpoints
• When the backend uses streaming (SSE or WebSocket), add a dedicated "Streaming Architecture" section; generic fetch patterns are not sufficient

Anti-Patterns

• Proposing new backend endpoints inside a frontend spec — the goal is to build a frontend against the existing backend; backend changes belong in a separate release spec
• Writing frontend specs from API documentation instead of reading actual handler code — docs drift; the handler is ground truth
• Skipping the integration guide and embedding API details only in the track prompt — the guide is the canonical reference; prompts should link to it, not duplicate it inline