From fe6d4c4f2a76f1276acefaf18c000a59e4778ea0 Mon Sep 17 00:00:00 2001 From: ashrafchowdury Date: Fri, 31 Jul 2026 12:34:56 +0600 Subject: [PATCH] Add findings skills and related documentation - Introduced five core skills for findings-driven review: scan-codebase, test-codebase, sync-findings, triage-findings, and resolve-findings. - Created detailed documentation for each skill, outlining their roles, parameters, workflows, and rules. - Established a shared findings lifecycle and schema to standardize findings management across skills. - Implemented YAML configurations for OpenAI integration for each skill. - Updated .gitignore to include new skill directories and adjusted references in AGENTS.md and findings documentation. --- {agents => .agents}/docs/code-review/README.md | 0 {agents => .agents}/docs/code-review/criteria.md | 0 {agents => .agents}/docs/code-review/deliverables.md | 0 {agents => .agents}/docs/code-review/docs.specs.md | 0 {agents => .agents}/docs/code-review/guidelines.md | 0 {agents => .agents}/docs/code-review/instructions.md | 0 {agents => .agents}/docs/code-review/rubrics/api.md | 0 {agents => .agents}/docs/code-review/rubrics/architecture.md | 0 {agents => .agents}/docs/code-review/rubrics/databases.md | 0 {agents => .agents}/docs/code-review/rubrics/general.md | 0 .../docs/code-review/rubrics/observability.md | 0 {agents => .agents}/docs/code-review/rubrics/performance.md | 0 {agents => .agents}/docs/code-review/rubrics/qa.md | 0 {agents => .agents}/docs/code-review/rubrics/sdk.md | 0 {agents => .agents}/docs/code-review/rubrics/security.md | 0 {agents => .agents}/docs/code-review/rubrics/services.md | 0 {agents => .agents}/docs/code-review/rubrics/testability.md | 0 {agents => .agents}/docs/code-review/rubrics/web.md | 0 {agents => .agents}/docs/code-review/templates/findings.md | 0 {agents => .agents}/docs/code-review/templates/metadata.json | 0 {agents => .agents}/docs/code-review/templates/plan.md | 0 {agents => .agents}/docs/code-review/templates/progress.md | 0 {agents => .agents}/docs/code-review/templates/questions.md | 0 {agents => .agents}/docs/code-review/templates/risks.md | 0 {agents => .agents}/docs/code-review/templates/scope.md | 0 {agents => .agents}/docs/code-review/templates/scorecard.md | 0 {agents => .agents}/docs/code-review/templates/summary.md | 0 {agents => .agents}/docs/diataxis/initial.digest.md | 0 {agents => .agents}/skills/README.md | 4 ++-- {agents => .agents}/skills/resolve-findings/SKILL.md | 0 .../skills/resolve-findings/agents/openai.yaml | 0 {agents => .agents}/skills/scan-codebase/SKILL.md | 0 {agents => .agents}/skills/scan-codebase/agents/openai.yaml | 0 .../skills/shared/references/findings.lifecycle.md | 0 .../skills/shared/references/findings.schema.md | 0 {agents => .agents}/skills/sync-findings/SKILL.md | 0 {agents => .agents}/skills/sync-findings/agents/openai.yaml | 0 {agents => .agents}/skills/test-codebase/SKILL.md | 0 {agents => .agents}/skills/test-codebase/agents/openai.yaml | 0 {agents => .agents}/skills/triage-findings/SKILL.md | 0 .../skills/triage-findings/agents/openai.yaml | 0 .claude/skills/resolve-findings | 1 + .claude/skills/scan-codebase | 1 + .claude/skills/sync-findings | 1 + .claude/skills/test-codebase | 1 + .claude/skills/triage-findings | 1 + .gitignore | 5 +++++ AGENTS.md | 2 +- docs/design/prompt-runtime-unification/findings.md | 4 ++-- docs/designs/support-fields/findings.md | 2 +- 50 files changed, 16 insertions(+), 6 deletions(-) rename {agents => .agents}/docs/code-review/README.md (100%) rename {agents => .agents}/docs/code-review/criteria.md (100%) rename {agents => .agents}/docs/code-review/deliverables.md (100%) rename {agents => .agents}/docs/code-review/docs.specs.md (100%) rename {agents => .agents}/docs/code-review/guidelines.md (100%) rename {agents => .agents}/docs/code-review/instructions.md (100%) rename {agents => .agents}/docs/code-review/rubrics/api.md (100%) rename {agents => .agents}/docs/code-review/rubrics/architecture.md (100%) rename {agents => .agents}/docs/code-review/rubrics/databases.md (100%) rename {agents => .agents}/docs/code-review/rubrics/general.md (100%) rename {agents => .agents}/docs/code-review/rubrics/observability.md (100%) rename {agents => .agents}/docs/code-review/rubrics/performance.md (100%) rename {agents => .agents}/docs/code-review/rubrics/qa.md (100%) rename {agents => .agents}/docs/code-review/rubrics/sdk.md (100%) rename {agents => .agents}/docs/code-review/rubrics/security.md (100%) rename {agents => .agents}/docs/code-review/rubrics/services.md (100%) rename {agents => .agents}/docs/code-review/rubrics/testability.md (100%) rename {agents => .agents}/docs/code-review/rubrics/web.md (100%) rename {agents => .agents}/docs/code-review/templates/findings.md (100%) rename {agents => .agents}/docs/code-review/templates/metadata.json (100%) rename {agents => .agents}/docs/code-review/templates/plan.md (100%) rename {agents => .agents}/docs/code-review/templates/progress.md (100%) rename {agents => .agents}/docs/code-review/templates/questions.md (100%) rename {agents => .agents}/docs/code-review/templates/risks.md (100%) rename {agents => .agents}/docs/code-review/templates/scope.md (100%) rename {agents => .agents}/docs/code-review/templates/scorecard.md (100%) rename {agents => .agents}/docs/code-review/templates/summary.md (100%) rename {agents => .agents}/docs/diataxis/initial.digest.md (100%) rename {agents => .agents}/skills/README.md (97%) rename {agents => .agents}/skills/resolve-findings/SKILL.md (100%) rename {agents => .agents}/skills/resolve-findings/agents/openai.yaml (100%) rename {agents => .agents}/skills/scan-codebase/SKILL.md (100%) rename {agents => .agents}/skills/scan-codebase/agents/openai.yaml (100%) rename {agents => .agents}/skills/shared/references/findings.lifecycle.md (100%) rename {agents => .agents}/skills/shared/references/findings.schema.md (100%) rename {agents => .agents}/skills/sync-findings/SKILL.md (100%) rename {agents => .agents}/skills/sync-findings/agents/openai.yaml (100%) rename {agents => .agents}/skills/test-codebase/SKILL.md (100%) rename {agents => .agents}/skills/test-codebase/agents/openai.yaml (100%) rename {agents => .agents}/skills/triage-findings/SKILL.md (100%) rename {agents => .agents}/skills/triage-findings/agents/openai.yaml (100%) create mode 120000 .claude/skills/resolve-findings create mode 120000 .claude/skills/scan-codebase create mode 120000 .claude/skills/sync-findings create mode 120000 .claude/skills/test-codebase create mode 120000 .claude/skills/triage-findings diff --git a/agents/docs/code-review/README.md b/.agents/docs/code-review/README.md similarity index 100% rename from agents/docs/code-review/README.md rename to .agents/docs/code-review/README.md diff --git a/agents/docs/code-review/criteria.md b/.agents/docs/code-review/criteria.md similarity index 100% rename from agents/docs/code-review/criteria.md rename to .agents/docs/code-review/criteria.md diff --git a/agents/docs/code-review/deliverables.md b/.agents/docs/code-review/deliverables.md similarity index 100% rename from agents/docs/code-review/deliverables.md rename to .agents/docs/code-review/deliverables.md diff --git a/agents/docs/code-review/docs.specs.md b/.agents/docs/code-review/docs.specs.md similarity index 100% rename from agents/docs/code-review/docs.specs.md rename to .agents/docs/code-review/docs.specs.md diff --git a/agents/docs/code-review/guidelines.md b/.agents/docs/code-review/guidelines.md similarity index 100% rename from agents/docs/code-review/guidelines.md rename to .agents/docs/code-review/guidelines.md diff --git a/agents/docs/code-review/instructions.md b/.agents/docs/code-review/instructions.md similarity index 100% rename from agents/docs/code-review/instructions.md rename to .agents/docs/code-review/instructions.md diff --git a/agents/docs/code-review/rubrics/api.md b/.agents/docs/code-review/rubrics/api.md similarity index 100% rename from agents/docs/code-review/rubrics/api.md rename to .agents/docs/code-review/rubrics/api.md diff --git a/agents/docs/code-review/rubrics/architecture.md b/.agents/docs/code-review/rubrics/architecture.md similarity index 100% rename from agents/docs/code-review/rubrics/architecture.md rename to .agents/docs/code-review/rubrics/architecture.md diff --git a/agents/docs/code-review/rubrics/databases.md b/.agents/docs/code-review/rubrics/databases.md similarity index 100% rename from agents/docs/code-review/rubrics/databases.md rename to .agents/docs/code-review/rubrics/databases.md diff --git a/agents/docs/code-review/rubrics/general.md b/.agents/docs/code-review/rubrics/general.md similarity index 100% rename from agents/docs/code-review/rubrics/general.md rename to .agents/docs/code-review/rubrics/general.md diff --git a/agents/docs/code-review/rubrics/observability.md b/.agents/docs/code-review/rubrics/observability.md similarity index 100% rename from agents/docs/code-review/rubrics/observability.md rename to .agents/docs/code-review/rubrics/observability.md diff --git a/agents/docs/code-review/rubrics/performance.md b/.agents/docs/code-review/rubrics/performance.md similarity index 100% rename from agents/docs/code-review/rubrics/performance.md rename to .agents/docs/code-review/rubrics/performance.md diff --git a/agents/docs/code-review/rubrics/qa.md b/.agents/docs/code-review/rubrics/qa.md similarity index 100% rename from agents/docs/code-review/rubrics/qa.md rename to .agents/docs/code-review/rubrics/qa.md diff --git a/agents/docs/code-review/rubrics/sdk.md b/.agents/docs/code-review/rubrics/sdk.md similarity index 100% rename from agents/docs/code-review/rubrics/sdk.md rename to .agents/docs/code-review/rubrics/sdk.md diff --git a/agents/docs/code-review/rubrics/security.md b/.agents/docs/code-review/rubrics/security.md similarity index 100% rename from agents/docs/code-review/rubrics/security.md rename to .agents/docs/code-review/rubrics/security.md diff --git a/agents/docs/code-review/rubrics/services.md b/.agents/docs/code-review/rubrics/services.md similarity index 100% rename from agents/docs/code-review/rubrics/services.md rename to .agents/docs/code-review/rubrics/services.md diff --git a/agents/docs/code-review/rubrics/testability.md b/.agents/docs/code-review/rubrics/testability.md similarity index 100% rename from agents/docs/code-review/rubrics/testability.md rename to .agents/docs/code-review/rubrics/testability.md diff --git a/agents/docs/code-review/rubrics/web.md b/.agents/docs/code-review/rubrics/web.md similarity index 100% rename from agents/docs/code-review/rubrics/web.md rename to .agents/docs/code-review/rubrics/web.md diff --git a/agents/docs/code-review/templates/findings.md b/.agents/docs/code-review/templates/findings.md similarity index 100% rename from agents/docs/code-review/templates/findings.md rename to .agents/docs/code-review/templates/findings.md diff --git a/agents/docs/code-review/templates/metadata.json b/.agents/docs/code-review/templates/metadata.json similarity index 100% rename from agents/docs/code-review/templates/metadata.json rename to .agents/docs/code-review/templates/metadata.json diff --git a/agents/docs/code-review/templates/plan.md b/.agents/docs/code-review/templates/plan.md similarity index 100% rename from agents/docs/code-review/templates/plan.md rename to .agents/docs/code-review/templates/plan.md diff --git a/agents/docs/code-review/templates/progress.md b/.agents/docs/code-review/templates/progress.md similarity index 100% rename from agents/docs/code-review/templates/progress.md rename to .agents/docs/code-review/templates/progress.md diff --git a/agents/docs/code-review/templates/questions.md b/.agents/docs/code-review/templates/questions.md similarity index 100% rename from agents/docs/code-review/templates/questions.md rename to .agents/docs/code-review/templates/questions.md diff --git a/agents/docs/code-review/templates/risks.md b/.agents/docs/code-review/templates/risks.md similarity index 100% rename from agents/docs/code-review/templates/risks.md rename to .agents/docs/code-review/templates/risks.md diff --git a/agents/docs/code-review/templates/scope.md b/.agents/docs/code-review/templates/scope.md similarity index 100% rename from agents/docs/code-review/templates/scope.md rename to .agents/docs/code-review/templates/scope.md diff --git a/agents/docs/code-review/templates/scorecard.md b/.agents/docs/code-review/templates/scorecard.md similarity index 100% rename from agents/docs/code-review/templates/scorecard.md rename to .agents/docs/code-review/templates/scorecard.md diff --git a/agents/docs/code-review/templates/summary.md b/.agents/docs/code-review/templates/summary.md similarity index 100% rename from agents/docs/code-review/templates/summary.md rename to .agents/docs/code-review/templates/summary.md diff --git a/agents/docs/diataxis/initial.digest.md b/.agents/docs/diataxis/initial.digest.md similarity index 100% rename from agents/docs/diataxis/initial.digest.md rename to .agents/docs/diataxis/initial.digest.md diff --git a/agents/skills/README.md b/.agents/skills/README.md similarity index 97% rename from agents/skills/README.md rename to .agents/skills/README.md index ff7fb6a351..6cf910f7a9 100644 --- a/agents/skills/README.md +++ b/.agents/skills/README.md @@ -56,14 +56,14 @@ Code + Docs -- scan-codebase --> Findings <-- test-codebase -- Tests / Runtime / For Codex: - invoke a skill with `$skill-name` -- `agents/skills/` is the canonical source, but Codex auto-discovers from `~/.codex/skills` +- `.agents/skills/` is the canonical source, but Codex auto-discovers from `~/.codex/skills` - if a skill does not appear under `$`, refresh the symlink or install it into `~/.codex/skills` and reload Codex For Claude: - invoke a project skill with `/project:skill-name` when your Claude client exposes project skills that way - otherwise use the Claude project skills picker after reloading the project -- `.claude/skills/` contains the Claude-facing wrappers for the canonical skills in `agents/skills/` +- `.claude/skills/` contains the Claude-facing wrappers for the canonical skills in `.agents/skills/` ## Skills diff --git a/agents/skills/resolve-findings/SKILL.md b/.agents/skills/resolve-findings/SKILL.md similarity index 100% rename from agents/skills/resolve-findings/SKILL.md rename to .agents/skills/resolve-findings/SKILL.md diff --git a/agents/skills/resolve-findings/agents/openai.yaml b/.agents/skills/resolve-findings/agents/openai.yaml similarity index 100% rename from agents/skills/resolve-findings/agents/openai.yaml rename to .agents/skills/resolve-findings/agents/openai.yaml diff --git a/agents/skills/scan-codebase/SKILL.md b/.agents/skills/scan-codebase/SKILL.md similarity index 100% rename from agents/skills/scan-codebase/SKILL.md rename to .agents/skills/scan-codebase/SKILL.md diff --git a/agents/skills/scan-codebase/agents/openai.yaml b/.agents/skills/scan-codebase/agents/openai.yaml similarity index 100% rename from agents/skills/scan-codebase/agents/openai.yaml rename to .agents/skills/scan-codebase/agents/openai.yaml diff --git a/agents/skills/shared/references/findings.lifecycle.md b/.agents/skills/shared/references/findings.lifecycle.md similarity index 100% rename from agents/skills/shared/references/findings.lifecycle.md rename to .agents/skills/shared/references/findings.lifecycle.md diff --git a/agents/skills/shared/references/findings.schema.md b/.agents/skills/shared/references/findings.schema.md similarity index 100% rename from agents/skills/shared/references/findings.schema.md rename to .agents/skills/shared/references/findings.schema.md diff --git a/agents/skills/sync-findings/SKILL.md b/.agents/skills/sync-findings/SKILL.md similarity index 100% rename from agents/skills/sync-findings/SKILL.md rename to .agents/skills/sync-findings/SKILL.md diff --git a/agents/skills/sync-findings/agents/openai.yaml b/.agents/skills/sync-findings/agents/openai.yaml similarity index 100% rename from agents/skills/sync-findings/agents/openai.yaml rename to .agents/skills/sync-findings/agents/openai.yaml diff --git a/agents/skills/test-codebase/SKILL.md b/.agents/skills/test-codebase/SKILL.md similarity index 100% rename from agents/skills/test-codebase/SKILL.md rename to .agents/skills/test-codebase/SKILL.md diff --git a/agents/skills/test-codebase/agents/openai.yaml b/.agents/skills/test-codebase/agents/openai.yaml similarity index 100% rename from agents/skills/test-codebase/agents/openai.yaml rename to .agents/skills/test-codebase/agents/openai.yaml diff --git a/agents/skills/triage-findings/SKILL.md b/.agents/skills/triage-findings/SKILL.md similarity index 100% rename from agents/skills/triage-findings/SKILL.md rename to .agents/skills/triage-findings/SKILL.md diff --git a/agents/skills/triage-findings/agents/openai.yaml b/.agents/skills/triage-findings/agents/openai.yaml similarity index 100% rename from agents/skills/triage-findings/agents/openai.yaml rename to .agents/skills/triage-findings/agents/openai.yaml diff --git a/.claude/skills/resolve-findings b/.claude/skills/resolve-findings new file mode 120000 index 0000000000..213a9da6cc --- /dev/null +++ b/.claude/skills/resolve-findings @@ -0,0 +1 @@ +../../.agents/skills/resolve-findings \ No newline at end of file diff --git a/.claude/skills/scan-codebase b/.claude/skills/scan-codebase new file mode 120000 index 0000000000..ab9da55b68 --- /dev/null +++ b/.claude/skills/scan-codebase @@ -0,0 +1 @@ +../../.agents/skills/scan-codebase \ No newline at end of file diff --git a/.claude/skills/sync-findings b/.claude/skills/sync-findings new file mode 120000 index 0000000000..7b15cbf349 --- /dev/null +++ b/.claude/skills/sync-findings @@ -0,0 +1 @@ +../../.agents/skills/sync-findings \ No newline at end of file diff --git a/.claude/skills/test-codebase b/.claude/skills/test-codebase new file mode 120000 index 0000000000..2aab85b14d --- /dev/null +++ b/.claude/skills/test-codebase @@ -0,0 +1 @@ +../../.agents/skills/test-codebase \ No newline at end of file diff --git a/.claude/skills/triage-findings b/.claude/skills/triage-findings new file mode 120000 index 0000000000..b03e5b07f5 --- /dev/null +++ b/.claude/skills/triage-findings @@ -0,0 +1 @@ +../../.agents/skills/triage-findings \ No newline at end of file diff --git a/.gitignore b/.gitignore index 39f748bb2c..5c5e6ee42f 100644 --- a/.gitignore +++ b/.gitignore @@ -118,6 +118,11 @@ services/runner/tests/results/ !.claude/skills/write-pr-description !.claude/skills/write-social-announcement !.claude/skills/write-template-playbooks +!.claude/skills/scan-codebase +!.claude/skills/triage-findings +!.claude/skills/resolve-findings +!.claude/skills/sync-findings +!.claude/skills/test-codebase # Temporary SDK copies created by run.sh --local api/sdks diff --git a/AGENTS.md b/AGENTS.md index c47be89b72..96fd7ca438 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ bottom. - Package vs app placement, `@agenta/*` packages, package unit tests: the `agenta-package-practices` skill. - Testing: [docs/designs/testing/README.md](docs/designs/testing/README.md). -- Docs writing: the Diátaxis framework digest at `agents/docs/diataxis/`, and the +- Docs writing: the Diátaxis framework digest at `.agents/docs/diataxis/`, and the `write-docs` skill for Agenta style, voice, and structure. ## Branching and PRs with GitButler diff --git a/docs/design/prompt-runtime-unification/findings.md b/docs/design/prompt-runtime-unification/findings.md index b08e9b1a98..fc1e8203f0 100644 --- a/docs/design/prompt-runtime-unification/findings.md +++ b/docs/design/prompt-runtime-unification/findings.md @@ -12,8 +12,8 @@ - GitHub issue `#4244`: `https://github.com/Agenta-AI/agenta/issues/4244` - GitHub review comments fetched through the GitHub plugin comment surface on `2026-05-01` - Shared findings references: - - `agents/skills/shared/references/findings.schema.md` - - `agents/skills/shared/references/findings.lifecycle.md` + - `.agents/skills/shared/references/findings.schema.md` + - `.agents/skills/shared/references/findings.lifecycle.md` - Local implementation: - `docs/design/prompt-runtime-unification/README.md` - `docs/design/prompt-runtime-unification/appendix-rendering-edge-cases.md` diff --git a/docs/designs/support-fields/findings.md b/docs/designs/support-fields/findings.md index 6ced74cacc..a3ab1fa3fa 100644 --- a/docs/designs/support-fields/findings.md +++ b/docs/designs/support-fields/findings.md @@ -40,7 +40,7 @@ Sync-derived findings (closed): ## Rules -- Severity scheme: `P0` / `P1` / `P2` / `P3` (per [findings.schema.md](../../../agents/skills/shared/references/findings.schema.md)). +- Severity scheme: `P0` / `P1` / `P2` / `P3` (per [findings.schema.md](../../../.agents/skills/shared/references/findings.schema.md)). ## Notes