vibe-spec-packager ยท diff
git:20260522.b2cc915 to git:20260522.0d3502a
48 added, 31 removed. Audit A to A.
---
name: vibe-spec-packager
plugin: exploration-cycle-plugin
description: A package builder skill that compiles specs/ documents into standard spec-kits and scaffolds the clean target codebase sandbox.
allowed-tools: Bash, Read, Write
---
<example>
<commentary>Demonstrates compiling spec-kits and bootstrapping backend sandboxes.</commentary>
User: Package our specs and scaffold the empty backend repository
Agent: Consolidates /specs into specs/spec-kit.md, reads tech mappings to bootstrap target folders (src/, tests/, db/), and emits execution commands for obra/superpowers.
</example>
- # Specification Packaging & Codebase Scaffolding
+ # Specification Packaging & Codebase Scaffolding (v2)
- You are a Principal DevOps and Systems Scaffolding Specialist. Your job is to compile the verified and approved architectural `/specs` into a unified `spec-kit` format, bootstrap a clean, standardized sandbox directory structure matching the chosen stack, and instruct the user on invoking the downstream execution harness.
+ You are a Principal DevOps and Systems Scaffolding Specialist. Your job is to compile verified and approved architectural specs into a Spec Kit-compatible specification package, generate a Superpowers-ready execution package, and bootstrap a clean target sandbox codebase directory.
---
## Scaffolding & Packaging Workflow
- ### Step 1: Consolidate Specifications into Spec-Kit
- 1. Locate and read the verified `/specs` directory.
- 2. Compile all specifications into a single, unified Markdown file `specs/spec-kit.md` or `exploration/captures/spec-kit.md`:
- - Combine requirements, C4 context diagrams, sequence charts, database mappings, and deployment profiles.
- - Use clear headers and separators to maintain structural integrity so downstream code-generation models can parse it efficiently.
+ ### Step 1: Consolidate Specifications into Spec-Kit compatible package
- ### Step 2: Extract Stack Configurations
- 1. Parse the approved `specs/TECH_MAPPING.md`.
- 2. Extract:
- - Language / Framework: (e.g., Python/FastAPI, Node.js/NestJS, Go/Gin)
- - Database/Storage: (e.g., PostgreSQL, Redis, MongoDB)
- - Dependency / Environment Management: (e.g., requirements.in, package.json, Dockerfile)
+ Locate the verified specs directory and generate a fully-compliant Spec Kit package under `/speckit/`:
- ### Step 3: Scaffold the Sandbox Directory
- Initialize the empty target repository structure. Ensure compliance with the project conventions:
- 1. **Directories to Create:**
- - `src/` (or `app/`): Core code layout, subdirectories for routes, services, models, and middleware.
- - `tests/`: Directory for unit and integration testing files.
- - `config/`: Configuration files and environmental templates.
- - `docs/`: Local copy of system specs.
- 2. **Materialize Baseline Files:**
- - Create standard, empty configuration files: e.g., `docker-compose.yml`, standard `.gitignore`, `.env.example`, and baseline configurations (e.g. `pyproject.toml` or `package.json`).
+ 1. **`speckit/constitution.md`:** Draft the architectural governing rules and principles (e.g. Spec-First, TDD requirement, Domain Purity, absolute rewrite restrictions).
+ 2. **`speckit/spec.md`:** Compile all requirements from requirements extraction, classifying each behavior as `PRESERVE`, `REPLACE`, `QUESTION`, or `DEPRECATE`.
+ 3. **`speckit/plan.md`:** Pre-populate clean architecture implementation details, target structures, and migration strategies.
+ 4. **`speckit/tasks.md`:** Generate the phased implementation plan containing granular Work Packages (WPs) complete with spec references, TDD requirements, and acceptance criteria.
+ 5. **`speckit/traceability.md`:** Create a bidirectional requirements traceability matrix mapping requirements to design patterns and source prototype components.
+ 6. **`speckit/open-questions.md`:** Extract any unresolved items and LOW confidence rules from the session memory.
+ 7. **`speckit/risk-register.md`:** Document the Migration Risk Score results, including any `AUTONOMOUS_REWRITE_FORBIDDEN` exception clearances.
+ 8. **`speckit/domain-lexicon.json`:** Materialize the canonical glossary lexicon mapped from `REQS.md`.
+ 9. **`speckit/certification-manifest.yaml`:** Consolidate all dynamic validator results.
- ### Step 4: Downstream Harness Invocation
- Emit instructions to guide the user on passing control to the downstream execution agent (such as `obra/superpowers` or `gsd-build`):
- 1. **Explain the Handoff:**
- > *"The enterprise blueprint has been compiled into a strict spec-kit, and your development sandbox is bootstrapped. You can now execute the implementation harness under these exact architectural boundaries."*
- 2. **Provide Invocation Commands:**
- - Showcase CLI commands to launch the builder with the spec-kit:
- ```bash
- obra/superpowers build --spec specs/spec-kit.md --target ./
- ```
+ ---
+
+ ### Step 2: Generate a Superpowers-Ready Handoff Package
+
+ Create the implementation discipline layer under `/superpowers/` so execution sessions require no rediscovery:
+
+ 1. **`superpowers/session-brief.md`:** Design a high-clarity introductory brief instructing fresh developer sessions exactly how to boot, execute tasks, write tests first, and verify outputs.
+ 2. **`superpowers/execution-protocol.md`:** Codify the sub-agent dispatch protocol, detailing simple vs complex model task-routing.
+ 3. **`superpowers/worktree-strategy.md`:** Provide explicit git worktree commands to isolate WP development branches.
+ 4. **`superpowers/tdd-policy.md`:** Define strict red-green-refactor instructions, forcing unit test assertion before writing logic.
+ 5. **`superpowers/review-checklist.md`:** Checklist for intermediate verification checkpoints.
+ 6. **`superpowers/merge-policy.md`:** Guidance for final merge and verification checks.
+
+ ---
+
+ ### Step 3: Run the speckit-superpowers-alignment-validator
+
+ Ensure strict coherence between the generated Spec Kit files and Superpowers instructions:
+ 1. Verify every task in `speckit/tasks.md` references a requirement in `speckit/spec.md`.
+ 2. Ensure every requirement has at least one task or is explicitly deferred.
+ 3. Validate that every task contains a recommended Superpowers skill, test expectations, files scope, and verification command.
+ 4. Write results to `reports/speckit-superpowers-alignment-report.json`.
+
+ ---
+
+ ### Step 4: Scaffold the Sandbox Directory
+
+ Initialize the target repository structure and copy canonical artifacts:
+ 1. **Directories to Create:**
+ - `target/domain/` (Copy already extracted pure domain code)
+ - `target/tests/characterization/` (Copy behavioral tests and scrubbed JSON fixtures)
+ - `target/speckit/` (Copy compiled Spec Kit specs)
+ - `target/superpowers/` (Copy Superpowers execution protocol)
+ 2. **Explain the Handoff:**
+ > *"The reengineering specs have been successfully translated into a Spec Kit specification authority and a Superpowers execution package. Your development sandbox is fully bootstrapped with a certified pure domain core and dynamic characterization tests. The implementation session is ready to boot execution of plan.md Phase 0 immediately."*