Feat/agent team skills upgrade - #36
Merged
Merged
Conversation
Port universal, vendor-neutral best-practice blocks from the runtime skills into the categorized source layout, preserving each file's house style. No project, ticket, sprint, or product nouns — general practices. - backend-developer: Code-level Engineering Standards (facts-only Javadoc, no narration, descriptive naming, builder beyond 6 params, Stream vs loop, algorithmic complexity, AOP for cross-cutting) + anti-pattern rows; Java micro-standards (instance vs static on a bean, cached regex Pattern, SplittableRandom for seeded RNG) in java-expertise reference. - reviewer: enforcement of those standards (process-refs BLOCKING, plus flags) + inline-comment-walk discipline; backend-review reference gains the grep scan, BAD/GOOD Javadoc, and per-flag detail. - e2e-tester cucumber reference: benchmark/stakeholder Gherkin scenarios as the proof artifact (tags, Scenario Outline + Examples); backend-tester gains a pointer to it. - solution-architect: cross-cutting concerns routed through AOP guardrail (and the inverse — no domain logic in aspects). - technical-writer: standing-agent duties (author every Conventional Commit, keep README/CHANGELOG current, release notes, PR template, CI gates, dual audiences) + new references/commit-and-docs.md. - scrum-master: orchestration rule to walk PR inline comments as the authoritative checklist.
…nces Two vendor-neutral, research-grounded, fact-checked reference libraries for the ai-engineer role agent (progressive disclosure, loaded on demand): - rag-patterns.md: chunking, embeddings, vector storage, retrieval, reranking, context assembly, evaluation, advanced patterns, anti-patterns. - agentic-workflows.md: single-agent loops, tool design, memory, multi-agent topologies, planning, reliability/control, evaluation, anti-patterns. These are the first of the LLM/RAG/multi-agent reference libraries. No project nouns; MCP version labels corrected to the real spec versions (2025-06-18).
…erences Two research-grounded, fact-checked, vendor-neutral references for the ai-engineer role agent, part of the LLM/RAG/multi-agent reference set: - llm-frameworks.md: framework selection by control model + MCP (roles, transports, dated spec revisions). - prompt-engineering.md: structured output, repair loops, context engineering. CHANGELOG: Unreleased -> Added entry for both references.
…re references Two vendor-neutral, research-grounded, fact-checked references at system-design altitude (complement the ai-engineer implementation references): - rag-architecture.md: retrieval topology, caching tiers, freshness/consistency SLOs - agentic-systems-architecture.md: agent topologies, control, observability/governance, OTel GenAI conventions Also: CHANGELOG Unreleased -> Added entry for the two references.
…us pipelines, vector-DB ops + tuning) Three new role-agent reference libraries, lane-separated by concern so each agent self-routes to its own altitude without overlap: - data-engineer: rag-corpus-pipelines.md (data-pipeline lane — corpus ingestion, chunking, embedding pipelines, freshness) - mlops-engineer: vector-db-operations.md (ops lane — serving, scaling, monitoring, lifecycle) - dba: vector-db-tuning.md (index-tuning lane — ANN parameters, query/storage optimization) Research-grounded, fact-checked, and vendor-neutral. Part of the LLM/RAG/multi-agent reference set.
…erences Research-grounded, fact-checked, vendor-neutral. Completes the ai-engineer reference set: rag-patterns, agentic-workflows, llm-frameworks, prompt-engineering, eval-frameworks, structured-output. eval-frameworks.md: eval-first methodology, golden/holdout datasets, metric types (deterministic / embedding / LLM-as-judge), judge bias + mitigations, RAG/agent eval pointers, assertion-style prompt tests, regression detection with statistical care (N runs, CIs, bootstrap on non-deterministic systems), offline vs production eval + OTel GenAI tracing, human eval, framework landscape. structured-output.md: reliability spectrum (prompt-ask -> JSON mode -> schema-constrained structured outputs -> grammar-constrained decoding -> tool-call-as-output), logit-masking mechanism, grammar-valid != value-correct, JSON Schema 2020-12 supported-vs-restricted subset, typed-model -> schema, validate/retry-with-error-feedback/bounded-cap/deterministic-fallback loop, streaming, failure modes. High-risk claims verified against current vendor/OSS docs (vLLM guided_json/ guided_regex/guided_grammar + XGrammar default, llama.cpp GBNF, Anthropic structured outputs, OpenAI strict-mode subset + JSON-mode-now-legacy, RAGAS metric names, OTel GenAI experimental status, LLM-judge bias literature).
Phase 1: engineering standards + technical-writer standing-agent duties.
Phase 3: 11 LLM/RAG/multi-agent reference libraries.
There was a problem hiding this comment.
Pull request overview
This PR expands the repo’s agent/skill library by adding several new “reference” documents (AI/RAG, agentic workflows, vector DB ops/tuning, corpus pipelines, architecture) and by updating existing SKILL.md guidance to incorporate new standing duties and cross-skill coordination patterns.
Changes:
- Add multiple vendor-neutral reference libraries for AI engineering (RAG, agent loops, prompts/structured output, evals, frameworks) and architecture (RAG + agentic systems).
- Add vector DB operations/tuning and RAG corpus pipeline references, lane-separated by concern (data / ops / DBA).
- Update several skills (technical-writer, reviewer, backend-tester, backend-developer, solution-architect, scrum-master) to reinforce standards and processes (e.g., inline review threads as authoritative checklist).
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| claude/skills/specialized/technical-writer/SKILL.md | Makes technical-writer a standing agent with commit-message + living-doc duties; adds cross-skill pointers. |
| claude/skills/specialized/technical-writer/references/commit-and-docs.md | New reference for Conventional Commits, changelog discipline, release notes, and CI-gate recommendations. |
| claude/skills/quality/testing/e2e-tester/references/cucumber-bdd.md | Adds stakeholder/benchmark scenario guidance for Gherkin as “proof artifacts”. |
| claude/skills/quality/testing/backend-tester/SKILL.md | Links backend testing to stakeholder-facing Gherkin benchmark/acceptance patterns. |
| claude/skills/quality/review/reviewer/SKILL.md | Adds explicit guidance: inline review comments are the authoritative checklist. |
| claude/skills/quality/review/reviewer/references/backend-review.md | Adds a consolidated “Engineering Standards Enforcement” section for backend reviews. |
| claude/skills/operations/mlops/mlops-engineer/references/vector-db-operations.md | New operational runbook for running vector DB infra in production. |
| claude/skills/management/scrum-master/references/orchestration-and-tickets.md | Reinforces resolving PR inline comments one-by-one as a workflow rule. |
| claude/skills/development/data/dba/dba/references/vector-db-tuning.md | New DBA-focused pgvector/dedicated-engine tuning guide (index choice, params, EXPLAIN, filtered recall). |
| claude/skills/development/data/data-engineer/references/rag-corpus-pipelines.md | New data-engineering guide for ingestion/CDC/dedup/lineage/freshness/re-embed pipelines. |
| claude/skills/development/backend/java/backend-developer/SKILL.md | Adds explicit code-level engineering standards (facts-only Javadoc, naming, builders, AOP guidance). |
| claude/skills/development/backend/java/backend-developer/references/java-expertise.md | Adds JVM-specific micro-standards (static vs instance, cached regex Patterns, seeded RNG). |
| claude/skills/development/ai/ai-engineer/references/structured-output.md | New structured-output reliability guide (schema/grammar constraints, validation/retry/fallback). |
| claude/skills/development/ai/ai-engineer/references/rag-patterns.md | New implementation-level RAG patterns reference (chunking → retrieval → eval). |
| claude/skills/development/ai/ai-engineer/references/prompt-engineering.md | New prompt engineering reference (prompt structure, examples, structured outputs, safety, prompt ops). |
| claude/skills/development/ai/ai-engineer/references/llm-frameworks.md | New guide for choosing SDK/framework/MCP layers and portability patterns. |
| claude/skills/development/ai/ai-engineer/references/eval-frameworks.md | New evaluation methodology + framework landscape reference for LLM systems. |
| claude/skills/development/ai/ai-engineer/references/agentic-workflows.md | New agent loop/tool/memory/multi-agent/control reference. |
| claude/skills/architecture/solution-architect/SKILL.md | Adds cross-cutting concern guidance (route timing/metrics/tracing via AOP; avoid domain logic in aspects). |
| claude/skills/architecture/solution-architect/references/rag-architecture.md | New system-design RAG architecture/topology/caching/governance reference. |
| claude/skills/architecture/solution-architect/references/agentic-systems-architecture.md | New system-design reference for agentic topologies, governance, reliability, observability. |
| CHANGELOG.md | Adds an Unreleased section describing the new reference libraries and skill expansions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- prompt-engineering.md: remove stray </content></invoke> tags at EOF - cucumber-bdd.md: pluralize citation count noun (source -> source(s)) - commit-and-docs.md: clarify 'do not 400' -> 'rather than rejecting with HTTP 400'
…herkin-proof changes The Unreleased section only listed the new LLM/RAG reference libraries. Backfill the agent-behaviour changes that also landed on this branch: the technical-writer becoming a standing commit-message/living-docs agent, the inline-review-comments-as-authoritative-checklist rule across reviewer and scrum-master, the facts-only code/Javadoc enforcement, and the stakeholder-facing Gherkin proof pattern. Add a Fixed entry for the three Copilot reference-doc copy-edits resolved on this branch.
- commit-and-docs.md: scan the full commit message (raw) in the commitlint
no-coauthor rule; Co-Authored-By is a footer trailer that body alone misses
- cucumber-bdd.md: reword benchmark step to a clear percentile-SLO claim
('the p95 answer latency is at most N milliseconds')
- CHANGELOG.md: replace shorthand references/... paths with repo-root paths under claude/skills/... so the new docs are navigable - vector-db-operations.md: fix footer cross-refs to the canonical relative paths used at the top of the file (they contradicted each other) - technical-writer/SKILL.md: clarify the 72-char subject limit covers the whole header including the type(scope): prefix (matches header-max-length)
…nks) The cross-references to the e2e-tester cucumber-bdd reference used a bare references/cucumber-bdd.md path that does not resolve from these files. Convert both to proper relative markdown links: - technical-writer/SKILL.md -> ../../quality/testing/e2e-tester/references/cucumber-bdd.md - backend-tester/SKILL.md -> ../e2e-tester/references/cucumber-bdd.md Both verified to resolve to the real file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add several agents and their skills