@soulcraft/kits 1.0.0

package/kits/technical-specification/kit.json

@@ -0,0 +1,369 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "technical-specification",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Technical Specification",
+  "description": "Detailed technical specification document for software projects",
+  "longDescription": "Complete technical specification template with architecture overview, data models, API design, security considerations, and implementation details. Structured for engineering review and stakeholder sign-off.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🏗️",
+  "tags": [
+    "technical",
+    "specification",
+    "architecture",
+    "design"
+  ],
+  "variables": [
+    {
+      "key": "projectName",
+      "label": "Project Name",
+      "description": "The name of the system or feature being specified",
+      "type": "string",
+      "required": true,
+      "example": "Customer Portal"
+    },
+    {
+      "key": "author",
+      "label": "Technical Lead",
+      "description": "The engineer authoring this specification",
+      "type": "string",
+      "required": false,
+      "example": "Your Name"
+    },
+    {
+      "key": "version",
+      "label": "Spec Version",
+      "description": "The version number of this specification",
+      "type": "string",
+      "required": false,
+      "example": "1.0",
+      "default": "1.0"
+    }
+  ],
+  "shared": {
+    "industry": "software-development",
+    "category": "development",
+    "aiExpertise": [
+      "Software architecture design",
+      "API contract definition",
+      "Data model design",
+      "Security threat modeling",
+      "Non-functional requirements specification"
+    ],
+    "dataModelHints": [
+      "concept",
+      "interface",
+      "resource",
+      "document"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "component",
+          "type": "Concept",
+          "description": "A software component or service within the system",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🔧"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "interface",
+          "type": "Concept",
+          "description": "An API contract or interface a component exposes",
+          "products": {
+            "workshop": {
+              "view": "tree",
+              "icon": "⚡"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "dataModel",
+          "type": "Concept",
+          "description": "A data schema or model used by the system",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🗂️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "service",
+          "type": "Concept",
+          "description": "An external or internal service depended on by components",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "☁️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "database",
+          "type": "Thing",
+          "description": "A data store or persistence layer used by the system",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🗄️"
+            },
+            "academy": {
+              "mapsTo": "resource",
+              "assessable": false
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "component",
+          "to": "component",
+          "verb": "DependsOn",
+          "description": "Component requires another component to function"
+        },
+        {
+          "from": "component",
+          "to": "interface",
+          "verb": "Implements",
+          "description": "Component implements this interface contract"
+        },
+        {
+          "from": "component",
+          "to": "database",
+          "verb": "Uses",
+          "description": "Component reads or writes to this data store"
+        },
+        {
+          "from": "component",
+          "to": "component",
+          "verb": "Contains",
+          "description": "System or module contains this component"
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Write a spec section",
+        "prompt": "Help me write a technical specification section"
+      },
+      {
+        "label": "Define architecture",
+        "prompt": "Help me define and document the system architecture"
+      },
+      {
+        "label": "Document APIs",
+        "prompt": "Help me document the API contracts and interfaces"
+      },
+      {
+        "label": "List requirements",
+        "prompt": "Help me define technical requirements and constraints"
+      },
+      {
+        "label": "Create diagrams",
+        "prompt": "Help me create a system diagram for my architecture"
+      },
+      {
+        "label": "Review spec",
+        "prompt": "Show me my technical specification structure and completeness"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "software-architecture",
+    "level": "advanced",
+    "learningObjectives": [
+      "Decompose a system into components with clear responsibilities and well-defined interfaces",
+      "Document API contracts with request/response schemas, error codes, and auth requirements",
+      "Design a data model identifying entities, fields, constraints, and indexing strategy",
+      "Perform a security threat model identifying attack surfaces and mitigations",
+      "Specify non-functional requirements (latency, throughput, availability) with measurable targets"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "software-architect"
+  },
+  "workshop": {
+    "difficulty": "advanced",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are a senior software architect helping engineering teams write clear, complete technical specifications that guide implementation and enable effective code review.",
+      "expertise": [
+        "Software architecture design",
+        "API contract definition",
+        "Data model design",
+        "Security and threat modeling",
+        "Performance and scalability planning"
+      ],
+      "tone": "collaborator"
+    },
+    "workspaceConfig": {
+      "paradigm": "developer",
+      "defaultTab": "edit",
+      "defaultView": "tree",
+      "defaultFile": "spec/overview.md",
+      "fallbackFiles": [
+        "README.md"
+      ],
+      "layout": {
+        "leftDock": "files",
+        "rightDock": "properties"
+      },
+      "onboarding": {
+        "showGuide": true,
+        "highlightFeatures": [
+          "tree",
+          "ai-chat"
+        ],
+        "suggestedActions": [
+          "Start with the overview document",
+          "Define your architecture in architecture.md",
+          "Document API endpoints systematically",
+          "Ask AI for security considerations"
+        ]
+      }
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "When user defines a component",
+          "When user describes an interface",
+          "When user creates a data model",
+          "When user identifies a dependency"
+        ],
+        "typeMapping": {
+          "component": "concept",
+          "interface": "interface",
+          "dataModel": "concept",
+          "service": "concept",
+          "database": "resource"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "dependsOn",
+          "description": "Component dependency"
+        },
+        {
+          "from": "concept",
+          "to": "interface",
+          "verb": "implements",
+          "description": "Component implements interface"
+        },
+        {
+          "from": "concept",
+          "to": "resource",
+          "verb": "uses",
+          "description": "Component uses database"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "contains",
+          "description": "System contains component"
+        }
+      ],
+      "rules": [
+        "Create concept entities for components",
+        "Track dependencies between components",
+        "Link components to interfaces",
+        "Document data flow relationships"
+      ]
+    },
+    "qualityGates": {
+      "fileChecks": [
+        {
+          "path": "technical-spec.md",
+          "required": [
+            "Executive Summary",
+            "Goals",
+            "Architecture",
+            "Data Model",
+            "Security"
+          ],
+          "optional": [
+            "Performance",
+            "Scalability",
+            "Deployment"
+          ]
+        },
+        {
+          "path": "api-design.md",
+          "required": [
+            "Endpoints"
+          ],
+          "optional": [
+            "Authentication",
+            "Error Handling"
+          ]
+        }
+      ],
+      "projectChecks": [
+        "Executive summary clearly states the problem and solution",
+        "Goals section has measurable success criteria",
+        "Architecture section includes component diagram",
+        "Non-functional requirements have specific targets",
+        "Security section addresses authentication and data protection",
+        "Risks and mitigations are documented"
+      ],
+      "exportReady": [
+        "All sections are complete with no TODOs",
+        "Architecture diagrams are included",
+        "Data model is fully specified",
+        "API contracts are defined",
+        "Document has been reviewed and approved"
+      ]
+    },
+    "exporters": [
+      {
+        "id": "spec-bundle",
+        "name": "Technical Specification Bundle",
+        "description": "Complete specification documents",
+        "icon": "📋",
+        "format": "zip",
+        "category": "document",
+        "handler": "markdown-bundle",
+        "options": {
+          "includeFiles": [
+            "**/*.md"
+          ],
+          "preserveStructure": true,
+          "addReadme": true
+        }
+      }
+    ],
+    "templateMetadata": {
+      "identifyByStructure": true
+    }
+  }
+}

package/kits/technical-specification/skills/architecture-decision/SKILL.md

@@ -0,0 +1,42 @@
+---
+id: architecture-decision
+name: Document Architecture Decision
+description: Create an Architecture Decision Record (ADR) for a technical choice
+version: "1.0.0"
+type: invocable
+parameters: [decision]
+requiresVision: false
+requiresData: false
+---
+
+## Document Architecture Decision
+
+Create an Architecture Decision Record (ADR) for a technical choice
+
+### Steps
+
+1. Identify the decision that needs to be made
+2. Describe the context and problem statement
+3. List the options considered with pros and cons
+4. Document the decision made and rationale
+5. Describe the consequences (positive and negative)
+6. Link to related decisions or requirements
+7. Add to the ADR index
+
+### Inputs Required
+
+- **decision** (required): Brief title of the decision
+- **context** (optional): Why this decision needs to be made
+
+### Expected Outputs
+
+- Architecture Decision Record (ADR)
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "architecture decision"
+- "ADR"
+- "should we use"
+- "which approach"
+- "design decision"

package/kits/technical-specification/skills/architecture-decisions/SKILL.md

@@ -0,0 +1,180 @@
+---
+id: architecture-decisions
+name: architecture-decisions
+description: Document Architecture Decision Records (ADRs) for technical specifications
+version: "1.0.0"
+type: invocable
+requiresVision: false
+requiresData: false
+---
+
+## Architecture Decision Records Skill
+
+When the user invokes `/adr`, help them document architecture decisions using the ADR format.
+
+### Invocation Patterns
+
+- `/adr` - Create new ADR for current decision
+- `/adr [title]` - Create ADR with specific title
+- `/adr review` - Review existing ADRs for consistency
+
+### ADR Structure
+
+```markdown
+# ADR-001: [Short Title]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[What is the issue that we're seeing that motivates this decision?]
+
+## Decision
+[What is the change that we're proposing and/or doing?]
+
+## Consequences
+[What becomes easier or more difficult because of this change?]
+```
+
+### Extended ADR Template
+
+```markdown
+# ADR-[NUMBER]: [TITLE]
+
+## Status
+[Status]
+
+## Date
+[YYYY-MM-DD]
+
+## Decision Makers
+[Who was involved in the decision]
+
+## Context
+[Background and problem statement]
+
+### Forces
+- [Force 1]: [Description]
+- [Force 2]: [Description]
+
+## Options Considered
+
+### Option 1: [Name]
+**Description**: [How it works]
+**Pros**:
+- [Pro 1]
+- [Pro 2]
+**Cons**:
+- [Con 1]
+- [Con 2]
+
+### Option 2: [Name]
+[Same format]
+
+## Decision
+[The chosen option and clear reasoning]
+
+## Consequences
+
+### Positive
+- [What becomes easier]
+
+### Negative
+- [What becomes harder]
+
+### Risks
+- [Risk 1]: [Mitigation]
+
+## Related Decisions
+- [ADR-XXX]: [Relationship]
+
+## Notes
+[Any additional context or future considerations]
+```
+
+### Output Format
+
+```markdown
+## Architecture Decision Record
+
+# ADR-[NUMBER]: [Generated Title]
+
+## Status
+Proposed
+
+## Date
+[Today's date]
+
+## Context
+[Synthesized from discussion]
+
+### Problem Statement
+[The specific problem being solved]
+
+### Forces
+[Constraints and considerations]
+
+## Options Considered
+
+### Option 1: [Name]
+[Analysis]
+
+### Option 2: [Name]
+[Analysis]
+
+### Option 3: [Name]
+[Analysis]
+
+## Decision
+We will use [Option X] because:
+1. [Reason 1]
+2. [Reason 2]
+
+## Consequences
+
+### Positive
+- [List]
+
+### Negative
+- [List]
+
+### Risks and Mitigations
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk] | [L/M/H] | [L/M/H] | [Strategy] |
+
+## Follow-up Actions
+- [ ] [Action item 1]
+- [ ] [Action item 2]
+```
+
+### When to Write an ADR
+
+Write an ADR when:
+- Choosing between technologies/frameworks
+- Defining major architectural patterns
+- Making security-related decisions
+- Setting coding standards
+- Choosing third-party integrations
+- Making decisions that are hard to reverse
+
+### Good ADR Characteristics
+
+**Concise**: One decision per ADR
+**Contextual**: Future readers understand why
+**Honest**: Include rejected options and tradeoffs
+**Immutable**: Supersede rather than edit
+**Numbered**: Easy to reference
+
+### Common Decision Areas
+
+- Database selection
+- API design patterns
+- Authentication approach
+- Deployment strategy
+- Testing strategy
+- Monitoring approach
+- Error handling patterns
+- Caching strategy
+- Message queue selection
+- Frontend framework

package/kits/technical-specification/skills/data-model-design/SKILL.md

@@ -0,0 +1,43 @@
+---
+id: data-model-design
+name: Design Data Model
+description: Create data model design for a feature or component
+version: "1.0.0"
+type: invocable
+parameters: [domain]
+requiresVision: false
+requiresData: false
+---
+
+## Design Data Model
+
+Create data model design for a feature or component
+
+### Steps
+
+1. Identify the entities and their attributes
+2. Define relationships between entities
+3. Choose appropriate data types for each attribute
+4. Identify primary keys and unique constraints
+5. Design indexes for query performance
+6. Consider normalization vs denormalization trade-offs
+7. Document the schema with DDL or diagram
+8. Add migration strategy if modifying existing schema
+
+### Inputs Required
+
+- **domain** (required): The domain or feature area
+
+### Expected Outputs
+
+- Data model documentation
+- Schema definition
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "data model"
+- "database schema"
+- "entities"
+- "ERD"
+- "schema design"