diff --git a/skills/research/architecture_spike.md b/skills/research/architecture_spike.md new file mode 100644 index 00000000..dd5b7775 --- /dev/null +++ b/skills/research/architecture_spike.md @@ -0,0 +1,67 @@ +--- +name: Architecture Spike +type: research +typical_query_count: 2-4 +expected_output_length: 600-1200 words +cascade_tier: groq_preferred +description: > + Investigate how to connect two systems or components. Produces an integration + architecture with sequence diagram, key decisions, and a proof-of-concept outline. +--- + +# Architecture Spike: Connect {system_a} to {system_b} + +## Context + +We need to integrate **{system_a}** with **{system_b}** in the context of +**{project_context}**. This spike answers: what is the best way to wire them +together, and what are the trade-offs? + +## Constraints + +- Prefer approaches that avoid adding new infrastructure dependencies. +- The integration should be **{sync_or_async}** (synchronous / asynchronous). +- Must work within: {environment_constraints}. + +## Research Steps + +1. Identify the APIs / protocols exposed by both systems. +2. List all known integration patterns (direct API, message queue, webhook, SDK, etc.). +3. Evaluate each pattern for complexity, reliability, and latency. +4. Select the recommended approach and outline a proof-of-concept. + +## Output Format + +### Integration Options + +| Pattern | Complexity | Reliability | Latency | Notes | +|---------|-----------|-------------|---------|-------| +| ... | ... | ... | ... | ... | + +### Recommended Approach + +**Pattern:** {pattern_name} + +**Why:** One paragraph explaining the choice. + +### Sequence Diagram + +``` +{system_a} -> {middleware} -> {system_b} +``` + +Describe the data flow step by step: + +1. {system_a} does X... +2. {middleware} transforms / routes... +3. {system_b} receives Y... + +### Proof-of-Concept Outline + +- Files to create or modify +- Key libraries / dependencies needed +- Estimated effort: {effort_estimate} + +### Open Questions + +Bullet list of decisions that need human input before proceeding. diff --git a/skills/research/competitive_scan.md b/skills/research/competitive_scan.md new file mode 100644 index 00000000..6565a43a --- /dev/null +++ b/skills/research/competitive_scan.md @@ -0,0 +1,74 @@ +--- +name: Competitive Scan +type: research +typical_query_count: 3-5 +expected_output_length: 800-1500 words +cascade_tier: groq_preferred +description: > + Compare a project against its alternatives. Produces a feature matrix, + strengths/weaknesses analysis, and positioning summary. +--- + +# Competitive Scan: {project} vs Alternatives + +## Context + +Compare **{project}** against **{alternatives}** (comma-separated list of +competitors). The goal is to understand where {project} stands and identify +differentiation opportunities. + +## Constraints + +- Comparison date: {date}. +- Focus areas: {focus_areas} (e.g., features, pricing, community, performance). +- Perspective: {perspective} (user, developer, business). + +## Research Steps + +1. Gather key facts about {project} (features, pricing, community size, release cadence). +2. Gather the same data for each alternative in {alternatives}. +3. Build a feature comparison matrix. +4. Identify strengths and weaknesses for each entry. +5. Summarize positioning and recommend next steps. + +## Output Format + +### Overview + +One paragraph: what space does {project} compete in, and who are the main players? + +### Feature Matrix + +| Feature / Attribute | {project} | {alt_1} | {alt_2} | {alt_3} | +|--------------------|-----------|---------|---------|---------| +| {feature_1} | ... | ... | ... | ... | +| {feature_2} | ... | ... | ... | ... | +| Pricing | ... | ... | ... | ... | +| License | ... | ... | ... | ... | +| Community Size | ... | ... | ... | ... | +| Last Major Release | ... | ... | ... | ... | + +### Strengths & Weaknesses + +#### {project} +- **Strengths:** ... +- **Weaknesses:** ... + +#### {alt_1} +- **Strengths:** ... +- **Weaknesses:** ... + +_(Repeat for each alternative)_ + +### Positioning Map + +Describe where each project sits along the key dimensions (e.g., simplicity +vs power, free vs paid, niche vs general). + +### Recommendations + +Bullet list of actions based on the competitive landscape: + +- **Differentiate on:** {differentiator} +- **Watch out for:** {threat} +- **Consider adopting from {alt}:** {feature_or_approach} diff --git a/skills/research/game_analysis.md b/skills/research/game_analysis.md new file mode 100644 index 00000000..a492c55a --- /dev/null +++ b/skills/research/game_analysis.md @@ -0,0 +1,68 @@ +--- +name: Game Analysis +type: research +typical_query_count: 2-3 +expected_output_length: 600-1000 words +cascade_tier: local_ok +description: > + Evaluate a game for AI agent playability. Assesses API availability, + observation/action spaces, and existing bot ecosystems. +--- + +# Game Analysis: {game} + +## Context + +Evaluate **{game}** to determine whether an AI agent can play it effectively. +Focus on programmatic access, observation space, action space, and existing +bot/AI ecosystems. + +## Constraints + +- Platform: {platform} (PC, console, mobile, browser). +- Agent type: {agent_type} (reinforcement learning, rule-based, LLM-driven, hybrid). +- Budget for API/licenses: {budget}. + +## Research Steps + +1. Identify official APIs, modding support, or programmatic access methods for {game}. +2. Characterize the observation space (screen pixels, game state JSON, memory reading, etc.). +3. Characterize the action space (keyboard/mouse, API calls, controller inputs). +4. Survey existing bots, AI projects, or research papers for {game}. +5. Assess feasibility and difficulty for the target agent type. + +## Output Format + +### Game Profile + +| Property | Value | +|-------------------|------------------------| +| Game | {game} | +| Genre | {genre} | +| Platform | {platform} | +| API Available | Yes / No / Partial | +| Mod Support | Yes / No / Limited | +| Existing AI Work | Extensive / Some / None| + +### Observation Space + +Describe what data the agent can access and how (API, screen capture, memory hooks, etc.). + +### Action Space + +Describe how the agent can interact with the game (input methods, timing constraints, etc.). + +### Existing Ecosystem + +List known bots, frameworks, research papers, or communities working on AI for {game}. + +### Feasibility Assessment + +- **Difficulty:** Easy / Medium / Hard / Impractical +- **Best approach:** {recommended_agent_type} +- **Key challenges:** Bullet list +- **Estimated time to MVP:** {time_estimate} + +### Recommendation + +One paragraph: should we proceed, and if so, what is the first step? diff --git a/skills/research/integration_guide.md b/skills/research/integration_guide.md new file mode 100644 index 00000000..08134598 --- /dev/null +++ b/skills/research/integration_guide.md @@ -0,0 +1,79 @@ +--- +name: Integration Guide +type: research +typical_query_count: 3-5 +expected_output_length: 1000-2000 words +cascade_tier: groq_preferred +description: > + Step-by-step guide to wire a specific tool into an existing stack, + complete with code samples, configuration, and testing steps. +--- + +# Integration Guide: Wire {tool} into {stack} + +## Context + +Integrate **{tool}** into our **{stack}** stack. The goal is to +**{integration_goal}** (e.g., "add vector search to the dashboard", +"send notifications via Telegram"). + +## Constraints + +- Must follow existing project conventions (see CLAUDE.md). +- No new cloud AI dependencies unless explicitly approved. +- Environment config via `pydantic-settings` / `config.py`. + +## Research Steps + +1. Review {tool}'s official documentation for installation and setup. +2. Identify the minimal dependency set required. +3. Map {tool}'s API to our existing patterns (singletons, graceful degradation). +4. Write integration code with proper error handling. +5. Define configuration variables and their defaults. + +## Output Format + +### Prerequisites + +- Dependencies to install (with versions) +- External services or accounts required +- Environment variables to configure + +### Configuration + +```python +# In config.py — add these fields to Settings: +{config_fields} +``` + +### Implementation + +```python +# {file_path} +{implementation_code} +``` + +### Graceful Degradation + +Describe how the integration behaves when {tool} is unavailable: + +| Scenario | Behavior | Log Level | +|-----------------------|--------------------|-----------| +| {tool} not installed | {fallback} | WARNING | +| {tool} unreachable | {fallback} | WARNING | +| Invalid credentials | {fallback} | ERROR | + +### Testing + +```python +# tests/unit/test_{tool_snake}.py +{test_code} +``` + +### Verification Checklist + +- [ ] Dependency added to pyproject.toml +- [ ] Config fields added with sensible defaults +- [ ] Graceful degradation tested (service down) +- [ ] Unit tests pass (`tox -e unit`) +- [ ] No new linting errors (`tox -e lint`) diff --git a/skills/research/state_of_art.md b/skills/research/state_of_art.md new file mode 100644 index 00000000..bf6fed7b --- /dev/null +++ b/skills/research/state_of_art.md @@ -0,0 +1,67 @@ +--- +name: State of the Art +type: research +typical_query_count: 4-6 +expected_output_length: 1000-2000 words +cascade_tier: groq_preferred +description: > + Comprehensive survey of what currently exists in a given field or domain. + Produces a structured landscape overview with key players, trends, and gaps. +--- + +# State of the Art: {field} (as of {date}) + +## Context + +Survey the current landscape of **{field}**. Identify key players, recent +developments, dominant approaches, and notable gaps. This is a point-in-time +snapshot intended to inform decision-making. + +## Constraints + +- Focus on developments from the last {timeframe} (e.g., 12 months, 2 years). +- Prioritize {priority} (open-source, commercial, academic, or all). +- Target audience: {audience} (technical team, leadership, general). + +## Research Steps + +1. Identify the major categories or sub-domains within {field}. +2. For each category, list the leading projects, companies, or research groups. +3. Note recent milestones, releases, or breakthroughs. +4. Identify emerging trends and directions. +5. Highlight gaps — things that don't exist yet but should. + +## Output Format + +### Executive Summary + +Two to three sentences: what is the state of {field} right now? + +### Landscape Map + +| Category | Key Players | Maturity | Trend | +|---------------|--------------------------|-------------|-------------| +| {category_1} | {player_a}, {player_b} | Early / GA | Growing / Stable / Declining | +| {category_2} | {player_c}, {player_d} | Early / GA | Growing / Stable / Declining | + +### Recent Milestones + +Chronological list of notable events in the last {timeframe}: + +- **{date_1}:** {event_description} +- **{date_2}:** {event_description} + +### Trends + +Numbered list of the top 3-5 trends shaping {field}: + +1. **{trend_name}** — {one-line description} +2. **{trend_name}** — {one-line description} + +### Gaps & Opportunities + +Bullet list of things that are missing, underdeveloped, or ripe for innovation. + +### Implications for Us + +One paragraph: what does this mean for our project? What should we do next? diff --git a/skills/research/tool_evaluation.md b/skills/research/tool_evaluation.md new file mode 100644 index 00000000..aef34726 --- /dev/null +++ b/skills/research/tool_evaluation.md @@ -0,0 +1,52 @@ +--- +name: Tool Evaluation +type: research +typical_query_count: 3-5 +expected_output_length: 800-1500 words +cascade_tier: groq_preferred +description: > + Discover and evaluate all shipping tools/libraries/services in a given domain. + Produces a ranked comparison table with pros, cons, and recommendation. +--- + +# Tool Evaluation: {domain} + +## Context + +You are researching tools, libraries, and services for **{domain}**. +The goal is to find everything that is currently shipping (not vaporware) +and produce a structured comparison. + +## Constraints + +- Only include tools that have public releases or hosted services available today. +- If a tool is in beta/preview, note that clearly. +- Focus on {focus_criteria} when evaluating (e.g., cost, ease of integration, community size). + +## Research Steps + +1. Identify all actively-maintained tools in the **{domain}** space. +2. For each tool, gather: name, URL, license/pricing, last release date, language/platform. +3. Evaluate each tool against the focus criteria. +4. Rank by overall fit for the use case: **{use_case}**. + +## Output Format + +### Summary + +One paragraph: what the landscape looks like and the top recommendation. + +### Comparison Table + +| Tool | License / Price | Last Release | Language | {focus_criteria} Score | Notes | +|------|----------------|--------------|----------|----------------------|-------| +| ... | ... | ... | ... | ... | ... | + +### Top Pick + +- **Recommended:** {tool_name} — {one-line reason} +- **Runner-up:** {tool_name} — {one-line reason} + +### Risks & Gaps + +Bullet list of things to watch out for (missing features, vendor lock-in, etc.).