spikerj/spikersoft-issues
1
0
Fork 0
Code Issues 196 Pull Requests Actions Packages Projects Releases Wiki Activity

Decompose project knowledge into Cursor rules, skills, and AGENTS.md guardrails #322

New Issue
Closed
opened 2026-07-01 22:29:42 +00:00 by spikerj · 2 comments
spikerj commented 2026-07-01 22:29:42 +00:00
Owner
Copy Link
Copy Source

Extract the load-bearing conventions currently buried in READMEs and code comments into Cursor rules (.cursor/rules/*.mdc) and skills (.cursor/skills/*/SKILL.md) across all three repos, leaving the READMEs in place as canonical deep docs. Thin AGENTS.md files mirror the guardrails for Claude sessions.

Scope

Workspace level (not in a git repo — lives in the multi-root workspace .cursor/):

  • Rule infrastructure-reality.mdc — swarm deploy model, stack≠folder naming, Jaeger VPN-internal access, verified versions
  • Rule telemetry-correlation.mdc — exact Jaeger:EndPoint key, RabbitMQ trace propagation via ActivityHelper, required overlays
  • Skill verify-ci-and-merge — Gitea PR status/diagnose/merge/close-tickets procedure

spikersoft-backend:

  • Refresh project-rules.mdc (stale: traefik v3.5, windows server → verified swarm facts)
  • Rules: worker-architecture, wasm-link-include, api-conventions, testing-conventions
  • Skill add-event-handler-worker (5-piece worker checklist)
  • AGENTS.md; stale-doc fixes (COVERAGE-BASELINE format note, Api README historical-note clarification, SecurityMonitor README MongoDB contradiction)

spikersoft-angular:

  • Rules: library-boundaries, i18n-workflow, e2e-conventions
  • Skill run-e2e-walk
  • AGENTS.md section (outside the nx-managed block); README fixes (eslint config path, stylelint legacy glob note)

spikersoft-infrastructure:

  • AGENTS.md (points at the root README as source of truth)

Motivated by recurring failure classes hit during the #307 epic work: Jaeger:OtlpEndpoint silent misconfig, Wasm Translations link-include break, gpu-coordinator test ctor drift, CORS-after-rate-limiter ordering.

Extract the load-bearing conventions currently buried in READMEs and code comments into Cursor rules (`.cursor/rules/*.mdc`) and skills (`.cursor/skills/*/SKILL.md`) across all three repos, leaving the READMEs in place as canonical deep docs. Thin `AGENTS.md` files mirror the guardrails for Claude sessions. ## Scope **Workspace level** (not in a git repo — lives in the multi-root workspace `.cursor/`): - Rule `infrastructure-reality.mdc` — swarm deploy model, stack≠folder naming, Jaeger VPN-internal access, verified versions - Rule `telemetry-correlation.mdc` — exact `Jaeger:EndPoint` key, RabbitMQ trace propagation via `ActivityHelper`, required overlays - Skill `verify-ci-and-merge` — Gitea PR status/diagnose/merge/close-tickets procedure **spikersoft-backend:** - Refresh `project-rules.mdc` (stale: traefik v3.5, windows server → verified swarm facts) - Rules: `worker-architecture`, `wasm-link-include`, `api-conventions`, `testing-conventions` - Skill `add-event-handler-worker` (5-piece worker checklist) - `AGENTS.md`; stale-doc fixes (COVERAGE-BASELINE format note, Api README historical-note clarification, SecurityMonitor README MongoDB contradiction) **spikersoft-angular:** - Rules: `library-boundaries`, `i18n-workflow`, `e2e-conventions` - Skill `run-e2e-walk` - `AGENTS.md` section (outside the nx-managed block); README fixes (eslint config path, stylelint legacy glob note) **spikersoft-infrastructure:** - `AGENTS.md` (points at the root README as source of truth) Motivated by recurring failure classes hit during the #307 epic work: `Jaeger:OtlpEndpoint` silent misconfig, Wasm `Translations` link-include break, gpu-coordinator test ctor drift, CORS-after-rate-limiter ordering.
spikerj added the enhancement label 2026-07-01 22:29:42 +00:00
spikerj commented 2026-07-03 17:12:30 +00:00
Author
Owner
Copy Link
Copy Source

Claude Code native translation landed (2026-07-03, local working trees — not yet committed):

Claude Code doesn't auto-attach .cursor/rules/*.mdc, so the previous CLAUDE.md workaround ("read every rule file at session start") is replaced with native mirrors in all three repos:

  • Rules → .claude/rules/*.md — same bodies, frontmatter translated (alwaysApply: true → always-loaded; globs:/appliesTo: → paths: so they attach when matching files are touched). 15 rules mirrored across angular/backend/infrastructure.
  • Skills → .claude/skills/<name>/SKILL.md — Cursor's SKILL.md format is directly compatible; all 7 project skills mirrored and verified discoverable (/run-e2e-walk, /verify-ci-and-merge ×3, /add-event-handler-worker, /dotnet-modernization, /native-aot-viability).
  • Agents — e2e-triager and csharp-architect were already mirrored at .claude/agents/; unchanged.
  • CLAUDE.md / AGENTS.md updated to document the mirror convention (edit both copies when changing a rule/skill).
  • verify-ci-and-merge SKILL.md (all copies) now names the Gitea MCP server for both tools: user-gitea (Cursor) / gitea (Claude Code); the same gitea-mcp binary+token is now registered in Claude Code user scope.

Notes:

  • spikersoft-backend/.cursor/rules/dotnet10-guidelines.md is an unwired byte-duplicate of net-core-10.mdc — not mirrored; candidate for deletion.
  • Remaining: commit the .claude/ mirrors in each repo.
**Claude Code native translation landed** (2026-07-03, local working trees — not yet committed): Claude Code doesn't auto-attach `.cursor/rules/*.mdc`, so the previous CLAUDE.md workaround ("read every rule file at session start") is replaced with native mirrors in all three repos: - **Rules → `.claude/rules/*.md`** — same bodies, frontmatter translated (`alwaysApply: true` → always-loaded; `globs:`/`appliesTo:` → `paths:` so they attach when matching files are touched). 15 rules mirrored across angular/backend/infrastructure. - **Skills → `.claude/skills/<name>/SKILL.md`** — Cursor's SKILL.md format is directly compatible; all 7 project skills mirrored and verified discoverable (`/run-e2e-walk`, `/verify-ci-and-merge` ×3, `/add-event-handler-worker`, `/dotnet-modernization`, `/native-aot-viability`). - **Agents** — `e2e-triager` and `csharp-architect` were already mirrored at `.claude/agents/`; unchanged. - **CLAUDE.md / AGENTS.md** updated to document the mirror convention (edit both copies when changing a rule/skill). - `verify-ci-and-merge` SKILL.md (all copies) now names the Gitea MCP server for both tools: `user-gitea` (Cursor) / `gitea` (Claude Code); the same gitea-mcp binary+token is now registered in Claude Code user scope. Notes: - `spikersoft-backend/.cursor/rules/dotnet10-guidelines.md` is an unwired byte-duplicate of `net-core-10.mdc` — not mirrored; candidate for deletion. - Remaining: commit the `.claude/` mirrors in each repo.
spikerj commented 2026-07-22 02:55:13 +00:00
Author
Owner
Copy Link
Copy Source

Board-sweep verified complete: docs/agent-rules mirrors merged in all three repos (backend #51/#52, angular #91/#92 + .claude mirrors, infra #2/#3, agent defs) and the .claude rules/skills verified present in each tree. Caveat noted by verification: workspace-level non-git .cursor items aren't trackable from the repos. Closing.

Board-sweep verified complete: docs/agent-rules mirrors merged in all three repos (backend #51/#52, angular #91/#92 + .claude mirrors, infra #2/#3, agent defs) and the .claude rules/skills verified present in each tree. Caveat noted by verification: workspace-level non-git .cursor items aren't trackable from the repos. Closing.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agentic
Actionable surfaced by the agentic architecture & security review
 bug
Something is not working
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 sonarqube
Code quality issue surfaced by SonarQube (bug / code smell)
 wontfix
This won't be fixed
No labels enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
spikerj (Joseph Spiker)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: spikerj/spikersoft-issues#322