@c0x12c/spartan-ai-toolkit 1.0.1

package/skills/ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/templates/competitor-analysis.md

@@ -0,0 +1,60 @@
+# Competitor Analysis: [Competitor Name]
+
+**URL:**
+**Analyzed:** YYYY-MM-DD
+
+## Overview
+What do they do? Who are they for?
+
+## Pricing
+| Plan | Price | What You Get |
+|------|-------|--------------|
+| Free | $0 | |
+| Pro | $X/mo | |
+| Enterprise | $X/mo | |
+
+## Features
+| Feature | Have it? | Notes |
+|---------|----------|-------|
+| | Yes/No | |
+| | Yes/No | |
+| | Yes/No | |
+
+## What They Do Well
+1.
+2.
+3.
+
+## What They Do Poorly
+1.
+2.
+3.
+
+## User Reviews (G2, Capterra, Reddit, etc.)
+### What users love:
+-
+
+### What users hate:
+-
+
+## Traffic / Traction
+- Monthly visits (SimilarWeb):
+- Social followers:
+- Reviews count:
+- Founded:
+- Funding:
+
+## How They Get Users
+- [ ] SEO
+- [ ] Paid ads
+- [ ] Social media
+- [ ] Referrals
+- [ ] Partnerships
+- [ ] Content marketing
+- [ ] Other: ___
+
+## Positioning
+How do they describe themselves? What's their main message?
+
+## Our Opportunity
+What gap can we fill? How can we be different/better?

package/templates/content/AGENT_TEMPLATE.md

@@ -0,0 +1,47 @@
+---
+name: agent-name
+description: What this agent does. When to use it.
+tools: ["Read", "Grep", "Glob"]
+model: sonnet
+---
+
+You are [identity]. Your job is [mission].
+
+## Your Job
+
+- Thing 1
+- Thing 2
+- Thing 3
+
+## How You Think
+
+[1-2 sentences on experience and approach]
+
+Patterns you watch for:
+- Pattern 1
+- Pattern 2
+- Pattern 3
+
+## Process
+
+1. **Step** - What happens
+2. **Step** - What happens
+3. **Step** - What happens
+
+## Output Format
+
+### Section Name
+- [What goes here]
+
+### Section Name
+- [What goes here]
+
+### Verdict
+[FORMAT]
+[Explanation format]
+
+## Rules
+
+- Rule 1
+- Rule 2
+- Rule 3

package/templates/content/COMMAND_TEMPLATE.md

@@ -0,0 +1,27 @@
+---
+name: spartan:COMMAND-NAME
+description: What this command does in one line
+argument-hint: "[what the user passes]"
+---
+
+# Command Title: {{ args[0] | default: "fallback" }}
+
+One sentence — what this does and when to use it.
+
+## Steps
+
+### Phase Name
+1. First action
+2. Second action
+3. Third action
+
+### Next Phase
+4. Action
+5. Action
+6. Action
+
+## Rules
+
+- Rule 1
+- Rule 2
+- Rule 3

package/templates/content/RULE_TEMPLATE.md

@@ -0,0 +1,40 @@
+# Rule Name
+
+> Full guide: use `/skill-name` skill
+
+## The Rule
+
+State the rule clearly in 1-2 sentences.
+
+### WRONG
+
+```kotlin
+// bad code example
+```
+
+### CORRECT
+
+```kotlin
+// good code example
+```
+
+## Section 2 (if needed)
+
+### WRONG
+
+```kotlin
+// bad code
+```
+
+### CORRECT
+
+```kotlin
+// good code
+```
+
+## Quick Reference
+
+| Situation | Do This | Not This |
+|-----------|---------|----------|
+| Case 1 | Good | Bad |
+| Case 2 | Good | Bad |

package/templates/content/SKILL_TEMPLATE.md

@@ -0,0 +1,41 @@
+---
+name: skill-name
+description: What this skill does. When to use it.
+---
+
+# Skill Name
+
+One sentence — what this turns input into.
+
+## When to Use
+
+- Situation 1
+- Situation 2
+- Situation 3
+
+## Process
+
+### 1. First Step
+What to do. What to ask.
+
+### 2. Second Step
+What to produce.
+
+### 3. Third Step
+What to check.
+
+## Interaction Style
+
+How the skill talks to the user.
+- What it always does
+- What it never does
+
+## Rules
+
+- Rule 1
+- Rule 2
+- Rule 3
+
+## Output
+
+Where to save results. What format.

package/templates/idea-canvas.md

@@ -0,0 +1,47 @@
+# Idea Canvas: [Name]
+
+**Date:** YYYY-MM-DD
+
+## The Problem
+> What's broken? What sucks? What takes too long?
+
+## Who Has This Problem?
+> Be specific. "Everyone" is not an answer.
+
+## How Do They Solve It Now?
+> What workarounds exist? What competitors are there?
+
+## Your Solution (30 seconds)
+> Explain it like you're texting a friend.
+
+## Why You?
+> What do you know that others don't? Any unfair advantages?
+
+## How Big Is This?
+- How many people have this problem?
+- How often do they have it?
+- How much would they pay to fix it?
+
+## Risks
+> What could kill this idea?
+
+1.
+2.
+3.
+
+## First Experiment
+> What's the cheapest way to test if this works?
+
+## Gut Check
+- [ ] I've seen this problem myself
+- [ ] I know at least 3 people with this problem
+- [ ] They've tried to solve it before
+- [ ] I could build v1 in 2 weeks
+- [ ] I'd use this product myself
+
+**Score:** _/5 boxes checked
+
+## Decision
+- [ ] Worth exploring
+- [ ] Kill it
+- [ ] Need more info on: ___________

package/templates/prd-template.md

@@ -0,0 +1,84 @@
+# PRD: [Feature/Product Name]
+
+**Author:**
+**Date:**
+**Status:** Draft / Review / Approved
+
+---
+
+## TL;DR
+What are we building and why? (2-3 sentences max)
+
+## Problem
+What problem does this solve? Include evidence from user research.
+
+## Goals
+What does success look like?
+
+| Goal | Metric | Target |
+|------|--------|--------|
+| | | |
+| | | |
+
+## Non-Goals
+What are we NOT doing?
+
+-
+
+## User Stories
+| As a... | I want to... | So that... |
+|---------|--------------|------------|
+| | | |
+| | | |
+
+## Solution
+
+### Overview
+How does it work? (simple explanation)
+
+### User Flow
+1. User does X
+2. System shows Y
+3. User clicks Z
+4. ...
+
+### Wireframes
+(Link to designs or paste images)
+
+## Technical Notes
+Anything the dev team needs to know?
+
+## Open Questions
+| Question | Answer | Owner |
+|----------|--------|-------|
+| | | |
+
+## Scope
+
+### MVP (Must Have)
+-
+
+### Nice to Have
+-
+
+### Future
+-
+
+## Timeline
+| Milestone | Target Date |
+|-----------|-------------|
+| Design complete | |
+| Dev complete | |
+| Launch | |
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| | | | |
+
+## Success Criteria
+How do we know this worked?
+
+1.
+2.
+3.

package/templates/project-readme.md

@@ -0,0 +1,35 @@
+# [Project Name]
+
+## One-liner
+What is this in one sentence?
+
+## Problem
+What problem are you solving? Who has this problem?
+
+## Solution
+How does your product solve it?
+
+## Status
+- [ ] Brainstorming
+- [ ] Research
+- [ ] Validation
+- [ ] Building
+
+## Key Links
+- [Idea Canvas](./01-brainstorm/idea-canvas.md)
+- [Competitor Research](./02-research/)
+- [User Interviews](./03-validation/)
+- [PRD](./04-build/)
+
+## Quick Stats
+| Metric | Value |
+|--------|-------|
+| Target users | ? |
+| Competitors found | ? |
+| Interviews done | ? |
+| Validation score | ?/10 |
+
+## Next Steps
+1. ...
+2. ...
+3. ...

package/templates/user-interview.md

@@ -0,0 +1,69 @@
+# User Interview
+
+**Person:**
+**Date:**
+**Context:** How do you know them? What do they do?
+
+---
+
+## Rules (Mom Test)
+1. Talk about their life, not your idea
+2. Ask about the past, not the future
+3. Talk less, listen more
+4. Bad news is good news
+5. Never pitch during the interview
+
+---
+
+## Opening
+> "Tell me about the last time you [did the thing you're solving for]"
+
+## Questions
+
+### Understanding the Problem
+1. Walk me through how you currently handle [problem]?
+2. What's the hardest part about [problem]?
+3. Why is that hard?
+4. How often does this happen?
+5. What have you tried to fix it?
+6. What happened?
+
+### Finding Pain
+7. What does it cost you? (time, money, stress)
+8. How do you work around it now?
+9. If you could wave a magic wand, what would change?
+
+### Validating Importance
+10. When was the last time this happened?
+11. What did you do?
+12. Have you looked for solutions?
+13. What did you find?
+14. Why didn't you use them?
+
+---
+
+## Notes
+> Write their actual words, not your interpretation
+
+## Key Quotes
+> Exact quotes that prove pain
+
+## Insights
+> What did you learn?
+
+## Red Flags
+> Anything that suggests they don't really care?
+
+## Follow-ups
+> What should you ask next time?
+
+---
+
+## Score
+| Question | Answer |
+|----------|--------|
+| Real problem? | Yes / Maybe / No |
+| Happens often? | Daily / Weekly / Monthly / Rarely |
+| Currently pays to solve? | Yes ($___) / No |
+| Would pay for solution? | Yes ($___) / Maybe / No |
+| Warm intro potential? | Yes / No |

package/templates/validation-checklist.md

@@ -0,0 +1,108 @@
+# Validation Checklist
+
+**Project:**
+**Date:**
+
+---
+
+## Problem Validation
+
+### Do people have this problem?
+- [ ] Talked to 5+ potential users
+- [ ] Found 3+ people actively trying to solve it
+- [ ] Problem happens at least weekly
+- [ ] Problem costs them real time/money/stress
+
+**Evidence:**
+
+### Is the problem big enough?
+- [ ] Market has 10,000+ potential users
+- [ ] They currently spend money on solutions
+- [ ] Problem is getting worse, not better
+
+**Evidence:**
+
+---
+
+## Solution Validation
+
+### Does your solution make sense?
+- [ ] Explained it to 5 people and they got it in 30 seconds
+- [ ] At least 3 said "I'd use that"
+- [ ] No one said "that already exists" (or you know why yours is different)
+
+**Evidence:**
+
+### Would they pay?
+- [ ] Asked about willingness to pay
+- [ ] Got specific price points
+- [ ] At least 1 person offered to pre-pay or sign up for beta
+
+**Evidence:**
+
+---
+
+## Competition Check
+
+### Can you win?
+- [ ] Analyzed 3+ competitors
+- [ ] Found clear gaps in existing solutions
+- [ ] Your approach is meaningfully different
+- [ ] You have some unfair advantage
+
+**Evidence:**
+
+---
+
+## Build Check
+
+### Can you actually build this?
+- [ ] Scoped MVP to 2-4 weeks of work
+- [ ] Have the skills (or know who does)
+- [ ] No major technical unknowns
+- [ ] Don't need permission from anyone
+
+**Evidence:**
+
+---
+
+## Founder Fit
+
+### Should YOU build this?
+- [ ] You understand the users personally
+- [ ] You'd use this product yourself
+- [ ] You can reach first 10 users without ads
+- [ ] You're excited to work on this for 2+ years
+
+**Evidence:**
+
+---
+
+## Scoring
+
+| Category | Score (1-5) | Notes |
+|----------|-------------|-------|
+| Problem exists | | |
+| Problem is painful | | |
+| Solution makes sense | | |
+| Would pay | | |
+| Can beat competition | | |
+| Can build it | | |
+| Founder fit | | |
+
+**Total:** /35
+
+### Decision Guide
+- 28-35: Strong signal. Build it.
+- 21-27: Promising. Do more validation.
+- 14-20: Weak. Rethink the idea or pivot.
+- Below 14: Kill it. Move on.
+
+---
+
+## Decision
+
+- [ ] Build MVP
+- [ ] More validation needed on: ___________
+- [ ] Pivot to: ___________
+- [ ] Kill and move on