@softspark/ai-toolkit 1.0.0

package/app/skills/docs/scripts/doc-inventory.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Inventory documentation files and find gaps in coverage."""
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+IGNORE_DIRS = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build', '.next', 'vendor', '.cache'}
+
+SOURCE_EXTS = {'.py', '.js', '.ts', '.tsx', '.jsx', '.go', '.php', '.dart'}
+
+STANDARD_DOCS = ['README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', 'LICENSE', 'LICENSE.md']
+
+STALE_THRESHOLD_DAYS = 90
+
+
+def find_files(root: str, extensions: set) -> list:
+    result = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
+        for fn in filenames:
+            if Path(fn).suffix in extensions or fn in extensions:
+                result.append(os.path.join(dirpath, fn))
+    return result
+
+
+def find_doc_files(root: str) -> list:
+    docs = []
+    # Check standard docs in root
+    for doc in STANDARD_DOCS:
+        p = os.path.join(root, doc)
+        if os.path.isfile(p):
+            docs.append(os.path.relpath(p, root))
+    # Check docs/ directory
+    docs_dir = os.path.join(root, 'docs')
+    if os.path.isdir(docs_dir):
+        for dirpath, dirnames, filenames in os.walk(docs_dir):
+            dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
+            for fn in filenames:
+                if fn.endswith(('.md', '.rst', '.txt', '.adoc')):
+                    docs.append(os.path.relpath(os.path.join(dirpath, fn), root))
+    return docs
+
+
+def count_public_symbols(filepath: str) -> tuple:
+    """Returns (total_public, documented_count)."""
+    ext = Path(filepath).suffix
+    total, documented = 0, 0
+    try:
+        with open(filepath, 'r', errors='replace') as f:
+            lines = f.readlines()
+    except OSError:
+        return 0, 0
+
+    if ext == '.py':
+        for i, line in enumerate(lines):
+            m = re.match(r'^(def|class)\s+(\w+)', line)
+            if m and not m.group(2).startswith('_'):
+                total += 1
+                # Check for docstring on next non-empty line
+                for j in range(i + 1, min(i + 4, len(lines))):
+                    stripped = lines[j].strip()
+                    if stripped.startswith(('"""', "'''")):
+                        documented += 1
+                        break
+                    if stripped and not stripped.startswith(('#', ')')):
+                        break
+
+    elif ext in ('.js', '.ts', '.tsx', '.jsx'):
+        for i, line in enumerate(lines):
+            if re.search(r'export\s+(function|class|const|let|interface|type|enum)\s+', line):
+                total += 1
+                # Check for JSDoc before export
+                for j in range(max(0, i - 5), i):
+                    if '/**' in lines[j]:
+                        documented += 1
+                        break
+
+    elif ext == '.go':
+        for i, line in enumerate(lines):
+            m = re.match(r'^func\s+(?:\([^)]*\)\s+)?([A-Z]\w*)', line)
+            if m:
+                total += 1
+                # Check for // comment on preceding line
+                if i > 0 and lines[i - 1].strip().startswith('//'):
+                    documented += 1
+            m = re.match(r'^type\s+([A-Z]\w*)', line)
+            if m:
+                total += 1
+                if i > 0 and lines[i - 1].strip().startswith('//'):
+                    documented += 1
+
+    elif ext == '.php':
+        for i, line in enumerate(lines):
+            m = re.match(r'\s*(?:public|protected)\s+function\s+(\w+)', line)
+            if m and not m.group(1).startswith('_'):
+                total += 1
+                for j in range(max(0, i - 5), i):
+                    if '/**' in lines[j]:
+                        documented += 1
+                        break
+
+    elif ext == '.dart':
+        for i, line in enumerate(lines):
+            m = re.match(r'^(?:class|enum)\s+(\w+)', line)
+            if not m:
+                m = re.match(r'^(\w+\s+\w+)\s*\(', line)
+            if m:
+                total += 1
+                for j in range(max(0, i - 5), i):
+                    if '///' in lines[j]:
+                        documented += 1
+                        break
+
+    return total, documented
+
+
+def get_mtime(filepath: str) -> float:
+    try:
+        return os.path.getmtime(filepath)
+    except OSError:
+        return 0.0
+
+
+def main():
+    root = os.path.abspath(sys.argv[1]) if len(sys.argv) > 1 else os.getcwd()
+    if not os.path.isdir(root):
+        print(json.dumps({"error": f"Not a directory: {root}"}))
+        sys.exit(1)
+
+    existing_docs = find_doc_files(root)
+    missing_docs = [d for d in STANDARD_DOCS if d not in existing_docs]
+
+    # Count public symbols across source files
+    source_files = find_files(root, SOURCE_EXTS)
+    total_public, total_documented = 0, 0
+    latest_code_mtime = 0.0
+
+    for sf in source_files:
+        pub, doc = count_public_symbols(sf)
+        total_public += pub
+        total_documented += doc
+        mt = get_mtime(sf)
+        if mt > latest_code_mtime:
+            latest_code_mtime = mt
+
+    coverage = round((total_documented / total_public * 100), 1) if total_public > 0 else 0.0
+
+    # Check for stale docs
+    stale_docs = []
+    threshold = STALE_THRESHOLD_DAYS * 86400
+    for doc in existing_docs:
+        doc_path = os.path.join(root, doc)
+        doc_mtime = get_mtime(doc_path)
+        if latest_code_mtime > 0 and doc_mtime > 0:
+            if (latest_code_mtime - doc_mtime) > threshold:
+                days_behind = int((latest_code_mtime - doc_mtime) / 86400)
+                stale_docs.append({"file": doc, "days_behind_code": days_behind})
+
+    result = {
+        "existing_docs": existing_docs,
+        "missing_docs": missing_docs,
+        "public_functions_total": total_public,
+        "documented_count": total_documented,
+        "doc_coverage_percent": coverage,
+        "stale_docs": stale_docs,
+    }
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/app/skills/docs/templates/adr-template.md

@@ -0,0 +1,36 @@
+# Architecture Note: [Title]
+
+## Status
+
+[Draft | Accepted | Deprecated | Superseded]
+
+## Context
+
+[What is the issue that we're seeing that is motivating this decision or change?]
+
+## Decision
+
+[What is the change that we're proposing and/or doing?]
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Risks
+- [Risk 1 and mitigation]
+
+## Alternatives Considered
+
+### Option A: [Name]
+- Pros: [...]
+- Cons: [...]
+
+### Option B: [Name]
+- Pros: [...]
+- Cons: [...]

package/app/skills/docs/templates/readme-template.md

@@ -0,0 +1,67 @@
+# Project Name
+
+Brief description of what this project does.
+
+## Quick Start
+
+```bash
+# Install
+[installation command]
+
+# Run
+[run command]
+```
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Language | [e.g., Python 3.12] |
+| Framework | [e.g., FastAPI] |
+| Database | [e.g., PostgreSQL] |
+| Cache | [e.g., Redis] |
+
+## Development
+
+### Prerequisites
+- [Requirement 1]
+- [Requirement 2]
+
+### Setup
+```bash
+[setup commands]
+```
+
+### Testing
+```bash
+[test commands]
+```
+
+### Linting
+```bash
+[lint commands]
+```
+
+## Project Structure
+```
+src/
+  [key directories and their purpose]
+```
+
+## API Documentation
+
+[Link or brief description]
+
+## Contributing
+
+[Contributing guidelines or link]
+
+## License
+
+[License type]

package/app/skills/documentation-standards/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: documentation-standards
+description: "Loaded when creating or updating KB documents, architecture notes, SOPs, or any file in kb/ directory"
+effort: medium
+user-invocable: false
+---
+
+# Documentation Standards
+
+Auto-loaded knowledge skill enforcing KB document conventions across all agents and skills.
+
+## Frontmatter Specification (MANDATORY)
+
+Every document in `kb/` MUST start with YAML frontmatter:
+
+```yaml
+---
+title: "Document Title"                    # REQUIRED — English, descriptive
+category: reference                        # REQUIRED — one of 5 valid categories
+service: ai-toolkit                        # REQUIRED — service identifier
+tags: [tag1, tag2, tag3]                   # REQUIRED — minimum 1, recommended 3+
+last_updated: "YYYY-MM-DD"                 # REQUIRED — ISO format
+created: "YYYY-MM-DD"                      # REQUIRED — creation date
+description: "One-line summary."           # REQUIRED — for search indexing
+version: "1.0.0"                           # optional — semver
+---
+```
+
+**All 7 fields above are REQUIRED.** Documents without valid frontmatter **fail `validate.sh` and block CI**.
+
+## Category Taxonomy
+
+| Category | Directory | Purpose | Examples |
+|----------|-----------|---------|----------|
+| `reference` | `kb/reference/` | Technical specifications, catalogs, architecture notes, API docs | `agents-catalog.md`, `architecture-overview.md` |
+| `howto` | `kb/howto/` | Step-by-step task guides | `use-corrective-rag.md`, `configure-mcp-server.md` |
+| `procedures` | `kb/procedures/` | SOPs, runbooks, operational processes | `maintenance-sop.md`, `incident-response.md` |
+| `troubleshooting` | `kb/troubleshooting/` | Problem resolution, debugging guides | `database-connection-issues.md` |
+| `best-practices` | `kb/best-practices/` | Guidelines, recommendations, standards | `security-checklist.md` |
+
+**Rule:** The `category:` frontmatter field MUST match the directory the file lives in.
+
+## Naming Conventions
+
+- **Filename:** kebab-case, descriptive, no dates (`merge-friendly-install-model.md`)
+- **Title:** English, clear, matches filename semantics
+- **No prefixes:** no `001-`, no `YYYY-MM-DD-` in filenames (dates go in frontmatter)
+- **Max length:** keep filenames under 60 characters
+
+## Language Rule
+
+**All KB content MUST be in English.** No exceptions for:
+- Document titles
+- Body content
+- Code comments within docs
+- Table headers and descriptions
+
+## Quality Standards
+
+### Required for every KB document:
+- [ ] Valid YAML frontmatter with all 7 required fields
+- [ ] Category matches directory
+- [ ] Written in English
+- [ ] Title is clear and descriptive
+- [ ] Content is actionable (not just placeholders)
+
+### Required for procedural docs (howto, procedures):
+- [ ] Prerequisites listed
+- [ ] Steps are numbered
+- [ ] Commands are copy-pasteable
+- [ ] Verification section present
+
+### Required for troubleshooting docs:
+- [ ] Symptoms described
+- [ ] Root cause identified
+- [ ] Resolution steps provided
+- [ ] Prevention notes included
+
+## Templates
+
+### Reference Document
+```yaml
+---
+title: "AI Toolkit - [Topic]"
+category: reference
+service: ai-toolkit
+tags: [topic, subtopic]
+version: "1.0.0"
+created: "YYYY-MM-DD"
+last_updated: "YYYY-MM-DD"
+description: "Brief summary."
+---
+
+# [Topic]
+
+## Overview
+[What this document covers]
+
+## Details
+[Technical content]
+
+## Related
+- [Other relevant KB docs]
+```
+
+### How-To Guide
+```yaml
+---
+title: "How to [Task]"
+category: howto
+service: ai-toolkit
+tags: [howto, task-name]
+created: "YYYY-MM-DD"
+last_updated: "YYYY-MM-DD"
+description: "Step-by-step guide for [task]."
+---
+
+# How to [Task]
+
+## Prerequisites
+- [Requirement]
+
+## Steps
+
+### 1. [Action]
+[Instructions + commands]
+
+### 2. [Action]
+[Instructions + commands]
+
+## Verification
+[How to confirm success]
+
+## Troubleshooting
+| Problem | Solution |
+|---------|----------|
+| [Error] | [Fix]    |
+```
+
+### SOP / Procedure
+```yaml
+---
+title: "SOP: [Process Name]"
+category: procedures
+service: ai-toolkit
+tags: [sop, process-name]
+created: "YYYY-MM-DD"
+last_updated: "YYYY-MM-DD"
+description: "Standard procedure for [process]."
+---
+
+# SOP: [Process Name]
+
+## Purpose
+[Why this procedure exists]
+
+## Prerequisites
+- [Requirement]
+
+## Procedure
+### Step 1: [Action]
+[Detailed instructions]
+
+## Verification
+[How to verify success]
+
+## Rollback
+[How to revert if needed]
+```
+
+## Validation
+
+```bash
+# Validates ALL kb/**/*.md frontmatter (title, category, service, tags, created, last_updated, description)
+scripts/validate.py
+
+# Checks: required fields present, category is valid, tags non-empty
+```
+
+Valid categories: `reference`, `howto`, `procedures`, `troubleshooting`, `best-practices`.
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| No frontmatter | Blocks CI, not indexed | Add frontmatter with all required fields |
+| Wrong category | Confuses search | Match `category:` to directory name |
+| Non-English content | Inconsistent KB | Translate to English |
+| Date in filename | Clutters, becomes stale | Use `created:` in frontmatter |
+| Empty tags | Hurts search relevance | Add at least 1 meaningful tag |
+| Placeholder content | Wastes reader time | Write real content or don't create the doc |

package/app/skills/ecommerce-patterns/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: ecommerce-patterns
+description: "Loaded when user asks about e-commerce or shopping cart features"
+effort: medium
+user-invocable: false
+---
+
+# E-commerce Patterns Skill
+
+## Platform Selection
+
+| Scenario | Platform |
+|----------|----------|
+| Enterprise B2B | OroCommerce |
+| Enterprise B2C | Magento 2 |
+| Mid-market | Shopify Plus |
+| Small business | WooCommerce, PrestaShop |
+| Custom/Headless | Medusa, Saleor |
+
+---
+
+## Magento 2 Patterns
+
+### Module Structure
+```
+app/code/Vendor/Module/
+├── Api/
+│   └── Data/
+│       └── EntityInterface.php
+├── Block/
+├── Controller/
+│   └── Index/
+│       └── Index.php
+├── etc/
+│   ├── module.xml
+│   ├── di.xml
+│   ├── routes.xml
+│   └── frontend/
+├── Model/
+│   └── ResourceModel/
+├── Setup/
+├── view/
+│   └── frontend/
+│       ├── layout/
+│       └── templates/
+├── registration.php
+└── composer.json
+```
+
+### Dependency Injection
+```xml
+<!-- etc/di.xml -->
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
+    <preference for="Vendor\Module\Api\ServiceInterface" type="Vendor\Module\Model\Service"/>
+    <type name="Vendor\Module\Model\Service">
+        <arguments>
+            <argument name="logger" xsi:type="object">Psr\Log\LoggerInterface</argument>
+        </arguments>
+    </type>
+</config>
+```
+
+### GraphQL
+```graphql
+type Query {
+    customProducts(
+        search: String
+        pageSize: Int = 20
+        currentPage: Int = 1
+    ): CustomProductOutput @resolver(class: "Vendor\\Module\\Model\\Resolver\\Products")
+}
+```
+
+---
+
+## Cart & Checkout Patterns
+
+### Cart State Machine
+```
+Empty → Has Items → Checkout Started → Payment → Order Placed
+                  ↑                    ↓
+                  └──── Abandoned ←────┘
+```
+
+### Checkout Flow
+```
+1. Cart Review
+2. Shipping Address
+3. Shipping Method
+4. Payment Method
+5. Order Review
+6. Place Order
+7. Confirmation
+```
+
+### Price Calculation
+```
+Base Price
+- Catalog Discounts
+= Adjusted Price
+× Quantity
+= Line Total
++ Tax (if exclusive)
+= Line Total with Tax
+Σ All Lines
+= Subtotal
++ Shipping
+- Cart Discounts
+= Grand Total
+```
+
+---
+
+## Inventory Patterns
+
+### Stock Management
+```python
+class InventoryService:
+    def reserve_stock(self, product_id: str, qty: int) -> bool:
+        """Reserve stock during checkout."""
+        with transaction.atomic():
+            stock = Stock.select_for_update().get(product_id=product_id)
+            if stock.available >= qty:
+                stock.reserved += qty
+                stock.available -= qty
+                stock.save()
+                return True
+            return False
+
+    def confirm_stock(self, reservation_id: str):
+        """Confirm reservation after order placed."""
+        reservation.status = 'confirmed'
+        reservation.save()
+
+    def release_stock(self, reservation_id: str):
+        """Release stock if order cancelled."""
+        # Return reserved qty to available
+```
+
+### Multi-Warehouse
+```sql
+-- Stock per warehouse
+SELECT
+    p.sku,
+    w.name as warehouse,
+    s.quantity,
+    s.reserved
+FROM stock s
+JOIN products p ON s.product_id = p.id
+JOIN warehouses w ON s.warehouse_id = w.id
+WHERE p.sku = 'SKU-123';
+```
+
+---
+
+## Search & Catalog
+
+### Product Indexing
+```
+Product → Indexer → Search Index (Elasticsearch/OpenSearch)
+                  → Price Index
+                  → Category Index
+                  → Stock Index
+```
+
+### Faceted Search
+```json
+{
+  "aggs": {
+    "categories": {
+      "terms": { "field": "category_ids" }
+    },
+    "price_ranges": {
+      "range": {
+        "field": "price",
+        "ranges": [
+          { "to": 50 },
+          { "from": 50, "to": 100 },
+          { "from": 100 }
+        ]
+      }
+    },
+    "brands": {
+      "terms": { "field": "brand" }
+    }
+  }
+}
+```
+
+---
+
+## Performance
+
+### Caching Layers
+| Layer | Cache |
+|-------|-------|
+| Page | Varnish, CDN |
+| Block | Redis |
+| Query | MySQL Query Cache |
+| Full Page | Redis FPC |
+
+### Optimization Checklist
+- [ ] Enable production mode
+- [ ] Enable full page cache
+- [ ] Optimize images (WebP)
+- [ ] Minify JS/CSS
+- [ ] Enable flat tables
+- [ ] Configure CDN
+- [ ] Index optimization