feat(agents): agentic infrastructure - skills, subagents, hooks, and cross-tool config

[seriouslysean]

Issue number

No linked issue — developer experience infrastructure.

Please check the following

• Do the tests still pass? (npm run test:unit 3/3, npm run test:agents 29/29)
• Is the code formatted properly? (npm run lint clean)
• For New Features:
  • Have tests been added to cover any new features or fixes? (29 vitest tests for git-guardrails)
  • Has the documentation been updated accordingly? (.agents/README.md and .agents/docs/ are the documentation)

Please describe additional details for testing this change

This PR adds agentic infrastructure — it has no effect on game behavior. Verification steps:

1. Symlinks resolve: readlink .claude/skills → ../.agents/skills; same for .claude/agents, .gemini/skills, .gemini/agents
2. Hook fires on main: git commit --allow-empty -m "test" while on main should be denied with a clear message
3. Hook passes on a feature branch: same command on any non-main branch should be allowed
4. AGENTS.md / CLAUDE.md / GEMINI.md unchanged: git diff main -- AGENTS.md CLAUDE.md GEMINI.md is empty

What's here vs what's next: The reference skills (ctl-sails-patterns, ctl-vue-patterns, ctl-test-patterns, ctl-game-domain) are currently opt-in. A follow-up will convert these to .claude/rules/ path-specific rules so they load automatically when a matching file is touched, without relying on keyword routing.

[Copilot]

Pull request overview

This PR introduces a shared, tool-agnostic “agentic infrastructure” under .agents/, plus per-tool configuration for Claude/Gemini/Codex, and a Node-based git-guardrails hook with Vitest coverage to prevent destructive git operations and enforce main-branch safety.

Changes:

• Add .agents/ structure (skills, docs, reviewer subagents) as a cross-tool source of truth.
• Add git-guardrails hook (Claude + Gemini wiring) and a dedicated test:agents Vitest suite for hook logic.
• Commit assistant configuration files (.claude/settings.json, .gemini/settings.json, .codex/config.toml) and adjust .gitignore to track shared config while ignoring local overrides.

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
package.json	Adds test:agents script to run .agents tool tests.
.gitignore	Stops ignoring whole assistant dirs; ignores only local override files/dirs.
.gemini/settings.json	Enables agents + runs guardrails before run_shell_command.
.codex/config.toml	Adds Codex project-doc fallback and feature toggles.
.claude/settings.json	Adds Claude allowlist permissions and PreToolUse hook configuration.
.claude/hooks/git-guardrails.sh	Adds a shim to invoke the Node guardrails script.
.agents/tools/vitest.config.mjs	Adds Vitest config for .agents/tools tests.
.agents/tools/git-guardrails.mjs	Implements command parsing + guardrail rules + hook output.
.agents/tools/tests/git-guardrails.spec.mjs	Adds Vitest coverage for guardrail rule behavior.
.agents/skills/ctl-vue-patterns/SKILL.md	Adds Vue/Pinia/Vuetify patterns skill.
.agents/skills/ctl-test-patterns/SKILL.md	Adds Cypress/Vitest testing patterns skill.
.agents/skills/ctl-sails-patterns/SKILL.md	Adds Sails.js backend patterns skill.
.agents/skills/ctl-plan-work/SKILL.md	Adds planning workflow skill (discover → plan → gate).
.agents/skills/ctl-github-create-pr/SKILL.md	Adds gh-based PR creation workflow skill.
.agents/skills/ctl-git-commit/SKILL.md	Adds conventional-commit workflow skill with guardrails.
.agents/skills/ctl-game-domain/SKILL.md	Adds game-domain glossary skill for consistent terminology.
.agents/skills/ctl-discover/SKILL.md	Adds discovery/grep recipes skill.
.agents/skills/ctl-code-review/SKILL.md	Adds review workflow skill + subagent dispatch instructions.
.agents/README.md	Documents .agents/ purpose, layout, and loading model.
.agents/docs/vue-patterns.md	Adds detailed Vue patterns doc referenced by the skill.
.agents/docs/testing.md	Adds detailed testing doc referenced by the skill.
.agents/docs/skill-conventions.md	Defines skill naming/frontmatter conventions.
.agents/docs/sails-patterns.md	Adds detailed Sails patterns doc referenced by the skill.
.agents/docs/github.md	Documents PR labeling/version-bump workflow + gh usage.
.agents/docs/game-domain.md	Adds expanded game-domain glossary.
.agents/docs/doc-format.md	Defines repo doc style conventions.
.agents/docs/commit-format.md	Documents conventional-commit format + repo rules.
.agents/agents/ctl-security-reviewer.md	Adds security reviewer subagent definition.
.agents/agents/ctl-performance-reviewer.md	Adds performance reviewer subagent definition.
.agents/agents/ctl-docs-reviewer.md	Adds docs reviewer subagent definition.
.agents/agents/ctl-architecture-reviewer.md	Adds architecture reviewer subagent definition.

Comments suppressed due to low confidence (2)

.agents/tools/git-guardrails.mjs:112

• execSync('git branch --show-current') runs in the current process CWD. If the hook is invoked from outside the repo (or from a different repo), branch detection will throw and the guardrail won't enforce commit/push rules. Consider running git with an explicit cwd/-C derived from CLAUDE_PROJECT_DIR/GEMINI_PROJECT_DIR (or the resolved repo root).

    );
    const branch = needsBranch
      ? execSync('git branch --show-current', { encoding: 'utf8' }).trim()
      : null;

.agents/docs/testing.md:38

• cy.loadGameFixture is documented here as cy.loadGameFixture(fixture), but the actual Cypress command is defined as loadGameFixture(pNum, fixture, gameId = null) (see tests/e2e/support/commands.js). Please update the signature and example to match real usage (including the required pNum).

### `cy.loadGameFixture(fixture)`

Loads a specific game state. All fields are optional.

```js
cy.loadGameFixture({
  p0Hand: [Card.ACE_OF_CLUBS, Card.SEVEN_OF_CLUBS],

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.