Delivering Frontend Projects

Delivering Frontend Projects

Overview

Control frontend delivery with one verifiable chain from scope and contract readiness to code, build, evidence, handoff, and release status. Treat recorded facts and executable evidence as the authority; deadline, seniority, sunk cost, and existing code do not convert an unknown into a fact.

中文读者可先阅读 中文使用说明书，再按本文件及其 references 执行规范流程。

Output Language

• 默认使用简体中文生成人类可读内容，包括交付报告、Markdown 正文、表格自由文本、状态说明，以及确有必要时新增或修改的源代码注释。
• 必要的源代码注释使用中文说明原因或约束，不翻译代码标识符，也不为显而易见的代码增加注释。
• 文件名、路径、命令、YAML/Schema 字段、固定 Markdown 标题、机器表头、ID、Profile、枚举和状态值、API 名称及代码标识符保持原始英文。
• 目标仓库明确规定其他语言时遵循仓库规则，并在交付报告中说明实际语言和冲突原因；不得为中文化破坏机器结构。

Core Rules

• Never guess API, ID, or field contracts.
• Never invent evidence or mark an unrun check as passed.
• Never equate Code Complete with Verified.
• Never deploy or claim Released without explicit authorization.
• Preserve user changes and existing project rules. Report conflicts before replacing or deprecating a truth source.
• Keep one current owner for each fact. Link artifacts instead of copying status, contracts, or test conclusions between files.
• An older contract remains unverified when sources conflict, even if a lead requests it and the UI already uses it. Block only the dependent work and keep safe independent work moving.

Entry Workflow

1. Inspect repository instructions, package metadata, lockfiles, framework configuration, existing delivery artifacts, contract sources, and trusted commands.
2. Separate confirmed facts, conflicts, and unknowns. Give every blocking unknown an owner and a measurable resolution condition.
3. Define one observable vertical slice, non-goals, user journey, acceptance criteria, dependencies, risk, and required artifacts.
4. Pass the Ready Gate before contract-dependent implementation.
5. Implement and integrate one slice at a time. Record state changes rather than rewriting history.
6. Execute checks against a bound code/build/environment and record persistent evidence.
7. Validate the artifact graph, then report the highest state the evidence proves.

Read workflow.md completely when creating, changing, blocking, resuming, deprecating, or handing off delivery artifacts. Read quality-gates.md before claiming Ready, Verified, release-ready, or Released.

Choose A Profile

Select from repository evidence, never preference:

• Use vue3-vite only when Vue 3 and Vite are both confirmed.
• Use react-next only when React and Next.js are confirmed; identify App Router or Pages Router.
• Otherwise use generic-web and record ambiguous or unsupported stack evidence.

Read profiles.md before choosing commands or framework checks. A Profile may add checks but cannot weaken universal gates.

Choose Artifacts By Risk

Create api-contract whenever an API, permission, ID owner, request/response field, enum, nullability, time, unit, or compatibility fact is unknown or conflicting. Create project-status when at least two active work-items exist or work crosses milestones. Create handoff for cross-person/team transfer, release preparation, or release.

Run Quality Gates

• Ready proves scope, acceptance, contracts, permissions, dependencies, owner, plan, and verification approach are sufficient to start.
• Code Complete proves implementation is locally complete; it does not prove integration or user behavior.
• Verified requires current PASS or compliant PASS_WITH_RISK evidence bound to the same work-item, target, code, build, environment, executor, and timestamp.
• release-ready requires a durable handoff with authorization gaps, rollback state, deployment requirements, open risks, owners, and resumption conditions.
• Released requires written authorization, deployment evidence, verified rollback evidence, and post-release evidence.

A generic request for “verification evidence” is insufficient. Enumerate missing code version, build ID or reason, environment, executor, timestamp, reproducible command/steps, expected/actual result, and persistent report, screenshot, trace, or log reference. Read quality-gates.md for exact result precedence and binding rules.

Use Templates

Copy only the artifacts required by risk and triggers, then replace empty fact fields with verified project values:

• AGENTS.md
• project-status.md
• work-item.md
• api-contract.md
• test-evidence.md
• handoff.md
• adr.md

Preserve an existing AGENTS.md; merge only confirmed additions and report conflicts. Store delivery artifacts under docs/delivery/ using project-relative references. Do not treat an unfilled template as valid.

Validate Artifacts

Run from the installed Skill directory, or use the script's absolute path:

node scripts/validate-artifacts.mjs <project-root>
node scripts/validate-artifacts.mjs <project-root> --strict
node scripts/validate-artifacts.mjs <project-root> --json

Default mode allows warnings; --strict makes warnings fail. Exit 0 is valid for the selected mode, 1 is an artifact failure, and 2 is a CLI/tool failure. Fix errors at their owning source; never edit several truth files to silence graph diagnostics.

Optional Integrations

Read optional-integrations.md before invoking another Skill, Browser, or Chrome. Detect capability first. If browser or environment checks are unavailable, record NOT_RUN plus exact manual reproduction steps; availability does not prove execution.

Stop Conditions And Reporting

Stop contract-dependent work when authority conflicts or a blocking contract/permission fact has no verified source. Do not silently choose the older, more convenient, or already-coded option.

Stop verification advancement when evidence bindings are absent, stale, mismatched, or non-reproducible. Keep the work-item at or below the last provable state.

Stop release when authorization, rollback, deployment, risk acceptance, or post-release validation is missing. Create or update the handoff even when the immediate action is “do not ship”; a verbal no-go without a durable owner and resumption condition is incomplete.

Report confirmed facts, current state, completed safe work, blockers, owners, resolution conditions, validation command/result, evidence gaps, unrun checks, open risks, and the next authorized action.