From 8f7a55266089bacc06a0b7fc01a6d05f4d7dd444 Mon Sep 17 00:00:00 2001 From: jason Date: Tue, 24 Mar 2026 00:12:06 -0500 Subject: [PATCH 1/2] Initial commit for README.md via agent --- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2a16f86 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# Drop-In Agent Instruction Suite + +This repository is a portable markdown instruction pack for coding agents. + +Copy these files into another repository to give the agent: +- a root `AGENTS.md` entrypoint, +- a central skill index, +- category hubs for routing, +- specialized skill files for common software, docs, UX, marketing, and ideation tasks. + +## Structure + +- `AGENTS.md` - base instructions and routing rules +- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults +- `INSTALL.md` - copy and customization guide for other repositories +- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults +- `SKILLS.md` - canonical skill index +- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples +- `hubs/` - category-level routing guides +- `skills/` - specialized reusable skill files + +## Design Goals + +- Plain markdown only +- Cross-agent portability +- Implementation-first defaults +- On-demand skill loading instead of loading everything every session +- Context-efficient routing for large skill libraries +- Prefilled deployment defaults without per-install questioning +- Repo-local instructions take precedence over this bundle + +## Intended Workflow + +1. The agent reads `AGENTS.md`. +2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in. +3. The agent checks `SKILLS.md`. +4. The agent opens only the relevant hub and skill files for the task. +5. The agent combines multiple skills when the task spans several domains. + +## Core Categories + +- Software development +- Debugging +- Documentation +- UI/UX +- Marketing +- Brainstorming From b037d09062aa3d0ad8113de87c0de85b162284f7 Mon Sep 17 00:00:00 2001 From: jason Date: Tue, 24 Mar 2026 00:12:21 -0500 Subject: [PATCH 2/2] Initial commit for AGENTS.md via agent --- AGENTS.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..11db255 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Agent Operating Guide + +Use this file as the first entrypoint for work in this repository. + +If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) exists and contains filled-in defaults, read it immediately after this file and treat it as the source of preloaded project preferences unless the destination repository provides stronger instructions. + +## Default Behavior + +- Inspect the repository before making assumptions. +- Prefer implementing and verifying work over giving abstract advice unless the user explicitly asks for planning only. +- Read only the skill files needed for the current task. +- Reuse existing project patterns, naming, architecture, and conventions. +- Test or validate changes when feasible, then summarize outcomes and any remaining risks. +- Update or create documentation when the change affects usage, onboarding, behavior, or developer workflow. +- If repository-specific instructions conflict with this suite, follow the repository-specific instructions. + +## How To Load Skills + +1. Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in for this deployment. +2. Read [SKILLS.md](./SKILLS.md). +3. Identify the task category and open the matching hub file. +4. Open only the specialized skill files relevant to the request. +5. Combine skills when the task spans multiple areas. +6. Avoid loading unrelated skills just because they exist. + +## Context Economy Rules + +- Default to reading one hub and two to four specialized skills for a normal task. +- Add more skills only when they materially change the approach, output, or quality bar. +- Prefer depth in the relevant skills over shallow loading across many categories. +- If two skills overlap heavily, choose the one that best matches the main risk or deliverable. +- Re-open the index when the task shifts, but do not reload the entire library reflexively. +- Treat the deployment profile as the early context layer and avoid re-reading it unless the task changes the relevant preference area. + +## Instruction Precedence + +Apply guidance in this order: + +1. Destination repository instructions +2. [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) +3. Generic routing and skill guidance from this suite + +## Routing Table + +| Task type | Start here | +| --- | --- | +| Feature work, refactors, reviews, tests, backend, frontend | [hubs/software-development.md](./hubs/software-development.md) | +| Failing tests, bugs, incident-style analysis, root-cause work | [hubs/debugging.md](./hubs/debugging.md) | +| Technical docs, onboarding, release notes, change communication | [hubs/documentation.md](./hubs/documentation.md) | +| UX evaluation, UI polish, interaction quality, content design | [hubs/ui-ux.md](./hubs/ui-ux.md) | +| Product copy, launch messaging, marketing content | [hubs/marketing.md](./hubs/marketing.md) | +| Ideation, option generation, structured brainstorming | [hubs/brainstorming.md](./hubs/brainstorming.md) | + +## Combination Rules + +- For new features, combine implementation + test strategy + relevant docs. +- For UI work, combine frontend implementation + UX review + product copy when text matters. +- For broken behavior, combine bug triage + debugging workflow + change summary when a fix lands. +- For launch or release tasks, combine technical docs or release notes with messaging or marketing skills as needed. +- For high-risk changes, add security review, observability, or performance optimization as appropriate. +- For long-lived system changes, add architecture and system design, dependency lifecycle, or database migration planning when relevant. + +## Output Expectations + +- Deliver concrete work products, not just observations. +- State key assumptions when the repository does not answer them. +- Call out blockers, tradeoffs, risks, and unverified areas clearly. +- Keep explanations concise and action-oriented.