chore: add project guidance and agent workflows
This commit is contained in:
tothbt committed
1 parent
349662a055
commit
326575e55d
14 files changed
+963
-6
No files matched your search
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: angular-feature
|
||||
description: Implement or modify Angular and Ionic features in Court Pilot while following its standalone-component, Dexie service, signal, localization, styling, and testing conventions. Use for changes to pages, routes, services, settings, and user-facing web or desktop UI behavior.
|
||||
---
|
||||
|
||||
# Angular Feature Workflow
|
||||
|
||||
Use this workflow for Angular/Ionic feature work in Court Pilot.
|
||||
|
||||
## 1. Establish the behavior
|
||||
|
||||
1. Read `AGENTS.md`.
|
||||
2. Identify the affected route in `src/app/app.routes.ts` or `src/app/tabs/tabs.routes.ts`.
|
||||
3. Read the page component, template, SCSS, related services, and adjacent specs.
|
||||
4. Check `docs/domain-glossary.md` before changing rotation or assignment behavior.
|
||||
5. Ask the maintainer rather than inventing a rule when a domain question remains unresolved.
|
||||
|
||||
## 2. Choose the correct layer
|
||||
|
||||
- Keep rendering and user interaction in the page/component.
|
||||
- Keep table access and reusable persistence operations in `src/app/services/`.
|
||||
- Use Angular signals for reactive state and `computed()` for derived state.
|
||||
- Follow existing `liveQuery()` plus `toSignal()` patterns for reactive Dexie queries.
|
||||
- If one operation writes multiple tables, consider a Dexie transaction so failure cannot leave a partial move.
|
||||
- Treat `db.ts` changes as schema work. Add a new schema version for released-data changes; never rewrite an existing released schema in place.
|
||||
|
||||
## 3. Follow UI conventions
|
||||
|
||||
- Use standalone components.
|
||||
- Import Ionic controls from `@ionic/angular/standalone` and list them in component `imports`.
|
||||
- Use `inject()` for dependencies.
|
||||
- Register new Ionicons with `addIcons()`.
|
||||
- Keep page HTML and SCSS beside the page TypeScript file.
|
||||
- Format touched files with the root `.prettierrc`; do not reformat unrelated files or apply personal overrides.
|
||||
- Preserve strict typing; do not use `any` to bypass domain modeling.
|
||||
|
||||
## 4. Localize user-facing text
|
||||
|
||||
1. Add a typed key to both `en` and `hu` in `src/app/i18n/translations.ts`.
|
||||
2. Keep interpolation placeholders identical in both languages.
|
||||
3. Use `TranslatePipe` in templates.
|
||||
4. Use `TranslationService` for alerts and TypeScript-created messages.
|
||||
5. If the Hungarian translation is unknown, ask for it instead of inventing production copy.
|
||||
|
||||
## 5. Protect platform behavior
|
||||
|
||||
- Guard Tauri-only APIs with `isTauri()` when browser execution is possible.
|
||||
- Remember that Linux updates are handled by Snap, while Windows and macOS use the Tauri updater.
|
||||
- Do not assume Capacitor targets are active until their intended support is confirmed.
|
||||
|
||||
## 6. Add validation
|
||||
|
||||
- Add or update adjacent `*.spec.ts` coverage for changed behavior.
|
||||
- Prefer behavior assertions over creation-only tests.
|
||||
- Run the narrowest relevant test first when supported by the current Karma setup.
|
||||
- Run `npm run lint`.
|
||||
- Run `npm run build`.
|
||||
- Report every command actually run and any validation that was unavailable.
|
||||
|
||||
## Completion checklist
|
||||
|
||||
- [ ] The implementation follows an existing page/service pattern.
|
||||
- [ ] Domain invariants remain intact.
|
||||
- [ ] New user-facing text exists in English and Hungarian.
|
||||
- [ ] Persistence changes have an explicit migration strategy.
|
||||
- [ ] Relevant tests were updated.
|
||||
- [ ] Lint and build results were reported.
|
||||
- [ ] Documentation was updated if behavior or architecture changed.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: database-change
|
||||
description: Modify Court Pilot's Dexie entities, indexes, or persisted data safely with a new schema version, explicit migration behavior, domain-invariant protection, tests, and documentation. Use whenever a task changes db.ts or the shape or meaning of stored records.
|
||||
---
|
||||
|
||||
# Database Change Workflow
|
||||
|
||||
Use this skill for any change to persisted Court Pilot data.
|
||||
|
||||
## Establish the migration
|
||||
|
||||
1. Read `AGENTS.md`, `docs/architecture.md`, and `docs/domain-glossary.md`.
|
||||
2. Read `db.ts` and every service that reads or writes the affected tables.
|
||||
3. Determine whether the change affects existing released records.
|
||||
4. Define the old shape, new shape, defaults, invalid-data handling, and rollback limitations before editing.
|
||||
5. Ask the maintainer if the migration depends on an undefined domain rule.
|
||||
|
||||
## Version the schema safely
|
||||
|
||||
- Never modify an existing released `db.version(...)` declaration in place.
|
||||
- Add the next integer schema version.
|
||||
- Declare the complete store schema required by that version.
|
||||
- Use an explicit Dexie upgrade callback when records need transformation.
|
||||
- Keep migration logic deterministic and safe to run once per database upgrade.
|
||||
- Do not delete user data unless the task explicitly requires and documents it.
|
||||
|
||||
## Preserve domain invariants
|
||||
|
||||
After migration, every court official must be in exactly one operational state:
|
||||
|
||||
- not on duty
|
||||
- waiting as umpire
|
||||
- waiting as service judge
|
||||
- assigned as umpire
|
||||
- assigned as service judge
|
||||
|
||||
Preserve FIFO queue ordering. Normalize order values if the migration can create gaps or conflicts. Removing assignments because courts no longer exist must leave those officials not on duty unless the requested behavior says otherwise.
|
||||
|
||||
Use a Dexie transaction for multi-table changes that must succeed or fail together.
|
||||
|
||||
## Update all affected layers
|
||||
|
||||
- Update TypeScript entity interfaces and table declarations.
|
||||
- Update services rather than moving raw database access into pages.
|
||||
- Update computed UI state and templates when the new data affects presentation.
|
||||
- Update both English and Hungarian translations for new user-facing concepts.
|
||||
- Document the new schema version and migration behavior in `docs/architecture.md`.
|
||||
|
||||
## Validate
|
||||
|
||||
- Add migration coverage using a database created at the previous version when practical.
|
||||
- Add tests for changed service behavior and domain invariants.
|
||||
- Run `npm run lint`.
|
||||
- Run `npm run build`.
|
||||
- Run the relevant non-watching tests.
|
||||
- Report the old and new schema versions and all commands actually run.
|
||||
@@ -0,0 +1,136 @@
|
||||
---
|
||||
name: prepare-release
|
||||
description: Prepare a Court Pilot desktop release by recommending a semantic version from commits or code changes, letting the developer confirm or override it, synchronizing all version locations, validating builds, and reviewing Windows, macOS, CrabNebula, and Linux Snap publication. Use whenever a developer asks to prepare or version a release.
|
||||
---
|
||||
|
||||
# Prepare Release
|
||||
|
||||
Use this skill only when the user explicitly asks to prepare a release. A release-preparation request authorizes creating the local release tag after the developer confirms the version and the synchronized version changes are committed and validated. It does not authorize creating a commit, pushing the tag, or publishing unless the developer explicitly requests those actions.
|
||||
|
||||
## Recommend the version
|
||||
|
||||
Do not change version files immediately. First determine the latest reachable release tag and the current application version, then review all changes since that tag.
|
||||
|
||||
Use Conventional Commits when the commit history is clear:
|
||||
|
||||
- `type!:` or a `BREAKING CHANGE:` footer → major bump
|
||||
- `feat:` or `feat(scope):` → minor bump
|
||||
- `fix:` or `perf:` → patch bump
|
||||
- `docs:`, `test:`, `refactor:`, `build:`, `ci:`, `chore:`, and style-only changes do not require a release bump by themselves unless they alter shipped behavior or packaging
|
||||
|
||||
The highest required bump wins. For example, a range containing both `fix:` and `feat:` recommends a minor bump.
|
||||
|
||||
This repository contains commits that do not always follow Conventional Commits. If commit messages are missing, inconsistent, or ambiguous:
|
||||
|
||||
1. Inspect the diff and changed files from the latest release tag through `HEAD`.
|
||||
2. Inspect relevant implementation and configuration—not only the diff summary—to determine shipped behavior.
|
||||
3. Treat incompatible user data, behavior, configuration, or supported-platform changes as major.
|
||||
4. Treat backward-compatible functionality as minor.
|
||||
5. Treat backward-compatible corrections, performance improvements, packaging fixes, or security fixes as patch.
|
||||
6. Mention unreleased working-tree changes separately; do not silently base a release solely on uncommitted work.
|
||||
|
||||
If there is no prior tag, inspect the complete relevant history and ask whether the release should establish the chosen initial version.
|
||||
|
||||
Present the developer with:
|
||||
|
||||
- current application version
|
||||
- latest release tag
|
||||
- relevant commits or code changes
|
||||
- recommended version
|
||||
- recommended bump type and concise reasoning
|
||||
|
||||
Then explicitly ask the developer to either accept the recommendation or enter a different version. Do not edit versions until they answer.
|
||||
|
||||
Validate the selected value as Semantic Versioning. It should normally be greater than both the current released version and latest release tag. Warn and request confirmation for a lower, equal, or prerelease version.
|
||||
|
||||
Release tags use the selected value prefixed with `v`, such as `v1.2.0`.
|
||||
|
||||
## Synchronize the confirmed version manually
|
||||
|
||||
After the developer accepts the recommendation or supplies a manual version, set that exact version in:
|
||||
|
||||
1. `package.json`
|
||||
2. The root package entries in `package-lock.json`
|
||||
3. `src-tauri/tauri.conf.json`
|
||||
4. `src-tauri/Cargo.toml`
|
||||
5. The `court-pilot` entry in `src-tauri/Cargo.lock`, normally refreshed by Cargo
|
||||
6. `snap/snapcraft.yaml`
|
||||
7. The version displayed in `src/app/tab3/tab3.page.html`
|
||||
|
||||
Do not introduce a release-version script unless the user requests automation.
|
||||
|
||||
After editing `Cargo.toml`, run `cargo check` from `src-tauri/` and confirm Cargo refreshed its lockfile metadata.
|
||||
|
||||
## Review release configuration
|
||||
|
||||
- Confirm the tag version matches all files.
|
||||
- Confirm the Tauri updater endpoint and public key are intentional.
|
||||
- Confirm Linux still skips the in-app updater because Snap manages updates.
|
||||
- Confirm `.github/workflows/release.yml` still builds Windows, both macOS architectures, and Linux Snap.
|
||||
- Do not expose or print signing, CrabNebula, or Snap Store secrets.
|
||||
- Note that platform packages cannot all be validated on one development host.
|
||||
|
||||
## Validate
|
||||
|
||||
Activate the required Node.js version, then run the checks in order. Keep `nvm use lts/jod` in the same shell session as the npm commands:
|
||||
|
||||
```sh
|
||||
nvm use lts/jod
|
||||
npm ci
|
||||
npm test -- --configuration=ci
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
From `src-tauri/`, run:
|
||||
|
||||
```sh
|
||||
cargo check
|
||||
```
|
||||
|
||||
Run a local Tauri build only when the host has the required native dependencies. Report platforms that were not built locally.
|
||||
|
||||
## Create the release tag
|
||||
|
||||
Do not tag uncommitted version changes: a tag points to a commit, not to the working tree. After validation:
|
||||
|
||||
1. Verify all synchronized version files are included in `HEAD` and the tracked working tree is clean. If they are not committed, ask the developer to commit them or explicitly authorize the agent to create the release commit.
|
||||
2. Verify that `v<version>` does not already exist locally.
|
||||
3. Create a lightweight tag, matching this repository's existing release-tag style:
|
||||
|
||||
```sh
|
||||
GIT_EDITOR=true git tag v<version>
|
||||
```
|
||||
|
||||
For version `1.2.0`, run exactly:
|
||||
|
||||
```sh
|
||||
GIT_EDITOR=true git tag v1.2.0
|
||||
```
|
||||
|
||||
4. Verify that the tag resolves to the intended release commit.
|
||||
5. Report the created local tag.
|
||||
|
||||
Do not push automatically. Explain that pushing the tag triggers `.github/workflows/release.yml`, then ask for explicit permission before running:
|
||||
|
||||
```sh
|
||||
git push origin v<version>
|
||||
```
|
||||
|
||||
Never move, overwrite, or force-push an existing release tag without explicit maintainer instructions.
|
||||
|
||||
## Completion report
|
||||
|
||||
Report:
|
||||
|
||||
- latest release tag and current version used for comparison
|
||||
- recommended bump and reasoning
|
||||
- version selected by the developer
|
||||
- files whose versions were synchronized
|
||||
- test, lint, Angular build, and Cargo results
|
||||
- platform builds not run locally
|
||||
- local release tag created and its target commit
|
||||
- whether the tag remains local or was explicitly pushed
|
||||
- any workflow or updater concerns
|
||||
|
||||
Stop before committing, pushing, or publishing unless the user explicitly asks for those actions.
|
||||
Reference in new issue
Block a user