# 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
- **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:

```bash
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

```bash
# 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

# 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`

| Type | Typical use |
|------|-------------|
| **feat** | New behavior / user-facing capability |
| **fix** | Bug fix |
| **docs** | Documentation only |
| **style** | Formatting, whitespace, etc. (no logic change) |
| **refactor** | Internal change, same external behavior |
| **perf** | Performance improvement |
| **test** | Tests only |
| **build** | Build system or dependencies (e.g. Maven, Gradle) |
| **ci** | CI config (workflows, pipelines) |
| **chore** | Maintenance, tooling, meta (when nothing else fits) |
| **revert** | Reverts a previous commit |

The [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 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`](.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:

```text
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](https://pre-commit.com/) configuration at [`.pre-commit-config.yaml`](.pre-commit-config.yaml): YAML checks and a **commit-msg** hook that enforces the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) rules above (including a required **scope**).

**Setup (once per clone):**

```bash
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:

```bash
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.7.0/pml.xsd](https://jabrena.github.io/pml/schemas/0.7.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