build-manifest

Build Manifest Generation

This skill provides templates and scripts for generating BUILD-GUIDE files (both JSON and Markdown) that show available commands organized by infrastructure layers.

Purpose

The BUILD-GUIDE is a layered execution blueprint that:

• Queries Airtable (as an index to marketplace plugins)
• Identifies available commands for the project's tech stack
• Organizes commands into sequential execution layers
• Detects gaps where tech is mentioned but no plugin exists
• Provides both machine-parseable (JSON) and human-readable (Markdown) formats

When to Use This Skill

Use this skill when:

• Initializing a new project after /planning:wizard completes
• Architecture docs exist with tech stack identified
• Need to generate a build execution plan
• Want to see what commands are available for the detected stack
• Need to identify missing plugins for technologies mentioned in specs

Layer Structure

BUILD-GUIDE organizes commands into sequential layers:

Layer 1: Infrastructure Foundation

• Core project setup (detection, specs, worktrees)
• Same for most projects
• Plugins: foundation, planning, supervisor

Layer 2: Tech Stack Initialization

• Initialize detected frameworks
• Dynamic based on project files (README, roadmap/*.json, specs/)
• Plugins: Project-specific (nextjs-frontend, fastapi-backend, supabase, etc.)

Layer 3: Feature Implementation

• Build features from specs
• Reference spec files
• Use commands + agents from detected plugins

Layer 4: Quality & Deployment

• Testing, validation, deployment
• Plugins: quality, deployment, versioning

Templates

JSON Template

Location: templates/BUILD-GUIDE.json.template

Shows the complete JSON structure with:

• Tech stack detection results
• Layered command organization
• Gap detection for missing plugins
• Available/unavailable status per command

Markdown Template

Location: templates/BUILD-GUIDE.md.template

Human-readable version with:

• Tech stack summary
• Commands grouped by layer
• Usage examples
• Gap warnings

Scripts

generate-manifest.py

Location: scripts/generate-manifest.py

Purpose: Query Airtable and generate BUILD-GUIDE files

Usage:

python scripts/generate-manifest.py \
  --project files (README, roadmap/*.json, specs/)/architecture/README.md \
  --output BUILD-GUIDE

Process:

1. Read project files (README, roadmap/*.json, specs/) to detect tech stack
2. Query Airtable for plugins matching detected technologies
3. Query Airtable for commands in those plugins
4. Organize commands into layers
5. Detect gaps (tech mentioned but no plugin exists)
6. Generate both .json and .md files

Requirements:

• AIRTABLE_TOKEN environment variable
• Architecture docs must exist
• Airtable base ID: appHbSB7WhT1TxEQb

Examples

Example Output Structure

See examples/BUILD-GUIDE.json for complete Next.js + FastAPI + Supabase example See examples/BUILD-GUIDE.md for markdown version

Example Gap Detection

{
  "gaps": [
    {
      "technology": "Redis",
      "mentioned_in": "docs/architecture/caching.md",
      "reason": "No redis plugin found in any marketplace",
      "suggestion": "Create redis plugin with /domain-plugin-builder:build-plugin redis"
    }
  ]
}

Integration with build-manifest-generator Agent

The build-manifest-generator agent in this plugin uses this skill:

!{skill planning:build-manifest}

The agent:

1. Invokes this skill to load templates
2. Uses scripts to query Airtable
3. Generates BUILD-GUIDE.json and BUILD-GUIDE.md
4. Places files at project root

Output Files

BUILD-GUIDE.json:

• Machine-parseable
• Complete structure with metadata
• Used by Claude when user requests features
• Location: Project root

BUILD-GUIDE.md:

• Human-readable
• Summary format
• Documentation reference
• Location: Project root

Security

All templates use placeholder format:

• your_service_key_here for API keys
• Environment variable references in code examples
• No hardcoded credentials

Validation

The skill validates:

• Architecture docs exist and are readable
• Airtable connection successful
• All detected plugins have valid commands
• Generated JSON is valid
• Generated Markdown renders correctly

Usage Pattern

Typical workflow:

# 1. Planning wizard creates project files (README, roadmap/*.json, specs/)
/planning:wizard

# 2. Generate build manifest
/planning:generate-build-guide  # Uses this skill

# 3. Reference during development
# Claude reads BUILD-GUIDE.json when user says "add authentication"
# Claude sees: /supabase:add-auth available

Maintenance

When adding new plugins to marketplaces:

1. Plugin metadata syncs to Airtable automatically (via sync scripts)
2. Regenerate BUILD-GUIDE for existing projects: /planning:generate-build-guide --refresh
3. New commands appear in Layer 2 (Tech Stack Initialization)