Skip to content

AGENTS.md

Latest commit

 

History

History
42 lines (33 loc) · 3.22 KB

AGENTS.md

File metadata and controls

42 lines (33 loc) · 3.22 KB
Raw

AGENTS.md

This is a StartOS service-package repository — it builds a .s9pk for StartOS.

Develop it inside a StartOS packaging workspace created by start-cli s9pk init-workspace, which provides the packaging guide and agent context one level up. If you're reading this in a bare clone with no workspace, the full guide is at https://docs.start9.com/packaging.

Start every task at the recipe index — ../start-technologies/projects/start-sdk/docs/src/recipes.md (or https://docs.start9.com/packaging/recipes.html). It maps an intent ("prompt the user to create admin credentials", "expose a web UI") to the constructs, the reference pages, and a named production package to copy. Find the recipe before you read this package's neighbours: a package you reach by grepping may be non-conformant, and the recipe outranks it.

Freshly scaffolded? Work the New Package Checklist (or https://docs.start9.com/packaging/new-package-checklist.html) from top to bottom. It is a guide page, not a file in this repo — read it, don't copy it in.

Keep README.md (technical reference for an AI support or administering agent) and instructions.md (end-user docs) in sync with your changes. This file restates neither: whoever changes the package has both, so it carries only what they don't — repo mechanics, a change that looks right and is not, where the next thing gets added, a naming trap, a build or test invocation particular to this repo.

Fix a defect you spot rather than reporting it — you have the package open and the context to be sure. File a GitHub issue on this repo only when the call isn't yours to make: you can't pin the cause down, two defensible fixes exist, or it's too large to ride on the work in hand. An open issue is a report, not a queue — implement one when you're asked to or when it's labelled Approved, then close it with Closes #<n>.

Don't record work in the repo instead: no TODO.md, no NOTES.md, no PLAN.md. What you verified, tried, and decided belongs in the commit message and the PR body.

This repo

  • Keep guardUpstreamUpgrade ahead of versionGraph in setupInit, because a volume StartOS could not snapshot keeps whatever data version the graph advanced to.
  • When renaming an action that has a live task, call sdk.action.clearTask(effects, '<old key>') in the same release: the old replay key no longer resolves, so nothing else ever removes the task.
  • Give a new queued occ task matching entries in ACTION_IDS, OCC_ARGS and TASK_NOTICE, plus a conditional health check, or it is never run or reported.
  • Edit startos/fileModels/php.pegjs and run npm run regen-parser; never edit php-parser.js by hand. The build does not read the grammar, so a skipped regeneration still builds and ships the old parser.
  • Add an external-storage source as an entry in startos/externalStorage.ts, a typed mountDependency in main.ts and a dependency in startos/dependencies.ts: the action and the reconcile pick up everything else from that registry.
  • Re-read /entrypoint.sh when bumping the image: install and upgrade progress phases key off its log lines, and a reworded line fails nothing.