@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/rules/REF_WORKFLOWS.md

@@ -0,0 +1,81 @@
+---
+trigger: always_on
+---
+
+# REF_WORKFLOWS.md - Workflows & Scripts Reference
+
+> This module contains lookup tables for workflows and scripts.
+
+---
+
+## Workflows (22)
+
+| Command | Purpose |
+|---------|---------|
+| `/ai-agent` | Build AI agent workflow (NEW) |
+| `/marketing` | Marketing campaign planning (NEW) |
+| `/pentest` | Penetration testing workflow (NEW) |
+| `/saas` | SaaS launch workflow (NEW) |
+| `/gamekit-init` | Initialize game project with Spec Ecosystem structure |
+| `/gamekit-spec` | Create game specification with Explained Q&A + GDD |
+| `/gamekit-plan` | Generate implementation plan from approved spec |
+| `/gamekit-tasks` | Generate executable task list from approved plan |
+| `/gamekit-qa` | **Playtest and QA loop for iterative refinement (NEW)** |
+| `/gamekit-launch` | **Mobile game launch: Build → Store → Post-launch (NEW)** |
+| `/autofix` | Autonomous self-healing loop |
+| `/brainstorm` | Structured brainstorming |
+| `/context` | Optimal context generation |
+| `/create` | Create new applications |
+| `/dashboard` | Visual project dashboards |
+| `/debug` | Systematic investigation |
+| `/deploy` | Production deployment |
+| `/enhance` | Add/update features |
+| `/next` | Next development steps |
+| `/orchestrate` | Multi-agent coordination |
+| `/plan` | Project planning |
+| `/preview` | Dev server management |
+| `/quality` | Context/output optimization |
+| `/spec` | Specification documents |
+| `/status` | Project/agent status |
+| `/test` | Create and run tests |
+| `/ui-ux-pro-max` | Professional UI/UX planning |
+
+---
+
+## Available Scripts (12 total)
+
+| Script | Skill | When to Use |
+|--------|-------|-------------|
+| `security_scan.py` | vulnerability-scanner | Always on deploy |
+| `dependency_analyzer.py` | vulnerability-scanner | Weekly / Deploy |
+| `lint_runner.py` | lint-and-validate | Every code change |
+| `test_runner.py` | testing-patterns | After logic change |
+| `schema_validator.py` | database-design | After DB change |
+| `ux_audit.py` | frontend-design | After UI change |
+| `accessibility_checker.py` | frontend-design | After UI change |
+| `seo_checker.py` | seo-fundamentals | After page change |
+| `bundle_analyzer.py` | performance-profiling | Before deploy |
+| `mobile_audit.py` | mobile-design | After mobile change |
+| `lighthouse_audit.py` | performance-profiling | Before deploy |
+| `playwright_runner.py` | webapp-testing | Before deploy |
+| `prompt_injection_scanner.py` | ai-security-guardrails | Security audit / Deploy |
+| `pii_scanner.py` | privacy-preserving-dev | Privacy audit / Deploy |
+| `otel_validator.py` | observability-patterns | Observability check |
+| `trace_analyzer.py` | opentelemetry-expert | Performance optimization |
+
+---
+
+## Script Locations
+
+| Script | Path |
+|--------|------|
+| Full verify | `scripts/verify_all.py` |
+| Security scan | `.agent/skills/vulnerability-scanner/scripts/security_scan.py` |
+| UX audit | `.agent/skills/frontend-design/scripts/ux_audit.py` |
+| Mobile audit | `.agent/skills/mobile-design/scripts/mobile_audit.py` |
+| Lighthouse | `.agent/skills/performance-profiling/scripts/lighthouse_audit.py` |
+| Playwright | `.agent/skills/webapp-testing/scripts/playwright_runner.py` |
+| Prompt injection | `.agent/skills/ai-security-guardrails/scripts/prompt_injection_scanner.py` |
+| PII scan | `.agent/skills/privacy-preserving-dev/scripts/pii_scanner.py` |
+| OTel validator | `.agent/skills/observability-patterns/scripts/otel_validator.py` |
+| Trace analyzer | `.agent/skills/opentelemetry-expert/scripts/trace_analyzer.py` |

package/.agent/scripts/ak_cli.py

@@ -14,6 +14,7 @@ Usage:
     ak memory            # Manage JSON memory
     ak autofix           # Autonomous repair loop
     ak dashboard         # Open visual dashboard
+    ak workflows         # Show available workflows guide
 """
 
 import os
@@ -611,6 +612,11 @@ def cmd_memory(args: argparse.Namespace) -> int:
     if args.task: cmd_args.extend(["--task", args.task])
     if args.status: cmd_args.extend(["--status", args.status])
     if args.level: cmd_args.extend(["--level", args.level])
+    if args.point: cmd_args.extend(["--point", args.point])
+    if args.chosen: cmd_args.extend(["--chosen", args.chosen])
+    if args.rationale: cmd_args.extend(["--rationale", args.rationale])
+    if args.alternatives: cmd_args.extend(["--alternatives", args.alternatives])
+    if args.category: cmd_args.extend(["--category", args.category])
     
     return run_python_script(memory_script, cmd_args)
 
@@ -642,6 +648,92 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     return 1
 
 
+# ============================================================================
+# Command: workflows
+# ============================================================================
+
+def cmd_workflows(args: argparse.Namespace) -> int:
+    """Display available workflows guide."""
+    project_root = Path(args.project_root).resolve()
+    kit_path = get_kit_path()
+    
+    # Get language from memory
+    language = "en"
+    user_json = project_root / ".agent" / "memory" / "user.json"
+    if user_json.exists():
+        try:
+            with open(user_json, "r", encoding="utf-8") as f:
+                user_data = json.load(f)
+                language = user_data.get("preferences", {}).get("language", "en")
+        except:
+            pass
+
+    # Try to find WORKFLOW_GUIDE.md with language suffix in various possible locations
+    guide_names = [f"WORKFLOW_GUIDE.{language}.md", "WORKFLOW_GUIDE.md"]
+    
+    # Priority: 
+    # 1. Project-local .agent/templates/docs/ (installed)
+    # 2. Kit-source .agent/templates/docs/ (repo source)
+    # 3. Top-level docs/ (fallback for dev)
+    
+    search_dirs = [
+        project_root / ".agent" / "templates" / "docs",
+        kit_path / "templates" / "docs",
+        project_root / "docs",
+        kit_path.parent / "docs",
+    ]
+    
+    guide_content = None
+    for sdir in search_dirs:
+        for name in guide_names:
+            path = sdir / name
+            if path.exists():
+                with open(path, "r", encoding="utf-8") as f:
+                    guide_content = f.read()
+                break
+        if guide_content:
+            break
+    
+    if guide_content:
+        print(BANNER)
+        print(f"📚 AGENT KIT WORKFLOW GUIDE ({language.upper()})")
+        print("=" * 60)
+        print(guide_content)
+        return 0
+    else:
+        # Fallback: list workflows from directory
+        print(BANNER)
+        print("📚 Available Workflows:")
+        print("=" * 60)
+        
+        workflow_dir = kit_path / "workflows"
+        if not workflow_dir.exists():
+            workflow_dir = project_root / ".agent" / "workflows"
+        
+        if workflow_dir.exists():
+            workflows = sorted(workflow_dir.glob("*.md"))
+            for wf in workflows:
+                name = wf.stem
+                # Read description from frontmatter
+                with open(wf, "r", encoding="utf-8") as f:
+                    content = f.read()
+                desc = ""
+                if "description:" in content:
+                    for line in content.split("\n"):
+                        if line.startswith("description:"):
+                            desc = line.split(":", 1)[1].strip()
+                            break
+                print(f"  /{name:20} {desc[:50]}")
+            print("")
+            print("💡 Use /<workflow-name> in AI chat to activate.")
+            print("📖 Full guide: docs/WORKFLOW_GUIDE.md")
+        else:
+            print("❌ Workflows directory not found")
+            return 1
+        
+        return 0
+
+
 # ============================================================================
 # Main Entry Point
 # ============================================================================
@@ -699,13 +791,18 @@ Examples:
     
     # memory command
     memory_parser = subparsers.add_parser("memory", help="Manage JSON memory")
-    memory_parser.add_argument("mem_command", choices=["init", "get", "set", "update-task", "set-level", "set-lang"])
-    memory_parser.add_argument("--type", choices=["brain", "session", "user"], default="session")
+    memory_parser.add_argument("mem_command", choices=["init", "get", "set", "update-task", "set-level", "set-lang", "log-decision"])
+    memory_parser.add_argument("--type", choices=["brain", "session", "user", "decisions"], default="session")
     memory_parser.add_argument("--key", help="Key to get or set")
     memory_parser.add_argument("--value", help="Value to set")
-    memory_parser.add_argument("--task", help="Task name")
-    memory_parser.add_argument("--status", choices=["active", "completed"], help="Task status")
-    memory_parser.add_argument("--level", choices=["newbie", "basic", "technical"], help="User level")
+    memory_parser.add_argument("--task", help="Task name for update-task")
+    memory_parser.add_argument("--status", choices=["active", "completed"], help="Status for update-task")
+    memory_parser.add_argument("--level", choices=["newbie", "basic", "technical"], help="Level for set-level")
+    memory_parser.add_argument("--point", help="Decision point for log-decision")
+    memory_parser.add_argument("--chosen", help="Chosen option for log-decision")
+    memory_parser.add_argument("--rationale", help="Rationale for log-decision")
+    memory_parser.add_argument("--alternatives", help="Comma-separated rejected alternatives")
+    memory_parser.add_argument("--category", default="general", help="Decision category")
     
     # autofix command
     autofix_parser = subparsers.add_parser("autofix", help="Autonomous repair loop")
@@ -714,6 +811,9 @@ Examples:
     # dashboard command
     subparsers.add_parser("dashboard", help="Open visual dashboard")
     
+    # workflows command
+    subparsers.add_parser("workflows", help="Show available workflows guide")
+    
     args = parser.parse_args()
     
     if args.command is None:
@@ -729,6 +829,7 @@ Examples:
         "memory": cmd_memory,
         "autofix": cmd_autofix,
         "dashboard": cmd_dashboard,
+        "workflows": cmd_workflows,
     }
     
     handler = commands.get(args.command)

package/.agent/scripts/memory_manager.py

@@ -13,7 +13,8 @@ class MemoryManager:
         self.files = {
             "brain": self.memory_dir / "brain.json",
             "session": self.memory_dir / "session.json",
-            "user": self.memory_dir / "user.json"
+            "user": self.memory_dir / "user.json",
+            "decisions": self.memory_dir / "decisions.json"
         }
         
         self._ensure_files()
@@ -43,6 +44,14 @@ class MemoryManager:
                     "auto_sync": True,
                     "language": "en"
                 }
+            },
+            "decisions": {
+                "version": "1.0.0",
+                "decisions": [],
+                "metadata": {
+                    "created_at": datetime.now().isoformat(),
+                    "description": "Decision log for AI agent decisions with full rationale"
+                }
             }
         }
         
@@ -62,7 +71,12 @@ class MemoryManager:
         if memory_type not in self.files:
             raise ValueError(f"Unknown memory type: {memory_type}")
         
-        data["last_updated" if memory_type == "brain" else "last_interaction"] = datetime.now().isoformat()
+        if memory_type == "brain":
+            data["last_updated"] = datetime.now().isoformat()
+        elif memory_type == "decisions":
+            pass # Keep version and metadata
+        else:
+            data["last_interaction"] = datetime.now().isoformat()
         
         with open(self.files[memory_type], "w") as f:
             json.dump(data, f, indent=2)
@@ -80,16 +94,41 @@ class MemoryManager:
                 session["completed_tasks"].append(task_name)
         self.save("session", session)
 
+    def log_decision(self, point: str, chosen: str, rationale: str, alternatives: str = "", category: str = "general"):
+        """Explicitly log a technical or architectural decision."""
+        decisions_data = self.load("decisions")
+        
+        new_decision = {
+            "id": f"dec-{datetime.now().strftime('%Y%m%d-%H%M%S')}",
+            "timestamp": datetime.now().isoformat(),
+            "category": category,
+            "decision_point": point,
+            "chosen_option": chosen,
+            "rejected_options": [alt.strip() for alt in alternatives.split(",")] if alternatives else [],
+            "rationale": rationale,
+            "metadata": {
+                "source": "ak cli"
+            }
+        }
+        
+        decisions_data["decisions"].append(new_decision)
+        self.save("decisions", decisions_data)
+
 if __name__ == "__main__":
     import argparse
     parser = argparse.ArgumentParser(description="Manage Agent Kit JSON Memory")
-    parser.add_argument("command", choices=["init", "get", "set", "update-task", "set-level", "set-lang"])
+    parser.add_argument("command", choices=["init", "get", "set", "update-task", "set-level", "set-lang", "log-decision"])
     parser.add_argument("--type", choices=["brain", "session", "user"], default="session")
     parser.add_argument("--key", help="Key to get or set")
     parser.add_argument("--value", help="Value to set")
     parser.add_argument("--task", help="Task name for update-task")
     parser.add_argument("--status", choices=["active", "completed"], help="Status for update-task")
     parser.add_argument("--level", choices=["newbie", "basic", "technical"], help="Level for set-level")
+    parser.add_argument("--point", help="Decision point for log-decision")
+    parser.add_argument("--chosen", help="Chosen option for log-decision")
+    parser.add_argument("--rationale", help="Rationale for log-decision")
+    parser.add_argument("--alternatives", help="Rejected alternatives for log-decision")
+    parser.add_argument("--category", default="general", help="Category for log-decision")
     parser.add_argument("--root", default=".", help="Project root")
     
     args = parser.parse_args()
@@ -107,12 +146,6 @@ if __name__ == "__main__":
         if args.task and args.status:
             manager.update_task(args.task, args.status)
             print(f"✅ Task '{args.task}' set to {args.status}")
-    elif args.command == "set-level":
-        if args.level:
-            user = manager.load("user")
-            user["skill_level"] = args.level
-            manager.save("user", user)
-            print(f"✅ User skill level set to: {args.level}")
     elif args.command == "set-lang":
         if args.value:
             user = manager.load("user")
@@ -136,3 +169,9 @@ if __name__ == "__main__":
                 print(f"✅ Workflow descriptions updated to: {args.value}")
             except Exception as e:
                 print(f"⚠️ Failed to localize workflows: {str(e)}")
+    elif args.command == "log-decision":
+        if args.point and args.chosen and args.rationale:
+            manager.log_decision(args.point, args.chosen, args.rationale, args.alternatives or "", args.category or "general")
+            print(f"✅ Decision logged: {args.point}")
+        else:
+            print("❌ Missing required arguments for log-decision: --point, --chosen, --rationale")

package/.agent/skills/anti-hallucination/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: anti-hallucination
+description: "Multi-layer hallucination detection for AI-generated code. Detects phantom APIs, packages, and documentation mismatches. Use when validating AI code output."
+version: "1.0.0"
+---
+
+# 🔮 Anti-Hallucination Guard
+
+> **"Code that looks right isn't always right"**
+
+AI models can confidently generate code that references non-existent APIs, packages, or features. This skill provides multi-layer detection to catch hallucinations before they reach production.
+
+---
+
+## When to Use This Skill
+
+- Validating AI-generated code
+- Before committing AI outputs
+- After major code generation tasks
+- When code "looks right" but fails
+
+---
+
+## 1. Hallucination Types
+
+| Type | Description | Detection Difficulty |
+|------|-------------|---------------------|
+| **Phantom Package** | Package doesn't exist in registry | 🟢 Easy |
+| **Phantom API** | Method/function doesn't exist | 🟡 Medium |
+| **Wrong Signature** | Correct API, wrong parameters | 🟠 Hard |
+| **Stale Feature** | Feature removed in newer version | 🟠 Hard |
+| **Made-up Option** | Config option that doesn't exist | 🔴 Very Hard |
+
+---
+
+## 2. Detection Layers
+
+### Layer 1: Package Existence
+
+```bash
+# NPM packages
+npm view <package-name> version
+
+# Python packages  
+pip index versions <package-name>
+
+# Bulk check
+cat package.json | jq '.dependencies | keys[]' | xargs -I{} npm view {} version
+```
+
+```python
+def check_package_exists(package: str, registry: str) -> bool:
+    if registry == "npm":
+        result = subprocess.run(
+            ["npm", "view", package, "version"],
+            capture_output=True
+        )
+        return result.returncode == 0
+    elif registry == "pypi":
+        response = requests.get(f"https://pypi.org/pypi/{package}/json")
+        return response.status_code == 200
+    return False
+```
+
+### Layer 2: API Validation
+
+```python
+def validate_api_calls(code: str, language: str) -> List[Issue]:
+    issues = []
+    
+    if language == "typescript":
+        # Use TypeScript compiler
+        result = subprocess.run(
+            ["tsc", "--noEmit", "--strict"],
+            capture_output=True
+        )
+        if result.returncode != 0:
+            issues.extend(parse_tsc_errors(result.stderr))
+    
+    elif language == "python":
+        # Use mypy + pyright
+        result = subprocess.run(
+            ["pyright", "--outputjson"],
+            capture_output=True
+        )
+        issues.extend(parse_pyright_errors(result.stdout))
+    
+    return issues
+```
+
+### Layer 3: Documentation Cross-Check
+
+```python
+KNOWN_APIS = {
+    "fetch": {
+        "methods": ["json", "text", "blob", "arrayBuffer", "formData"],
+        "not_methods": ["advanced", "simple", "smart"]  # Common hallucinations
+    },
+    "console": {
+        "methods": ["log", "error", "warn", "info", "table", "dir"],
+        "not_methods": ["print", "output", "display"]
+    }
+}
+
+def check_api_against_docs(api_call: str) -> Optional[Issue]:
+    obj, method = api_call.split(".")
+    
+    if obj in KNOWN_APIS:
+        known = KNOWN_APIS[obj]
+        if method in known.get("not_methods", []):
+            return Issue(
+                type="PHANTOM_API",
+                detail=f"{obj}.{method} does not exist",
+                suggestion=f"Did you mean: {known['methods']}"
+            )
+    return None
+```
+
+### Layer 4: Version-Specific Check
+
+```python
+def check_version_compatibility(package: str, version: str, api: str) -> bool:
+    """
+    Check if API exists in specific package version
+    """
+    # Get package documentation
+    docs = fetch_package_docs(package, version)
+    
+    # Check if API is documented
+    return api in docs.get("exports", [])
+```
+
+---
+
+## 3. Common Hallucination Patterns
+
+### JavaScript/TypeScript
+
+```javascript
+// ❌ HALLUCINATION: fetch.advanced doesn't exist
+const data = await fetch.advanced(url, { retries: 3 });
+
+// ✅ REAL: Use standard fetch with manual retry
+const data = await fetch(url).then(r => r.json());
+```
+
+```javascript
+// ❌ HALLUCINATION: console.print doesn't exist
+console.print("Hello");
+
+// ✅ REAL: Use console.log
+console.log("Hello");
+```
+
+### Python
+
+```python
+# ❌ HALLUCINATION: pandas.smart_read doesn't exist
+df = pd.smart_read("data.csv", auto_detect=True)
+
+# ✅ REAL: Use pandas.read_csv
+df = pd.read_csv("data.csv")
+```
+
+### React
+
+```jsx
+// ❌ HALLUCINATION: useAutoEffect doesn't exist
+useAutoEffect(() => { ... }, [dep], { auto: true });
+
+// ✅ REAL: Use useEffect
+useEffect(() => { ... }, [dep]);
+```
+
+---
+
+## 4. Hallucination Red Flags
+
+| Red Flag | Description |
+|----------|-------------|
+| **Overly Convenient API** | API that does exactly what you need, perfectly |
+| **Missing from Autocomplete** | IDE doesn't recognize it |
+| **No Documentation** | Can't find in official docs |
+| **Unusual Parameter** | Config option that seems too specific |
+| **"Smart" Prefix** | smartFetch, autoProcess, etc. |
+
+---
+
+## 5. Detection Commands
+
+### Quick Check Script
+
+```bash
+#!/bin/bash
+# anti-hallucination-check.sh
+
+echo "=== Package Check ==="
+npm ls --all 2>&1 | grep -E "MISSING|INVALID|ERR"
+
+echo "=== TypeScript Check ==="
+npx tsc --noEmit 2>&1 | grep -E "error TS"
+
+echo "=== Import Check ==="
+grep -rn "from '" src/ | cut -d"'" -f2 | sort -u | while read pkg; do
+  if [[ ! $pkg == .* ]]; then
+    npm view $pkg version > /dev/null 2>&1 || echo "Missing: $pkg"
+  fi
+done
+```
+
+### Python Check
+
+```bash
+#!/bin/bash
+# python-hallucination-check.sh
+
+echo "=== Pyright Check ==="
+pyright --outputjson 2>/dev/null | jq '.generalDiagnostics[] | {file, message}'
+
+echo "=== Package Check ==="
+pip check
+
+echo "=== Import Check ==="
+python -c "import ast; [print(n.name) for n in ast.walk(ast.parse(open('$1').read())) if isinstance(n, ast.Import)]"
+```
+
+---
+
+## 6. Integration Points
+
+### With Verification Gate
+
+```
+AI Output
+    ↓
+Anti-Hallucination Check
+    ↓
+[Pass] → Verification Gate → Completion Claim
+[Fail] → Reject → Request AI Fix
+```
+
+### With Emergence Detector
+
+```
+Anti-Hallucination focuses on: "Is this API real?"
+Emergence Detector focuses on: "Did AI add unwanted things?"
+```
+
+---
+
+## 7. Automated Checks
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Run anti-hallucination check
+./scripts/anti-hallucination-check.sh
+
+if [ $? -ne 0 ]; then
+  echo "❌ Hallucination detected. Fix before commit."
+  exit 1
+fi
+```
+
+### CI Pipeline
+
+```yaml
+- name: Anti-Hallucination Check
+  run: |
+    npm ls --all 2>&1 | grep -qE "MISSING|INVALID" && exit 1
+    npx tsc --noEmit
+```
+
+---
+
+## 8. Response Protocol
+
+| Detection | Severity | Action |
+|-----------|----------|--------|
+| Phantom Package | 🔴 Critical | Reject immediately |
+| Phantom API | 🔴 Critical | Reject, find real API |
+| Wrong Signature | 🟠 High | Fix parameters |
+| Stale Feature | 🟡 Medium | Upgrade or downgrade |
+| Made-up Option | 🟡 Medium | Remove option |
+
+---
+
+## Related Skills
+
+- `emergence-detector` - Detect unexpected behaviors
+- `verification-gate` - Evidence-based verification
+- `trust-spectrum` - Agent trust management