[chore] Move agent skills from agents/ to canonical .agents/ - #5603
Conversation
- 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.
dosubot
Bot
added
the
size:XS
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dosubot
Bot
added
the
refactoring
|
Trying to clean things up, having 3 sources of agent skills makes me confused |
ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (50)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdded a structured code-review documentation framework with domain rubrics, reusable templates, findings lifecycle guidance, five agent skills, OpenAI metadata, Claude symlinks, and canonical ChangesCode-review documentation
Findings workflow
Agent integration
Estimated code review effort: 3 (Moderate) | ~30 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 17
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (9)
.agents/docs/code-review/criteria.md-13-22 (1)
13-22: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd language tags to both diagram fences.
The same unlabeled-fence issue appears in both documents.
.agents/docs/code-review/criteria.md#L13-L22: addtextto the opening fence..agents/docs/code-review/guidelines.md#L137-L144: addtextto the opening fence.Source: Linters/SAST tools
.agents/docs/code-review/templates/findings.md-11-11 (1)
11-11: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the evidence links in the template.
findings.mdandevidence/are sibling per-run artifacts.../evidence/SLUG.mdpoints outside the run directory. Useevidence/SLUG.mdin both examples.Proposed link fix
- [evidence](../evidence/SLUG.md) + [evidence](evidence/SLUG.md) ... -**Evidence:** [evidence/SLUG.md](../evidence/SLUG.md) +**Evidence:** [evidence/SLUG.md](evidence/SLUG.md)Also applies to: 32-32
.agents/docs/code-review/templates/progress.md-15-28 (1)
15-28: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winRepresent conditional tasks explicitly.
risks.md,questions.md, andscorecard.mdare conditional outputs, but the task log always includes their creation tasks and has nonot applicablestate. Addn/aor make these rows conditional. A completed progress log must distinguish “not required” from “not done”..agents/docs/code-review/templates/questions.md-3-3 (1)
3-3: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winReference the canonical notes section.
The template directs internal questions to
notes/, but the findings schema defines## Notesinsidefindings.mdand does not define anotes/artifact. Change this instruction to reference the canonical## Notessection or definenotes/in the artifact contract..agents/docs/diataxis/initial.digest.md-3-3 (1)
3-3: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRemove internal citation metadata from link labels.
Normal Markdown rendering exposes text such as
oai_citation:0‡diataxis.frto readers. Replace these labels with descriptive text such asDiátaxis, or confirm that a publication step removes the metadata before release. Apply the same fix to the repeated citations in this file..agents/docs/code-review/rubrics/api.md-35-35 (1)
35-35: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine enum compatibility by serialized values.
Reordering named enum values does not change wire behavior when clients serialize names. Renumbering numeric enum values can break clients. Change this criterion to distinguish enum-name removal from numeric-value changes.
.agents/docs/code-review/rubrics/qa.md-5-6 (1)
5-6: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winCorrect the criterion number for
testability.md.The notice maps both specialist rubrics to criterion 10.
testability.mduses criterion 9, whileobservability.mduses criterion 10. Change the testability entry to criterion 9..agents/skills/scan-codebase/SKILL.md-22-31 (1)
22-31: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine the behavior of
depth=shallow.
depthacceptsshallowanddeep, but the workflow does not apply a different inspection scope. Line 66 also says to bias toward deep inspection. Ashallowrequest can therefore run the same deep review.Define the files and checks for each value. Require the selected depth during scope confirmation.
Also applies to: 64-68
.agents/skills/test-codebase/SKILL.md-21-30 (1)
21-30: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine the behavior for each
depthvalue.The interface accepts
shallowanddeep, but the workflow only confirms the value. It does not state which tests, repros, documentation checks, or full-suite work each value permits. Different invocations can therefore perform inconsistent validation.Specify the required validation scope for both values, or remove the parameter.
Also applies to: 43-58
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 6c6716ab-27d6-4ee3-ad84-58054530531f
📒 Files selected for processing (50)
.agents/docs/code-review/README.md.agents/docs/code-review/criteria.md.agents/docs/code-review/deliverables.md.agents/docs/code-review/docs.specs.md.agents/docs/code-review/guidelines.md.agents/docs/code-review/instructions.md.agents/docs/code-review/rubrics/api.md.agents/docs/code-review/rubrics/architecture.md.agents/docs/code-review/rubrics/databases.md.agents/docs/code-review/rubrics/general.md.agents/docs/code-review/rubrics/observability.md.agents/docs/code-review/rubrics/performance.md.agents/docs/code-review/rubrics/qa.md.agents/docs/code-review/rubrics/sdk.md.agents/docs/code-review/rubrics/security.md.agents/docs/code-review/rubrics/services.md.agents/docs/code-review/rubrics/testability.md.agents/docs/code-review/rubrics/web.md.agents/docs/code-review/templates/findings.md.agents/docs/code-review/templates/metadata.json.agents/docs/code-review/templates/plan.md.agents/docs/code-review/templates/progress.md.agents/docs/code-review/templates/questions.md.agents/docs/code-review/templates/risks.md.agents/docs/code-review/templates/scope.md.agents/docs/code-review/templates/scorecard.md.agents/docs/code-review/templates/summary.md.agents/docs/diataxis/initial.digest.md.agents/skills/README.md.agents/skills/resolve-findings/SKILL.md.agents/skills/resolve-findings/agents/openai.yaml.agents/skills/scan-codebase/SKILL.md.agents/skills/scan-codebase/agents/openai.yaml.agents/skills/shared/references/findings.lifecycle.md.agents/skills/shared/references/findings.schema.md.agents/skills/sync-findings/SKILL.md.agents/skills/sync-findings/agents/openai.yaml.agents/skills/test-codebase/SKILL.md.agents/skills/test-codebase/agents/openai.yaml.agents/skills/triage-findings/SKILL.md.agents/skills/triage-findings/agents/openai.yaml.claude/skills/resolve-findings.claude/skills/scan-codebase.claude/skills/sync-findings.claude/skills/test-codebase.claude/skills/triage-findings.gitignoreAGENTS.mddocs/design/prompt-runtime-unification/findings.mddocs/designs/support-fields/findings.md
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 17
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (9)
.agents/docs/code-review/criteria.md-13-22 (1)
13-22: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd language tags to both diagram fences.
The same unlabeled-fence issue appears in both documents.
.agents/docs/code-review/criteria.md#L13-L22: addtextto the opening fence..agents/docs/code-review/guidelines.md#L137-L144: addtextto the opening fence.Source: Linters/SAST tools
.agents/docs/code-review/templates/findings.md-11-11 (1)
11-11: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the evidence links in the template.
findings.mdandevidence/are sibling per-run artifacts.../evidence/SLUG.mdpoints outside the run directory. Useevidence/SLUG.mdin both examples.Proposed link fix
- [evidence](../evidence/SLUG.md) + [evidence](evidence/SLUG.md) ... -**Evidence:** [evidence/SLUG.md](../evidence/SLUG.md) +**Evidence:** [evidence/SLUG.md](evidence/SLUG.md)Also applies to: 32-32
.agents/docs/code-review/templates/progress.md-15-28 (1)
15-28: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winRepresent conditional tasks explicitly.
risks.md,questions.md, andscorecard.mdare conditional outputs, but the task log always includes their creation tasks and has nonot applicablestate. Addn/aor make these rows conditional. A completed progress log must distinguish “not required” from “not done”..agents/docs/code-review/templates/questions.md-3-3 (1)
3-3: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winReference the canonical notes section.
The template directs internal questions to
notes/, but the findings schema defines## Notesinsidefindings.mdand does not define anotes/artifact. Change this instruction to reference the canonical## Notessection or definenotes/in the artifact contract..agents/docs/diataxis/initial.digest.md-3-3 (1)
3-3: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRemove internal citation metadata from link labels.
Normal Markdown rendering exposes text such as
oai_citation:0‡diataxis.frto readers. Replace these labels with descriptive text such asDiátaxis, or confirm that a publication step removes the metadata before release. Apply the same fix to the repeated citations in this file..agents/docs/code-review/rubrics/api.md-35-35 (1)
35-35: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine enum compatibility by serialized values.
Reordering named enum values does not change wire behavior when clients serialize names. Renumbering numeric enum values can break clients. Change this criterion to distinguish enum-name removal from numeric-value changes.
.agents/docs/code-review/rubrics/qa.md-5-6 (1)
5-6: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winCorrect the criterion number for
testability.md.The notice maps both specialist rubrics to criterion 10.
testability.mduses criterion 9, whileobservability.mduses criterion 10. Change the testability entry to criterion 9..agents/skills/scan-codebase/SKILL.md-22-31 (1)
22-31: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine the behavior of
depth=shallow.
depthacceptsshallowanddeep, but the workflow does not apply a different inspection scope. Line 66 also says to bias toward deep inspection. Ashallowrequest can therefore run the same deep review.Define the files and checks for each value. Require the selected depth during scope confirmation.
Also applies to: 64-68
.agents/skills/test-codebase/SKILL.md-21-30 (1)
21-30: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winDefine the behavior for each
depthvalue.The interface accepts
shallowanddeep, but the workflow only confirms the value. It does not state which tests, repros, documentation checks, or full-suite work each value permits. Different invocations can therefore perform inconsistent validation.Specify the required validation scope for both values, or remove the parameter.
Also applies to: 43-58
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 6c6716ab-27d6-4ee3-ad84-58054530531f
📒 Files selected for processing (50)
.agents/docs/code-review/README.md.agents/docs/code-review/criteria.md.agents/docs/code-review/deliverables.md.agents/docs/code-review/docs.specs.md.agents/docs/code-review/guidelines.md.agents/docs/code-review/instructions.md.agents/docs/code-review/rubrics/api.md.agents/docs/code-review/rubrics/architecture.md.agents/docs/code-review/rubrics/databases.md.agents/docs/code-review/rubrics/general.md.agents/docs/code-review/rubrics/observability.md.agents/docs/code-review/rubrics/performance.md.agents/docs/code-review/rubrics/qa.md.agents/docs/code-review/rubrics/sdk.md.agents/docs/code-review/rubrics/security.md.agents/docs/code-review/rubrics/services.md.agents/docs/code-review/rubrics/testability.md.agents/docs/code-review/rubrics/web.md.agents/docs/code-review/templates/findings.md.agents/docs/code-review/templates/metadata.json.agents/docs/code-review/templates/plan.md.agents/docs/code-review/templates/progress.md.agents/docs/code-review/templates/questions.md.agents/docs/code-review/templates/risks.md.agents/docs/code-review/templates/scope.md.agents/docs/code-review/templates/scorecard.md.agents/docs/code-review/templates/summary.md.agents/docs/diataxis/initial.digest.md.agents/skills/README.md.agents/skills/resolve-findings/SKILL.md.agents/skills/resolve-findings/agents/openai.yaml.agents/skills/scan-codebase/SKILL.md.agents/skills/scan-codebase/agents/openai.yaml.agents/skills/shared/references/findings.lifecycle.md.agents/skills/shared/references/findings.schema.md.agents/skills/sync-findings/SKILL.md.agents/skills/sync-findings/agents/openai.yaml.agents/skills/test-codebase/SKILL.md.agents/skills/test-codebase/agents/openai.yaml.agents/skills/triage-findings/SKILL.md.agents/skills/triage-findings/agents/openai.yaml.claude/skills/resolve-findings.claude/skills/scan-codebase.claude/skills/sync-findings.claude/skills/test-codebase.claude/skills/triage-findings.gitignoreAGENTS.mddocs/design/prompt-runtime-unification/findings.mddocs/designs/support-fields/findings.md
🛑 Comments failed to post (17)
.agents/docs/code-review/deliverables.md (2)
7-30: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Align artifact requiredness across the framework.
The closure gate and artifact maps define different requiredness rules. Choose one policy and apply it to every artifact.
.agents/docs/code-review/deliverables.md#L7-L30: define the canonical requiredness for plan, progress, findings, summary, metadata, and evidence..agents/docs/code-review/README.md#L80-L87: align theprogress.mdrule..agents/docs/code-review/README.md#L102-L109: align the evidence exception..agents/docs/code-review/README.md#L111-L118: align themetadata.jsonrule..agents/docs/code-review/README.md#L124-L131: align thefindings.mdrule..agents/docs/code-review/README.md#L155-L162: align thesummary.mdrule..agents/docs/code-review/README.md#L188-L207: update the quick-reference table and evidence footnote..agents/docs/code-review/guidelines.md#L45-L83: update the artifact map to use the same policy.📍 Affects 3 files
.agents/docs/code-review/deliverables.md#L7-L30(this comment).agents/docs/code-review/README.md#L80-L87.agents/docs/code-review/README.md#L102-L109.agents/docs/code-review/README.md#L111-L118.agents/docs/code-review/README.md#L124-L131.agents/docs/code-review/README.md#L155-L162.agents/docs/code-review/README.md#L188-L207.agents/docs/code-review/guidelines.md#L45-L83
34-44: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use one severity vocabulary for findings.
The deliverables and templates support
info, but the procedure rejects it. This can produce findings and metadata that do not satisfy the documented procedure.
.agents/docs/code-review/deliverables.md#L34-L44: decide whetherinfobelongs in confirmed findings..agents/docs/code-review/instructions.md#L65-L78: update the allowed severity set..agents/docs/code-review/templates/findings.md#L3-L5: update the template guidance..agents/docs/code-review/templates/metadata.json#L13-L18: updatefinding_counts.📍 Affects 4 files
.agents/docs/code-review/deliverables.md#L34-L44(this comment).agents/docs/code-review/instructions.md#L65-L78.agents/docs/code-review/templates/findings.md#L3-L5.agents/docs/code-review/templates/metadata.json#L13-L18.agents/docs/code-review/guidelines.md (1)
103-131: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Add the QA rubric to every rubric index.
The review stack lists
.agents/docs/code-review/rubrics/qa.md, but the canonical rubric indexes omit it.
.agents/docs/code-review/guidelines.md#L103-L131: addqa.mdto the domain rubric table..agents/docs/code-review/deliverables.md#L112-L129: addqa.mdto the rubric references..agents/docs/code-review/criteria.md#L166-L183: add a QA column and define its criterion coverage.📍 Affects 3 files
.agents/docs/code-review/guidelines.md#L103-L131(this comment).agents/docs/code-review/deliverables.md#L112-L129.agents/docs/code-review/criteria.md#L166-L183.agents/docs/code-review/instructions.md (1)
9-14: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Wire the universal criteria into review startup.
The framework requires
criteria.md, but the harness indexes and startup sequence omit it.
.agents/docs/code-review/instructions.md#L9-L14: addcriteria.mdas a pre-review read..agents/docs/code-review/README.md#L5-L25: listcriteria.mdwith the fixed harness files..agents/docs/code-review/README.md#L173-L205: includecriteria.mdin the lifecycle and quick-reference table.📍 Affects 2 files
.agents/docs/code-review/instructions.md#L9-L14(this comment).agents/docs/code-review/README.md#L5-L25.agents/docs/code-review/README.md#L173-L205.agents/docs/code-review/rubrics/api.md (1)
3-5: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Scope HTTP criteria to HTTP APIs.
This rubric applies to GraphQL, gRPC, WebSocket, and async message APIs, but it requires REST/HTTP concepts such as resource nouns, HTTP verbs, HTTP status codes, URL or
Acceptversioning, and rate-limit headers. Add protocol applicability to each criterion or split the HTTP criteria into a separate rubric. Make rate-limit headers conditional on an HTTP rate-limit contract.Also applies to: 22-25, 42-44, 50-61
.agents/docs/code-review/rubrics/databases.md (2)
28-28: 🚀 Performance & Scalability | 🟠 Major | ⚡ Quick win
Do not order composite indexes by selectivity alone.
Index order depends on equality and range predicates, joins, sort requirements, and the query plan. Selectivity alone can produce an ineffective index. Require query-pattern-driven ordering and plan validation instead.
36-36: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail rg -n -i --glob '!node_modules/**' --glob '!dist/**' \ '(postgres|mysql|mariadb|sqlite|sql server|cockroach|alembic|flyway|liquibase|django migrations)' .Repository: Agenta-AI/agenta
Length of output: 50373
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "== target file ==" wc -l .agents/docs/code-review/rubrics/databases.md sed -n '1,80p' .agents/docs/code-review/rubrics/databases.md echo echo "== nearby migration-related rubric context ==" rg -n -i "migration|ALTER TABLE|ADD COLUMN|expand|contract|online|noop|fill|backfill|add_column|add value" .agents/docs/code-review/rubrics .agents/docs/code-review \ || true echo echo "== broader database migration guidance ==" fd -i 'migration|database|databases|sql|docs|guide|rubric' .agents/docs/code-review -t f -x sh -c 'echo "--- $1"; sed -n "1,120p" "$1"' sh {}Repository: Agenta-AI/agenta
Length of output: 42467
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "== target file ==" wc -l .agents/docs/code-review/rubrics/databases.md sed -s '1,80p' .agents/docs/code-review/rubrics/databases.md echo echo "== nearby migration-related rubric context ==" rg -n -i "migration|ALTER TABLE|ADD COLUMN|expand|contract|online|noop|fill|backfill|add_column|add value" .agents/docs/code-review/rubrics .agents/docs/code-review \ || true echo echo "== broader database migration guidance ==" fd -i 'migration|database|databases|sql|docs|guide|rubric' .agents/docs/code-review -t f -x sh -c 'echo "--- $1"; sed -n "1,160p" "$1"' sh {}Repository: Agenta-AI/agenta
Length of output: 50372
Make the
ADD COLUMNcriterion database-specific.
DEFAULTsemantics still matter by engine and version: newer PostgreSQL allows metadata-onlyNOT NULLdefaults, while older PostgreSQL and many other engines can rewrite or lock large tables. Name the supported databases/versions, or require documented expand/contract or online migration guidance for the target engine..agents/docs/code-review/rubrics/observability.md (1)
26-30: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Prevent PII leakage through required log context.
O-1requires a user ID in error logs, whileO-5prohibits sensitive data in logs. A raw user ID can be PII. Require request IDs, trace IDs, or approved pseudonymous subject identifiers instead. Explicitly prohibit raw emails and user identifiers unless policy permits them..agents/docs/code-review/rubrics/services.md (3)
26-30: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Separate required dependencies from optional dependencies.
SV-3requires all dependencies, including the cache and broker, to be reachable before readiness.SV-9requires graceful operation when a non-critical dependency is unavailable. Define which dependencies are required. Readiness must gate only on required dependencies.
46-49: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Define idempotency on message processing.
SV-12says that messages published to a broker are idempotent. Duplicate side effects occur when a consumer processes the same message more than once. Rewrite this criterion for idempotent consumer processing. Add a separate producer requirement if duplicate publishes require deduplication or an idempotency key.
94-94: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Do not downgrade missing timeouts based on dependency availability.
An internal, highly available dependency can still hang or exhaust caller resources. Keep
SV-6and bounded retry behavior inSV-7high regardless of the dependency SLA. Allow downgrades only when the criterion is proven not applicable and the evidence is documented..agents/docs/code-review/rubrics/web.md (1)
72-74: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Add an explicit CSRF criterion.
The scoring guidance classifies CSRF as critical, but this rubric has no CSRF checklist item. Add a criterion for state-changing requests, or explicitly require the
security.mdS-23 check..agents/docs/code-review/templates/scope.md (1)
14-18: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Include every supported rubric in
Review type.The template lists only
general,security,performance, andapi, but the repository also defines architecture, database, observability, SDK, service, testability, and web rubrics. A scope document cannot select those review layers. Use a free-form list or include all supported rubric names with a defined multi-value format..agents/docs/code-review/templates/scorecard.md (1)
20-28: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Keep verdict values consistent across summary and scorecard.
The canonical workflow uses lowercase
pass,pass with conditions, andfail. Both templates must use those exact values.
.agents/docs/code-review/templates/scorecard.md#L20-L28: replace uppercase and title-case verdict values with lowercase values..agents/docs/code-review/templates/summary.md#L18-L20: replace the uppercase health-verdict placeholder with lowercase values.📍 Affects 2 files
.agents/docs/code-review/templates/scorecard.md#L20-L28(this comment).agents/docs/code-review/templates/summary.md#L18-L20.agents/skills/scan-codebase/SKILL.md (1)
58-60: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Reconcile the findings record before writing it.
The scan starts from fresh context, then updates an existing
path/findings.md. The workflow does not define how to match new observations to existing IDs or preserveopen,closed, and user-decision statuses. A repeated scan can create duplicates or reopen a closed finding.Add a reconciliation step after the fresh review and before the record update. Use the shared schema and lifecycle rules.
Suggested workflow change
-4. Update the active findings record. +4. Reconcile new findings with the active record. + Match findings by stable ID or equivalent evidence. + Preserve existing statuses and user dispositions. +5. Update the active findings record.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.4. Reconcile new findings with the active record. Match findings by stable ID or equivalent evidence. Preserve existing statuses and user dispositions. 5. Update the active findings record. Use `path/findings.md`..agents/skills/shared/references/findings.schema.md (1)
109-118: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Define one canonical severity mapping.
The schema prefers
P0–P3, while the scorecard countscritical,high,medium, andlow, and the rubrics use those names. An agent following this schema can produceP0findings that the scorecard cannot count. Choose one vocabulary or define a mandatory mapping such asP0=critical,P1=high,P2=medium, andP3=low..agents/skills/sync-findings/SKILL.md (1)
54-61: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Reorder source discovery and the mandatory save.
The workflow requires
path/findings.mdto contain every new PR comment or scan observation before source reconciliation runs. The agent cannot identify those sources at that point. It also refreshes## Summarybefore the record is current. This can create incomplete or duplicate findings.First reconcile local and optional GitHub sources. Then write new findings and refresh the summary before proposing fixes or mutating threads.
Also applies to: 63-66, 76-78
|
Thanks @ashrafchowdury much needed |
2 participants
Context
The repo kept agent skills in two places. Nineteen skills lived in the canonical
.agents/skills/(read natively by Codex, symlinked into.claude/skills/for Claude). Five more (scan-codebase,test-codebase,sync-findings,triage-findings,resolve-findings) plus their shared references and thecode-review/diataxisdocs lived in a separate no-dotagents/directory.That no-dot path matches no tool's discovery location, so those five skills were invisible to Claude, Codex, and Cursor. This moves them to the canonical
.agents/location so every tool picks them up, following the single-source-of-truth-plus-symlinks convention the repo already uses.Changes
Relocated the whole tree with
git mv(history preserved; git detects these as pure renames):Then wired discovery and fixed references:
.claude/skills/{scan-codebase,triage-findings,resolve-findings,sync-findings,test-codebase}symlinks into.agents/skills/, matching the existing 19. Codex reads.agents/directly; Claude reads the symlinks.!.claude/skills/<name>negations to.gitignoreso the symlinks are tracked (the dir uses an allowlist).AGENTS.md(diataxis digest), the movedREADME.md, and twodocs/**/findings.mdlinks.agents/directory.Tests / notes
.claude/skillssymlinks resolve to a realSKILL.md; the../shared/references/…links inside each skill still resolve (shared/ moved with them).package.jsonreferenced the old path.services/runner/**andweb/oss/src/components/Drives/driveTree.tsmentionagents/skills/<digest>andagents/sessions/…, and the SDK hassdks/python/agenta/sdk/agents/skills/. These are the runner's in-sandbox runtime namespace and SDK source, unrelated to the repo directory that moved (coincidental name).docs/design/agents-md-compartmentalization/{findings,playbook}.mdstill describe these skills as "invisible to every tool." That is now stale, but those files are a dated design record, so they are left as the snapshot they were.🤖 Generated with Claude Code