Developer Summary

Developer Summary

Generates a developer-focused summary document from Sherpy planning artifacts. Provides developers with a quick-start view of what's being built, key deliverables, and the milestone roadmap.

Usage

/developer-summary [base-directory]

If no directory is provided, auto-detect by looking for requirements/business-requirements.yaml in the current directory.

If not found, prompt the user: "Where are your planning artifacts located?"

Wait for the user to provide a path before proceeding.

Required Artifacts

The skill auto-discovers these files from the standard Sherpy folder structure:

Process

Step 1: Determine Base Directory and Scan for Required Artifacts

If no directory parameter was provided, check if requirements/business-requirements.yaml exists in the current directory.

• If found, use current directory as base_directory
• If not found, prompt: "Where are your planning artifacts located?" and wait for user response

Once base_directory is determined, scan for required files in standard locations. Display status:

## Developer Summary — Dependency Check

Scanning for required artifacts...

 ✓  requirements/business-requirements.yaml
 ✓  requirements/technical-requirements.yaml
 ✓  implementation/milestones.yaml
 ✗  delivery/timeline.yaml

3 of 4 required files found.

Legend: ✓ found · ✗ missing

Step 2: Handle Missing Files

If any required files are missing, ask:

"Missing required files: timeline.yaml

>

Options:

1. Continue with partial data — Generate summary with available information (missing sections will be marked as [Not Available])

2. Exit — Complete missing artifacts first (run /delivery-timeline to generate timeline.yaml)

>

What would you like to do?"

Wait for user response:

• If user chooses 1 (Continue): Proceed with available data, mark missing sections clearly
• If user chooses 2 (Exit): Display which skills to run and exit gracefully

Step 3: Load and Parse Artifacts

Read all available files and extract:

From business-requirements.yaml:

• Project name and description
• Core features and capabilities
• Key deliverables

From technical-requirements.yaml:

• Technology stack
• Architectural patterns
• Key technical components

From milestones.yaml:

• Milestone sequence (m0, m1, m2, etc.)
• Milestone names and descriptions
• Dependencies between milestones
• Estimated duration per milestone

From timeline.yaml (if available):

• Total project duration
• Target completion date
• Timeline workback schedule

Step 4: Generate Developer Summary

Create summaries/developer-summary.md.

The output document includes: header (timestamp, project name), Overview (3-5 sentence synthesis), Deliverables (grouped by category), Milestones & Timeline (M0, M1... with duration, dependencies, key deliverable), and Summary (total milestones, estimated duration, target completion).

See [references/output-spec.md](references/output-spec.md) for the complete document specification with section structure and formatting rules.

See [references/example.md](references/example.md) for a full example.

Step 5: Handle Missing Data Gracefully

When required files are missing, insert clear placeholders:

## Milestones & Timeline

[Not Available - `milestones.yaml` not found. Run `/implementation-planner` to generate milestones.]

Or for partial data:

## Summary

**Total Milestones:** 4
**Estimated Total Duration:** 6 weeks (estimated from milestones)
**Target Completion:** [Not Available - run `/delivery-timeline` to set production deploy date]

Step 6: Confirmation

After generating the summary, display:

## Developer Summary Generated ✓

**Location:** summaries/developer-summary.md
**Size:** [file size]

Summary includes:
  ✓ Project overview
  ✓ Deliverables breakdown
  ✓ Milestone roadmap
  [Missing data: timeline completion date - run /delivery-timeline]

The summary is ready for developer onboarding and reference.

Deliverables Extraction Logic

Identifying Deliverables

Parse the following sources to build the deliverables list:

From business-requirements.yaml:

• functional_requirements → User-facing features
• features or capabilities → High-level capabilities
• scope.in_scope → Explicitly included items

From technical-requirements.yaml:

• architecture.components → Technical components
• technology_stack → Infrastructure items (databases, APIs, services)
• data_model.entities → Domain entities/models
• apis.endpoints → API endpoints if listed
• integration_points → External integrations

Categorization Rules

Group deliverables into logical categories based on type:

• API Endpoints - REST/GraphQL endpoints, webhooks
• Domain Handlers - Business logic handlers, command processors
• UI Components - Pages, views, components (if applicable)
• Data Models - Entities, schemas, database tables
• Infrastructure - Databases, message queues, auth systems
• Integrations - External service connections
• Background Jobs - Scheduled tasks, workers
• Configuration - Environment setup, deployment configs

Use the most relevant categories based on what's present in the requirements. Don't force categories that don't apply.

Overview Generation Logic

Crafting the Overview Paragraph

Synthesize information from multiple sources to create a concise, informative overview:

Elements to include (in order): 1. What - The system/feature being built (1 sentence) 2. Why - The problem it solves or value it provides (1 sentence) 3. How (high-level) - The approach or key capability (1 sentence, optional)

Source fields to use:

• business-requirements.yaml:
• description or overview
• business_goals.primary_goal
• success_criteria
• technical-requirements.yaml:
• solution_overview
• architecture.approach

Template:

"[System Name] is a [type of system] that [primary function]. It addresses [problem] by [solution approach], enabling [key benefit/outcome]. The system will [key technical approach or differentiator]."

Example:

"The Sherpy CLI is a structured planning tool for AI-assisted software development. It addresses requirement drift and planning gaps by conducting guided interviews and generating comprehensive implementation plans with task-level detail. The system enforces best practices like task sizing, TDD requirements, and style anchors throughout the planning process."

Keep it Concise

• Maximum 5 sentences
• No bullet points in the overview
• Focus on business value, not implementation details
• Avoid jargon unless it's domain-specific and necessary

Milestone Roadmap Logic

Extracting Milestone Information

For each milestone in milestones.yaml, extract:

Required fields:

• id - Milestone identifier (m0, m1, etc.)
• name - Milestone title
• description - What the milestone delivers
• estimated_duration - Time estimate
• dependencies - Which milestones must complete first

Formatting:

• Display milestones in sequence (m0 → m1 → m2...)
• Show dependencies clearly
• Highlight the "key deliverable" from the first line of the description or the most important success criterion

Example extraction:

# From milestones.yaml:
milestones:
  - id: m1
    name: API Foundation
    description: |
      Build core REST API with authentication and authorization.
      Includes user management endpoints and JWT token handling.
    dependencies: [m0]
    estimated_duration: 2 weeks
    success_criteria:
      - All auth endpoints functional
      - JWT tokens properly validated

Renders as:

### M1: API Foundation
**Duration:** 2 weeks
**Dependencies:** M0
**Key Deliverable:** Core REST API with authentication and authorization

Timeline Calculation

If timeline.yaml is available:

• Use total_duration field
• Use production_deploy_date for target completion
• Show the calculated project dates

If only milestones.yaml is available:

• Sum all estimated_duration values
• Convert to appropriate unit (days/weeks)
• Note that this is an estimate without QA/PR time

If neither is available:

• Mark as "TBD" with instruction to run appropriate skill

Error Handling

File Not Found

If a required file doesn't exist in the expected location:

• Check alternative common locations (root directory as fallback)
• Display clear error with exact path tried
• Suggest which Sherpy skill generates that file

Invalid YAML

If a file exists but can't be parsed:

• Display parsing error
• Show the file path and line number if available
• Suggest checking file format or regenerating

Missing Required Fields

If a file is missing expected fields:

• Use sensible defaults or mark as "[Not Specified]"
• Continue generating summary with available data
• Note missing fields in the confirmation output

Output Location

Always output to: {base_directory}/summaries/developer-summary.md

If the directory doesn't exist, create it:

mkdir -p {base_directory}/summaries

Integration with Sherpy Flow

This skill is designed to be called as Step 10 in /sherpy-flow. When invoked by sherpy-flow, it receives base_directory as a parameter. It should:

• Run after all planning artifacts are complete
• Auto-discover files from the organized folder structure within base_directory
• Not fail if optional files (like timeline) are missing
• Generate the summary without user interaction when all files are present

Examples

See [references/example.md](references/example.md) for a complete sample developer summary.

Related Skills

• /executive-summary - Generate executive summary for stakeholders
• /sherpy-flow - Full planning workflow (includes this skill at the end)
• /implementation-planner - Generates the milestones.yaml used by this skill
• /delivery-timeline - Generates the timeline.yaml used by this skill

Developer Summary

Generated: 2026-04-16 14:32:15 UTC Project: Package Domain Registry Service

---

Overview

The Package Domain Registry Service is a centralized metadata management system for npm package domain validation and verification. It addresses the challenge of tracking ownership and security status across distributed package ecosystems by providing a single source of truth for package domain mappings. The system enables automated security scanning, ownership verification, and compliance reporting across the entire package supply chain.

---

Deliverables

API Endpoints

• POST /api/v1/domains - Register new domain
• GET /api/v1/domains/{id} - Retrieve domain details
• PUT /api/v1/domains/{id}/verify - Verify domain ownership
• GET /api/v1/packages/{name}/domain - Lookup package domain mapping
• POST /api/v1/scan/trigger - Trigger security scan

Domain Package Handlers

• DomainRegistrationHandler - Process domain registration requests
• DomainVerificationHandler - Handle DNS and file-based verification
• PackageDomainMapper - Map packages to verified domains
• SecurityScanHandler - Orchestrate vulnerability scans

Data Models

• Domain entity (id, name, owner, verification_status, created_at)
• Package entity (name, version, domain_id, scan_status)
• VerificationToken entity (domain_id, token, method, expires_at)
• ScanResult entity (package_id, severity, findings, scanned_at)

Infrastructure

• PostgreSQL database with TimescaleDB for time-series scan data
• Redis cache for domain lookup performance
• AWS SQS queue for async scan orchestration
• S3 bucket for verification file storage

Integrations

• npm Registry API - Package metadata sync
• Snyk API - Vulnerability scanning
• Auth0 - Authentication and authorization
• DataDog - Monitoring and alerting

Background Jobs

• DailySyncJob - Sync package metadata from npm
• VerificationExpiryJob - Expire unverified tokens after 7 days
• ScanSchedulerJob - Schedule periodic security scans
• MetricsAggregationJob - Roll up daily statistics

---

Milestones & Timeline

M0: Project Setup & Foundation

Duration: 1 week Dependencies: None Key Deliverable: Development environment, database schema, and CI/CD pipeline configured

M1: Domain Registration API

Duration: 2 weeks Dependencies: M0 Key Deliverable: Domain registration endpoints with basic CRUD operations

M2: Domain Verification System

Duration: 2 weeks Dependencies: M1 Key Deliverable: DNS and file-based verification workflows fully functional

M3: Package-Domain Mapping

Duration: 1.5 weeks Dependencies: M2 Key Deliverable: Package lookup API with Redis caching and npm sync job

M4: Security Scanning Integration

Duration: 2 weeks Dependencies: M3 Key Deliverable: Snyk integration with async scan orchestration via SQS

M5: Monitoring & Observability

Duration: 1 week Dependencies: M4 Key Deliverable: DataDog dashboards, alerts, and SLO monitoring

M6: Documentation & Deployment

Duration: 1 week Dependencies: M5 Key Deliverable: API documentation, runbooks, and production deployment

---

Summary

Total Milestones: 7 Estimated Total Duration: 10.5 weeks Target Completion: 2026-06-30 (production deploy)

---

For detailed implementation tasks, see `implementation/milestones.yaml` and task files in `implementation/tasks/`. For delivery timeline and QA plan, see `delivery/`.

Developer Summary Specification

Version: 1.0.0 Document Type: Markdown File Pattern: developer-summary.md Generated By: /developer-summary skill

---

1. Document Overview

Purpose

Provides developers with a quick-start view of what's being built, key deliverables, and the milestone roadmap. Synthesizes planning artifacts into a concise, actionable reference for developer onboarding and daily work.

Dependencies (Input Artifacts)

Required:

• requirements/business-requirements.yaml - Project overview and deliverables
• requirements/technical-requirements.yaml - Technical context and architecture
• implementation/milestones.yaml - Milestone sequence and estimates

Optional:

• delivery/timeline.yaml - Timeline estimates and target dates

Outputs (What Uses This)

• Developer onboarding documentation
• Team reference during implementation
• Quick-start guides for new contributors

---

2. File Format & Location

Format: Markdown (.md), UTF-8, LF line endings

Location: {base_directory}/summaries/developer-summary.md

Naming: Fixed filename, no versioning or date suffixes

---

3. Document Structure

Required Sections

3.1 Header Block

# Developer Summary

*Generated: YYYY-MM-DD HH:MM:SS UTC*
*Project: [project-name]*

---

Fields:

• Generated: ISO 8601 timestamp of generation
• Project: From business-requirements.yaml → project.name

3.2 Overview

## Overview

[Single paragraph, 3-5 sentences maximum, describing what's being built,
why it matters, and what it enables.]

---

Content Sources:

• business-requirements.yaml → description, business_goals.primary_goal
• technical-requirements.yaml → solution_overview, architecture.approach

Format Rules:

• Single paragraph (no bullet points)
• 3-5 sentences maximum
• Focus on what/why/how (high-level)
• Avoid implementation details

3.3 Deliverables

## Deliverables

### [Category 1]
- [Deliverable 1]
- [Deliverable 2]

### [Category 2]
- [Deliverable 1]
- [Deliverable 2]

---

Categories (use relevant subset):

• API Endpoints
• Domain Handlers
• UI Components
• Data Models
• Infrastructure
• Integrations
• Background Jobs
• Configuration

Content Sources:

• business-requirements.yaml → functional_requirements, scope.in_scope
• technical-requirements.yaml → architecture.components, data_model.entities, apis.endpoints, integration_points

3.4 Milestones & Timeline

## Milestones & Timeline

### M0: [Milestone Name]
**Duration:** [estimated duration]
**Dependencies:** None
**Key Deliverable:** [primary outcome]

### M1: [Milestone Name]
**Duration:** [estimated duration]
**Dependencies:** M0
**Key Deliverable:** [primary outcome]

---

Content Sources:

• implementation/milestones.yaml → all milestone entries
• delivery/timeline.yaml → total_duration, production_deploy_date (if available)

Format Rules:

• List milestones in sequence (M0, M1, M2...)
• Show dependencies clearly
• Extract "key deliverable" from milestone description or first success criterion

3.5 Summary

## Summary

**Total Milestones:** [count]
**Estimated Total Duration:** [duration]
**Target Completion:** [date or "TBD"]

---

*For detailed implementation tasks, see `implementation/milestones.yaml` and task files in `implementation/tasks/`.*
*For delivery timeline and QA plan, see `delivery/`.*

Fields:

• Total Milestones: Count from milestones.yaml
• Estimated Total Duration: Sum of milestone durations OR from timeline.yaml if available
• Target Completion: From timeline.yaml production_deploy_date or "TBD - run /delivery-timeline"

---

4. Generation Guidelines

Step 1: Discover Base Directory & Scan Artifacts

• If no directory provided, check for requirements/business-requirements.yaml in current directory
• If not found, prompt: "Where are your planning artifacts located?" and wait for response
• Display scan status showing which artifacts are found (✓) or missing (✗)

Step 2: Handle Missing Files

If required files missing, ask user to either: 1. Continue with partial data (mark missing sections as [Not Available]) 2. Exit and complete missing artifacts first

Step 3: Load and Parse Artifacts

Extract from available files:

• business-requirements.yaml: Project name, description, features, deliverables
• technical-requirements.yaml: Technology stack, architectural patterns, components
• milestones.yaml: Milestone sequence, names, dependencies, durations
• timeline.yaml (optional): Total duration, target completion date

Step 4: Generate Summary Document

Create summaries/developer-summary.md with:

• Overview: 3-5 sentence paragraph synthesizing what/why/how
• Deliverables: Categorized list from functional and technical requirements
• Milestones: Sequential roadmap with duration, dependencies, key deliverable
• Summary: Total count, estimated duration, target completion date

Step 5: Handle Missing Data

Insert clear placeholders for unavailable sections:

[Not Available - `milestones.yaml` not found. Run `/implementation-planner`]

Step 6: Confirmation

Display generation status with location, size, included sections, and missing data notes

---

5. Validation Rules

Required Sections

• [ ] Header block with timestamp and project name
• [ ] Overview section (non-empty)
• [ ] Deliverables section with at least one category
• [ ] Milestones & Timeline section with at least one milestone
• [ ] Summary section with metrics

Overview Validation

• [ ] Single paragraph format
• [ ] 3-5 sentences maximum
• [ ] No bullet points
• [ ] Describes what/why at minimum

Deliverables Validation

• [ ] At least one category present
• [ ] Each category has at least one deliverable
• [ ] Categories use standard names or are clearly domain-specific

Milestones Validation

• [ ] Listed in sequence (M0, M1, M2...)
• [ ] Each has: name, duration, dependencies, key deliverable
• [ ] Dependencies reference existing milestones

Summary Validation

• [ ] Total milestones count matches milestone list
• [ ] Duration is positive value or "TBD"
• [ ] Target completion is date or explicit "TBD" message

---

6. Error Handling

File Not Found

Error: Required file not found
Path: {base_directory}/requirements/business-requirements.yaml
Run: /business-requirements-interview

Invalid YAML

Error: Cannot parse requirements file
File: technical-requirements.yaml
Line: 42
Issue: Invalid YAML syntax

Missing Fields

• Use "[Not Specified]" for missing optional fields
• Continue generation with available data
• Note missing fields in confirmation

---

7. Integration Points

Input Skills:

• /business-requirements-interview, /technical-requirements-interview, /implementation-planner, /delivery-timeline

Usage: Developer onboarding, sprint planning reference, architecture review context

Sherpy Flow: Step 10, runs after all planning artifacts complete. Receives base_directory parameter, auto-discovers files, generates silently when all data present.

---

8. Example Structure

See /Users/kydavis/Sites/sherpy/docs/specifications/summaries/example-developer-summary.md for a complete example.

---

Version History

1.0.0 (2026-04-16)

• Initial specification
• Defines structure, generation logic, and validation rules
• Aligned with /developer-summary skill implementation