From c507e20a2273a7e3dd4e8f60973a2fac85e0b1d8 Mon Sep 17 00:00:00 2001 From: Matus Kasak Date: Tue, 12 May 2026 10:27:27 +0200 Subject: [PATCH] Created md files for agents --- .github/agents/agents-fix-review.md | 85 +++++++++++++++ .github/agents/agents-pr.md | 154 ++++++++++++++++++++++++++++ .github/skills/dspace-dev.SKILL.md | 43 ++++++++ .github/skills/pr-quality.SKILL.md | 36 +++++++ .github/skills/security.SKILL.md | 36 +++++++ AGENTS.md | 68 ++++++++++++ 6 files changed, 422 insertions(+) create mode 100644 .github/agents/agents-fix-review.md create mode 100644 .github/agents/agents-pr.md create mode 100644 .github/skills/dspace-dev.SKILL.md create mode 100644 .github/skills/pr-quality.SKILL.md create mode 100644 .github/skills/security.SKILL.md create mode 100644 AGENTS.md diff --git a/.github/agents/agents-fix-review.md b/.github/agents/agents-fix-review.md new file mode 100644 index 00000000000..a58f983950e --- /dev/null +++ b/.github/agents/agents-fix-review.md @@ -0,0 +1,85 @@ +# Agents Review Loop Playbook + +Standard process for handling PR review feedback with minimal risk. + +## Loop Entry Condition +Use this playbook after PR is opened/updated and review/check statuses are being monitored. + +Carry forward the checklist initialized in `.github/agents/agents-pr.md` and keep it updated during each review cycle. + +## Parse Review Feedback +- Gather all open comments from PR review and inline threads. +- Normalize each comment into: + - `type`: blocking or non-blocking + - `area`: file/component/test/doc + - `expected_change`: explicit action + +Suggested data refresh cadence: +- Default cadence: refresh review data and checks/status every 5 minutes. +- Active cadence: switch to every 2 minutes when new comments appear, checks are failing, or quick follow-up is needed near status transitions. +- Update checklist status after each refresh. + +## Prioritize +1. Blocking correctness issues +2. Regressions and failing checks +3. Test gaps for changed behavior +4. Non-blocking cleanups and readability suggestions + +## Execution Rules +- Apply small, atomic commits per feedback cluster. +- Do not mix unrelated refactors into review-fix commits. +- Preserve public behavior unless comment explicitly requests behavior change. +- Keep commit messages traceable to review topics. +- For each Copilot/human suggestion, make explicit decision: + - `accept`: implement and validate + - `decline`: add concise PR reply with technical rationale + +Blocking suggestions must not be ignored silently. + +## Test Strategy Per Iteration +- After each review round, re-run relevant tests first. +- Minimum per changed area: + - targeted test(s) for touched component/service + - lint for touched code +- Before marking comments resolved, confirm required full checks still pass: + - `yarn run lint --quiet` + - `yarn run check-circ-deps` + - `yarn run build:prod` + - `yarn run test:headless` + +## Reporting Back in PR +For each resolved feedback item, report: +- what was changed +- where it was changed +- what test/validation was run +- why solution is safe + +Suggested template: +- `Fixed:` +- `Files:` +- `Validation:` +- `Notes:` + +For declined suggestions, use: +- `Not applied:` +- `Reason:` +- `Risk:` + +## Polling Completion Rule +Continue adaptive polling loop (5-minute default, 2-minute active mode) until all are true: +- required checks are green +- no unresolved blocking review comments +- no pending requested changes from required reviewers + +When complete, mark checklist items `review comments handled` and `checks green` as done. + +If loop exceeds 90 minutes or repository API access is insufficient, stop and return `BLOCKER REPORT` with: +- current PR URL +- unresolved checks/comments +- exact next commands for human follow-up +- checklist state at time of stop + +## Safety +- If feedback is ambiguous, document assumption in PR comment before deep refactor. +- If comment requests scope expansion, split into follow-up issue unless explicitly approved. +- If repeated failures persist, escalate after third loop as human handoff. diff --git a/.github/agents/agents-pr.md b/.github/agents/agents-pr.md new file mode 100644 index 00000000000..7a822adf278 --- /dev/null +++ b/.github/agents/agents-pr.md @@ -0,0 +1,154 @@ +# Agents PR Playbook + +Canonical end-to-end workflow for: issue -> branch -> fix -> PR -> review loop -> green checks. + +## Trigger +Use this playbook automatically when user input includes any of the following: +- issue URL +- issue ID +- phrases like "fix bug", "resolve issue", "implement issue" + +Do not require user to explicitly ask for branch/PR creation. + +## Input +- `issue_number`: GitHub issue ID, for example `1234` +- `target_branch`: default `dtq-dev` unless issue says otherwise +- `scope`: explicit in-scope change list and out-of-scope list + +If user does not provide `target_branch`, assume `dtq-dev`. + +## Step 0: Initialize Task Checklist +Create and keep a compact checklist for this run. Suggested statuses: `not-started`, `in-progress`, `done`, `blocked`. + +Suggested checklist template: +- issue parsed +- scope confirmed +- branch created +- fix implemented +- local checks passed +- PR opened/updated +- Copilot review requested +- review comments handled +- checks green + +Update checklist after every major step and use it as the source of truth for continuation. + +## Step 1: Load Issue Context +- Read issue title, description, linked comments, and acceptance criteria. +- Extract explicit constraints: UI behavior, backward compatibility, SSR impact, test expectations. +- If acceptance criteria are missing, add an assumption block in PR notes. +- Mark checklist item `issue parsed` and `scope confirmed`. + +## Step 2: Create Branch +- Update local target branch and branch off from it. +- Naming: + - Feature: `feat/issue--` + - Bugfix: `fix/issue--` +- Keep branch scoped to a single issue. +- Mark checklist item `branch created`. + +## Step 3: Implement Minimal Fix +- Start with smallest viable code change that satisfies acceptance criteria. +- Keep changes localized. +- Preserve existing architecture patterns and SSR compatibility. +- Add or update tests only where behavior changes. +- Mark checklist item `fix implemented` when done. + +## Step 4: Validate Locally (Required Order) +1. `yarn install --frozen-lockfile` +2. `yarn run lint --quiet` +3. `yarn run check-circ-deps` +4. `yarn run build:prod` +5. `yarn run test:headless` + +Notes: +- Use Yarn, never npm. +- Node runtime for local agent runs should follow `.github/copilot-instructions.md`. +- If only a focused area changed, run targeted unit tests first, then run full required sequence before final PR-ready state. +- Mark checklist item `local checks passed` only after required sequence succeeds. + +## Step 5: Open or Update PR +- Create PR targeting `target_branch`. +- Prefer GitHub CLI for deterministic automation: + - `gh pr create --base --head --title "" --body-file <file>` + - or `gh pr edit <pr_number> --title "<title>" --body-file <file>` for updates +- Include: + - problem statement + - root cause + - fix summary + - test evidence (commands + result) + - risks and rollback notes +- Link issue using `Fixes #<issue_number>` when appropriate. + +If `gh` auth or permissions are missing, stop and return blocker details (see Output Contract below). +- Mark checklist item `PR opened/updated`. + +## Step 6: Trigger Review +- Request human reviewer(s). +- Request Copilot review after PR is created/updated. +- Keep discussion on concrete code/test outcomes. + +Recommended commands (adapt to org permissions): +- `gh pr comment <pr_number> --body "@copilot review"` +- `gh pr edit <pr_number> --add-reviewer <github-user-or-team>` + +If review request cannot be sent due to permissions, continue with polling and return a note in final summary. +- Mark checklist item `Copilot review requested` when request succeeds, otherwise `blocked` with reason. + +## Step 7: Post-PR Polling Loop (Adaptive Cadence) +After PR creation/update, start polling loop and continue until exit criteria are met: +1. Refresh review comments and review threads. +2. Refresh CI/check status. +3. If new blocking feedback exists: + - follow `.github/agents/agents-fix-review.md` + - decide per comment: implement now or respond with explicit rationale + - push fixes and continue polling +4. If checks are red: + - inspect failing jobs/logs + - apply focused fix + - re-run relevant local checks + - push and continue polling + +Polling cadence: +- Default: sleep/wait approximately 5 minutes between status refresh cycles. +- Active mode: use 2-minute polling when at least one is true: + - new review comments arrived in the last cycle + - any required check is failing + - required checks are close to completion and frequent refresh is useful +- Keep looping until checks are green and no unresolved blocking comments remain. +- Update checklist on each cycle (`review comments handled`, `checks green`). + +Maximum unattended polling window: +- 90 minutes by default. +- If still not converged, return `BLOCKER REPORT` with current PR state and next human commands. + +## Exit Criteria +- Required checks are green. +- No unresolved blocking review comments. +- Required approvals are present according to repo policy. +- PR description reflects final code and test state. + +Post-PR loop cannot exit early while checks are pending/failing or while blocking comments are unresolved. + +## Output Contract (Mandatory) +Issue/bug task is complete only if final output contains exactly one of: +- `PR URL: <https://...>` + - include final check status summary + - include review status summary (blocking comments resolved) + - include final checklist state +- `BLOCKER REPORT:` + - failing step + - exact error summary + - exact follow-up command(s) for human + - checklist state at time of block + +Returning only "code fixed" or "local tests passed" is not sufficient completion. + +## Safety Constraints +- Max 3 review/fix iterations by agent. +- If still unstable after 3 iterations, handoff to human with: + - unresolved blockers + - tried fixes + - suspected root cause + - recommended next step +- Do not expand scope without explicit justification in PR notes. diff --git a/.github/skills/dspace-dev.SKILL.md b/.github/skills/dspace-dev.SKILL.md new file mode 100644 index 00000000000..9ec072dd80e --- /dev/null +++ b/.github/skills/dspace-dev.SKILL.md @@ -0,0 +1,43 @@ +# dspace-dev Skill + +Canonical development commands and validation flow for this repository. + +## Environment Baseline +- Use Yarn 1.x commands. +- Follow repository Copilot instructions for local Node runtime selection. +- Always install dependencies before validation runs: + - `yarn install --frozen-lockfile` + +## Canonical Commands +- Install deps: `yarn install --frozen-lockfile` +- Lint: `yarn run lint --quiet` +- Circular dependencies: `yarn run check-circ-deps` +- Production build: `yarn run build:prod` +- Unit tests (headless): `yarn run test:headless` +- Dev server: `yarn run start:dev` +- SSR serve after build: `yarn run serve:ssr` + +## Required Validation Order +1. `yarn install --frozen-lockfile` +2. `yarn run lint --quiet` +3. `yarn run check-circ-deps` +4. `yarn run build:prod` +5. `yarn run test:headless` + +## Focused Test Runs +- Single or subset unit tests: + - `yarn run test:headless --include='**/path/to/file.spec.ts'` +- Fast local loop recommendation: + - run focused tests first + - then run full required validation order before PR readiness + +## E2E Context +- E2E command from package scripts: `yarn run e2e` +- In CI, Cypress runs against SSR server and Docker backend as defined in `.github/workflows/build.yml`. + +## PowerShell Note +If circular dependency command parsing fails in PowerShell due to `|`, use stop-parsing form: +- `npx --% madge --exclude "(bitstream|bundle|collection|config-submission-form|eperson|item|version)\.model\.ts$" --circular --extensions ts ./` + +## Assumption +- Full local CI-equivalent validation does not require changing repository CI workflow files. diff --git a/.github/skills/pr-quality.SKILL.md b/.github/skills/pr-quality.SKILL.md new file mode 100644 index 00000000000..ec6d1fd732b --- /dev/null +++ b/.github/skills/pr-quality.SKILL.md @@ -0,0 +1,36 @@ +# pr-quality Skill + +Checklist and structure for high-quality PRs in this repository. + +## PR Narrative Template +- Problem: What user-facing or system behavior is wrong. +- Root Cause: Why current code fails. +- Change Set: What was modified and why this is minimal. +- Test Evidence: Exact commands run and summary outcomes. +- Risk: Potential side effects and mitigations. +- Rollback: How to revert safely if needed. + +## Required Checklist +- Issue linked (for example `Fixes #1234`) when applicable. +- Scope is limited to the issue. +- Lint passed. +- Circular dependency check passed. +- Build passed. +- Unit tests passed. +- Public API changes include required docs/comments where applicable. +- New behavior has tests or explicit justification if tests are not possible. + +## Review Readiness +- Diff is easy to review and split into logical commits. +- No unrelated file churn. +- PR description includes assumptions and non-goals. +- Known pre-existing failures (if any) are explicitly separated from new failures. + +## Suggested Validation Section +- `yarn run lint --quiet` -> pass +- `yarn run check-circ-deps` -> pass +- `yarn run build:prod` -> pass +- `yarn run test:headless` -> pass + +## Definition of Done for PR Quality +- Reviewer can verify fix from PR text plus command evidence, without guessing intent. diff --git a/.github/skills/security.SKILL.md b/.github/skills/security.SKILL.md new file mode 100644 index 00000000000..74ca587d475 --- /dev/null +++ b/.github/skills/security.SKILL.md @@ -0,0 +1,36 @@ +# security Skill + +Mandatory safety guardrails for agent-driven changes. + +## Hard Prohibitions +- Never commit secrets, tokens, passwords, private keys, or credential dumps. +- Never add real credentials to tests, config, docs, or screenshots. +- Never run destructive git operations without explicit human approval: + - `git reset --hard` + - `git checkout -- <path>` + - history rewrites on shared branches +- Never push directly to protected integration branches (`dtq-dev`, `main`). + +## Repository Hygiene +- Do not commit runtime/local artifacts, including: + - `.env*` + - `coverage/` + - `cypress/videos/` + - `cypress/screenshots/` + - temporary logs or local debug dumps +- Do not silently change CI policy files unless task explicitly requires it. + +## Change Safety +- Keep scope minimal and issue-focused. +- Re-run validation after each meaningful change. +- Stop and request human handoff if fix path becomes unclear or risky. + +## Review Safety +- Mark assumptions explicitly when requirements are ambiguous. +- If requested change conflicts with existing policy/docs, document conflict and choose policy-compliant path. + +## Incident Rule +If accidental sensitive data appears in working tree: +- stop further edits +- report file path and exposure risk +- wait for human remediation instruction diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..8013cce5f1c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Agent Automation Framework + +This repository uses a lightweight agent automation framework for the loop: +Issue -> fix -> PR -> review loop -> checks green. + +## Purpose +- Define one entrypoint for agent behavior. +- Keep issue-to-PR flow deterministic and auditable. +- Reuse canonical project commands and CI-aligned checks. + +## Auto-Dispatch Rules +When a user gives a high-level request (for example: "fix this issue", "resolve this bug", or shares an issue URL), the agent must use this routing automatically: +1. Read this file (`AGENTS.md`) first. +2. If request is issue/bug implementation, load `.github/agents/agents-pr.md`. +3. Run implementation and local validation from that playbook. +4. After PR is opened/updated, if review feedback exists, load `.github/agents/agents-fix-review.md` and execute review loop. +5. Use `.github/skills/*.SKILL.md` files only when the current step needs that capability (dev commands, PR quality, security constraints). + +This means users do not need a specialized prompt to trigger the full workflow. + +## Progress Tracking Contract +For long-running issue/PR tasks, the agent must maintain a short live checklist of steps and status. + +Minimum checklist items: +- issue parsed and scope confirmed +- branch created +- implementation done +- local validation done +- PR opened/updated +- review loop status +- checks status + +Rules: +- initialize checklist near the beginning of execution +- update checklist after each major step +- use checklist state to avoid skipping steps or repeating completed work +- include final checklist state in completion summary + +## Entry Documents +- Main PR workflow playbook: `.github/agents/agents-pr.md` +- Review iteration playbook: `.github/agents/agents-fix-review.md` +- Project dev commands skill: `.github/skills/dspace-dev.SKILL.md` +- PR quality skill: `.github/skills/pr-quality.SKILL.md` +- Security guardrails skill: `.github/skills/security.SKILL.md` +- Extended human+agent operational guide: `docs/agents.md` + +## Hard Rules +- Never push directly to `dtq-dev` or `main`. +- Always use an issue branch (`feat/issue-<id>-<slug>` for features, `fix/issue-<id>-<slug>` for bugfixes). +- Run required validation before requesting final review: lint, circular dependency check, build, unit tests. +- Do not expand issue scope without explicit reason documented in PR. +- No destructive git commands (`git reset --hard`, `git checkout -- <path>`) unless explicitly approved by a human owner. +- Do not commit local/runtime artifacts (for example `.env*`, `coverage/`, `cypress/videos/`, `cypress/screenshots/`). + +## PR Workflow Pointer +Use `.github/agents/agents-pr.md` as the canonical issue-to-PR workflow document. + +## Completion Contract +For issue/bug requests, "done" means one of the following: +- PR successfully opened or updated, required checks are green, no unresolved blocking review comments remain, and agent returns `PR URL` + validation summary. +- PR could not be opened due to a concrete blocker, and agent returns `BLOCKER REPORT` with exact failing step and exact commands for human follow-up. +- PR exists but post-PR loop could not finish (for example missing API permission for review/check status), and agent returns `BLOCKER REPORT` with exact failing step and exact commands for human follow-up. + +A local code fix without `PR URL` or `BLOCKER REPORT` is not considered complete. + +## Assumptions +- Default integration branch in this fork is `dtq-dev` (from repository workflow configuration). +- If a specific issue or maintainer instruction requires another target branch, that instruction overrides this default.