spec2cloud

Create Domain-Driven Design proposals from product specs or brownfield extraction outputs. Define bounded contexts, ubiquitous language, aggregates, context maps, and Mermaid-based domain and database diagrams. Use when domain boundaries, business rules, or data ownership need to be explicit before planning, implementation, or modernization.

Identify, research, and resolve every technology needed by the application. Evaluate data storage, caching, AI/ML, authentication, real-time, search, infrastructure, and library choices. Use when resolving technology decisions, comparing framework options, or documenting the tech stack before implementation begins.

Write application code to make failing tests pass using contract-driven, slice-based architecture. Implement API slice (Express routes, services), Web slice (Next.js pages, components), and Integration slice (wire API+Web via Aspire). Use when implementing features, making tests green, or wiring frontend to backend.

Generate a Product Requirements Document (PRD) from analyzed codebase extraction data. Reverse-engineer the product vision, user personas, and feature list from what the code actually implements. Used in brownfield workflows to produce a spec2cloud-compatible PRD that drives downstream FRD generation, increment planning, and implementation.

Review PRDs and FRDs through product and technical lenses. Identify gaps, ambiguities, edge cases, and conflicts. Break approved PRDs into FRDs. Use when refining specifications, reviewing PRDs, creating FRDs, or validating spec quality before downstream phases.

Extract API contracts from existing code — routes, endpoints, request/response schemas, authentication patterns. Output in the same OpenAPI-compatible YAML format used by the contract-generation skill. Pure extraction — document the API surface that exists in code without judgment or suggestions.

Map application architecture — components, layers, data flow, and integration points. Produce Mermaid diagrams. Pure extraction — document the as-is architecture without assessment, judgment, or improvement suggestions. Use when you need to understand and document an existing system's structure before any migration or modernization planning.

Append structured entries to .spec2cloud/audit.log for every significant action. Never overwrite, always append. Use when logging task execution, increment transitions, human gate events, or errors.

Provision Azure infrastructure, deploy to Azure Container Apps, and verify via smoke tests. Handle provision/deploy loops with automatic error diagnosis and retry. Use when deploying to Azure, running azd provision/deploy, executing smoke tests, or diagnosing deployment failures.

Lightweight entry point for fixing bugs with full traceability. Takes a bug report, links to the relevant FRD, generates a failing test, fixes the code, and ships. Tracked as a micro-increment. Use when fixing bugs with test-first methodology and spec2cloud pipeline traceability.

Verify that all project services (API and Web) build successfully. Check compilation errors, type errors, and lint warnings. Use before running tests, before deployment, after code changes, and on resume. Trigger when build verification, compilation check, or pre-test validation is needed.

Assess application readiness for cloud-native deployment. Evaluate against 12-factor app principles, containerization readiness, and Azure service fit. Adaptive depth.

Plan the journey to cloud-native deployment on Azure. Generate increments for containerization, configuration externalization, infrastructure-as-code, observability, CI/CD, and Azure service provisioning. Each increment feeds into the standard Phase 2 delivery pipeline.

Scan project structure, detect languages and frameworks, identify entry points and application boundaries. Pure extraction — document what exists with zero judgment, zero assessment, zero recommendations. Use when you need a factual inventory of a project's technology footprint before any migration, assessment, or modernization work begins.

Create standardized git commits at phase and increment boundaries. Defines commit procedures, message formats, and state bundling. Use when committing after phase completion, increment delivery, or slice implementation.

Extract database schemas, data models, and entity relationships from code. Produce Mermaid ERD diagrams. Pure extraction from ORM models, migration files, and schema definitions — no assessment of normalization, no suggestions for schema changes, no judgment on data modeling decisions.

Create a complete inventory of all project dependencies with versions, purposes, and relationship mapping. Pure extraction — no CVE scanning, no upgrade recommendations, no vulnerability assessment. Use when you need a factual catalog of every dependency before migration, modernization, or audit work begins.

Generate Playwright end-to-end test specs and Page Object Models from UI/UX flow walkthroughs. Create complete user journey tests that exercise navigation, forms, and interactions. Use when scaffolding e2e tests, creating POMs, or generating Playwright specs for user flows.

Plan new feature additions to an existing application. Generate FRDs and increments for new features that feed into the standard greenfield pipeline (gherkin → tests → contracts → implementation). Use when adding capabilities to a brownfield application.

Generate Feature Requirement Documents (FRDs) from codebase analysis. Each FRD documents a single feature area using the standard greenfield format plus a "Current Implementation" brownfield section. Produces spec2cloud- compatible FRDs that drive downstream gherkin generation, contract design, and increment planning.

Generate comprehensive Gherkin scenarios from approved FRDs. Produce feature files with acceptance criteria coverage, edge cases, and error handling scenarios. Use when creating BDD scenarios, writing feature files, or mapping FRD requirements to testable Gherkin specifications.

Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements. Adaptive depth — starts surface-level, escalates based on findings. Produces ADRs for significant decisions.

Create a prioritized modernization roadmap from assessment findings. Generate increments that go through the standard test-contract-implement-deploy pipeline. Each increment is a self-contained modernization unit. Use when transforming assessment results into actionable, ordered work items.

Identify performance bottlenecks, inefficient patterns, and optimization opportunities through static analysis. Adaptive depth.

Resume a spec2cloud session from saved state. Read state.json, determine position, re-validate by running tests, handle human edits during pause. Use at CLI session start, after interruption, or when continuing work from a previous session.

Assess feasibility and effort of rewriting the application in a different language, framework, or architecture. Compare current stack against target stack. Produce ADRs for rewrite vs modernize decision.

Plan a component-by-component rewrite from one stack to another using the strangler fig pattern. Each increment rewrites one component while keeping the rest running. Use when migrating between technology stacks incrementally.

Audit codebase for security vulnerabilities, insecure patterns, and compliance gaps. Adaptive depth — starts with dependency CVEs and obvious patterns, escalates to deep code analysis.

Create a prioritized security remediation plan from security assessment findings. Critical vulnerabilities first, then hardening improvements. Generate increments that feed into the standard Phase 2 delivery pipeline. Use when transforming security assessment results into actionable fix items.

Read, write, and maintain .spec2cloud/state.json across phases and increments. Defines the state schema, read/write protocol, and resume re-validation logic. Use when reading project state, updating state after task completion, or resuming from a previous session.

Catalog existing tests — discover test frameworks, count tests by type, parse coverage reports, and map test-to-feature relationships. Pure discovery — no gap analysis, no recommendations for new tests, no assessment of test quality. Use when you need a factual inventory of the testing landscape before migration or modernization planning.

Generate BDD test code from Gherkin scenarios. Create Cucumber step definitions with real test code (HTTP calls, Playwright interactions) and Vitest unit tests. Produce a red baseline where all tests compile and fail. Use when scaffolding BDD tests, creating step definitions, or generating unit tests from feature files.

Execute the appropriate test suite (unit, Gherkin, e2e, smoke) and return structured results. Use during Phase 3 (e2e test verification), Phase 4 (red baseline verification), Phase 5 (contract type compilation), Phase 6 (API/Web/integration slices), Phase 7 (smoke tests against deployment), and on resume (re-validate test state). Trigger when running tests, checking test status, or verifying test baselines.

Generate interactive HTML wireframe prototypes from approved FRDs. Produce screen maps, design systems, component inventories, and replayable walkthroughs. Serve prototypes for human review via HTTP server. Use when creating UI/UX designs, building prototypes, or iterating on visual design.

Generate API contracts, shared TypeScript types, and infrastructure resource definitions from Gherkin scenarios and test files. Produce the stable foundation for parallel frontend/backend implementation. Use when generating contracts, creating shared types, defining API specs, or updating infrastructure requirements per increment.

Pause execution and request human approval at defined checkpoints. Present summaries, state next steps, and record approval or rejection. Use at phase exits, after Gherkin generation, after implementation PR review, and after deployment verification.

Generate and manage Architecture Decision Records (ADRs). Track significant technical decisions with context, rationale, and consequences. Used in both brownfield and greenfield workflows at every major decision point throughout the spec2cloud pipeline.

Diagnose and resolve Azure deployment failures by analyzing error output, checking Azure resource state, and suggesting fixes. Use when azd provision fails, azd deploy fails, smoke tests fail against live deployment, container images fail to push/pull, or any Phase 6 deployment error occurs. Trigger on deployment errors, infrastructure failures, or post-deploy smoke test failures.

Handle failures during spec2cloud execution. Covers sub-agent failures, stuck loops, corrupted state, and test infrastructure failures. Use when encountering errors, retrying failed tasks, or recovering from corrupted state.

Research current best practices, latest package versions, and official guidance before writing implementation code. Uses MCP tools (Microsoft Learn, Context7, DeepWiki) and available Copilot skills to ground decisions in up-to-date, first-party documentation rather than stale training data.