@soulcraft/kits 1.0.0

package/kits/api-documentation/kit.json

@@ -0,0 +1,358 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "api-documentation",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "API Documentation",
+  "description": "Complete API reference with endpoints, authentication, and examples",
+  "longDescription": "Professional API documentation structure with endpoint specifications, authentication guides, code examples, and error handling. Includes OpenAPI/Swagger export capabilities.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "⚡",
+  "tags": [
+    "api",
+    "documentation",
+    "development",
+    "technical"
+  ],
+  "variables": [
+    {
+      "key": "projectName",
+      "label": "API Name",
+      "description": "The name of the API being documented",
+      "type": "string",
+      "required": true,
+      "example": "Payment Processing API"
+    },
+    {
+      "key": "version",
+      "label": "Version",
+      "description": "API version number",
+      "type": "string",
+      "required": false,
+      "example": "v1.0"
+    },
+    {
+      "key": "baseUrl",
+      "label": "Base URL",
+      "description": "The root URL for all API endpoints",
+      "type": "string",
+      "required": false,
+      "example": "https://api.example.com"
+    }
+  ],
+  "shared": {
+    "industry": "software-development",
+    "category": "dev",
+    "glossary": {},
+    "aiExpertise": [
+      "API documentation best practices",
+      "OpenAPI/Swagger specification",
+      "REST endpoint design",
+      "Authentication flows",
+      "Developer experience"
+    ],
+    "dataModelHints": [
+      "document",
+      "thing",
+      "topic"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "endpoint",
+          "type": "Concept",
+          "description": "An API endpoint with HTTP method, path, and contract",
+          "products": {
+            "workshop": {
+              "view": "tree",
+              "icon": "⚡"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "resource",
+          "type": "Concept",
+          "description": "A domain object or data resource operated on by endpoints",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🗂️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "errorCode",
+          "type": "Concept",
+          "description": "An error code with meaning, cause, and resolution",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "⚠️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "parameter",
+          "type": "Concept",
+          "description": "A request or response field with type and constraints",
+          "products": {
+            "workshop": {
+              "view": "tree",
+              "icon": "🔧"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "endpoint",
+          "to": "resource",
+          "verb": "References",
+          "description": "Endpoint operates on this resource"
+        },
+        {
+          "from": "endpoint",
+          "to": "errorCode",
+          "verb": "Returns",
+          "description": "Endpoint can return this error code"
+        },
+        {
+          "from": "resource",
+          "to": "parameter",
+          "verb": "Contains",
+          "description": "Resource has this field or parameter"
+        },
+        {
+          "from": "endpoint",
+          "to": "endpoint",
+          "verb": "RelatedTo",
+          "description": "Related endpoints within the same resource group"
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Add an endpoint",
+        "prompt": "Help me document a new API endpoint"
+      },
+      {
+        "label": "Generate examples",
+        "prompt": "Generate request and response examples for my API endpoints"
+      },
+      {
+        "label": "Write authentication docs",
+        "prompt": "Help me write the authentication section of my API documentation"
+      },
+      {
+        "label": "Create error reference",
+        "prompt": "Help me create a comprehensive error code reference"
+      },
+      {
+        "label": "Review consistency",
+        "prompt": "Review my API documentation for consistency in naming and formatting"
+      },
+      {
+        "label": "Explore API structure",
+        "prompt": "Show me the structure of my API documentation and what's complete"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "technical-writing",
+    "level": "intermediate",
+    "learningObjectives": [
+      "Write endpoint specifications that developers can implement without asking follow-up questions",
+      "Structure authentication documentation covering all supported flows with code examples",
+      "Design an error taxonomy with machine-readable codes and actionable resolution guidance",
+      "Apply OpenAPI/Swagger conventions to produce spec-compliant reference documentation",
+      "Review and edit API docs for consistency in naming, tone, and formatting"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "api-documenter"
+  },
+  "workshop": {
+    "difficulty": "intermediate",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are an expert API documentation specialist helping developers create clear, complete, and consistent reference documentation.",
+      "expertise": [
+        "API documentation best practices",
+        "OpenAPI/Swagger specification",
+        "Endpoint design and naming",
+        "Authentication documentation",
+        "Error handling documentation"
+      ],
+      "tone": "mentor"
+    },
+    "workspaceConfig": {
+      "paradigm": "analyst",
+      "defaultTab": "edit",
+      "defaultView": "tree",
+      "defaultFile": "README.md",
+      "layout": {
+        "leftDock": "files",
+        "rightDock": "views"
+      },
+      "onboarding": {
+        "showGuide": true,
+        "highlightFeatures": [
+          "graph",
+          "export"
+        ],
+        "suggestedActions": [
+          "Define your API resources",
+          "Document endpoints for each resource",
+          "Add code examples in multiple languages",
+          "Use Tree view to see endpoint hierarchy"
+        ]
+      }
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "When user creates an endpoint",
+          "When user defines a resource",
+          "When user specifies an error code",
+          "When user documents authentication"
+        ],
+        "typeMapping": {
+          "endpoint": "interface",
+          "resource": "concept",
+          "errorCode": "concept",
+          "parameter": "concept"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "interface",
+          "to": "concept",
+          "verb": "references",
+          "description": "Endpoint uses resource"
+        },
+        {
+          "from": "interface",
+          "to": "concept",
+          "verb": "returns",
+          "description": "Endpoint returns error"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "contains",
+          "description": "Resource contains field"
+        },
+        {
+          "from": "interface",
+          "to": "interface",
+          "verb": "relatedTo",
+          "description": "Related endpoints"
+        }
+      ],
+      "rules": [
+        "Create interface entities for endpoints",
+        "Document resources and their fields",
+        "Track error codes per endpoint",
+        "Note authentication requirements"
+      ]
+    },
+    "qualityGates": {
+      "fileChecks": [
+        {
+          "path": "README.md",
+          "required": [
+            "Base URL",
+            "Authentication",
+            "Quick Start"
+          ],
+          "optional": [
+            "SDK",
+            "Rate Limits"
+          ]
+        },
+        {
+          "path": "authentication.md",
+          "required": [
+            "Authorization",
+            "API Key"
+          ],
+          "optional": [
+            "OAuth",
+            "Scopes",
+            "Security"
+          ]
+        },
+        {
+          "path": "errors.md",
+          "required": [
+            "Error Response Format",
+            "Status Codes"
+          ],
+          "optional": [
+            "Error Codes",
+            "Troubleshooting"
+          ]
+        }
+      ],
+      "projectChecks": [
+        "At least one resource with CRUD endpoints documented",
+        "Authentication section is complete with examples",
+        "Error handling documentation exists",
+        "All endpoints have request/response examples",
+        "Rate limiting is documented"
+      ],
+      "exportReady": [
+        "All endpoints have complete documentation",
+        "Code examples exist for primary language(s)",
+        "Authentication flows are fully documented",
+        "All status codes and errors are documented",
+        "Examples use consistent, realistic data"
+      ]
+    },
+    "templateMetadata": {
+      "identifyByStructure": true
+    },
+    "exporters": [
+      {
+        "id": "markdown-docs",
+        "name": "Documentation Bundle",
+        "description": "Complete API documentation as ZIP",
+        "icon": "📚",
+        "format": "zip",
+        "category": "document",
+        "handler": "markdown-bundle",
+        "options": {
+          "includeFiles": [
+            "**/*.md"
+          ],
+          "preserveStructure": true,
+          "addReadme": true
+        }
+      }
+    ]
+  }
+}

package/kits/api-documentation/skills/api-examples/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: api-examples
+description: Generate code examples for API endpoints in multiple programming languages
+type: invocable
+version: "1.0.0"
+---
+
+## API Examples Skill
+
+When the user invokes `/examples`, generate clear, working code examples for API endpoints in multiple programming languages.
+
+### Invocation Patterns
+
+- `/examples` - Generate examples for current endpoint
+- `/examples [language]` - Generate for specific language
+- `/examples all` - Generate for all common languages
+
+### Supported Languages
+
+- cURL (universal baseline)
+- JavaScript (fetch, axios)
+- Python (requests)
+- Ruby
+- PHP
+- Go
+- Java
+- C# (.NET)
+
+### Example Templates
+
+**cURL**
+```bash
+curl -X POST 'https://api.example.com/v1/users' \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "email": "user@example.com",
+    "name": "John Doe"
+  }'
+```
+
+**JavaScript (fetch)**
+```javascript
+const response = await fetch('https://api.example.com/v1/users', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer YOUR_TOKEN',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    email: 'user@example.com',
+    name: 'John Doe',
+  }),
+});
+
+const data = await response.json();
+```
+
+**Python (requests)**
+```python
+import requests
+
+response = requests.post(
+    'https://api.example.com/v1/users',
+    headers={
+        'Authorization': 'Bearer YOUR_TOKEN',
+    },
+    json={
+        'email': 'user@example.com',
+        'name': 'John Doe',
+    }
+)
+
+data = response.json()
+```
+
+**Go**
+```go
+package main
+
+import (
+    "bytes"
+    "encoding/json"
+    "net/http"
+)
+
+func main() {
+    payload := map[string]string{
+        "email": "user@example.com",
+        "name":  "John Doe",
+    }
+    body, _ := json.Marshal(payload)
+
+    req, _ := http.NewRequest("POST", "https://api.example.com/v1/users", bytes.NewBuffer(body))
+    req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
+    req.Header.Set("Content-Type", "application/json")
+
+    client := &http.Client{}
+    resp, _ := client.Do(req)
+    defer resp.Body.Close()
+}
+```
+
+### Output Format
+
+```markdown
+## API Examples: [Endpoint Name]
+
+### Request
+- **Method**: POST
+- **URL**: `https://api.example.com/v1/users`
+- **Authentication**: Bearer token
+
+### cURL
+```bash
+[cURL example]
+```
+
+### JavaScript
+```javascript
+[JavaScript example]
+```
+
+### Python
+```python
+[Python example]
+```
+
+### Response Example
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+```
+
+### Best Practices
+
+**Code Quality**
+- Use realistic placeholder values
+- Include error handling in complex examples
+- Show response handling
+- Use idiomatic code for each language
+
+**Completeness**
+- Include all required headers
+- Show authentication
+- Include request body for POST/PUT
+- Show expected response
+
+**Clarity**
+- Use syntax highlighting
+- Add comments for complex steps
+- Keep examples minimal but complete
+- Use consistent formatting
+
+### Common Patterns
+
+**Authentication Examples**
+- Bearer token
+- API key (header vs query param)
+- Basic auth
+- OAuth flow
+
+**Request Body Patterns**
+- JSON (most common)
+- Form data
+- Multipart (file uploads)
+
+**Response Handling**
+- Success parsing
+- Error handling
+- Pagination

package/kits/api-documentation/skills/api-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: Review API Documentation
+description: Comprehensive review of API documentation for completeness and quality
+type: invocable
+version: "1.0.0"
+---
+
+## Review API Documentation
+
+Comprehensive review of API documentation for completeness and quality
+
+### Steps
+
+1. Check that all endpoints are documented with method, path, and description
+2. Verify authentication requirements are clear for each endpoint
+3. Ensure all request parameters are documented with types and requirements
+4. Verify all response formats are documented including error responses
+5. Check for consistent naming conventions across endpoints
+6. Verify examples are complete and use realistic data
+7. Check that rate limits and pagination are documented
+8. Identify any gaps or inconsistencies
+9. Provide prioritized improvement recommendations
+
+### Expected Outputs
+
+- Documentation review report
+- Improvement recommendations
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "review"
+- "check documentation"
+- "audit"
+- "completeness"