mcpField
U
upfront-design

upfront-design

github.com/prathamdbyDevelopment6228 installsUpdated 4d ago
Repository

About upfront-design

upfront-design is a skill for structuring and persisting software designs, aimed at teams moving from requests to reviewable milestones. It proceeds through product, system, program, slices, and finalize phases, with approval pauses between phases.

Key features

  1. 01Draft designs in defined phases
  2. 02Persist phase content after approval
  3. 03Track design status and approvals
  4. 04Map success criteria to symbols and results
  5. 05Check approved milestones

Use cases

  1. 01Turn a complex request into a phased design
  2. 02Advance to the next design phase after approval
  3. 03Check the first open milestone in an approved design

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/prathamdby/skills --skill upfront-design

After installing, type/upfront-designin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
check.md
decisions.md
design.md

Details

From the project README

Upfront design

Route and persistence

A design has request/status frontmatter and a # Design: title. New request → design; draft → first missing section; approved → check next open milestone; another status → BLOCKED. A named revision phase removes later sections only after the user authorizes that revision.

Resolve this skill's absolute anchor. Store new designs at <anchor>/designs/<basename>-<slug>-<YYYY-MM-DD-HHmmss>.md, outside repos. <basename> is the first repo's root directory name. After a path exists, persist approved phases and the ledger through sibling temporary files and atomic rename before advancing. Record request | size | design | phase | approvals | ADR offers | terminal. Keep the ledger at <design>.ledger on AWAITING_USER; remove on other terminals.

Small means one module, no contract/data/public-signature change, and a one-sentence outcome. Return DIRECT plus that sentence without a file/ledger. Otherwise find ADR trees (docs/adr/, adr/, doc/adr/, docs/decisions/); absence is silent. Create the document using references/design.md. Done when route, size, path/frontmatter, and relevant ADRs are fixed.

Design phases

Each phase pauses with AWAITING_USER; write its approved content before the next starts. Resume at the first missing or explicitly revised phase.

  1. Product: concrete pain, measurable Success, bold one-line solution, supplied mockup or draft text wireframe/state table for user-facing work, delivery paragraph. Ask the entire question frontier in one numbered round, recommending an answer per question. Done when approved content is persisted.
  2. System: bold shape + cited pattern, NEW/CHANGED layer roles, sources and constraints with cost reasons, phase-banded sequence. Name ADR conflicts, not overrides. Done when approved content is persisted.
  3. Program: changed boundary contracts, constraints, real signatures, usage, and roles, not bodies. Cite patterns or assumptions; compare two uncertain layouts, choose one, and record why the other lost. For multiple boundaries, changed dispatch, or unclear async order, apply Wiring views in references/design.md. Done when each Success maps to symbols/results and approval is persisted.
  4. Slices: after prefactoring, start with a thin end-to-end contract/check. One reviewable vertical PR per milestone; name symbols, expected success and relevant failures, assertions/manual proof, repo order, and one open checkbox. Only the user defers/skips; wide refactors expand then contract. Done when every symbol is assigned and approved milestones are persisted.
  5. Finalize: set approved. Offer ADRs only for decisions hard to reverse, surprising without context, and chosen over a real alternative. On approval use references/decisions.md. Done with DESIGNED when all five document sections exist and each ADR offer is written or declined. Report design/ADR paths, peer-review, and milestone check route.

Check

For an approved design, follow references/check.md for the first open, non-deferred/non-skipped milestone. Show exact commands and obtain approval before running them. Tick only with outcome proof and matching symbols, not a successful exit. Open manual boxes or ambiguous legacy outcomes pause. Never edit product files to make a check pass. Done with CHECKED if ticked or all complete, otherwise AWAITING_USER.

Terminals: DIRECT (router no-op success), AWAITING_USER, DESIGNED, CHECKED, BLOCKED. Revise via draft status and a named phase.

Comments

Markdown supported