From 8bb6fbc1a1cad4f554ef5e14b04f95d88212add4 Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Wed, 27 May 2026 15:42:39 +0800 Subject: [PATCH] chore: add AI agent groundwork --- .github/ISSUE_TEMPLATE/bug.yml | 85 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 10 +++ .github/ISSUE_TEMPLATE/feature.yml | 73 ++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 60 +++++++++++++ AGENTS.md | 136 +++++++++++++++++++++++++++++ 5 files changed, 364 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 AGENTS.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..48cb0aa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,85 @@ +name: Bug Report +description: Report a reproducible bug for this repository. +title: "[Bug]: " +labels: + - type:bug + +body: + - type: textarea + id: summary + attributes: + label: Summary + description: Describe the bug clearly. + validations: + required: true + + - type: textarea + id: current_behavior + attributes: + label: Current Behavior + description: What is happening now? + validations: + required: true + + - type: textarea + id: expected_behavior + attributes: + label: Expected Behavior + description: What should happen instead? + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: Provide exact reproduction steps. + placeholder: | + 1. + 2. + 3. + validations: + required: true + + - type: textarea + id: affected_area + attributes: + label: Affected Area + description: Mention routes, components, models, APIs, commands, or workflows affected. + validations: + required: false + + - type: textarea + id: proposed_fix + attributes: + label: Proposed Fix + description: Optional implementation direction. + validations: + required: false + + - type: textarea + id: acceptance_criteria + attributes: + label: Acceptance Criteria + description: Define what must be true for this bug to be fixed. + placeholder: | + - [ ] + - [ ] + validations: + required: true + + - type: textarea + id: docs_impact + attributes: + label: Documentation Impact + description: Does this require updates to fleetbase/fleetbase.io? + validations: + required: false + + - type: textarea + id: api_impact + attributes: + label: API Reference Impact + description: Does this require updates to fleetbase/postman? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..918cf4a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,10 @@ +blank_issues_enabled: true + +contact_links: + - name: Fleetbase Documentation + url: https://fleetbase.io/docs + about: Read Fleetbase documentation. + + - name: Fleetbase Website + url: https://fleetbase.io + about: Visit the Fleetbase website. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..da6d01f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,73 @@ +name: Feature Request +description: Request a new feature or enhancement. +title: "[Feature]: " +labels: + - type:feature + +body: + - type: textarea + id: summary + attributes: + label: Summary + description: Describe the feature clearly. + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem / Use Case + description: What problem does this solve? + validations: + required: true + + - type: textarea + id: proposed_solution + attributes: + label: Proposed Solution + description: Describe the desired implementation or behavior. + validations: + required: false + + - type: textarea + id: affected_area + attributes: + label: Affected Area + description: Mention routes, components, models, APIs, commands, or workflows affected. + validations: + required: false + + - type: textarea + id: acceptance_criteria + attributes: + label: Acceptance Criteria + description: Define what must be true for this feature to be complete. + placeholder: | + - [ ] + - [ ] + validations: + required: true + + - type: textarea + id: implementation_notes + attributes: + label: Implementation Notes + description: Optional technical direction for agents or maintainers. + validations: + required: false + + - type: textarea + id: docs_impact + attributes: + label: Documentation Impact + description: Does this require updates to fleetbase/fleetbase.io? + validations: + required: false + + - type: textarea + id: api_impact + attributes: + label: API Reference Impact + description: Does this require updates to fleetbase/postman? + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..eb04b55 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,60 @@ +## Summary + +Describe what changed and why. + +## Related Issue + +Closes # + +## Type of Change + +- [ ] Bug fix +- [ ] Feature +- [ ] Refactor +- [ ] Documentation +- [ ] Test +- [ ] Chore + +## Implementation Notes + +Explain the important implementation details. + +## Validation + +List commands run: + +- [ ] Tests +- [ ] Lint +- [ ] Build +- [ ] Manual validation + +Command output / summary: + +```txt +``` + +## Documentation Impact + +- [ ] No documentation changes needed +- [ ] Documentation updated in `fleetbase/fleetbase.io` +- [ ] Documentation needed but not included + +## API Reference Impact + +- [ ] No API reference changes needed +- [ ] Updated `fleetbase/postman` +- [ ] API reference updates required but not included + +API reference notes: + +## Documentation Notes + +Describe documentation or API specification updates. + +## Risk + +Describe possible risks, migrations, compatibility issues, or rollout concerns. + +## Screenshots / Recordings + +Add screenshots or recordings for UI changes. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cc20743 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,136 @@ +# AI Agent Instructions + +## Repository Scope + +Fleetbase Postman and OpenAPI specification source for API collections, workflow examples, environments, and API reference generation. + +## Allowed Work + +- Updates to Postman/OpenAPI YAML collections, examples, workflow requests, and API documentation source files. +- Lint fixes, collection organization, and examples that preserve real API behavior. +- Spec updates that correspond to verified API behavior changes in Fleetbase modules. + +## Restricted Work + +- Committing real tokens, cookies, IDs, exported Vault data, or production credentials. +- Inventing API behavior not backed by implementation or approved design. +- Changing generated public documentation without coordinating required `fleetbase/fleetbase.io` regeneration or PRs. + +## Global Agent Rules + +- Do not merge pull requests. +- Do not publish packages. +- Do not rotate, expose, modify, or invent secrets. +- Do not change production credentials or deployment configuration unless explicitly requested. +- Do not perform large rewrites unless explicitly requested. +- Prefer small, reviewable changes. +- Preserve existing architecture and conventions. +- Follow the repository's existing naming, formatting, and test patterns. +- Add or update tests where practical. +- If tests are not added, explain why in the PR. +- Run available lint/test/build commands before finalizing the PR. +- Include command output or a clear summary of validation performed. +- If the issue is ambiguous, comment with questions instead of guessing. + +## Local Setup + +- `npm install` + +## Test Commands + +- Lint collections: `npm run postman:lint` +- Run collections: `npm run postman:run` +- Run scoped collections with scripts such as `npm run postman:run:fleetbase`, `npm run postman:run:core`, `npm run postman:run:storefront`, or `npm run postman:run:ledger` + +## Pull Request Rules + +- Work on a dedicated branch for each task. +- Keep changes small and reviewable. +- Stage only files related to the task. +- Do not include unrelated local changes in commits. +- Use clear PR titles and descriptions that explain what changed and why. +- Link the related issue when one exists. +- Include validation commands and a concise summary of results. +- Explain any skipped tests, missing coverage, or known follow-up work. +- Call out documentation and API reference impact using the PR template. +- Do not merge the PR after opening it. + +## Documentation Rules + +Some changes require documentation updates in `fleetbase/fleetbase.io`. + +Some API-related changes additionally require updates to API specification files in `fleetbase/postman`. + +Update or create documentation when a change affects: + +- user-facing behavior +- configuration +- installation steps +- environment variables +- API behavior +- request/response schemas +- authentication behavior +- extension behavior +- permissions or IAM behavior +- billing, invoicing, wallets, or gateway behavior +- developer workflows +- CLI commands +- mobile app workflows +- onboarding flows +- breaking changes +- deprecated behavior + +If API behavior changes, the agent must determine whether corresponding specification updates are needed in `fleetbase/postman`. + +Examples include: + +- new endpoints +- modified endpoints +- payload changes +- validation changes +- authentication changes +- response schema changes +- enum changes +- new query parameters +- deprecated API behavior + +If API specification files are updated in `fleetbase/postman`, the agent should also determine whether a documentation PR or regeneration step is required in `fleetbase/fleetbase.io`. + +If documentation should be updated but cannot be updated in the same PR, the agent must: + +1. mention this clearly in the PR description; +2. add a `needs-docs` label if available; +3. reference the expected documentation area in `fleetbase/fleetbase.io`; +4. reference any required specification updates in `fleetbase/postman`. + +## Escalation Rules + +Stop and request human clarification when: + +- the requested behavior is ambiguous or conflicts with existing architecture; +- the change would alter public APIs, authentication, permissions, billing, financial records, or production configuration; +- secrets, credentials, signing assets, deployment settings, or release automation are involved; +- the safest implementation requires a large rewrite or broad cross-repository coordination; +- tests fail for reasons that are not clearly related to the change; +- documentation or API specification ownership is unclear. + +## Recommended Labels + +Use these labels when they are available: + +- `type:bug` +- `type:feature` +- `type:docs` +- `type:refactor` +- `type:chore` +- `agent:ready` +- `agent:blocked` +- `agent:in-progress` +- `needs-docs` +- `needs-api-spec` +- `needs-human-review` +- `needs-product-decision` +- `priority:p0` +- `priority:p1` +- `priority:p2` +- `priority:p3`