program-design

Program Design

When to Use

Phase 4 of the full-stack workflow: after the technical review is approved and before task breakdown.
When the user requests architecture design, module division, or project structure.

Communicate with the user (required)

This phase isexecuted in the main conversation, and key assumptions or alternative options in the design should be confirmed with the user before finalizing.

Interaction Principles

When multiple reasonable options exist, present them as structured choices, and write them in only after the user selects.
Ask no more than 2–3 questions at a time, and continue only after the user replies.
Before finalizing, present a design summary to the user, and produce the complete document only after confirmation.

Structured Confirmation Points

During the design process, the following decision points must be confirmed with the user in the form of options:

C1 — Layering Granularity(if multiple reasonable approaches exist)

A. Standard three layers (Controller / Service / Repository)
B. Add a DTO layer (strict input/output parameter isolation)
C. DDD domain-driven (aggregate root / domain service / repository)
D. Other (please specify)

C2 — Frontend Routing/Page Approach(if multiple reasonable divisions exist)

A. Divide routes by functional module (/orders, /users, /stats)
B. Divide entry points by role (/admin/, /user/）
C. Other

C3 — State Management Strategy(if the frontend involves complex state)

A. Server state as the primary source (refresh on each request, minimal local caching)
B. Client store caching as the primary source (reduce requests, manual synchronization)
C. Hybrid (real-time requests for critical data, caching for lists, etc.)

C4 — Finalization Confirmation

After completing the design draft, present a summary to the user (number of modules, number of interfaces, list of core flows), and produce the complete document only after the user confirms or supplements it.

Input

Read the following from the current iteration directory:

Requirements document (requirements-{id}.md）
Technology selection document (technology-selection-{id}.md）
Technical review document (technical-review-{id}.md) — pay special attention to the API contract and data model.

Execution Points

Module Layering: Divide according to the technology selection (e.g., frontend pages/components, backend controllers/services/repositories, data models).
API Design: Based on the API contract determined in the review, refine the request/response schema.
Data Model: Based on the entity relationships determined in the review, write complete field definitions and draw a Mermaid ER diagram。
Architecture Overview: Use a Mermaid architecture diagram to show the overall relationships among the frontend/backend/database/external services.
Key Flows: 1–3 core business processes; each process must provide a Mermaid flowchart(decision branches) and a Mermaid sequence diagram(call sequence between modules).
Error Handling: Global error code system, frontend error display strategy, backend exception hierarchy.
Project directory: Provide a recommended directory structure, consistent with the technology selection and layering.

Supplementary materials

Complete example output:examples/sample-output.md — Show the complete structure and depth of a qualified design document
Design references:reference.md — Layered architecture reference, state machine design, API patterns, frontend encapsulation patterns, database design considerations

Output

Use templates/design-template.md to produce the design document, for use in "task breakdown", "unit testing", and "code development".

Document and status

Output written to docs/{current_iteration_id}/program-design-{program_design_id}.md。
Before starting: call the history-manager skill's get-phase program_design and check-file to confirm whether it has been completed.
After completion: call the history-manager skill's set-phase program_design {program_design_id} to record and advance the status.