App Spec Generator

Overview

Automatically scan feature specification folders, parse implementation plans, calculate completion percentages from markdown checkboxes, and generate comprehensive app-specs.md documentation with progress tracking, categorization, and status dashboards.

This skill transforms scattered feature specifications into a single source of truth with visual progress indicators, making it easy to track project completion and share status with stakeholders.

Core Capabilities

1. Scanning & Parsing

Recursively scan project spec directories to:

• Find requirements.md and implementation-plan.md files
• Extract titles, descriptions, and metadata from markdown
• Count checkboxes ([x] vs [ ]) to calculate completion percentages
• Infer categories from folder names (GitHub, UX, Performance, etc.)
• Identify supplementary documentation

2. Progress Tracking

Analyze implementation status across all features:

• Calculate per-feature completion percentages from checkboxes
• Determine overall project completion metrics
• Track features by status: ✅ Completed, 🟡 In Progress, ⏳ Planned
• Generate category-wise progress breakdowns
• Extract effort estimates and target dates when available

3. Documentation Generation

Create structured app-specs.md with these sections:

• Status Dashboard - Progress table organized by category
• Table of Contents - Quick navigation to all sections
• Feature Lists - Grouped by status (completed, in-progress, planned)
• Tech Stack - Dependencies extracted from package.json
• Database Schema - Models extracted from Prisma schema
• Detailed Specs - Per-feature breakdowns with implementation links

4. Archive & Cleanup (Optional)

Safely consolidate documentation with these safety features:

• Archive all spec folders to timestamped directory before any changes
• Validate archive completeness before cleanup proceeds
• Remove original spec folders only after verification
• Create symlink to latest archive for easy access
• Automatic rollback if cleanup fails

Quick Start

Using the Slash Command

The recommended way to use this skill:

/update-specs

This scans spec folders in /specs/, generates app-specs.md, and leaves original folders intact (non-destructive mode).

Direct Script Execution

Run the TypeScript script manually:

tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts

With Cleanup Mode (Destructive)

⚠️ Warning: Archives and removes spec folders after generation.

tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts --cleanup

Use cleanup mode only when consolidating all documentation into the single app-specs.md file.

Expected Directory Structure

The generator expects this structure:

project-root/
├── perseon/
│   └── specs/
│       ├── feature-1/
│       │   ├── requirements.md
│       │   └── implementation-plan.md
│       ├── feature-2/
│       │   ├── requirements.md
│       │   └── implementation-plan.md
│       └── app-specs.md          ← Generated output
├── package.json                   ← Optional: for tech stack
└── prisma/
    └── schema.prisma              ← Optional: for database schema

Categories

Features are automatically categorized based on folder names:

Status Recognition

The parser recognizes these status indicators in markdown:

• ✅ Completed - 100% checkboxes completed or ✅ emoji in title
• 🟡 In Progress - Some checkboxes completed or 🟡 emoji
• ⏳ Planned - No checkboxes completed or ⏳ emoji
• ❌ Not Started - No content or ❌ emoji

Checkbox format must be: - [x] (completed) or - [ ] (pending) with space between - and [.

Workflow

When a user asks to update specs or generate documentation:

1. Verify prerequisites: Check that tsx is installed globally
2. Confirm spec directory: Verify /specs/ exists or ask for custom path
3. Run scanner: Execute the update script (non-destructive by default)
4. Show summary: Display features processed, completion percentage, status breakdown
5. Cleanup (optional): Only if user explicitly requests archival and removal

Default Mode (Non-Destructive)

tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts

Generates or updates app-specs.md without modifying spec folders.

Cleanup Mode (Destructive)

Ask user for explicit confirmation before running:

tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts --cleanup

Explain that this will:

• Archive all spec folders to /specs/.archive/[timestamp]/
• Remove original spec folders from /specs/
• Leave only app-specs.md as the documentation source

TypeScript Modules

The skill includes these core modules in scripts/:

• types.ts - TypeScript interfaces and type definitions
• scanner.ts - Directory scanning, file operations, archiving, cleanup
• parser.ts - Markdown parsing, checkbox counting, metadata extraction
• generator.ts - Document generation, template rendering, validation
• index.ts - Main orchestrator coordinating all operations
• update.ts - CLI entry point with argument parsing

Additional Resources

Reference Files

For detailed configuration and advanced usage, consult:

• references/configuration.md - Custom paths, categories, exclusions
• references/output-format.md - Generated document structure details
• references/troubleshooting.md - Common issues and solutions
• references/advanced-usage.md - Programmatic API and customization

Script Files

Implementation scripts available in scripts/:

• All TypeScript modules for scanning, parsing, and generation
• Requires Node.js 18+ and tsx runtime

Safety Features

When using cleanup mode, these protections activate:

✅ Archive First - All folders backed up before deletion ✅ Validation - Archive checked for completeness ✅ Exclusions - Critical folders never deleted ✅ Rollback - Automatic restoration if cleanup fails ✅ Atomic Operations - Completes fully or rolls back entirely

Archive location: /specs/.archive/[timestamp]/

Best Practices

1. Run regularly: Update after completing features or at sprint end
2. Non-destructive first: Use default mode until ready to consolidate
3. Verify output: Review generated app-specs.md before cleanup
4. Use version control: Commit before running cleanup mode
5. Check prerequisites: Ensure tsx is installed globally

Prerequisites

• Node.js 18+ - Required for TypeScript execution
• tsx - TypeScript runtime (npm install -g tsx or pnpm add -g tsx)
• Spec directory - Organized feature folders with markdown files