Skip to content

SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist

documentation-specialist

Verified

This skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".

FileKindSize
SKILL.mdskill md10.0 KB
references/examples/TOC.mdmarkdown6.5 KB
references/examples/brownfield/database-failover-runbook.mdmarkdown8.1 KB
references/examples/brownfield/spring-boot-sdd.mdmarkdown5.6 KB
references/examples/greenfield/adr-microservices.mdmarkdown6.3 KB
references/examples/greenfield/architecture-doc.mdmarkdown3.7 KB
references/examples/greenfield/billing-srs.mdmarkdown12.4 KB
references/examples/greenfield/cli-getting-started.mdmarkdown9.3 KB
references/examples/greenfield/collaboration-prd.mdmarkdown13.8 KB
references/examples/greenfield/document-specialist-sdd.mdmarkdown15.4 KB
references/examples/greenfield/ecommerce-sdd.mdmarkdown7.8 KB
references/examples/greenfield/rest-api-tutorial.mdmarkdown13.8 KB
references/examples/greenfield/task-api-openapi.yamlconfig19.0 KB
references/examples/greenfield/taskmanager-user-manual.mdmarkdown8.7 KB
references/examples/greenfield/ui-wireframes.mdmarkdown5.8 KB
references/guides/requirements/README.mdmarkdown3.7 KB
references/mappings/backend/fastapi-mapping.yamlconfig9.7 KB
references/mappings/backend/spring-boot-mapping.yamlconfig24.1 KB
references/reference/01-philosophy.mdmarkdown2.0 KB
references/reference/02-requirements-srs-vs-prd.mdmarkdown1.2 KB
references/reference/02-requirements-traceability.mdmarkdown1.7 KB
references/reference/02-requirements-writing.mdmarkdown1.4 KB
references/reference/03-design-adrs.mdmarkdown2.2 KB
references/reference/03-design-arc42.mdmarkdown2.6 KB
references/reference/03-design-requirements-matrix.mdmarkdown1.3 KB
references/reference/04-diagrams-c4-hierarchy.mdmarkdown2.0 KB
references/reference/04-diagrams-selection.mdmarkdown5.1 KB
references/reference/04-diagrams-state-vs-activity.mdmarkdown2.3 KB
references/reference/05-api-checklist.mdmarkdown2.0 KB
references/reference/05-api-openapi.mdmarkdown3.4 KB
references/reference/05-api-stripe-gold-standard.mdmarkdown1.8 KB
references/reference/06-deployment-diagrams.mdmarkdown1.8 KB
references/reference/06-deployment-documentation.mdmarkdown2.9 KB
references/reference/06-deployment-runbooks.mdmarkdown2.5 KB
references/reference/06-operational-docs.mdmarkdown2.7 KB
references/reference/07-user-kb-approach.mdmarkdown1.8 KB
references/reference/07-user-kb-template.mdmarkdown3.1 KB
references/reference/07-user-writing-style.mdmarkdown2.0 KB
references/reference/08-agile-process.mdmarkdown3.2 KB
references/reference/08-tutorial-writing.mdmarkdown7.4 KB
references/reference/09-code-to-docs-detection.mdmarkdown2.5 KB
references/reference/09-code-to-docs-example.mdmarkdown3.2 KB
references/reference/09-code-to-docs-when.mdmarkdown1.7 KB
references/reference/09-code-to-docs-workflow.mdmarkdown2.0 KB
references/reference/10-quality-bonsai-pruning.mdmarkdown2.4 KB
references/reference/10-quality-checklist.mdmarkdown2.6 KB
references/reference/10-quality-metrics.mdmarkdown3.1 KB
references/reference/11-voice-and-style.mdmarkdown1.5 KB
references/reference/comprehensive-guide.mdmarkdown7.3 KB
references/templates/markdown/DESIGN_DOC.mdmarkdown4.5 KB
references/templates/markdown/api-openapi.yamlconfig17.7 KB
references/templates/markdown/architecture.mdmarkdown1.6 KB
references/templates/markdown/design-sdd.mdmarkdown143 B
references/templates/markdown/developer-tutorial.mdmarkdown7.1 KB
references/templates/markdown/getting-started.mdmarkdown6.5 KB
references/templates/markdown/howto-guide.mdmarkdown4.1 KB
references/templates/markdown/requirements-prd.mdmarkdown10.2 KB
references/templates/markdown/requirements-srs.mdmarkdown17.0 KB
references/templates/markdown/runbook.mdmarkdown8.8 KB
references/templates/markdown/user-manual.mdmarkdown4.8 KB
references/workflows/TOC.mdmarkdown1.9 KB
references/workflows/audit-workflow.mdmarkdown2.5 KB
references/workflows/brownfield-workflow.mdmarkdown3.6 KB
references/workflows/brownfield/fastapi-guide.mdmarkdown1.8 KB
references/workflows/brownfield/pulumi-guide.mdmarkdown1.9 KB
references/workflows/brownfield/springboot-guide.mdmarkdown2.2 KB
references/workflows/convert-workflow.mdmarkdown1.4 KB
references/workflows/design-workflow.mdmarkdown3.0 KB
references/workflows/diagram-workflow.mdmarkdown3.7 KB
references/workflows/greenfield-workflow.mdmarkdown3.4 KB
references/workflows/greenfield/advanced.mdmarkdown1.9 KB
references/workflows/greenfield/openapi-guide.mdmarkdown2.5 KB
references/workflows/greenfield/prd-guide.mdmarkdown2.0 KB
references/workflows/greenfield/srs-guide.mdmarkdown2.0 KB
references/workflows/runbook-workflow.mdmarkdown2.4 KB
references/workflows/tutorial-workflow.mdmarkdown2.3 KB
references/workflows/user-docs-workflow.mdmarkdown2.3 KB

references/mappings/backend/spring-boot-mapping.yaml

View on GitHub
# Spring Boot Code-to-Documentation Mapping
# This file defines how to extract documentation from Spring Boot applications

framework: Spring Boot
language: Java
versions:
  - "2.x"
  - "3.x"
documentation_types:
  - Software Design Document (SDD)
  - OpenAPI/REST API Specification
  - Deployment Documentation

# ============================================================================
# DETECTION: How to identify a Spring Boot project
# ============================================================================
detection:
  required_files:
    - pattern: "pom.xml"
      description: "Maven build file"
      alternative: "build.gradle"
    - pattern: "**/src/main/java/**/*Application.java"
      description: "Main application class"

  required_dependencies:
    maven:
      - "org.springframework.boot:spring-boot-starter"
      - "org.springframework.boot:spring-boot-starter-web"
    gradle:
      - "implementation 'org.springframework.boot:spring-boot-starter'"

  key_annotations:
    - "@SpringBootApplication"
    - "@RestController"
    - "@Service"
    - "@Repository"

# ============================================================================
# ARCHITECTURE MAPPING: Code → SDD Section 5 (Building Block View)
# ============================================================================
architecture_mappings:

  # Main Application Class
  - source_pattern: "@SpringBootApplication"
    grep_command: "grep -r \"@SpringBootApplication\" src/"
    target_document: "design-sdd.md"
    target_section: "5.1 Application Entry Point"
    extraction_rules:
      - element: "class_name"
        method: "Extract class name"
        example: "TaskManagerApplication"
      - element: "component_scan_packages"
        method: "Extract from @ComponentScan or infer from package"
        example: "com.example.taskmanager"
      - element: "enabled_features"
        method: "Extract from annotations like @EnableScheduling"
        example: "@EnableScheduling, @EnableAsync"

    documentation_template: |
      ## 5.1 Application Entry Point

      **Application Class**: {class_name}
      **Base Package**: {component_scan_packages}
      **Enabled Features**:
      {enabled_features}

      This is the main entry point for the Spring Boot application. It bootstraps
      the Spring context and enables component scanning for the entire application.

  # Configuration Classes
  - source_pattern: "@Configuration"
    grep_command: "grep -r \"@Configuration\" src/"
    target_document: "design-sdd.md"
    target_section: "5.2 Configuration Components"
    extraction_rules:
      - element: "config_class_name"
        method: "Extract class name"
      - element: "bean_definitions"
        method: "Extract methods with @Bean annotation"
      - element: "property_sources"
        method: "Extract @PropertySource annotations"

    documentation_template: |
      ### Configuration: {config_class_name}

      **Purpose**: {infer from class name and bean types}
      **Bean Definitions**:
      {list of @Bean methods}

      **Configuration Properties**:
      {property_sources}

  # Application Properties
  - source_pattern: "application.properties | application.yml"
    grep_command: "find src/main/resources -name 'application*.properties' -o -name 'application*.yml'"
    target_document: "design-sdd.md"
    target_section: "7. Deployment View"
    extraction_rules:
      - element: "server_port"
        property: "server.port"
        default: "8080"
      - element: "database_url"
        property: "spring.datasource.url"
      - element: "database_driver"
        property: "spring.datasource.driver-class-name"
      - element: "external_services"
        property: "*.url"
        note: "Extract any properties ending in .url"

    documentation_template: |
      ## 7. Deployment View

      ### 7.1 Application Configuration

      **Server Port**: {server_port}
      **Database**: {database_driver} at {database_url}
      **External Services**:
      {external_services}

# ============================================================================
# API MAPPING: Code → OpenAPI Specification
# ============================================================================
api_mappings:

  # REST Controllers
  - source_pattern: "@RestController"
    grep_command: "grep -r \"@RestController\" src/"
    target_document: "api-reference-openapi.yaml"
    target_section: "paths"
    extraction_rules:
      - element: "controller_class"
        method: "Extract class name"
      - element: "base_path"
        method: "Extract from @RequestMapping at class level"
        example: "/api/v1/tasks"
      - element: "endpoints"
        method: "Extract all @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping methods"

    endpoint_extraction:
      - annotation: "@GetMapping"
        http_method: "get"
        extract:
          - path: "annotation value or method-level @RequestMapping"
          - parameters: "@RequestParam, @PathVariable"
          - response_type: "method return type"
          - response_status: "@ResponseStatus or default 200"

      - annotation: "@PostMapping"
        http_method: "post"
        extract:
          - path: "annotation value"
          - request_body: "@RequestBody parameter type"
          - response_type: "method return type"
          - response_status: "@ResponseStatus or default 201"

      - annotation: "@PutMapping"
        http_method: "put"
        extract:
          - path: "annotation value with {id} path variables"
          - path_parameters: "@PathVariable"
          - request_body: "@RequestBody parameter type"
          - response_type: "method return type"

      - annotation: "@DeleteMapping"
        http_method: "delete"
        extract:
          - path: "annotation value"
          - path_parameters: "@PathVariable"
          - response_status: "@ResponseStatus or default 204"

    example_code: |
      @RestController
      @RequestMapping("/api/v1/tasks")
      public class TaskController {

          @GetMapping
          public List<TaskDTO> listTasks(@RequestParam(required = false) String status) {
              return taskService.findByStatus(status);
          }

          @PostMapping
          @ResponseStatus(HttpStatus.CREATED)
          public TaskDTO createTask(@Valid @RequestBody CreateTaskRequest request) {
              return taskService.create(request);
          }

          @PutMapping("/{id}")
          public TaskDTO updateTask(
              @PathVariable Long id,
              @RequestBody UpdateTaskRequest request) {
              return taskService.update(id, request);
          }
      }

    generated_openapi: |
      paths:
        /api/v1/tasks:
          get:
            summary: List tasks
            operationId: listTasks
            parameters:
              - name: status
                in: query
                required: false
                schema:
                  type: string
            responses:
              '200':
                description: List of tasks
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/TaskDTO'

          post:
            summary: Create a new task
            operationId: createTask
            requestBody:
              required: true
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/CreateTaskRequest'
            responses:
              '201':
                description: Task created successfully
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/TaskDTO'

        /api/v1/tasks/{id}:
          put:
            summary: Update a task
            operationId: updateTask
            parameters:
              - name: id
                in: path
                required: true
                schema:
                  type: integer
                  format: int64
            requestBody:
              required: true
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/UpdateTaskRequest'
            responses:
              '200':
                description: Task updated successfully

  # DTO/Request/Response Classes
  - source_pattern: "DTO | Request | Response classes"
    grep_command: "find src/ -name '*DTO.java' -o -name '*Request.java' -o -name '*Response.java'"
    target_document: "api-reference-openapi.yaml"
    target_section: "components.schemas"
    extraction_rules:
      - element: "class_name"
        method: "Extract class name"
      - element: "fields"
        method: "Extract all fields with types"
      - element: "validation_annotations"
        method: "Extract @NotNull, @NotBlank, @Size, @Min, @Max, @Pattern, @Email"

    example_code: |
      public class CreateTaskRequest {
          @NotBlank(message = "Title is required")
          @Size(max = 200)
          private String title;

          @Size(max = 2000)
          private String description;

          @Future
          private LocalDate dueDate;

          @NotNull
          private TaskPriority priority;

          // getters and setters
      }

    generated_openapi_schema: |
      components:
        schemas:
          CreateTaskRequest:
            type: object
            required:
              - title
              - priority
            properties:
              title:
                type: string
                maxLength: 200
                description: Title of the task
              description:
                type: string
                maxLength: 2000
                description: Detailed description
              dueDate:
                type: string
                format: date
                description: Task due date (must be in the future)
              priority:
                $ref: '#/components/schemas/TaskPriority'

# ============================================================================
# DATA MODEL MAPPING: Code → SDD Section 6 (Data Design)
# ============================================================================
data_mappings:

  # JPA Entities
  - source_pattern: "@Entity"
    grep_command: "grep -r \"@Entity\" src/"
    target_document: "design-sdd.md"
    target_section: "6.1 Data Model"
    extraction_rules:
      - element: "entity_class_name"
        method: "Extract class name"
      - element: "table_name"
        method: "Extract from @Table(name=...) or derive from class name"
      - element: "primary_key"
        method: "Extract field with @Id annotation"
      - element: "columns"
        method: "Extract all fields (ignoring @Transient)"
      - element: "relationships"
        method: "Extract @OneToMany, @ManyToOne, @ManyToMany, @OneToOne"

    relationship_extraction:
      - annotation: "@ManyToOne"
        relationship_type: "Many-to-One"
        extract:
          - target_entity: "field type or @JoinColumn"
          - join_column: "@JoinColumn(name=...)"
          - fetch_type: "FetchType.LAZY or EAGER"

      - annotation: "@OneToMany"
        relationship_type: "One-to-Many"
        extract:
          - target_entity: "field type generic or mappedBy"
          - mapped_by: "@OneToMany(mappedBy=...)"
          - cascade: "CascadeType"

      - annotation: "@ManyToMany"
        relationship_type: "Many-to-Many"
        extract:
          - target_entity: "field type generic"
          - join_table: "@JoinTable annotation"

    example_code: |
      @Entity
      @Table(name = "tasks")
      public class Task {
          @Id
          @GeneratedValue(strategy = GenerationType.IDENTITY)
          private Long id;

          @Column(nullable = false, length = 200)
          private String title;

          @Column(length = 2000)
          private String description;

          @Column(name = "due_date")
          private LocalDate dueDate;

          @Enumerated(EnumType.STRING)
          private TaskStatus status;

          @ManyToOne(fetch = FetchType.LAZY)
          @JoinColumn(name = "assigned_user_id")
          private User assignedUser;

          @OneToMany(mappedBy = "task", cascade = CascadeType.ALL)
          private List<Comment> comments;
      }

    generated_sdd_content: |
      ### Entity: Task

      **Table**: `tasks`
      **Primary Key**: `id` (Long, auto-generated)

      **Columns**:
      | Column | Type | Constraints | Description |
      |--------|------|-------------|-------------|
      | id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | Unique identifier |
      | title | VARCHAR(200) | NOT NULL | Task title |
      | description | VARCHAR(2000) | | Detailed description |
      | due_date | DATE | | Target completion date |
      | status | VARCHAR(50) | | Task status (PENDING, IN_PROGRESS, COMPLETED) |
      | assigned_user_id | BIGINT | FOREIGN KEY → users.id | Assigned user |

      **Relationships**:
      - **Many-to-One** to `User` via `assigned_user_id`
      - **One-to-Many** to `Comment` (mapped by `task`)

    generated_er_diagram_mermaid: |
      erDiagram
        USERS ||--o{ TASKS : assigned
        USERS ||--o{ COMMENTS : writes
        TASKS ||--o{ COMMENTS : has
        USERS {
          bigint id PK
          varchar email
          varchar name
        }
        TASKS {
          bigint id PK
          varchar title
          varchar description
          date due_date
          varchar status
          bigint assigned_user_id FK
        }
        COMMENTS {
          bigint id PK
          bigint task_id FK
          bigint user_id FK
          text content
          timestamp created_at
        }

  # Repository Interfaces
  - source_pattern: "@Repository | extends JpaRepository"
    grep_command: "grep -r \"extends JpaRepository\\|extends CrudRepository\\|@Repository\" src/"
    target_document: "design-sdd.md"
    target_section: "6.2 Data Access Layer"
    extraction_rules:
      - element: "repository_name"
        method: "Extract interface name"
      - element: "entity_type"
        method: "Extract generic parameter from JpaRepository<Entity, ID>"
      - element: "custom_queries"
        method: "Extract methods with @Query annotation"

    example_code: |
      @Repository
      public interface TaskRepository extends JpaRepository<Task, Long> {

          List<Task> findByAssignedUserId(Long userId);

          List<Task> findByStatus(TaskStatus status);

          @Query("SELECT t FROM Task t WHERE t.dueDate < :date AND t.status != 'COMPLETED'")
          List<Task> findOverdueTasks(@Param("date") LocalDate date);
      }

    generated_sdd_content: |
      ### Repository: TaskRepository

      **Entity**: Task
      **Type**: JPA Repository

      **Query Methods**:
      - `findByAssignedUserId(Long userId)` - Find all tasks for a specific user
      - `findByStatus(TaskStatus status)` - Find tasks by status
      - `findOverdueTasks(LocalDate date)` - Custom query for overdue tasks

# ============================================================================
# BUSINESS LOGIC MAPPING: Code → SDD Section 5 (Component Design)
# ============================================================================
business_logic_mappings:

  # Service Classes
  - source_pattern: "@Service"
    grep_command: "grep -r \"@Service\" src/"
    target_document: "design-sdd.md"
    target_section: "5.3 Service Layer Components"
    extraction_rules:
      - element: "service_name"
        method: "Extract class name"
      - element: "public_methods"
        method: "Extract all public methods (API)"
      - element: "dependencies"
        method: "Extract @Autowired or constructor-injected dependencies"
      - element: "transactions"
        method: "Extract methods with @Transactional"

    example_code: |
      @Service
      public class TaskService {

          private final TaskRepository taskRepository;
          private final UserRepository userRepository;

          @Autowired
          public TaskService(TaskRepository taskRepository, UserRepository userRepository) {
              this.taskRepository = taskRepository;
              this.userRepository = userRepository;
          }

          @Transactional
          public TaskDTO create(CreateTaskRequest request) {
              Task task = new Task();
              task.setTitle(request.getTitle());
              task.setDescription(request.getDescription());
              task.setStatus(TaskStatus.PENDING);

              Task saved = taskRepository.save(task);
              return TaskMapper.toDTO(saved);
          }

          @Transactional(readOnly = true)
          public List<TaskDTO> findByStatus(TaskStatus status) {
              return taskRepository.findByStatus(status)
                  .stream()
                  .map(TaskMapper::toDTO)
                  .collect(Collectors.toList());
          }
      }

    generated_sdd_content: |
      ### Service: TaskService

      **Responsibilities**: Core business logic for task management

      **Dependencies**:
      - TaskRepository (data access)
      - UserRepository (user lookups)

      **Public API**:
      - `create(CreateTaskRequest)` → TaskDTO
        - Creates a new task (transactional)
      - `findByStatus(TaskStatus)` → List<TaskDTO>
        - Queries tasks by status (read-only transaction)

      **Transaction Boundaries**: Methods annotated with @Transactional

# ============================================================================
# SECURITY MAPPING: Code → SDD Section 8 (Crosscutting Concepts)
# ============================================================================
security_mappings:

  - source_pattern: "SecurityConfig | WebSecurityConfigurerAdapter"
    grep_command: "find src/ -name '*SecurityConfig.java'"
    target_document: "design-sdd.md"
    target_section: "8.1 Security"
    extraction_rules:
      - element: "authentication_method"
        method: "Detect JWT, OAuth2, Basic Auth, Form Login"
      - element: "authorization_rules"
        method: "Extract from http.authorizeRequests()"
      - element: "cors_config"
        method: "Extract CORS configuration"

    example_code: |
      @Configuration
      @EnableWebSecurity
      public class SecurityConfig extends WebSecurityConfigurerAdapter {

          @Override
          protected void configure(HttpSecurity http) throws Exception {
              http
                  .csrf().disable()
                  .authorizeRequests()
                      .antMatchers("/api/public/**").permitAll()
                      .antMatchers("/api/admin/**").hasRole("ADMIN")
                      .anyRequest().authenticated()
                  .and()
                  .oauth2ResourceServer().jwt();
          }
      }

    generated_sdd_content: |
      ## 8.1 Security

      **Authentication**: OAuth2 JWT (Resource Server)
      **Authorization**: Role-based access control

      **Access Rules**:
      - `/api/public/**` - No authentication required
      - `/api/admin/**` - Requires ADMIN role
      - All other endpoints - Requires authentication

      **CSRF Protection**: Disabled (stateless API)

# ============================================================================
# DIAGRAM GENERATION RULES
# ============================================================================
diagram_generation:

  # C4 Level 2: Container Diagram
  - diagram_type: "C4 Container"
    tool: "design-doc-mermaid"
    inputs:
      - "@SpringBootApplication class"
      - "application.properties/yml (database, external services)"
      - "Dockerfile or deployment config"
    output_file: "docs/diagrams/c4-container.md"
    description: "Shows Spring Boot application, database, and external systems"

  # Component Diagram
  - diagram_type: "Component Diagram"
    tool: "design-doc-mermaid"
    inputs:
      - "All @RestController classes"
      - "All @Service classes"
      - "All @Repository interfaces"
    output_file: "docs/diagrams/component-diagram.md"
    description: "Shows internal architecture layers and dependencies"
    template: |
      flowchart TD
        TaskController --> TaskService
        UserController --> UserService
        TaskService --> TaskRepository
        UserService --> UserRepository
        TaskRepository --> tasks[(tasks)]
        UserRepository --> users[(users)]

  # Sequence Diagram
  - diagram_type: "Sequence Diagram"
    tool: "design-doc-mermaid"
    inputs:
      - "Trace a user flow (e.g., 'Create Task')"
      - "Controller → Service → Repository → Database"
    output_file: "docs/diagrams/sequence-create-task.md"
    description: "Shows message flow for a specific use case"
    template: |
      sequenceDiagram
        actor User
        participant Controller as TaskController
        participant Service as TaskService
        participant Repo as TaskRepository
        participant DB as PostgreSQL
        User->>Controller: POST /api/v1/tasks
        Controller->>Service: create(request)
        Service->>Service: validate(request)
        Service->>Repo: save(task)
        Repo->>DB: INSERT INTO tasks
        DB-->>Repo: saved task entity
        Repo-->>Service: Task entity
        Service-->>Controller: TaskDTO
        Controller-->>User: 201 Created + TaskDTO

  # ER Diagram
  - diagram_type: "ER Diagram"
    tool: "design-doc-mermaid"
    inputs:
      - "All @Entity classes with relationships"
    output_file: "docs/diagrams/er-diagram.md"
    description: "Database schema with relationships"

# ============================================================================
# EXECUTION WORKFLOW
# ============================================================================
workflow:
  steps:
    - step: 1
      name: "Detect Framework"
      action: "Verify this is a Spring Boot project"
      commands:
        - "find . -name 'pom.xml' -o -name 'build.gradle'"
        - "grep -r '@SpringBootApplication' src/"

    - step: 2
      name: "Scan Architecture"
      action: "Find all major components"
      commands:
        - "grep -r '@RestController' src/"
        - "grep -r '@Service' src/"
        - "grep -r '@Repository' src/"
        - "grep -r '@Entity' src/"
        - "grep -r '@Configuration' src/"

    - step: 3
      name: "Read Configuration"
      action: "Extract deployment details"
      commands:
        - "find src/main/resources -name 'application*.properties' -o -name 'application*.yml'"

    - step: 4
      name: "Generate SDD"
      action: "Create arc42 Software Design Document"
      sections:
        - "5. Building Block View (from @Service, @Repository, @Controller)"
        - "6. Data Design (from @Entity)"
        - "7. Deployment (from application.yml)"
        - "8. Crosscutting Concepts (from SecurityConfig, error handling)"

    - step: 5
      name: "Generate OpenAPI Spec"
      action: "Extract API specification"
      sections:
        - "paths (from @RestController)"
        - "components.schemas (from DTO/Request/Response classes)"
        - "securitySchemes (from SecurityConfig)"

    - step: 6
      name: "Generate Diagrams"
      action: "Create visual documentation"
      diagrams:
        - "C4 Container (design-doc-mermaid)"
        - "Component Diagram (design-doc-mermaid)"
        - "ER Diagram (design-doc-mermaid)"
        - "Sequence Diagram for key flows (design-doc-mermaid)"
        - "Wireframes / leftover UML (plantuml, always PNG or SVG)"

    - step: 7
      name: "Post-Processing"
      action: "Offer conversions and enhancements"
      options:
        - "Convert SDD to Word (docx skill)"
        - "Generate PDF package (pdf skill)"
        - "Render leftover PlantUML (wireframes, use case) to PNG"

# ============================================================================
# NOTES AND BEST PRACTICES
# ============================================================================
notes:
  - "Always read application.properties/yml for deployment context"
  - "Extract validation annotations for OpenAPI schema constraints"
  - "Look for custom exception handlers (@ControllerAdvice) for error response documentation"
  - "Check for @ApiOperation and Swagger annotations (might already have partial API docs)"
  - "For microservices, scan for Eureka, Consul, or other service discovery"
  - "Check for @Async and @Scheduled for background processing documentation"
  - "Look for @Cacheable for caching strategy documentation"
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall