design-to-project

description: Full AI-AGENT-PLAYBOOK orchestration - transforms a design specification into project artifacts and begins implementation tags: [design, planning, project-init, tasks, implementation, orchestration] techStack: [all] appliesTo: ["projects/*/spec.md", "implement spec", "design to project"] alwaysApply: false

Purpose

Orchestrates the complete transformation of a Detailed Design Specification into executable project artifacts. This is the master skill that sequences

project-init

task-create

When to Use

• User provides a design specification (.docx, .md, or inline text)
• User says "implement this spec", "turn this into a project", or "follow the playbook"
• Explicitly invoked with

  /design-to-project {spec-path}

• Starting a new feature from a completed design document

Inputs Required

projects/{project-name}/

Design Spec Location Convention

Design specs live with their project at

projects/{project-name}/spec.md

Workflow:

1. Operator creates folder:

   projects/{descriptive-name}/

2. Operator places spec:

   projects/{project-name}/spec.md

3. Invoke:

   /design-to-project projects/{project-name}

4. Skill derives project name from folder and runs full pipeline

Phase Overview

┌─────────────────────────────────────────────────────────────────┐
│                    DESIGN-TO-PROJECT PIPELINE                   │
├─────────────────────────────────────────────────────────────────┤
│ Phase 1: INGEST      → Extract key info from design spec       │
│ Phase 2: CONTEXT     → Gather ADRs, architecture, existing code │
│ Phase 3: GENERATE    → Create README, plan.md, task files       │
│ Phase 4: VALIDATE    → Cross-reference checklist before coding  │
│ Phase 5: IMPLEMENT   → Execute tasks with context management    │
└─────────────────────────────────────────────────────────────────┘

Workflow

Phase 1: Ingest Design Specification

Step 1.1: Acquire Spec

IF project path provided (e.g., projects/sdap-fileviewer-enhancements-1):
  EXTRACT project-name from folder name
  VERIFY projects/{project-name}/spec.md exists
  LOAD spec.md
ELSE:
  ASK: "Please provide the project path (e.g., projects/my-feature)"

IF spec.md not found:
  STOP: "spec.md not found at projects/{project-name}/spec.md
         Please create the project folder and add spec.md first."

Step 1.2: Extract Key Information

PARSE spec for these sections:

| Field | Look For | Required |
|-------|----------|----------|
| Feature Name | Title, "Overview" section | Yes |
| Problem Statement | "Problem", "Background", "Current State" | Yes |
| Solution Approach | "Solution", "Approach", "Design" | Yes |
| Data Model | "Data Model", "Entities", "Schema" | If applicable |
| API Endpoints | "API", "Endpoints", "Contracts" | If applicable |
| UI Components | "UI", "Screens", "Components" | If applicable |
| Acceptance Criteria | "Acceptance Criteria", "Requirements" | Yes |
| NFRs | "NFRs", "Performance", "Security" | If specified |

Step 1.3: Summarize Understanding

## Design Spec Summary

**Feature**: {Feature Name}
**Problem**: {1-2 sentence problem statement}
**Solution**: {1-2 sentence solution approach}

**Key Components**:
- {Component 1 - type: API/PCF/Plugin/etc.}
- {Component 2}
- {Component 3}

**Estimated Complexity**: {Low | Medium | High}
**Basis**: {Why this complexity level}

Proceeding to Phase 2: Context Gathering...

Phase 2: Gather Context

Step 2.1: Discover Related Resources

Search for related skills and knowledge docs:

1. Extract keywords from spec.md:

   • Technology names (e.g., "Azure OpenAI", "Dataverse", "React", "PCF")
   • Feature types (e.g., "API endpoint", "PCF control", "plugin")
   • Operations (e.g., "deploy", "authentication", "caching")

2. Search

   .claude/skills/INDEX.md

   :
   • Look for skills with matching

     tags

     or

     techStack

     in their YAML frontmatter
   • Read relevant skill files for patterns and procedures
   • Example: If spec mentions "PCF control" → load relevant PCF skills

3. Search

   docs/ai-knowledge/

   :
   • Look for guides matching technologies or patterns in spec
   • Load relevant architecture docs, guides, and standards

Output: List of discovered skills and knowledge docs to use throughout pipeline.

Step 2.2: Check ADRs

READ: docs/ai-knowledge/CLAUDE.md for relevant articles
READ: docs/reference/adr/ index

FOR each technology in spec:
  MATCH to relevant ADRs:
    - PCF control → ADR-006, ADR-011, ADR-012
    - API endpoint → ADR-001, ADR-007, ADR-008, ADR-010
    - Dataverse plugin → ADR-002
    - Caching → ADR-009
    - Authorization → ADR-003, ADR-008

OUTPUT:
  | ADR | Title | Constraint for This Project |
  |-----|-------|----------------------------|
  | ... | ... | {specific constraint} |

Step 2.2: Find Reusable Code

SEARCH src/ for similar implementations:
  - PCF controls: src/client/pcf/
  - API patterns: src/server/api/
  - Shared libraries: src/client/shared/, src/server/shared/

OUTPUT:
  | Component | Location | How to Reuse |
  |-----------|----------|--------------|
  | ... | ... | ... |

Step 2.3: Load Knowledge Articles

BASED ON technologies in spec, load:
  - PCF: docs/ai-knowledge/guides/ PCF-related
  - Auth: docs/ai-knowledge/standards/oauth-*, auth-*
  - SDAP: docs/ai-knowledge/architecture/sdap-*

TRACK context usage - if > 50%:
  → Summarize key points
  → Reference file paths for later
  → Don't load full content

Step 2.4: Context Summary

## Context Summary

**Applicable ADRs**: ADR-006, ADR-008, ADR-012 (etc.)

**Reusable Components**:
- {Component}: {brief description}
- {Component}: {brief description}

**Key Knowledge Articles**:
- `docs/ai-knowledge/architecture/{article}` - {key insight}
- `docs/ai-knowledge/standards/{article}` - {key insight}

**Architecture Fit**:
{How this feature fits into existing system}

Proceeding to Phase 3: Generate Artifacts...

Phase 3: Generate Project Artifacts

Step 3.1: Invoke project-init

INVOKE: /project-init {project-name}

WITH context:
  - Design spec summary from Phase 1
  - ADR constraints from Phase 2
  - Complexity estimate from Phase 1

VERIFY outputs:
  - projects/{project-name}/spec.md (input - already existed)
  - projects/{project-name}/README.md
  - projects/{project-name}/plan.md
  - projects/{project-name}/CLAUDE.md
  - projects/{project-name}/tasks/

Step 3.2: Enrich README.md

ENHANCE README.md with Phase 2 findings:
  - Add "Key Decisions" section linking ADRs
  - Add "Dependencies" section with reusable components
  - Add "Risks" section based on complexity and dependencies

Step 3.3: Complete plan.md

ENHANCE plan.md with:
  - Executive Summary from spec
  - Solution Overview with architecture fit
  - WBS phases based on spec sections:

| Spec Section | Generates Phase |
|--------------|-----------------|
| Data Model | Phase: Entity/Schema Setup |
| API Endpoints | Phase: API Development |
| UI Components | Phase: UI Development |
| Integration | Phase: Integration & Wiring |
| Security | Phase: Auth Implementation |
| Testing | Phase: Validation |

APPLY estimation heuristics:
  - Simple CRUD endpoint: 0.5-1 day
  - Complex endpoint with auth: 1-2 days
  - PCF component (simple): 2-3 days
  - PCF component (complex): 3-5 days
  - Integration: 1-2 days
  - Unit tests: 0.5 day per component
  - Integration tests: 1-2 days

Step 3.4: Invoke task-create

INVOKE: /task-create {project-name}

VERIFY outputs:
  - tasks/TASK-INDEX.md exists
  - Task files created for each WBS phase
  - Dependencies mapped correctly

Step 3.5: Create Feature Branch

CREATE feature branch for this project:

git checkout -b feature/{project-name}

WHY at this point:
  - All artifacts created (README, plan, tasks)
  - Ready for commits that represent meaningful work
  - PR can be created as draft for visibility

NAMING convention:
  - feature/{project-name}  ← matches project folder name
  - Example: feature/ai-document-summary

COMMIT initial artifacts:
  git add projects/{project-name}/
  git commit -m "feat({scope}): initialize {project-name} project"
  git push -u origin feature/{project-name}

OPTIONAL - Create draft PR:
  gh pr create --draft --title "feat({scope}): {project-name}" \
    --body "## Summary\nImplementation of {project-name}\n\n## Status\n- [x] Project initialized\n- [ ] Implementation in progress\n- [ ] Code review\n- [ ] Ready for merge"

Phase 4: Validate Before Implementation

Step 4.1: Cross-Reference Checklist

VALIDATE all items:
  
□ ADR Compliance
  - Plan phases don't violate ADR constraints
  - Technology choices align with ADRs
  - Example: PCF uses v9 Fluent UI (ADR-006)

□ Reuse Maximized
  - Shared components referenced in tasks
  - No reinventing existing utilities
  - @spaarke/ui-components used where applicable

□ Scope Clear
  - In-scope items listed in README
  - Out-of-scope explicitly stated
  - No ambiguous deliverables

□ Acceptance Testable
  - Each criterion in README is measurable
  - Tasks include verification steps
  - "Done" is unambiguous

□ Dependencies Identified
  - All external dependencies listed
  - Blocking dependencies noted in tasks
  - Environment requirements documented

□ Risks Mitigated
  - High/Critical risks have mitigation plans
  - Technical debt acknowledged
  - Unknowns surfaced

Step 4.2: Output Ready Summary

## ✅ Ready for Development

**Project**: {feature-name}
**Location**: docs/projects/{feature-name}/

## ✅ Ready for Development

**Project**: {project-name}
**Location**: projects/{project-name}/

**Documents Created**:
- ✅ spec.md - Design specification (source of truth - input)
- ✅ README.md - Project overview, scope, graduation criteria
- ✅ plan.md - Implementation plan with WBS
- ✅ CLAUDE.md - AI context file
- ✅ tasks/TASK-INDEX.md - Task tracker
- ✅ {N} task files in tasks/

**Applicable ADRs**: {list}

**Reusable Components**:
- {component} ({purpose})
- {component} ({purpose})

**Estimated Effort**: {X} days ({Y} tasks)

**First Task**: `tasks/001-{slug}.md` - {title}

**Validation Checklist**: All items passed ✅

---

Ready to begin implementation? Reply "go" to start Phase 5.

Phase 5: Implement (Task Execution)

Step 5.0: Context Management (CRITICAL)

BEFORE each task and AFTER each subtask:

CHECK context usage:
  < 50%  → ✅ Proceed normally
  50-70% → ⚠️ Monitor, wrap up current subtask soon
  > 70%  → 🛑 STOP - Create handoff summary
  > 85%  → 🚨 CRITICAL - Immediate handoff

IF context reset needed:
  CREATE handoff summary (see Handoff Protocol below)
  OUTPUT: "Context limit reached. Handoff created. Start new chat."

Step 5.1: Execute Tasks

FOR each task in execution order:
  1. LOAD task file from tasks/{NNN}-{slug}.md
  2. CHECK dependencies are met
  3. GATHER resources (ADRs, patterns, related code)
  4. EXECUTE steps from <steps> section
  5. VERIFY outputs from <outputs> section
  6. UPDATE task status to "completed"
  7. CHECK context → reset if > 70%

Step 5.2: Apply Conventions

ALWAYS APPLY spaarke-conventions skill during implementation:
  - File naming conventions
  - Code patterns (.NET, TypeScript)
  - Error handling patterns
  - Async patterns

REFER TO:
  - .claude/skills/spaarke-conventions/SKILL.md
  - Root CLAUDE.md for standards

Step 5.3: Code Review Gate

AFTER implementing code:
  RUN: /code-review {changed-files}
  
IF critical issues found:
  FIX before marking task complete
  
IF warnings found:
  NOTE in task completion summary

Handoff Protocol

When context reaches 70%, create handoff summary:

## Handoff Summary - {project-name}

**Context Reset Trigger**: {current-task} at {step}
**Date**: {timestamp}

### Completed
- ✅ Phase 1: Ingest - {summary}
- ✅ Phase 2: Context - {summary}
- ✅ Phase 3: Generate - {artifacts created}
- ✅ Phase 4: Validate - {checklist passed}
- 🔄 Phase 5: Implement - {tasks completed}

### Current State
**Current Task**: {task-id} - {task-title}
**Current Step**: {step number/description}
**Files Modified**: {list}
**Tests Status**: {passing/failing}

### To Continue
1. Load: docs/projects/{project-name}/CLAUDE.md
2. Load: tasks/{current-task-id}.md
3. Resume at step: {step}
4. Remaining tasks: {list task IDs}

### Key Decisions Made
- {decision 1 with rationale}
- {decision 2 with rationale}

### Warnings/Issues
- {any blockers or concerns}

Conventions

Project Naming

• Derive from design spec title
• Use kebab-case
• Examples:

  universal-quick-create

  ,

  document-sync-worker

Phase Transitions

• Always output status when moving between phases
• Wait for user confirmation before Phase 5 (implementation)
• Create handoff if interrupted

Context Efficiency

• Summarize verbose specs, don't quote in full
• Reference file paths instead of loading full content when >50% context
• Prioritize: ADR constraints > reusable code > knowledge articles

Resources

Templates Used

• docs/ai-knowledge/templates/project-README.template.md

• docs/ai-knowledge/templates/project-plan.template.md

• docs/ai-knowledge/templates/task-execution.template.md

Skills Orchestrated

• project-init: Phase 3 - folder structure and initial artifacts
• task-create: Phase 3 - task decomposition
• code-review: Phase 5 - quality gate before task completion
• spaarke-conventions: Phase 5 - always-apply during implementation
• adr-check: Phase 5 - architecture validation
• repo-cleanup: Phase 5 (wrap-up) - repository hygiene after project completion

Reference Playbook

• docs/ai-knowledge/templates/AI-AGENT-PLAYBOOK.md

  - Full playbook documentation

Examples

Example 1: Full Pipeline

Trigger: "Here's the design spec for Universal Quick Create PCF. Transform it to a project."

Process:

1. Phase 1: Extract PCF feature details, data model, acceptance criteria
2. Phase 2: Identify ADR-006, ADR-011, ADR-012; find existing PCF patterns
3. Phase 3: Create

   docs/projects/universal-quick-create/

   with all artifacts
4. Phase 4: Validate checklist, output ready summary
5. Phase 5: User confirms, begin task execution

Example 2: Partial Execution

Trigger: "/design-to-project but stop after planning"

Process:

1. Execute Phases 1-4 only
2. Output ready summary with "Reply 'go' to begin implementation"
3. Wait for user

Example 3: Resume from Handoff

Trigger: "Continue from the handoff summary you created"

Process:

1. Load project CLAUDE.md
2. Load current task file
3. Resume at indicated step
4. Continue Phase 5 execution

Validation Checklist

Before declaring project ready for implementation:

• Design spec fully ingested (all sections extracted)
• All applicable ADRs identified
• Reusable components catalogued
• README.md has graduation criteria
• plan.md has complete WBS with estimates
• Task files created with POML format
• Dependencies form valid execution order
• Cross-reference checklist passed
• User informed of effort estimate