chore: align repo with agentic SDLC scaffolding practices

[NilashishC]

Description

Align ansible-backstage-plugins with Agentic SDLC repo scaffolding best practices — better AI agent context, deterministic enforcement, and contributor onboarding.

Ref: https://gitlab.cee.redhat.com/global-engineering/wg-agentic-sdlc/-/blob/main/best-practices/repo-scaffolding/README.md?ref_type=heads

Changes

1. Agent context (Tier 1)

.cursorrules - trimmed to pointer (~186 lines removed)

Change: Replaced duplicated project guidance with a short pointer to AGENTS.md.

Reasoning: Best practice 1.2: single source of truth for agent context. Duplicated .cursorrules / AGENTS.md content drifts over time; agents and humans should read one canonical file.

AGENTS.md - expanded and corrected

Changes:

• Fast-feedback lint/type-check commands (single file / package)
• Note that yarn workspace <pkg> exec <bin> does not work in Yarn 4 with nodeLinker: node-modules
• Pre-commit / Husky workflow documented
• Import boundary enforcement documented
• AI attribution conventions documented

Reasoning: Best practice 1.3: agents need copy-paste commands that actually work. Wrong commands (e.g. broken exec tsc) waste agent cycles. Documenting architecture boundaries helps agents avoid invalid imports before CI catches them.

---

2. Deterministic enforcement (Tier 2)

.husky/pre-commit - delegate to pre-commit

Change: Replaced yarn lint-staged with pre-commit run --hook-stage pre-commit.

Reasoning: Best practice 2.2: one IDE-agnostic enforcement layer. Husky is only the Git entry point; hook logic lives in .pre-commit-config.yaml (same locally and in CI).

.pre-commit-config.yaml - ESLint + commit-msg hooks

Changes:

• Added eslint local hook → scripts/pre-commit-lint.sh
• Removed always_run: true from Prettier (only runs on staged matching files)
• Added check-commit-attribution hook (stages: [commit-msg])

Reasoning: Centralizes all commit-time checks. ESLint via Backstage CLI handles monorepo package boundaries; attribution hook enforces Red Hat AI commit policy at commit time, not only in CodeRabbit review.

scripts/pre-commit-lint.sh (new)

Change: Runs yarn backstage-cli repo lint --fix; if e2e files are staged, runs tsc --noEmit in e2e-tests/.

Reasoning: Root npx eslint breaks on e2e TypeScript (wrong config/parser). Backstage CLI is monorepo-aware; e2e gets a separate type-check only when relevant files are staged.

package.json - removed lint-staged

Change: Dropped lint-staged script, config block, and devDependency.

Reasoning: Avoids two parallel lint paths (lint-staged vs pre-commit). Single source of truth reduces drift and “passes locally, fails in CI” surprises.

.config/eslint-architecture.js (new)

Change: Shared ESLint rules for three plugin tiers:

• Frontend: no backend imports; no AAPClient / ScmClient from common barrel
• Backend: no frontend plugin imports
• Common: no imports from other plugins

Reasoning: Best practice 3.3: architectural boundaries should be machine-enforced, not just documented. Matches the dependency flow in AGENTS.md and prevents frontend → AAP direct access.

Plugin .eslintrc.js files (6 plugins)

Change: Each extends eslint-architecture.js with the appropriate profile (frontend, backend, or common).

Reasoning: Wires boundary rules into each package’s existing Backstage ESLint factory config.

Minor Prettier formatting fixes (8 source files)

Files: GitlabClient.ts, helpers.ts, prepareForPublish.ts, EEDetailsPage.tsx, useLatestCIActivity.ts, AAPResourcePicker.tsx, CollectionsPickerExtension.tsx

Reasoning: Incidental — auto-fixed when ESLint/Prettier ran during the new pre-commit hook. No behavior change.

---

3. Onboarding (Tier 2)

install-deps: install pre-commit CLI

Change: After yarn install, runs python3 -m pip install pre-commit and pre-commit install-hooks (with fallback via python3 -m pre_commit).

Reasoning: Closes onboarding gap. Contributors previously had to manually pip install pre-commit or commits would fail at the Husky hook. Prefetching hook envs speeds up the first commit.

.config/requirements.txt: added pre-commit

Change: One-line addition at top of requirements file.

Reasoning: Aligns Python dev deps with what CI/docs expect; available for docs tooling installs.

README.md, CONTRIBUTING.md, docs/installation.md

Changes:

• Document that install-deps installs pre-commit
• Manual fallback if Python/pip unavailable
• AI attribution patterns (Assisted-by / Generated by, no email required)

Reasoning: Onboarding docs should match actual setup flow. Contributors shouldn’t discover missing pre-commit only at first git commit.

---

4. AI commit attribution (Tier 2 + policy)

scripts/check-commit-attribution.sh (new)

Change: commit-msg validation that rejects Co-authored-by: lines naming AI tools/bots (Cursor, Claude, Copilot, [bot], etc.). Allows human co-authors and accepted patterns:

Assisted-by: <name of code assistant>
Generated by <name of code assistant>

Reasoning: Red Hat policy and Linux kernel precedent: AI tools must not use Co-authored-by. Enforcement at commit time is stronger than CodeRabbit warnings alone. Human pair-programming co-authors remain valid.

.husky/commit-msg (new)

Change: Runs pre-commit run check-commit-attribution --hook-stage commit-msg --commit-msg-filename "$1".

Reasoning: Husky triggers validation; only the attribution hook runs (not Prettier on .git/COMMIT_EDITMSG, which caused failures when all hooks ran on commit-msg stage).

.coderabbit.yaml: ai-attribution instruction update

Change: Clarified accepted patterns: "Assisted-by: <tool>" or "Generated by <tool>" (no email required).

Reasoning: Keeps automated PR review aligned with local hook policy and contributor docs.

Related Issues

N/A

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Chore

Testing

N/A

Screenshots (if applicable)

N/A

Checklist

• Code follows project style
• Tests pass locally
• Documentation updated

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ad7f33dc-bc57-4c74-9982-e7cf1cf738e3

---

_{Comment @coderabbitai help to get the list of available commands.}

[NilashishC]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 95.69%. Comparing base (afb129c) to head (041a9ac).

Files with missing lines	Patch %	Lines
.../components/GitRepositories/useLatestCIActivity.ts	66.66%	1 Missing ⚠️

@@            Coverage Diff             @@
##             main     #599      +/-   ##
==========================================
- Coverage   95.69%   95.69%   -0.01%     
==========================================
  Files         231      231              
  Lines       14296    14298       +2     
  Branches     3857     3859       +2     
==========================================
+ Hits        13681    13682       +1     
- Misses        601      602       +1     
  Partials       14       14              

Flag	Coverage Δ
plugins	95.69% <90.90%> (-0.01%)	⬇️

Files with missing lines	Coverage Δ
.../backstage-rhaap-common/src/AAPClient/AAPClient.ts	91.83% <ø> (ø)
...ckstage-rhaap-common/src/ScmClient/GitlabClient.ts	97.11% <100.00%> (ø)
...lugins/catalog-backend-module-rhaap/src/helpers.ts	97.61% <100.00%> (ø)
...e-backstage-rhaap/src/actions/prepareForPublish.ts	100.00% <100.00%> (ø)
...ts/ExecutionEnvironments/catalog/EEDetailsPage.tsx	92.20% <ø> (ø)
.../Scaffolder/AAResourcePicker/AAPResourcePicker.tsx	91.04% <ø> (ø)
...r/CollectionsPicker/CollectionsPickerExtension.tsx	89.38% <ø> (ø)
.../components/GitRepositories/useLatestCIActivity.ts	96.32% <66.66%> (-0.70%)	⬇️

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update afb129c...041a9ac. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[abhikdps]

LGTM

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
1 Accepted issue

Measures
0 Security Hotspots
93.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud