Build agent instruction suite with deployment profiling

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.

DEPLOYMENT-PROFILE.md

@@ -0,0 +1,106 @@
+# 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
+
+Replace this section with concise deployment-wide defaults for:
+- target repository types
+- OS, shell, and environment assumptions
+- preferred package managers, build tools, and task runners
+- favored languages, runtimes, and frameworks
+- testing philosophy by risk level
+- assumption-versus-confirmation bias
+- default documentation expectations
+- UX and quality bar
+- release and rollout expectations
+- top risks to optimize against
+
+## Software Development Defaults
+
+Replace this section with concise defaults for:
+- architecture bias
+- frontend, backend, or full-stack emphasis
+- preferred frameworks and implementation patterns
+- database and persistence assumptions
+- migration safety posture
+- dependency upgrade strategy
+- performance expectations
+- security baseline
+- observability expectations
+- refactoring and technical-debt appetite
+
+## Debugging Defaults
+
+Replace this section with concise defaults for:
+- repro-first versus inspect-first posture
+- preferred diagnostic signals
+- incident and stabilization behavior
+- rollback and mitigation posture
+- regression-test expectations for bug fixes
+- root-cause explanation standard
+- acceptable short-term stabilization tradeoffs
+- threshold for bundling observability improvements with fixes
+
+## Documentation Defaults
+
+Replace this section with concise defaults for:
+- docs-as-code posture
+- onboarding depth
+- ADR expectations
+- release-note and change-summary style
+- API and integration doc expectations
+- examples and snippet preference
+- required update thresholds after behavior changes
+- concise versus comprehensive doc bias
+
+## UI/UX Defaults
+
+Replace this section with concise defaults for:
+- design-system strictness
+- accessibility baseline
+- responsive expectations
+- component reuse policy
+- interface copy standards
+- motion and visual flourish tolerance
+- boldness versus continuity preference
+- required state coverage for UI readiness
+
+## Marketing Defaults
+
+Replace this section with concise defaults for:
+- primary audience priority
+- baseline voice and tone
+- claim-proof expectations
+- launch-content defaults
+- SEO versus launch emphasis
+- product-copy style
+- positioning posture
+- preferred CTA style
+
+## Brainstorming Defaults
+
+Replace this section with concise defaults for:
+- breadth versus speed bias
+- default option count
+- scoring criteria
+- prioritization method
+- innovation versus practicality balance
+- roadmap framing
+- trigger for converting ideas into plans
+- common early rejection criteria

INSTALL.md

@@ -0,0 +1,105 @@
+# Install and Copy Guide
+
+Use this guide to copy the instruction suite into another repository without bloating the destination or confusing the agent.
+
+## Recommended Install
+
+Copy these items into the target repository root:
+
+- `AGENTS.md`
+- `DEPLOYMENT-PROFILE.md`
+- `SKILLS.md`
+- `PROJECT-PROFILE-WORKBOOK.md`
+- `ROUTING-EXAMPLES.md`
+- `hubs/`
+- `skills/`
+
+Optional:
+
+- `README.md` if you want human-facing explanation of the bundle in the destination repo
+
+## Fast Copy Workflow
+
+From this repository root, copy the suite into another repo root while excluding `.git`:
+
+```powershell
+Copy-Item AGENTS.md,DEPLOYMENT-PROFILE.md,SKILLS.md,PROJECT-PROFILE-WORKBOOK.md,ROUTING-EXAMPLES.md -Destination <target-repo>
+Copy-Item hubs -Destination <target-repo> -Recurse
+Copy-Item skills -Destination <target-repo> -Recurse
+```
+
+If you also want the explanatory readme:
+
+```powershell
+Copy-Item README.md -Destination <target-repo>
+```
+
+## Prefill Workflow
+
+Before deployment:
+
+1. Fill out `PROJECT-PROFILE-WORKBOOK.md`.
+2. Translate the answers into agent-facing defaults in `DEPLOYMENT-PROFILE.md`.
+3. Keep the deployment profile concise so it can be read early without wasting context.
+4. Copy the suite with the filled-in deployment profile included.
+
+At runtime:
+
+1. The agent reads `AGENTS.md`.
+2. The agent reads `DEPLOYMENT-PROFILE.md` if it is filled in.
+3. The agent reads `SKILLS.md`.
+4. The agent opens the relevant hub and specialized skill files only as needed.
+
+## Minimal Install
+
+If the target repository wants the smallest useful setup, copy:
+
+- `AGENTS.md`
+- `DEPLOYMENT-PROFILE.md`
+- `SKILLS.md`
+- `hubs/`
+- only the skill files the team expects to use often
+
+Good minimal baseline:
+
+- `skills/software/repo-exploration.md`
+- `skills/software/feature-implementation.md`
+- `skills/software/test-strategy.md`
+- `skills/software/code-review.md`
+- `skills/debugging/bug-triage.md`
+- `skills/debugging/debugging-workflow.md`
+- `skills/documentation/technical-docs.md`
+- `skills/ui-ux/ux-review.md`
+
+## How To Customize Safely
+
+- Keep `AGENTS.md` short and stable; put detail in hubs and skill files.
+- Add repo-specific instructions near the top of `AGENTS.md` or in existing repo instruction files.
+- Treat `DEPLOYMENT-PROFILE.md` as the canonical place for staged build, tool, environment, and workflow defaults.
+- Prefer editing hub routing before adding more root-level rules.
+- Add new skill files only when they introduce a distinct workflow, risk area, or deliverable.
+- If two skills overlap heavily, merge them or make the routing distinction explicit.
+
+## Context Limit Guidance
+
+- Do not instruct the agent to load the entire `skills/` tree on every task.
+- Keep the default path to one hub plus two to four specialized skills.
+- Reserve four to six skills for large cross-functional tasks.
+- Use the routing examples to confirm the suite still routes clearly after customization.
+
+## Updating The Bundle
+
+- Pull improvements from this source repository into destination repos periodically.
+- Refill the workbook and refresh the deployment profile when your preferred defaults change materially.
+- Review local customizations before overwriting shared files.
+- If a destination repo has stronger local conventions, keep those and treat this suite as the fallback layer.
+
+## Suggested Verification After Copying
+
+Check that the destination repo can answer these questions clearly:
+
+1. Where does the agent start? `AGENTS.md`
+2. Where does the agent get preloaded defaults? `DEPLOYMENT-PROFILE.md`
+3. Where does the agent look for available skills? `SKILLS.md`
+4. How does the agent decide what to read next? Deployment profile, hubs, and routing examples
+5. Does the repo still prioritize local instructions over the generic bundle? It should

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.
+
+The answers here are for humans to provide. After filling this out, translate the answers into [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) so agents can use the results directly.
+
+## 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 shape: short list of repo types and their priority.
+
+### 2. What operating systems, shells, and local environments should the agent assume first?
+Answer shape: primary OS, shell, and any fallback assumptions.
+
+### 3. What package managers, build tools, and task runners should the agent prefer when multiple options exist?
+Answer shape: ranked tool preferences plus any tools to avoid.
+
+### 4. Which languages, runtimes, or frameworks should get first-class preference across deployments?
+Answer shape: priority-ordered stack preferences.
+
+### 5. What is your default testing philosophy before considering work complete?
+Answer shape: what level of testing is expected for low, medium, and high-risk changes.
+
+### 6. How cautious should the agent be about asking questions versus making reasonable assumptions?
+Answer shape: preferred bias plus examples of when to stop and confirm.
+
+### 7. What documentation should usually be updated when behavior, setup, or workflows change?
+Answer shape: required doc types and the threshold for updating them.
+
+### 8. What UX and polish bar should the suite assume for user-facing changes?
+Answer shape: default quality bar and what cannot be skipped.
+
+### 9. What release, rollout, and communication expectations should be standard?
+Answer shape: release-note, migration-note, and rollout-summary expectations.
+
+### 10. What kinds of risk should the suite optimize hardest against?
+Answer shape: ranked risks such as regressions, slow delivery, incidents, weak UX, docs drift, or security gaps.
+
+## Software Development Defaults
+
+### 1. What architecture style or system design bias should be the default?
+Answer shape: preferred architecture patterns and anti-patterns.
+
+### 2. How should the suite balance frontend, backend, and full-stack execution by default?
+Answer shape: preferred split and what usually takes priority.
+
+### 3. Which frameworks, libraries, or implementation patterns should be preferred first?
+Answer shape: preferred stack choices and any banned or discouraged patterns.
+
+### 4. What database and persistence assumptions should the agent make?
+Answer shape: default datastore types, ORM/query preferences, and data-model expectations.
+
+### 5. How conservative should migration and schema-change work be?
+Answer shape: rollout posture, compatibility expectations, and rollback requirements.
+
+### 6. What dependency upgrade strategy should be assumed?
+Answer shape: preferred upgrade cadence, batch size, and tolerance for deprecations.
+
+### 7. What performance bar should the suite assume by default?
+Answer shape: key performance concerns and when optimization should be proactive.
+
+### 8. What minimum security baseline should be applied to code changes?
+Answer shape: required checks around auth, validation, secrets, or exposure.
+
+### 9. What observability and operability expectations should be normal?
+Answer shape: logging, metrics, traces, dashboards, and alerting expectations.
+
+### 10. How aggressive should the agent be about refactoring and technical debt reduction while doing feature work?
+Answer shape: cleanup appetite and what counts as acceptable adjacent improvement.
+
+## Debugging Defaults
+
+### 1. Should debugging start with reproduction first, code inspection first, or whichever is fastest to verify?
+Answer shape: preferred starting posture and exceptions.
+
+### 2. What logs, traces, or diagnostics should the agent expect to consult before guessing?
+Answer shape: preferred debugging signals in priority order.
+
+### 3. How should the agent behave during live or user-impacting incidents?
+Answer shape: stabilize-first versus diagnose-first posture and escalation expectations.
+
+### 4. What is the preferred rollback, mitigation, or feature-flag strategy when risk is high?
+Answer shape: favored containment methods and what to avoid under pressure.
+
+### 5. How strongly should the agent try to add or update tests when fixing bugs?
+Answer shape: regression-test expectations by bug type or risk.
+
+### 6. What level of root-cause explanation should be standard after a fix?
+Answer shape: expected detail and preferred format.
+
+### 7. What tradeoffs are acceptable when stabilizing an issue quickly?
+Answer shape: acceptable temporary fixes, degraded modes, or short-term compromises.
+
+### 8. When should observability improvements be bundled with a bug fix?
+Answer shape: default threshold for adding logs, metrics, traces, or alerts.
+
+## Documentation Defaults
+
+### 1. How strongly should the suite treat documentation as part of normal implementation work?
+Answer shape: docs-as-code posture and exceptions.
+
+### 2. What onboarding depth should be the default for new repos or contributor workflows?
+Answer shape: expected setup detail and verification guidance.
+
+### 3. When should architecture decision records be created or updated?
+Answer shape: qualifying decision types and expected depth.
+
+### 4. What release-note or change-summary style should be standard?
+Answer shape: preferred audience, tone, and detail level.
+
+### 5. What level of API or integration documentation is expected by default?
+Answer shape: minimum doc standard for interfaces and integrations.
+
+### 6. How much should examples, snippets, or command samples be favored in docs?
+Answer shape: preferred density and where examples are most important.
+
+### 7. What documentation updates should be mandatory after behavior or workflow changes?
+Answer shape: triggers that require doc updates.
+
+### 8. What types of documentation should be concise versus comprehensive?
+Answer shape: guidance by doc type.
+
+## UI/UX Defaults
+
+### 1. How strict should design-system adherence be by default?
+Answer shape: reuse posture and when custom patterns are acceptable.
+
+### 2. What accessibility baseline should every user-facing change meet?
+Answer shape: required accessibility checks and must-have standards.
+
+### 3. What responsive behavior should be assumed for new or updated UI?
+Answer shape: required device classes and layout expectations.
+
+### 4. How strongly should the agent favor component reuse over local implementation?
+Answer shape: reuse threshold and when new abstractions are warranted.
+
+### 5. What clarity and copy standards should be assumed for interface text?
+Answer shape: tone, verbosity, and UX-writing preferences.
+
+### 6. How much motion, animation, or visual flourish is appropriate by default?
+Answer shape: motion tolerance and preferred feel.
+
+### 7. Should the suite bias toward bold, distinctive UI or conservative continuity with existing patterns?
+Answer shape: preferred visual stance and exceptions.
+
+### 8. How detailed should UI work be before it is considered ready?
+Answer shape: expected treatment of empty, loading, error, success, and edge states.
+
+## Marketing Defaults
+
+### 1. Which audience should marketing and messaging defaults prioritize first?
+Answer shape: primary audience, secondary audience, and who to deprioritize.
+
+### 2. What voice and tone should be the baseline?
+Answer shape: 3-5 tone traits and anything to avoid.
+
+### 3. What level of proof, specificity, or technical grounding should marketing claims include?
+Answer shape: proof standard and claim tolerance.
+
+### 4. What launch-content formats should be standard by default?
+Answer shape: favored deliverables such as release notes, emails, landing pages, blog posts, or social posts.
+
+### 5. How important is SEO and evergreen discoverability relative to launch messaging?
+Answer shape: priority order and content bias.
+
+### 6. What product-copy style should be the default?
+Answer shape: clarity, persuasion, length, and CTA preferences.
+
+### 7. How should the suite frame differentiation and positioning?
+Answer shape: preferred competitive posture and value framing.
+
+### 8. What types of calls to action should be preferred?
+Answer shape: action style, urgency, and conversion posture.
+
+## Brainstorming Defaults
+
+### 1. Should idea generation favor breadth, speed, novelty, practicality, or a specific balance?
+Answer shape: default ideation bias and what to avoid.
+
+### 2. How many options should the agent generate by default before recommending one?
+Answer shape: preferred option count for small, medium, and strategic decisions.
+
+### 3. What criteria should be used most often to score or compare ideas?
+Answer shape: ranked decision criteria.
+
+### 4. What prioritization method should be the default for roadmap or opportunity choices?
+Answer shape: preferred comparison framework or decision lens.
+
+### 5. How should innovation be balanced against implementation realism?
+Answer shape: preferred balance and when to lean harder one way.
+
+### 6. What kind of roadmap framing should be standard?
+Answer shape: preferred time horizon and planning granularity.
+
+### 7. When should brainstorming output turn into a scoped implementation plan?
+Answer shape: trigger conditions and expected planning depth.
+
+### 8. What types of ideas should usually be filtered out early?
+Answer shape: common rejection criteria.

README.md

@@ -1 +1,47 @@
-Hello World
+# 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

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

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.

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.