Upload files to "/"
This commit is contained in:
68
AGENTS.md
Normal file
68
AGENTS.md
Normal file
@@ -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.
|
||||||
99
DEPLOYMENT-PROFILE.md
Normal file
99
DEPLOYMENT-PROFILE.md
Normal file
@@ -0,0 +1,99 @@
|
|||||||
|
# Deployment Profile
|
||||||
|
|
||||||
|
Use this file to stage prefilled defaults before deploying the suite into other repositories.
|
||||||
|
|
||||||
|
This file is the canonical source of preloaded build, tool, environment, workflow, and quality preferences for the deployed bundle. Keep it concise enough to be read early in a session.
|
||||||
|
|
||||||
|
## Precedence
|
||||||
|
|
||||||
|
1. Destination repository instructions
|
||||||
|
2. This deployment profile
|
||||||
|
3. Generic `AGENTS.md`, hubs, and skill files
|
||||||
|
|
||||||
|
## How To Maintain This File
|
||||||
|
|
||||||
|
- Fill out [PROJECT-PROFILE-WORKBOOK.md](./PROJECT-PROFILE-WORKBOOK.md) first.
|
||||||
|
- Rewrite the answers here as agent-facing defaults, not as questions.
|
||||||
|
- Prefer short, durable defaults over long policy prose.
|
||||||
|
- Update this file when your preferred build, tool, or workflow defaults change materially.
|
||||||
|
|
||||||
|
## Global Defaults
|
||||||
|
|
||||||
|
- Optimize first for full-stack web application repositories.
|
||||||
|
- Assume Windows and PowerShell for local development, but keep Docker and Linux deployment realities in mind.
|
||||||
|
- Prefer compatibility-first tooling and standard stack defaults when multiple valid tools exist.
|
||||||
|
- Favor Node and TypeScript for application work, while using Python when it is the best fit for tooling or automation.
|
||||||
|
- Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
|
||||||
|
- Ask clarifying questions before meaningful changes when product intent or risk is unclear.
|
||||||
|
- Update documentation for meaningful changes, especially README content, Unraid install docs, roadmaps, and shipped or release-oriented summaries.
|
||||||
|
- Hold user-facing work to a high polish bar by default.
|
||||||
|
- Provide concise change summaries after meaningful work and call out rollout or migration impact when relevant.
|
||||||
|
- Optimize hardest against regressions and broken behavior.
|
||||||
|
|
||||||
|
## Software Development Defaults
|
||||||
|
|
||||||
|
- Favor modular boundaries and cleaner separation early rather than waiting for severe pain.
|
||||||
|
- Operate as a full-stack agent by default and work comfortably across frontend and backend.
|
||||||
|
- Prefer mainstream modern patterns for the stack when multiple valid options exist.
|
||||||
|
- Assume relational databases first unless the repository clearly indicates otherwise.
|
||||||
|
- Be careful with schema and migration work, but do not overengineer small changes.
|
||||||
|
- Prefer small, safe, frequent dependency upgrades with focused validation.
|
||||||
|
- Treat performance as important early, especially on critical paths.
|
||||||
|
- Apply a basic secure-defaults baseline: validate input, handle secrets safely, and respect auth boundaries.
|
||||||
|
- Maintain good operational hygiene with meaningful logs and diagnostics on important paths, and add more for risky systems.
|
||||||
|
- Use feature work as an opportunity for meaningful surrounding cleanup when the added refactoring clearly improves the change.
|
||||||
|
|
||||||
|
## Debugging Defaults
|
||||||
|
|
||||||
|
- Start with the fastest trustworthy signal rather than forcing a single debugging order.
|
||||||
|
- Lean on logs and traces heavily before guessing.
|
||||||
|
- During live or user-impacting incidents, stabilize first and diagnose more deeply after impact is reduced.
|
||||||
|
- Prefer reversible mitigations such as rollbacks, flags, or partial disablement when risk is high.
|
||||||
|
- Add regression tests for higher-risk or recurring bugs rather than treating every fix as a mandatory test addition.
|
||||||
|
- Explain root cause clearly by connecting symptom, cause, and why the fix works.
|
||||||
|
- Avoid temporary compromises unless there is no safer path.
|
||||||
|
- Bundle observability improvements with medium or high-risk bug fixes when they would make future diagnosis easier.
|
||||||
|
|
||||||
|
## Documentation Defaults
|
||||||
|
|
||||||
|
- Treat documentation as part of most meaningful implementation work unless it is clearly unnecessary.
|
||||||
|
- Default to practical onboarding that includes prerequisites, setup steps, validation, and common gotchas.
|
||||||
|
- Create or update ADRs for major technical decisions and meaningful pattern shifts.
|
||||||
|
- Write concise, audience-aware change summaries that call out user impact when relevant.
|
||||||
|
- Maintain strong API and integration documentation by default for meaningful backend or interface work.
|
||||||
|
- Prefer examples, snippets, and commands in places where they reduce ambiguity and improve adoption.
|
||||||
|
- Update docs for any meaningful user-facing, setup, or team workflow change.
|
||||||
|
- Bias toward concise documentation for reference material and more complete guidance for onboarding and operational content.
|
||||||
|
|
||||||
|
## UI/UX Defaults
|
||||||
|
|
||||||
|
- Prefer reuse of existing design-system components and patterns, but allow custom patterns when they clearly improve the experience.
|
||||||
|
- Do not assume extra accessibility work by default beyond the repository or task requirements unless the task calls for it.
|
||||||
|
- Design responsively for both desktop and mobile by default.
|
||||||
|
- Reuse components when they fit well, and create new abstractions when they are likely to matter again.
|
||||||
|
- Hold interface copy to a highly polished product-copy standard by default.
|
||||||
|
- Use motion and visual flourish actively enough to make interfaces feel premium.
|
||||||
|
- Bias toward bold, distinctive UI within reason rather than purely conservative continuity.
|
||||||
|
- Treat UI work as incomplete until important states, copy quality, polish, and edge cases are addressed.
|
||||||
|
|
||||||
|
## Marketing Defaults
|
||||||
|
|
||||||
|
- Prioritize a mixed audience with a lean toward technical and product-savvy readers.
|
||||||
|
- Use a premium, distinctive, and persuasive voice.
|
||||||
|
- Keep marketing claims persuasive but grounded in real features and outcomes.
|
||||||
|
- Default to a fuller launch kit when marketing work is requested: release notes, launch copy, landing page sections, and social or email variants as appropriate.
|
||||||
|
- Balance launch messaging with evergreen discoverability, but do not let SEO weaken clarity.
|
||||||
|
- Favor sharp, polished product copy with strong differentiation and clear calls to action.
|
||||||
|
- Frame positioning conservatively around real value rather than aggressive comparative claims.
|
||||||
|
- Prefer clear, action-oriented CTAs without heavy urgency.
|
||||||
|
|
||||||
|
## Brainstorming Defaults
|
||||||
|
|
||||||
|
- Favor breadth first when generating ideas.
|
||||||
|
- Generate three options by default before recommending one.
|
||||||
|
- Compare ideas primarily through user value, differentiation, and implementation realism.
|
||||||
|
- Prioritize roadmap or opportunity choices through strategic fit, user value, and implementation cost.
|
||||||
|
- Balance innovation with execution realism and require a believable path to implementation.
|
||||||
|
- Use a short-to-medium horizon with practical sequencing for roadmap framing.
|
||||||
|
- Turn brainstorming into a scoped implementation plan once a preferred option is selected.
|
||||||
|
- Do not filter ideas out too early; raise concerns and explore alternatives that may offer more value before narrowing.
|
||||||
207
PROJECT-PROFILE-WORKBOOK.md
Normal file
207
PROJECT-PROFILE-WORKBOOK.md
Normal file
@@ -0,0 +1,207 @@
|
|||||||
|
# Project Profile Workbook
|
||||||
|
|
||||||
|
Fill out this workbook once before deployment when you want the suite to ship with pre-staged defaults for build, tools, environment, workflow, and quality preferences.
|
||||||
|
|
||||||
|
This version has been completed and should act as the human-readable source behind [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md).
|
||||||
|
|
||||||
|
## How To Use This Workbook
|
||||||
|
|
||||||
|
- Keep answers concise and specific.
|
||||||
|
- Prefer durable defaults over task-specific preferences.
|
||||||
|
- If a question does not matter for your projects, write `No strong preference`.
|
||||||
|
- If your answer depends on project type, note the default and the main exception.
|
||||||
|
- Treat this workbook as the source for pre-deployment staging, not a runtime questionnaire.
|
||||||
|
|
||||||
|
## Global Defaults
|
||||||
|
|
||||||
|
### 1. What repository types should this suite optimize for by default?
|
||||||
|
Answer: Full-stack web apps.
|
||||||
|
|
||||||
|
### 2. What operating systems, shells, and local environments should the agent assume first?
|
||||||
|
Answer: Windows and PowerShell for local development. Keep Linux, Docker, and Unraid deployment realities in mind.
|
||||||
|
|
||||||
|
### 3. What package managers, build tools, and task runners should the agent prefer when multiple options exist?
|
||||||
|
Answer: Compatibility-first defaults and standard stack tooling.
|
||||||
|
|
||||||
|
### 4. Which languages, runtimes, or frameworks should get first-class preference across deployments?
|
||||||
|
Answer: Node and TypeScript first for application work, with Python acceptable for tooling and automation.
|
||||||
|
|
||||||
|
### 5. What is your default testing philosophy before considering work complete?
|
||||||
|
Answer: Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
|
||||||
|
|
||||||
|
### 6. How cautious should the agent be about asking questions versus making reasonable assumptions?
|
||||||
|
Answer: Ask-first when product intent or change risk is unclear.
|
||||||
|
|
||||||
|
### 7. What documentation should usually be updated when behavior, setup, or workflows change?
|
||||||
|
Answer: Readmes, Unraid install docs, roadmaps, and shipped summaries are all important and should usually be updated when changes matter.
|
||||||
|
|
||||||
|
### 8. What UX and polish bar should the suite assume for user-facing changes?
|
||||||
|
Answer: High polish by default.
|
||||||
|
|
||||||
|
### 9. What release, rollout, and communication expectations should be standard?
|
||||||
|
Answer: Provide a concise change summary by default and note rollout or migration impact when relevant.
|
||||||
|
|
||||||
|
### 10. What kinds of risk should the suite optimize hardest against?
|
||||||
|
Answer: Regressions and broken behavior.
|
||||||
|
|
||||||
|
## Software Development Defaults
|
||||||
|
|
||||||
|
### 1. What architecture style or system design bias should be the default?
|
||||||
|
Answer: Favor modular boundaries and cleaner separation early.
|
||||||
|
|
||||||
|
### 2. How should the suite balance frontend, backend, and full-stack execution by default?
|
||||||
|
Answer: Full-stack by default.
|
||||||
|
|
||||||
|
### 3. Which frameworks, libraries, or implementation patterns should be preferred first?
|
||||||
|
Answer: Prefer mainstream modern patterns for the stack.
|
||||||
|
|
||||||
|
### 4. What database and persistence assumptions should the agent make?
|
||||||
|
Answer: Relational database first.
|
||||||
|
|
||||||
|
### 5. How conservative should migration and schema-change work be?
|
||||||
|
Answer: Be careful, but do not overengineer small schema changes.
|
||||||
|
|
||||||
|
### 6. What dependency upgrade strategy should be assumed?
|
||||||
|
Answer: Prefer small, safe, frequent upgrades with focused validation.
|
||||||
|
|
||||||
|
### 7. What performance bar should the suite assume by default?
|
||||||
|
Answer: Be proactive about performance on critical paths.
|
||||||
|
|
||||||
|
### 8. What minimum security baseline should be applied to code changes?
|
||||||
|
Answer: Basic secure defaults only: validate input, handle secrets safely, and respect auth boundaries.
|
||||||
|
|
||||||
|
### 9. What observability and operability expectations should be normal?
|
||||||
|
Answer: Good operational hygiene with meaningful logs and diagnostics for important paths.
|
||||||
|
|
||||||
|
### 10. How aggressive should the agent be about refactoring and technical debt reduction while doing feature work?
|
||||||
|
Answer: Use feature work as an opportunity to improve surrounding structure meaningfully when it helps the change.
|
||||||
|
|
||||||
|
## Debugging Defaults
|
||||||
|
|
||||||
|
### 1. Should debugging start with reproduction first, code inspection first, or whichever is fastest to verify?
|
||||||
|
Answer: Use whichever path gives the fastest trustworthy signal.
|
||||||
|
|
||||||
|
### 2. What logs, traces, or diagnostics should the agent expect to consult before guessing?
|
||||||
|
Answer: Lean on logs and traces first.
|
||||||
|
|
||||||
|
### 3. How should the agent behave during live or user-impacting incidents?
|
||||||
|
Answer: Stabilize first, then diagnose more deeply.
|
||||||
|
|
||||||
|
### 4. What is the preferred rollback, mitigation, or feature-flag strategy when risk is high?
|
||||||
|
Answer: Prefer reversible mitigations such as flags, rollbacks, or partial disablement.
|
||||||
|
|
||||||
|
### 5. How strongly should the agent try to add or update tests when fixing bugs?
|
||||||
|
Answer: Add tests for higher-risk or recurring bugs.
|
||||||
|
|
||||||
|
### 6. What level of root-cause explanation should be standard after a fix?
|
||||||
|
Answer: Clearly explain cause, symptom, and why the fix works.
|
||||||
|
|
||||||
|
### 7. What tradeoffs are acceptable when stabilizing an issue quickly?
|
||||||
|
Answer: Avoid temporary compromises unless there is no safer path.
|
||||||
|
|
||||||
|
### 8. When should observability improvements be bundled with a bug fix?
|
||||||
|
Answer: For most medium or high-risk bugs, add enough signal to help next time.
|
||||||
|
|
||||||
|
## Documentation Defaults
|
||||||
|
|
||||||
|
### 1. How strongly should the suite treat documentation as part of normal implementation work?
|
||||||
|
Answer: Docs are part of most meaningful changes unless clearly unnecessary.
|
||||||
|
|
||||||
|
### 2. What onboarding depth should be the default for new repos or contributor workflows?
|
||||||
|
Answer: Practical onboarding with prerequisites, setup steps, validation, and common gotchas.
|
||||||
|
|
||||||
|
### 3. When should architecture decision records be created or updated?
|
||||||
|
Answer: For major decisions and meaningful pattern shifts.
|
||||||
|
|
||||||
|
### 4. What release-note or change-summary style should be standard?
|
||||||
|
Answer: Concise, audience-aware summaries with user impact called out when relevant.
|
||||||
|
|
||||||
|
### 5. What level of API or integration documentation is expected by default?
|
||||||
|
Answer: Strong API and integration documentation by default.
|
||||||
|
|
||||||
|
### 6. How much should examples, snippets, or command samples be favored in docs?
|
||||||
|
Answer: Prefer examples for setup, APIs, and workflows where ambiguity hurts adoption.
|
||||||
|
|
||||||
|
### 7. What documentation updates should be mandatory after behavior or workflow changes?
|
||||||
|
Answer: Update docs for any meaningful user-facing, setup, or team workflow change.
|
||||||
|
|
||||||
|
### 8. What types of documentation should be concise versus comprehensive?
|
||||||
|
Answer: Balanced. Keep reference content concise and onboarding or operational content more complete.
|
||||||
|
|
||||||
|
## UI/UX Defaults
|
||||||
|
|
||||||
|
### 1. How strict should design-system adherence be by default?
|
||||||
|
Answer: Strong preference for reuse, but custom patterns are acceptable when they clearly improve the experience.
|
||||||
|
|
||||||
|
### 2. What accessibility baseline should every user-facing change meet?
|
||||||
|
Answer: Do not assume extra accessibility work by default unless requested.
|
||||||
|
|
||||||
|
### 3. What responsive behavior should be assumed for new or updated UI?
|
||||||
|
Answer: Responsive by default for desktop and mobile.
|
||||||
|
|
||||||
|
### 4. How strongly should the agent favor component reuse over local implementation?
|
||||||
|
Answer: Reuse when it fits well, and create new abstractions only when they are likely to matter again.
|
||||||
|
|
||||||
|
### 5. What clarity and copy standards should be assumed for interface text?
|
||||||
|
Answer: Highly polished product-copy quality by default.
|
||||||
|
|
||||||
|
### 6. How much motion, animation, or visual flourish is appropriate by default?
|
||||||
|
Answer: Use motion and flourish actively enough to make the interface feel premium.
|
||||||
|
|
||||||
|
### 7. Should the suite bias toward bold, distinctive UI or conservative continuity with existing patterns?
|
||||||
|
Answer: Bold and distinctive by default, within reason.
|
||||||
|
|
||||||
|
### 8. How detailed should UI work be before it is considered ready?
|
||||||
|
Answer: High completeness with strong state coverage, copy quality, polish, and edge-case handling.
|
||||||
|
|
||||||
|
## Marketing Defaults
|
||||||
|
|
||||||
|
### 1. Which audience should marketing and messaging defaults prioritize first?
|
||||||
|
Answer: Mixed audience, leaning technical and product-savvy.
|
||||||
|
|
||||||
|
### 2. What voice and tone should be the baseline?
|
||||||
|
Answer: Premium, distinctive, and persuasive.
|
||||||
|
|
||||||
|
### 3. What level of proof, specificity, or technical grounding should marketing claims include?
|
||||||
|
Answer: Claims should be persuasive but grounded in real features and outcomes.
|
||||||
|
|
||||||
|
### 4. What launch-content formats should be standard by default?
|
||||||
|
Answer: Broader launch kit: release notes, launch copy, landing page sections, and social or email variants.
|
||||||
|
|
||||||
|
### 5. How important is SEO and evergreen discoverability relative to launch messaging?
|
||||||
|
Answer: Balance both, but do not let SEO weaken clarity.
|
||||||
|
|
||||||
|
### 6. What product-copy style should be the default?
|
||||||
|
Answer: Strong product-copy polish with sharper differentiation and CTA energy.
|
||||||
|
|
||||||
|
### 7. How should the suite frame differentiation and positioning?
|
||||||
|
Answer: Conservative positioning that focuses on real value rather than aggressive comparison.
|
||||||
|
|
||||||
|
### 8. What types of calls to action should be preferred?
|
||||||
|
Answer: Clear, action-oriented CTAs without heavy urgency.
|
||||||
|
|
||||||
|
## Brainstorming Defaults
|
||||||
|
|
||||||
|
### 1. Should idea generation favor breadth, speed, novelty, practicality, or a specific balance?
|
||||||
|
Answer: Favor breadth first.
|
||||||
|
|
||||||
|
### 2. How many options should the agent generate by default before recommending one?
|
||||||
|
Answer: Three options by default.
|
||||||
|
|
||||||
|
### 3. What criteria should be used most often to score or compare ideas?
|
||||||
|
Answer: User value, differentiation, and implementation realism.
|
||||||
|
|
||||||
|
### 4. What prioritization method should be the default for roadmap or opportunity choices?
|
||||||
|
Answer: Strategic fit, user value, and implementation cost.
|
||||||
|
|
||||||
|
### 5. How should innovation be balanced against implementation realism?
|
||||||
|
Answer: Balanced, but require a believable path to execution.
|
||||||
|
|
||||||
|
### 6. What kind of roadmap framing should be standard?
|
||||||
|
Answer: Short-to-medium horizon with practical sequencing.
|
||||||
|
|
||||||
|
### 7. When should brainstorming output turn into a scoped implementation plan?
|
||||||
|
Answer: Usually after a preferred option is selected.
|
||||||
|
|
||||||
|
### 8. What types of ideas should usually be filtered out early?
|
||||||
|
Answer: Do not filter too early. Raise concerns and explore alternatives with more value before narrowing.
|
||||||
47
README.md
Normal file
47
README.md
Normal file
@@ -0,0 +1,47 @@
|
|||||||
|
# Drop-In Agent Instruction Suite
|
||||||
|
|
||||||
|
This repository is a portable markdown instruction pack for coding agents.
|
||||||
|
|
||||||
|
Copy these files into another repository to give the agent:
|
||||||
|
- a root `AGENTS.md` entrypoint,
|
||||||
|
- a central skill index,
|
||||||
|
- category hubs for routing,
|
||||||
|
- specialized skill files for common software, docs, UX, marketing, and ideation tasks.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
- `AGENTS.md` - base instructions and routing rules
|
||||||
|
- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults
|
||||||
|
- `INSTALL.md` - copy and customization guide for other repositories
|
||||||
|
- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults
|
||||||
|
- `SKILLS.md` - canonical skill index
|
||||||
|
- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples
|
||||||
|
- `hubs/` - category-level routing guides
|
||||||
|
- `skills/` - specialized reusable skill files
|
||||||
|
|
||||||
|
## Design Goals
|
||||||
|
|
||||||
|
- Plain markdown only
|
||||||
|
- Cross-agent portability
|
||||||
|
- Implementation-first defaults
|
||||||
|
- On-demand skill loading instead of loading everything every session
|
||||||
|
- Context-efficient routing for large skill libraries
|
||||||
|
- Prefilled deployment defaults without per-install questioning
|
||||||
|
- Repo-local instructions take precedence over this bundle
|
||||||
|
|
||||||
|
## Intended Workflow
|
||||||
|
|
||||||
|
1. The agent reads `AGENTS.md`.
|
||||||
|
2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in.
|
||||||
|
3. The agent checks `SKILLS.md`.
|
||||||
|
4. The agent opens only the relevant hub and skill files for the task.
|
||||||
|
5. The agent combines multiple skills when the task spans several domains.
|
||||||
|
|
||||||
|
## Core Categories
|
||||||
|
|
||||||
|
- Software development
|
||||||
|
- Debugging
|
||||||
|
- Documentation
|
||||||
|
- UI/UX
|
||||||
|
- Marketing
|
||||||
|
- Brainstorming
|
||||||
84
ROUTING-EXAMPLES.md
Normal file
84
ROUTING-EXAMPLES.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user