From 0c777488d3abe83ab6af6246d612c8ff8b74b2e7 Mon Sep 17 00:00:00 2001 From: jason Date: Tue, 24 Mar 2026 00:11:34 -0500 Subject: [PATCH] Initial commit from agent --- .env.example | 20 + .gitignore | 34 + AGENTS.md | 68 ++ DEPLOYMENT-PROFILE.md | 99 ++ JARVIS.md | 71 ++ PROJECT-PROFILE-WORKBOOK.md | 207 ++++ README.md | 47 + ROADMAP.md | 47 + ROUTING-EXAMPLES.md | 84 ++ SKILLS.md | 91 ++ capabilities/__init__.py | 0 capabilities/browser_control.py | 48 + capabilities/calendar_access.py | 61 ++ capabilities/email_access.py | 54 ++ capabilities/file_system.py | 43 + capabilities/git_manager.py | 39 + capabilities/notes_manager.py | 68 ++ capabilities/screen_vision.py | 48 + capabilities/task_manager.py | 56 ++ capabilities/terminal_control.py | 41 + client/jarvis-dashboard.html | 902 ++++++++++++++++++ core/__init__.py | 0 core/claude_agent.py | 234 +++++ core/google_auth.py | 34 + core/voice_input.py | 35 + core/voice_output.py | 27 + core/websocket_manager.py | 24 + hubs/brainstorming.md | 25 + hubs/debugging.md | 27 + hubs/documentation.md | 26 + hubs/marketing.md | 26 + hubs/software-development.md | 44 + hubs/ui-ux.md | 26 + main.py | 70 ++ requirements.txt | 36 + skills/brainstorming/ideation.md | 45 + .../roadmap-opportunity-prioritization.md | 45 + .../brainstorming/structured-brainstorming.md | 45 + skills/debugging/bug-triage.md | 46 + skills/debugging/debugging-workflow.md | 46 + .../incident-response-stabilization.md | 45 + .../architecture-decision-records.md | 45 + skills/documentation/onboarding-docs.md | 45 + skills/documentation/technical-docs.md | 45 + skills/marketing/content-strategy-seo.md | 45 + skills/marketing/marketing-content.md | 45 + skills/marketing/messaging-positioning.md | 45 + skills/marketing/product-copy.md | 45 + skills/software/api-backend.md | 45 + skills/software/architecture-system-design.md | 45 + skills/software/code-review.md | 45 + skills/software/database-migrations.md | 45 + skills/software/dependency-lifecycle.md | 45 + skills/software/feature-implementation.md | 48 + skills/software/frontend-ui-implementation.md | 45 + skills/software/maintenance-technical-debt.md | 45 + skills/software/observability-operability.md | 45 + skills/software/performance-optimization.md | 45 + skills/software/refactoring.md | 45 + skills/software/release-change-summary.md | 45 + skills/software/repo-exploration.md | 44 + skills/software/security-review-hardening.md | 45 + skills/software/test-strategy.md | 45 + skills/ui-ux/accessibility-review.md | 45 + skills/ui-ux/design-system-consistency.md | 45 + skills/ui-ux/ux-review.md | 45 + utils/__init__.py | 0 utils/audio_utils.py | 49 + utils/window_utils.py | 43 + 69 files changed, 4253 insertions(+) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 DEPLOYMENT-PROFILE.md create mode 100644 JARVIS.md create mode 100644 PROJECT-PROFILE-WORKBOOK.md create mode 100644 README.md create mode 100644 ROADMAP.md create mode 100644 ROUTING-EXAMPLES.md create mode 100644 SKILLS.md create mode 100644 capabilities/__init__.py create mode 100644 capabilities/browser_control.py create mode 100644 capabilities/calendar_access.py create mode 100644 capabilities/email_access.py create mode 100644 capabilities/file_system.py create mode 100644 capabilities/git_manager.py create mode 100644 capabilities/notes_manager.py create mode 100644 capabilities/screen_vision.py create mode 100644 capabilities/task_manager.py create mode 100644 capabilities/terminal_control.py create mode 100644 client/jarvis-dashboard.html create mode 100644 core/__init__.py create mode 100644 core/claude_agent.py create mode 100644 core/google_auth.py create mode 100644 core/voice_input.py create mode 100644 core/voice_output.py create mode 100644 core/websocket_manager.py create mode 100644 hubs/brainstorming.md create mode 100644 hubs/debugging.md create mode 100644 hubs/documentation.md create mode 100644 hubs/marketing.md create mode 100644 hubs/software-development.md create mode 100644 hubs/ui-ux.md create mode 100644 main.py create mode 100644 requirements.txt create mode 100644 skills/brainstorming/ideation.md create mode 100644 skills/brainstorming/roadmap-opportunity-prioritization.md create mode 100644 skills/brainstorming/structured-brainstorming.md create mode 100644 skills/debugging/bug-triage.md create mode 100644 skills/debugging/debugging-workflow.md create mode 100644 skills/debugging/incident-response-stabilization.md create mode 100644 skills/documentation/architecture-decision-records.md create mode 100644 skills/documentation/onboarding-docs.md create mode 100644 skills/documentation/technical-docs.md create mode 100644 skills/marketing/content-strategy-seo.md create mode 100644 skills/marketing/marketing-content.md create mode 100644 skills/marketing/messaging-positioning.md create mode 100644 skills/marketing/product-copy.md create mode 100644 skills/software/api-backend.md create mode 100644 skills/software/architecture-system-design.md create mode 100644 skills/software/code-review.md create mode 100644 skills/software/database-migrations.md create mode 100644 skills/software/dependency-lifecycle.md create mode 100644 skills/software/feature-implementation.md create mode 100644 skills/software/frontend-ui-implementation.md create mode 100644 skills/software/maintenance-technical-debt.md create mode 100644 skills/software/observability-operability.md create mode 100644 skills/software/performance-optimization.md create mode 100644 skills/software/refactoring.md create mode 100644 skills/software/release-change-summary.md create mode 100644 skills/software/repo-exploration.md create mode 100644 skills/software/security-review-hardening.md create mode 100644 skills/software/test-strategy.md create mode 100644 skills/ui-ux/accessibility-review.md create mode 100644 skills/ui-ux/design-system-consistency.md create mode 100644 skills/ui-ux/ux-review.md create mode 100644 utils/__init__.py create mode 100644 utils/audio_utils.py create mode 100644 utils/window_utils.py diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..993b53b --- /dev/null +++ b/.env.example @@ -0,0 +1,20 @@ +# ─── Anthropic ───────────────────────────────────── +ANTHROPIC_API_KEY=your_anthropic_api_key_here + +# ─── Fish Audio TTS ───────────────────────────────── +FISH_AUDIO_API_KEY=your_fish_audio_api_key_here +# Optional: specific voice model ID +FISH_AUDIO_VOICE_ID= + +# ─── Whisper ──────────────────────────────────────── +# Options: tiny, base, small, medium, large +WHISPER_MODEL=base + +# ─── Server ───────────────────────────────────────── +HOST=0.0.0.0 +PORT=8000 + +# ─── Google Keep (gkeepapi) ───────────────────────── +# Master token from Android device or Google account +GOOGLE_KEEP_EMAIL= +GOOGLE_KEEP_MASTER_TOKEN= diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8aa3724 --- /dev/null +++ b/.gitignore @@ -0,0 +1,34 @@ +# Google OAuth — NEVER commit +credentials.json +token.json +*.pickle + +# Environment +.env +.venv/ +venv/ +env/ + +# Python +__pycache__/ +*.py[cod] +*.pyo +*.pyd +.Python +*.egg-info/ +dist/ +build/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log +logs/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..11db255 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Agent Operating Guide + +Use this file as the first entrypoint for work in this repository. + +If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) exists and contains filled-in defaults, read it immediately after this file and treat it as the source of preloaded project preferences unless the destination repository provides stronger instructions. + +## Default Behavior + +- Inspect the repository before making assumptions. +- Prefer implementing and verifying work over giving abstract advice unless the user explicitly asks for planning only. +- Read only the skill files needed for the current task. +- Reuse existing project patterns, naming, architecture, and conventions. +- Test or validate changes when feasible, then summarize outcomes and any remaining risks. +- Update or create documentation when the change affects usage, onboarding, behavior, or developer workflow. +- If repository-specific instructions conflict with this suite, follow the repository-specific instructions. + +## How To Load Skills + +1. Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in for this deployment. +2. Read [SKILLS.md](./SKILLS.md). +3. Identify the task category and open the matching hub file. +4. Open only the specialized skill files relevant to the request. +5. Combine skills when the task spans multiple areas. +6. Avoid loading unrelated skills just because they exist. + +## Context Economy Rules + +- Default to reading one hub and two to four specialized skills for a normal task. +- Add more skills only when they materially change the approach, output, or quality bar. +- Prefer depth in the relevant skills over shallow loading across many categories. +- If two skills overlap heavily, choose the one that best matches the main risk or deliverable. +- Re-open the index when the task shifts, but do not reload the entire library reflexively. +- Treat the deployment profile as the early context layer and avoid re-reading it unless the task changes the relevant preference area. + +## Instruction Precedence + +Apply guidance in this order: + +1. Destination repository instructions +2. [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) +3. Generic routing and skill guidance from this suite + +## Routing Table + +| Task type | Start here | +| --- | --- | +| Feature work, refactors, reviews, tests, backend, frontend | [hubs/software-development.md](./hubs/software-development.md) | +| Failing tests, bugs, incident-style analysis, root-cause work | [hubs/debugging.md](./hubs/debugging.md) | +| Technical docs, onboarding, release notes, change communication | [hubs/documentation.md](./hubs/documentation.md) | +| UX evaluation, UI polish, interaction quality, content design | [hubs/ui-ux.md](./hubs/ui-ux.md) | +| Product copy, launch messaging, marketing content | [hubs/marketing.md](./hubs/marketing.md) | +| Ideation, option generation, structured brainstorming | [hubs/brainstorming.md](./hubs/brainstorming.md) | + +## Combination Rules + +- For new features, combine implementation + test strategy + relevant docs. +- For UI work, combine frontend implementation + UX review + product copy when text matters. +- For broken behavior, combine bug triage + debugging workflow + change summary when a fix lands. +- For launch or release tasks, combine technical docs or release notes with messaging or marketing skills as needed. +- For high-risk changes, add security review, observability, or performance optimization as appropriate. +- For long-lived system changes, add architecture and system design, dependency lifecycle, or database migration planning when relevant. + +## Output Expectations + +- Deliver concrete work products, not just observations. +- State key assumptions when the repository does not answer them. +- Call out blockers, tradeoffs, risks, and unverified areas clearly. +- Keep explanations concise and action-oriented. diff --git a/DEPLOYMENT-PROFILE.md b/DEPLOYMENT-PROFILE.md new file mode 100644 index 0000000..9a81284 --- /dev/null +++ b/DEPLOYMENT-PROFILE.md @@ -0,0 +1,99 @@ +# Deployment Profile + +Use this file to stage prefilled defaults before deploying the suite into other repositories. + +This file is the canonical source of preloaded build, tool, environment, workflow, and quality preferences for the deployed bundle. Keep it concise enough to be read early in a session. + +## Precedence + +1. Destination repository instructions +2. This deployment profile +3. Generic `AGENTS.md`, hubs, and skill files + +## How To Maintain This File + +- Fill out [PROJECT-PROFILE-WORKBOOK.md](./PROJECT-PROFILE-WORKBOOK.md) first. +- Rewrite the answers here as agent-facing defaults, not as questions. +- Prefer short, durable defaults over long policy prose. +- Update this file when your preferred build, tool, or workflow defaults change materially. + +## Global Defaults + +- Optimize first for full-stack web application repositories. +- Assume Windows and PowerShell for local development, but keep Docker and Linux deployment realities in mind. +- Prefer compatibility-first tooling and standard stack defaults when multiple valid tools exist. +- Favor Node and TypeScript for application work, while using Python when it is the best fit for tooling or automation. +- Run the most relevant local tests for the changed area by default, and broaden verification for risky changes. +- Ask clarifying questions before meaningful changes when product intent or risk is unclear. +- Update documentation for meaningful changes, especially README content, Unraid install docs, roadmaps, and shipped or release-oriented summaries. +- Hold user-facing work to a high polish bar by default. +- Provide concise change summaries after meaningful work and call out rollout or migration impact when relevant. +- Optimize hardest against regressions and broken behavior. + +## Software Development Defaults + +- Favor modular boundaries and cleaner separation early rather than waiting for severe pain. +- Operate as a full-stack agent by default and work comfortably across frontend and backend. +- Prefer mainstream modern patterns for the stack when multiple valid options exist. +- Assume relational databases first unless the repository clearly indicates otherwise. +- Be careful with schema and migration work, but do not overengineer small changes. +- Prefer small, safe, frequent dependency upgrades with focused validation. +- Treat performance as important early, especially on critical paths. +- Apply a basic secure-defaults baseline: validate input, handle secrets safely, and respect auth boundaries. +- Maintain good operational hygiene with meaningful logs and diagnostics on important paths, and add more for risky systems. +- Use feature work as an opportunity for meaningful surrounding cleanup when the added refactoring clearly improves the change. + +## Debugging Defaults + +- Start with the fastest trustworthy signal rather than forcing a single debugging order. +- Lean on logs and traces heavily before guessing. +- During live or user-impacting incidents, stabilize first and diagnose more deeply after impact is reduced. +- Prefer reversible mitigations such as rollbacks, flags, or partial disablement when risk is high. +- Add regression tests for higher-risk or recurring bugs rather than treating every fix as a mandatory test addition. +- Explain root cause clearly by connecting symptom, cause, and why the fix works. +- Avoid temporary compromises unless there is no safer path. +- Bundle observability improvements with medium or high-risk bug fixes when they would make future diagnosis easier. + +## Documentation Defaults + +- Treat documentation as part of most meaningful implementation work unless it is clearly unnecessary. +- Default to practical onboarding that includes prerequisites, setup steps, validation, and common gotchas. +- Create or update ADRs for major technical decisions and meaningful pattern shifts. +- Write concise, audience-aware change summaries that call out user impact when relevant. +- Maintain strong API and integration documentation by default for meaningful backend or interface work. +- Prefer examples, snippets, and commands in places where they reduce ambiguity and improve adoption. +- Update docs for any meaningful user-facing, setup, or team workflow change. +- Bias toward concise documentation for reference material and more complete guidance for onboarding and operational content. + +## UI/UX Defaults + +- Prefer reuse of existing design-system components and patterns, but allow custom patterns when they clearly improve the experience. +- Do not assume extra accessibility work by default beyond the repository or task requirements unless the task calls for it. +- Design responsively for both desktop and mobile by default. +- Reuse components when they fit well, and create new abstractions when they are likely to matter again. +- Hold interface copy to a highly polished product-copy standard by default. +- Use motion and visual flourish actively enough to make interfaces feel premium. +- Bias toward bold, distinctive UI within reason rather than purely conservative continuity. +- Treat UI work as incomplete until important states, copy quality, polish, and edge cases are addressed. + +## Marketing Defaults + +- Prioritize a mixed audience with a lean toward technical and product-savvy readers. +- Use a premium, distinctive, and persuasive voice. +- Keep marketing claims persuasive but grounded in real features and outcomes. +- Default to a fuller launch kit when marketing work is requested: release notes, launch copy, landing page sections, and social or email variants as appropriate. +- Balance launch messaging with evergreen discoverability, but do not let SEO weaken clarity. +- Favor sharp, polished product copy with strong differentiation and clear calls to action. +- Frame positioning conservatively around real value rather than aggressive comparative claims. +- Prefer clear, action-oriented CTAs without heavy urgency. + +## Brainstorming Defaults + +- Favor breadth first when generating ideas. +- Generate three options by default before recommending one. +- Compare ideas primarily through user value, differentiation, and implementation realism. +- Prioritize roadmap or opportunity choices through strategic fit, user value, and implementation cost. +- Balance innovation with execution realism and require a believable path to implementation. +- Use a short-to-medium horizon with practical sequencing for roadmap framing. +- Turn brainstorming into a scoped implementation plan once a preferred option is selected. +- Do not filter ideas out too early; raise concerns and explore alternatives that may offer more value before narrowing. diff --git a/JARVIS.md b/JARVIS.md new file mode 100644 index 0000000..cd3c19e --- /dev/null +++ b/JARVIS.md @@ -0,0 +1,71 @@ +# JARVIS — Just A Rather Very Intelligent System +**Windows Port | Google Workspace Edition** + +A voice-activated AI assistant powered by FastAPI, Anthropic Claude, Fish Audio TTS, and OpenAI Whisper — integrated with the full Google Workspace suite. + +## Quick Start + +### 1. Prerequisites +- Python 3.11+ +- Google Cloud project with OAuth credentials (`credentials.json`) +- Anthropic API key +- Fish Audio API key + +### 2. Install dependencies +```bash +python -m venv .venv +.venv\Scripts\activate +pip install -r requirements.txt +``` + +### 3. Configure environment +```bash +cp .env.example .env +# Edit .env with your API keys +``` + +### 4. Google OAuth setup +- Place your `credentials.json` from Google Cloud Console in the project root +- On first run, a browser window will open for authorization +- Token is saved to `token.json` automatically + +### 5. Run +```bash +uvicorn main:app --reload --host 0.0.0.0 --port 8000 +``` + +### 6. Open dashboard +Navigate to `http://localhost:8000` in Chrome. + +## Project Structure +``` +jarvis-windows/ +├── main.py # FastAPI entrypoint +├── requirements.txt +├── .env.example +├── .gitignore +├── core/ +│ ├── google_auth.py # Shared Google OAuth handler +│ ├── voice_input.py # Whisper STT +│ ├── voice_output.py # Fish Audio TTS +│ ├── claude_agent.py # Claude API + tool use +│ └── websocket_manager.py # WebSocket connection manager +├── capabilities/ +│ ├── screen_vision.py # mss + win32gui screen capture +│ ├── calendar_access.py # Google Calendar API +│ ├── email_access.py # Gmail API (read-only) +│ ├── notes_manager.py # Google Keep / gkeepapi +│ ├── task_manager.py # Google Tasks API +│ ├── file_system.py # os/pathlib file operations +│ ├── terminal_control.py # subprocess PowerShell/CMD +│ ├── browser_control.py # Selenium Chrome automation +│ └── git_manager.py # Git via subprocess +├── utils/ +│ ├── audio_utils.py # PyAudio helpers +│ └── window_utils.py # win32gui active window +└── client/ + └── jarvis-dashboard.html # Animated Three.js frontend +``` + +## Roadmap +See `ROADMAP.md` diff --git a/PROJECT-PROFILE-WORKBOOK.md b/PROJECT-PROFILE-WORKBOOK.md new file mode 100644 index 0000000..e96c83c --- /dev/null +++ b/PROJECT-PROFILE-WORKBOOK.md @@ -0,0 +1,207 @@ +# Project Profile Workbook + +Fill out this workbook once before deployment when you want the suite to ship with pre-staged defaults for build, tools, environment, workflow, and quality preferences. + +This version has been completed and should act as the human-readable source behind [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md). + +## How To Use This Workbook + +- Keep answers concise and specific. +- Prefer durable defaults over task-specific preferences. +- If a question does not matter for your projects, write `No strong preference`. +- If your answer depends on project type, note the default and the main exception. +- Treat this workbook as the source for pre-deployment staging, not a runtime questionnaire. + +## Global Defaults + +### 1. What repository types should this suite optimize for by default? +Answer: Full-stack web apps. + +### 2. What operating systems, shells, and local environments should the agent assume first? +Answer: Windows and PowerShell for local development. Keep Linux, Docker, and Unraid deployment realities in mind. + +### 3. What package managers, build tools, and task runners should the agent prefer when multiple options exist? +Answer: Compatibility-first defaults and standard stack tooling. + +### 4. Which languages, runtimes, or frameworks should get first-class preference across deployments? +Answer: Node and TypeScript first for application work, with Python acceptable for tooling and automation. + +### 5. What is your default testing philosophy before considering work complete? +Answer: Run the most relevant local tests for the changed area by default, and broaden verification for risky changes. + +### 6. How cautious should the agent be about asking questions versus making reasonable assumptions? +Answer: Ask-first when product intent or change risk is unclear. + +### 7. What documentation should usually be updated when behavior, setup, or workflows change? +Answer: Readmes, Unraid install docs, roadmaps, and shipped summaries are all important and should usually be updated when changes matter. + +### 8. What UX and polish bar should the suite assume for user-facing changes? +Answer: High polish by default. + +### 9. What release, rollout, and communication expectations should be standard? +Answer: Provide a concise change summary by default and note rollout or migration impact when relevant. + +### 10. What kinds of risk should the suite optimize hardest against? +Answer: Regressions and broken behavior. + +## Software Development Defaults + +### 1. What architecture style or system design bias should be the default? +Answer: Favor modular boundaries and cleaner separation early. + +### 2. How should the suite balance frontend, backend, and full-stack execution by default? +Answer: Full-stack by default. + +### 3. Which frameworks, libraries, or implementation patterns should be preferred first? +Answer: Prefer mainstream modern patterns for the stack. + +### 4. What database and persistence assumptions should the agent make? +Answer: Relational database first. + +### 5. How conservative should migration and schema-change work be? +Answer: Be careful, but do not overengineer small schema changes. + +### 6. What dependency upgrade strategy should be assumed? +Answer: Prefer small, safe, frequent upgrades with focused validation. + +### 7. What performance bar should the suite assume by default? +Answer: Be proactive about performance on critical paths. + +### 8. What minimum security baseline should be applied to code changes? +Answer: Basic secure defaults only: validate input, handle secrets safely, and respect auth boundaries. + +### 9. What observability and operability expectations should be normal? +Answer: Good operational hygiene with meaningful logs and diagnostics for important paths. + +### 10. How aggressive should the agent be about refactoring and technical debt reduction while doing feature work? +Answer: Use feature work as an opportunity to improve surrounding structure meaningfully when it helps the change. + +## Debugging Defaults + +### 1. Should debugging start with reproduction first, code inspection first, or whichever is fastest to verify? +Answer: Use whichever path gives the fastest trustworthy signal. + +### 2. What logs, traces, or diagnostics should the agent expect to consult before guessing? +Answer: Lean on logs and traces first. + +### 3. How should the agent behave during live or user-impacting incidents? +Answer: Stabilize first, then diagnose more deeply. + +### 4. What is the preferred rollback, mitigation, or feature-flag strategy when risk is high? +Answer: Prefer reversible mitigations such as flags, rollbacks, or partial disablement. + +### 5. How strongly should the agent try to add or update tests when fixing bugs? +Answer: Add tests for higher-risk or recurring bugs. + +### 6. What level of root-cause explanation should be standard after a fix? +Answer: Clearly explain cause, symptom, and why the fix works. + +### 7. What tradeoffs are acceptable when stabilizing an issue quickly? +Answer: Avoid temporary compromises unless there is no safer path. + +### 8. When should observability improvements be bundled with a bug fix? +Answer: For most medium or high-risk bugs, add enough signal to help next time. + +## Documentation Defaults + +### 1. How strongly should the suite treat documentation as part of normal implementation work? +Answer: Docs are part of most meaningful changes unless clearly unnecessary. + +### 2. What onboarding depth should be the default for new repos or contributor workflows? +Answer: Practical onboarding with prerequisites, setup steps, validation, and common gotchas. + +### 3. When should architecture decision records be created or updated? +Answer: For major decisions and meaningful pattern shifts. + +### 4. What release-note or change-summary style should be standard? +Answer: Concise, audience-aware summaries with user impact called out when relevant. + +### 5. What level of API or integration documentation is expected by default? +Answer: Strong API and integration documentation by default. + +### 6. How much should examples, snippets, or command samples be favored in docs? +Answer: Prefer examples for setup, APIs, and workflows where ambiguity hurts adoption. + +### 7. What documentation updates should be mandatory after behavior or workflow changes? +Answer: Update docs for any meaningful user-facing, setup, or team workflow change. + +### 8. What types of documentation should be concise versus comprehensive? +Answer: Balanced. Keep reference content concise and onboarding or operational content more complete. + +## UI/UX Defaults + +### 1. How strict should design-system adherence be by default? +Answer: Strong preference for reuse, but custom patterns are acceptable when they clearly improve the experience. + +### 2. What accessibility baseline should every user-facing change meet? +Answer: Do not assume extra accessibility work by default unless requested. + +### 3. What responsive behavior should be assumed for new or updated UI? +Answer: Responsive by default for desktop and mobile. + +### 4. How strongly should the agent favor component reuse over local implementation? +Answer: Reuse when it fits well, and create new abstractions only when they are likely to matter again. + +### 5. What clarity and copy standards should be assumed for interface text? +Answer: Highly polished product-copy quality by default. + +### 6. How much motion, animation, or visual flourish is appropriate by default? +Answer: Use motion and flourish actively enough to make the interface feel premium. + +### 7. Should the suite bias toward bold, distinctive UI or conservative continuity with existing patterns? +Answer: Bold and distinctive by default, within reason. + +### 8. How detailed should UI work be before it is considered ready? +Answer: High completeness with strong state coverage, copy quality, polish, and edge-case handling. + +## Marketing Defaults + +### 1. Which audience should marketing and messaging defaults prioritize first? +Answer: Mixed audience, leaning technical and product-savvy. + +### 2. What voice and tone should be the baseline? +Answer: Premium, distinctive, and persuasive. + +### 3. What level of proof, specificity, or technical grounding should marketing claims include? +Answer: Claims should be persuasive but grounded in real features and outcomes. + +### 4. What launch-content formats should be standard by default? +Answer: Broader launch kit: release notes, launch copy, landing page sections, and social or email variants. + +### 5. How important is SEO and evergreen discoverability relative to launch messaging? +Answer: Balance both, but do not let SEO weaken clarity. + +### 6. What product-copy style should be the default? +Answer: Strong product-copy polish with sharper differentiation and CTA energy. + +### 7. How should the suite frame differentiation and positioning? +Answer: Conservative positioning that focuses on real value rather than aggressive comparison. + +### 8. What types of calls to action should be preferred? +Answer: Clear, action-oriented CTAs without heavy urgency. + +## Brainstorming Defaults + +### 1. Should idea generation favor breadth, speed, novelty, practicality, or a specific balance? +Answer: Favor breadth first. + +### 2. How many options should the agent generate by default before recommending one? +Answer: Three options by default. + +### 3. What criteria should be used most often to score or compare ideas? +Answer: User value, differentiation, and implementation realism. + +### 4. What prioritization method should be the default for roadmap or opportunity choices? +Answer: Strategic fit, user value, and implementation cost. + +### 5. How should innovation be balanced against implementation realism? +Answer: Balanced, but require a believable path to execution. + +### 6. What kind of roadmap framing should be standard? +Answer: Short-to-medium horizon with practical sequencing. + +### 7. When should brainstorming output turn into a scoped implementation plan? +Answer: Usually after a preferred option is selected. + +### 8. What types of ideas should usually be filtered out early? +Answer: Do not filter too early. Raise concerns and explore alternatives with more value before narrowing. diff --git a/README.md b/README.md new file mode 100644 index 0000000..2a16f86 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# Drop-In Agent Instruction Suite + +This repository is a portable markdown instruction pack for coding agents. + +Copy these files into another repository to give the agent: +- a root `AGENTS.md` entrypoint, +- a central skill index, +- category hubs for routing, +- specialized skill files for common software, docs, UX, marketing, and ideation tasks. + +## Structure + +- `AGENTS.md` - base instructions and routing rules +- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults +- `INSTALL.md` - copy and customization guide for other repositories +- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults +- `SKILLS.md` - canonical skill index +- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples +- `hubs/` - category-level routing guides +- `skills/` - specialized reusable skill files + +## Design Goals + +- Plain markdown only +- Cross-agent portability +- Implementation-first defaults +- On-demand skill loading instead of loading everything every session +- Context-efficient routing for large skill libraries +- Prefilled deployment defaults without per-install questioning +- Repo-local instructions take precedence over this bundle + +## Intended Workflow + +1. The agent reads `AGENTS.md`. +2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in. +3. The agent checks `SKILLS.md`. +4. The agent opens only the relevant hub and skill files for the task. +5. The agent combines multiple skills when the task spans several domains. + +## Core Categories + +- Software development +- Debugging +- Documentation +- UI/UX +- Marketing +- Brainstorming diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..83602b1 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,47 @@ +# JARVIS Windows — Project Roadmap + +## Phase 1 — Core Stack ✅ (Week 1) +- [ ] FastAPI server with WebSocket endpoint +- [ ] Whisper STT (base model, local) +- [ ] Fish Audio TTS integration +- [ ] Claude API connection +- [ ] WebSocket manager (connect/disconnect/broadcast) +- [ ] Basic end-to-end voice loop (speak → transcribe → Claude → respond) + +## Phase 2 — Google Workspace Integrations (Weeks 2–3) +### 2a — Auth + Core Services +- [ ] Google OAuth 2.0 setup (credentials.json → token.json) +- [ ] Google Calendar: read today's events, upcoming schedule +- [ ] Gmail: unread messages, search by sender/subject +- [ ] Google Tasks: list pending, create, complete + +### 2b — Notes + Screen +- [ ] Google Keep via gkeepapi (or Markdown fallback) +- [ ] Screen vision: mss screenshot + win32gui active window +- [ ] Window list enumeration + +### 2c — System Capabilities +- [ ] Terminal control via subprocess (PowerShell + CMD) +- [ ] File system: create projects, manage folders +- [ ] Git status/operations via subprocess +- [ ] Chrome automation via Selenium + +## Phase 3 — Claude Tool Use (Week 4) +- [ ] Define tools manifest (all capabilities as function specs) +- [ ] Tool dispatch router (route Claude tool_use to capability modules) +- [ ] Multi-turn conversation with tool results +- [ ] Error handling + tool fallbacks + +## Phase 4 — Dashboard + Packaging (Week 5) +- [ ] Wire WebSocket to Three.js dashboard frontend +- [ ] Live transcript display +- [ ] State: idle / listening / processing / speaking +- [ ] Windows startup registration (Task Scheduler) +- [ ] .env validation on startup + +## Phase 5 — Optional Enhancements +- [ ] Docker containerization (for Unraid or headless server) +- [ ] Wake word detection ("Hey JARVIS") +- [ ] Conversation history / memory across sessions +- [ ] Google Drive file access +- [ ] React/Electron desktop wrapper diff --git a/ROUTING-EXAMPLES.md b/ROUTING-EXAMPLES.md new file mode 100644 index 0000000..efe6600 --- /dev/null +++ b/ROUTING-EXAMPLES.md @@ -0,0 +1,84 @@ +# Routing Examples + +Use these examples to validate that the suite routes clearly from `AGENTS.md` to the right hub files and specialized skills. + +In deployments with a filled-in [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md), the agent should read that file after `AGENTS.md` and before opening hubs or skills. + +## Representative Prompts + +### Fix a failing backend test and explain the root cause + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Debugging Hub](./hubs/debugging.md) +- Use [Bug Triage](./skills/debugging/bug-triage.md) +- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md) +- Add [API and Backend Work](./skills/software/api-backend.md) +- Add [Test Strategy](./skills/software/test-strategy.md) + +### Build a new UI settings page with good UX and copy + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Software Development Hub](./hubs/software-development.md) +- Use [Feature Implementation](./skills/software/feature-implementation.md) +- Use [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md) +- Add [UI/UX Hub](./hubs/ui-ux.md) +- Use [UX Review](./skills/ui-ux/ux-review.md) +- Add [Product Copy](./skills/marketing/product-copy.md) + +### Write release notes and update onboarding docs for this feature + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Documentation Hub](./hubs/documentation.md) +- Use [Release and Change Summary](./skills/software/release-change-summary.md) +- Use [Onboarding Documentation](./skills/documentation/onboarding-docs.md) +- Add [Technical Documentation](./skills/documentation/technical-docs.md) if setup or behavior changed + +### Brainstorm three product directions and turn the best one into a scoped implementation plan + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Brainstorming Hub](./hubs/brainstorming.md) +- Use [Ideation](./skills/brainstorming/ideation.md) +- Use [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md) +- Add [Repository Exploration](./skills/software/repo-exploration.md) if the plan must align to an existing codebase +- Add [Feature Implementation](./skills/software/feature-implementation.md) for implementation-ready shaping + +### Review this PR for bugs, regressions, and missing tests + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Software Development Hub](./hubs/software-development.md) +- Use [Code Review](./skills/software/code-review.md) +- Add [Test Strategy](./skills/software/test-strategy.md) + +### Draft launch messaging for a developer tool feature + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Marketing Hub](./hubs/marketing.md) +- Use [Messaging and Positioning](./skills/marketing/messaging-positioning.md) +- Use [Marketing Content](./skills/marketing/marketing-content.md) +- Add [Technical Documentation](./skills/documentation/technical-docs.md) if claims need implementation-grounded detail + +### Plan a risky framework upgrade without derailing feature delivery + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Software Development Hub](./hubs/software-development.md) +- Use [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md) +- Add [Test Strategy](./skills/software/test-strategy.md) +- Add [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md) +- Add [Release and Change Summary](./skills/software/release-change-summary.md) if rollout communication matters + +### Respond to a live production issue and leave the system easier to diagnose next time + +- Start at [AGENTS.md](./AGENTS.md) +- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in +- Open [Debugging Hub](./hubs/debugging.md) +- Use [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md) +- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md) +- Add [Observability and Operability](./skills/software/observability-operability.md) +- Add [Bug Triage](./skills/debugging/bug-triage.md) if reproduction or impact framing is still loose diff --git a/SKILLS.md b/SKILLS.md new file mode 100644 index 0000000..cfc08be --- /dev/null +++ b/SKILLS.md @@ -0,0 +1,91 @@ +# Skill Index + +This file is the canonical registry for the instruction suite. Read this index after `AGENTS.md` and the deployment profile, then open only the hub and skill files needed for the current task. + +## Skill Contract + +Every skill file follows the same structure: +- `Purpose` +- `When to use` +- `Inputs to gather` +- `How to work` +- `Output expectations` +- `Quality checklist` +- `Handoff notes` + +## Loading Guidance + +- If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) is filled in, treat it as the default preference layer before applying generic skill guidance. +- Start narrow: one hub plus the smallest set of specialized skills that covers the task. +- Typical task size: two to four skills. +- Larger, cross-functional tasks may need four to six skills, but only when each one adds a distinct concern. +- Prefer high-leverage skills that shape implementation quality over collecting adjacent but redundant guidance. +- When in doubt, prioritize repository exploration, implementation/debugging, testing, and one domain-specific skill. + +## Category Hubs + +- [Software Development](./hubs/software-development.md) +- [Debugging](./hubs/debugging.md) +- [Documentation](./hubs/documentation.md) +- [UI/UX](./hubs/ui-ux.md) +- [Marketing](./hubs/marketing.md) +- [Brainstorming](./hubs/brainstorming.md) + +## Specialized Skills + +### Software Development + +- [Architecture and System Design](./skills/software/architecture-system-design.md) +- [Feature Implementation](./skills/software/feature-implementation.md) +- [Refactoring](./skills/software/refactoring.md) +- [Code Review](./skills/software/code-review.md) +- [Test Strategy](./skills/software/test-strategy.md) +- [API and Backend Work](./skills/software/api-backend.md) +- [Database Migrations and Data Evolution](./skills/software/database-migrations.md) +- [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md) +- [Performance Optimization](./skills/software/performance-optimization.md) +- [Security Review and Hardening](./skills/software/security-review-hardening.md) +- [Observability and Operability](./skills/software/observability-operability.md) +- [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md) +- [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md) +- [Repository Exploration](./skills/software/repo-exploration.md) +- [Release and Change Summary](./skills/software/release-change-summary.md) + +### Debugging + +- [Bug Triage](./skills/debugging/bug-triage.md) +- [Debugging Workflow](./skills/debugging/debugging-workflow.md) +- [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md) + +### Documentation + +- [Architecture Decision Records](./skills/documentation/architecture-decision-records.md) +- [Technical Documentation](./skills/documentation/technical-docs.md) +- [Onboarding Documentation](./skills/documentation/onboarding-docs.md) + +### UI/UX + +- [UX Review](./skills/ui-ux/ux-review.md) +- [Accessibility Review](./skills/ui-ux/accessibility-review.md) +- [Design System and UI Consistency](./skills/ui-ux/design-system-consistency.md) + +### Marketing + +- [Product Copy](./skills/marketing/product-copy.md) +- [Marketing Content](./skills/marketing/marketing-content.md) +- [Messaging and Positioning](./skills/marketing/messaging-positioning.md) +- [Content Strategy and SEO](./skills/marketing/content-strategy-seo.md) + +### Brainstorming + +- [Ideation](./skills/brainstorming/ideation.md) +- [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md) +- [Roadmap and Opportunity Prioritization](./skills/brainstorming/roadmap-opportunity-prioritization.md) + +## Quick Routing Hints + +- If the task changes code, start with the software development hub. +- If the task starts from a defect, regression, failing test, or unclear breakage, add debugging skills. +- If the task changes how people use, adopt, or understand the product, add documentation and possibly UX or marketing skills. +- If the task asks for options, concepts, or strategic directions before execution, use brainstorming skills. +- If the task affects long-term system health, look for architecture, security, performance, observability, dependency, or maintenance skills before loading more tactical ones. diff --git a/capabilities/__init__.py b/capabilities/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/capabilities/browser_control.py b/capabilities/browser_control.py new file mode 100644 index 0000000..a9f3afc --- /dev/null +++ b/capabilities/browser_control.py @@ -0,0 +1,48 @@ +""" +Chrome browser automation via Selenium. +Selenium 4+ handles ChromeDriver automatically — no manual install needed. +""" +from selenium import webdriver +from selenium.webdriver.chrome.options import Options +from selenium.webdriver.common.by import By +from selenium.webdriver.support.ui import WebDriverWait +from selenium.webdriver.support import expected_conditions as EC +import urllib.parse + +_driver = None + +def _get_driver(headless: bool = False) -> webdriver.Chrome: + global _driver + if _driver is None: + options = Options() + if headless: + options.add_argument("--headless=new") + options.add_argument("--no-sandbox") + options.add_argument("--disable-dev-shm-usage") + _driver = webdriver.Chrome(options=options) + return _driver + +def navigate_to(url: str): + """Navigate Chrome to a URL.""" + driver = _get_driver() + driver.get(url) + return driver.title + +def search_web(query: str): + """Perform a Google search in Chrome.""" + encoded = urllib.parse.quote_plus(query) + return navigate_to(f"https://www.google.com/search?q={encoded}") + +def get_page_title() -> str: + driver = _get_driver() + return driver.title + +def get_page_url() -> str: + driver = _get_driver() + return driver.current_url + +def close_browser(): + global _driver + if _driver: + _driver.quit() + _driver = None diff --git a/capabilities/calendar_access.py b/capabilities/calendar_access.py new file mode 100644 index 0000000..27fa4d2 --- /dev/null +++ b/capabilities/calendar_access.py @@ -0,0 +1,61 @@ +""" +Google Calendar API integration. +Reads today's events and upcoming schedule. +""" +import datetime +from googleapiclient.discovery import build +from core.google_auth import get_credentials + +def _service(): + return build('calendar', 'v3', credentials=get_credentials()) + +def get_todays_events() -> list[dict]: + """Return all events happening today.""" + now = datetime.datetime.now(tz=datetime.timezone.utc) + end = now.replace(hour=23, minute=59, second=59) + result = _service().events().list( + calendarId='primary', + timeMin=now.isoformat(), + timeMax=end.isoformat(), + singleEvents=True, + orderBy='startTime' + ).execute() + return [ + { + 'summary': e.get('summary', '(No title)'), + 'start': e['start'].get('dateTime', e['start'].get('date')), + 'end': e['end'].get('dateTime', e['end'].get('date')), + 'location': e.get('location', ''), + } + for e in result.get('items', []) + ] + +def get_upcoming_events(days: int = 7) -> list[dict]: + """Return events in the next N days.""" + now = datetime.datetime.now(tz=datetime.timezone.utc) + end = now + datetime.timedelta(days=days) + result = _service().events().list( + calendarId='primary', + timeMin=now.isoformat(), + timeMax=end.isoformat(), + maxResults=20, + singleEvents=True, + orderBy='startTime' + ).execute() + return [ + { + 'summary': e.get('summary', '(No title)'), + 'start': e['start'].get('dateTime', e['start'].get('date')), + } + for e in result.get('items', []) + ] + +def create_event(summary: str, start_dt: str, end_dt: str, description: str = "") -> dict: + """Create a new calendar event. Dates in ISO 8601 format.""" + event = { + 'summary': summary, + 'description': description, + 'start': {'dateTime': start_dt, 'timeZone': 'America/Chicago'}, + 'end': {'dateTime': end_dt, 'timeZone': 'America/Chicago'}, + } + return _service().events().insert(calendarId='primary', body=event).execute() diff --git a/capabilities/email_access.py b/capabilities/email_access.py new file mode 100644 index 0000000..e44570f --- /dev/null +++ b/capabilities/email_access.py @@ -0,0 +1,54 @@ +""" +Gmail API integration — read-only access. +Fetches unread messages and supports search queries. +""" +from googleapiclient.discovery import build +from core.google_auth import get_credentials + +def _service(): + return build('gmail', 'v1', credentials=get_credentials()) + +def get_unread_emails(count: int = 10) -> list[dict]: + """Fetch the most recent unread emails.""" + svc = _service() + result = svc.users().messages().list( + userId='me', q='is:unread', maxResults=count + ).execute() + messages = result.get('messages', []) + emails = [] + for msg in messages: + detail = svc.users().messages().get( + userId='me', id=msg['id'], format='metadata', + metadataHeaders=['Subject', 'From', 'Date'] + ).execute() + headers = {h['name']: h['value'] for h in detail['payload']['headers']} + emails.append({ + 'id': msg['id'], + 'subject': headers.get('Subject', '(No subject)'), + 'from': headers.get('From', ''), + 'date': headers.get('Date', ''), + 'snippet': detail.get('snippet', ''), + }) + return emails + +def search_emails(query: str, count: int = 20) -> list[dict]: + """Search Gmail using standard Gmail search syntax.""" + svc = _service() + result = svc.users().messages().list( + userId='me', q=query, maxResults=count + ).execute() + messages = result.get('messages', []) + emails = [] + for msg in messages: + detail = svc.users().messages().get( + userId='me', id=msg['id'], format='metadata', + metadataHeaders=['Subject', 'From', 'Date'] + ).execute() + headers = {h['name']: h['value'] for h in detail['payload']['headers']} + emails.append({ + 'id': msg['id'], + 'subject': headers.get('Subject', '(No subject)'), + 'from': headers.get('From', ''), + 'snippet': detail.get('snippet', ''), + }) + return emails diff --git a/capabilities/file_system.py b/capabilities/file_system.py new file mode 100644 index 0000000..05bef42 --- /dev/null +++ b/capabilities/file_system.py @@ -0,0 +1,43 @@ +""" +File system operations — create projects, manage folders, list files. +Cross-platform: uses pathlib and os only. +""" +import os +import subprocess +from pathlib import Path + +def create_project(name: str, base_path: str = "C:/Projects") -> str: + """Create a new project folder with README and .gitignore.""" + path = Path(base_path) / name + path.mkdir(parents=True, exist_ok=True) + (path / "README.md").write_text(f"# {name}\n\nProject created by JARVIS.\n") + (path / ".gitignore").write_text("__pycache__/\n.env\n*.pyc\n") + return str(path) + +def list_directory(path: str) -> list[dict]: + """List files and folders in a directory.""" + p = Path(path) + if not p.exists(): + return [] + return [ + {'name': item.name, 'type': 'dir' if item.is_dir() else 'file', 'size': item.stat().st_size if item.is_file() else None} + for item in sorted(p.iterdir()) + ] + +def read_file(path: str) -> str: + """Read the contents of a text file.""" + return Path(path).read_text(encoding='utf-8') + +def write_file(path: str, content: str): + """Write content to a file, creating parent directories if needed.""" + p = Path(path) + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(content, encoding='utf-8') + +def delete_file(path: str): + """Delete a file.""" + Path(path).unlink(missing_ok=True) + +def open_folder(path: str): + """Open a folder in Windows Explorer.""" + os.startfile(path) diff --git a/capabilities/git_manager.py b/capabilities/git_manager.py new file mode 100644 index 0000000..2be9ea0 --- /dev/null +++ b/capabilities/git_manager.py @@ -0,0 +1,39 @@ +""" +Git operations via subprocess. +Wraps common git commands for use by JARVIS. +""" +import subprocess +from pathlib import Path + +def _git(path: str, *args) -> dict: + result = subprocess.run( + ["git", *args], cwd=path, capture_output=True, text=True + ) + return { + "stdout": result.stdout.strip(), + "stderr": result.stderr.strip(), + "returncode": result.returncode + } + +def get_git_status(path: str) -> str: + return _git(path, "status")["stdout"] + +def get_git_log(path: str, count: int = 5) -> str: + return _git(path, "log", f"--oneline", f"-{count}")["stdout"] + +def git_diff(path: str) -> str: + return _git(path, "diff")["stdout"] + +def git_pull(path: str) -> dict: + return _git(path, "pull") + +def git_add_commit(path: str, message: str) -> dict: + _git(path, "add", "-A") + return _git(path, "commit", "-m", message) + +def git_push(path: str) -> dict: + return _git(path, "push") + +def list_branches(path: str) -> list[str]: + result = _git(path, "branch", "-a") + return [b.strip().lstrip("* ") for b in result["stdout"].splitlines() if b.strip()] diff --git a/capabilities/notes_manager.py b/capabilities/notes_manager.py new file mode 100644 index 0000000..b926f13 --- /dev/null +++ b/capabilities/notes_manager.py @@ -0,0 +1,68 @@ +""" +Google Keep notes via gkeepapi (unofficial). +Falls back to local Markdown files if Keep is unavailable. + +NOTE: The official Google Keep API requires Google Workspace Enterprise. +For personal/standard accounts use gkeepapi or the Markdown fallback below. +""" +import os +from pathlib import Path + +# ─── gkeepapi backend ────────────────────────── +try: + import gkeepapi + _keep = None + + def _init(): + global _keep + if _keep is None: + email = os.getenv("GOOGLE_KEEP_EMAIL") + token = os.getenv("GOOGLE_KEEP_MASTER_TOKEN") + if not email or not token: + raise ValueError("Set GOOGLE_KEEP_EMAIL and GOOGLE_KEEP_MASTER_TOKEN in .env") + _keep = gkeepapi.Keep() + _keep.authenticate(email, token) + return _keep + + def create_note(title: str, content: str) -> str: + keep = _init() + note = keep.createNote(title, content) + note.pinned = True + keep.sync() + return note.id + + def get_all_notes() -> list[dict]: + keep = _init() + return [{'id': n.id, 'title': n.title, 'text': n.text} for n in keep.all()] + + def search_notes(query: str) -> list[dict]: + keep = _init() + return [{'id': n.id, 'title': n.title, 'text': n.text} for n in keep.find(query=query)] + + NOTES_BACKEND = "gkeepapi" + +except ImportError: + # ─── Markdown fallback ────────────────────── + NOTES_DIR = Path.home() / "JARVIS_Notes" + NOTES_DIR.mkdir(exist_ok=True) + NOTES_BACKEND = "markdown" + + def create_note(title: str, content: str) -> str: + safe_title = "".join(c for c in title if c.isalnum() or c in " _-").strip() + path = NOTES_DIR / f"{safe_title}.md" + path.write_text(f"# {title}\n\n{content}\n") + return str(path) + + def get_all_notes() -> list[dict]: + return [ + {'title': p.stem, 'text': p.read_text()} + for p in NOTES_DIR.glob("*.md") + ] + + def search_notes(query: str) -> list[dict]: + results = [] + for p in NOTES_DIR.glob("*.md"): + text = p.read_text() + if query.lower() in text.lower(): + results.append({'title': p.stem, 'text': text}) + return results diff --git a/capabilities/screen_vision.py b/capabilities/screen_vision.py new file mode 100644 index 0000000..5300edb --- /dev/null +++ b/capabilities/screen_vision.py @@ -0,0 +1,48 @@ +""" +Screen vision — captures screenshots and identifies active/open windows. +Uses mss for fast capture and win32gui for window enumeration. +""" +import mss +import base64 +import io +from PIL import Image + +try: + import win32gui + WIN32_AVAILABLE = True +except ImportError: + WIN32_AVAILABLE = False + print("[JARVIS] pywin32 not available — window detection disabled") + +def get_active_window_title() -> str: + if WIN32_AVAILABLE: + return win32gui.GetWindowText(win32gui.GetForegroundWindow()) + return "Unknown" + +def list_open_windows() -> list[str]: + if not WIN32_AVAILABLE: + return [] + windows = [] + def _enum(hwnd, _): + if win32gui.IsWindowVisible(hwnd): + title = win32gui.GetWindowText(hwnd) + if title: + windows.append(title) + win32gui.EnumWindows(_enum, None) + return windows + +def capture_screen() -> str: + """Returns base64-encoded PNG of the primary monitor.""" + with mss.mss() as sct: + monitor = sct.monitors[1] + img = sct.grab(monitor) + pil_img = Image.frombytes("RGB", img.size, img.bgra, "raw", "BGRX") + buffer = io.BytesIO() + pil_img.save(buffer, format="PNG") + return base64.b64encode(buffer.getvalue()).decode() + +def capture_screen_file(path: str = "screenshot.png") -> str: + """Saves screenshot to file and returns the path.""" + with mss.mss() as sct: + sct.shot(mon=1, output=path) + return path diff --git a/capabilities/task_manager.py b/capabilities/task_manager.py new file mode 100644 index 0000000..226a99c --- /dev/null +++ b/capabilities/task_manager.py @@ -0,0 +1,56 @@ +""" +Google Tasks API integration. +List, create, and complete tasks across all task lists. +""" +from googleapiclient.discovery import build +from core.google_auth import get_credentials + +def _service(): + return build('tasks', 'v1', credentials=get_credentials()) + +def _get_default_list_id() -> str: + svc = _service() + lists = svc.tasklists().list(maxResults=1).execute() + return lists['items'][0]['id'] + +def get_pending_tasks() -> list[dict]: + """Return all incomplete tasks across all task lists.""" + svc = _service() + tasklists = svc.tasklists().list(maxResults=10).execute() + all_tasks = [] + for tl in tasklists.get('items', []): + tasks = svc.tasks().list( + tasklist=tl['id'], showCompleted=False, maxResults=50 + ).execute() + for t in tasks.get('items', []): + all_tasks.append({ + 'id': t['id'], + 'tasklist_id': tl['id'], + 'title': t.get('title', ''), + 'due': t.get('due', ''), + 'notes': t.get('notes', ''), + 'list': tl['title'], + }) + return all_tasks + +def create_task(title: str, notes: str = None, due: str = None) -> dict: + """Create a new task in the default task list.""" + svc = _service() + list_id = _get_default_list_id() + body = {'title': title} + if notes: + body['notes'] = notes + if due: + body['due'] = due + return svc.tasks().insert(tasklist=list_id, body=body).execute() + +def complete_task(tasklist_id: str, task_id: str) -> dict: + """Mark a task as completed.""" + svc = _service() + task = svc.tasks().get(tasklist=tasklist_id, task=task_id).execute() + task['status'] = 'completed' + return svc.tasks().update(tasklist=tasklist_id, task=task_id, body=task).execute() + +def delete_task(tasklist_id: str, task_id: str): + """Delete a task permanently.""" + _service().tasks().delete(tasklist=tasklist_id, task=task_id).execute() diff --git a/capabilities/terminal_control.py b/capabilities/terminal_control.py new file mode 100644 index 0000000..dca8de9 --- /dev/null +++ b/capabilities/terminal_control.py @@ -0,0 +1,41 @@ +""" +Terminal control — runs PowerShell and CMD commands via subprocess. +Opens Windows Terminal at a given path. +""" +import subprocess +import os + +def run_powershell(command: str, timeout: int = 30) -> dict: + """Execute a PowerShell command and return stdout/stderr.""" + result = subprocess.run( + ["powershell", "-ExecutionPolicy", "Bypass", "-NonInteractive", "-Command", command], + capture_output=True, text=True, timeout=timeout + ) + return { + "stdout": result.stdout.strip(), + "stderr": result.stderr.strip(), + "returncode": result.returncode + } + +def run_cmd(command: str, timeout: int = 30) -> dict: + """Execute a CMD command.""" + result = subprocess.run( + ["cmd", "/c", command], + capture_output=True, text=True, timeout=timeout + ) + return { + "stdout": result.stdout.strip(), + "stderr": result.stderr.strip(), + "returncode": result.returncode + } + +def open_terminal(path: str = None): + """Open Windows Terminal at the given directory.""" + cmd = ["wt"] + if path: + cmd += ["-d", path] + subprocess.Popen(cmd) + +def open_vscode(path: str): + """Open VS Code at a given path.""" + subprocess.Popen(["code", path]) diff --git a/client/jarvis-dashboard.html b/client/jarvis-dashboard.html new file mode 100644 index 0000000..8f6365e --- /dev/null +++ b/client/jarvis-dashboard.html @@ -0,0 +1,902 @@ + + + + + +JARVIS + + + + + + + + +
+
+ +
+ +
+ +
+
+
Online
+
+
+
--:--:--
+
---
+
+
+ + +
+ + + + +
+
+
+
STANDBY
+
+
+
+
+
+
+
Tap microphone to speak
+
+ + + +
+ + +
+ +
Say something…
+ +
+
+ + +
+
JARVIS Response
+
+
+ + + + diff --git a/core/__init__.py b/core/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/core/claude_agent.py b/core/claude_agent.py new file mode 100644 index 0000000..8f1dff6 --- /dev/null +++ b/core/claude_agent.py @@ -0,0 +1,234 @@ +""" +Claude API agent with tool use. +All JARVIS capabilities are registered as tools that Claude can invoke. +""" +import os +import json +import anthropic +from capabilities import ( + screen_vision, + calendar_access, + email_access, + notes_manager, + task_manager, + file_system, + terminal_control, + browser_control, + git_manager, +) + +client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY")) + +SYSTEM_PROMPT = """You are JARVIS (Just A Rather Very Intelligent System), a Windows-based AI assistant. +You have access to the following capabilities: screen vision, Google Calendar, Gmail, Google Tasks, +Google Keep notes, file system management, PowerShell terminal, Chrome browser automation, and Git. +Be concise, direct, and helpful. When using tools, always explain what you found.""" + +TOOLS = [ + { + "name": "capture_screen", + "description": "Take a screenshot and identify active windows and open applications", + "input_schema": {"type": "object", "properties": {}, "required": []} + }, + { + "name": "get_calendar_events", + "description": "Get today's events or upcoming events from Google Calendar", + "input_schema": { + "type": "object", + "properties": { + "days_ahead": {"type": "integer", "description": "Number of days ahead to fetch (default 0 = today only)", "default": 0} + }, + "required": [] + } + }, + { + "name": "get_emails", + "description": "Get unread emails from Gmail or search by query", + "input_schema": { + "type": "object", + "properties": { + "query": {"type": "string", "description": "Gmail search query (e.g. 'from:boss@company.com' or 'subject:invoice')"}, + "count": {"type": "integer", "description": "Max number of emails to return", "default": 10} + }, + "required": [] + } + }, + { + "name": "get_tasks", + "description": "Get pending tasks from Google Tasks", + "input_schema": {"type": "object", "properties": {}, "required": []} + }, + { + "name": "create_task", + "description": "Create a new task in Google Tasks", + "input_schema": { + "type": "object", + "properties": { + "title": {"type": "string", "description": "Task title"}, + "notes": {"type": "string", "description": "Optional task notes"}, + "due": {"type": "string", "description": "Optional due date in RFC 3339 format"} + }, + "required": ["title"] + } + }, + { + "name": "create_note", + "description": "Create a note in Google Keep", + "input_schema": { + "type": "object", + "properties": { + "title": {"type": "string", "description": "Note title"}, + "content": {"type": "string", "description": "Note body text"} + }, + "required": ["title", "content"] + } + }, + { + "name": "run_powershell", + "description": "Execute a PowerShell command and return the output", + "input_schema": { + "type": "object", + "properties": { + "command": {"type": "string", "description": "PowerShell command to run"} + }, + "required": ["command"] + } + }, + { + "name": "get_git_status", + "description": "Get git status of a project directory", + "input_schema": { + "type": "object", + "properties": { + "path": {"type": "string", "description": "Absolute path to the git repository"} + }, + "required": ["path"] + } + }, + { + "name": "open_browser", + "description": "Open Chrome and navigate to a URL or perform a Google search", + "input_schema": { + "type": "object", + "properties": { + "url": {"type": "string", "description": "URL to navigate to"}, + "search": {"type": "string", "description": "Search query (alternative to url)"} + }, + "required": [] + } + }, + { + "name": "create_project_folder", + "description": "Create a new project folder with a README", + "input_schema": { + "type": "object", + "properties": { + "name": {"type": "string", "description": "Project name"}, + "base_path": {"type": "string", "description": "Base directory path", "default": "C:/Projects"} + }, + "required": ["name"] + } + } +] + +def _dispatch_tool(name: str, inputs: dict) -> str: + """Route a Claude tool_use call to the appropriate capability module.""" + try: + if name == "capture_screen": + windows = screen_vision.list_open_windows() + active = screen_vision.get_active_window_title() + return json.dumps({"active_window": active, "open_windows": windows[:10]}) + + elif name == "get_calendar_events": + days = inputs.get("days_ahead", 0) + if days == 0: + events = calendar_access.get_todays_events() + else: + events = calendar_access.get_upcoming_events(days=days) + return json.dumps(events) + + elif name == "get_emails": + query = inputs.get("query") + count = inputs.get("count", 10) + if query: + emails = email_access.search_emails(query) + else: + emails = email_access.get_unread_emails(count=count) + return json.dumps(emails) + + elif name == "get_tasks": + return json.dumps(task_manager.get_pending_tasks()) + + elif name == "create_task": + result = task_manager.create_task( + title=inputs["title"], + notes=inputs.get("notes"), + due=inputs.get("due") + ) + return json.dumps({"created": True, "id": result.get("id")}) + + elif name == "create_note": + note_id = notes_manager.create_note(inputs["title"], inputs["content"]) + return json.dumps({"created": True, "id": note_id}) + + elif name == "run_powershell": + result = terminal_control.run_powershell(inputs["command"]) + return json.dumps(result) + + elif name == "get_git_status": + status = git_manager.get_git_status(inputs["path"]) + return json.dumps({"status": status}) + + elif name == "open_browser": + if inputs.get("url"): + browser_control.navigate_to(inputs["url"]) + return json.dumps({"opened": inputs["url"]}) + elif inputs.get("search"): + browser_control.search_web(inputs["search"]) + return json.dumps({"searching": inputs["search"]}) + + elif name == "create_project_folder": + path = file_system.create_project( + inputs["name"], + inputs.get("base_path", "C:/Projects") + ) + return json.dumps({"created": path}) + + return json.dumps({"error": f"Unknown tool: {name}"}) + except Exception as e: + return json.dumps({"error": str(e)}) + +async def get_response(user_text: str) -> str: + """Send user text to Claude with tool use enabled. Returns final text response.""" + messages = [{"role": "user", "content": user_text}] + + while True: + response = client.messages.create( + model="claude-opus-4-5", + max_tokens=1024, + system=SYSTEM_PROMPT, + tools=TOOLS, + messages=messages + ) + + # If Claude wants to use a tool, dispatch and continue + if response.stop_reason == "tool_use": + tool_results = [] + for block in response.content: + if block.type == "tool_use": + result = _dispatch_tool(block.name, block.input) + tool_results.append({ + "type": "tool_result", + "tool_use_id": block.id, + "content": result + }) + + messages.append({"role": "assistant", "content": response.content}) + messages.append({"role": "user", "content": tool_results}) + + else: + # Final text response + for block in response.content: + if hasattr(block, "text"): + return block.text + return "I couldn't generate a response." diff --git a/core/google_auth.py b/core/google_auth.py new file mode 100644 index 0000000..4e77e7a --- /dev/null +++ b/core/google_auth.py @@ -0,0 +1,34 @@ +""" +Shared Google OAuth 2.0 handler. +Covers: Gmail, Google Calendar, Google Tasks, Google Keep. +Place credentials.json (downloaded from Google Cloud Console) in project root. +""" +import os +from google.auth.transport.requests import Request +from google.oauth2.credentials import Credentials +from google_auth_oauthlib.flow import InstalledAppFlow + +SCOPES = [ + 'https://www.googleapis.com/auth/gmail.readonly', + 'https://www.googleapis.com/auth/calendar', + 'https://www.googleapis.com/auth/tasks', + # 'https://www.googleapis.com/auth/keep', # Uncomment if Workspace Enterprise +] + +def get_credentials() -> Credentials: + """ + Returns valid Google OAuth credentials. + Opens browser on first run. Saves/refreshes token.json automatically. + """ + creds = None + if os.path.exists('token.json'): + creds = Credentials.from_authorized_user_file('token.json', SCOPES) + if not creds or not creds.valid: + if creds and creds.expired and creds.refresh_token: + creds.refresh(Request()) + else: + flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES) + creds = flow.run_local_server(port=0) + with open('token.json', 'w') as token: + token.write(creds.to_json()) + return creds diff --git a/core/voice_input.py b/core/voice_input.py new file mode 100644 index 0000000..31e9011 --- /dev/null +++ b/core/voice_input.py @@ -0,0 +1,35 @@ +""" +Voice input — transcribes raw audio bytes using OpenAI Whisper (local). +Model size set via WHISPER_MODEL env var (default: base). +""" +import os +import tempfile +import asyncio +import whisper + +_model = None + +def _get_model(): + global _model + if _model is None: + model_size = os.getenv("WHISPER_MODEL", "base") + print(f"[JARVIS] Loading Whisper model: {model_size}") + _model = whisper.load_model(model_size) + return _model + +async def transcribe_audio(audio_bytes: bytes) -> str: + """Transcribe raw WAV audio bytes to text using Whisper.""" + model = _get_model() + loop = asyncio.get_event_loop() + + def _transcribe(): + with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f: + f.write(audio_bytes) + tmp_path = f.name + try: + result = model.transcribe(tmp_path, fp16=False) + return result["text"].strip() + finally: + os.unlink(tmp_path) + + return await loop.run_in_executor(None, _transcribe) diff --git a/core/voice_output.py b/core/voice_output.py new file mode 100644 index 0000000..234f199 --- /dev/null +++ b/core/voice_output.py @@ -0,0 +1,27 @@ +""" +Voice output — converts text to speech using Fish Audio TTS API. +""" +import os +import asyncio +from fish_audio_sdk import Session, TTSRequest + +async def speak(text: str) -> bytes: + """ + Convert text to speech audio bytes using Fish Audio TTS. + Returns raw audio bytes (MP3). + """ + api_key = os.getenv("FISH_AUDIO_API_KEY") + voice_id = os.getenv("FISH_AUDIO_VOICE_ID", None) + loop = asyncio.get_event_loop() + + def _tts(): + with Session(apikey=api_key) as session: + audio_chunks = [] + for chunk in session.tts(TTSRequest( + text=text, + reference_id=voice_id + )): + audio_chunks.append(chunk) + return b"".join(audio_chunks) + + return await loop.run_in_executor(None, _tts) diff --git a/core/websocket_manager.py b/core/websocket_manager.py new file mode 100644 index 0000000..22ce430 --- /dev/null +++ b/core/websocket_manager.py @@ -0,0 +1,24 @@ +""" +WebSocket connection manager — handles multiple simultaneous clients. +""" +from fastapi import WebSocket +from typing import List + +class ConnectionManager: + def __init__(self): + self.active_connections: List[WebSocket] = [] + + async def connect(self, websocket: WebSocket): + await websocket.accept() + self.active_connections.append(websocket) + + def disconnect(self, websocket: WebSocket): + self.active_connections.remove(websocket) + + async def broadcast_json(self, data: dict): + for connection in self.active_connections: + await connection.send_json(data) + + async def broadcast_bytes(self, data: bytes): + for connection in self.active_connections: + await connection.send_bytes(data) diff --git a/hubs/brainstorming.md b/hubs/brainstorming.md new file mode 100644 index 0000000..cddbd41 --- /dev/null +++ b/hubs/brainstorming.md @@ -0,0 +1,25 @@ +# Brainstorming Hub + +Use this hub when the task is to generate options, explore solution space, compare directions, or turn rough ideas into structured next steps. + +If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains brainstorming defaults, apply those preferences before falling back to the generic routing in this hub. + +## When To Use + +- The user wants concepts, options, or strategic directions +- Requirements are early-stage and need shaping +- A promising idea needs to become a scoped plan +- The team wants alternatives before implementation + +## Skill Routing + +- [Ideation](../skills/brainstorming/ideation.md) for broad option generation and concept creation +- [Structured Brainstorming](../skills/brainstorming/structured-brainstorming.md) for narrowing, comparing, scoring, and turning ideas into action +- [Roadmap and Opportunity Prioritization](../skills/brainstorming/roadmap-opportunity-prioritization.md) for sequencing initiatives, balancing impact versus effort, and choosing what should happen next + +## Common Combinations + +- Product concepting: ideation + messaging/positioning +- Solution design: ideation + structured brainstorming + repository exploration +- From ideas to build plan: structured brainstorming + feature implementation + test strategy +- Long-range planning: roadmap and opportunity prioritization + maintenance and technical debt planning + architecture and system design diff --git a/hubs/debugging.md b/hubs/debugging.md new file mode 100644 index 0000000..06c9922 --- /dev/null +++ b/hubs/debugging.md @@ -0,0 +1,27 @@ +# Debugging Hub + +Use this hub for work that begins with a defect, regression, failing test, production issue, or confusing system behavior. + +If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains debugging defaults, apply those preferences before falling back to the generic routing in this hub. + +## When To Use + +- A test is failing and the cause is unclear +- A user-reported bug needs reproduction and triage +- The system behaves inconsistently across environments or inputs +- A suspected regression needs careful isolation + +## Start With + +- [Bug Triage](../skills/debugging/bug-triage.md) to define the problem, impact, environment, and reproduction path +- [Debugging Workflow](../skills/debugging/debugging-workflow.md) to isolate root cause and verify a fix + +## Combine With + +- [API and Backend Work](../skills/software/api-backend.md) when the issue is server-side or data-related +- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) when the issue is client-side or interaction-related +- [Test Strategy](../skills/software/test-strategy.md) when the fix needs coverage +- [Release and Change Summary](../skills/software/release-change-summary.md) when the resolution should be communicated clearly +- [Incident Response and Stabilization](../skills/debugging/incident-response-stabilization.md) when the issue is live, user-impacting, or needs temporary containment before a full fix +- [Observability and Operability](../skills/software/observability-operability.md) when logs, metrics, traces, or alerting gaps block diagnosis +- [Performance Optimization](../skills/software/performance-optimization.md) when the problem is latency, throughput, memory, or rendering related diff --git a/hubs/documentation.md b/hubs/documentation.md new file mode 100644 index 0000000..557cd06 --- /dev/null +++ b/hubs/documentation.md @@ -0,0 +1,26 @@ +# Documentation Hub + +Use this hub when the task changes how people understand, adopt, operate, or maintain the product. + +If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains documentation defaults, apply those preferences before falling back to the generic routing in this hub. + +## When To Use + +- Write or update technical documentation +- Improve onboarding or contributor guidance +- Create release notes or change summaries +- Align docs with code or product changes + +## Skill Routing + +- [Architecture Decision Records](../skills/documentation/architecture-decision-records.md) for capturing meaningful technical choices, tradeoffs, and why a direction was selected +- [Technical Documentation](../skills/documentation/technical-docs.md) for architecture, APIs, workflows, operational guidance, and usage docs +- [Onboarding Documentation](../skills/documentation/onboarding-docs.md) for setup guides, contributor onboarding, first-run experience, and internal enablement +- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, changelog writing, and rollout explanations + +## Common Combinations + +- New feature: technical docs + release/change summary +- Developer experience improvement: onboarding docs + technical docs +- Product launch: release/change summary + messaging/positioning + marketing content +- Long-lived architecture change: architecture and system design + architecture decision records + technical docs diff --git a/hubs/marketing.md b/hubs/marketing.md new file mode 100644 index 0000000..26472b2 --- /dev/null +++ b/hubs/marketing.md @@ -0,0 +1,26 @@ +# Marketing Hub + +Use this hub for external-facing product language, launch assets, positioning, and persuasive communication. + +If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains marketing defaults, apply those preferences before falling back to the generic routing in this hub. + +## When To Use + +- Draft launch messaging or feature announcements +- Improve website or product marketing copy +- Clarify product differentiation and audience fit +- Create marketing assets tied to engineering or product changes + +## Skill Routing + +- [Product Copy](../skills/marketing/product-copy.md) for UI-adjacent language, concise product text, and conversion-oriented wording +- [Marketing Content](../skills/marketing/marketing-content.md) for launch posts, feature pages, emails, social copy, and content drafts +- [Messaging and Positioning](../skills/marketing/messaging-positioning.md) for audience, value proposition, differentiation, and narrative framing +- [Content Strategy and SEO](../skills/marketing/content-strategy-seo.md) for durable organic content, search intent alignment, and content planning + +## Common Combinations + +- Feature launch: messaging/positioning + marketing content + release/change summary +- Landing page refresh: product copy + messaging/positioning + UX review +- Developer tool announcement: marketing content + technical docs + messaging/positioning +- Evergreen growth work: content strategy and SEO + messaging/positioning + technical docs diff --git a/hubs/software-development.md b/hubs/software-development.md new file mode 100644 index 0000000..da82bea --- /dev/null +++ b/hubs/software-development.md @@ -0,0 +1,44 @@ +# Software Development Hub + +Use this hub for implementation-focused software work: features, refactors, code review, tests, backend changes, frontend changes, and release communication tied to engineering output. + +If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains software defaults, apply those preferences before falling back to the generic routing in this hub. + +## When To Use + +- Build or modify product functionality +- Improve maintainability or architecture +- Review existing code for bugs, regressions, or missing tests +- Plan or add verification coverage +- Explore an unfamiliar codebase before changing it + +## Start With + +- [Repository Exploration](../skills/software/repo-exploration.md) for unfamiliar codebases or vague requests +- [Feature Implementation](../skills/software/feature-implementation.md) for net-new behavior or substantial changes + +## Skill Routing + +- [Architecture and System Design](../skills/software/architecture-system-design.md) for major system changes, design tradeoffs, and long-lived technical direction +- [Refactoring](../skills/software/refactoring.md) for structure improvements without intended behavior changes +- [Code Review](../skills/software/code-review.md) for finding bugs, regressions, risky assumptions, and missing coverage +- [Test Strategy](../skills/software/test-strategy.md) for designing, expanding, or evaluating verification +- [API and Backend Work](../skills/software/api-backend.md) for services, storage, schema, integration, and server-side logic +- [Database Migrations and Data Evolution](../skills/software/database-migrations.md) for schema changes, backfills, compatibility windows, and rollout-safe data transitions +- [Dependency Lifecycle Management](../skills/software/dependency-lifecycle.md) for upgrades, dependency risk reduction, and ecosystem maintenance +- [Performance Optimization](../skills/software/performance-optimization.md) for latency, throughput, rendering, and resource-efficiency work +- [Security Review and Hardening](../skills/software/security-review-hardening.md) for auth, validation, secrets, exposure, and abuse resistance concerns +- [Observability and Operability](../skills/software/observability-operability.md) for logging, metrics, traces, alerts, and operational readiness +- [Maintenance and Technical Debt Planning](../skills/software/maintenance-technical-debt.md) for long-horizon cleanup, risk reduction, and sequencing work +- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for interfaces, interaction logic, and client-side UX execution +- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, summaries, migration notes, and rollout communication + +## Common Combinations + +- New feature: repository exploration + feature implementation + test strategy + technical docs +- Backend bug fix: bug triage + debugging workflow + API and backend work + release/change summary +- UI feature: feature implementation + frontend UI implementation + UX review + product copy +- PR review: code review + test strategy +- Platform change: architecture and system design + API/backend work + observability and operability + technical docs +- Risky upgrade: dependency lifecycle management + test strategy + release/change summary +- Data model change: architecture and system design + database migrations and data evolution + API/backend work diff --git a/hubs/ui-ux.md b/hubs/ui-ux.md new file mode 100644 index 0000000..0117701 --- /dev/null +++ b/hubs/ui-ux.md @@ -0,0 +1,26 @@ +# UI/UX Hub + +Use this hub when the task depends on interface quality, interaction flow, usability, clarity, or user-facing content design. + +If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains UI/UX defaults, apply those preferences before falling back to the generic routing in this hub. + +## When To Use + +- Review a screen, flow, or feature for UX weaknesses +- Improve copy, hierarchy, clarity, or task completion +- Implement or revise UI behavior with usability in mind + +## Skill Routing + +- [UX Review](../skills/ui-ux/ux-review.md) for critique, heuristics, friction detection, and recommendations +- [Accessibility Review](../skills/ui-ux/accessibility-review.md) for inclusive interaction quality, keyboard support, semantics, contrast, and assistive-technology readiness +- [Design System and UI Consistency](../skills/ui-ux/design-system-consistency.md) for component reuse, visual consistency, and scalable UI patterns +- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for shipping the UI changes +- [Product Copy](../skills/marketing/product-copy.md) when labels, empty states, CTAs, or in-product messaging matter + +## Common Combinations + +- New settings page: frontend UI implementation + UX review + product copy +- Navigation cleanup: UX review + frontend UI implementation +- Conversion-focused UI change: UX review + product copy + messaging/positioning +- UI platform work: design system and UI consistency + frontend UI implementation + accessibility review diff --git a/main.py b/main.py new file mode 100644 index 0000000..97f8580 --- /dev/null +++ b/main.py @@ -0,0 +1,70 @@ +""" +JARVIS — main FastAPI entrypoint +""" +import os +from fastapi import FastAPI, WebSocket, WebSocketDisconnect +from fastapi.staticfiles import StaticFiles +from fastapi.responses import FileResponse +from dotenv import load_dotenv + +from core.websocket_manager import ConnectionManager +from core.voice_input import transcribe_audio +from core.claude_agent import get_response +from core.voice_output import speak + +load_dotenv() + +app = FastAPI(title="JARVIS", version="1.0.0") +manager = ConnectionManager() + +# Serve the dashboard frontend +app.mount("/static", StaticFiles(directory="client"), name="static") + +@app.get("/") +async def root(): + return FileResponse("client/jarvis-dashboard.html") + +@app.get("/health") +async def health(): + return {"status": "online", "version": "1.0.0"} + +@app.websocket("/ws/voice") +async def voice_endpoint(websocket: WebSocket): + """ + Main voice WebSocket endpoint. + Client sends raw audio bytes → server transcribes → Claude → TTS → sends audio bytes back. + """ + await manager.connect(websocket) + try: + while True: + # Receive audio chunk from client + audio_chunk = await websocket.receive_bytes() + + # 1. Transcribe with Whisper + await websocket.send_json({"type": "status", "state": "processing"}) + text = await transcribe_audio(audio_chunk) + await websocket.send_json({"type": "transcript", "text": text}) + + # 2. Get Claude response (with tool use) + await websocket.send_json({"type": "status", "state": "thinking"}) + response_text = await get_response(text) + await websocket.send_json({"type": "response", "text": response_text}) + + # 3. Synthesize speech with Fish Audio + await websocket.send_json({"type": "status", "state": "speaking"}) + audio_response = await speak(response_text) + await websocket.send_bytes(audio_response) + + await websocket.send_json({"type": "status", "state": "idle"}) + + except WebSocketDisconnect: + manager.disconnect(websocket) + +if __name__ == "__main__": + import uvicorn + uvicorn.run( + "main:app", + host=os.getenv("HOST", "0.0.0.0"), + port=int(os.getenv("PORT", 8000)), + reload=True + ) diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..ad54691 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,36 @@ +# ─── Core ───────────────────────────────────────── +fastapi +uvicorn[standard] +websockets +python-dotenv + +# ─── AI / Voice ─────────────────────────────────── +anthropic +openai-whisper +SpeechRecognition +pyaudio +# NOTE: On Windows, if pyaudio fails: +# pip install pipwin && pipwin install pyaudio + +# ─── Fish Audio TTS ─────────────────────────────── +fish-audio-sdk + +# ─── Google Workspace ───────────────────────────── +google-api-python-client +google-auth-httplib2 +google-auth-oauthlib +gkeepapi + +# ─── Windows Screen / Automation ───────────────── +mss +pyautogui +Pillow +pywin32 + +# ─── Browser Automation ─────────────────────────── +selenium +# Selenium 4+ auto-downloads ChromeDriver — no manual install needed + +# ─── Utilities ──────────────────────────────────── +aiofiles +httpx diff --git a/skills/brainstorming/ideation.md b/skills/brainstorming/ideation.md new file mode 100644 index 0000000..3bd5dd2 --- /dev/null +++ b/skills/brainstorming/ideation.md @@ -0,0 +1,45 @@ +# Ideation + +## Purpose + +Generate strong options quickly without locking too early onto the first plausible idea. + +## When to use + +- The user wants multiple concepts, approaches, or product directions +- Requirements are early and the solution space is still wide +- A team needs creative alternatives before choosing a path +- You want to escape local maxima in product or technical thinking + +## Inputs to gather + +- Goal, audience, constraints, and success criteria +- What is already known, tried, or ruled out +- Time, complexity, and implementation constraints +- The desired balance of novelty versus practicality + +## How to work + +- Produce several meaningfully different options, not minor variations of one idea. +- Cover a range from safer to bolder approaches when useful. +- Make tradeoffs explicit so ideas are easy to compare. +- Keep ideas concrete enough that someone can imagine implementation or execution. +- Narrow only after the option space is genuinely explored. + +## Output expectations + +- Distinct options with concise descriptions +- Tradeoffs, strengths, and risks for each option +- A recommended direction when appropriate + +## Quality checklist + +- Options are genuinely different in mechanism or strategy. +- Ideas respect the stated constraints. +- Tradeoffs are visible rather than implied. +- Recommendations, if given, follow from the comparison. + +## Handoff notes + +- Note whether the ideas are exploratory, implementation-ready, or need structured narrowing next. +- Pair with structured brainstorming when the next step is selecting and shaping one path. diff --git a/skills/brainstorming/roadmap-opportunity-prioritization.md b/skills/brainstorming/roadmap-opportunity-prioritization.md new file mode 100644 index 0000000..d896a48 --- /dev/null +++ b/skills/brainstorming/roadmap-opportunity-prioritization.md @@ -0,0 +1,45 @@ +# Roadmap and Opportunity Prioritization + +## Purpose + +Choose what to do next by comparing opportunities, maintenance work, and strategic bets against explicit decision criteria. + +## When to use + +- Too many plausible initiatives compete for limited time +- Feature work and maintenance work need to be balanced +- A team needs a more defensible roadmap discussion +- Promising ideas need sequencing rather than more generation + +## Inputs to gather + +- Candidate initiatives or workstreams +- Decision criteria such as impact, urgency, effort, risk reduction, or strategic fit +- Dependencies, timing constraints, and team capacity +- Evidence for expected payoff or avoided risk + +## How to work + +- Make prioritization criteria explicit before ranking work. +- Compare user value, strategic value, and risk reduction together. +- Treat maintenance and enabling work as first-class opportunities when they materially improve future delivery. +- Distinguish what is urgent, what is high leverage, and what is merely attractive. +- Produce a sequence that a team can actually act on. + +## Output expectations + +- Prioritized list or roadmap recommendation +- Clear rationale for order and tradeoffs +- Notes on what to defer, revisit, or validate next + +## Quality checklist + +- Priorities reflect stated criteria rather than intuition alone. +- Sequencing respects dependencies and capacity. +- Lower-priority items are deferred for a reason, not forgotten accidentally. +- Maintenance work is evaluated on outcomes, not optics. + +## Handoff notes + +- Note what new evidence would most change the ranking. +- Pair with maintenance and technical debt planning or structured brainstorming when the decision needs deeper shaping. diff --git a/skills/brainstorming/structured-brainstorming.md b/skills/brainstorming/structured-brainstorming.md new file mode 100644 index 0000000..bd69031 --- /dev/null +++ b/skills/brainstorming/structured-brainstorming.md @@ -0,0 +1,45 @@ +# Structured Brainstorming + +## Purpose + +Turn rough ideas into decision-ready options by comparing them systematically, narrowing intelligently, and shaping the chosen direction into actionable next steps. + +## When to use + +- Many ideas exist and the team needs a clear recommendation +- A promising concept needs scoping before implementation +- Tradeoffs need to be surfaced explicitly +- The next step is choosing, sequencing, or planning rather than generating more ideas + +## Inputs to gather + +- Candidate ideas or possible approaches +- Decision criteria such as impact, effort, risk, speed, or strategic fit +- Constraints on time, team, technical feasibility, or audience needs +- Any assumptions that materially change the choice + +## How to work + +- Define the decision criteria before ranking options. +- Compare options on the criteria that actually matter for the request. +- Remove weak options quickly once the reason is clear. +- Turn the selected direction into a scoped set of next steps or a buildable outline. +- Keep the analysis proportional; do not over-formalize simple decisions. + +## Output expectations + +- Clear comparison of options +- Recommended direction with reasoning +- A scoped next-step plan or action outline + +## Quality checklist + +- Decision criteria are explicit and relevant. +- The recommendation follows from the comparison rather than preference alone. +- The chosen path is actionable, not just inspirational. +- Key assumptions are visible. + +## Handoff notes + +- Note what would most likely change the recommendation. +- Pair with feature implementation, repo exploration, or messaging skills when moving from choice to execution. diff --git a/skills/debugging/bug-triage.md b/skills/debugging/bug-triage.md new file mode 100644 index 0000000..dd38b92 --- /dev/null +++ b/skills/debugging/bug-triage.md @@ -0,0 +1,46 @@ +# Bug Triage + +## Purpose + +Frame a defect clearly before or during debugging so the team understands impact, reproduction, suspected scope, and next actions. + +## When to use + +- A bug report arrives with incomplete detail +- A failing test or regression needs initial framing +- Multiple issues compete for attention and severity matters +- You need a reliable reproduction path before deeper debugging + +## Inputs to gather + +- Reported symptoms, expected behavior, and actual behavior +- Reproduction steps, environment, and frequency +- User impact, severity, and likely affected surfaces +- Recent changes, logs, or tests that may be related + +## How to work + +- Turn vague symptoms into a concrete problem statement. +- Reproduce the issue when possible and tighten the reproduction steps. +- Separate confirmed facts from assumptions. +- Estimate impact and likely blast radius before diving into fixes. +- Identify the next best debugging step if root cause is not yet known. + +## Output expectations + +- Clear bug statement and reproduction status +- Impact and severity assessment +- Suspected scope or likely component area +- Recommended next debugging or fix step + +## Quality checklist + +- The issue is described in observable terms rather than guesses. +- Reproduction details are specific enough to be reused. +- Impact is clear enough to prioritize intelligently. +- Unknowns are named instead of hidden. + +## Handoff notes + +- Record environment details and whether the issue is deterministic, intermittent, or unconfirmed. +- Pair with debugging workflow once the problem is framed well enough to investigate deeply. diff --git a/skills/debugging/debugging-workflow.md b/skills/debugging/debugging-workflow.md new file mode 100644 index 0000000..ac6aba0 --- /dev/null +++ b/skills/debugging/debugging-workflow.md @@ -0,0 +1,46 @@ +# Debugging Workflow + +## Purpose + +Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment. + +## When to use + +- The defect is real but the cause is unclear +- A failing test needs investigation +- The system has inconsistent or environment-specific behavior +- A regression may have multiple plausible causes + +## Inputs to gather + +- Reproduction path or failing signal +- Relevant code paths, logs, traces, state transitions, and recent changes +- Existing tests or ways to validate a hypothesis +- Environment details that may influence behavior + +## How to work + +- Reproduce first when possible, then narrow scope by isolating the smallest failing path. +- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively. +- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration. +- Fix the root cause rather than only masking symptoms when feasible. +- Re-run the original failing signal and add regression protection if appropriate. + +## Output expectations + +- Root cause explanation tied to evidence +- Fix or recommended fix approach +- Verification that the original issue is resolved +- Remaining uncertainty, if any + +## Quality checklist + +- The explanation connects cause to symptom clearly. +- The chosen fix addresses the real failure mechanism. +- Verification includes the original failing path. +- Regression protection is considered when the bug is likely to recur. + +## Handoff notes + +- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause. +- Mention monitoring or follow-up checks if confidence is limited by environment or observability. diff --git a/skills/debugging/incident-response-stabilization.md b/skills/debugging/incident-response-stabilization.md new file mode 100644 index 0000000..34f4c27 --- /dev/null +++ b/skills/debugging/incident-response-stabilization.md @@ -0,0 +1,45 @@ +# Incident Response and Stabilization + +## Purpose + +Guide high-pressure response to live or high-impact issues by separating immediate stabilization from deeper root-cause correction. + +## When to use + +- A production issue is actively impacting users or operators +- A regression needs containment before a complete fix is ready +- The team needs a calm sequence for triage, mitigation, and follow-up +- Communication and operational clarity matter as much as code changes + +## Inputs to gather + +- Current symptoms, severity, affected users, and timing +- Available logs, metrics, alerts, dashboards, and recent changes +- Safe rollback, feature flag, degrade, or traffic-shaping options +- Stakeholders who need updates and what they need to know + +## How to work + +- Stabilize user impact first if a safe containment path exists. +- Keep mitigation, diagnosis, and communication distinct but coordinated. +- Prefer reversible steps under uncertainty. +- Record what is confirmed versus assumed while the incident is active. +- After stabilization, convert the incident into structured debugging and prevention work. + +## Output expectations + +- Stabilization plan or incident response summary +- Clear mitigation status and next actions +- Follow-up work for root cause, observability, and prevention + +## Quality checklist + +- User impact reduction is prioritized appropriately. +- Risky irreversible changes are avoided under pressure. +- Communication is clear enough for collaborators to act. +- Post-incident follow-up is not lost after immediate recovery. + +## Handoff notes + +- Note what was mitigated versus actually fixed. +- Pair with debugging workflow and observability once the system is stable enough for deeper work. diff --git a/skills/documentation/architecture-decision-records.md b/skills/documentation/architecture-decision-records.md new file mode 100644 index 0000000..0f649b7 --- /dev/null +++ b/skills/documentation/architecture-decision-records.md @@ -0,0 +1,45 @@ +# Architecture Decision Records + +## Purpose + +Capture significant technical decisions so future contributors understand what was chosen, why it was chosen, and what tradeoffs were accepted. + +## When to use + +- A meaningful architectural or platform choice has been made +- Multiple alternatives were considered and context would otherwise be lost +- A decision will affect future implementation, migration, or team habits +- You want to prevent repeated re-litigation of the same tradeoff + +## Inputs to gather + +- The decision being made +- Alternatives considered +- Relevant constraints, drivers, and consequences +- Current status: proposed, accepted, superseded, or rejected + +## How to work + +- Record the decision close to when it is made. +- Keep the record concise but concrete enough to survive future context loss. +- Explain why the selected option won, not just what it is. +- Include consequences so future readers understand the cost of the choice. +- Update or supersede older records rather than leaving conflicting guidance unresolved. + +## Output expectations + +- A crisp decision record with context, choice, alternatives, and consequences +- Status that reflects whether the decision is still tentative or settled +- Links to implementation or follow-up docs when useful + +## Quality checklist + +- The decision is clear and specific. +- Alternatives and tradeoffs are visible. +- Future readers can understand the reasoning without redoing the whole discussion. +- The record stays short enough to remain useful. + +## Handoff notes + +- Reference the implementation, technical docs, or migration plan that operationalizes the decision. +- Pair with architecture and system design for major system changes. diff --git a/skills/documentation/onboarding-docs.md b/skills/documentation/onboarding-docs.md new file mode 100644 index 0000000..6a40528 --- /dev/null +++ b/skills/documentation/onboarding-docs.md @@ -0,0 +1,45 @@ +# Onboarding Documentation + +## Purpose + +Help new contributors or users become productive quickly by reducing ambiguity, setup friction, and missing context. + +## When to use + +- Improving setup or first-run guidance +- Writing contributor onboarding docs +- Creating "start here" guides for internal or external users +- Simplifying confusing developer or product entry points + +## Inputs to gather + +- Current setup steps and prerequisites +- Common failure points, hidden assumptions, and missing context +- Existing onboarding flow and repository conventions +- Intended audience: contributor, operator, customer, or teammate + +## How to work + +- Optimize for first success, not exhaustiveness. +- Put prerequisites, setup order, and validation steps in the order a new person needs them. +- Surface gotchas early rather than burying them after failures occur. +- Use concrete commands, examples, and expected outcomes when they reduce confusion. +- Trim insider jargon unless it is explained. + +## Output expectations + +- A cleaner onboarding path with clear first steps +- Documentation that reduces setup ambiguity and dead ends +- Helpful validation or troubleshooting guidance where needed + +## Quality checklist + +- A new person can tell where to start. +- Steps are ordered logically and are easy to verify. +- Prerequisites and common failures are not hidden. +- The doc avoids assuming too much existing context. + +## Handoff notes + +- Note any setup steps you could not verify directly. +- Pair with technical docs when onboarding depends on deeper conceptual explanation. diff --git a/skills/documentation/technical-docs.md b/skills/documentation/technical-docs.md new file mode 100644 index 0000000..02f0870 --- /dev/null +++ b/skills/documentation/technical-docs.md @@ -0,0 +1,45 @@ +# Technical Documentation + +## Purpose + +Create or update documentation that helps developers, operators, or advanced users understand how the system works and how to use it correctly. + +## When to use + +- Updating docs after engineering changes +- Writing usage guides, architecture notes, or operational docs +- Explaining APIs, workflows, configuration, or system behavior +- Improving stale or incomplete technical documentation + +## Inputs to gather + +- The current implementation and the user-visible workflow +- Existing docs, terminology, and structure in the repo +- Intended audience and their technical depth +- Any setup steps, caveats, or common failure points + +## How to work + +- Document the real behavior of the system, not the hoped-for design. +- Prefer task-oriented structure when users need to get something done. +- Use precise terminology that matches the code and UI. +- Include examples, prerequisites, and pitfalls when they materially improve clarity. +- Keep docs aligned with adjacent pages and avoid fragmenting the source of truth. + +## Output expectations + +- Clear, accurate documentation update or new draft +- Audience-appropriate level of technical detail +- Explicit caveats, prerequisites, and compatibility notes when relevant + +## Quality checklist + +- Instructions are accurate against the current implementation. +- The document helps someone complete a real task or understand a real concept. +- Terms and examples are consistent with the product and codebase. +- Important caveats are easy to find. + +## Handoff notes + +- Mention what was verified directly in code versus inferred from context. +- Note any related docs that should be updated later to stay consistent. diff --git a/skills/marketing/content-strategy-seo.md b/skills/marketing/content-strategy-seo.md new file mode 100644 index 0000000..feeba4f --- /dev/null +++ b/skills/marketing/content-strategy-seo.md @@ -0,0 +1,45 @@ +# Content Strategy and SEO + +## Purpose + +Create durable content plans and search-aligned messaging that compound over time instead of only supporting one launch moment. + +## When to use + +- Planning evergreen content around a product area +- Improving discoverability for technical or product topics +- Aligning content to audience intent and search behavior +- Deciding which topics deserve durable written assets + +## Inputs to gather + +- Audience segments and their recurring questions +- Product strengths, proof points, and topic authority +- Existing content library and content gaps +- Desired business outcome: discovery, education, conversion, or retention + +## How to work + +- Start from audience intent and recurring problems, not isolated keywords alone. +- Organize content into durable themes that the product can support credibly. +- Align titles, structure, and calls to action with user intent. +- Avoid search-driven copy that weakens clarity or trust. +- Prefer content that stays useful as the product evolves. + +## Output expectations + +- Content strategy, topic map, or SEO-aware draft direction +- Prioritized content opportunities with rationale +- Notes on how content connects to product positioning and documentation + +## Quality checklist + +- Recommendations reflect real audience needs. +- Content ideas support durable value, not shallow traffic grabs. +- Search alignment does not distort message clarity. +- The strategy can inform multiple future assets. + +## Handoff notes + +- Note which assumptions are based on audience reasoning versus actual search data. +- Pair with messaging/positioning and technical docs for strong, credible long-tail content. diff --git a/skills/marketing/marketing-content.md b/skills/marketing/marketing-content.md new file mode 100644 index 0000000..f255430 --- /dev/null +++ b/skills/marketing/marketing-content.md @@ -0,0 +1,45 @@ +# Marketing Content + +## Purpose + +Create external-facing content that explains, promotes, or launches product capabilities in a way that is accurate, audience-aware, and compelling. + +## When to use + +- Drafting launch posts, emails, feature pages, announcements, or social content +- Turning product or engineering work into outward-facing communication +- Adapting one core message into multiple channels +- Creating content tied to a release or campaign + +## Inputs to gather + +- Audience, channel, and desired action +- The actual product change or offer being communicated +- Supporting proof points, examples, and differentiators +- Voice, tone, and length constraints + +## How to work + +- Lead with why the audience should care. +- Ground claims in the real product and its benefits. +- Structure content so it is easy to scan and repurpose. +- Tailor tone and density to the channel instead of reusing the same draft everywhere. +- Keep technical explanations accurate while translating them into audience-relevant outcomes. + +## Output expectations + +- A polished draft for the requested channel +- Supporting variations or headline options when useful +- Clear call to action where appropriate + +## Quality checklist + +- The content is audience-centered, not feature-dump centered. +- Claims are specific and defensible. +- The narrative is easy to scan and follow. +- The output matches the requested medium and length. + +## Handoff notes + +- State which audience and channel the draft targets. +- Pair with messaging/positioning when the strategic framing is not yet settled. diff --git a/skills/marketing/messaging-positioning.md b/skills/marketing/messaging-positioning.md new file mode 100644 index 0000000..fc1b4b4 --- /dev/null +++ b/skills/marketing/messaging-positioning.md @@ -0,0 +1,45 @@ +# Messaging and Positioning + +## Purpose + +Clarify who the product or feature is for, what value it provides, why it matters now, and how it differs from alternatives. + +## When to use + +- Defining or refining product narrative +- Preparing launches, landing pages, or feature announcements +- Choosing how to frame a new capability for a target audience +- Aligning product, UX, and marketing language around one story + +## Inputs to gather + +- Target audience and their pain points +- Product capability, strengths, and evidence +- Competitive or alternative solutions +- Business goal of the messaging effort + +## How to work + +- Start with audience pain or desired outcome, then connect the product to that need. +- Distinguish core value, supporting proof, and differentiators. +- Avoid vague slogans unless they are backed by a concrete explanation. +- Stress-test the message against realistic alternatives and skeptical readers. +- Produce a tight core narrative that other copy can inherit. + +## Output expectations + +- Clear positioning statement or message framework +- Defined audience, value proposition, and differentiators +- Candidate headlines, pillars, or narrative directions when useful + +## Quality checklist + +- The message is specific about audience and value. +- Differentiation is real, not generic category language. +- Claims are supportable by the product. +- The narrative can guide product copy and campaign content consistently. + +## Handoff notes + +- Note open questions about audience, market, or product maturity if they limit confidence. +- Pair with product copy or marketing content to turn the narrative into shipped assets. diff --git a/skills/marketing/product-copy.md b/skills/marketing/product-copy.md new file mode 100644 index 0000000..5c5c137 --- /dev/null +++ b/skills/marketing/product-copy.md @@ -0,0 +1,45 @@ +# Product Copy + +## Purpose + +Write concise, user-facing product language that is clear, useful, on-brand, and matched to the immediate interface or conversion context. + +## When to use + +- Naming buttons, labels, helper text, empty states, and error messages +- Tightening landing page or feature page copy +- Improving clarity and persuasion in product-adjacent text +- Rewriting awkward or confusing interface wording + +## Inputs to gather + +- Audience, goal, and context of the text +- Current product voice and terminology +- UI constraints such as length, hierarchy, and surrounding elements +- Desired action or decision the copy should support + +## How to work + +- Optimize for clarity first, persuasion second, cleverness last. +- Use the words users expect based on the product and task. +- Match the level of confidence and urgency to the action being requested. +- Keep text tight and scannable, especially in UI contexts. +- Offer alternatives when tone or positioning is uncertain. + +## Output expectations + +- Final copy or strong candidate options +- Brief rationale when choosing between meaningful directions +- Notes on character, tone, or placement constraints when relevant + +## Quality checklist + +- Copy is clear on first read. +- The wording fits the user's moment and intent. +- Claims are credible and specific. +- Text length is appropriate to the surface. + +## Handoff notes + +- Note if final selection depends on brand voice or product strategy not yet defined. +- Pair with UX review for interface clarity and with messaging/positioning for strategic alignment. diff --git a/skills/software/api-backend.md b/skills/software/api-backend.md new file mode 100644 index 0000000..848c48c --- /dev/null +++ b/skills/software/api-backend.md @@ -0,0 +1,45 @@ +# API and Backend Work + +## Purpose + +Guide server-side, service, API, data, and integration changes with attention to contracts, compatibility, failure handling, and operational impact. + +## When to use + +- Modifying endpoints, handlers, services, jobs, or data flows +- Adding or changing schemas, persistence, or integration behavior +- Working on backend business logic or infrastructure-facing code +- Investigating performance, reliability, or contract issues on the server side + +## Inputs to gather + +- API contracts, schema, storage models, and service boundaries +- Existing validation, auth, error handling, and observability patterns +- Compatibility constraints for clients, data, and deployments +- Current tests and representative request or event flows + +## How to work + +- Trace the full request or job lifecycle before changing a boundary. +- Preserve compatibility intentionally or document the break clearly. +- Handle validation, authorization, error responses, and retries in line with existing system behavior. +- Consider migration, rollout, and operational visibility when data or contracts change. +- Add or update tests at the right layer for the change. + +## Output expectations + +- Working backend change with contract implications made explicit +- Notes on schema, config, data, or rollout impact +- Verification results covering the critical paths + +## Quality checklist + +- Inputs and outputs are validated appropriately. +- Failure handling is explicit and consistent. +- Compatibility and migration impact are understood. +- Logging, metrics, or observability concerns are addressed when relevant. + +## Handoff notes + +- Call out any required coordination with frontend, data migration, configuration, or deployment steps. +- Note backwards-incompatible changes clearly and early. diff --git a/skills/software/architecture-system-design.md b/skills/software/architecture-system-design.md new file mode 100644 index 0000000..d8dad30 --- /dev/null +++ b/skills/software/architecture-system-design.md @@ -0,0 +1,45 @@ +# Architecture and System Design + +## Purpose + +Shape meaningful technical direction so systems stay understandable, evolvable, and aligned with product needs over time. + +## When to use + +- Designing a major feature or subsystem +- Changing service boundaries, module boundaries, or core data flow +- Evaluating multiple implementation approaches with long-term consequences +- Preparing work that will influence maintainability, scale, or team velocity + +## Inputs to gather + +- Current architecture, boundaries, and pain points +- Product goals, scale expectations, and reliability constraints +- Existing patterns, platform constraints, and team operating model +- Compatibility, migration, and rollout concerns + +## How to work + +- Start from the user or system outcome, then identify the simplest architecture that supports it well. +- Make tradeoffs explicit: complexity, performance, reliability, maintainability, and delivery speed. +- Preserve useful existing boundaries unless there is a clear reason to change them. +- Prefer designs that are easy to operate and easy for the team to understand. +- Document why the chosen path is better than the main alternatives. + +## Output expectations + +- Clear recommended design or architecture direction +- Explicit tradeoffs and constraints +- Interfaces, boundaries, and rollout considerations that matter for implementation + +## Quality checklist + +- The design solves the actual problem, not a hypothetical future one. +- Tradeoffs are named clearly enough to guide later decisions. +- Complexity is justified by concrete needs. +- Operational and migration consequences are not ignored. + +## Handoff notes + +- Pair with architecture decision records when the choice should be preserved for future contributors. +- Call out which parts are decided versus intentionally deferred. diff --git a/skills/software/code-review.md b/skills/software/code-review.md new file mode 100644 index 0000000..b8cf65e --- /dev/null +++ b/skills/software/code-review.md @@ -0,0 +1,45 @@ +# Code Review + +## Purpose + +Review code with a bug-finding mindset that prioritizes correctness, regressions, risky assumptions, edge cases, and missing tests over style commentary. + +## When to use + +- Reviewing a pull request or patch +- Auditing a risky change before merge +- Evaluating whether a change is safe to ship +- Checking for test and documentation gaps + +## Inputs to gather + +- The diff or changed files +- Nearby code paths and contracts affected by the change +- Existing tests, especially those intended to cover the modified behavior +- Context on expected behavior, rollout risk, and compatibility requirements + +## How to work + +- Start with correctness, then move to regressions, then test gaps, then maintainability risks. +- Trace changed code through call sites, error paths, and data flow rather than reading only the edited lines in isolation. +- Focus comments on issues that materially affect behavior, safety, or maintainability. +- Be explicit about severity and the concrete consequence of each issue. +- Keep summary brief after listing the findings. + +## Output expectations + +- A prioritized list of findings with clear reasoning +- Open questions or assumptions that affect confidence +- Brief summary of overall risk after the findings + +## Quality checklist + +- Findings identify real behavior or verification risk, not cosmetic preferences. +- Severity is proportional to user impact and likelihood. +- Missing tests are called out where they reduce confidence materially. +- If no issues are found, residual risk and coverage gaps are still noted. + +## Handoff notes + +- Include file references and tight line references when available. +- Distinguish confirmed issues from lower-confidence concerns. diff --git a/skills/software/database-migrations.md b/skills/software/database-migrations.md new file mode 100644 index 0000000..02924d7 --- /dev/null +++ b/skills/software/database-migrations.md @@ -0,0 +1,45 @@ +# Database Migrations and Data Evolution + +## Purpose + +Change schemas and data safely while protecting compatibility, correctness, rollout reliability, and recovery options. + +## When to use + +- Adding, removing, or changing database schema +- Backfilling or transforming data +- Introducing compatibility windows between old and new code +- Planning rollout for data-sensitive changes + +## Inputs to gather + +- Current schema, access patterns, and data volume +- Migration tooling and deployment model +- Compatibility requirements across services, jobs, or clients +- Rollback constraints and data recovery options + +## How to work + +- Prefer staged migrations when compatibility matters: expand, backfill, switch reads or writes, then contract. +- Minimize lock risk, data loss risk, and long-running migration risk. +- Consider how old and new code will coexist during rollout. +- Define verification steps for schema state and critical data correctness. +- Document irreversible steps and operator actions clearly. + +## Output expectations + +- Safe migration plan or implementation +- Compatibility and rollout notes +- Verification and rollback considerations + +## Quality checklist + +- The migration is safe for the repository's deployment model. +- Data correctness is protected during and after rollout. +- Backwards and forwards compatibility are considered when needed. +- Irreversible or risky steps are made explicit. + +## Handoff notes + +- Call out sequencing requirements across application code, migrations, and background jobs. +- Pair with release/change summary and technical docs when operators or teammates need a clear rollout path. diff --git a/skills/software/dependency-lifecycle.md b/skills/software/dependency-lifecycle.md new file mode 100644 index 0000000..a7bba5b --- /dev/null +++ b/skills/software/dependency-lifecycle.md @@ -0,0 +1,45 @@ +# Dependency Lifecycle Management + +## Purpose + +Keep dependencies healthy over time by balancing security, compatibility, maintainability, and upgrade cost. + +## When to use + +- Upgrading libraries, frameworks, runtimes, or tooling +- Auditing dependency risk or staleness +- Reducing upgrade backlog and ecosystem drift +- Planning how to adopt breaking changes safely + +## Inputs to gather + +- Current dependency versions and their role in the system +- Changelogs, upgrade guides, and breaking changes +- Existing test coverage and high-risk integration points +- Security, support-window, or maintenance concerns + +## How to work + +- Prefer focused upgrade batches that are easy to validate and revert. +- Separate mechanical version bumps from behavior-changing adaptation when possible. +- Read authoritative release notes before changing usage patterns. +- Verify the highest-risk integration paths, not just installation success. +- Capture follow-up work when a safe incremental upgrade leaves known deprecated patterns behind. + +## Output expectations + +- Upgrade plan or completed upgrade with adaptation notes +- Risk summary for changed dependencies +- Verification results and known remaining debt + +## Quality checklist + +- The upgrade reduces risk or maintenance burden meaningfully. +- Breaking changes are understood before implementation. +- Validation covers the most likely failure surfaces. +- Residual deprecations or postponed steps are documented clearly. + +## Handoff notes + +- Note whether the work is a full upgrade, a safe intermediate step, or a reconnaissance pass. +- Pair with test strategy and release/change summary when adoption affects developer workflow or runtime behavior. diff --git a/skills/software/feature-implementation.md b/skills/software/feature-implementation.md new file mode 100644 index 0000000..9119e01 --- /dev/null +++ b/skills/software/feature-implementation.md @@ -0,0 +1,48 @@ +# Feature Implementation + +## Purpose + +Guide implementation of new behavior or meaningful changes to existing behavior with a bias toward working software, repository alignment, and practical verification. + +## When to use + +- Building a new feature +- Expanding an existing workflow +- Making a multi-file change that affects user or developer behavior +- Turning a scoped request into implemented code + +## Inputs to gather + +- Relevant entrypoints, modules, and surrounding patterns +- Existing interfaces, types, schema, and tests +- User goal, success criteria, constraints, and impacted surfaces +- Any repository instructions that override generic defaults + +## How to work + +- Inspect the codebase before editing and identify the smallest coherent change set. +- Prefer existing patterns over introducing novel structure unless the current patterns are clearly limiting. +- Implement end-to-end behavior, not just partial scaffolding, when feasible. +- Keep logic changes close to the relevant module boundaries and avoid unrelated cleanup unless it materially helps the task. +- Validate with targeted tests, builds, or manual checks appropriate to the repository. +- Update docs, examples, or change notes when the feature alters usage or expectations. + +## Output expectations + +- A working implementation or a clearly explained blocker +- Concise summary of what changed and why +- Validation results and any gaps that remain +- Notes on follow-up work only when it is genuinely important + +## Quality checklist + +- The change matches the stated goal and avoids unrelated churn. +- Naming, structure, and style fit the existing codebase. +- Errors, edge cases, and obvious failure paths are handled. +- Verification is appropriate for the size and risk of the change. +- User-facing or developer-facing behavior changes are documented when needed. + +## Handoff notes + +- Mention touched subsystems and any assumptions made because the repo did not answer them. +- Call out migration or rollout concerns if the feature affects data, config, or compatibility. diff --git a/skills/software/frontend-ui-implementation.md b/skills/software/frontend-ui-implementation.md new file mode 100644 index 0000000..f57e6eb --- /dev/null +++ b/skills/software/frontend-ui-implementation.md @@ -0,0 +1,45 @@ +# Frontend UI Implementation + +## Purpose + +Guide interface implementation that balances correctness, usability, clarity, performance, and consistency with the existing product experience. + +## When to use + +- Building or updating pages, components, and interactions +- Implementing client-side state or view logic +- Adjusting layout, form flows, states, and visual feedback +- Shipping UI changes tied to product behavior + +## Inputs to gather + +- Existing design system, component patterns, and styling conventions +- User flow, content requirements, and responsive constraints +- State, API, and error/loading behavior tied to the UI +- Current tests, stories, screenshots, or acceptance criteria if available + +## How to work + +- Preserve the established visual language unless the task explicitly calls for a new direction. +- Design for the full experience: loading, empty, error, success, and edge states. +- Keep interaction logic understandable and avoid overengineering small UI behavior. +- Use content, hierarchy, and spacing intentionally so the UI communicates clearly. +- Validate on the most important screen sizes or states that the repository can reasonably support. + +## Output expectations + +- A functional UI change that is coherent visually and behaviorally +- Clear notes on user-facing behavior and state handling +- Verification appropriate to the stack, such as tests, stories, or manual checks + +## Quality checklist + +- The UI is understandable without hidden assumptions. +- Important states are handled, not just the happy path. +- Visual and code patterns fit the existing app. +- Accessibility, responsiveness, and copy quality are considered. + +## Handoff notes + +- Mention any UX debts, unresolved visual questions, or browser/device gaps that remain. +- Pair with UX review or product copy when usability or wording is central to the task. diff --git a/skills/software/maintenance-technical-debt.md b/skills/software/maintenance-technical-debt.md new file mode 100644 index 0000000..09c1e18 --- /dev/null +++ b/skills/software/maintenance-technical-debt.md @@ -0,0 +1,45 @@ +# Maintenance and Technical Debt Planning + +## Purpose + +Turn vague maintenance needs into a practical, sequenced plan that improves delivery speed, reliability, and future change safety over time. + +## When to use + +- The codebase has accumulated risky or slowing debt +- A team needs to prioritize cleanup against feature work +- Repeated friction suggests structural maintenance investment is overdue +- You need to explain why maintenance work matters in product terms + +## Inputs to gather + +- Known pain points, repeated failures, and slow areas in delivery +- Architectural hotspots, obsolete patterns, and fragile dependencies +- Team constraints, roadmap pressure, and acceptable disruption +- Evidence of cost: incidents, churn, slowed feature work, or support burden + +## How to work + +- Focus on debt that materially changes future delivery, reliability, or risk. +- Group issues into themes rather than a flat list of annoyances. +- Prioritize by impact, urgency, and dependency relationships. +- Prefer incremental sequences that can ship safely between feature work. +- Translate maintenance value into outcomes the team can defend. + +## Output expectations + +- Prioritized maintenance plan or backlog proposal +- Clear rationale for what should happen now versus later +- Sequencing guidance and expected payoff + +## Quality checklist + +- Recommendations are tied to real delivery or reliability pain. +- Prioritization is explicit and defensible. +- The plan is incremental enough to execute. +- Work is framed in terms of reduced risk or increased velocity, not vague cleanliness. + +## Handoff notes + +- Note what evidence would strengthen or change the prioritization. +- Pair with roadmap and opportunity prioritization when balancing debt against new initiatives. diff --git a/skills/software/observability-operability.md b/skills/software/observability-operability.md new file mode 100644 index 0000000..bde62a9 --- /dev/null +++ b/skills/software/observability-operability.md @@ -0,0 +1,45 @@ +# Observability and Operability + +## Purpose + +Make systems easier to understand, debug, and run by improving signals, diagnostics, and operational readiness around important behavior. + +## When to use + +- A system is hard to diagnose in production or staging +- New functionality needs useful logs, metrics, traces, or alerts +- Operational ownership is unclear during failures or rollout +- Reliability work needs better visibility before deeper changes + +## Inputs to gather + +- Critical workflows, failure modes, and current diagnostic signals +- Existing logging, metrics, tracing, dashboards, and alerts +- Operator needs during rollout, incident response, and debugging +- Noise constraints and performance or cost considerations + +## How to work + +- Instrument the questions a responder will need answered during failure. +- Prefer signals tied to user-impacting behavior over vanity metrics. +- Make logs structured and actionable when possible. +- Add observability close to important boundaries and state transitions. +- Keep signal quality high by avoiding low-value noise. + +## Output expectations + +- Improved observability or an operability plan for the target area +- Clear explanation of what new signals reveal +- Notes on alerting, dashboard, or rollout support when relevant + +## Quality checklist + +- Signals help detect and diagnose meaningful failures. +- Instrumentation is focused and not excessively noisy. +- Operational usage is considered, not just implementation convenience. +- Added visibility maps to critical user or system outcomes. + +## Handoff notes + +- Mention what incidents or debugging tasks the new observability should make easier. +- Pair with debugging workflow, incident response, or performance optimization when diagnosis is the main bottleneck. diff --git a/skills/software/performance-optimization.md b/skills/software/performance-optimization.md new file mode 100644 index 0000000..6e97c1e --- /dev/null +++ b/skills/software/performance-optimization.md @@ -0,0 +1,45 @@ +# Performance Optimization + +## Purpose + +Improve responsiveness and efficiency by focusing on the bottlenecks that matter most to users, systems, or operating cost. + +## When to use + +- Investigating slow pages, endpoints, jobs, or queries +- Reducing memory, CPU, network, or rendering overhead +- Preventing regressions in critical paths +- Prioritizing optimization work with limited time + +## Inputs to gather + +- Performance symptoms, target metrics, and critical user or system paths +- Existing measurements, profiles, logs, traces, or benchmarks +- Current architecture and known hot spots +- Acceptable tradeoffs in complexity, cost, and feature scope + +## How to work + +- Measure or inspect evidence before optimizing. +- Focus on the dominant bottleneck rather than broad cleanup. +- Prefer changes that improve the critical path without making the system harder to maintain. +- Re-measure after changes when possible. +- Capture the conditions under which the optimization matters so future work does not cargo-cult it. + +## Output expectations + +- Bottleneck diagnosis and recommended or implemented improvement +- Before-and-after evidence when available +- Notes on tradeoffs, limits, and remaining hot spots + +## Quality checklist + +- Optimization targets a real bottleneck. +- Claimed gains are grounded in evidence, not assumption alone. +- Complexity added by the optimization is justified. +- Regression risk is considered for correctness and maintainability. + +## Handoff notes + +- Note whether the result is measured, estimated, or hypothesis-driven. +- Pair with observability and operability when instrumentation is weak. diff --git a/skills/software/refactoring.md b/skills/software/refactoring.md new file mode 100644 index 0000000..a049ccf --- /dev/null +++ b/skills/software/refactoring.md @@ -0,0 +1,45 @@ +# Refactoring + +## Purpose + +Improve code structure, readability, maintainability, or modularity without intentionally changing externally observable behavior. + +## When to use + +- Simplifying complex logic +- Extracting clearer abstractions +- Reducing duplication or coupling +- Preparing code for future work while preserving behavior + +## Inputs to gather + +- Current behavior and tests that define expected outcomes +- Structural pain points in the relevant modules +- Constraints around public APIs, compatibility, or performance +- Existing patterns for abstraction and module boundaries + +## How to work + +- Preserve behavior intentionally and define what must remain unchanged before editing. +- Favor small, reviewable moves over sweeping rewrites unless the code is already unsafe to work in incrementally. +- Keep interface changes minimal and justified. +- Add or strengthen tests when behavior preservation is important and current coverage is weak. +- Separate cleanup that supports the refactor from unrelated aesthetic changes. + +## Output expectations + +- Cleaner code with behavior preserved +- Clear explanation of the structural improvement +- Verification evidence that the refactor did not break expected behavior + +## Quality checklist + +- Intended behavior is unchanged unless explicitly documented otherwise. +- The resulting structure is easier to understand or extend. +- Interface changes are minimal, justified, and documented. +- Added complexity is avoided unless it buys meaningful maintainability. + +## Handoff notes + +- Call out any areas where behavior preservation is inferred rather than strongly verified. +- Note future cleanup opportunities only if they naturally follow from the refactor. diff --git a/skills/software/release-change-summary.md b/skills/software/release-change-summary.md new file mode 100644 index 0000000..d9b59e3 --- /dev/null +++ b/skills/software/release-change-summary.md @@ -0,0 +1,45 @@ +# Release and Change Summary + +## Purpose + +Explain shipped or proposed changes clearly for developers, operators, collaborators, or end users, with emphasis on what changed, why it matters, and what action is required. + +## When to use + +- Writing release notes or changelog entries +- Summarizing completed engineering work +- Explaining migration or rollout impact +- Turning technical changes into clear stakeholder communication + +## Inputs to gather + +- The actual code or product changes +- Intended audience and their level of technical depth +- Any rollout, migration, compatibility, or operational considerations +- Linked docs, issues, or feature context that explains why the change exists + +## How to work + +- Lead with the user-meaningful change, not internal implementation trivia. +- Group related changes into a few clear themes rather than a raw diff dump. +- Call out required actions, migrations, or risks explicitly. +- Tailor the level of detail to the audience. +- Keep the summary accurate to the implementation that actually landed. + +## Output expectations + +- Clear release notes, summary, or change communication draft +- Audience-appropriate explanation of impact and required action +- Explicit mention of follow-up items only when relevant + +## Quality checklist + +- The summary matches the real change, not the original intent alone. +- Important caveats, migrations, and compatibility notes are visible. +- Wording is concise and easy to scan. +- Audience knowledge level is respected. + +## Handoff notes + +- Say who the summary is for and what medium it targets if that is not obvious. +- Pair with technical docs or marketing skills when the output needs deeper explanation or stronger positioning. diff --git a/skills/software/repo-exploration.md b/skills/software/repo-exploration.md new file mode 100644 index 0000000..ae45f00 --- /dev/null +++ b/skills/software/repo-exploration.md @@ -0,0 +1,44 @@ +# Repository Exploration + +## Purpose + +Rapidly build accurate context before implementation, debugging, or planning by identifying the right files, flows, conventions, and constraints in the repository. + +## When to use + +- Starting in an unfamiliar repository +- Locating the right implementation area for a request +- Understanding current architecture before proposing changes +- Reducing ambiguity in a vague task + +## Inputs to gather + +- Repository layout, entrypoints, and key modules +- Build, test, and dependency configuration +- Existing patterns for similar features or workflows +- Any local instructions, docs, or conventions already in the repo + +## How to work + +- Start broad, then narrow quickly to the files and flows relevant to the task. +- Favor authoritative sources in the repo such as configs, types, interfaces, docs, and existing implementations. +- Identify where decisions are already made by the codebase so you do not reinvent them. +- Summarize findings in terms of how they affect the next action. +- Stop exploring once the path to execution is clear enough. + +## Output expectations + +- Concise map of the relevant code paths and conventions +- Recommended starting points for changes or further investigation +- Key unknowns that still require validation + +## Quality checklist + +- Exploration answers practical implementation questions rather than producing generic architecture prose. +- Findings are tied to concrete files, modules, or workflows. +- Enough context is gathered to act confidently without over-reading the entire repo. + +## Handoff notes + +- Mention the most relevant files, commands, and repo conventions discovered. +- Flag ambiguous areas where multiple plausible implementation paths exist. diff --git a/skills/software/security-review-hardening.md b/skills/software/security-review-hardening.md new file mode 100644 index 0000000..351973c --- /dev/null +++ b/skills/software/security-review-hardening.md @@ -0,0 +1,45 @@ +# Security Review and Hardening + +## Purpose + +Reduce avoidable security risk by reviewing trust boundaries, sensitive data handling, exposure paths, and abuse opportunities in the relevant system area. + +## When to use + +- Shipping authentication, authorization, input handling, or sensitive workflows +- Reviewing an externally exposed feature or API +- Auditing risky changes for common security failures +- Hardening an existing system area with known gaps + +## Inputs to gather + +- Trust boundaries, user roles, and entry points +- Sensitive data flows, secrets, tokens, or privileged operations +- Existing auth, validation, logging, and rate limiting patterns +- Relevant compliance or threat concerns if known + +## How to work + +- Start with who can do what, from where, and with which inputs. +- Check validation, authorization, data exposure, secret handling, and abuse resistance. +- Prefer concrete mitigations over vague warnings. +- Align with existing security controls unless they are clearly insufficient. +- Call out unverified areas when the environment or tooling limits confidence. + +## Output expectations + +- Concrete risks found or a scoped hardening plan +- Recommended mitigations tied to the actual threat surface +- Clear statement of confidence and any blind spots + +## Quality checklist + +- Review covers the real trust boundaries and attack surface. +- Findings describe exploit consequence, not just theoretical concern. +- Mitigations are practical for the system and team. +- Residual risk is visible where hardening is incomplete. + +## Handoff notes + +- Separate must-fix risks from defense-in-depth improvements. +- Pair with code review, API/backend work, and observability when the issue spans implementation and detection. diff --git a/skills/software/test-strategy.md b/skills/software/test-strategy.md new file mode 100644 index 0000000..8412cf8 --- /dev/null +++ b/skills/software/test-strategy.md @@ -0,0 +1,45 @@ +# Test Strategy + +## Purpose + +Choose and evaluate the right level of verification so changes are covered proportionally to their risk, behavior, and maintenance cost. + +## When to use + +- Adding or updating tests for a feature or bug fix +- Deciding what verification is necessary before shipping +- Auditing coverage gaps in existing code +- Designing regression protection for risky areas + +## Inputs to gather + +- The behavior being changed or protected +- Current test layout, tooling, and conventions +- Known failure modes, regressions, or edge cases +- Constraints on test speed, environment, and confidence needs + +## How to work + +- Match test level to risk: unit for logic, integration for boundaries, end-to-end for critical workflows. +- Prefer the smallest test that meaningfully protects the behavior. +- Cover success paths, likely failure paths, and regressions suggested by the change. +- Reuse existing fixtures and patterns where possible. +- If tests are not feasible, define alternate validation steps and explain the gap. + +## Output expectations + +- Specific recommended or implemented tests +- Clear rationale for test level and scope +- Any remaining uncovered risks or follow-up test ideas + +## Quality checklist + +- Tests target behavior, not implementation trivia. +- Coverage includes the change's highest-risk paths. +- Test design fits repository conventions and runtime cost expectations. +- Non-tested areas are called out explicitly when important. + +## Handoff notes + +- Note flaky, expensive, or environment-dependent checks separately from fast local confidence checks. +- Mention whether the test plan is implemented, recommended, or partially blocked. diff --git a/skills/ui-ux/accessibility-review.md b/skills/ui-ux/accessibility-review.md new file mode 100644 index 0000000..fad7036 --- /dev/null +++ b/skills/ui-ux/accessibility-review.md @@ -0,0 +1,45 @@ +# Accessibility Review + +## Purpose + +Improve inclusive usability by checking whether interfaces are operable, understandable, and robust for people using different devices, input methods, and assistive technologies. + +## When to use + +- Reviewing or implementing user-facing UI +- Checking forms, dialogs, navigation, or interactive states +- Improving keyboard support, semantics, contrast, or feedback +- Raising the quality bar for long-lived interface patterns + +## Inputs to gather + +- Relevant screens, components, and interaction flows +- Existing design system, semantic patterns, and accessibility goals +- Keyboard, screen reader, focus, contrast, and motion considerations +- Known constraints in the stack or component library + +## How to work + +- Check the main user path with keyboard and semantics in mind first. +- Review labels, focus order, state announcements, contrast, and error clarity. +- Prioritize issues that block task completion or create major confusion. +- Recommend changes that fit the current implementation model and team capacity. +- Treat accessibility as product quality, not a final polish pass. + +## Output expectations + +- Clear accessibility findings or implementation guidance +- Prioritized fixes by impact on usability and inclusion +- Notes on what was inspected directly versus inferred + +## Quality checklist + +- Findings focus on real interaction barriers. +- Recommendations are specific enough to implement. +- The review covers both semantics and user experience. +- High-impact accessibility gaps are surfaced early. + +## Handoff notes + +- Mention whether checks were code-based, visual, or manually reasoned. +- Pair with frontend UI implementation and design system consistency when shipping durable fixes. diff --git a/skills/ui-ux/design-system-consistency.md b/skills/ui-ux/design-system-consistency.md new file mode 100644 index 0000000..478f8ca --- /dev/null +++ b/skills/ui-ux/design-system-consistency.md @@ -0,0 +1,45 @@ +# Design System and UI Consistency + +## Purpose + +Promote reusable, scalable UI patterns so the interface stays coherent as the product grows. + +## When to use + +- A UI area is drifting from existing patterns +- Reusable components or patterns should replace one-off implementations +- A feature adds new patterns that may affect future screens +- You want to improve consistency without a full redesign + +## Inputs to gather + +- Existing components, tokens, layout patterns, and style conventions +- The new or changed UI requirements +- Current inconsistencies, duplication, or local hacks +- Constraints from the stack, theme system, or design resources + +## How to work + +- Reuse existing components and conventions before inventing new ones. +- Introduce new patterns only when the current system cannot express the need cleanly. +- Optimize for maintainability and consistency, not just a one-screen outcome. +- Keep component APIs and styling patterns understandable. +- Document new reusable patterns when they materially expand the design system. + +## Output expectations + +- More consistent UI implementation or a clear plan for pattern consolidation +- Notes on reused versus newly introduced patterns +- Guidance on where the system should expand carefully + +## Quality checklist + +- The UI becomes more coherent, not more fragmented. +- Reuse is meaningful and does not force a poor fit. +- New abstractions are justified by repeated or durable need. +- The solution helps future features move faster. + +## Handoff notes + +- Note whether the work is local cleanup, reusable component work, or system-level direction. +- Pair with UX review and frontend implementation when consistency changes affect behavior and clarity. diff --git a/skills/ui-ux/ux-review.md b/skills/ui-ux/ux-review.md new file mode 100644 index 0000000..160231b --- /dev/null +++ b/skills/ui-ux/ux-review.md @@ -0,0 +1,45 @@ +# UX Review + +## Purpose + +Evaluate an interface or flow for clarity, usability, friction, trust, and task completion quality, then turn those observations into actionable improvements. + +## When to use + +- Reviewing a screen or flow before or after implementation +- Looking for usability issues in forms, navigation, settings, or onboarding +- Improving hierarchy, copy clarity, state handling, or feedback +- Assessing whether an interface supports the intended user goal well + +## Inputs to gather + +- Screens, flows, components, or descriptions of the experience +- Target user goal and success criteria +- Existing design system or product patterns +- Constraints such as device, context, accessibility, or content requirements + +## How to work + +- Review from the user's task perspective rather than from the component tree outward. +- Check whether the next action is obvious at each step. +- Evaluate hierarchy, wording, spacing, feedback, and state transitions together. +- Prioritize issues by how much they block comprehension, confidence, or completion. +- Suggest improvements that fit the current product language unless redesign is requested. + +## Output expectations + +- Clear list of UX issues or strengths +- Prioritized recommendations with rationale +- Notes on where UI changes, copy changes, or research would help most + +## Quality checklist + +- Feedback is tied to user outcomes, not vague aesthetic preference. +- Important states such as empty, loading, error, and success are considered. +- Recommendations are specific enough to act on. +- Suggestions fit the product's current level of complexity and style. + +## Handoff notes + +- Distinguish between usability issues, visual polish issues, and copy issues. +- Pair with frontend implementation or product copy when turning review into shipped changes. diff --git a/utils/__init__.py b/utils/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/utils/audio_utils.py b/utils/audio_utils.py new file mode 100644 index 0000000..609b63b --- /dev/null +++ b/utils/audio_utils.py @@ -0,0 +1,49 @@ +""" +Audio utilities — microphone capture helpers using PyAudio. +Captures audio from the default input device and returns WAV bytes. +""" +import io +import wave +import pyaudio + +CHUNK = 1024 +FORMAT = pyaudio.paInt16 +CHANNELS = 1 +RATE = 16000 + +def record_audio(duration: float = 5.0) -> bytes: + """ + Record audio from default microphone for the given duration. + Returns raw WAV bytes compatible with Whisper. + """ + p = pyaudio.PyAudio() + stream = p.open( + format=FORMAT, channels=CHANNELS, + rate=RATE, input=True, frames_per_buffer=CHUNK + ) + frames = [] + for _ in range(int(RATE / CHUNK * duration)): + data = stream.read(CHUNK, exception_on_overflow=False) + frames.append(data) + stream.stop_stream() + stream.close() + p.terminate() + + buf = io.BytesIO() + with wave.open(buf, 'wb') as wf: + wf.setnchannels(CHANNELS) + wf.setsampwidth(p.get_sample_size(FORMAT)) + wf.setframerate(RATE) + wf.writeframes(b''.join(frames)) + return buf.getvalue() + +def list_audio_devices() -> list[dict]: + """List all available audio input devices.""" + p = pyaudio.PyAudio() + devices = [] + for i in range(p.get_device_count()): + info = p.get_device_info_by_index(i) + if info['maxInputChannels'] > 0: + devices.append({'index': i, 'name': info['name']}) + p.terminate() + return devices diff --git a/utils/window_utils.py b/utils/window_utils.py new file mode 100644 index 0000000..fad96c7 --- /dev/null +++ b/utils/window_utils.py @@ -0,0 +1,43 @@ +""" +Windows window utilities using win32gui. +Enumerate and manage application windows. +""" +try: + import win32gui + import win32con + + def get_active_window() -> dict: + hwnd = win32gui.GetForegroundWindow() + return { + 'hwnd': hwnd, + 'title': win32gui.GetWindowText(hwnd) + } + + def list_windows() -> list[dict]: + windows = [] + def _enum(hwnd, _): + if win32gui.IsWindowVisible(hwnd): + title = win32gui.GetWindowText(hwnd) + if title: + windows.append({'hwnd': hwnd, 'title': title}) + win32gui.EnumWindows(_enum, None) + return windows + + def focus_window(title_substring: str) -> bool: + """Bring a window to foreground by partial title match.""" + def _enum(hwnd, _): + if title_substring.lower() in win32gui.GetWindowText(hwnd).lower(): + win32gui.SetForegroundWindow(hwnd) + return False + win32gui.EnumWindows(_enum, None) + return True + +except ImportError: + def get_active_window(): + return {'hwnd': None, 'title': 'Unknown (pywin32 not installed)'} + + def list_windows(): + return [] + + def focus_window(title_substring: str): + return False