Dev Swarm Tech Specs

AI Builder - Technical Specifications

This skill creates/updates the technical specifications documentation defining the technology stack, security posture, theme standards (extracted from UX mockup), coding standards, testing standards, and security standards.

When to Use This Skill

• User asks to "define tech specs" or "choose tech stack"
• User requests to start Stage 7 or the next stage after architecture
• User wants to select technologies and frameworks
• User wants to establish coding and testing standards
• User needs to define security standards

Prerequisites

This skill requires 06-architecture to be completed for L3+ projects. For L2 projects, this stage can proceed without architecture documentation.

Your Roles in This Skill

• Tech Manager (Architect): Lead tech stack selection and standards definition. Review architecture to choose appropriate technologies. Define coding and testing standards. Ensure technical choices align with requirements and constraints.
• Security Engineer: Define security posture, authentication approach, and secure coding standards. Identify security threats and mitigation strategies. Establish security testing and compliance requirements.
• UI Designer: Extract theme standards from approved UX mockup. Document colors, fonts, spacing, and design tokens. Ensure design consistency rules are clear for implementation.
• DevOps Engineer: Review tech stack for deployment and operational feasibility. Provide input on infrastructure compatibility. Consider monitoring and logging requirements.

Role Communication

As an expert in your assigned roles, you must announce your actions before performing them using the following format:

As a {Role} [and {Role}, ...], I will {action description}

This communication pattern ensures transparency and allows for human-in-the-loop oversight at key decision points.

Instructions

Follow these steps in order:

Step 0: Verify Prerequisites and Gather Context

First read and understand rules: dev-swarm/docs/research-specs-rules.md then:

1. Check for Project Scale (L2 vs L3+):

   • Check 00-init-ideas/README.md or classification to determine project scale.

2. Check if 06-architecture/ folder exists:

   • For L3+ projects (Mandatory):
     • If NOT found: Inform user they need to create architecture first, then STOP.
     • If found: Read all files.
   • For L2 projects (Optional):
     • If found: Read files.
     • If NOT found: Proceed without it.

2.5 Verify previous stage completion (06-architecture when required):

• If 06-architecture/README.md exists, read it and list required docs
• If README is missing or required docs are missing:
  • Ask the user to start/continue stage 06, or skip it if allowed
  • If skip: create 06-architecture/SKIP.md with a short reason
  • If continue: STOP and return after stage 06 is complete

3. Check if 05-ux/ folder exists (Mandatory for L3+):

   • If NOT found and project is L3+: Warn user.
   • For L2: Skip if not relevant.
     • CSS variables and design tokens
     • Color palette
     • Typography (fonts, sizes)
     • Spacing system
     • Border radius and shadows
     • Component styles

4. Check if 00-init-ideas/ folder exists (recommended):

   • If found: Read all files to understand it

5. Check if 04-prd/ folder exists (recommended):

   • If found: Read to understand:
     • Non-functional requirements (performance, security, compliance)
     • Technical constraints

6. Check if 03-mvp/ folder exists (recommended):

   • If found: Read to understand:
     • MVP scope (prioritize tech choices for MVP)
     • Timeline constraints

7. Check if this stage should be skipped:

   • Check if 07-tech-specs/SKIP.md exists
   • If SKIP.md exists:
     • Read SKIP.md to understand why this stage was skipped
     • Inform the user: "Stage 7 (tech-specs) is marked as SKIP because [reason from SKIP.md]"
     • Ask the user: "Would you like to proceed to the next stage (devops)?"
     • If user says yes:
       • Exit this skill and inform them to run the next stage skill
     • If user says no:
       • Ask if they want to proceed with tech specs anyway
       • If yes, delete SKIP.md and continue with this skill
       • If no, exit the skill

8. Check if 07-tech-specs/ folder exists:

   • If exists: Read all existing files to understand current tech specs state
   • If NOT exists: Will create new structure

9. If README.md exists: Check whether it requires diagrams. If it does, follow dev-swarm/docs/mermaid-diagram-guide.md and use the dev-swarm-mermaid skill to render outputs.

10. Read source code structure guidance (mandatory):

    • Read dev-swarm/docs/source-code-structure.md
    • Use it as the baseline when creating 07-tech-specs/source-code-structure.md

11. Proceed to Step 1 with gathered context

Step 1: Refine Design Requirements in README and Get Approval

CRITICAL: Create/update README.md first without pre-approval. Then ask the user to review/update/approve it, re-read it after approval, and only then create other docs.

1. Analyze information from previous stages:

   • Read 06-architecture/ to understand system components and deployment
   • Read 05-ux/mockups/styles.css to extract theme (CRITICAL for theme-standards.md)
   • Read 04-prd/ to understand non-functional requirements
   • Read 03-mvp/ (if exists) to understand what to prioritize
   • Consider cost-budget constraints for this stage

2. Create or update 07-tech-specs/README.md with refined requirements:

   • Use the template in references/README.md
   • Follow the checkbox rules: checked items apply after README approval; create file items only after approval; propose default checks; allow user changes
   • Populate only the template sections; do not add new headings such as Documents or Deliverables
   • Follow dev-swarm/docs/stage-readme-guidelines.md before drafting
   • Refer to references/deliverables.md to select deliverables by project type
   • Present any choices as checkbox lists with a default selection
   • For L2 projects: Create a simple README (just several lines) indicating the project level and that only tech-stack.md is required.
   • For L3+ projects: List deliverables explicitly in README (typical: tech-stack.md, security.md, theme-standards.md, coding-standards.md, source-code-structure.md, testing-standards.md, security-standards.md)
   • Stage overview and objectives (based on previous stage context)
   • Owners: Tech Manager (lead), Security Engineer, UI Designer, DevOps Engineer
   • Diagrams (if required by project init):
     • Reference dev-swarm/docs/mermaid-diagram-guide.md
     • Include diagram/ deliverables when needed
   • What tech specs will include:
     • Technology stack selection with rationale
     • Security posture and authentication approach
     • Theme standards extracted from UX mockup (CRITICAL)
     • Coding standards and best practices
     • Testing standards and coverage requirements
     • Security standards for secure coding
   • Methodology:
     • How tech stack will be selected (based on architecture + requirements)
     • How theme will be extracted from mockup CSS (DO NOT invent values)
   • Deliverables planned:
     • List of files that will be created (tech-stack.md, theme-standards.md, etc.)
   • Status: In Progress (update to "Completed" after implementation)

3. Notify user after README is created:

   • Say: "I have created README.md file, please check and update or approve the content."
   • Summarize the tech specs approach and what will be defined
   • Summarize what documentation files will be created
   • Explain how it aligns with previous stages

4. Wait for user approval:

   • If user says yes: Re-read README.md (user may have updated it), then proceed to Step 2
   • If user says no:
     • Ask what needs to be changed
     • Update README based on feedback
     • Ask for approval again, then re-read README.md before proceeding

Step 2: Create/Update Tech Specs Structure

Only after user approves the README and you re-read it:

1. Create files as specified in the approved README.md:

   IMPORTANT: The file structure below is a SAMPLE only. The actual files you create must follow what was approved in the README.md in Step 1.

   Typical structure (example):

   07-tech-specs/
   ├── README.md (created in Step 1, then reviewed/approved)
   ├── tech-stack.md (if specified in README)
   ├── security.md (if specified in README)
   ├── theme-standards.md (if specified in README - MUST extract from UX mockup)
   ├── coding-standards.md (if specified in README)
   ├── source-code-structure.md (if specified in README)
   ├── testing-standards.md (if specified in README)
   └── security-standards.md (if specified in README)
   

   Create only the files listed in the README's "Deliverables planned" section.

Step 3: Create/Update Technical Specifications Documentation

IMPORTANT: Only create tech specs documentation after README is approved in Step 1 and re-read.

NOTE: Use references/deliverables.md for file-by-file content guidance. Adapt based on the approved README and project needs.

Step 4: Ensure Alignment

Make sure tech specs align with:

• Architecture from 06-architecture/
• Non-functional requirements from 04-prd/non-functional-requirements.md
• UX mockup theme from 05-ux/mockups/styles.css (CRITICAL for theme-standards.md)
• MVP scope from 03-mvp/ (prioritize tech choices for MVP)

Verify that:

• Tech stack can implement the architecture
• Theme standards match the UX mockup exactly
• Security standards address requirements
• Testing standards ensure quality
• Coding standards are clear and enforceable

Step 5: Final User Review

1. Inform user that tech specs are complete

2. Update README.md:

   • Change Status from "In Progress" to "Completed"
   • Add a Summary section with key insights (2-3 paragraphs)
   • Add a Created Files section listing all created files

3. Present completed work to user:

   • Review chosen tech stack and rationale
   • Show theme standards extracted from UX mockup
   • Explain security approach
   • Walk through coding and testing standards

4. Highlight key insights:

   • Frontend framework choice and why
   • Backend framework choice and why
   • Database choice and why
   • Theme values extracted from mockup (show side-by-side)
   • Security compliance level
   • Test coverage requirements

5. Ask questions:

   • Comfortable with tech stack choices?
   • Theme standards match their vision?
   • Any security concerns?
   • Testing requirements achievable?
   • Ready to proceed to next stage (DevOps)?

6. Make adjustments based on user feedback if needed

Step 6: Commit to Git (if user confirms)

1. If user confirms tech specs are complete:
   • Ask if they want to commit to git
2. If user wants to commit:
   • Stage all changes in 07-tech-specs/
   • Commit with message: "Define tech stack and engineering standards (Stage 7)"