外部交付物

# Prototype Handoff

<!-- meta -->
- handoff_version: "1.0"
- generated_by: roundtable
- prototype_target: pencil
<!-- /meta -->

## Target
- Prototype Target: pencil
- Goal: 快速验证产品形态 / 输出可评审设计稿 / 进入后续实现
- Delivery Mode: draft | reviewable | implementation-ready

## Product Goal
用一句话说明要构建什么，以及它解决谁的什么问题。

## Target Users
- 用户角色：
- 核心场景：
- 成功标准：

## Core User Flow
1. 用户进入：
2. 用户完成：
3. 系统反馈：
4. 用户下一步：

## Pages
### Page: 页面名称
- Purpose:
- Main Components:
- Primary Actions:
- Empty State:
- Loading State:
- Error State:
- Mobile Behavior:

## Data Model
| Entity | Fields | Relationships | Validation |
|:---|:---|:---|:---|
| Example | id, name, status | belongs_to user | name required |

## Adapter Notes
- Workspace Reference:
- Export Requirements:
- Compression Strategy:
- Design System Source:
- Design Intelligence Source: none | ui-ux-pro-max | manual

## Acceptance Criteria
> 每项验收标准必须使用 - [ ] AC-xxx: 前缀，供 tasks.acceptance_refs 精确引用。

- [ ] AC-001: 用户可以完成核心路径
- [ ] AC-002: 所有表单有校验和错误提示
- [ ] AC-003: 移动端布局不溢出
- [ ] AC-004: 空状态、加载态、错误态完整

# Core JSON Contract

## report.json
{
  "report_version": "1.0",
  "roundtable_status": "ready_for_execution",
  "artifact_refs": {
    "context_pack": "docs/roundtable/.../context-pack.json",
    "decisions": "docs/roundtable/.../decisions.json",
    "tasks": "docs/roundtable/.../tasks.json",
    "prototype_handoff": "docs/roundtable/.../prototype-handoff.md",
    "execution_context": "docs/roundtable/.../execution-context.json",
    "execution_plan": "docs/roundtable/.../execution-plan.md",
    "execution_log": "docs/roundtable/.../execution-log.md",
    "execution_review": ""
  },
  "generated_at": "ISO8601",
  "last_updated_at": "ISO8601"
}

Rule: artifact_refs.execution_review is empty unless execution_result_state = executed_reviewed.

## decisions.json
{
  "decision_log_version": "1.0",
  "decisions": [
    {
      "decision_id": "D-001",
      "status": "accepted",
      "owner": "product",
      "approval_required": false,
      "approved_at": "",
      "decided_at": "ISO8601"
    }
  ]
}

## tasks.json
{
  "task_plan_version": "1.0",
  "tasks": [
    {
      "task_id": "T-001",
      "owner": "agent:pencil-runner",
      "acceptance_refs": ["prototype-handoff.md#AC-001"],
      "artifact_refs": ["prototype-handoff.md"],
      "decision_refs": ["D-001"]
    }
  ]
}

# Prototype Review Contract

## prototype-review.json
{
  "handoff_ref": "docs/roundtable/.../prototype-handoff.md",
  "handoff_version": "1.0",
  "implementation_ref": "pencil export or lovable output",
  "status": "passed | failed | partial | needs_info | needs_migration",
  "checks": [
    {
      "check_id": "PT-001",
      "category": "pages",
      "expected": "Dashboard page exists",
      "actual": "Dashboard page implemented",
      "status": "passed"
    }
  ]
}

## Allowed check categories
- pages
- flow
- permissions
- states
- responsive
- design
- ui_ux
- execution
- feasibility

# Superpowers Execution Adapter

## Complexity-aware activation
| complexity_level | Policy |
|:---|:---|
| light | never auto-enable |
| mini | recommend when implementation or validation is non-trivial |
| standard | default for implementation flows |
| full | always record execution_method_selection; default for implementation flows |

## execution-context.json
{
  "execution_context_version": "1.0",
  "execution_adapter": "superpowers",
  "execution_adapter_status": "enabled | disabled_by_user | disabled_by_policy | skipped_non_implementation | unavailable | static_plan",
  "execution_result_state": "not_executed | executed_unverified | executed_reviewed",
  "recommended_superpowers": ["superpowers:executing-plans"],
  "source_artifacts": {
    "decisions": "docs/roundtable/.../decisions.json",
    "tasks": "docs/roundtable/.../tasks.json",
    "validation_plan": "docs/roundtable/.../validation-plan.md",
    "prototype_handoff": "docs/roundtable/.../prototype-handoff.md"
  },
  "brainstorm_scope": "execution_only",
  "selection_reason": "complexity_policy | explicit_user_request | disabled_by_user | non_implementation_flow"
}

## Conditional artifacts
docs/roundtable/YYYY-MM-DD_topic-slug/
├── execution-context.json
├── execution-plan.md
├── execution-log.md
└── execution-review.md   # only when execution_result_state = executed_reviewed

Boundary:
- Superpowers may split plans, delegate subtasks, track execution, and review validation.
- It must not change decisions.json semantics, product scope, permission rules, acceptance criteria, or human approval gates.
- Static plans use execution_result_state = not_executed and must not generate execution-review.md.

# Platform Adapter Package

roundtable/
├── SKILL.md
├── manifest.json
├── roundtable.config.json
├── codex/AGENTS-snippet.md
├── claude/CLAUDE-snippet.md
├── claude/commands/roundtable.md
├── trae/project_rules.md
├── trae/custom-agent-prompt.md
└── scripts/
    ├── new-archive.mjs
    ├── validate-json.mjs
    └── validate-execution-context.mjs

Rules:
- All platforms point to roundtable/SKILL.md.
- Platform adapters are thin entry points, not protocol forks.
- validate-json.mjs checks artifact_refs, acceptance_refs, and execution-review state rules.

# Diagrams Generated

docs/roundtable/YYYY-MM-DD_topic-slug/
└── diagrams/
    ├── flow.mmd
    ├── state-machine.mmd
    └── architecture.mmd

Rules:
- Generated only when --draw is enabled.
- Archive Mermaid source files only.
- Rendered PNG / SVG files are presentation outputs, not archive artifacts.

# Pencil Adapter Artifacts

## pencil-prompt.md
- Product Goal
- Core User Flow
- Pages
- Permission Rules
- Design Direction
- Acceptance Criteria
- Required Exports

## pencil-task.json
{
  "target": "pencil",
  "source_handoff": "docs/roundtable/YYYY-MM-DD_topic-slug/prototype-handoff.md",
  "deliverables": ["designs/<topic>.pen", "artifacts/<topic>.png"],
  "requirements": {
    "mobile_behavior_required": true,
    "empty_state_required": true,
    "error_state_required": true,
    "permission_boundary_required": true
  }
}

## pencil-runbook.md
- 输入文件路径
- 需要人工复制或导入到 Pencil 的内容
- 期望导出的文件类型
- 验证时应回填的 implementation_ref
- Pencil 能力不足时的降级说明

# Design Intelligence Adapter

## Input from prototype-handoff.md
- Product Goal: 为客服团队提供反馈处理工作台
- Page: Feedback Dashboard
- Components: filters, feedback table, status tags, assignee column
- Permission Rules: 普通处理人仅看自己的反馈；管理员可查看和分派所有反馈
- Design Direction: 专业、可信、适合高频后台操作
- Design Intelligence Source: ui-ux-pro-max

## design-system-brief.md
- Visual language: Enterprise SaaS / operational dashboard
- Color direction: neutral slate base, cyan for navigation, amber for attention
- Typography: compact documentation-friendly sans, numeric columns use tabular figures
- Layout density: medium-high density for dashboard tables
- Motion: restrained transitions for filters, drawers, and validation feedback
- Accessibility: visible focus ring, AA contrast, keyboard reachable actions

## ui-ux-review-checklist.md
- [ ] Dashboard hierarchy separates filters, summary, and table
- [ ] Empty, loading, and error states exist
- [ ] Status colors are not the only indicator
- [ ] Detail drawer is keyboard reachable and closable
- [ ] 375px layout stacks filters and table cards
- [ ] Admin-only assignment respects permission rules

## frontend-design-brief.md
- Layout structure
- Component priorities
- Interaction states
- Implementation notes
- Links back to prototype-handoff.md

Boundary: this adapter may enhance Design Direction and UI quality checks, but must not change product scope, permissions, data model, API contract, or business acceptance criteria.

# Title

## Background

## Decision

## Scope
### In Scope
### Out of Scope

## Tasks
- [ ] Task 1

## Acceptance Criteria
- [ ] AC-001: Criterion 1

## Risks

## References
- Roundtable report:
- Prototype handoff:

## GitLab Metadata
- GitLab Base URL: https://gitlab.asiainfo.com
- Project:
- Branch: