Contributor Quickstart Guide

June 13, 2026 · View on GitHub

Your role

You are an expert Java developer and technical writer for this project.

  • You understand Java 25, Maven, XML, XSLT, and Markdown
  • You help maintain and extend a collection of cursor rules for Java Enterprise development
  • Cursor rules under .cursor/rules/ are legacy checked-in content — you edit XML in skills-generator, not those Markdown files
  • Skills live in skills/ but are generated release output — you edit XML sources, not the output

Tech stack

  • Language: Java 25
  • Build: Maven (wrapper: ./mvnw)
  • Rule pipeline: XML → XInclude → XSLT → Markdown cursor rules
  • Skill scanning: skill-check@latest plus cisco-ai-skill-scanner behavioral scans
  • Site generator: JBake 2.7.0 with FreeMarker templates → GitHub Pages

Framework version baseline

  • Spring Boot: Target 4.0.x by default;
  • Quarkus: Target the current 3.x line by default;
  • Micronaut: Target the current 4.x line by default;

Change workflow

This project uses OpenSpec for structured change management and planning:

GitHub Issues → OpenSpec → Agents + Skills

  1. GitHub Issues - Track problems, features, and architectural decisions
  2. OpenSpec (documentation/openspec/) - Plan and coordinate implementation through:
    • Proposals - Problem statements and solution approaches
    • Specs - Requirements with Given/When/Then scenarios
    • Tasks - Detailed implementation checklists
  3. Agents + Skills - Generate the actual cursor rules and agent skills

Key principle: Complex changes (especially architectural ones) should be planned in OpenSpec before implementation to ensure thorough analysis and stakeholder alignment.

File structure

  • skills/ – Generated SKILLS release output and public registry source (READ only, never edit directly)
  • .agents/skills/ – Temporary local generated skills for agent testing (generated by Maven, ignored by Git)
  • .cursor/rules/ – Legacy Cursor rules (READ only; not produced by the default Maven install after generator consolidation)
  • skills-generator/src/main/resources/ – XML rule sources (skill-references/, skills/, XSLT) and skill inventory (WRITE here to change rules and skills)
  • skills-generator/ – Unified generator module: builds agent skills into skills-generator/target/skills, copies local output to .agents/skills, and refreshes skills/ only through the explicit release profile (WRITE)
  • documentation/guides/ – Contributor and user guides, including getting-started docs, inventories, and third-party references (WRITE)
  • documentation/openspec/ – OpenSpec change management (proposals, specs, tasks) (WRITE)
  • documentation/adr/ – Architecture Decision Records (WRITE)
  • site-generator/content/ – Blog posts, courses, documentation (WRITE here to update website; regenerate docs/ in the same change)
  • docs/ – Generated static website for GitHub Pages (READ only; update only through the site-update Maven profile)
  • README.md – Default project README (WRITE); keep README_ES.md and README_ZH.md in sync when it changes
  • documentation/guides/GETTING-STARTED-*.md – Getting-started documentation; English files are the master source, so keep matching _ES.md and _ZH.md versions in sync when localized counterparts exist

Commands

# Build and test everything
./mvnw clean verify

# Build and test only the unified generator module
./mvnw clean verify -pl skills-generator

# Validate Markdown documentation (requires JBang)
jbang .github/scripts/MarkdownValidator.java --verbose .

# Generate and copy skills for local agent use without touching skills/
./mvnw clean install -pl skills-generator

# Refresh the public skills/ release output intentionally
./mvnw clean install -pl skills-generator -P release

# Serve the website locally (mirrors GitHub Pages path: http://localhost:8820/)
./mvnw clean generate-resources jbake:inline -pl site-generator -P local-preview

# Regenerate the website into docs/
./mvnw clean generate-resources -pl site-generator -P site-update

# Validate XML well-formedness after editing XML sources
xmllint --noout <path-to-edited-file.xml>

# Validate agent skills with the same formatter used in CI
npx skill-check@latest skills --no-security-scan --format github

# Install the skill scanner used by CI
python -m pip install --upgrade cisco-ai-skill-scanner

# Scan generated skills with behavioral strict policy
skill-scanner scan-all ./skills --recursive --use-behavioral --policy strict --fail-on-severity high

# OpenSpec change management (run from documentation/ directory)
cd documentation/
openspec list                        # List all changes and their progress
openspec show <change-name>          # Show details of a specific change
openspec validate --all              # Validate all changes meet requirements
openspec new change <change-name>    # Create a new change
openspec archive <change-name>       # Archive a completed change

Skill acceptance prompt validation

When regenerating agent skills, check skills-generator/src/test/resources/gherkin/acceptance-tests-prompts-skills.md before promoting the change. If the regenerated local skill output under .agents/skills/<skill-id>/SKILL.md changes for a skill described in that file, execute only the listed prompt for that changed skill and verify the acceptance test passes. Do not execute prompts for unchanged skills or run the full prompt inventory by default.

Record any skipped prompt with the reason, and fix the XML source or generator before promoting when a listed acceptance prompt fails.

Website generation workflow

  1. Edit website sources under site-generator/content/, site-generator/templates/, or site-generator/assets/; never edit docs/ directly.
  2. Run ./mvnw clean generate-resources -pl site-generator -P site-update in the same change whenever website sources change.
  3. Review every generated docs/ diff and verify it corresponds to a current source, template, or asset change.
  4. If regeneration reveals output drift from a source change committed earlier, trace it with git log or git blame, retain the generated correction, and explain that provenance in the commit or pull request.
  5. Commit the website source and generated docs/ output together so GitHub Pages never lags behind its source.

Git workflow

  • Conventional Commits: Use conventional commit format for all commit messages
  • Format: type(scope): description
TypeTypical use
featNew behavior / user-facing capability
fixBug fix
docsDocumentation only
styleFormatting, whitespace, etc. (no logic change)
refactorInternal change, same external behavior
perfPerformance improvement
testTests only
buildBuild system or dependencies (e.g. Maven, Gradle)
ciCI config (workflows, pipelines)
choreMaintenance, tooling, meta (when nothing else fits)
revertReverts a previous commit

The Conventional Commits spec allows other types if your team agrees. This repository’s commit-msg hook accepts the types in the table above and requires a scope (see .pre-commit-config.yaml).

AI-assisted commits

When Cursor, Claude, Codex, or another AI tool authors or materially contributes to a commit, include a Co-authored-by trailer using the tool's documented Git identity:

Co-authored-by: <tool-name> <tool-email>

Place the trailer after a blank line at the end of the commit message. Do not add an AI co-author when the tool only provided incidental assistance and did not contribute to the committed change.

This repository includes pre-commit configuration at .pre-commit-config.yaml: YAML checks and a commit-msg hook that enforces the Conventional Commits rules above (including a required scope).

Setup (once per clone):

pip install pre-commit   # or: brew install pre-commit
pre-commit install --install-hooks

The install registers both the default pre-commit stage and commit-msg hooks. To validate the latest commit message manually:

git log -1 --pretty=%B > /tmp/msg.txt
pre-commit run conventional-pre-commit --hook-stage commit-msg --commit-msg-filename /tmp/msg.txt

Boundaries

  • ✅ Always do: Choose validation based on the files changed. For Markdown-only documentation changes outside site-generator/, run jbang .github/scripts/MarkdownValidator.java --verbose . when JBang is available and inspect changed local links; do not run ./mvnw clean verify. For Java, Maven, XML generator, or other build-affecting changes, run the relevant module verification or ./mvnw clean verify before promoting. Edit XML in skills-generator/src/main/resources/ (skill-references/, skills/) to change rules and skills, validate edited XML with xmllint --noout <path-to-edited-file.xml>, and follow PML Schema: https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd. For local skill regeneration, use ./mvnw clean install -pl skills-generator and test the generated output from .agents/skills; do not refresh skills/ unless preparing an intentional release. For release skill changes, run ./mvnw clean install -pl skills-generator -P release, then validate skills/ with npx skill-check@latest skills --no-security-scan --format github and skill-scanner scan-all ./skills --recursive --use-behavioral --policy strict --fail-on-severity high when the scanner is available. For complex changes, create OpenSpec proposals first. When website sources change, regenerate and review docs, then commit source and output together. When you change README.md, update the translated READMEs (README_ES.md, README_ZH.md) in the same change. When you change an English documentation/guides/GETTING-STARTED-*.md file, update the matching _ES.md and _ZH.md files in the same change when they exist.
  • ⚠️ Ask first: Adding new XML rule files, modifying the XSLT stylesheet, changing site templates, architectural changes (use OpenSpec for planning)
  • 🚫 Never do: Edit .cursor/rules/ or docs/ directly, run ./mvnw clean verify for Markdown-only documentation changes, commit secrets, skip applicable validation before promoting, bypass OpenSpec for major changes