From 649252bcf56c5e1f35cb6ee667238b41830ffb83 Mon Sep 17 00:00:00 2001 From: Oleg Shulyakov Date: Mon, 25 May 2026 12:52:46 +0300 Subject: [PATCH] refactor(skills): rename to shorter verb-first names - Rename build-* skills to code-* - Rename utility skills to shorter names - Update all internal references, metadata, evals, and docs to match new skill names --- .agents/memory/2026-05-24.md | 4 +- .agents/skills/README.md | 30 ++--- .agents/skills/adapt/SKILL.md | 2 +- .agents/skills/adapt/evals/evals.json | 2 +- .../skills/{ask-questions => ask}/SKILL.md | 6 +- .../{ask-questions => ask}/evals/evals.json | 32 ++--- .../{reason-problem => brainstorm}/SKILL.md | 6 +- .../evals/evals.json | 32 ++--- .../{decide-direction => choose}/SKILL.md | 6 +- .../evals/evals.json | 32 ++--- .../{classify-content => classify}/SKILL.md | 6 +- .../evals/evals.json | 32 ++--- .../{build-backend => code-backend}/SKILL.md | 6 +- .../evals/evals.json | 2 +- .../references/ada.md | 0 .../references/c.md | 0 .../references/cpp.md | 0 .../references/csharp-aspnet-core.md | 0 .../references/csharp.md | 0 .../references/delphi.md | 0 .../references/elixir-phoenix.md | 0 .../references/elixir.md | 0 .../references/fortran.md | 0 .../references/go-chi.md | 0 .../references/go-echo.md | 0 .../references/go-fiber.md | 0 .../references/go-gin.md | 0 .../references/go.md | 0 .../references/java-micronaut.md | 0 .../references/java-quarkus.md | 0 .../references/java-spring-boot.md | 0 .../references/java.md | 0 .../references/kotlin-ktor.md | 0 .../references/kotlin.md | 0 .../references/matlab.md | 0 .../references/nodejs-express.md | 0 .../references/nodejs-fastify.md | 0 .../references/nodejs-hono.md | 0 .../references/nodejs-nestjs.md | 0 .../references/nodejs-nitro.md | 0 .../references/nodejs.md | 0 .../references/perl.md | 0 .../references/php-laravel.md | 0 .../references/php-symfony.md | 0 .../references/php.md | 0 .../references/python-django.md | 0 .../references/python-fastapi.md | 0 .../references/python-flask.md | 0 .../references/python.md | 0 .../references/r.md | 0 .../references/ruby-rails.md | 0 .../references/ruby-sinatra.md | 0 .../references/ruby.md | 0 .../references/rust-actix-web.md | 0 .../references/rust-axum.md | 0 .../references/rust-rocket.md | 0 .../references/rust.md | 0 .../references/swift.md | 0 .../references/visual-basic.md | 0 .../SKILL.md | 8 +- .../evals/evals.json | 2 +- .../references/analytics.md | 0 .../references/bigquery.md | 0 .../references/clickhouse.md | 0 .../references/cockroachdb.md | 0 .../references/common.md | 0 .../references/migration.md | 0 .../references/mssql.md | 0 .../references/mysql.md | 0 .../references/oracle.md | 0 .../references/postgres.md | 0 .../references/schema-design.md | 0 .../references/snowflake.md | 0 .../references/sqlite.md | 0 .../SKILL.md | 8 +- .../evals/evals.json | 2 +- .../references/accessibility.md | 0 .../references/css-bootstrap.md | 0 .../references/css-component-libraries.md | 0 .../references/css-tailwind.md | 0 .../references/css.md | 0 .../references/forms.md | 0 .../references/html.md | 0 .../references/internationalization.md | 0 .../references/javascript-angular.md | 0 .../references/javascript-astro.md | 0 .../references/javascript-react-nextjs.md | 0 .../references/javascript-react-remix.md | 0 .../references/javascript-react.md | 0 .../references/javascript-solidjs.md | 0 .../references/javascript-svelte-sveltekit.md | 0 .../references/javascript-svelte.md | 0 .../references/javascript-vue-nuxt.md | 0 .../references/javascript-vue.md | 0 .../references/javascript.md | 0 .../references/performance.md | 0 .../references/pwa.md | 0 .../references/state.md | 0 .../references/typescript.md | 0 .../references/visualization.md | 0 .../{build-tests => code-tests}/SKILL.md | 6 +- .../evals/evals.json | 2 +- .../references/api.md | 0 .../references/e2e.md | 0 .../references/perf.md | 0 .../scripts/__init__.py | 0 .../scripts/agent_runner.py | 0 .../scripts/aggregate_benchmark.py | 0 .../scripts/generate_report.py | 0 .../scripts/improve_description.py | 0 .../scripts/run_eval.py | 0 .../scripts/run_loop.py | 0 .../scripts/utils.py | 0 .../scripts/validate_evals.py | 6 +- .../create-rule/scripts/grade_rule_output.py | 2 +- .../create-rule/scripts/run_trigger_eval.py | 2 +- .../{explain-topic => explain}/SKILL.md | 6 +- .../evals/evals.json | 22 ++-- .../{explore-context => explore}/SKILL.md | 6 +- .../evals/evals.json | 32 ++--- .../{coordinate-work => manage}/SKILL.md | 8 +- .../evals/evals.json | 32 ++--- .agents/skills/{plan-work => plan}/SKILL.md | 6 +- .../{plan-work => plan}/evals/evals.json | 20 +-- .../{remember-context => remember}/SKILL.md | 6 +- .../evals/evals.json | 32 ++--- docs/2026-05-02-team-roles-as-skills/PRD.md | 6 +- docs/2026-05-02-team-roles-as-skills/SPEC.md | 24 ++-- docs/2026-05-02-team-roles-as-skills/TASKS.md | 8 +- docs/2026-05-20-general-agent-skills/PRD.md | 104 +++++++-------- docs/2026-05-20-general-agent-skills/SPEC.md | 120 +++++++++--------- ...US-001-author-standalone-general-skills.md | 26 ++-- .../US-002-generate-skill-evals.md | 16 +-- docs/2026-05-23-design-principles/PRD.md | 6 +- docs/2026-05-23-design-principles/SPEC.md | 26 ++-- 135 files changed, 371 insertions(+), 371 deletions(-) rename .agents/skills/{ask-questions => ask}/SKILL.md (97%) rename .agents/skills/{ask-questions => ask}/evals/evals.json (72%) rename .agents/skills/{reason-problem => brainstorm}/SKILL.md (97%) rename .agents/skills/{reason-problem => brainstorm}/evals/evals.json (71%) rename .agents/skills/{decide-direction => choose}/SKILL.md (97%) rename .agents/skills/{decide-direction => choose}/evals/evals.json (69%) rename .agents/skills/{classify-content => classify}/SKILL.md (97%) rename .agents/skills/{classify-content => classify}/evals/evals.json (68%) rename .agents/skills/{build-backend => code-backend}/SKILL.md (99%) rename .agents/skills/{build-backend => code-backend}/evals/evals.json (99%) rename .agents/skills/{build-backend => code-backend}/references/ada.md (100%) rename .agents/skills/{build-backend => code-backend}/references/c.md (100%) rename .agents/skills/{build-backend => code-backend}/references/cpp.md (100%) rename .agents/skills/{build-backend => code-backend}/references/csharp-aspnet-core.md (100%) rename .agents/skills/{build-backend => code-backend}/references/csharp.md (100%) rename .agents/skills/{build-backend => code-backend}/references/delphi.md (100%) rename .agents/skills/{build-backend => code-backend}/references/elixir-phoenix.md (100%) rename .agents/skills/{build-backend => code-backend}/references/elixir.md (100%) rename .agents/skills/{build-backend => code-backend}/references/fortran.md (100%) rename .agents/skills/{build-backend => code-backend}/references/go-chi.md (100%) rename .agents/skills/{build-backend => code-backend}/references/go-echo.md (100%) rename .agents/skills/{build-backend => code-backend}/references/go-fiber.md (100%) rename .agents/skills/{build-backend => code-backend}/references/go-gin.md (100%) rename .agents/skills/{build-backend => code-backend}/references/go.md (100%) rename .agents/skills/{build-backend => code-backend}/references/java-micronaut.md (100%) rename .agents/skills/{build-backend => code-backend}/references/java-quarkus.md (100%) rename .agents/skills/{build-backend => code-backend}/references/java-spring-boot.md (100%) rename .agents/skills/{build-backend => code-backend}/references/java.md (100%) rename .agents/skills/{build-backend => code-backend}/references/kotlin-ktor.md (100%) rename .agents/skills/{build-backend => code-backend}/references/kotlin.md (100%) rename .agents/skills/{build-backend => code-backend}/references/matlab.md (100%) rename .agents/skills/{build-backend => code-backend}/references/nodejs-express.md (100%) rename .agents/skills/{build-backend => code-backend}/references/nodejs-fastify.md (100%) rename .agents/skills/{build-backend => code-backend}/references/nodejs-hono.md (100%) rename .agents/skills/{build-backend => code-backend}/references/nodejs-nestjs.md (100%) rename .agents/skills/{build-backend => code-backend}/references/nodejs-nitro.md (100%) rename .agents/skills/{build-backend => code-backend}/references/nodejs.md (100%) rename .agents/skills/{build-backend => code-backend}/references/perl.md (100%) rename .agents/skills/{build-backend => code-backend}/references/php-laravel.md (100%) rename .agents/skills/{build-backend => code-backend}/references/php-symfony.md (100%) rename .agents/skills/{build-backend => code-backend}/references/php.md (100%) rename .agents/skills/{build-backend => code-backend}/references/python-django.md (100%) rename .agents/skills/{build-backend => code-backend}/references/python-fastapi.md (100%) rename .agents/skills/{build-backend => code-backend}/references/python-flask.md (100%) rename .agents/skills/{build-backend => code-backend}/references/python.md (100%) rename .agents/skills/{build-backend => code-backend}/references/r.md (100%) rename .agents/skills/{build-backend => code-backend}/references/ruby-rails.md (100%) rename .agents/skills/{build-backend => code-backend}/references/ruby-sinatra.md (100%) rename .agents/skills/{build-backend => code-backend}/references/ruby.md (100%) rename .agents/skills/{build-backend => code-backend}/references/rust-actix-web.md (100%) rename .agents/skills/{build-backend => code-backend}/references/rust-axum.md (100%) rename .agents/skills/{build-backend => code-backend}/references/rust-rocket.md (100%) rename .agents/skills/{build-backend => code-backend}/references/rust.md (100%) rename .agents/skills/{build-backend => code-backend}/references/swift.md (100%) rename .agents/skills/{build-backend => code-backend}/references/visual-basic.md (100%) rename .agents/skills/{build-database => code-database}/SKILL.md (98%) rename .agents/skills/{build-database => code-database}/evals/evals.json (99%) rename .agents/skills/{build-database => code-database}/references/analytics.md (100%) rename .agents/skills/{build-database => code-database}/references/bigquery.md (100%) rename .agents/skills/{build-database => code-database}/references/clickhouse.md (100%) rename .agents/skills/{build-database => code-database}/references/cockroachdb.md (100%) rename .agents/skills/{build-database => code-database}/references/common.md (100%) rename .agents/skills/{build-database => code-database}/references/migration.md (100%) rename .agents/skills/{build-database => code-database}/references/mssql.md (100%) rename .agents/skills/{build-database => code-database}/references/mysql.md (100%) rename .agents/skills/{build-database => code-database}/references/oracle.md (100%) rename .agents/skills/{build-database => code-database}/references/postgres.md (100%) rename .agents/skills/{build-database => code-database}/references/schema-design.md (100%) rename .agents/skills/{build-database => code-database}/references/snowflake.md (100%) rename .agents/skills/{build-database => code-database}/references/sqlite.md (100%) rename .agents/skills/{build-frontend => code-frontend}/SKILL.md (96%) rename .agents/skills/{build-frontend => code-frontend}/evals/evals.json (99%) rename .agents/skills/{build-frontend => code-frontend}/references/accessibility.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/css-bootstrap.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/css-component-libraries.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/css-tailwind.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/css.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/forms.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/html.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/internationalization.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-angular.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-astro.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-react-nextjs.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-react-remix.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-react.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-solidjs.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-svelte-sveltekit.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-svelte.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-vue-nuxt.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript-vue.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/javascript.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/performance.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/pwa.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/state.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/typescript.md (100%) rename .agents/skills/{build-frontend => code-frontend}/references/visualization.md (100%) rename .agents/skills/{build-tests => code-tests}/SKILL.md (98%) rename .agents/skills/{build-tests => code-tests}/evals/evals.json (98%) rename .agents/skills/{build-tests => code-tests}/references/api.md (100%) rename .agents/skills/{build-tests => code-tests}/references/e2e.md (100%) rename .agents/skills/{build-tests => code-tests}/references/perf.md (100%) rename .agents/skills/{build-tests => code-tests}/scripts/__init__.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/agent_runner.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/aggregate_benchmark.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/generate_report.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/improve_description.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/run_eval.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/run_loop.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/utils.py (100%) rename .agents/skills/{build-tests => code-tests}/scripts/validate_evals.py (96%) rename .agents/skills/{explain-topic => explain}/SKILL.md (99%) rename .agents/skills/{explain-topic => explain}/evals/evals.json (90%) rename .agents/skills/{explore-context => explore}/SKILL.md (97%) rename .agents/skills/{explore-context => explore}/evals/evals.json (69%) rename .agents/skills/{coordinate-work => manage}/SKILL.md (96%) rename .agents/skills/{coordinate-work => manage}/evals/evals.json (69%) rename .agents/skills/{plan-work => plan}/SKILL.md (97%) rename .agents/skills/{plan-work => plan}/evals/evals.json (84%) rename .agents/skills/{remember-context => remember}/SKILL.md (97%) rename .agents/skills/{remember-context => remember}/evals/evals.json (68%) diff --git a/.agents/memory/2026-05-24.md b/.agents/memory/2026-05-24.md index f1d2962..eaf3978 100644 --- a/.agents/memory/2026-05-24.md +++ b/.agents/memory/2026-05-24.md @@ -6,8 +6,8 @@ Skill naming, metadata, document metadata, and utility skill coverage were align ## Observations -- Renamed skills to a verb-first naming convention, including `write-tests` to `build-tests`. -- Added general utility skills: `ask-questions`, `classify-content`, `coordinate-work`, `decide-direction`, `explore-context`, `plan-work`, `reason-problem`, `remember-context`, and `adapt`. +- Renamed skills to a verb-first naming convention, including `write-tests` to `code-tests`. +- Added general utility skills: `ask`, `classify`, `manage`, `choose`, `explore`, `plan`, `brainstorm`, `remember`, and `adapt`. - Added tags and YAML frontmatter metadata to skills. - Moved `author`, `version`, and `source` under `metadata`; added `metadata.category` to maintained skills, rules, and commands. - Updated `create-skill` and `create-rule` authoring guidance so new artifacts place categories under `metadata.category`. diff --git a/.agents/skills/README.md b/.agents/skills/README.md index f0386f9..5ec733f 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -9,24 +9,24 @@ A complete skill is a directory with a required `SKILL.md` file and optional bun | Skill | Use it for | Notable resources | | --- | --- | --- | | [`adapt`](adapt/SKILL.md) | Detecting evidence-driven change needs and routing updates to the right skill, workflow, artifact, or owner. | [`evals/`](adapt/evals/) | -| [`ask-questions`](ask-questions/SKILL.md) | Generating high-leverage questions, clarifying missing context, and surfacing assumptions. | [`evals/`](ask-questions/evals/) | +| [`ask`](ask/SKILL.md) | Generating high-leverage questions, clarifying missing context, and surfacing assumptions. | [`evals/`](ask/evals/) | | [`audit-skill-security`](audit-skill-security/SKILL.md) | Auditing third-party or local skills before installing, updating, or trusting them. | [`references/audit-protocol.md`](audit-skill-security/references/audit-protocol.md) | -| [`classify-content`](classify-content/SKILL.md) | Organizing material into meaningful groups by criteria, similarity, priority, dependency, or abstraction level. | [`evals/`](classify-content/evals/) | -| [`build-backend`](build-backend/SKILL.md) | Production backend code: APIs, services, middleware, workers, persistence, validation, auth, and backend tests. | [`references/`](build-backend/references/), [`evals/`](build-backend/evals/) | -| [`build-database`](build-database/SKILL.md) | Database code: schemas, DDL, OLTP SQL, analytics SQL, migrations, indexes, stored procedures, and dialect-specific scripts. | [`references/`](build-database/references/), [`evals/`](build-database/evals/) | -| [`build-frontend`](build-frontend/SKILL.md) | Production frontend code: components, routes, client state, forms, styling, accessibility, performance, PWA behavior, and visualization. | [`references/`](build-frontend/references/), [`evals/`](build-frontend/evals/) | -| [`build-tests`](build-tests/SKILL.md) | Automated tests and evals, including E2E, API, integration, performance, AI output, tool-use, RAG, and prompt regression suites. | [`references/`](build-tests/references/), [`scripts/`](build-tests/scripts/), [`evals/`](build-tests/evals/) | -| [`coordinate-work`](coordinate-work/SKILL.md) | Managing active work across people, agents, tasks, dependencies, blockers, status, and handoffs. | [`evals/`](coordinate/evals/) | +| [`brainstorm`](brainstorm/SKILL.md) | Working through ambiguous problems, assumptions, hypotheses, and problem framing before deciding or planning. | [`evals/`](brainstorm/evals/) | +| [`choose`](choose/SKILL.md) | Comparing options, weighing tradeoffs, and recommending a direction using explicit criteria. | [`evals/`](choose/evals/) | +| [`classify`](classify/SKILL.md) | Organizing material into meaningful groups by criteria, similarity, priority, dependency, or abstraction level. | [`evals/`](classify/evals/) | +| [`code-backend`](code-backend/SKILL.md) | Production backend code: APIs, services, middleware, workers, persistence, validation, auth, and backend tests. | [`references/`](code-backend/references/), [`evals/`](code-backend/evals/) | +| [`code-database`](code-database/SKILL.md) | Database code: schemas, DDL, OLTP SQL, analytics SQL, migrations, indexes, stored procedures, and dialect-specific scripts. | [`references/`](code-database/references/), [`evals/`](code-database/evals/) | +| [`code-frontend`](code-frontend/SKILL.md) | Production frontend code: components, routes, client state, forms, styling, accessibility, performance, PWA behavior, and visualization. | [`references/`](code-frontend/references/), [`evals/`](code-frontend/evals/) | +| [`code-tests`](code-tests/SKILL.md) | Automated tests and evals, including E2E, API, integration, performance, AI output, tool-use, RAG, and prompt regression suites. | [`references/`](code-tests/references/), [`scripts/`](code-tests/scripts/), [`evals/`](code-tests/evals/) | | [`create-rule`](create-rule/SKILL.md) | Writing or improving agent rules, instruction files, `AGENTS.md`, `CLAUDE.md`, Cursor rules, Copilot instructions, and `.agents/rules/*.md`. | [`scripts/`](create-rule/scripts/), [`evals/`](create-rule/evals/) | | [`create-skill`](create-skill/SKILL.md) | Creating, editing, reviewing, evaluating, packaging, optimizing, or improving skills. Start here for skill authoring. | [`references/`](create-skill/references/), [`scripts/`](create-skill/scripts/), [`eval-viewer/`](create-skill/eval-viewer/), [`agents/`](create-skill/agents/), [`assets/`](create-skill/assets/), [`evals/`](create-skill/evals/) | -| [`decide-direction`](decide-direction/SKILL.md) | Comparing options, weighing tradeoffs, and recommending a direction using explicit criteria. | [`evals/`](decide-direction/evals/) | | [`design-api`](design-api/SKILL.md) | Contract-first API design for OpenAPI, AsyncAPI, GraphQL, endpoints, schemas, and request/response shapes. | [`references/`](design-api/references/), [`evals/`](design-api/evals/) | -| [`explain-topic`](explain-topic/SKILL.md) | Explaining general knowledge, concepts, code, behavior, design, architecture, APIs, data flow, and tradeoffs in simple terms. | [`evals/`](explain-topic/evals/) | -| [`explore-context`](explore-context/SKILL.md) | Investigating local repository, project document, and attached-artifact context with evidence. | [`evals/`](explore-context/evals/) | +| [`explain`](explain/SKILL.md) | Explaining general knowledge, concepts, code, behavior, design, architecture, APIs, data flow, and tradeoffs in simple terms. | [`evals/`](explain/evals/) | +| [`explore`](explore/SKILL.md) | Investigating local repository, project document, and attached-artifact context with evidence. | [`evals/`](explore/evals/) | +| [`manage`](manage/SKILL.md) | Managing active work across people, agents, tasks, dependencies, blockers, status, and handoffs. | [`evals/`](manage/evals/) | | [`manage-git`](manage-git/SKILL.md) | Git branch naming, branch actions, commit-message drafting, and committing staged changes. | [`references/`](manage-git/references/), [`evals/`](manage-git/evals/) | -| [`plan-work`](plan-work/SKILL.md) | Sequencing work before execution with phases, dependencies, risks, validation, and next actions. | [`evals/`](plan-work/evals/) | -| [`reason-problem`](reason-problem/SKILL.md) | Working through ambiguous problems, assumptions, hypotheses, and problem framing before deciding or planning. | [`evals/`](reason-problem/evals/) | -| [`remember-context`](remember-context/SKILL.md) | Preserving durable project facts, decisions, conventions, and useful observations in `.agents/memory/`. | [`evals/`](remember-context/evals/) | +| [`plan`](plan/SKILL.md) | Sequencing work before execution with phases, dependencies, risks, validation, and next actions. | [`evals/`](plan/evals/) | +| [`remember`](remember/SKILL.md) | Preserving durable project facts, decisions, conventions, and useful observations in `.agents/memory/`. | [`evals/`](remember/evals/) | | [`review-code`](review-code/SKILL.md) | Reviewing code changes, diffs, pull requests, branches, or patches for correctness, regressions, security, performance, and test gaps. | [`references/`](review-code/references/), [`evals/`](review-code/evals/) | | [`write-prd`](write-prd/SKILL.md) | Product requirements, product briefs, feature requirements, product scope, and launch requirements. | [`references/`](write-prd/references/), [`evals/`](write-prd/evals/) | | [`write-spec`](write-spec/SKILL.md) | Technical specs, design docs, functional and non-functional requirements, data contracts, UI specs, release specs, and handoff docs. | [`references/`](write-spec/references/), [`evals/`](write-spec/evals/) | @@ -49,13 +49,13 @@ Use [`create-skill`](create-skill/SKILL.md) to create, revise, package, or evalu ```bash cd .agents/skills/create-skill -python3 -m scripts.package_skill ../build-database /tmp/skills-dist +python3 -m scripts.package_skill ../code-database /tmp/skills-dist ``` Use this validation command when changing an existing skill: ```bash -python3 .agents/skills/create-skill/scripts/quick_validate.py .agents/skills/build-database +python3 .agents/skills/create-skill/scripts/quick_validate.py .agents/skills/code-database ``` The key rule is simple: keep `SKILL.md` and any files it references together. If a skill says to read `references/postgres.md`, that file must remain available relative to the skill folder. Tiny rule, large consequences. Filesystems enjoy pettiness. diff --git a/.agents/skills/adapt/SKILL.md b/.agents/skills/adapt/SKILL.md index 3ebdfc4..70165cf 100644 --- a/.agents/skills/adapt/SKILL.md +++ b/.agents/skills/adapt/SKILL.md @@ -15,7 +15,7 @@ metadata: references: - create-skill - create-rule - - remember-context + - remember --- # adapt diff --git a/.agents/skills/adapt/evals/evals.json b/.agents/skills/adapt/evals/evals.json index 4e18987..e69b93f 100644 --- a/.agents/skills/adapt/evals/evals.json +++ b/.agents/skills/adapt/evals/evals.json @@ -66,7 +66,7 @@ { "id": "adapt-010", "category": "true-positive", - "prompt": "The eval caught a false positive trigger for plan-work. What should we adjust?", + "prompt": "The eval caught a false positive trigger for plan. What should we adjust?", "expected_trigger": "Trigger adapt.", "expected_output": "Identifies a trigger-boundary problem, targets the affected skill description or evals, and proposes a focused trigger or non-trigger update." }, diff --git a/.agents/skills/ask-questions/SKILL.md b/.agents/skills/ask/SKILL.md similarity index 97% rename from .agents/skills/ask-questions/SKILL.md rename to .agents/skills/ask/SKILL.md index 6740ae5..0b266be 100644 --- a/.agents/skills/ask-questions/SKILL.md +++ b/.agents/skills/ask/SKILL.md @@ -1,5 +1,5 @@ --- -name: ask-questions +name: ask description: Generate high-leverage questions and clarify missing context. Use for question-generation requests like "what should I ask", "right questions", "what are we missing", "clarify this", and ambiguous requests blocked by unknowns. license: MIT tags: @@ -8,13 +8,13 @@ tags: - questions metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: collaboration --- -# ask-questions +# ask Generate the smallest useful set of questions that would change the next action. diff --git a/.agents/skills/ask-questions/evals/evals.json b/.agents/skills/ask/evals/evals.json similarity index 72% rename from .agents/skills/ask-questions/evals/evals.json rename to .agents/skills/ask/evals/evals.json index 1674135..972fb97 100644 --- a/.agents/skills/ask-questions/evals/evals.json +++ b/.agents/skills/ask/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "ask-questions-001", + "id": "ask-001", "category": "true-positive", "prompt": "What should I ask the team before we commit to this migration approach?", - "expected_trigger": "Trigger ask-questions.", + "expected_trigger": "Trigger ask.", "expected_output": "Produces a short prioritized set of migration questions, with blockers separated from nice-to-have context." }, { - "id": "ask-questions-002", + "id": "ask-002", "category": "true-positive", "prompt": "Clarify this feature request and tell me what context is missing.", - "expected_trigger": "Trigger ask-questions.", + "expected_trigger": "Trigger ask.", "expected_output": "Identifies missing goals, users, scope, acceptance criteria, and assumptions without planning implementation." }, { - "id": "ask-questions-003", + "id": "ask-003", "category": "true-positive", "prompt": "What are the right questions to ask before choosing a vendor?", - "expected_trigger": "Trigger ask-questions.", + "expected_trigger": "Trigger ask.", "expected_output": "Returns high-leverage vendor selection questions ordered by decision impact." }, { - "id": "ask-questions-004", + "id": "ask-004", "category": "true-positive", "prompt": "We have an ambiguous request to improve onboarding. What are we missing?", - "expected_trigger": "Trigger ask-questions.", + "expected_trigger": "Trigger ask.", "expected_output": "Surfaces missing user, workflow, metric, constraint, and success-context questions." }, { - "id": "ask-questions-005", + "id": "ask-005", "category": "false-positive", "prompt": "Decide whether we should build or buy the onboarding tool.", - "expected_trigger": "Do not trigger ask-questions as the primary skill.", + "expected_trigger": "Do not trigger ask as the primary skill.", "expected_output": "Should compare options and recommend a direction rather than only generating questions." }, { - "id": "ask-questions-006", + "id": "ask-006", "category": "false-positive", "prompt": "Plan the onboarding migration in milestones.", - "expected_trigger": "Do not trigger ask-questions as the primary skill.", + "expected_trigger": "Do not trigger ask as the primary skill.", "expected_output": "Should sequence work and include risks or verification; questions may appear only as blockers." }, { - "id": "ask-questions-007", + "id": "ask-007", "category": "non-trigger", "prompt": "Explain how OAuth refresh tokens work.", - "expected_trigger": "Do not trigger ask-questions.", + "expected_trigger": "Do not trigger ask.", "expected_output": "Should explain the concept, not generate a discovery questionnaire." }, { - "id": "ask-questions-008", + "id": "ask-008", "category": "non-trigger", "prompt": "Update the README to document the install command.", - "expected_trigger": "Do not trigger ask-questions.", + "expected_trigger": "Do not trigger ask.", "expected_output": "Should perform documentation work unless clarification is truly blocking." } ] diff --git a/.agents/skills/reason-problem/SKILL.md b/.agents/skills/brainstorm/SKILL.md similarity index 97% rename from .agents/skills/reason-problem/SKILL.md rename to .agents/skills/brainstorm/SKILL.md index 8b5da77..2027b69 100644 --- a/.agents/skills/reason-problem/SKILL.md +++ b/.agents/skills/brainstorm/SKILL.md @@ -1,5 +1,5 @@ --- -name: reason-problem +name: brainstorm description: Work through ambiguous problems before a firm output shape is warranted. Use for reasoning requests like "reason through", "think through", "brainstorm", "help me frame this", "let's work through this", and messy problem statements. license: MIT tags: @@ -8,13 +8,13 @@ tags: - thinking metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: productivity --- -# reason-problem +# brainstorm Clarify messy problems without forcing a premature answer. diff --git a/.agents/skills/reason-problem/evals/evals.json b/.agents/skills/brainstorm/evals/evals.json similarity index 71% rename from .agents/skills/reason-problem/evals/evals.json rename to .agents/skills/brainstorm/evals/evals.json index d2f84b1..b4b04e9 100644 --- a/.agents/skills/reason-problem/evals/evals.json +++ b/.agents/skills/brainstorm/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "reason-problem-001", + "id": "brainstorm-001", "category": "true-positive", "prompt": "Let's reason through why this workflow feels fragile before we change it.", - "expected_trigger": "Trigger reason-problem.", + "expected_trigger": "Trigger brainstorm.", "expected_output": "Frames the problem, separates facts from assumptions, names hypotheses, and ends with a clearer next clarity step." }, { - "id": "reason-problem-002", + "id": "brainstorm-002", "category": "true-positive", "prompt": "Help me think through whether this product idea is actually one problem or three.", - "expected_trigger": "Trigger reason-problem.", + "expected_trigger": "Trigger brainstorm.", "expected_output": "Explores interpretations, constraints, and possible framings without forcing an immediate recommendation." }, { - "id": "reason-problem-003", + "id": "brainstorm-003", "category": "true-positive", "prompt": "Brainstorm possible causes for the drop in activation, but keep uncertainty visible.", - "expected_trigger": "Trigger reason-problem.", + "expected_trigger": "Trigger brainstorm.", "expected_output": "Generates hypotheses, marks assumptions, and identifies evidence that would distinguish them." }, { - "id": "reason-problem-004", + "id": "brainstorm-004", "category": "true-positive", "prompt": "This architecture debate is messy. Help me frame the core tension.", - "expected_trigger": "Trigger reason-problem.", + "expected_trigger": "Trigger brainstorm.", "expected_output": "Clarifies competing goals and tradeoffs, then states a sharper problem framing." }, { - "id": "reason-problem-005", + "id": "brainstorm-005", "category": "false-positive", "prompt": "Choose the best database for this workload and recommend one.", - "expected_trigger": "Do not trigger reason-problem as the primary skill.", + "expected_trigger": "Do not trigger brainstorm as the primary skill.", "expected_output": "Should use decision criteria and produce a recommendation." }, { - "id": "reason-problem-006", + "id": "brainstorm-006", "category": "false-positive", "prompt": "Break this migration into phases with validation steps.", - "expected_trigger": "Do not trigger reason-problem as the primary skill.", + "expected_trigger": "Do not trigger brainstorm as the primary skill.", "expected_output": "Should produce a plan rather than an open-ended reasoning frame." }, { - "id": "reason-problem-007", + "id": "brainstorm-007", "category": "non-trigger", "prompt": "Classify these bugs by severity and affected component.", - "expected_trigger": "Do not trigger reason-problem.", + "expected_trigger": "Do not trigger brainstorm.", "expected_output": "Should group items by explicit criteria." }, { - "id": "reason-problem-008", + "id": "brainstorm-008", "category": "non-trigger", "prompt": "Remember that we chose SQLite for local development.", - "expected_trigger": "Do not trigger reason-problem.", + "expected_trigger": "Do not trigger brainstorm.", "expected_output": "Should write durable memory if appropriate." } ] diff --git a/.agents/skills/decide-direction/SKILL.md b/.agents/skills/choose/SKILL.md similarity index 97% rename from .agents/skills/decide-direction/SKILL.md rename to .agents/skills/choose/SKILL.md index a815566..b570dc2 100644 --- a/.agents/skills/decide-direction/SKILL.md +++ b/.agents/skills/choose/SKILL.md @@ -1,5 +1,5 @@ --- -name: decide-direction +name: choose description: Compare options and recommend a direction. Use for decision requests like "choose", "which option", "tradeoffs", "recommend", "should we", and option selection with criteria, risks, and reversibility. license: MIT tags: @@ -8,13 +8,13 @@ tags: - tradeoffs metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: project-management --- -# decide-direction +# choose Choose a direction by comparing viable options against explicit criteria. diff --git a/.agents/skills/decide-direction/evals/evals.json b/.agents/skills/choose/evals/evals.json similarity index 69% rename from .agents/skills/decide-direction/evals/evals.json rename to .agents/skills/choose/evals/evals.json index 88ecdf4..cbd2a81 100644 --- a/.agents/skills/decide-direction/evals/evals.json +++ b/.agents/skills/choose/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "decide-direction-001", + "id": "choose-001", "category": "true-positive", "prompt": "Decide whether we should build this as a plugin or a skill.", - "expected_trigger": "Trigger decide-direction.", + "expected_trigger": "Trigger choose.", "expected_output": "States criteria, compares plugin versus skill, recommends one, and notes tradeoffs." }, { - "id": "decide-direction-002", + "id": "choose-002", "category": "true-positive", "prompt": "Which option should we choose for the cache: Redis, Postgres, or in-memory?", - "expected_trigger": "Trigger decide-direction.", + "expected_trigger": "Trigger choose.", "expected_output": "Compares viable options against criteria and recommends a direction or tie-breaker." }, { - "id": "decide-direction-003", + "id": "choose-003", "category": "true-positive", "prompt": "Recommend whether we should ship this now or wait for the analytics work.", - "expected_trigger": "Trigger decide-direction.", + "expected_trigger": "Trigger choose.", "expected_output": "Evaluates timing tradeoffs, risks, assumptions, and reversibility before recommending." }, { - "id": "decide-direction-004", + "id": "choose-004", "category": "true-positive", "prompt": "Should we optimize for implementation speed or long-term extensibility here?", - "expected_trigger": "Trigger decide-direction.", + "expected_trigger": "Trigger choose.", "expected_output": "Defines decision criteria and recommends based on the stated context." }, { - "id": "decide-direction-005", + "id": "choose-005", "category": "false-positive", "prompt": "Classify these options by risk level without recommending one.", - "expected_trigger": "Do not trigger decide-direction as the primary skill.", + "expected_trigger": "Do not trigger choose as the primary skill.", "expected_output": "Should organize options by risk category without forcing a recommendation." }, { - "id": "decide-direction-006", + "id": "choose-006", "category": "false-positive", "prompt": "Think through what might be causing users to abandon setup.", - "expected_trigger": "Do not trigger decide-direction as the primary skill.", + "expected_trigger": "Do not trigger choose as the primary skill.", "expected_output": "Should reason through hypotheses and uncertainty rather than choose an option." }, { - "id": "decide-direction-007", + "id": "choose-007", "category": "non-trigger", "prompt": "Find where setup completion is tracked in the repo.", - "expected_trigger": "Do not trigger decide-direction.", + "expected_trigger": "Do not trigger choose.", "expected_output": "Should inspect local files and cite evidence." }, { - "id": "decide-direction-008", + "id": "choose-008", "category": "non-trigger", "prompt": "Write a user story for password reset.", - "expected_trigger": "Do not trigger decide-direction.", + "expected_trigger": "Do not trigger choose.", "expected_output": "Should produce a user story, not a recommendation." } ] diff --git a/.agents/skills/classify-content/SKILL.md b/.agents/skills/classify/SKILL.md similarity index 97% rename from .agents/skills/classify-content/SKILL.md rename to .agents/skills/classify/SKILL.md index d98f274..7ff21d9 100644 --- a/.agents/skills/classify-content/SKILL.md +++ b/.agents/skills/classify/SKILL.md @@ -1,5 +1,5 @@ --- -name: classify-content +name: classify description: Organize material into meaningful groups. Use for classification requests like "categorize", "group", "cluster", "sort", "taxonomy", "organize these", and grouping by criteria, priority, dependency, similarity, or abstraction level. license: MIT tags: @@ -8,13 +8,13 @@ tags: - organization metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: data --- -# classify-content +# classify Group material by explicit criteria while preserving edge cases. diff --git a/.agents/skills/classify-content/evals/evals.json b/.agents/skills/classify/evals/evals.json similarity index 68% rename from .agents/skills/classify-content/evals/evals.json rename to .agents/skills/classify/evals/evals.json index 2d189ac..7f31946 100644 --- a/.agents/skills/classify-content/evals/evals.json +++ b/.agents/skills/classify/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "classify-content-001", + "id": "classify-001", "category": "true-positive", "prompt": "Classify these feature requests by underlying user need.", - "expected_trigger": "Trigger classify-content.", + "expected_trigger": "Trigger classify.", "expected_output": "States grouping criteria, labels groups, assigns requests, and flags ambiguous items." }, { - "id": "classify-content-002", + "id": "classify-002", "category": "true-positive", "prompt": "Group these incidents by root cause pattern and note any multi-fit cases.", - "expected_trigger": "Trigger classify-content.", + "expected_trigger": "Trigger classify.", "expected_output": "Groups incidents by root cause pattern and preserves incidents that belong to multiple groups." }, { - "id": "classify-content-003", + "id": "classify-003", "category": "true-positive", "prompt": "Build a taxonomy for these support tickets.", - "expected_trigger": "Trigger classify-content.", + "expected_trigger": "Trigger classify.", "expected_output": "Creates clear category labels and places tickets into the taxonomy." }, { - "id": "classify-content-004", + "id": "classify-004", "category": "true-positive", "prompt": "Sort these tasks by dependency and priority.", - "expected_trigger": "Trigger classify-content.", + "expected_trigger": "Trigger classify.", "expected_output": "Defines dependency and priority criteria, then organizes tasks accordingly." }, { - "id": "classify-content-005", + "id": "classify-005", "category": "false-positive", "prompt": "Decide which of these three projects we should fund first.", - "expected_trigger": "Do not trigger classify-content as the primary skill.", + "expected_trigger": "Do not trigger classify as the primary skill.", "expected_output": "Should compare options and recommend a project using decision criteria." }, { - "id": "classify-content-006", + "id": "classify-006", "category": "false-positive", "prompt": "Plan the order for implementing these tasks.", - "expected_trigger": "Do not trigger classify-content as the primary skill.", + "expected_trigger": "Do not trigger classify as the primary skill.", "expected_output": "Should produce an execution sequence, not just grouped categories." }, { - "id": "classify-content-007", + "id": "classify-007", "category": "non-trigger", "prompt": "Explain why the cache is invalidated on write.", - "expected_trigger": "Do not trigger classify-content.", + "expected_trigger": "Do not trigger classify.", "expected_output": "Should explain behavior." }, { - "id": "classify-content-008", + "id": "classify-008", "category": "non-trigger", "prompt": "Investigate where the billing webhook is handled.", - "expected_trigger": "Do not trigger classify-content.", + "expected_trigger": "Do not trigger classify.", "expected_output": "Should inspect local context and cite files." } ] diff --git a/.agents/skills/build-backend/SKILL.md b/.agents/skills/code-backend/SKILL.md similarity index 99% rename from .agents/skills/build-backend/SKILL.md rename to .agents/skills/code-backend/SKILL.md index 9fcbf76..ef69764 100644 --- a/.agents/skills/build-backend/SKILL.md +++ b/.agents/skills/code-backend/SKILL.md @@ -1,5 +1,5 @@ --- -name: build-backend +name: code-backend description: Build or modify backend implementation. Use for API routes, services, middleware, workers, persistence, validation, authorization, configuration, observability, and backend behavior tests. license: MIT tags: @@ -8,13 +8,13 @@ tags: - engineering metadata: author: Oleg Shulyakov - version: "1.1.1" + version: "1.1.2" source: github.com/olegshulyakov/agent.md catalog: software-team-roles category: development --- -# build-backend +# code-backend Implement backend code for APIs, services, workers, persistence, middleware, validation, authorization, configuration, observability, and behavior tests. Use this as a router: identify the backend language from the request and repository, read exactly one language reference, and read at most one framework reference when the framework signal is explicit or unambiguous. diff --git a/.agents/skills/build-backend/evals/evals.json b/.agents/skills/code-backend/evals/evals.json similarity index 99% rename from .agents/skills/build-backend/evals/evals.json rename to .agents/skills/code-backend/evals/evals.json index 8b95d37..8a5997f 100644 --- a/.agents/skills/build-backend/evals/evals.json +++ b/.agents/skills/code-backend/evals/evals.json @@ -1,5 +1,5 @@ { - "skill_name": "build-backend", + "skill_name": "code-backend", "evals": [ { "id": 1, diff --git a/.agents/skills/build-backend/references/ada.md b/.agents/skills/code-backend/references/ada.md similarity index 100% rename from .agents/skills/build-backend/references/ada.md rename to .agents/skills/code-backend/references/ada.md diff --git a/.agents/skills/build-backend/references/c.md b/.agents/skills/code-backend/references/c.md similarity index 100% rename from .agents/skills/build-backend/references/c.md rename to .agents/skills/code-backend/references/c.md diff --git a/.agents/skills/build-backend/references/cpp.md b/.agents/skills/code-backend/references/cpp.md similarity index 100% rename from .agents/skills/build-backend/references/cpp.md rename to .agents/skills/code-backend/references/cpp.md diff --git a/.agents/skills/build-backend/references/csharp-aspnet-core.md b/.agents/skills/code-backend/references/csharp-aspnet-core.md similarity index 100% rename from .agents/skills/build-backend/references/csharp-aspnet-core.md rename to .agents/skills/code-backend/references/csharp-aspnet-core.md diff --git a/.agents/skills/build-backend/references/csharp.md b/.agents/skills/code-backend/references/csharp.md similarity index 100% rename from .agents/skills/build-backend/references/csharp.md rename to .agents/skills/code-backend/references/csharp.md diff --git a/.agents/skills/build-backend/references/delphi.md b/.agents/skills/code-backend/references/delphi.md similarity index 100% rename from .agents/skills/build-backend/references/delphi.md rename to .agents/skills/code-backend/references/delphi.md diff --git a/.agents/skills/build-backend/references/elixir-phoenix.md b/.agents/skills/code-backend/references/elixir-phoenix.md similarity index 100% rename from .agents/skills/build-backend/references/elixir-phoenix.md rename to .agents/skills/code-backend/references/elixir-phoenix.md diff --git a/.agents/skills/build-backend/references/elixir.md b/.agents/skills/code-backend/references/elixir.md similarity index 100% rename from .agents/skills/build-backend/references/elixir.md rename to .agents/skills/code-backend/references/elixir.md diff --git a/.agents/skills/build-backend/references/fortran.md b/.agents/skills/code-backend/references/fortran.md similarity index 100% rename from .agents/skills/build-backend/references/fortran.md rename to .agents/skills/code-backend/references/fortran.md diff --git a/.agents/skills/build-backend/references/go-chi.md b/.agents/skills/code-backend/references/go-chi.md similarity index 100% rename from .agents/skills/build-backend/references/go-chi.md rename to .agents/skills/code-backend/references/go-chi.md diff --git a/.agents/skills/build-backend/references/go-echo.md b/.agents/skills/code-backend/references/go-echo.md similarity index 100% rename from .agents/skills/build-backend/references/go-echo.md rename to .agents/skills/code-backend/references/go-echo.md diff --git a/.agents/skills/build-backend/references/go-fiber.md b/.agents/skills/code-backend/references/go-fiber.md similarity index 100% rename from .agents/skills/build-backend/references/go-fiber.md rename to .agents/skills/code-backend/references/go-fiber.md diff --git a/.agents/skills/build-backend/references/go-gin.md b/.agents/skills/code-backend/references/go-gin.md similarity index 100% rename from .agents/skills/build-backend/references/go-gin.md rename to .agents/skills/code-backend/references/go-gin.md diff --git a/.agents/skills/build-backend/references/go.md b/.agents/skills/code-backend/references/go.md similarity index 100% rename from .agents/skills/build-backend/references/go.md rename to .agents/skills/code-backend/references/go.md diff --git a/.agents/skills/build-backend/references/java-micronaut.md b/.agents/skills/code-backend/references/java-micronaut.md similarity index 100% rename from .agents/skills/build-backend/references/java-micronaut.md rename to .agents/skills/code-backend/references/java-micronaut.md diff --git a/.agents/skills/build-backend/references/java-quarkus.md b/.agents/skills/code-backend/references/java-quarkus.md similarity index 100% rename from .agents/skills/build-backend/references/java-quarkus.md rename to .agents/skills/code-backend/references/java-quarkus.md diff --git a/.agents/skills/build-backend/references/java-spring-boot.md b/.agents/skills/code-backend/references/java-spring-boot.md similarity index 100% rename from .agents/skills/build-backend/references/java-spring-boot.md rename to .agents/skills/code-backend/references/java-spring-boot.md diff --git a/.agents/skills/build-backend/references/java.md b/.agents/skills/code-backend/references/java.md similarity index 100% rename from .agents/skills/build-backend/references/java.md rename to .agents/skills/code-backend/references/java.md diff --git a/.agents/skills/build-backend/references/kotlin-ktor.md b/.agents/skills/code-backend/references/kotlin-ktor.md similarity index 100% rename from .agents/skills/build-backend/references/kotlin-ktor.md rename to .agents/skills/code-backend/references/kotlin-ktor.md diff --git a/.agents/skills/build-backend/references/kotlin.md b/.agents/skills/code-backend/references/kotlin.md similarity index 100% rename from .agents/skills/build-backend/references/kotlin.md rename to .agents/skills/code-backend/references/kotlin.md diff --git a/.agents/skills/build-backend/references/matlab.md b/.agents/skills/code-backend/references/matlab.md similarity index 100% rename from .agents/skills/build-backend/references/matlab.md rename to .agents/skills/code-backend/references/matlab.md diff --git a/.agents/skills/build-backend/references/nodejs-express.md b/.agents/skills/code-backend/references/nodejs-express.md similarity index 100% rename from .agents/skills/build-backend/references/nodejs-express.md rename to .agents/skills/code-backend/references/nodejs-express.md diff --git a/.agents/skills/build-backend/references/nodejs-fastify.md b/.agents/skills/code-backend/references/nodejs-fastify.md similarity index 100% rename from .agents/skills/build-backend/references/nodejs-fastify.md rename to .agents/skills/code-backend/references/nodejs-fastify.md diff --git a/.agents/skills/build-backend/references/nodejs-hono.md b/.agents/skills/code-backend/references/nodejs-hono.md similarity index 100% rename from .agents/skills/build-backend/references/nodejs-hono.md rename to .agents/skills/code-backend/references/nodejs-hono.md diff --git a/.agents/skills/build-backend/references/nodejs-nestjs.md b/.agents/skills/code-backend/references/nodejs-nestjs.md similarity index 100% rename from .agents/skills/build-backend/references/nodejs-nestjs.md rename to .agents/skills/code-backend/references/nodejs-nestjs.md diff --git a/.agents/skills/build-backend/references/nodejs-nitro.md b/.agents/skills/code-backend/references/nodejs-nitro.md similarity index 100% rename from .agents/skills/build-backend/references/nodejs-nitro.md rename to .agents/skills/code-backend/references/nodejs-nitro.md diff --git a/.agents/skills/build-backend/references/nodejs.md b/.agents/skills/code-backend/references/nodejs.md similarity index 100% rename from .agents/skills/build-backend/references/nodejs.md rename to .agents/skills/code-backend/references/nodejs.md diff --git a/.agents/skills/build-backend/references/perl.md b/.agents/skills/code-backend/references/perl.md similarity index 100% rename from .agents/skills/build-backend/references/perl.md rename to .agents/skills/code-backend/references/perl.md diff --git a/.agents/skills/build-backend/references/php-laravel.md b/.agents/skills/code-backend/references/php-laravel.md similarity index 100% rename from .agents/skills/build-backend/references/php-laravel.md rename to .agents/skills/code-backend/references/php-laravel.md diff --git a/.agents/skills/build-backend/references/php-symfony.md b/.agents/skills/code-backend/references/php-symfony.md similarity index 100% rename from .agents/skills/build-backend/references/php-symfony.md rename to .agents/skills/code-backend/references/php-symfony.md diff --git a/.agents/skills/build-backend/references/php.md b/.agents/skills/code-backend/references/php.md similarity index 100% rename from .agents/skills/build-backend/references/php.md rename to .agents/skills/code-backend/references/php.md diff --git a/.agents/skills/build-backend/references/python-django.md b/.agents/skills/code-backend/references/python-django.md similarity index 100% rename from .agents/skills/build-backend/references/python-django.md rename to .agents/skills/code-backend/references/python-django.md diff --git a/.agents/skills/build-backend/references/python-fastapi.md b/.agents/skills/code-backend/references/python-fastapi.md similarity index 100% rename from .agents/skills/build-backend/references/python-fastapi.md rename to .agents/skills/code-backend/references/python-fastapi.md diff --git a/.agents/skills/build-backend/references/python-flask.md b/.agents/skills/code-backend/references/python-flask.md similarity index 100% rename from .agents/skills/build-backend/references/python-flask.md rename to .agents/skills/code-backend/references/python-flask.md diff --git a/.agents/skills/build-backend/references/python.md b/.agents/skills/code-backend/references/python.md similarity index 100% rename from .agents/skills/build-backend/references/python.md rename to .agents/skills/code-backend/references/python.md diff --git a/.agents/skills/build-backend/references/r.md b/.agents/skills/code-backend/references/r.md similarity index 100% rename from .agents/skills/build-backend/references/r.md rename to .agents/skills/code-backend/references/r.md diff --git a/.agents/skills/build-backend/references/ruby-rails.md b/.agents/skills/code-backend/references/ruby-rails.md similarity index 100% rename from .agents/skills/build-backend/references/ruby-rails.md rename to .agents/skills/code-backend/references/ruby-rails.md diff --git a/.agents/skills/build-backend/references/ruby-sinatra.md b/.agents/skills/code-backend/references/ruby-sinatra.md similarity index 100% rename from .agents/skills/build-backend/references/ruby-sinatra.md rename to .agents/skills/code-backend/references/ruby-sinatra.md diff --git a/.agents/skills/build-backend/references/ruby.md b/.agents/skills/code-backend/references/ruby.md similarity index 100% rename from .agents/skills/build-backend/references/ruby.md rename to .agents/skills/code-backend/references/ruby.md diff --git a/.agents/skills/build-backend/references/rust-actix-web.md b/.agents/skills/code-backend/references/rust-actix-web.md similarity index 100% rename from .agents/skills/build-backend/references/rust-actix-web.md rename to .agents/skills/code-backend/references/rust-actix-web.md diff --git a/.agents/skills/build-backend/references/rust-axum.md b/.agents/skills/code-backend/references/rust-axum.md similarity index 100% rename from .agents/skills/build-backend/references/rust-axum.md rename to .agents/skills/code-backend/references/rust-axum.md diff --git a/.agents/skills/build-backend/references/rust-rocket.md b/.agents/skills/code-backend/references/rust-rocket.md similarity index 100% rename from .agents/skills/build-backend/references/rust-rocket.md rename to .agents/skills/code-backend/references/rust-rocket.md diff --git a/.agents/skills/build-backend/references/rust.md b/.agents/skills/code-backend/references/rust.md similarity index 100% rename from .agents/skills/build-backend/references/rust.md rename to .agents/skills/code-backend/references/rust.md diff --git a/.agents/skills/build-backend/references/swift.md b/.agents/skills/code-backend/references/swift.md similarity index 100% rename from .agents/skills/build-backend/references/swift.md rename to .agents/skills/code-backend/references/swift.md diff --git a/.agents/skills/build-backend/references/visual-basic.md b/.agents/skills/code-backend/references/visual-basic.md similarity index 100% rename from .agents/skills/build-backend/references/visual-basic.md rename to .agents/skills/code-backend/references/visual-basic.md diff --git a/.agents/skills/build-database/SKILL.md b/.agents/skills/code-database/SKILL.md similarity index 98% rename from .agents/skills/build-database/SKILL.md rename to .agents/skills/code-database/SKILL.md index e674600..1f3daad 100644 --- a/.agents/skills/build-database/SKILL.md +++ b/.agents/skills/code-database/SKILL.md @@ -1,5 +1,5 @@ --- -name: build-database +name: code-database description: > Generate or modify database code: schemas, DDL, SQL queries, migrations, analytics SQL, indexes, stored procedures, and dialect-specific database scripts. @@ -10,15 +10,15 @@ tags: - data metadata: author: Oleg Shulyakov - version: "1.0.1" + version: "1.0.2" source: github.com/olegshulyakov/agent.md catalog: software-team-roles category: database references: - - classify-content + - classify --- -# build-database +# code-database Generate production-ready database code for schemas, DDL, OLTP queries, analytics SQL, migrations, indexes, stored procedures, and dialect-specific scripts. Use this as a router: classify the database artifact first, detect the dialect from context or repository evidence, then read only the relevant references. diff --git a/.agents/skills/build-database/evals/evals.json b/.agents/skills/code-database/evals/evals.json similarity index 99% rename from .agents/skills/build-database/evals/evals.json rename to .agents/skills/code-database/evals/evals.json index 9380bc4..50fdf7b 100644 --- a/.agents/skills/build-database/evals/evals.json +++ b/.agents/skills/code-database/evals/evals.json @@ -1,5 +1,5 @@ { - "skill_name": "build-database", + "skill_name": "code-database", "evals": [ { "id": 1, diff --git a/.agents/skills/build-database/references/analytics.md b/.agents/skills/code-database/references/analytics.md similarity index 100% rename from .agents/skills/build-database/references/analytics.md rename to .agents/skills/code-database/references/analytics.md diff --git a/.agents/skills/build-database/references/bigquery.md b/.agents/skills/code-database/references/bigquery.md similarity index 100% rename from .agents/skills/build-database/references/bigquery.md rename to .agents/skills/code-database/references/bigquery.md diff --git a/.agents/skills/build-database/references/clickhouse.md b/.agents/skills/code-database/references/clickhouse.md similarity index 100% rename from .agents/skills/build-database/references/clickhouse.md rename to .agents/skills/code-database/references/clickhouse.md diff --git a/.agents/skills/build-database/references/cockroachdb.md b/.agents/skills/code-database/references/cockroachdb.md similarity index 100% rename from .agents/skills/build-database/references/cockroachdb.md rename to .agents/skills/code-database/references/cockroachdb.md diff --git a/.agents/skills/build-database/references/common.md b/.agents/skills/code-database/references/common.md similarity index 100% rename from .agents/skills/build-database/references/common.md rename to .agents/skills/code-database/references/common.md diff --git a/.agents/skills/build-database/references/migration.md b/.agents/skills/code-database/references/migration.md similarity index 100% rename from .agents/skills/build-database/references/migration.md rename to .agents/skills/code-database/references/migration.md diff --git a/.agents/skills/build-database/references/mssql.md b/.agents/skills/code-database/references/mssql.md similarity index 100% rename from .agents/skills/build-database/references/mssql.md rename to .agents/skills/code-database/references/mssql.md diff --git a/.agents/skills/build-database/references/mysql.md b/.agents/skills/code-database/references/mysql.md similarity index 100% rename from .agents/skills/build-database/references/mysql.md rename to .agents/skills/code-database/references/mysql.md diff --git a/.agents/skills/build-database/references/oracle.md b/.agents/skills/code-database/references/oracle.md similarity index 100% rename from .agents/skills/build-database/references/oracle.md rename to .agents/skills/code-database/references/oracle.md diff --git a/.agents/skills/build-database/references/postgres.md b/.agents/skills/code-database/references/postgres.md similarity index 100% rename from .agents/skills/build-database/references/postgres.md rename to .agents/skills/code-database/references/postgres.md diff --git a/.agents/skills/build-database/references/schema-design.md b/.agents/skills/code-database/references/schema-design.md similarity index 100% rename from .agents/skills/build-database/references/schema-design.md rename to .agents/skills/code-database/references/schema-design.md diff --git a/.agents/skills/build-database/references/snowflake.md b/.agents/skills/code-database/references/snowflake.md similarity index 100% rename from .agents/skills/build-database/references/snowflake.md rename to .agents/skills/code-database/references/snowflake.md diff --git a/.agents/skills/build-database/references/sqlite.md b/.agents/skills/code-database/references/sqlite.md similarity index 100% rename from .agents/skills/build-database/references/sqlite.md rename to .agents/skills/code-database/references/sqlite.md diff --git a/.agents/skills/build-frontend/SKILL.md b/.agents/skills/code-frontend/SKILL.md similarity index 96% rename from .agents/skills/build-frontend/SKILL.md rename to .agents/skills/code-frontend/SKILL.md index c93edf3..0aab60c 100644 --- a/.agents/skills/build-frontend/SKILL.md +++ b/.agents/skills/code-frontend/SKILL.md @@ -1,5 +1,5 @@ --- -name: build-frontend +name: code-frontend description: Generate production-ready frontend code. Use for components, pages, routes, client state, forms, styling, accessibility, performance, PWA behavior, and data visualization. license: MIT tags: @@ -8,13 +8,13 @@ tags: - ui metadata: author: Oleg Shulyakov - version: "1.1.1" + version: "1.1.2" source: github.com/olegshulyakov/agent.md catalog: software-team-roles category: web-development --- -# build-frontend +# code-frontend Implement production frontend work by routing to the smallest relevant reference set, matching the repository's existing architecture, and verifying the user-facing behavior. @@ -25,7 +25,7 @@ Implement production frontend work by routing to the smallest relevant reference - **User signals:** Look for framework names, route or page names, component libraries, state libraries, CSS systems, test tools, file paths, file extensions, and requested user-facing behavior. - **Repository signals:** Inspect `package.json`, lockfiles, framework configs, `tsconfig.json`, source folders, imports, routing structure, design tokens, Storybook, test setup, and CI jobs before choosing an implementation path. - **Frontend scope:** Use this skill for components, pages, layouts, routes, loaders/actions, forms, stores, queries, charts, responsive styling, accessibility fixes, PWA behavior, and frontend performance work. -- **Route away:** Use `build-tests` for test-only work, `design-api` for API contract design, `build-backend` for backend implementation, and `write-spec` or a design skill for UI/UX specification when no code is requested. +- **Route away:** Use `code-tests` for test-only work, `design-api` for API contract design, `code-backend` for backend implementation, and `write-spec` or a design skill for UI/UX specification when no code is requested. - **Clarify rarely:** If the framework, styling system, or target surface remains genuinely ambiguous after inspection, ask one short question naming the likely options. --- diff --git a/.agents/skills/build-frontend/evals/evals.json b/.agents/skills/code-frontend/evals/evals.json similarity index 99% rename from .agents/skills/build-frontend/evals/evals.json rename to .agents/skills/code-frontend/evals/evals.json index 4e22e3a..f5c4a55 100644 --- a/.agents/skills/build-frontend/evals/evals.json +++ b/.agents/skills/code-frontend/evals/evals.json @@ -1,5 +1,5 @@ { - "skill_name": "build-frontend", + "skill_name": "code-frontend", "evals": [ { "id": 1, diff --git a/.agents/skills/build-frontend/references/accessibility.md b/.agents/skills/code-frontend/references/accessibility.md similarity index 100% rename from .agents/skills/build-frontend/references/accessibility.md rename to .agents/skills/code-frontend/references/accessibility.md diff --git a/.agents/skills/build-frontend/references/css-bootstrap.md b/.agents/skills/code-frontend/references/css-bootstrap.md similarity index 100% rename from .agents/skills/build-frontend/references/css-bootstrap.md rename to .agents/skills/code-frontend/references/css-bootstrap.md diff --git a/.agents/skills/build-frontend/references/css-component-libraries.md b/.agents/skills/code-frontend/references/css-component-libraries.md similarity index 100% rename from .agents/skills/build-frontend/references/css-component-libraries.md rename to .agents/skills/code-frontend/references/css-component-libraries.md diff --git a/.agents/skills/build-frontend/references/css-tailwind.md b/.agents/skills/code-frontend/references/css-tailwind.md similarity index 100% rename from .agents/skills/build-frontend/references/css-tailwind.md rename to .agents/skills/code-frontend/references/css-tailwind.md diff --git a/.agents/skills/build-frontend/references/css.md b/.agents/skills/code-frontend/references/css.md similarity index 100% rename from .agents/skills/build-frontend/references/css.md rename to .agents/skills/code-frontend/references/css.md diff --git a/.agents/skills/build-frontend/references/forms.md b/.agents/skills/code-frontend/references/forms.md similarity index 100% rename from .agents/skills/build-frontend/references/forms.md rename to .agents/skills/code-frontend/references/forms.md diff --git a/.agents/skills/build-frontend/references/html.md b/.agents/skills/code-frontend/references/html.md similarity index 100% rename from .agents/skills/build-frontend/references/html.md rename to .agents/skills/code-frontend/references/html.md diff --git a/.agents/skills/build-frontend/references/internationalization.md b/.agents/skills/code-frontend/references/internationalization.md similarity index 100% rename from .agents/skills/build-frontend/references/internationalization.md rename to .agents/skills/code-frontend/references/internationalization.md diff --git a/.agents/skills/build-frontend/references/javascript-angular.md b/.agents/skills/code-frontend/references/javascript-angular.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-angular.md rename to .agents/skills/code-frontend/references/javascript-angular.md diff --git a/.agents/skills/build-frontend/references/javascript-astro.md b/.agents/skills/code-frontend/references/javascript-astro.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-astro.md rename to .agents/skills/code-frontend/references/javascript-astro.md diff --git a/.agents/skills/build-frontend/references/javascript-react-nextjs.md b/.agents/skills/code-frontend/references/javascript-react-nextjs.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-react-nextjs.md rename to .agents/skills/code-frontend/references/javascript-react-nextjs.md diff --git a/.agents/skills/build-frontend/references/javascript-react-remix.md b/.agents/skills/code-frontend/references/javascript-react-remix.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-react-remix.md rename to .agents/skills/code-frontend/references/javascript-react-remix.md diff --git a/.agents/skills/build-frontend/references/javascript-react.md b/.agents/skills/code-frontend/references/javascript-react.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-react.md rename to .agents/skills/code-frontend/references/javascript-react.md diff --git a/.agents/skills/build-frontend/references/javascript-solidjs.md b/.agents/skills/code-frontend/references/javascript-solidjs.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-solidjs.md rename to .agents/skills/code-frontend/references/javascript-solidjs.md diff --git a/.agents/skills/build-frontend/references/javascript-svelte-sveltekit.md b/.agents/skills/code-frontend/references/javascript-svelte-sveltekit.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-svelte-sveltekit.md rename to .agents/skills/code-frontend/references/javascript-svelte-sveltekit.md diff --git a/.agents/skills/build-frontend/references/javascript-svelte.md b/.agents/skills/code-frontend/references/javascript-svelte.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-svelte.md rename to .agents/skills/code-frontend/references/javascript-svelte.md diff --git a/.agents/skills/build-frontend/references/javascript-vue-nuxt.md b/.agents/skills/code-frontend/references/javascript-vue-nuxt.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-vue-nuxt.md rename to .agents/skills/code-frontend/references/javascript-vue-nuxt.md diff --git a/.agents/skills/build-frontend/references/javascript-vue.md b/.agents/skills/code-frontend/references/javascript-vue.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript-vue.md rename to .agents/skills/code-frontend/references/javascript-vue.md diff --git a/.agents/skills/build-frontend/references/javascript.md b/.agents/skills/code-frontend/references/javascript.md similarity index 100% rename from .agents/skills/build-frontend/references/javascript.md rename to .agents/skills/code-frontend/references/javascript.md diff --git a/.agents/skills/build-frontend/references/performance.md b/.agents/skills/code-frontend/references/performance.md similarity index 100% rename from .agents/skills/build-frontend/references/performance.md rename to .agents/skills/code-frontend/references/performance.md diff --git a/.agents/skills/build-frontend/references/pwa.md b/.agents/skills/code-frontend/references/pwa.md similarity index 100% rename from .agents/skills/build-frontend/references/pwa.md rename to .agents/skills/code-frontend/references/pwa.md diff --git a/.agents/skills/build-frontend/references/state.md b/.agents/skills/code-frontend/references/state.md similarity index 100% rename from .agents/skills/build-frontend/references/state.md rename to .agents/skills/code-frontend/references/state.md diff --git a/.agents/skills/build-frontend/references/typescript.md b/.agents/skills/code-frontend/references/typescript.md similarity index 100% rename from .agents/skills/build-frontend/references/typescript.md rename to .agents/skills/code-frontend/references/typescript.md diff --git a/.agents/skills/build-frontend/references/visualization.md b/.agents/skills/code-frontend/references/visualization.md similarity index 100% rename from .agents/skills/build-frontend/references/visualization.md rename to .agents/skills/code-frontend/references/visualization.md diff --git a/.agents/skills/build-tests/SKILL.md b/.agents/skills/code-tests/SKILL.md similarity index 98% rename from .agents/skills/build-tests/SKILL.md rename to .agents/skills/code-tests/SKILL.md index cfe6925..f30ed5a 100644 --- a/.agents/skills/build-tests/SKILL.md +++ b/.agents/skills/code-tests/SKILL.md @@ -1,5 +1,5 @@ --- -name: build-tests +name: code-tests description: Generate or revise automated tests. Use for E2E/browser, API/contract, integration, and load/performance test requests. license: MIT tags: @@ -7,13 +7,13 @@ tags: - testing metadata: author: Oleg Shulyakov - version: "1.1.1" + version: "1.1.2" source: github.com/olegshulyakov/agent.md catalog: software-team-roles category: testing --- -# build-tests +# code-tests Generate production-ready test code. Classify the request, read the matching reference, inspect the repository, then implement runnable tests or provide complete files when direct edits are not safe. diff --git a/.agents/skills/build-tests/evals/evals.json b/.agents/skills/code-tests/evals/evals.json similarity index 98% rename from .agents/skills/build-tests/evals/evals.json rename to .agents/skills/code-tests/evals/evals.json index 20ad456..88f0382 100644 --- a/.agents/skills/build-tests/evals/evals.json +++ b/.agents/skills/code-tests/evals/evals.json @@ -1,5 +1,5 @@ { - "skill_name": "build-tests", + "skill_name": "code-tests", "evals": [ { "id": 1, diff --git a/.agents/skills/build-tests/references/api.md b/.agents/skills/code-tests/references/api.md similarity index 100% rename from .agents/skills/build-tests/references/api.md rename to .agents/skills/code-tests/references/api.md diff --git a/.agents/skills/build-tests/references/e2e.md b/.agents/skills/code-tests/references/e2e.md similarity index 100% rename from .agents/skills/build-tests/references/e2e.md rename to .agents/skills/code-tests/references/e2e.md diff --git a/.agents/skills/build-tests/references/perf.md b/.agents/skills/code-tests/references/perf.md similarity index 100% rename from .agents/skills/build-tests/references/perf.md rename to .agents/skills/code-tests/references/perf.md diff --git a/.agents/skills/build-tests/scripts/__init__.py b/.agents/skills/code-tests/scripts/__init__.py similarity index 100% rename from .agents/skills/build-tests/scripts/__init__.py rename to .agents/skills/code-tests/scripts/__init__.py diff --git a/.agents/skills/build-tests/scripts/agent_runner.py b/.agents/skills/code-tests/scripts/agent_runner.py similarity index 100% rename from .agents/skills/build-tests/scripts/agent_runner.py rename to .agents/skills/code-tests/scripts/agent_runner.py diff --git a/.agents/skills/build-tests/scripts/aggregate_benchmark.py b/.agents/skills/code-tests/scripts/aggregate_benchmark.py similarity index 100% rename from .agents/skills/build-tests/scripts/aggregate_benchmark.py rename to .agents/skills/code-tests/scripts/aggregate_benchmark.py diff --git a/.agents/skills/build-tests/scripts/generate_report.py b/.agents/skills/code-tests/scripts/generate_report.py similarity index 100% rename from .agents/skills/build-tests/scripts/generate_report.py rename to .agents/skills/code-tests/scripts/generate_report.py diff --git a/.agents/skills/build-tests/scripts/improve_description.py b/.agents/skills/code-tests/scripts/improve_description.py similarity index 100% rename from .agents/skills/build-tests/scripts/improve_description.py rename to .agents/skills/code-tests/scripts/improve_description.py diff --git a/.agents/skills/build-tests/scripts/run_eval.py b/.agents/skills/code-tests/scripts/run_eval.py similarity index 100% rename from .agents/skills/build-tests/scripts/run_eval.py rename to .agents/skills/code-tests/scripts/run_eval.py diff --git a/.agents/skills/build-tests/scripts/run_loop.py b/.agents/skills/code-tests/scripts/run_loop.py similarity index 100% rename from .agents/skills/build-tests/scripts/run_loop.py rename to .agents/skills/code-tests/scripts/run_loop.py diff --git a/.agents/skills/build-tests/scripts/utils.py b/.agents/skills/code-tests/scripts/utils.py similarity index 100% rename from .agents/skills/build-tests/scripts/utils.py rename to .agents/skills/code-tests/scripts/utils.py diff --git a/.agents/skills/build-tests/scripts/validate_evals.py b/.agents/skills/code-tests/scripts/validate_evals.py similarity index 96% rename from .agents/skills/build-tests/scripts/validate_evals.py rename to .agents/skills/code-tests/scripts/validate_evals.py index a9ee705..9535f92 100644 --- a/.agents/skills/build-tests/scripts/validate_evals.py +++ b/.agents/skills/code-tests/scripts/validate_evals.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Validate build-tests eval files.""" +"""Validate code-tests eval files.""" from __future__ import annotations @@ -36,8 +36,8 @@ def validate(path: Path) -> list[str]: if not isinstance(data, dict): return ["evals.json must contain a JSON object"] - if data.get("skill_name") != "build-tests": - errors.append("skill_name must be build-tests") + if data.get("skill_name") != "code-tests": + errors.append("skill_name must be code-tests") evals = data.get("evals") if not isinstance(evals, list) or not evals: diff --git a/.agents/skills/create-rule/scripts/grade_rule_output.py b/.agents/skills/create-rule/scripts/grade_rule_output.py index 9ea9884..60f80d1 100644 --- a/.agents/skills/create-rule/scripts/grade_rule_output.py +++ b/.agents/skills/create-rule/scripts/grade_rule_output.py @@ -25,7 +25,7 @@ ] IMPERATIVE_RE = re.compile( - r"\b(use|run|never|do not|don't|ask-questions|include|update|avoid|prefer|keep|" + r"\b(use|run|never|do not|don't|ask|include|update|avoid|prefer|keep|" r"write|add|check|verify|redact|report|call out|do)\b", re.IGNORECASE, ) diff --git a/.agents/skills/create-rule/scripts/run_trigger_eval.py b/.agents/skills/create-rule/scripts/run_trigger_eval.py index dc9d2d0..24f8d33 100644 --- a/.agents/skills/create-rule/scripts/run_trigger_eval.py +++ b/.agents/skills/create-rule/scripts/run_trigger_eval.py @@ -30,7 +30,7 @@ NEGATIVE_PATTERNS = [ r"\b(review this pull request|fix the failing|generate SQL|release notes|user story|technical spec)\b", - r"\b(explain-topic|summarize)\b.*\b(AGENTS\.md|README|coding standards)\b", + r"\b(explain|summarize)\b.*\b(AGENTS\.md|README|coding standards)\b", ] diff --git a/.agents/skills/explain-topic/SKILL.md b/.agents/skills/explain/SKILL.md similarity index 99% rename from .agents/skills/explain-topic/SKILL.md rename to .agents/skills/explain/SKILL.md index 5171d20..02ed42c 100644 --- a/.agents/skills/explain-topic/SKILL.md +++ b/.agents/skills/explain/SKILL.md @@ -1,5 +1,5 @@ --- -name: explain-topic +name: explain description: Explain any knowledge topic simply and accurately. Use for explanation requests like "explain X", "why/how/what is X?", concepts, science, definitions, code, design, architecture, and walkthroughs. license: MIT tags: @@ -8,13 +8,13 @@ tags: - reference metadata: author: Oleg Shulyakov - version: "2.1.2" + version: "2.1.3" source: github.com/olegshulyakov/agent.md catalog: utility category: education --- -# explain-topic +# explain Explain knowledge questions clearly, accurately, and at the right depth. Use simple language first, then add precision only where it helps the user understand. diff --git a/.agents/skills/explain-topic/evals/evals.json b/.agents/skills/explain/evals/evals.json similarity index 90% rename from .agents/skills/explain-topic/evals/evals.json rename to .agents/skills/explain/evals/evals.json index 8a226a1..9939557 100644 --- a/.agents/skills/explain-topic/evals/evals.json +++ b/.agents/skills/explain/evals/evals.json @@ -1,5 +1,5 @@ { - "skill_name": "explain-topic", + "skill_name": "explain", "evals": [ { "id": 1, @@ -9,7 +9,7 @@ "expected_output": "Explains Rayleigh scattering in simple terms, gives the short answer first, and avoids unnecessary technical depth.", "files": [], "expectations": [ - "Triggers the explain-topic skill for a general knowledge why question", + "Triggers the explain skill for a general knowledge why question", "Starts with a concise answer", "Explains sunlight scattering by air molecules", "Mentions shorter blue wavelengths scattering more than red wavelengths", @@ -24,7 +24,7 @@ "expected_output": "Defines planet clearly, gives the core criteria, and notes context where definitions vary.", "files": [], "expectations": [ - "Triggers the explain-topic skill for a definition question", + "Triggers the explain skill for a definition question", "Gives a plain-language definition first", "Explains orbiting a star and being rounded by gravity", "Mentions clearing the orbital neighborhood when using the IAU Solar System definition", @@ -39,7 +39,7 @@ "expected_output": "Explains both evolutionary reasons and the physical mechanism of flight in simple language.", "files": [], "expectations": [ - "Triggers the explain-topic skill for a general biology question", + "Triggers the explain skill for a general biology question", "Explains reasons such as food, escape, migration, and nesting", "Explains wings, lift, thrust, and lightweight bodies at a simple level", "Separates why birds evolved flight from how flight works", @@ -54,7 +54,7 @@ "expected_output": "Gives the exact vacuum speed of light and briefly explains why it matters.", "files": [], "expectations": [ - "Triggers the explain-topic skill for a factual knowledge question", + "Triggers the explain skill for a factual knowledge question", "States 299,792,458 meters per second in vacuum", "Mentions that light slows in materials", "Briefly explains its role as a fundamental speed limit", @@ -78,13 +78,13 @@ }, { "id": 6, - "query": "/explain-topic user signup", - "prompt": "/explain-topic user signup", + "query": "/explain user signup", + "prompt": "/explain user signup", "should_trigger": true, - "expected_output": "Treats /explain-topic as an explanation request, recognizes signup as a code walkthrough topic, traces the signup path, and explains how data moves through the system.", + "expected_output": "Treats /explain as an explanation request, recognizes signup as a code walkthrough topic, traces the signup path, and explains how data moves through the system.", "files": [], "expectations": [ - "Triggers the explain-topic skill from the /explain-topic phrasing", + "Triggers the explain skill from the /explain phrasing", "Starts from likely signup entry points", "Explains data flow from input through persistence or side effects", "Mentions tests or fixtures when found", @@ -200,10 +200,10 @@ "query": "Implement a new endpoint for exporting audit logs.", "prompt": "Implement a new endpoint for exporting audit logs.", "should_trigger": false, - "expected_output": "Does not route to explain-topic; treats the request as implementation work rather than an explanation or architecture critique.", + "expected_output": "Does not route to explain; treats the request as implementation work rather than an explanation or architecture critique.", "files": [], "expectations": [ - "Does not produce an explain-topic-style architecture walkthrough as the main output", + "Does not produce an explain-style architecture walkthrough as the main output", "Inspects implementation conventions before editing", "Routes to a code generation skill or normal implementation workflow", "Adds or updates code and tests when appropriate" diff --git a/.agents/skills/explore-context/SKILL.md b/.agents/skills/explore/SKILL.md similarity index 97% rename from .agents/skills/explore-context/SKILL.md rename to .agents/skills/explore/SKILL.md index e8e6def..a281297 100644 --- a/.agents/skills/explore-context/SKILL.md +++ b/.agents/skills/explore/SKILL.md @@ -1,5 +1,5 @@ --- -name: explore-context +name: explore description: Investigate local repository, document, and attached-artifact context. Use for local investigation requests like "investigate", "find where", "understand this repo", "trace", and local-context research; do not use for web search. license: MIT tags: @@ -8,13 +8,13 @@ tags: - local-context metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: research --- -# explore-context +# explore Investigate local context and report evidence-backed findings. diff --git a/.agents/skills/explore-context/evals/evals.json b/.agents/skills/explore/evals/evals.json similarity index 69% rename from .agents/skills/explore-context/evals/evals.json rename to .agents/skills/explore/evals/evals.json index cfb8f2b..437bdef 100644 --- a/.agents/skills/explore-context/evals/evals.json +++ b/.agents/skills/explore/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "explore-context-001", + "id": "explore-001", "category": "true-positive", "prompt": "Explore whether this repo already supports SSO.", - "expected_trigger": "Trigger explore-context.", + "expected_trigger": "Trigger explore.", "expected_output": "Searches local files and docs, reports findings with file references, and marks gaps." }, { - "id": "explore-context-002", + "id": "explore-002", "category": "true-positive", "prompt": "Investigate where the billing webhook is handled.", - "expected_trigger": "Trigger explore-context.", + "expected_trigger": "Trigger explore.", "expected_output": "Uses local search and traces relevant files or handlers with evidence." }, { - "id": "explore-context-003", + "id": "explore-003", "category": "true-positive", "prompt": "Find where we define the retry policy and how it is used.", - "expected_trigger": "Trigger explore-context.", + "expected_trigger": "Trigger explore.", "expected_output": "Finds definitions and call sites, distinguishes live behavior from references, and cites files." }, { - "id": "explore-context-004", + "id": "explore-004", "category": "true-positive", "prompt": "Trace the local code path for user deletion.", - "expected_trigger": "Trigger explore-context.", + "expected_trigger": "Trigger explore.", "expected_output": "Traces repository code paths with local evidence and uncertainty where needed." }, { - "id": "explore-context-005", + "id": "explore-005", "category": "false-positive", "prompt": "Search the web for the latest pricing of this API provider.", - "expected_trigger": "Do not trigger explore-context.", + "expected_trigger": "Do not trigger explore.", "expected_output": "Should use a web/current-information workflow, not local-only exploration." }, { - "id": "explore-context-006", + "id": "explore-006", "category": "false-positive", "prompt": "Explain how the retry policy works conceptually.", - "expected_trigger": "Do not trigger explore-context as the primary skill.", + "expected_trigger": "Do not trigger explore as the primary skill.", "expected_output": "Should explain the concept; local inspection is only needed if repo behavior is requested." }, { - "id": "explore-context-007", + "id": "explore-007", "category": "non-trigger", "prompt": "Plan a gradual rollout for SSO.", - "expected_trigger": "Do not trigger explore-context.", + "expected_trigger": "Do not trigger explore.", "expected_output": "Should produce phased planning guidance." }, { - "id": "explore-context-008", + "id": "explore-008", "category": "non-trigger", "prompt": "Decide whether SSO should be SAML or OIDC for our customers.", - "expected_trigger": "Do not trigger explore-context.", + "expected_trigger": "Do not trigger explore.", "expected_output": "Should compare options and recommend using criteria." } ] diff --git a/.agents/skills/coordinate-work/SKILL.md b/.agents/skills/manage/SKILL.md similarity index 96% rename from .agents/skills/coordinate-work/SKILL.md rename to .agents/skills/manage/SKILL.md index edbed01..dfe1008 100644 --- a/.agents/skills/coordinate-work/SKILL.md +++ b/.agents/skills/manage/SKILL.md @@ -1,20 +1,20 @@ --- -name: coordinate-work +name: manage description: Manage active work across people, agents, tasks, dependencies, blockers, and handoffs. Use for coordination requests like "manage this work", "lead this", "assign", "delegate", "track blockers", "status", "handoff", and multi-workstream execution. license: MIT tags: - - coordinate-work + - manage - execution - handoff metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: project-management --- -# coordinate-work +# manage Keep active work understandable across owners, dependencies, blockers, and handoffs. diff --git a/.agents/skills/coordinate-work/evals/evals.json b/.agents/skills/manage/evals/evals.json similarity index 69% rename from .agents/skills/coordinate-work/evals/evals.json rename to .agents/skills/manage/evals/evals.json index a6f071f..1d2ca49 100644 --- a/.agents/skills/coordinate-work/evals/evals.json +++ b/.agents/skills/manage/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "coordinate-work-001", + "id": "manage-001", "category": "true-positive", "prompt": "Coordinate this migration across frontend, backend, and QA.", - "expected_trigger": "Trigger coordinate-work.", + "expected_trigger": "Trigger manage.", "expected_output": "Creates an execution view with workstreams, owners or assumptions, dependencies, blockers, and next actions." }, { - "id": "coordinate-work-002", + "id": "manage-002", "category": "true-positive", "prompt": "Lead this work and keep track of blockers and handoffs.", - "expected_trigger": "Trigger coordinate-work.", + "expected_trigger": "Trigger manage.", "expected_output": "Tracks active status, blockers, handoff state, and next actions without inventing authority." }, { - "id": "coordinate-work-003", + "id": "manage-003", "category": "true-positive", "prompt": "Assign the three investigation tasks to the available agents and track progress.", - "expected_trigger": "Trigger coordinate-work.", + "expected_trigger": "Trigger manage.", "expected_output": "Separates tasks, owners, statuses, dependencies, blockers, and progress updates." }, { - "id": "coordinate-work-004", + "id": "manage-004", "category": "true-positive", "prompt": "Give me a status view for the active release workstreams.", - "expected_trigger": "Trigger coordinate-work.", + "expected_trigger": "Trigger manage.", "expected_output": "Summarizes current state by workstream with blockers and next steps." }, { - "id": "coordinate-work-005", + "id": "manage-005", "category": "false-positive", "prompt": "Plan the release from scratch before anyone starts working.", - "expected_trigger": "Do not trigger coordinate-work as the primary skill.", + "expected_trigger": "Do not trigger manage as the primary skill.", "expected_output": "Should sequence future work as a plan rather than manage active status." }, { - "id": "coordinate-work-006", + "id": "manage-006", "category": "false-positive", "prompt": "What questions should I ask each team before assigning work?", - "expected_trigger": "Do not trigger coordinate-work as the primary skill.", + "expected_trigger": "Do not trigger manage as the primary skill.", "expected_output": "Should generate clarification questions before coordination." }, { - "id": "coordinate-work-007", + "id": "manage-007", "category": "non-trigger", "prompt": "Explain why this rollout needs a feature flag.", - "expected_trigger": "Do not trigger coordinate-work.", + "expected_trigger": "Do not trigger manage.", "expected_output": "Should explain the reasoning or mechanism." }, { - "id": "coordinate-work-008", + "id": "manage-008", "category": "non-trigger", "prompt": "Categorize these tasks by frontend, backend, and docs.", - "expected_trigger": "Do not trigger coordinate-work.", + "expected_trigger": "Do not trigger manage.", "expected_output": "Should classify tasks by component." } ] diff --git a/.agents/skills/plan-work/SKILL.md b/.agents/skills/plan/SKILL.md similarity index 97% rename from .agents/skills/plan-work/SKILL.md rename to .agents/skills/plan/SKILL.md index e78598c..d223b03 100644 --- a/.agents/skills/plan-work/SKILL.md +++ b/.agents/skills/plan/SKILL.md @@ -1,5 +1,5 @@ --- -name: plan-work +name: plan description: Sequence work before execution. Use for planning requests like "break this down", "roadmap", "approach", "milestones", "how should we proceed", migration planning, rollout planning, and scoped next steps. license: MIT tags: @@ -8,13 +8,13 @@ tags: - sequencing metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: project-management --- -# plan-work +# plan Turn a goal into a practical sequence of work. diff --git a/.agents/skills/plan-work/evals/evals.json b/.agents/skills/plan/evals/evals.json similarity index 84% rename from .agents/skills/plan-work/evals/evals.json rename to .agents/skills/plan/evals/evals.json index 11a82ff..4a9429f 100644 --- a/.agents/skills/plan-work/evals/evals.json +++ b/.agents/skills/plan/evals/evals.json @@ -1,56 +1,56 @@ { "evals": [ { - "id": "plan-work-001", + "id": "plan-001", "category": "true-positive", "prompt": "Plan the migration from the old auth service to the new one.", "expected_trigger": "Trigger plan.", "expected_output": "Produces phases, dependencies, risks, validation steps, and a next action." }, { - "id": "plan-work-002", + "id": "plan-002", "category": "true-positive", "prompt": "Break this feature into milestones we can implement safely.", "expected_trigger": "Trigger plan.", "expected_output": "Breaks work into scoped milestones with assumptions and verification." }, { - "id": "plan-work-003", + "id": "plan-003", "category": "true-positive", "prompt": "What's the best approach for rolling this out gradually?", "expected_trigger": "Trigger plan.", "expected_output": "Outlines a staged rollout with risks, gates, and rollback or validation checks." }, { - "id": "plan-work-004", + "id": "plan-004", "category": "true-positive", "prompt": "How should we proceed with cleaning up this module?", "expected_trigger": "Trigger plan.", "expected_output": "Defines a practical sequence and notes missing context that could change it." }, { - "id": "plan-work-005", + "id": "plan-005", "category": "false-positive", "prompt": "Coordinate frontend, backend, and QA while this migration is already in progress.", - "expected_trigger": "Do not trigger plan-work as the primary skill.", + "expected_trigger": "Do not trigger plan as the primary skill.", "expected_output": "Should manage active workstreams, owners, blockers, and handoffs." }, { - "id": "plan-work-006", + "id": "plan-006", "category": "false-positive", "prompt": "What are the right questions before we plan the migration?", - "expected_trigger": "Do not trigger plan-work as the primary skill.", + "expected_trigger": "Do not trigger plan as the primary skill.", "expected_output": "Should generate high-leverage clarification questions first." }, { - "id": "plan-work-007", + "id": "plan-007", "category": "non-trigger", "prompt": "Classify these API endpoints by customer-facing versus internal.", "expected_trigger": "Do not trigger plan.", "expected_output": "Should group endpoints by the requested criteria." }, { - "id": "plan-work-008", + "id": "plan-008", "category": "non-trigger", "prompt": "Remember that migration plans should include rollback checks.", "expected_trigger": "Do not trigger plan.", diff --git a/.agents/skills/remember-context/SKILL.md b/.agents/skills/remember/SKILL.md similarity index 97% rename from .agents/skills/remember-context/SKILL.md rename to .agents/skills/remember/SKILL.md index 44e8ad5..a80941b 100644 --- a/.agents/skills/remember-context/SKILL.md +++ b/.agents/skills/remember/SKILL.md @@ -1,5 +1,5 @@ --- -name: remember-context +name: remember description: Preserve durable project facts, decisions, and useful observations in .agents/memory/. Use for memory requests like "remember this", "save context", "record a decision", "update memory", or preserving a project fact. license: MIT tags: @@ -8,13 +8,13 @@ tags: - project-context metadata: author: Oleg Shulyakov - version: "1.0.2" + version: "1.0.3" source: github.com/olegshulyakov/agent.md catalog: utility category: productivity --- -# remember-context +# remember Write durable project memory only when it will help future work. diff --git a/.agents/skills/remember-context/evals/evals.json b/.agents/skills/remember/evals/evals.json similarity index 68% rename from .agents/skills/remember-context/evals/evals.json rename to .agents/skills/remember/evals/evals.json index 3483bb3..0069dbc 100644 --- a/.agents/skills/remember-context/evals/evals.json +++ b/.agents/skills/remember/evals/evals.json @@ -1,59 +1,59 @@ { "evals": [ { - "id": "remember-context-001", + "id": "remember-001", "category": "true-positive", "prompt": "Remember that we chose skills over plugins for this workflow.", - "expected_trigger": "Trigger remember-context.", + "expected_trigger": "Trigger remember.", "expected_output": "Writes a concise durable memory note without asking for extra confirmation." }, { - "id": "remember-context-002", + "id": "remember-002", "category": "true-positive", "prompt": "Save context: this repo keeps task-specific docs under docs/YYYY-MM-DD-task-name/.", - "expected_trigger": "Trigger remember-context.", + "expected_trigger": "Trigger remember.", "expected_output": "Records the durable convention in the appropriate memory file if not already present." }, { - "id": "remember-context-003", + "id": "remember-003", "category": "true-positive", "prompt": "Record the decision that explicit memory requests are auto-approved.", - "expected_trigger": "Trigger remember-context.", + "expected_trigger": "Trigger remember.", "expected_output": "Persists the decision as durable project memory and reports the file updated." }, { - "id": "remember-context-004", + "id": "remember-004", "category": "true-positive", - "prompt": "Update memory with the fact that explore-context is local-only and never web search.", - "expected_trigger": "Trigger remember-context.", + "prompt": "Update memory with the fact that explore is local-only and never web search.", + "expected_trigger": "Trigger remember.", "expected_output": "Writes a brief project fact while avoiding duplication if already stored." }, { - "id": "remember-context-005", + "id": "remember-005", "category": "false-positive", "prompt": "Plan how we should capture project decisions going forward.", - "expected_trigger": "Do not trigger remember-context as the primary skill.", + "expected_trigger": "Do not trigger remember as the primary skill.", "expected_output": "Should produce a plan; memory writes require an explicit thing to preserve." }, { - "id": "remember-context-006", + "id": "remember-006", "category": "false-positive", "prompt": "Explain how the memory files are organized.", - "expected_trigger": "Do not trigger remember-context as the primary skill.", + "expected_trigger": "Do not trigger remember as the primary skill.", "expected_output": "Should explain the convention, not write memory." }, { - "id": "remember-context-007", + "id": "remember-007", "category": "non-trigger", "prompt": "Here is my API token, keep it handy for later.", "expected_trigger": "Do not write sensitive memory.", "expected_output": "Should refuse to store secrets and suggest a safer handling pattern." }, { - "id": "remember-context-008", + "id": "remember-008", "category": "non-trigger", "prompt": "Find where the project memory loader is implemented.", - "expected_trigger": "Do not trigger remember-context.", + "expected_trigger": "Do not trigger remember.", "expected_output": "Should inspect local repository context and cite evidence." } ] diff --git a/docs/2026-05-02-team-roles-as-skills/PRD.md b/docs/2026-05-02-team-roles-as-skills/PRD.md index 8f05e1b..3e82198 100644 --- a/docs/2026-05-02-team-roles-as-skills/PRD.md +++ b/docs/2026-05-02-team-roles-as-skills/PRD.md @@ -93,7 +93,7 @@ The initiative targets teams and individual practitioners who want role-aware AI | FR-4 | Support multi-variant routing where domains share one role context. | SHOULD | Router skills detect variants from prompt and repo context; router skills ask at most one clarifying question when context is materially ambiguous; variant references are loaded on demand. | [SPEC.md](SPEC.md) | | FR-5 | Prioritize build order by daily leverage and role coverage. | MUST | P1 foundation skills are built first; P2/P3/P4 priorities are visible in TASKS.md; completed skills are marked in the tracker. | [TASKS.md](TASKS.md) | | FR-6 | Package completed skills for distribution. | SHOULD | Completed skills can be exported as `.skill` files; package contents include instructions, references, scripts, and assets needed for reuse; root-level evals are retained in the source folder and excluded from packaged artifacts by the current packager. | [SPEC.md](SPEC.md), [.agents/skills/README.md](../../.agents/skills/README.md) | -| FR-7 | Keep security and test responsibilities separated. | MUST | `audit-security` owns prompt-injection, jailbreak, exfiltration, secrets, and threat-modeling guidance; `build-tests` owns functional tests, AI evals, tool-use evals, performance tests, and CI test setup. | [SPEC.md](SPEC.md) | +| FR-7 | Keep security and test responsibilities separated. | MUST | `audit-security` owns prompt-injection, jailbreak, exfiltration, secrets, and threat-modeling guidance; `code-tests` owns functional tests, AI evals, tool-use evals, performance tests, and CI test setup. | [SPEC.md](SPEC.md) | --- @@ -124,14 +124,14 @@ The initiative targets teams and individual practitioners who want role-aware AI Users invoke skills by naming the skill directly, asking for the artifact the skill owns, or describing a role-specific task. The agent should select the matching skill from its description, load only the needed references, and produce or edit the requested artifact in the repository. -For multi-variant skills, the expected interaction is context-first routing. For example, a request for API tests, E2E tests, AI evals, or performance tests should route through `build-tests` and select the relevant testing reference without requiring the user to know the internal variant name. +For multi-variant skills, the expected interaction is context-first routing. For example, a request for API tests, E2E tests, AI evals, or performance tests should route through `code-tests` and select the relevant testing reference without requiring the user to know the internal variant name. --- ## 🗺️ User Journeys / Key Flows 1. A product owner asks for a PRD. The agent loads `write-prd`, reads the required output format, extracts known context, marks inferences with `[assumed]`, and writes `PRD.md`. -2. A backend engineer asks for API code. The agent loads `build-backend`, detects language and framework from repository context, writes focused code changes, and verifies them with local tests where available. +2. A backend engineer asks for API code. The agent loads `code-backend`, detects language and framework from repository context, writes focused code changes, and verifies them with local tests where available. 3. A maintainer adds a new skill. The maintainer follows the skill structure in SPEC.md, adds references only when needed, writes eval cases, updates TASKS.md, and packages the skill when complete. --- diff --git a/docs/2026-05-02-team-roles-as-skills/SPEC.md b/docs/2026-05-02-team-roles-as-skills/SPEC.md index 58031fa..93b24f6 100644 --- a/docs/2026-05-02-team-roles-as-skills/SPEC.md +++ b/docs/2026-05-02-team-roles-as-skills/SPEC.md @@ -208,7 +208,7 @@ Runtime plugin hosting, remote skill fetching, marketplace behavior, live Jira/G **Acceptance criteria:** - `audit-security` owns prompt injection, jailbreak, exfiltration, secrets, OWASP review, and threat modeling. -- `build-tests` owns executable tests, AI evals, tool-use evals, performance tests, fixtures, framework setup, and CI test setup. +- `code-tests` owns executable tests, AI evals, tool-use evals, performance tests, fixtures, framework setup, and CI test setup. - Boundary prompts route consistently between the two. ## 3. Non-Functional Requirements @@ -294,7 +294,7 @@ Router skills use one `SKILL.md` plus variant references when related artifacts 4. Ask one concise question only when the route changes the output materially. 5. Mark inferred details with `[assumed]` when producing a spec or planning artifact. -Router skills for this release are `audit-security`, `build-frontend`, `build-backend`, `build-database`, `build-mobile`, `build-tests`, `design-arch`, `write-spec`, `configure-infra`, `create-template`, `write-tech-docs`, `review-code`, and `plan-capacity`. +Router skills for this release are `audit-security`, `code-frontend`, `code-backend`, `code-database`, `build-mobile`, `code-tests`, `design-arch`, `write-spec`, `configure-infra`, `create-template`, `write-tech-docs`, `review-code`, and `plan-capacity`. ## 5. Catalog @@ -307,11 +307,11 @@ Router skills for this release are `audit-security`, `build-frontend`, `build-ba | `audit-security` | Security Eng | Security router: OWASP review, secrets audit, threat model | | `audit-test-flaky` | AQA | Flaky test report with root cause and fix recommendations | | `check-release` | Release Manager | Release checklist with rollback criteria | -| `build-backend` | Backend Dev | Backend code: routes, services, middleware, tests | -| `build-database` | DBA, Backend, Data Eng | Database code: schemas, SQL, migrations, analytics queries | -| `build-frontend` | Frontend Dev | Frontend code: components, pages, state, styling | +| `code-backend` | Backend Dev | Backend code: routes, services, middleware, tests | +| `code-database` | DBA, Backend, Data Eng | Database code: schemas, SQL, migrations, analytics queries | +| `code-frontend` | Frontend Dev | Frontend code: components, pages, state, styling | | `build-mobile` | Mobile Dev | Mobile code: screens, navigation, platform patterns | -| `build-tests` | AQA | Test suites, eval harnesses, fixtures, configs, CI setup | +| `code-tests` | AQA | Test suites, eval harnesses, fixtures, configs, CI setup | | `design-api` | Backend Dev | API contract: OpenAPI, AsyncAPI, GraphQL, endpoints, schemas | | `design-arch` | Architect | Architecture router: system design, ADR, C4 diagram | | `diagram-dfd` | System Analyst | Data flow diagram in Mermaid or structured text | @@ -366,11 +366,11 @@ Router skills for this release are `audit-security`, `build-frontend`, `build-ba | --- | --- | | `write-spec` | `functional.md`, `technical.md`, `non-functional.md`, `design-ui.md`, `data-contract.md` | | `design-arch` | `system-design.md`, `adr.md`, `c4.md` | -| `build-database` | `schema-design.md`, `migration.md`, `common.md`, plus supported dialect references | -| `build-frontend` | Language, framework, styling, accessibility, forms, state, performance, PWA, i18n, visualization references | -| `build-backend` | Language-level references plus supported framework references | +| `code-database` | `schema-design.md`, `migration.md`, `common.md`, plus supported dialect references | +| `code-frontend` | Language, framework, styling, accessibility, forms, state, performance, PWA, i18n, visualization references | +| `code-backend` | Language-level references plus supported framework references | | `build-mobile` | `swift.md`, `kotlin-android.md`, `react-native.md`, `flutter.md` | -| `build-tests` | `e2e.md`, `api.md`, `perf.md`, `framework-setup.md`, `ai-output.md`, `ai-tool-use.md`, `ai-perf.md` | +| `code-tests` | `e2e.md`, `api.md`, `perf.md`, `framework-setup.md`, `ai-output.md`, `ai-tool-use.md`, `ai-perf.md` | | `configure-infra` | `iac.md`, `cicd.md`, `etl.md`, `observability.md` | | `plan-capacity` | `db.md`, `infra.md` | | `audit-security` | `owasp.md`, `secrets.md`, `threat-model.md` | @@ -386,10 +386,10 @@ Router skills for this release are `audit-security`, `build-frontend`, `build-ba | `design-api` vs `write-tech-docs` API docs | `design-api` is contract-first before implementation; `write-tech-docs` documents an existing API. | | `design-arch` variants | System design is broad architecture; ADR is one decision; C4 is diagram-focused. | | `write-user-story` vs `write-epic` | User story is one deliverable with acceptance criteria and tasks; epic groups related stories. | -| `build-tests` vs `write-test-strategy` | `build-tests` writes executable tests/config/evals; `write-test-strategy` writes planning guidance. | +| `code-tests` vs `write-test-strategy` | `code-tests` writes executable tests/config/evals; `write-test-strategy` writes planning guidance. | | `review-code` vs `audit-security` | `review-code` reviews a code change; `audit-security` performs standalone security analysis. | | `create-template` vs `write-*` | `create-template` creates reusable blank templates; `write-*` creates filled artifacts. | -| `audit-security` vs `build-tests` AI evals | `audit-security` owns abuse, exfiltration, secrets, and threat modeling; `build-tests` owns quality, tool-use, latency, cost, and regression evals. | +| `audit-security` vs `code-tests` AI evals | `audit-security` owns abuse, exfiltration, secrets, and threat modeling; `code-tests` owns quality, tool-use, latency, cost, and regression evals. | ## 7. Validation diff --git a/docs/2026-05-02-team-roles-as-skills/TASKS.md b/docs/2026-05-02-team-roles-as-skills/TASKS.md index 946b0dc..65b6135 100644 --- a/docs/2026-05-02-team-roles-as-skills/TASKS.md +++ b/docs/2026-05-02-team-roles-as-skills/TASKS.md @@ -87,11 +87,11 @@ Ordered alphabetically by name (matches filesystem order). | Done | Skill | Priority | Domain | Primary Role | Produces | | ----- | ------------------ | -------- | ------- | ------------- | ------------------------------------------------------------------------------------------- | -| - [x] | `build-backend` | 🔴 P1 | Code | Backend Dev | Production-ready backend code across TIOBE-informed backend routes | -| - [x] | `build-database` | 🔴 P1 | Database | DBA / Backend | Database code router for OLTP SQL, analytics SQL, schema design, and migrations | -| - [x] | `build-frontend` | 🔴 P1 | Code | Frontend Dev | Production-ready frontend code + design system tokens + component style guide | +| - [x] | `code-backend` | 🔴 P1 | Code | Backend Dev | Production-ready backend code across TIOBE-informed backend routes | +| - [x] | `code-database` | 🔴 P1 | Database | DBA / Backend | Database code router for OLTP SQL, analytics SQL, schema design, and migrations | +| - [x] | `code-frontend` | 🔴 P1 | Code | Frontend Dev | Production-ready frontend code + design system tokens + component style guide | | - [ ] | `build-mobile` | 🟠 P2 | Code | Mobile Dev | Production-ready mobile code (Swift/iOS, Kotlin/Android, React Native, Flutter) | -| - [x] | `build-tests` | 🔴 P1 | Testing | AQA / Backend / ML | Test suite and test framework generation (e2e, api, perf, AI evals, CI config) | +| - [x] | `code-tests` | 🔴 P1 | Testing | AQA / Backend / ML | Test suite and test framework generation (e2e, api, perf, AI evals, CI config) | ### `design-` diff --git a/docs/2026-05-20-general-agent-skills/PRD.md b/docs/2026-05-20-general-agent-skills/PRD.md index b9351f2..23c30e2 100644 --- a/docs/2026-05-20-general-agent-skills/PRD.md +++ b/docs/2026-05-20-general-agent-skills/PRD.md @@ -30,7 +30,7 @@ Without these skills, the agent has to infer these broad behaviors from generic | Goal ID | Target Outcome | Success Metric | | --- | --- | --- | -| G-1 | Provide a minimal general skill set for common agent collaboration modes. | Ten skills exist: `ask-questions`, `explain-topic`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, and `adapt`. | +| G-1 | Provide a minimal general skill set for common agent collaboration modes. | Ten skills exist: `ask`, `explain`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, and `adapt`. | | G-2 | Keep every skill independently installable. | Each skill works at runtime without requiring, calling, importing, or delegating to another installed skill. | | G-3 | Make trigger behavior predictable. | Each skill has explicit trigger phrases, exclusions, and at least 7 representative eval prompts: 3 true-positive, 2 false-positive, and 2 non-trigger prompts. | | G-4 | Keep each skill lightweight and reusable across repositories. | Each `SKILL.md` stays under 500 lines and uses references only when needed. | @@ -49,15 +49,15 @@ Without these skills, the agent has to infer these broad behaviors from generic ### In Scope -- `ask-questions`: Identify useful questions, missing context, hidden assumptions, and the smallest clarifications needed to move forward. -- `explain-topic`: Explain concepts, code, architecture, behavior, tradeoffs, and decisions in clear terms matched to the user's question. -- `reason-problem`: Work through ambiguous problems by clarifying terms, surfacing assumptions, generating hypotheses, testing arguments, and shaping a clearer framing. -- `classify-content`: Organize items, ideas, observations, requirements, examples, files, risks, or options into meaningful categories by similarity, difference, type, abstraction level, priority, dependency, or other explicit criteria. -- `plan-work`: Turn a goal into a scoped plan, milestones, risks, sequencing, and next actions. -- `explore-context`: Investigate local code, project docs, attached artifacts, and repository context when local research is needed. -- `decide-direction`: Compare options and recommend a course of action with tradeoffs, assumptions, and decision criteria. -- `coordinate-work`: Manage multi-step or multi-agent work by tracking goals, owners, dependencies, status, blockers, handoffs, and next actions. -- `remember-context`: Capture durable project facts, decisions, and useful observations in `.agents/memory/`. +- `ask`: Identify useful questions, missing context, hidden assumptions, and the smallest clarifications needed to move forward. +- `explain`: Explain concepts, code, architecture, behavior, tradeoffs, and decisions in clear terms matched to the user's question. +- `brainstorm`: Work through ambiguous problems by clarifying terms, surfacing assumptions, generating hypotheses, testing arguments, and shaping a clearer framing. +- `classify`: Organize items, ideas, observations, requirements, examples, files, risks, or options into meaningful categories by similarity, difference, type, abstraction level, priority, dependency, or other explicit criteria. +- `plan`: Turn a goal into a scoped plan, milestones, risks, sequencing, and next actions. +- `explore`: Investigate local code, project docs, attached artifacts, and repository context when local research is needed. +- `choose`: Compare options and recommend a course of action with tradeoffs, assumptions, and decision criteria. +- `manage`: Manage multi-step or multi-agent work by tracking goals, owners, dependencies, status, blockers, handoffs, and next actions. +- `remember`: Capture durable project facts, decisions, and useful observations in `.agents/memory/`. - `adapt`: Detect when existing behavior, skills, rules, workflows, docs, evals, or memory conventions no longer fit observed outcomes, user feedback, failures, repeated friction, outdated assumptions, or changed constraints, then identify what should change and which appropriate skill or workflow should make the change. - Trigger and exclusion guidance for each skill. - Acceptance criteria and eval prompts for skill behavior. @@ -66,7 +66,7 @@ Without these skills, the agent has to infer these broad behaviors from generic ### Out of Scope - Live integrations with Jira, Linear, Confluence, GitHub Issues, or external memory stores. -- Web search, web browsing, or external/current-information research inside `explore-context`. +- Web search, web browsing, or external/current-information research inside `explore`. - Automatic memory writes without user intent or clearly durable project value. - Direct artifact rewrites by `adapt` unless the user separately asks to proceed with the appropriate update workflow. - Replacing project instructions in `AGENTS.md`. @@ -82,15 +82,15 @@ Without these skills, the agent has to infer these broad behaviors from generic | Requirement ID | Capability / Feature | Priority | Acceptance Criteria | Tracker | | --- | --- | --- | --- | --- | -| FR-1 | Define `ask-questions` as the skill for question generation and clarification. | MUST | Triggers on “ask-questions”, “what should I ask”, “what are the right questions”, “what are we missing”, “clarify this”, and ambiguous requests where progress depends on missing context. Produces a minimal, prioritized set of useful questions, assumptions, and context gaps. | TBD | -| FR-2 | Define `explain-topic` as the skill for clarification and teaching. | MUST | Triggers on “explain-topic”, “what is”, “why”, “how does”, “walk me through”, and code/concept explanation requests. Produces clear explanations matched to the user's context and desired depth. | TBD | -| FR-3 | Define `reason-problem` as the skill for working through ambiguous problems. | MUST | Triggers on “reason through”, “think through”, “brainstorm”, “tackle this problem”, “help me frame this”, “let’s work through this”, and messy problem statements where the desired output is not yet clear. Clarifies terms, assumptions, constraints, possible explanations, and candidate directions without forcing a premature decision or plan. | TBD | -| FR-4 | Define `classify-content` as the skill for organizing material into meaningful groups. | MUST | Triggers on “classify-content”, “categorize”, “group”, “cluster”, “sort”, “taxonomy”, “organize these”, and requests to group items by similarity, difference, category, priority, dependency, abstraction level, or other explicit criteria. Produces labeled groups, grouping criteria, notable edge cases, and items that do not clearly fit. | TBD | -| FR-5 | Define `plan-work` as the skill for sequencing work before execution. | MUST | Triggers on “plan-work”, “break this down”, “roadmap”, “approach”, “milestones”, and “how should we proceed”. Produces scoped steps, risks, assumptions, and verification strategy when relevant. | TBD | -| FR-6 | Define `explore-context` as the skill for local investigation and repository research. | MUST | Triggers on “explore-context”, “investigate”, “find where”, “understand this repo”, “trace”, and local-context research requests. Covers local code, project docs, attached artifacts, and repository context only. Produces findings with file references, artifact references, or uncertainty clearly marked. | TBD | -| FR-7 | Define `decide-direction` as the skill for choosing among options. | MUST | Triggers on “decide-direction”, “choose”, “which option”, “tradeoffs”, “recommend”, and “should we”. States decision criteria, compares viable options, recommends one, and identifies reversibility or risk. | TBD | -| FR-8 | Define `coordinate-work` as the skill for managing active work across people, agents, tasks, and dependencies. | MUST | Triggers on “coordinate-work”, “manage this work”, “team lead”, “lead this”, “assign”, “delegate”, “track blockers”, “status”, “handoff”, and multi-agent or multi-workstream requests. Maintains an execution view with goals, owners, dependencies, current status, blockers, and next actions. | TBD | -| FR-9 | Define `remember-context` as the skill for durable project memory. | MUST | Triggers when the user asks to remember, save context, record a decision, update memory, or preserve a project fact. When the user explicitly asks to remember something, the memory write is auto-approved and should proceed without asking again. Writes only durable facts, decisions, and observations to `.agents/memory/` according to project conventions. Avoids storing transient task chatter or unverifiable assumptions as fact. | TBD | +| FR-1 | Define `ask` as the skill for question generation and clarification. | MUST | Triggers on “ask”, “what should I ask”, “what are the right questions”, “what are we missing”, “clarify this”, and ambiguous requests where progress depends on missing context. Produces a minimal, prioritized set of useful questions, assumptions, and context gaps. | TBD | +| FR-2 | Define `explain` as the skill for clarification and teaching. | MUST | Triggers on “explain”, “what is”, “why”, “how does”, “walk me through”, and code/concept explanation requests. Produces clear explanations matched to the user's context and desired depth. | TBD | +| FR-3 | Define `brainstorm` as the skill for working through ambiguous problems. | MUST | Triggers on “reason through”, “think through”, “brainstorm”, “tackle this problem”, “help me frame this”, “let’s work through this”, and messy problem statements where the desired output is not yet clear. Clarifies terms, assumptions, constraints, possible explanations, and candidate directions without forcing a premature decision or plan. | TBD | +| FR-4 | Define `classify` as the skill for organizing material into meaningful groups. | MUST | Triggers on “classify”, “categorize”, “group”, “cluster”, “sort”, “taxonomy”, “organize these”, and requests to group items by similarity, difference, category, priority, dependency, abstraction level, or other explicit criteria. Produces labeled groups, grouping criteria, notable edge cases, and items that do not clearly fit. | TBD | +| FR-5 | Define `plan` as the skill for sequencing work before execution. | MUST | Triggers on “plan”, “break this down”, “roadmap”, “approach”, “milestones”, and “how should we proceed”. Produces scoped steps, risks, assumptions, and verification strategy when relevant. | TBD | +| FR-6 | Define `explore` as the skill for local investigation and repository research. | MUST | Triggers on “explore”, “investigate”, “find where”, “understand this repo”, “trace”, and local-context research requests. Covers local code, project docs, attached artifacts, and repository context only. Produces findings with file references, artifact references, or uncertainty clearly marked. | TBD | +| FR-7 | Define `choose` as the skill for choosing among options. | MUST | Triggers on “choose”, “choose”, “which option”, “tradeoffs”, “recommend”, and “should we”. States decision criteria, compares viable options, recommends one, and identifies reversibility or risk. | TBD | +| FR-8 | Define `manage` as the skill for managing active work across people, agents, tasks, and dependencies. | MUST | Triggers on “manage”, “manage this work”, “team lead”, “lead this”, “assign”, “delegate”, “track blockers”, “status”, “handoff”, and multi-agent or multi-workstream requests. Maintains an execution view with goals, owners, dependencies, current status, blockers, and next actions. | TBD | +| FR-9 | Define `remember` as the skill for durable project memory. | MUST | Triggers when the user asks to remember, save context, record a decision, update memory, or preserve a project fact. When the user explicitly asks to remember something, the memory write is auto-approved and should proceed without asking again. Writes only durable facts, decisions, and observations to `.agents/memory/` according to project conventions. Avoids storing transient task chatter or unverifiable assumptions as fact. | TBD | | FR-10 | Define `adapt` as the skill for detecting evidence-driven change needs and routing the update. | MUST | Triggers on “adapt based on this”, “what should change after this?”, “fold this feedback into our process”, “this keeps happening”, “we keep hitting this issue”, “this failed, what should change?”, “our instructions didn’t handle this”, “the workflow no longer fits”, “the constraints changed”, “this behavior is outdated”, “adjust future behavior based on this”, “turn this failure into an instruction change”, “what artifact should change because of this?”, and “do we need to update a skill, rule, doc, eval, or memory?”. Identifies the adaptation signal, affected behavior or artifact, smallest useful change, and appropriate follow-up skill or workflow. Does not directly update artifacts by default. | TBD | | FR-11 | Document standalone runtime boundaries. | MUST | Each skill defines its own purpose, trigger phrases, non-trigger cases, expected behavior, and output shape without requiring, calling, importing, or delegating to another skill at runtime. `adapt` may identify an appropriate follow-up skill or workflow as a route, but that route is not a runtime dependency. | TBD | | FR-12 | Add behavior evals. | SHOULD | Each skill has at least 7 representative prompts: 3 true-positive prompts, 2 false-positive prompts, and 2 non-trigger prompts. | TBD | @@ -102,14 +102,14 @@ Without these skills, the agent has to infer these broad behaviors from generic | NFR ID | Category | Target Specification | | --- | --- | --- | | NFR-1 | Maintainability | Each skill has one clear workflow and avoids becoming a dumping ground for generic agent behavior. | -| NFR-2 | Portability | Skills work across repositories and do not assume this repository layout except where `remember-context` explicitly uses `.agents/memory/`. Runtime behavior must not depend on any other skill being installed. | +| NFR-2 | Portability | Skills work across repositories and do not assume this repository layout except where `remember` explicitly uses `.agents/memory/`. Runtime behavior must not depend on any other skill being installed. | | NFR-3 | Token Efficiency | Main `SKILL.md` files stay concise; long examples or eval details move to references only when they reduce ambiguity. | -| NFR-4 | Question Quality | `ask-questions` must prefer the fewest high-leverage questions over exhaustive questionnaires. | -| NFR-5 | Reasoning Quality | `reason-problem` must expose assumptions, uncertainty, and competing interpretations instead of presenting guesses as settled conclusions. | -| NFR-6 | Classification Quality | `classify-content` must state the grouping criteria and preserve ambiguous or multi-fit items instead of forcing every item into a clean bucket. | -| NFR-7 | Source Discipline | `explore-context` must cite local files, project docs, or attached artifacts and distinguish verified repository facts from inference. It must not perform web search or browsing. | -| NFR-8 | Memory Hygiene | `remember-context` must preserve useful context without duplicating docs or storing sensitive/transient information. | -| NFR-9 | Coordination Clarity | `coordinate-work` must keep status, owners, blockers, and next actions explicit enough that another agent or human can continue the work. | +| NFR-4 | Question Quality | `ask` must prefer the fewest high-leverage questions over exhaustive questionnaires. | +| NFR-5 | Reasoning Quality | `brainstorm` must expose assumptions, uncertainty, and competing interpretations instead of presenting guesses as settled conclusions. | +| NFR-6 | Classification Quality | `classify` must state the grouping criteria and preserve ambiguous or multi-fit items instead of forcing every item into a clean bucket. | +| NFR-7 | Source Discipline | `explore` must cite local files, project docs, or attached artifacts and distinguish verified repository facts from inference. It must not perform web search or browsing. | +| NFR-8 | Memory Hygiene | `remember` must preserve useful context without duplicating docs or storing sensitive/transient information. | +| NFR-9 | Coordination Clarity | `manage` must keep status, owners, blockers, and next actions explicit enough that another agent or human can continue the work. | | NFR-10 | Adaptation Discipline | `adapt` must distinguish durable evidence-driven change signals from one-off exceptions and route actual updates to the appropriate skill or workflow. | --- @@ -127,15 +127,15 @@ Without these skills, the agent has to infer these broad behaviors from generic ## User Journeys / Key Flows -1. A user asks, “What should we ask before committing to this approach?” The agent uses `ask-questions` to produce a short set of high-leverage questions, assumptions, and missing context. -2. A user asks, “Explain how this auth flow works.” The agent uses `explain-topic`, reads the relevant code only if needed, and returns a clear explanation with file references when applicable. -3. A user asks, “Let’s think through why this workflow feels fragile.” The agent uses `reason-problem` to clarify the problem, surface assumptions, generate hypotheses, and identify what would make the situation clearer. -4. A user asks, “Classify these feature requests by underlying user need.” The agent uses `classify-content` to define grouping criteria, label groups, place items, and flag ambiguous cases. -5. A user asks, “Let’s plan the migration.” The agent uses `plan-work` to identify phases, risks, verification, assumptions, and next actions. -6. A user asks, “Explore whether we already support this.” The agent uses `explore-context`, searches local files, project docs, and attached artifacts, then reports findings and gaps. -7. A user asks, “Should we build this as a plugin or a skill?” The agent uses `decide-direction`, compares options against explicit criteria, and recommends one. -8. A user asks, “Lead this migration across frontend, backend, and tests.” The agent uses `coordinate-work` to track workstreams, owners, dependencies, blockers, status, and handoffs. -9. A user asks, “Remember that we chose skills over plugins for this.” The agent uses `remember-context`, records the durable decision in the appropriate memory file, and keeps the note concise. +1. A user asks, “What should we ask before committing to this approach?” The agent uses `ask` to produce a short set of high-leverage questions, assumptions, and missing context. +2. A user asks, “Explain how this auth flow works.” The agent uses `explain`, reads the relevant code only if needed, and returns a clear explanation with file references when applicable. +3. A user asks, “Let’s think through why this workflow feels fragile.” The agent uses `brainstorm` to clarify the problem, surface assumptions, generate hypotheses, and identify what would make the situation clearer. +4. A user asks, “Classify these feature requests by underlying user need.” The agent uses `classify` to define grouping criteria, label groups, place items, and flag ambiguous cases. +5. A user asks, “Let’s plan the migration.” The agent uses `plan` to identify phases, risks, verification, assumptions, and next actions. +6. A user asks, “Explore whether we already support this.” The agent uses `explore`, searches local files, project docs, and attached artifacts, then reports findings and gaps. +7. A user asks, “Should we build this as a plugin or a skill?” The agent uses `choose`, compares options against explicit criteria, and recommends one. +8. A user asks, “Lead this migration across frontend, backend, and tests.” The agent uses `manage` to track workstreams, owners, dependencies, blockers, status, and handoffs. +9. A user asks, “Remember that we chose skills over plugins for this.” The agent uses `remember`, records the durable decision in the appropriate memory file, and keeps the note concise. 10. A user says, “This failed, what should change?” The agent uses `adapt` to identify the failure signal, determine whether a skill, rule, doc, eval, memory convention, or workflow should change, and route the actual update to the appropriate follow-up skill or workflow. --- @@ -145,14 +145,14 @@ Without these skills, the agent has to infer these broad behaviors from generic | Risk ID | Assumption / Risk Description | Impact | Mitigation Strategy | Status | | --- | --- | --- | --- | --- | | R-1 | General skills could become too broad and behave inconsistently. | HIGH | Define clear trigger phrases, non-trigger cases, and output expectations in every skill. | OPEN | -| R-2 | `explore-context` could be mistaken for web research. | MEDIUM | Define `explore-context` as local and artifact investigation only; external/current research remains out of scope for this skill. | OPEN | -| R-3 | `remember-context` could accumulate low-value notes. | MEDIUM | Require durability criteria before writing memory. | OPEN | -| R-4 | `decide-direction` recommendations may hide subjective criteria. | MEDIUM | Require explicit criteria, assumptions, and reversibility notes. | OPEN | +| R-2 | `explore` could be mistaken for web research. | MEDIUM | Define `explore` as local and artifact investigation only; external/current research remains out of scope for this skill. | OPEN | +| R-3 | `remember` could accumulate low-value notes. | MEDIUM | Require durability criteria before writing memory. | OPEN | +| R-4 | `choose` recommendations may hide subjective criteria. | MEDIUM | Require explicit criteria, assumptions, and reversibility notes. | OPEN | | R-5 | Eval coverage may be too small to catch trigger conflicts. | MEDIUM | Include false-positive and non-trigger prompts, not only happy-path prompts. | OPEN | -| R-6 | `coordinate-work` could overlap with `plan-work`. | MEDIUM | Define `plan-work` as pre-execution sequencing and `coordinate-work` as active coordination across workstreams, owners, blockers, and handoffs. | OPEN | -| R-7 | `reason-problem` could become vague brainstorming without useful output. | MEDIUM | Require a clear problem framing, assumptions, hypotheses or options, and suggested next clarity step. | OPEN | -| R-8 | `ask-questions` could become an endless questionnaire. | MEDIUM | Require prioritized questions and a bias toward the smallest question set that changes the next action. | OPEN | -| R-9 | `classify-content` could force false precision. | MEDIUM | Require explicit grouping criteria, ambiguous cases, and optional multi-label classifications when needed. | OPEN | +| R-6 | `manage` could overlap with `plan`. | MEDIUM | Define `plan` as pre-execution sequencing and `manage` as active coordination across workstreams, owners, blockers, and handoffs. | OPEN | +| R-7 | `brainstorm` could become vague brainstorming without useful output. | MEDIUM | Require a clear problem framing, assumptions, hypotheses or options, and suggested next clarity step. | OPEN | +| R-8 | `ask` could become an endless questionnaire. | MEDIUM | Require prioritized questions and a bias toward the smallest question set that changes the next action. | OPEN | +| R-9 | `classify` could force false precision. | MEDIUM | Require explicit grouping criteria, ambiguous cases, and optional multi-label classifications when needed. | OPEN | | R-10 | `adapt` could become a generic “improve anything” skill or rewrite artifacts directly. | MEDIUM | Define `adapt` as evidence-driven change detection and routing only; actual updates belong to the appropriate artifact-specific skill or workflow. | OPEN | --- @@ -170,15 +170,15 @@ Without these skills, the agent has to infer these broad behaviors from generic | Question ID | Question | Answer / Decision | Owner | Resolution Date | | --- | --- | --- | --- | --- | -| Q-1 | Should `explore-context` include web research by default, or only when the user asks or current information matters? | Decided: no. `explore-context` covers local code, project docs, attached artifacts, and repository context only. Web search and browsing are out of scope. | Oleg Shulyakov | 2026-05-21 | -| Q-2 | Should `remember-context` ask before writing memory, or write automatically when the user explicitly asks to remember something? | Decided: explicit user requests to remember context are auto-approved. The skill should write without asking again, while still filtering for durable project value and avoiding sensitive, transient, or unverifiable notes. | Oleg Shulyakov | 2026-05-21 | -| Q-3 | Should these skills use neutral names (`plan-work`) or verb-first names (`plan-general`, `research-context`)? | Decided: keep simple names because they are standalone cognitive modes. | Oleg Shulyakov | 2026-05-21 | -| Q-4 | Should `plan-work` create task files, or only produce conversational plans unless paired with another writing skill? | Decided: conversational by default; durable task files require explicit user request or substantial work. | Oleg Shulyakov | 2026-05-21 | -| Q-5 | Should the coordination skill be named `coordinate-work`, `lead`, or `manage`? | Decided: `coordinate-work`, because it is plain, action-oriented, and covers team-leading, delegation, status, and multi-agent coordination without implying people-management authority. | Oleg Shulyakov | 2026-05-21 | -| Q-6 | Should the ambiguous-problem skill be named `reason-problem`, `think`, or `brainstorm`? | Decided: `reason-problem`, because it covers brainstorming, framing, assumptions, and argument-testing without being limited to idea generation. | Oleg Shulyakov | 2026-05-21 | -| Q-7 | Should question generation be its own skill or part of `reason-problem`? | Decided: keep `ask-questions` separate because identifying the right questions is a distinct output and often useful before any reasoning path is chosen. | Oleg Shulyakov | 2026-05-21 | -| Q-8 | Should grouping be named `classify-content`, `sort`, or `categorize`? | Decided: `classify-content`, because it covers category assignment, similarity/difference grouping, taxonomies, and edge cases more precisely than `sort`. | Oleg Shulyakov | 2026-05-21 | +| Q-1 | Should `explore` include web research by default, or only when the user asks or current information matters? | Decided: no. `explore` covers local code, project docs, attached artifacts, and repository context only. Web search and browsing are out of scope. | Oleg Shulyakov | 2026-05-21 | +| Q-2 | Should `remember` ask before writing memory, or write automatically when the user explicitly asks to remember something? | Decided: explicit user requests to remember context are auto-approved. The skill should write without asking again, while still filtering for durable project value and avoiding sensitive, transient, or unverifiable notes. | Oleg Shulyakov | 2026-05-21 | +| Q-3 | Should these skills use neutral names (`plan`) or verb-first names (`plan-general`, `research-context`)? | Decided: keep simple names because they are standalone cognitive modes. | Oleg Shulyakov | 2026-05-21 | +| Q-4 | Should `plan` create task files, or only produce conversational plans unless paired with another writing skill? | Decided: conversational by default; durable task files require explicit user request or substantial work. | Oleg Shulyakov | 2026-05-21 | +| Q-5 | Should the coordination skill be named `manage`, `lead`, or `manage`? | Decided: `manage`, because it is plain, action-oriented, and covers team-leading, delegation, status, and multi-agent coordination without implying people-management authority. | Oleg Shulyakov | 2026-05-21 | +| Q-6 | Should the ambiguous-problem skill be named `brainstorm`, `think`, or `brainstorm`? | Decided: `brainstorm`, because it covers brainstorming, framing, assumptions, and argument-testing without being limited to idea generation. | Oleg Shulyakov | 2026-05-21 | +| Q-7 | Should question generation be its own skill or part of `brainstorm`? | Decided: keep `ask` separate because identifying the right questions is a distinct output and often useful before any reasoning path is chosen. | Oleg Shulyakov | 2026-05-21 | +| Q-8 | Should grouping be named `classify`, `sort`, or `categorize`? | Decided: `classify`, because it covers category assignment, similarity/difference grouping, taxonomies, and edge cases more precisely than `sort`. | Oleg Shulyakov | 2026-05-21 | | Q-9 | Should the evidence-driven change-detection skill be named `evolve` or `adapt`? | Decided: `adapt`, because it detects when existing behavior or artifacts no longer fit observed evidence without implying autonomous self-modification. | Oleg Shulyakov | 2026-05-24 | -| Q-10 | Should `adapt` perform the actual update to skills, rules, docs, evals, or memory? | Decided: no. `adapt` diagnoses the need and routes the update; artifact-specific skills such as `create-skill`, `create-rule`, `write-*`, `build-tests`, or `remember-context` perform the actual change when requested. | Oleg Shulyakov | 2026-05-24 | +| Q-10 | Should `adapt` perform the actual update to skills, rules, docs, evals, or memory? | Decided: no. `adapt` diagnoses the need and routes the update; artifact-specific skills such as `create-skill`, `create-rule`, `write-*`, `code-tests`, or `remember` perform the actual change when requested. | Oleg Shulyakov | 2026-05-24 | --- diff --git a/docs/2026-05-20-general-agent-skills/SPEC.md b/docs/2026-05-20-general-agent-skills/SPEC.md index a416ef1..3496c93 100644 --- a/docs/2026-05-20-general-agent-skills/SPEC.md +++ b/docs/2026-05-20-general-agent-skills/SPEC.md @@ -19,7 +19,7 @@ related: ### 1.1 Purpose -This spec defines the implementation contract for ten standalone, general-purpose agent skills: `ask-questions`, `explain-topic`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, and `adapt`. +This spec defines the implementation contract for ten standalone, general-purpose agent skills: `ask`, `explain`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, and `adapt`. The goal is to make common collaboration modes predictable at runtime without requiring any skill to depend on another installed skill. @@ -27,7 +27,7 @@ The goal is to make common collaboration modes predictable at runtime without re The existing skill library covers specialized creation, coding, review, documentation, and operations workflows. It has a remaining gap for project-agnostic thinking modes that recur across repositories and tasks. -Without explicit skills for these modes, the agent must infer broad behavior from generic instructions each time. That creates inconsistent trigger behavior, unclear output shapes, and accidental overlap between similar modes such as `plan-work` and `coordinate-work`, or `ask-questions` and `reason-problem`. +Without explicit skills for these modes, the agent must infer broad behavior from generic instructions each time. That creates inconsistent trigger behavior, unclear output shapes, and accidental overlap between similar modes such as `plan` and `manage`, or `ask` and `brainstorm`. This work creates a small general layer with clear trigger boundaries, exclusions, expected behavior, and eval prompts for each skill. @@ -50,14 +50,14 @@ Success means a user can install any one of the ten skills independently and get | Goal | Success Metric | Target | | --- | --- | --- | -| Minimal general skill set | Ten skills exist with approved names | `ask-questions`, `explain-topic`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, `adapt` | +| Minimal general skill set | Ten skills exist with approved names | `ask`, `explain`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, `adapt` | | Standalone runtime behavior | No skill requires another skill to be installed, called, imported, or delegated to | 100% of skills | | Predictable triggers | Each skill documents triggers, exclusions, expected behavior, and eval prompts | 8-10 eval prompts where possible, never fewer than 7 | | Lightweight packaging | Main `SKILL.md` files remain concise | Under 500 lines each | ### 1.6 Non-Goals -This work does not add live integrations with Jira, Linear, Confluence, GitHub Issues, or external memory stores. It does not add web search behavior to `explore-context`, automatic memory writes without durable value, a shared trigger-overlap eval harness, or replacements for project-level `AGENTS.md` instructions. +This work does not add live integrations with Jira, Linear, Confluence, GitHub Issues, or external memory stores. It does not add web search behavior to `explore`, automatic memory writes without durable value, a shared trigger-overlap eval harness, or replacements for project-level `AGENTS.md` instructions. --- @@ -109,36 +109,36 @@ Each skill body shall define purpose, scope, trigger cases, non-trigger cases, w ### 2.4 Per-Skill Behavior Requirements -#### FR-001: `ask-questions` +#### FR-001: `ask` **Priority:** Must-have -**Description:** The system shall use `ask-questions` for question generation, clarification, missing-context discovery, and assumption surfacing. +**Description:** The system shall use `ask` for question generation, clarification, missing-context discovery, and assumption surfacing. **Acceptance criteria:** -- [ ] Triggers on "ask-questions", "what should I ask", "right questions", "what are we missing", "clarify this", and ambiguous requests blocked by missing context. +- [ ] Triggers on "ask", "what should I ask", "right questions", "what are we missing", "clarify this", and ambiguous requests blocked by missing context. - [ ] Produces a minimal prioritized set of high-leverage questions. - [ ] States assumptions and context gaps when useful. - [ ] Avoids exhaustive questionnaires unless explicitly requested. - [ ] Does not make decisions, plans, or implementation changes as its primary output. -#### FR-002: `explain-topic` +#### FR-002: `explain` **Priority:** Must-have -**Description:** The system shall use `explain-topic` for teaching, clarification, walkthroughs, concepts, code behavior, architecture, tradeoffs, and decisions. +**Description:** The system shall use `explain` for teaching, clarification, walkthroughs, concepts, code behavior, architecture, tradeoffs, and decisions. **Acceptance criteria:** -- [ ] Triggers on "explain-topic", "what is", "why", "how does", "walk me through", and direct explanation requests. +- [ ] Triggers on "explain", "what is", "why", "how does", "walk me through", and direct explanation requests. - [ ] Matches depth to the user's question and available context. - [ ] For code explanations, inspects relevant local files before describing repository behavior. - [ ] Marks uncertainty when evidence is incomplete. - [ ] Does not implement, review, or plan unless the user asks for that additional work. -#### FR-003: `reason-problem` +#### FR-003: `brainstorm` **Priority:** Must-have -**Description:** The system shall use `reason-problem` to work through ambiguous problems before a firm output shape, decision, or plan is warranted. +**Description:** The system shall use `brainstorm` to work through ambiguous problems before a firm output shape, decision, or plan is warranted. **Acceptance criteria:** @@ -148,75 +148,75 @@ Each skill body shall define purpose, scope, trigger cases, non-trigger cases, w - [ ] Ends with a clearer framing or next clarity step. - [ ] Distinguishes facts, assumptions, and opinions. -#### FR-004: `classify-content` +#### FR-004: `classify` **Priority:** Must-have -**Description:** The system shall use `classify-content` to organize material into meaningful groups. +**Description:** The system shall use `classify` to organize material into meaningful groups. **Acceptance criteria:** -- [ ] Triggers on "classify-content", "categorize", "group", "cluster", "sort", "taxonomy", "organize these", and requests to group by explicit criteria. +- [ ] Triggers on "classify", "categorize", "group", "cluster", "sort", "taxonomy", "organize these", and requests to group by explicit criteria. - [ ] States grouping criteria before or alongside the classification. - [ ] Labels groups clearly and places items into them. - [ ] Preserves ambiguous, multi-fit, or unclassified items instead of forcing false precision. - [ ] Supports grouping by similarity, difference, category, priority, dependency, abstraction level, or user-provided criteria. -#### FR-005: `plan-work` +#### FR-005: `plan` **Priority:** Must-have -**Description:** The system shall use `plan-work` to sequence work before execution. +**Description:** The system shall use `plan` to sequence work before execution. **Acceptance criteria:** -- [ ] Triggers on "plan-work", "break this down", "roadmap", "approach", "milestones", and "how should we proceed". +- [ ] Triggers on "plan", "break this down", "roadmap", "approach", "milestones", and "how should we proceed". - [ ] Produces scoped steps, milestones, dependencies, assumptions, risks, and verification strategy when relevant. - [ ] Defaults to conversational planning unless durable files are explicitly requested or the task clearly needs them. - [ ] Does not coordinate live owners, blockers, handoffs, or active workstreams as its primary behavior. - [ ] Identifies when more context is required before a reliable plan can be made. -#### FR-006: `explore-context` +#### FR-006: `explore` **Priority:** Must-have -**Description:** The system shall use `explore-context` for local repository, local document, and attached-artifact investigation. +**Description:** The system shall use `explore` for local repository, local document, and attached-artifact investigation. **Acceptance criteria:** -- [ ] Triggers on "explore-context", "investigate", "find where", "understand this repo", "trace", and local-context research requests. +- [ ] Triggers on "explore", "investigate", "find where", "understand this repo", "trace", and local-context research requests. - [ ] Searches local files, project docs, attached artifacts, and repository context only. - [ ] Uses file references, artifact references, and command evidence for findings. - [ ] Distinguishes verified facts from inference. - [ ] Does not perform web search or browsing as part of this skill. -#### FR-007: `decide-direction` +#### FR-007: `choose` **Priority:** Must-have -**Description:** The system shall use `decide-direction` to compare options and recommend a direction. +**Description:** The system shall use `choose` to compare options and recommend a direction. **Acceptance criteria:** -- [ ] Triggers on "decide-direction", "choose", "which option", "tradeoffs", "recommend", and "should we". +- [ ] Triggers on "choose", "choose", "which option", "tradeoffs", "recommend", and "should we". - [ ] States decision criteria before or alongside the comparison. - [ ] Compares viable options against the criteria. - [ ] Recommends one option when evidence supports a recommendation. - [ ] Notes assumptions, risks, tradeoffs, and reversibility. -#### FR-008: `coordinate-work` +#### FR-008: `manage` **Priority:** Must-have -**Description:** The system shall use `coordinate-work` to manage active work across people, agents, tasks, dependencies, blockers, and handoffs. +**Description:** The system shall use `manage` to manage active work across people, agents, tasks, dependencies, blockers, and handoffs. **Acceptance criteria:** -- [ ] Triggers on "coordinate-work", "manage this work", "team lead", "lead this", "assign", "delegate", "track blockers", "status", "handoff", and multi-agent or multi-workstream requests. +- [ ] Triggers on "manage", "manage this work", "team lead", "lead this", "assign", "delegate", "track blockers", "status", "handoff", and multi-agent or multi-workstream requests. - [ ] Maintains an execution view with goals, owners, dependencies, current status, blockers, and next actions. - [ ] Separates active coordination from pre-execution planning. - [ ] Makes handoff state clear enough for another human or agent to continue. - [ ] Does not silently assign real people to work without user-provided ownership or clear assumptions. -#### FR-009: `remember-context` +#### FR-009: `remember` **Priority:** Must-have -**Description:** The system shall use `remember-context` to preserve durable project facts, decisions, and useful observations in `.agents/memory/`. +**Description:** The system shall use `remember` to preserve durable project facts, decisions, and useful observations in `.agents/memory/`. **Acceptance criteria:** @@ -238,7 +238,7 @@ Each skill body shall define purpose, scope, trigger cases, non-trigger cases, w - [ ] Distinguishes durable evidence-driven change needs from one-off exceptions. - [ ] Identifies the affected behavior or artifact, such as a skill, rule, workflow, document, eval, memory convention, or process. - [ ] Recommends the smallest useful change and the appropriate follow-up skill or workflow for the actual update. -- [ ] Does not directly rewrite artifacts by default; actual updates belong to artifact-specific skills such as `create-skill`, `create-rule`, `write-*`, `build-tests`, or `remember-context` when the user asks to proceed. +- [ ] Does not directly rewrite artifacts by default; actual updates belong to artifact-specific skills such as `create-skill`, `create-rule`, `write-*`, `code-tests`, or `remember` when the user asks to proceed. #### FR-011: Standalone Runtime Boundaries @@ -268,13 +268,13 @@ Each skill body shall define purpose, scope, trigger cases, non-trigger cases, w ### 2.5 Business Rules -**BR-001:** Skill names are fixed as `ask-questions`, `explain-topic`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, and `adapt`. +**BR-001:** Skill names are fixed as `ask`, `explain`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, and `adapt`. **BR-002:** Runtime behavior must be standalone. Development-time validation may use existing creator or packaging workflows, but installed skill behavior must not depend on them. -**BR-003:** `explore-context` is local-only. Web search, browsing, and current-information research are out of scope. +**BR-003:** `explore` is local-only. Web search, browsing, and current-information research are out of scope. -**BR-004:** `remember-context` may write memory automatically only when the user explicitly asks to remember or preserve something. +**BR-004:** `remember` may write memory automatically only when the user explicitly asks to remember or preserve something. **BR-005:** `adapt` detects and routes evidence-driven change needs. It shall not directly rewrite skills, rules, docs, evals, or memory by default. @@ -287,12 +287,12 @@ Each skill body shall define purpose, scope, trigger cases, non-trigger cases, w | Category | Requirement | Target | Priority | | --- | --- | --- | --- | | Maintainability | Each skill has one clear workflow and avoids becoming a generic behavior dump | Reviewer can summarize each skill in one sentence | High | -| Portability | Skills work across repositories without assuming this repo layout, except `remember-context` memory conventions | No hard dependency on project-specific files outside documented exceptions | High | +| Portability | Skills work across repositories without assuming this repo layout, except `remember` memory conventions | No hard dependency on project-specific files outside documented exceptions | High | | Token efficiency | Main skill files stay concise | Under 500 lines per `SKILL.md` | High | | Trigger accuracy | Trigger and exclusion rules are explicit | Evals include positive, false-positive, and non-trigger prompts | High | -| Source discipline | `explore-context` cites local evidence and marks inference | Findings include file/artifact references when available | High | -| Memory hygiene | `remember-context` stores only durable value | No transient chatter or sensitive data in memory notes | High | -| Coordination clarity | `coordinate-work` preserves execution state | Goals, owners, status, blockers, dependencies, and next actions are explicit | Medium | +| Source discipline | `explore` cites local evidence and marks inference | Findings include file/artifact references when available | High | +| Memory hygiene | `remember` stores only durable value | No transient chatter or sensitive data in memory notes | High | +| Coordination clarity | `manage` preserves execution state | Goals, owners, status, blockers, dependencies, and next actions are explicit | Medium | | Adaptation discipline | `adapt` diagnoses evidence-driven change needs without becoming a generic update workflow | Actual artifact changes are routed to the appropriate follow-up skill or workflow | High | --- @@ -320,7 +320,7 @@ flowchart TD | `.agents/skills//SKILL.md` | Runtime instructions, metadata, trigger guidance, exclusions, workflow, and output expectations | | `.agents/skills//evals/evals.json` | Representative trigger and non-trigger prompts generated through `create-skill` | | `.agents/skills//evals/iterations/iteration-N/` | Reproducible eval run outputs, grading, and benchmark artifacts when generated | -| `.agents/memory/` | Target memory location for `remember-context` behavior | +| `.agents/memory/` | Target memory location for `remember` behavior | | `.agents/skills/create-skill/` | Development-time eval generation, validation, and packaging support | ### 4.3 Key Design Decisions @@ -328,7 +328,7 @@ flowchart TD **Decision: Use simple cognitive-mode names.** Chosen names are short and direct because the PRD resolved naming in favor of standalone cognitive modes. The tradeoff is that trigger boundaries must be especially explicit to avoid overlap. -**Decision: Keep `explore-context` local-only.** +**Decision: Keep `explore` local-only.** This prevents accidental current-information research and keeps the skill portable across disconnected or restricted environments. The tradeoff is that users must invoke another workflow for web research. **Decision: Treat explicit memory requests as approval.** @@ -343,7 +343,7 @@ Per-skill eval files keep each installable unit self-contained. A shared overlap No database or structured runtime data model is added. -The only persistent output introduced by skill behavior is `remember-context` writing Markdown entries under `.agents/memory/` according to existing conventions. +The only persistent output introduced by skill behavior is `remember` writing Markdown entries under `.agents/memory/` according to existing conventions. Memory entries shall use one of these categories when applicable: facts, preferences, decisions, or observations. Decision entries should include context, decision, and revisit conditions when those details are available. @@ -351,25 +351,25 @@ Memory entries shall use one of these categories when applicable: facts, prefere ## 6. Security, Privacy, and Safety -Skills shall not request, store, or expose secrets. `remember-context` shall avoid writing credentials, tokens, private personal information, transient task chatter, or unverifiable assumptions as fact. +Skills shall not request, store, or expose secrets. `remember` shall avoid writing credentials, tokens, private personal information, transient task chatter, or unverifiable assumptions as fact. -`explore-context` shall not use web browsing, web search, external services, or live integrations. Its findings shall be based on local repository files, local docs, attached artifacts, or clearly marked inference. +`explore` shall not use web browsing, web search, external services, or live integrations. Its findings shall be based on local repository files, local docs, attached artifacts, or clearly marked inference. -Skills shall avoid presenting subjective recommendations as facts. `reason-problem` and `decide-direction` shall distinguish assumptions, evidence, opinion, and uncertainty. +Skills shall avoid presenting subjective recommendations as facts. `brainstorm` and `choose` shall distinguish assumptions, evidence, opinion, and uncertainty. --- ## 7. Error Paths and Edge Cases -If a user request matches multiple skills, the selected skill shall explain the dominant intent through its output shape, not through a long routing discussion. For example, "Should we plan this migration or split it?" should favor `decide-direction` if the user needs a choice, and `plan-work` if the choice is already settled. +If a user request matches multiple skills, the selected skill shall explain the dominant intent through its output shape, not through a long routing discussion. For example, "Should we plan this migration or split it?" should favor `choose` if the user needs a choice, and `plan` if the choice is already settled. -If required local evidence is missing, `explore-context` and `explain-topic` shall report what was inspected, what could not be verified, and the best-supported inference. +If required local evidence is missing, `explore` and `explain` shall report what was inspected, what could not be verified, and the best-supported inference. -If `remember-context` receives content that is explicit but not durable, sensitive, or unverifiable, it shall decline the memory write briefly and explain the reason. +If `remember` receives content that is explicit but not durable, sensitive, or unverifiable, it shall decline the memory write briefly and explain the reason. -If `coordinate-work` lacks owners, it shall use unassigned workstreams or assumed role labels instead of inventing real ownership. +If `manage` lacks owners, it shall use unassigned workstreams or assumed role labels instead of inventing real ownership. -If `classify-content` receives items that do not fit a single category, it shall use an ambiguous, multi-label, or needs-review grouping rather than forcing a clean bucket. +If `classify` receives items that do not fit a single category, it shall use an ambiguous, multi-label, or needs-review grouping rather than forcing a clean bucket. --- @@ -397,14 +397,14 @@ Boundary prompts shall specifically test likely overlaps: | Boundary | Expected Distinction | | --- | --- | -| `ask-questions` vs `reason-problem` | `ask-questions` produces questions; `reason-problem` develops framing and hypotheses | -| `reason-problem` vs `decide-direction` | `reason-problem` clarifies ambiguity; `decide-direction` recommends between options | -| `plan-work` vs `coordinate-work` | `plan-work` sequences future work; `coordinate-work` tracks active workstreams and handoffs | -| `explain-topic` vs `explore-context` | `explain-topic` teaches; `explore-context` investigates local evidence | -| `classify-content` vs `decide-direction` | `classify-content` groups material; `decide-direction` chooses a direction | -| `remember-context` vs docs writing | `remember-context` captures durable memory; docs writing creates formal project artifacts | +| `ask` vs `brainstorm` | `ask` produces questions; `brainstorm` develops framing and hypotheses | +| `brainstorm` vs `choose` | `brainstorm` clarifies ambiguity; `choose` recommends between options | +| `plan` vs `manage` | `plan` sequences future work; `manage` tracks active workstreams and handoffs | +| `explain` vs `explore` | `explain` teaches; `explore` investigates local evidence | +| `classify` vs `choose` | `classify` groups material; `choose` chooses a direction | +| `remember` vs docs writing | `remember` captures durable memory; docs writing creates formal project artifacts | | `adapt` vs `create-skill` / `create-rule` / docs writing | `adapt` identifies what should change and routes the update; artifact-specific skills perform the actual update | -| `adapt` vs `remember-context` | `adapt` identifies future behavior or artifact changes; `remember-context` preserves durable facts and decisions | +| `adapt` vs `remember` | `adapt` identifies future behavior or artifact changes; `remember` preserves durable facts and decisions | ### 8.4 Manual Acceptance @@ -416,8 +416,8 @@ Manual acceptance passes when a reviewer can invoke representative prompts and o ### Phase 1: Skill Boundaries -- [ ] Draft `SKILL.md` for `ask-questions`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, and `adapt`. -- [x] Treat existing `explain-topic` as complete for this work. +- [ ] Draft `SKILL.md` for `ask`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, and `adapt`. +- [x] Treat existing `explain` as complete for this work. - [ ] Confirm each skill has clear trigger and non-trigger rules. ### Phase 2: Evals @@ -445,7 +445,7 @@ Manual acceptance passes when a reviewer can invoke representative prompts and o | Dependency | Needed By | | --- | --- | | Existing skill authoring conventions | All skill files | -| Existing `.agents/memory/` conventions | `remember-context` | +| Existing `.agents/memory/` conventions | `remember` | | `.agents/skills/create-skill/` eval generation workflow | Evals and release readiness | --- @@ -468,7 +468,7 @@ Manual acceptance passes when a reviewer can invoke representative prompts and o | # | Question | Owner | Due | Status | | --- | --- | --- | --- | --- | | 1 | Should eval prompts be plain Markdown or a machine-readable format? | Oleg Shulyakov | 2026-05-21 | Resolved: evals are generated by `.agents/skills/create-skill/`. | -| 2 | Should `explain-topic` be treated as already complete or revised to match the new general skill set style? | Oleg Shulyakov | 2026-05-21 | Resolved: mark `explain-topic` as complete. | +| 2 | Should `explain` be treated as already complete or revised to match the new general skill set style? | Oleg Shulyakov | 2026-05-21 | Resolved: mark `explain` as complete. | | 3 | Should every new skill use version `1.0.0`, or inherit a project-wide initial version convention? | Oleg Shulyakov | 2026-05-21 | Resolved: use `1.0.0` as the initial version. | | 4 | Should the evidence-driven change-detection skill be named `evolve` or `adapt`? | Oleg Shulyakov | 2026-05-24 | Resolved: use `adapt`, because it detects that existing behavior no longer fits evidence without implying autonomous self-modification. | | 5 | Should `adapt` perform the actual updates it identifies? | Oleg Shulyakov | 2026-05-24 | Resolved: no. It diagnoses and routes updates to artifact-specific skills or workflows. | @@ -482,4 +482,4 @@ Related documents: - [PRD.md](PRD.md) - `.agents/memory/MEMORY.md` - `.agents/skills/create-skill/SKILL.md` -- `.agents/skills/explain-topic/SKILL.md` +- `.agents/skills/explain/SKILL.md` diff --git a/docs/2026-05-20-general-agent-skills/user-stories/US-001-author-standalone-general-skills.md b/docs/2026-05-20-general-agent-skills/user-stories/US-001-author-standalone-general-skills.md index 6ab69ea..4a8441a 100644 --- a/docs/2026-05-20-general-agent-skills/user-stories/US-001-author-standalone-general-skills.md +++ b/docs/2026-05-20-general-agent-skills/user-stories/US-001-author-standalone-general-skills.md @@ -14,20 +14,20 @@ Source documents: - **Persona:** As a skill library maintainer, - **Action:** I want the missing general-purpose agent skills authored as standalone installable skill folders, - **Outcome:** so that users can invoke consistent collaboration modes without hidden runtime dependencies. -- **Epic Context:** Implements the approved General Agent Skills PRD/SPEC by creating `ask-questions`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, and `adapt`. Existing `explain-topic` is already complete and must not be rewritten unless validation reveals a spec violation. +- **Epic Context:** Implements the approved General Agent Skills PRD/SPEC by creating `ask`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, and `adapt`. Existing `explain` is already complete and must not be rewritten unless validation reveals a spec violation. --- ## 🔍 2. Strict Constraints & Scope Boundaries - **In-Scope:** - - Create `.agents/skills//SKILL.md` for `ask-questions`, `reason-problem`, `classify-content`, `plan-work`, `explore-context`, `decide-direction`, `coordinate-work`, `remember-context`, and `adapt`. + - Create `.agents/skills//SKILL.md` for `ask`, `brainstorm`, `classify`, `plan`, `explore`, `choose`, `manage`, `remember`, and `adapt`. - Use initial skill version `1.0.0`. - Include frontmatter fields required by local skill conventions. - Define each skill's purpose, trigger cases, non-trigger cases, workflow, output expectations, error paths, and verification guidance where relevant. - Keep every skill independently installable and runtime-standalone. - **Out-of-Scope (Do NOT implement):** - - Do not modify `explain-topic` unless a direct mismatch with the approved SPEC is found and documented. + - Do not modify `explain` unless a direct mismatch with the approved SPEC is found and documented. - Do not add live Jira, Linear, Confluence, GitHub Issues, web browsing, web search, or external memory integrations. - Do not create placeholder `references/`, `scripts/`, or `assets/` folders. - Do not make one skill delegate to another skill at runtime. @@ -74,19 +74,19 @@ Scenario: Avoid placeholder support folders *Note to Agent: You are restricted to modifying or analyzing the following components.* - **Primary Target Files:** - 1. `.agents/skills/ask-questions/SKILL.md` -> New question-generation skill. - 2. `.agents/skills/reason-problem/SKILL.md` -> New ambiguous-problem reasoning skill. - 3. `.agents/skills/classify-content/SKILL.md` -> New classification and grouping skill. - 4. `.agents/skills/plan-work/SKILL.md` -> New planning skill. - 5. `.agents/skills/explore-context/SKILL.md` -> New local investigation skill. - 6. `.agents/skills/decide-direction/SKILL.md` -> New decision support skill. - 7. `.agents/skills/coordinate-work/SKILL.md` -> New coordination skill. - 8. `.agents/skills/remember-context/SKILL.md` -> New durable memory skill. + 1. `.agents/skills/ask/SKILL.md` -> New question-generation skill. + 2. `.agents/skills/brainstorm/SKILL.md` -> New ambiguous-problem reasoning skill. + 3. `.agents/skills/classify/SKILL.md` -> New classification and grouping skill. + 4. `.agents/skills/plan/SKILL.md` -> New planning skill. + 5. `.agents/skills/explore/SKILL.md` -> New local investigation skill. + 6. `.agents/skills/choose/SKILL.md` -> New decision support skill. + 7. `.agents/skills/manage/SKILL.md` -> New coordination skill. + 8. `.agents/skills/remember/SKILL.md` -> New durable memory skill. 9. `.agents/skills/adapt/SKILL.md` -> New evidence-driven adaptation diagnosis and routing skill. - **Shared Dependencies/Imports:** - Follow `.agents/skills/create-skill/references/authoring.md`. - Use [SPEC.md](../SPEC.md) as the implementation contract. - - Treat `.agents/skills/explain-topic/SKILL.md` as complete. + - Treat `.agents/skills/explain/SKILL.md` as complete. --- @@ -108,5 +108,5 @@ Scenario: Avoid placeholder support folders - [ ] **Compilation:** Not applicable; Markdown authoring only. - [ ] **Test Coverage:** New skill files are ready for eval generation in US-002. -- [ ] **No Regression:** Existing `.agents/skills/explain-topic/SKILL.md` remains unchanged unless a documented spec mismatch required a fix. +- [ ] **No Regression:** Existing `.agents/skills/explain/SKILL.md` remains unchanged unless a documented spec mismatch required a fix. - [ ] **Idempotency:** Re-running the work does not duplicate folders, sections, or placeholder resources. diff --git a/docs/2026-05-20-general-agent-skills/user-stories/US-002-generate-skill-evals.md b/docs/2026-05-20-general-agent-skills/user-stories/US-002-generate-skill-evals.md index 1a33f95..721a95f 100644 --- a/docs/2026-05-20-general-agent-skills/user-stories/US-002-generate-skill-evals.md +++ b/docs/2026-05-20-general-agent-skills/user-stories/US-002-generate-skill-evals.md @@ -69,14 +69,14 @@ Scenario: Preserve eval folder discipline *Note to Agent: You are restricted to modifying or analyzing the following components.* - **Primary Target Files:** - 1. `.agents/skills/ask-questions/evals/evals.json` -> Trigger and output evals. - 2. `.agents/skills/reason-problem/evals/evals.json` -> Trigger and output evals. - 3. `.agents/skills/classify-content/evals/evals.json` -> Trigger and output evals. - 4. `.agents/skills/plan-work/evals/evals.json` -> Trigger and output evals. - 5. `.agents/skills/explore-context/evals/evals.json` -> Trigger and output evals. - 6. `.agents/skills/decide-direction/evals/evals.json` -> Trigger and output evals. - 7. `.agents/skills/coordinate-work/evals/evals.json` -> Trigger and output evals. - 8. `.agents/skills/remember-context/evals/evals.json` -> Trigger and output evals. + 1. `.agents/skills/ask/evals/evals.json` -> Trigger and output evals. + 2. `.agents/skills/brainstorm/evals/evals.json` -> Trigger and output evals. + 3. `.agents/skills/classify/evals/evals.json` -> Trigger and output evals. + 4. `.agents/skills/plan/evals/evals.json` -> Trigger and output evals. + 5. `.agents/skills/explore/evals/evals.json` -> Trigger and output evals. + 6. `.agents/skills/choose/evals/evals.json` -> Trigger and output evals. + 7. `.agents/skills/manage/evals/evals.json` -> Trigger and output evals. + 8. `.agents/skills/remember/evals/evals.json` -> Trigger and output evals. 9. `.agents/skills/adapt/evals/evals.json` -> Trigger and output evals. - **Shared Dependencies/Imports:** - Follow `.agents/skills/create-skill/references/evaluation.md`. diff --git a/docs/2026-05-23-design-principles/PRD.md b/docs/2026-05-23-design-principles/PRD.md index 02cdd48..9124618 100644 --- a/docs/2026-05-23-design-principles/PRD.md +++ b/docs/2026-05-23-design-principles/PRD.md @@ -34,7 +34,7 @@ Without this integration, agents may apply principles inconsistently: overusing | Goal ID | Target Outcome | Success Metric | | --- | --- | --- | | G-1 | Establish a shared engineering-principles rule for `.agents`. | One concise global rule exists under `.agents/rules/` and is referenced by implementation-facing skills where useful. | -| G-2 | Make principles operational in code-writing and code-review workflows. | `build-backend`, `build-frontend`, `build-database`, `build-tests`, `review-code`, and `create-skill` apply relevant principle lenses without duplicating the full source document. | +| G-2 | Make principles operational in code-writing and code-review workflows. | `code-backend`, `code-frontend`, `code-database`, `code-tests`, `review-code`, and `create-skill` apply relevant principle lenses without duplicating the full source document. | | G-3 | Keep runtime instructions token-efficient. | New or edited runtime guidance is concise and avoids copying the entire collected principles list into every skill. | | G-4 | Preserve pragmatic judgment. | Guidance explicitly treats KISS and YAGNI as default brakes, DRY as knowledge deduplication, and SOLID as useful only when it reduces real coupling or change risk. | @@ -82,7 +82,7 @@ Without this integration, agents may apply principles inconsistently: overusing | FR-3 | Clarify DRY behavior. | MUST | Guidance distinguishes duplicated knowledge or business logic from harmless repeated syntax, markup, or test setup. | TBD | | FR-4 | Clarify SOLID behavior. | MUST | Guidance applies SRP, ISP, DIP, and related principles through clear responsibilities, small interfaces, and explicit dependencies without adding ceremonial layers. | TBD | | FR-5 | Scope Boy Scout cleanup. | MUST | Guidance allows cleanup only in touched code or code required for the requested change, and forbids unrelated opportunistic refactors. | TBD | -| FR-6 | Add principle lenses to implementation skills. | SHOULD | `build-backend`, `build-frontend`, `build-database`, and `build-tests` contain targeted principle guidance only where it changes implementation behavior. | TBD | +| FR-6 | Add principle lenses to implementation skills. | SHOULD | `code-backend`, `code-frontend`, `code-database`, and `code-tests` contain targeted principle guidance only where it changes implementation behavior. | TBD | | FR-7 | Add principle lenses to review and skill-authoring workflows. | SHOULD | `review-code` and `create-skill` can identify over-abstraction, duplicated knowledge, unclear responsibilities, leaky dependencies, and untestable side effects as concrete issues. | TBD | | FR-8 | Add focused eval coverage. | COULD | At least one eval or test prompt verifies the agent rejects speculative abstraction and one verifies it flags duplicated business rules over duplicated text. | TBD | @@ -146,7 +146,7 @@ Without this integration, agents may apply principles inconsistently: overusing | Question ID | Question | Answer / Decision | Owner | Resolution Date | | --- | --- | --- | --- | --- | | Q-1 | Should this be only a global rule, or also a standalone skill? | Proposed: start as a global rule; create a skill only if users ask to reason explicitly about engineering principles. | Oleg Shulyakov | TBD | -| Q-2 | Which skills should receive direct updates in the first implementation pass? | Proposed: `build-backend`, `build-frontend`, `build-database`, `build-tests`, `review-code`, and `create-skill`. | Oleg Shulyakov | TBD | +| Q-2 | Which skills should receive direct updates in the first implementation pass? | Proposed: `code-backend`, `code-frontend`, `code-database`, `code-tests`, `review-code`, and `create-skill`. | Oleg Shulyakov | TBD | | Q-3 | Should eval coverage be added now or after the first rule/skill update? | TBD | Oleg Shulyakov | TBD | --- diff --git a/docs/2026-05-23-design-principles/SPEC.md b/docs/2026-05-23-design-principles/SPEC.md index c48b756..0bb23fa 100644 --- a/docs/2026-05-23-design-principles/SPEC.md +++ b/docs/2026-05-23-design-principles/SPEC.md @@ -28,7 +28,7 @@ This spec defines how to integrate common engineering principles into `.agents` The source document `Most Popular Principles.md` lists SOLID, DRY, KISS, YAGNI, Law of Demeter, Composition Over Inheritance, Boy Scout Rule, CQS, and Separation of Concerns. It correctly frames these as skills disguised as rules: useful guardrails that require judgment. -The existing `.agents` library already contains overlapping guidance in `karpathy-guidelines`, `build-backend`, `build-frontend`, `review-code`, and `create-skill`. The implementation should therefore avoid duplicating definitions and instead add a small shared rule plus targeted skill patches. +The existing `.agents` library already contains overlapping guidance in `karpathy-guidelines`, `code-backend`, `code-frontend`, `review-code`, and `create-skill`. The implementation should therefore avoid duplicating definitions and instead add a small shared rule plus targeted skill patches. ### 1.3 Roles & Responsibilities @@ -158,10 +158,10 @@ Users rely on this skill library to produce code, reviews, docs, and agent artif **Description:** The system shall update selected build skills with targeted principle behavior. **Acceptance criteria:** -- [ ] `build-backend` preserves or improves its existing pragmatic SOLID guidance without duplicating the new rule. -- [ ] `build-frontend` includes principle guidance only where it affects components, state, effects, or shared abstractions. -- [ ] `build-database` includes principle guidance where it affects schema ownership, duplicated business rules, migrations, and query responsibilities. -- [ ] `build-tests` includes principle guidance where it affects test abstraction, duplicated setup, side effects, and maintainability. +- [ ] `code-backend` preserves or improves its existing pragmatic SOLID guidance without duplicating the new rule. +- [ ] `code-frontend` includes principle guidance only where it affects components, state, effects, or shared abstractions. +- [ ] `code-database` includes principle guidance where it affects schema ownership, duplicated business rules, migrations, and query responsibilities. +- [ ] `code-tests` includes principle guidance where it affects test abstraction, duplicated setup, side effects, and maintainability. #### FR-007: Review and Skill-Authoring Updates @@ -207,10 +207,10 @@ The integration uses a layered documentation model: ```mermaid flowchart TD Source["Most Popular Principles.md"] --> Rule[".agents/rules/engineering-principles.md"] - Rule --> Backend["build-backend"] - Rule --> Frontend["build-frontend"] - Rule --> Database["build-database"] - Rule --> Tests["build-tests"] + Rule --> Backend["code-backend"] + Rule --> Frontend["code-frontend"] + Rule --> Database["code-database"] + Rule --> Tests["code-tests"] Rule --> Review["review-code"] Rule --> SkillAuthoring["create-skill"] ``` @@ -305,10 +305,10 @@ No personal data handling changes are expected. Verify that new wording does not ### Phase 3: Targeted Skill Updates -- [ ] Patch `build-backend` only if the new rule clarifies or replaces current principle wording. -- [ ] Patch `build-frontend` for component/state/effect abstraction guidance. -- [ ] Patch `build-database` for schema/query/rule ownership guidance. -- [ ] Patch `build-tests` for test abstraction and setup duplication guidance. +- [ ] Patch `code-backend` only if the new rule clarifies or replaces current principle wording. +- [ ] Patch `code-frontend` for component/state/effect abstraction guidance. +- [ ] Patch `code-database` for schema/query/rule ownership guidance. +- [ ] Patch `code-tests` for test abstraction and setup duplication guidance. - [ ] Patch `review-code` for actionable principle-based finding criteria. - [ ] Patch `create-skill` for skill artifact cohesion and anti-boilerplate guidance.