Skip to content

vt-c-pd-6-handoff

Prepare and execute development handoff with specs package, prototype code, and documentation.

Plugin: core-standards
Category: Product Design Workflow
Command: /vt-c-pd-6-handoff

Product Design: Development Handoff

Prepare the complete development handoff package and coordinate the transition from Product Design to Development workflow.

Workflow Position

/vt-c-pd-4-validate → /vt-c-pd-6-handoff → DEVELOPMENT WORKFLOW
                              │
                              ├── Package preparation
                              ├── Handoff meeting
                              └── Development kickoff
                                   │
                                   ▼
                              /vt-c-specs-from-prd → /vt-c-2-plan → /vt-c-3-build → ...

Invocation

/vt-c-pd-6-handoff                  # Full handoff workflow
/vt-c-pd-6-handoff --package        # Prepare handoff package only
/vt-c-pd-6-handoff --meeting        # Generate meeting agenda
/vt-c-pd-6-handoff --verify         # Verify handoff completeness

Configuration

# Project paths
prd_path: "03-PRD/PRD.md"
pid_path: "03-PRD/PID.md"
specs_folder: "05-specs"
prototype_folder: "04-prototyp"
research_folder: "02-Knowledge"
handoff_output: "06-Handoff"

Unified Repo Mode Detection

Before executing, check for .repo-manifest.yaml:

If .repo-manifest.yaml EXISTS (unified repo): - This skill transitions the repo from design mode to development mode - No external handoff package needed — all artifacts are in the same repo - Steps: verify gates → bootstrap tech stack → set up .specify → show /vt-c-activate - See "Unified Mode Execution" section below

If .repo-manifest.yaml does NOT exist (separate project): - This skill prepares the traditional handoff package for an external development team - Steps: verify gates → create 06-Handoff/ package → generate meeting agenda - Continue with standard execution below

Unified Mode Execution

When .repo-manifest.yaml exists, replace the standard handoff with:

Unified Step 1: Verify Design Quality Gates

Same as Step 0 below — all quality gates must pass.

Unified Step 2: Bootstrap Tech Stack

If src/ does not exist or is empty: 

Development infrastructure not yet set up.
Run /vt-c-1-bootstrap [stack] to add tech-stack configs.
Use AskUserQuestion to select stack, then run bootstrap inline.

Unified Step 3: Set Up .specify

  1. Create .specify/ and specs/ directories if missing
  2. Extract project constitution from PRD into .specify/memory/constitution.md
  3. Show: ".specify/ ready for specs activation"

Unified Step 4: Transition State

Update .design-state.yaml: 

current_state:
  phase: "development"
  status: "active"
  transitioned_at: "{timestamp}"
  mode: "unified"

Unified Step 5: Show Next Steps

Design-to-Development Transition Complete!

All design quality gates passed. The repo is now in development mode.

Tech stack: [bootstrapped stack]

Next steps:
  /vt-c-specs-from-prd  → generate specs directly from PRD, load first for development
  /vt-c-activate             → show spec sequence dashboard (if specs already exist)
  /vt-c-activate --status    → view execution dashboard

For prototype code reuse:
  /vt-c-promote             → move prototype components to src/ with production audit
  (Do NOT copy files manually — /vt-c-promote audits for production readiness)

Then STOP — do not continue with the standard handoff steps below.

Standard Handoff Execution (Separate Project Mode)

Iteration Loop Integration

Step 0: Check Design State (Before Starting)

Before preparing handoff, verify all quality gates have passed:

# Load design state
Read: .design-state.yaml

# Check all quality gates
if quality_gates.pd-1-research.passed != true:
  BLOCK: "Research quality gate not passed"
if quality_gates.pd-2-prd.passed != true:
  BLOCK: "PRD quality gate not passed"
if quality_gates.pd-3-prototype.passed != true:
  BLOCK: "Prototype quality gate not passed"
if quality_gates.pd-4-validate.passed != true:
  BLOCK: "Validation quality gate not passed"

# Check for pending inbox items
if inbox.pending_items exists:
  Run: /vt-c-pd-inbox-scan to process first

If any quality gate fails: 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Cannot Proceed with Handoff
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quality gates not met:

• {failed_gate}: {reason}

Please complete the following before handoff:
→ Run /{phase} to address outstanding items

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If this is a completed iteration: 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Iteration Context: pd-6-handoff
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All Quality Gates: ✓ PASSED
Iterations Completed: {iteration count}
Artifacts Ready:
• PRD: v{version} (approved)
• Prototype: v{version} (deployed)
• specs: {count} files (v{version})

Design Journey Summary:
• Started: {first iteration date}
• Iterations: {count}
• Key decisions: {count} logged

Ready to prepare handoff package.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quality Gate: pd-6-handoff

Mark phase as complete when: - [ ] All previous quality gates passed - [ ] Handoff package created in 06-Handoff/ - [ ] Meeting agenda prepared - [ ] Development guide complete - [ ] Team access granted - [ ] Handoff meeting scheduled/completed

Update state file on completion: 

quality_gates:
  pd-6-handoff:
    passed: true
    passed_at: "{timestamp}"
    criteria:
      all_gates_passed: true
      package_created: true
      meeting_scheduled: true
      access_granted: true

# Mark workflow as complete
current_state:
  phase: "handoff_complete"
  status: "completed"
  completed_at: "{timestamp}"

Execution Instructions

Step 1: Verify Prerequisites

Check all Product Design deliverables are complete:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Development Handoff - Product Design Phase 6
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project: [directory name]

Prerequisites Check:
─────────────────────────────────────────────────────────────────
[✓/✗] PRD.md approved (Section 12 sign-off)
[✓/✗] PID.md complete (tech stack defined)
[✓/✗] Prototype deployed and accessible
[✓/✗] Usability validation complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If any prerequisites fail, guide to appropriate phase: - Missing PRD sign-off → "Get stakeholder approval in PRD Section 12" - Missing validation → "Run /vt-c-pd-4-validate first"

Step 2: Prepare Handoff Package

Create the 06-Handoff/ directory structure:

06-Handoff/
├── README.md                    # Handoff overview
├── handoff-checklist.md         # Verification checklist
├── meeting-agenda.md            # Handoff meeting agenda
├── development-guide.md         # Quick start for developers
├── design-journey.md            # Iteration history and decisions
└── links/
    ├── prd.md                   # Link to ../03-PRD/PRD.md
    ├── pid.md                   # Link to ../03-PRD/PID.md
    ├── prototype.md             # Link to ../04-prototyp/
    └── specs/                # Links to ../05-specs/*.md

Generate Design Journey Document

Create 06-Handoff/design-journey.md from .design-state.yaml and docs/decisions/:

Step 2a: Load decision records

  1. Glob docs/decisions/*.md for all decision records
  2. For each record, parse YAML frontmatter to extract:
  3. id, date, phase, iteration, trigger
  4. findings, artifacts_changed, tags
  5. Read the record body to extract:
  6. Source evidence (verbatim stakeholder quotes with speaker attribution)
  7. Decisions Made table entries
  8. Open Questions
  9. Sort records by date ascending

Step 2b: Generate design-journey.md

# Design Journey - [Project Name]

## Overview

This document captures the design evolution from initial concept to handoff.

**Duration**: {first iteration start} → {handoff date}
**Total Iterations**: {count}
**Final Artifacts**: PRD v{version}, Prototype v{version}, {count} specs
**Decision Records**: {count} in docs/decisions/

## Iteration Timeline

| # | Started | Ended | Trigger | Phases | Outcome | Decision Record |
|---|---------|-------|---------|--------|---------|-----------------|
| 1 | {date} | {date} | Initial | pd-0 → pd-2 | PRD v1.0 | — |
| 2 | {date} | {date} | Normal | pd-3 → pd-4 | Prototype v1.0 | — |
| 3 | {date} | {date} | Usability | pd-3 → pd-4 | UI fixes | DEC-003 |
| ... | ... | ... | ... | ... | ... | ... |

## Key Decisions

{Enriched from docs/decisions/*.md records. For each decision record, include
the source evidence and rationale, not just the summary from .design-state.yaml.}

| Date | Phase | Decision | Source Evidence | Rationale |
|------|-------|----------|-----------------|-----------|
| {date} | {phase} | {decision} | {speaker}: "{quote}" | {rationale from record} |

## Usability Findings Summary

**Tests Conducted**: {count}
**Task Completion Rate**: {final rate}%
**Critical Issues Resolved**: {count}

Key improvements made:
- {improvement 1}
- {improvement 2}

## Stakeholder Feedback Incorporated

{List significant stakeholder inputs that changed direction}

- {feedback summary → impact on design}

## What Development Should Know

### Why Certain Decisions Were Made

{Extract from decision records — include verbatim stakeholder quotes with speaker
attribution to give developers full context on why decisions were made.}

1. **{Decision 1}**: {Why this was chosen, implications for dev}
   > "{Verbatim quote}" — {Speaker}, {Date}

2. **{Decision 2}**: {Why this was chosen, implications for dev}
   > "{Verbatim quote}" — {Speaker}, {Date}

### Known Limitations Accepted

{From deferred items or continue_with_limitations decisions}

- {limitation 1} - Reason: {why accepted}
- {limitation 2} - Reason: {why accepted}

### Open Questions for Development

{Aggregated from decision records' Open Questions sections plus any unresolved items}

- {question 1} (from DEC-NNN)
- {question 2} (from DEC-NNN)

## Metrics

**Total Design Time**: {calculate from iterations}
**Phases Completed**: 7 (pd-0 through pd-6)
**Quality Gates Passed**: 6/6
**Artifacts Produced**: PRD, PID, Prototype, {N} specs, Research docs
**Decision Records**: {count} across {iteration count} iterations

Step 3: Generate Handoff README

Create 06-Handoff/README.md:

# Development Handoff Package

**Project**: [Project Name]
**Handoff Date**: YYYY-MM-DD
**PM Contact**: [Name]

## Quick Links

| Document | Location | Purpose |
|----------|----------|---------|
| PRD | [03-PRD/PRD.md](../03-PRD/PRD.md) | Complete product requirements |
| PID | [03-PRD/PID.md](../03-PRD/PID.md) | Technical constraints |
| Prototype | [04-prototyp/](../04-prototyp/) | 95% reusable code |
| specs | [05-specs/](../05%20specs/) | Implementation specs |
| Design Journey | [design-journey.md](./design-journey.md) | Iteration history & decisions |
| User Manual | [docs/user-manual/](../docs/user-manual/) | Product documentation and developer onboarding |

> If `docs/user-manual/` does not exist, replace the User Manual row with:
> `| User Manual | Not yet generated | Run /vt-c-user-manual-generate to create |`

## Design Evolution Summary

**Iterations**: {count}
**Key Pivots**: {count decision points that changed direction}
**Final Versions**: PRD v{version}, Prototype v{version}

For detailed iteration history, decisions made, and rationale, see [design-journey.md](./design-journey.md).

## Development Sequence

### Phase 1: Project Setup
1. Read spec-0-project-setup.md
2. Run `/vt-c-0-start` to validate readiness
3. Run `/vt-c-1-bootstrap` to scaffold project

### Phase 2: Feature Implementation
For each specs (in priority order):
1. Run `/vt-c-activate` to load specs into `specs/[N]-feature/`
2. Run `/vt-c-2-plan` to generate technical plan
3. Run `/vt-c-3-build` to implement
4. Run `/vt-c-4-review` for code review

## Prototype Code Reuse

**Expected reuse**: 95% of prototype components

| Component Type | Reuse Strategy |
|---------------|----------------|
| Angular Standalone Components | Copy directly, connect to APIs |
| PrimeNG Preset (vt-preset.ts) | Use as-is (VisiTrans design tokens) |
| Design Tokens (CSS variables) | Use as-is |
| Mock Data (Services/Signals) | Replace with API calls |
| Feature Module Layouts | Adapt for lazy-loaded routes |

## Feature Priority Order

| Priority | specs | Feature |
|----------|----------|---------|
| 1 | spec-0 | Project Setup |
| 2 | spec-1 | [Feature Name] |
| 3 | spec-2 | [Feature Name] |
| ... | ... | ... |

## Support & Questions

- **PM Contact**: [Name] - [Slack/Email]
- **Design Questions**: Reference prototype
- **Requirement Clarifications**: Tag PM in GitHub issues
- **Weekly Sync**: [Day/Time]

Step 3.5: Implementation Readiness Deliverables Prompt

After preparing the core handoff package, check whether the project has implementation readiness documentation. These are standard deliverables for prototype projects that help the production team understand UI states and test coverage.

Standard Implementation Readiness Deliverables: 1. UI State Matrix — all UI states, permutations, and coverage status 2. Test Dataset — sample data covering all state permutations 3. Data Model Reference — entities, fields, relationships, validation rules 4. API Concept — endpoint structure, request/response shapes, error handling

Check: 1. Look for 01-docs/deliverables/implementation-readiness/ in the project 2. If directory exists: verify which deliverables are present and list status 3. If directory does not exist: display advisory: 

Implementation Readiness Deliverables:
─────────────────────────────────────────────────────────────────
No implementation readiness docs found. Consider creating:
• UI State Matrix — see templates/scaffold/design/ui-state-matrix-template.md
• Test Dataset — sample data for all UI state permutations
• Data Model Reference — entities and validation rules
• API Concept — endpoint structure and error handling

These help the production team understand what the prototype covers.
Create in: 01-docs/deliverables/implementation-readiness/
─────────────────────────────────────────────────────────────────

Step 4: Generate Handoff Checklist

Create 06-Handoff/handoff-checklist.md:

# Handoff Verification Checklist

## Product Design Deliverables

### PRD (03-PRD/PRD.md)
- [ ] All 12 sections complete
- [ ] Section 4 Feature table has all features
- [ ] Prototyp column links valid
- [ ] FB-Link column populated with specs references
- [ ] Section 12 stakeholder sign-off obtained
- [ ] PID.md tech stack documented

### Prototype (04-prototyp/)
- [ ] Git repository initialized
- [ ] VisiTrans CD tokens applied
- [ ] All PRD features have corresponding screens
- [ ] Responsive layouts implemented
- [ ] Deployed to preview URL
- [ ] Mock data fixtures created

### User Research (02-Knowledge/)
- [ ] Personas documented (02-Zielgruppen-Personas/)
- [ ] Interview analyses complete (04-Dokumente/)
- [ ] Usability test results documented
- [ ] Key findings summarized

### specs (05-specs/)
- [ ] spec-0 (Project Setup) exists
- [ ] All PRD features have corresponding specs
- [ ] SpecKit-compatible YAML frontmatter
- [ ] Acceptance criteria defined for each
- [ ] Dependencies identified
- [ ] Prototype links valid

### Implementation Readiness (01-docs/deliverables/implementation-readiness/)
- [ ] UI State Matrix complete (all dimensions, permutations, coverage)
- [ ] Test Dataset covers all state permutations
- [ ] Data Model Reference documented
- [ ] API Concept documented

## Development Readiness

### Code Handoff
- [ ] Prototype Git repo access granted
- [ ] Design system documentation available
- [ ] API specifications documented (if applicable)
- [ ] Third-party service credentials ready (not in code)

### Team Readiness
- [ ] Development team identified
- [ ] Handoff meeting scheduled
- [ ] Communication channels established
- [ ] Weekly sync cadence agreed

### Environment
- [ ] Development environment setup documented
- [ ] CI/CD requirements specified in spec-0
- [ ] Staging/production requirements in PID

Step 5: Generate Meeting Agenda

Create 06-Handoff/meeting-agenda.md:

# Development Handoff Meeting

**Date**: YYYY-MM-DD
**Duration**: 60 minutes
**Attendees**: [PM], [Tech Lead], [Developers]

## Agenda

### 1. Project Overview (10 min)
- Business context and goals
- Target users and personas
- Success metrics

### 2. PRD Walkthrough (15 min)
- Key features and priorities
- Scope and non-scope
- Technical constraints (PID)

### 3. Prototype Demo (15 min)
- User flows and screens
- Design system and tokens
- Code structure for reuse

### 4. specs Review (15 min)
- Implementation sequence
- Dependencies between features
- Acceptance criteria overview

### 5. Q&A and Next Steps (5 min)
- Immediate questions
- First sprint planning
- Communication protocol

## Pre-Meeting Preparation

**For Development Team**:
- [ ] Review PRD.md overview sections
- [ ] Access prototype preview URL
- [ ] Review spec-0 (Project Setup)
- [ ] Prepare technical questions

**For PM**:
- [ ] Prepare prototype demo
- [ ] Have research findings ready
- [ ] Identify open questions to discuss

## Post-Meeting Actions

- [ ] Answer any outstanding questions (PM, 24h)
- [ ] Create development repository (Tech Lead, 48h)
- [ ] Schedule first sprint planning (Tech Lead, 1 week)
- [ ] Set up communication channels (PM, 24h)

Step 6: Generate Development Guide

Create 06-Handoff/development-guide.md:

# Development Quick Start Guide

## Getting Started

### 1. Clone Prototype
```bash
cd 04-prototyp
# Prototype is a Git repo with VisiTrans CD

2. Review Project Setup

# Read the project setup spec
cat "05-specs/spec-0-project-setup.md"

3. Initialize Development Repo

# Create new repo or use prototype as base
/vt-c-0-start
/vt-c-1-bootstrap

4. Implement Features

# For each specs:
/vt-c-activate                # loads specs into specs/[N]-feature/
/vt-c-2-plan
/vt-c-3-build
/vt-c-4-review

Design System Reference

VisiTrans Corporate Design Tokens

/* Colors */
--vt-black: #1F1F1F;
--vt-orange: #FC9E00;
--vt-white: #FFFFFF;
--vt-magenta: #E6007E; /* Action color */

/* Gray Scale */
--vt-gray-90: #2D2D2D;
--vt-gray-70: #5C5C5C;
--vt-gray-50: #8A8A8A;
--vt-gray-30: #B8B8B8;
--vt-gray-10: #E6E6E6;

/* Typography */
--vt-font-family: 'Inter', sans-serif;

Component Reuse Strategy

  1. Copy Angular standalone components from 04-prototyp/src/app/shared/components/ and 04-prototyp/src/app/features/
  2. Keep PrimeNG preset (vt-preset.ts) — already has VisiTrans design tokens
  3. Replace MockDataService with real API services using HttpClient
  4. Add validation — prototype has UI, add server-side and reactive form validation

Key Files to Review

File Why
03-PRD/PRD.md Full requirements context
03-PRD/PID.md Tech stack constraints
05-specs/spec-0-*.md Project setup requirements
04-prototyp/src/app/core/theme/vt-preset.ts PrimeNG design tokens (Angular)
04-prototyp/src/app/shared/components/ Reusable Angular components
04-prototyp/src/app/features/ Feature components (.component.ts)

Questions?

  • Requirements: Check PRD, then ask PM
  • Design: Check prototype, then ask PM
  • Technical: Check PID, then decide with team 
    ### Step 7: Verify Package Completeness

Run verification:
    Handoff Package Verification: ───────────────────────────────────────────────────────────────── [✓/✗] 06-Handoff/README.md exists and complete [✓/✗] 06-Handoff/handoff-checklist.md exists [✓/✗] 06-Handoff/meeting-agenda.md exists [✓/✗] 06-Handoff/development-guide.md exists [✓/✗] 06-Handoff/design-journey.md exists and populated [✓/✗] All specs linked and accessible [✓/✗] Prototype URL accessible [✓/✗] PRD sign-off verified [✓/✗] Design state file shows all quality gates passed 
    ### Step 8: Display Summary
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Development Handoff Package Complete ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Package Location: 06-Handoff/

Contents: • README.md - Handoff overview and quick links • handoff-checklist.md - Verification checklist • meeting-agenda.md - 60-minute handoff meeting agenda • development-guide.md - Quick start for developers • design-journey.md - Iteration history and key decisions

Deliverables Summary: ───────────────────────────────────────────────────────────────── • PRD: 03-PRD/PRD.md (approved, v{version}) • PID: 03-PRD/PID.md (tech stack defined) • Prototype: 04-prototyp/ (deployed, v{version}) • specs: {N} files in 05-specs/ (v{version}) • Research: 02-Knowledge/ (personas, findings)

Design Journey: ───────────────────────────────────────────────────────────────── • Iterations: {count} (from {start} to {end}) • Quality Gates: 6/6 passed • Key Decisions: {count} documented • Usability Rate: {final task completion rate}%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ NEXT STEPS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Schedule handoff meeting with development team
  2. Share 06-Handoff/ folder with team
  3. Grant prototype repo access
  4. Development team runs: /vt-c-0-start → /vt-c-1-bootstrap → /vt-c-2-plan (with specs)

Product Design workflow complete! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 

### Step 9: Update Design State File

Mark handoff as complete:

```yaml
# Update .design-state.yaml
current_state:
  phase: "handoff_complete"
  status: "completed"
  iteration: {final}
  completed_at: "{timestamp}"

quality_gates:
  pd-6-handoff:
    passed: true
    passed_at: "{timestamp}"
    criteria:
      all_gates_passed: true
      package_created: true
      design_journey_documented: true

# Log final decision
decisions:
  - timestamp: "{now}"
    phase: "pd-6-handoff"
    type: "workflow_complete"
    reason: "All quality gates passed, handoff package prepared"
    action: "Transition to Development workflow"

Integration with Development Workflow

After handoff, development team:

  1. Project Setup (spec-0): 

    /vt-c-0-start → /vt-c-1-bootstrap

  2. Feature Implementation: 

    /vt-c-specs-from-prd   # generates specs directly from PRD
/vt-c-activate SPEC-NNN     # activates a specific spec
/vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-5-finalize

  3. Prototype Code Reuse:

  4. Copy Angular standalone components (.component.ts, .component.html) directly
  5. Use PrimeNG preset (vt-preset.ts) as-is
  6. Replace MockDataService with real API services
  7. Add server-side validation and reactive forms

Best Practices

Handoff Meeting

  • Keep to 60 minutes
  • Focus on overview, not details (details in docs)
  • Record for team members who can't attend
  • Create action items with owners

Communication Protocol

  • Slack channel for daily questions
  • Weekly sync for status and blockers
  • Tag PM in GitHub issues for requirement questions
  • PM available first 2 weeks for intensive support

Success Metrics

  • Question volume: < 5 clarifications per specs
  • Code reuse: > 90% prototype components used
  • First feature: Shipped within 1 sprint
  • Design fidelity: 95% match to prototype