Contributor Quickstart Guide

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 plinth-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
• Dependency scanning: Snyk Maven plugin through the opt-in snyk profile
• 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;

Internal scripts

Use Java with JBang for repository-internal helper scripts such as conversion utilities, example generators, and validation helpers. Do not add new Python or ad hoc shell scripts for this kind of tooling.

Follow the markdown-validator entry-point pattern: a JBang-compatible .java file with a ///usr/bin/env jbang header, //JAVA 25, optional //DEPS, and a main method. Run with:

jbang path/to/Script.java [args]

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)
• plinth-commands-generator/ – Embedded command inventory, markdown assets, loader code, and command-focused tests (WRITE)
• plinth-agents-generator/ – Embedded agent inventory, markdown assets, loader code, and agent-focused tests (WRITE)
• plinth-skills-generator/src/main/resources/ – XML rule sources (skill-references/, skills/, XSLT) and skill inventory (WRITE here to change rules and skills)
• plinth-skills-generator/ – Unified generator module: builds agent skills into plinth-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 plinth-commands-generator
./mvnw clean verify -pl plinth-agents-generator
./mvnw clean verify -pl plinth-skills-generator -am

# Validate Markdown documentation (requires JBang)
jbang markdown-validator/src/main/java/info/jab/mv/MarkdownValidator.java .

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

# Refresh the public skills/ release output intentionally
./mvnw clean install -pl plinth-skills-generator -am -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

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

# Install the Snyk CLI with Homebrew
brew tap snyk/tap
brew install snyk

# Authenticate locally with Snyk using the OAuth browser flow
snyk auth

# Scan all Maven modules; in CI, provide SNYK_TOKEN through the CI secret store
./mvnw clean verify -P snyk

# 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 plinth-skills-generator/src/test/resources/gherkin/skills/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.

When adding a new skill Gherkin file under plinth-skills-generator/src/test/resources/gherkin/skills/, also update plinth-skills-generator/src/test/resources/gherkin/skills/acceptance-tests-prompts-skills.md in the same change with the matching prompt to execute that .feature file. Keep the entry grouped by skill id and use the existing execute @...feature format.

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

• On-demand commits only: Never create commits, push branches, or open pull requests automatically. Only do so when the maintainer explicitly asks (e.g. “commit”, “push”, “open a PR”, “commit and pr”).
• Conventional Commits: Use conventional commit format for all commit messages
• Format: type(scope): description

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.

Pre-commit hooks (recommended)

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 markdown-validator/src/main/java/info/jab/mv/MarkdownValidator.java . 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 plinth-skills-generator/src/main/resources/ (skill-references/, skills/) to change rules and skills; edit embedded command sources in plinth-commands-generator/src/main/resources/ (commands.xml, commands/); edit embedded agent sources in plinth-agents-generator/src/main/resources/ (agents.xml, agents/). Validate edited XML with xmllint --noout <path-to-edited-file.xml>, and follow PML Schema: https://jabrena.github.io/pml/schemas/0.9.0/pml.xsd. For local skill regeneration, use ./mvnw clean install -pl plinth-skills-generator -am 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 plinth-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