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/examples/greenfield/task-api-openapi.yaml

View on GitHub
openapi: 3.0.3

info:
  title: Task Management API
  version: 1.0.0
  description: |
    REST API for managing tasks, projects, and team collaboration.

    **Features:**
    - Create, update, delete tasks
    - Organize tasks into projects
    - Assign tasks to team members
    - Track task status and progress

    **Authentication:** Bearer token (JWT)

    **Rate Limiting:** 1000 requests/hour per user
  contact:
    name: API Support
    email: api-support@example.com
    url: https://docs.example.com/api
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.taskmanager.com/v1
    description: Production
  - url: https://staging-api.taskmanager.com/v1
    description: Staging
  - url: http://localhost:3000/v1
    description: Local development

tags:
  - name: Tasks
    description: Task CRUD operations
  - name: Projects
    description: Project management
  - name: Users
    description: User management
  - name: Comments
    description: Task comments and discussions

paths:
  /tasks:
    get:
      summary: List tasks
      description: Retrieve a paginated list of tasks with optional filtering
      operationId: listTasks
      tags:
        - Tasks
      parameters:
        - name: status
          in: query
          description: Filter by task status
          required: false
          schema:
            type: string
            enum: [pending, in_progress, in_review, completed]
            example: in_progress
        - name: assignee
          in: query
          description: Filter by assignee user ID
          required: false
          schema:
            type: string
            format: uuid
            example: "550e8400-e29b-41d4-a716-446655440000"
        - name: project_id
          in: query
          description: Filter by project ID
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Number of tasks to return (max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
        - name: offset
          in: query
          description: Number of tasks to skip (for pagination)
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
      responses:
        '200':
          description: List of tasks retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                success:
                  value:
                    data:
                      - id: "550e8400-e29b-41d4-a716-446655440000"
                        title: "Implement user authentication"
                        description: "Add JWT-based authentication to the API"
                        status: "in_progress"
                        priority: "high"
                        assignee_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                        project_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
                        due_date: "2025-01-30"
                        created_at: "2025-01-15T10:30:00Z"
                        updated_at: "2025-01-15T14:22:00Z"
                    pagination:
                      total: 42
                      limit: 20
                      offset: 0
                      has_more: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

    post:
      summary: Create task
      description: Create a new task
      operationId: createTask
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              simple:
                summary: Simple task
                value:
                  title: "Write API documentation"
                  project_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
              detailed:
                summary: Detailed task
                value:
                  title: "Implement payment processing"
                  description: "Integrate Stripe API for credit card payments"
                  status: "pending"
                  priority: "high"
                  assignee_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                  project_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
                  due_date: "2025-02-15"
                  tags: ["backend", "payment", "integration"]
      responses:
        '201':
          description: Task created successfully
          headers:
            Location:
              description: URL of the created task
              schema:
                type: string
                example: "/v1/tasks/550e8400-e29b-41d4-a716-446655440000"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

  /tasks/{task_id}:
    get:
      summary: Get task by ID
      description: Retrieve detailed information about a specific task
      operationId: getTask
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Task details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update task
      description: Update one or more fields of an existing task
      operationId: updateTask
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
            examples:
              status_update:
                summary: Update status
                value:
                  status: "completed"
              reassign:
                summary: Reassign task
                value:
                  assignee_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                  status: "in_progress"
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

    delete:
      summary: Delete task
      description: Permanently delete a task
      operationId: deleteTask
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '204':
          description: Task deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /tasks/{task_id}/comments:
    get:
      summary: List task comments
      description: Retrieve all comments for a specific task
      operationId: listTaskComments
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Comments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    post:
      summary: Add task comment
      description: Add a new comment to a task
      operationId: createTaskComment
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/TaskId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  minLength: 1
                  maxLength: 5000
                  example: "Great progress! Let's discuss the API design in tomorrow's standup."
      responses:
        '201':
          description: Comment added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /projects:
    get:
      summary: List projects
      description: Retrieve all projects
      operationId: listProjects
      tags:
        - Projects
      responses:
        '200':
          description: Projects retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create project
      description: Create a new project
      operationId: createProject
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    Task:
      type: object
      required:
        - id
        - title
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique task identifier
          example: "550e8400-e29b-41d4-a716-446655440000"
        title:
          type: string
          minLength: 1
          maxLength: 255
          description: Task title
          example: "Implement user authentication"
        description:
          type: string
          nullable: true
          maxLength: 5000
          description: Detailed task description (Markdown supported)
          example: "Add JWT-based authentication to the API with email/password and OAuth2 (Google, GitHub)"
        status:
          type: string
          enum: [pending, in_progress, in_review, completed]
          description: Current task status
          example: "in_progress"
        priority:
          type: string
          enum: [low, medium, high, urgent]
          default: medium
          description: Task priority
          example: "high"
        assignee_id:
          type: string
          format: uuid
          nullable: true
          description: User ID of the person assigned to this task
          example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
        project_id:
          type: string
          format: uuid
          description: Project ID this task belongs to
          example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
        due_date:
          type: string
          format: date
          nullable: true
          description: Task deadline (ISO 8601 date)
          example: "2025-01-30"
        tags:
          type: array
          items:
            type: string
          description: Array of tags for categorization
          example: ["backend", "authentication", "security"]
        created_at:
          type: string
          format: date-time
          description: Task creation timestamp
          example: "2025-01-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2025-01-15T14:22:00Z"

    CreateTaskRequest:
      type: object
      required:
        - title
        - project_id
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 5000
        status:
          type: string
          enum: [pending, in_progress, in_review, completed]
          default: pending
        priority:
          type: string
          enum: [low, medium, high, urgent]
          default: medium
        assignee_id:
          type: string
          format: uuid
          nullable: true
        project_id:
          type: string
          format: uuid
        due_date:
          type: string
          format: date
          nullable: true
        tags:
          type: array
          items:
            type: string

    UpdateTaskRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 5000
        status:
          type: string
          enum: [pending, in_progress, in_review, completed]
        priority:
          type: string
          enum: [low, medium, high, urgent]
        assignee_id:
          type: string
          format: uuid
          nullable: true
        due_date:
          type: string
          format: date
          nullable: true
        tags:
          type: array
          items:
            type: string

    Project:
      type: object
      required:
        - id
        - name
        - created_at
      properties:
        id:
          type: string
          format: uuid
          example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
        name:
          type: string
          minLength: 1
          maxLength: 255
          example: "API v2.0 Development"
        description:
          type: string
          nullable: true
          example: "Complete rewrite of REST API with GraphQL support"
        created_at:
          type: string
          format: date-time
          example: "2025-01-01T00:00:00Z"

    CreateProjectRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 1000

    Comment:
      type: object
      required:
        - id
        - task_id
        - author_id
        - content
        - created_at
      properties:
        id:
          type: string
          format: uuid
        task_id:
          type: string
          format: uuid
        author_id:
          type: string
          format: uuid
        content:
          type: string
        created_at:
          type: string
          format: date-time

    Pagination:
      type: object
      required:
        - total
        - limit
        - offset
        - has_more
      properties:
        total:
          type: integer
          description: Total number of items
          example: 42
        limit:
          type: integer
          description: Number of items returned
          example: 20
        offset:
          type: integer
          description: Number of items skipped
          example: 0
        has_more:
          type: boolean
          description: Whether more items are available
          example: true

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Human-readable error message
          example: "Task title is required"
        details:
          type: object
          description: Additional error context
          nullable: true

  parameters:
    TaskId:
      name: task_id
      in: path
      required: true
      description: Task UUID
      schema:
        type: string
        format: uuid
        example: "550e8400-e29b-41d4-a716-446655440000"

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "BAD_REQUEST"
            message: "Invalid request parameters"

    Unauthorized:
      description: Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "UNAUTHORIZED"
            message: "Authentication required. Please provide a valid Bearer token."

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "NOT_FOUND"
            message: "Task not found"

    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "VALIDATION_ERROR"
            message: "Task title must be between 1 and 255 characters"
            details:
              field: "title"
              constraint: "length"

    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          description: Requests allowed per hour
          schema:
            type: integer
            example: 1000
        X-RateLimit-Remaining:
          description: Remaining requests in current window
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset:
          description: Timestamp when rate limit resets
          schema:
            type: integer
            example: 1705334400
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: "RATE_LIMIT_EXCEEDED"
            message: "API rate limit exceeded. Try again in 15 minutes."

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token obtained from the `/auth/login` endpoint.

        **Example:**
        ```
        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        ```

security:
  - BearerAuth: []
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