Agent automation framework for issue to PR workflow

.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:` <short description>
+- `Files:` <paths>
+- `Validation:` <commands/results>
+- `Notes:` <compatibility or tradeoff>
+
+For declined suggestions, use:
+- `Not applied:` <short description>
+- `Reason:` <technical rationale>
+- `Risk:` <why current state is safe>
+
+## 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.

.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-<id>-<slug>`
+  - Bugfix: `fix/issue-<id>-<slug>`
+- 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 <target_branch> --head <branch_name> --title "<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.

.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.

.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.

.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