shipkit-communications

Purpose: Create beautiful, visual HTML reports from any ShipKit Lite content for presentations, sharing, or visual review.

What it does: Reads markdown content from .shipkit/, generates styled HTML with purple gradient theme, archives old reports, creates latest.html.

---

When to Invoke

User triggers:

• "Visualize the architecture decisions"
• "Create HTML report"
• "Make a visual status report"
• "Generate presentation from project status"
• "Show me quality checklist as HTML"
• "Create shareable report"

Use cases:

• Share architecture decisions with team
• Present project status to stakeholders
• Visual review of quality checklist
• Export component documentation as HTML
• Create visual specs for review

---

Prerequisites

Optional (depends on what user wants to visualize):

• .shipkit/architecture.json - For architecture decisions
• .shipkit/codebase-index.json - For component/route docs
• .shipkit/stack.json - For tech stack overview
• .shipkit/specs/{todo,active}/*.json - For specs
• .shipkit/plans/{todo,active}/*.json - For implementation plans

No strict prerequisites - Can create HTML from any content.

---

Process

Step 1: Ask What to Visualize

Before generating anything, ask user what they want to visualize:

Present options:

What would you like to visualize as HTML?

1. Architecture Decisions - Visual timeline of decisions
2. Project Status - Complete health dashboard
3. Quality Checklist - Pre-ship verification
4. Component Documentation - All components/routes
5. Feature Specs - Active specifications
6. Implementation Plans - Current plans
7. Tech Stack - Visual stack overview
8. Custom - You specify the files

Choose a number or describe what you need:

Wait for user response.

---

Step 2: Determine Source Files

Based on user choice, identify which .shipkit/ files to read:

| Choice | Files to Read | Description Word | |--------|---------------|------------------| | 1. Architecture Decisions | .shipkit/architecture.json | architecture-decisions | | 2. Project Status | Glob .shipkit/**/*.json | project-health | | 3. Quality Checklist | .shipkit/codebase-index.json, .shipkit/specs/{todo,active}/*.json | quality-checklist | | 4. Component Documentation | .shipkit/codebase-index.json | component-docs | | 5. Feature Specs | .shipkit/specs/{todo,active}/*.json | feature-specs | | 6. Implementation Plans | .shipkit/plans/{todo,active}/*.json | implementation-plans | | 7. Tech Stack | .shipkit/stack.json | tech-stack | | 8. Custom | User-specified files | User-specified description |

Description word: Used for archive filename (2-4 kebab-case words)

---

Step 3: Read Source Content

Use Read tool to load source markdown files.

FOR COMPREHENSIVE REPORTS (Project Status), USE PARALLEL READS:

Launch these Read operations IN PARALLEL (single message, multiple tool calls):

1. Read: .shipkit/architecture.json
2. Read: .shipkit/stack.json
3. Read: .shipkit/codebase-index.json
4. Read: .shipkit/schema.json
5. Glob + Read: .shipkit/specs/{todo,active}/*.json
6. Glob + Read: .shipkit/plans/{todo,active}/*.json

Why parallel: All file reads are independent - no dependencies between them. Parallel reads significantly speed up comprehensive report generation.

Examples for single-source reports:

For architecture decisions:

Read: .shipkit/architecture.json

For quality checklist:

Read: .shipkit/codebase-index.json
Glob: .shipkit/specs/{todo,active}/*.json

IMPORTANT: Actually read files - don't generate placeholder content.

---

Step 4: Check for Existing latest.html

Check if .shipkit/communications/latest.html already exists:

If latest.html exists:
  1. Get current timestamp: YYYYMMDD-HHMM format
  2. Create archive filename: YYYYMMDD-HHMM-{description}.html
     Example: 20251228-1430-architecture-decisions.html
  3. Use Read tool to read latest.html content
  4. Use Write tool to create archive:
     Path: .shipkit/communications/archive/{timestamp}-{description}.html
     Content: [contents of old latest.html]
  5. Proceed to generate new latest.html

If latest.html does NOT exist:
  1. Proceed directly to generate new latest.html

Archive naming examples:

• 20251228-1430-architecture-decisions.html
• 20251228-1515-project-health.html
• 20251228-1620-quality-checklist.html

---

Step 5: Generate HTML

Create beautiful, styled HTML using the template structure.

Complete HTML template: See references/html-template.md

Key template features:

• Purple gradient theme (#667eea → #764ba2)
• Responsive design (mobile-friendly)
• Mermaid.js support via CDN
• Inline CSS (no external dependencies)
• Clean typography and spacing

Template variables to replace:

• {Report Title} - Main title
• {Report Subtitle} - Subtitle
• {Current DateTime} - Full timestamp
• {Current Date} - Date only
• {CONVERTED MARKDOWN CONTENT HERE} - HTML-converted content

Content Conversion Rules:

1. Markdown to HTML: Convert markdown content to semantic HTML

   • # Header → <h2>
   • ## Header → <h3>
   • ### Header → <h4>
   • **bold** → <strong>
   • *italic* → <em>
   • Lists → <ul> / <ol>
   • Code blocks → <pre><code>
   • Inline code → <code>
   • Tables → <table>

2. Special Sections: Wrap important sections in cards

   • Decisions → .card div
   • Warnings → .card with warning style
   • Key points → .card

3. Mermaid Diagrams: Detect markdown code blocks with mermaid language:

   ```mermaid
   graph TD
   A --> B
   ```
   

   Convert to:

   <div class="mermaid">
   graph TD
   A --> B
   </div>
   

4. Timestamps: Use current datetime in header

Report Title Examples:

• "Architecture Decisions"
• "Project Status Dashboard"
• "Quality Confidence Report"
• "Component Documentation"

---

Step 6: Write latest.html

Use Write tool to create:

Location: .shipkit/communications/latest.html

Content: Complete HTML generated in Step 5

Example Write call:

Write tool:
  File: .shipkit/communications/latest.html
  Content: [Full HTML from Step 5]

---

Step 7: Confirm to User

After creating HTML, tell user:

✅ Visual HTML report created

📁 Location: .shipkit/communications/latest.html

📊 Report type: {Description}

{IF ARCHIVED}
🗄️  Previous report archived:
   .shipkit/communications/archive/{timestamp}-{description}.html
{END IF}

👉 Open latest.html in your browser to view the report.

---

Workspace Structure

This skill creates:

.shipkit/
  communications/
    latest.html                                    # Always current report
    archive/
      20251228-1430-architecture-decisions.html   # Previous reports
      20251228-1515-project-health.html
      20251228-1620-quality-checklist.html

Always one latest.html - Easy to find current report

Archive preserves history - Never lose previous visualizations

---

Completion Checklist

Copy and track:

• [ ] Identified source content to visualize
• [ ] Generated HTML with appropriate styling
• [ ] Saved to appropriate location

---

Content Type Examples

1. Architecture Decisions

Source: .shipkit/architecture.json

Converts to: Visual timeline with cards for each decision, showing:

• Decision date
• What was decided
• Rationale
• Alternatives considered

Good for: Team alignment, onboarding, documentation

---

2. Project Status Dashboard

Source: All .shipkit/**/*.json files

Converts to: Comprehensive dashboard with:

• Tech stack summary
• Active specs (count + list)
• Implementation plans (count + list)
• Recent decisions
• Component inventory

Good for: Stakeholder updates, weekly reviews

---

3. Quality Checklist

Source: .shipkit/codebase-index.json + specs

Converts to: Interactive checklist with:

• All components listed
• Acceptance criteria per spec
• Implementation status
• Quality gates

Good for: Pre-ship reviews, QA handoff

---

4. Component Documentation

Source: .shipkit/codebase-index.json

Converts to: Component catalog with:

• Each component in a card
• Props/interfaces
• Usage examples
• File locations

Good for: Developer reference, onboarding

---

Integration with Other Skills

Before shipkit-communications:

• Any skill that creates .shipkit/ content
• Examples:
  • /shipkit-engineering-definition → Visualize decisions
  • verify manually → Visualize checklist
  • document components manually → Visualize docs

After shipkit-communications:

• Share HTML with team
• Present in meetings
• Continue current workflow

When to use:

• Need visual format for presentation
• Sharing with non-technical stakeholders
• Want shareable artifact (email, Slack, etc.)
• Prefer visual review over markdown

---

Context Files This Skill Reads

Depends on visualization type (see Step 2):

• .shipkit/architecture.json - Architecture decisions
• .shipkit/codebase-index.json - Components/routes
• .shipkit/stack.json - Tech stack
• .shipkit/specs/{todo,active,parked,shipped}/*.json - Specifications
• .shipkit/plans/{todo,active,parked,shipped}/*.json - Implementation plans
• Any .shipkit/**/*.json - Custom/comprehensive

Lazy loading: Only reads what's needed for chosen visualization

---

Context Files This Skill Writes

Run-scoped output (parallel-safe). communications/ is a transient artifact. When running under the orchestration engine, write under the run root (<runDir>/communications/…) per install/shared/references/run-artifacts.md; with no run context it stays at .shipkit/communications/… (back-compatible). Readers resolve the same base.

Creates/Updates:

• .shipkit/communications/latest.html - OVERWRITE AND REPLACE
  • Write Strategy: OVERWRITE AND REPLACE
  • Behavior: Always contains most recent visualization
  • Why: "latest" means current - old versions go to archive

Archives:

• .shipkit/communications/archive/{timestamp}-{description}.html - APPEND
  • Write Strategy: APPEND (create new file)
  • Behavior: Archives old latest.html before overwriting
  • Why: Preserve history, never lose previous visualizations

Never modifies source files: All .shipkit/*.json context files are read-only inputs

---

<!-- SECTION:after-completion -->

After Completion

Guardrails Check: Before moving to next task, verify:

1. Persistence - Has important context been saved to .shipkit/?
2. Prerequisites - Does the next action need a spec or plan first?
3. Session length - Long session? Consider /shipkit-work-memory for continuity.

Natural capabilities (no skill needed): Implementation, debugging, testing, refactoring, code documentation.

Suggest skill when: User needs to make decisions, create persistence, or check project status.

<!-- /SECTION:after-completion --> <!-- SECTION:success-criteria -->

Success Criteria

Visualization is complete when:

• [ ] User specified what to visualize
• [ ] Source files read successfully
• [ ] Old latest.html archived (if existed)
• [ ] New latest.html created
• [ ] HTML renders correctly in browser
• [ ] Mermaid diagrams render (if present)
• [ ] Styling matches ShipKit Lite purple theme
• [ ] Mobile-responsive
• [ ] User knows where to find latest.html

<!-- /SECTION:success-criteria -->

---

Common Scenarios

Scenario 1: Architecture Decisions for Team Review

User: "Visualize the architecture decisions"

Claude:
1. Ask confirmation (already clear)
2. Read: .shipkit/architecture.json
3. Check for latest.html (exists)
4. Archive old: archive/20251228-1430-architecture-decisions.html
5. Generate HTML with:
   - Timeline of decisions
   - Each decision as a card
   - Rationale highlighted
   - Alternatives in tables
6. Write: latest.html
7. Confirm: "✅ Architecture decisions visualized. Open .shipkit/communications/latest.html"

Scenario 2: Project Status for Stakeholders

User: "Create HTML report for weekly update"

Claude:
1. Ask: "What type of report?"
2. User: "Project status"
3. Glob: .shipkit/**/*.json
4. Read all markdown files
5. No existing latest.html (first time)
6. Generate comprehensive dashboard HTML
7. Write: latest.html
8. Confirm: "✅ Project status dashboard created"

Scenario 3: Quality Checklist Before Launch

User: "Show me quality checklist as HTML"

Claude:
1. Ask confirmation
2. Read: codebase-index.json + specs/{todo,active}/*.json
3. Check latest.html (exists)
4. Archive: archive/20251228-1620-quality-checklist.html
5. Generate checklist HTML with:
   - All acceptance criteria
   - Component verification
   - Quality gates
6. Write: latest.html
7. Confirm with next steps

---

Tips for Effective Visualizations

Choose the right type:

• Architecture decisions → Best for team alignment
• Project status → Best for stakeholder updates
• Quality checklist → Best for pre-ship reviews
• Component docs → Best for developer reference

When to regenerate:

• After significant changes to source content
• Before team meetings/presentations
• Weekly for status updates
• Before sharing with stakeholders

Archive benefits:

• Compare how project evolved over time
• Reference past visualizations
• Track decision-making history
• Never lose previous reports

Sharing tips:

• latest.html is self-contained (inline CSS)
• No external dependencies (except Mermaid CDN)
• Works offline after initial load
• Email-friendly (single file)
• Mobile-responsive for phone viewing

---

Markdown to HTML Conversion Guide

Quick reference:

• Headers: # → <h2>, ## → <h3>, ### → <h4>
• Emphasis: **bold** → <strong>, *italic* → <em>, `code` → <code>
• Lists: - → <ul><li>, 1. → <ol><li>
• Code blocks with language support
• Tables with header/body structure
• Mermaid diagrams: ```mermaid → <div class="mermaid">

---

Remember: This skill is about making ShipKit Lite content beautiful and shareable. Always read actual content, never generate placeholders. Archive old reports to preserve history.