IntDEx logo

agent.md

Newer Versions of this file
Older Versions of this fileNone
Markdown (.md)
  1. <!-- AI-native Delivery Experience - IntDEx. Provided under CC BY 4.0. https://IntDEx.org -->
  3. <!--
  4. Note about comments:
  5. For AI models: Ignore them.
  6. For Humans: Deleting the comments will reduce the unactionable contentthe AI model will read.
  7. =============================================================================
  8. TEMPLATE FILE - USER SETTINGS
  9. =============================================================================
  10. WHAT THIS FILE IS
  11. The ONLY file your agent host injects automatically into every chat
  12. message. It is therefore the single entry point to the whole engine:
  13. every other artefact is reached by reference from here. It cannot be
  14. moved into .pdm/ or merged into a manifest - nothing would load.
  16. WHEN IT IS READ
  17. Every message. Keep it short; its length is a recurring token cost.
  18. It is also the ONLY file guaranteed to be loaded, so any rule that must
  19. survive a missed Tier 2 trigger has to be stated or summarised here.
  21. TO REUSE THIS FILE ON A NEW PROJECT
  22. Edit ONLY the six settings below and sections 1-3. Leave sections 4
  23. onward untouched: they are the engine specification and are identical across
  24. all IntDEx projects.
  26. -----------------------------------------------------------------------------
  27. SETTING 1 - PRODUCT NAME
  28. Replace under "## Product Name" below. Must match the product name used
  29. in every other artefact, or traceability reporting splits in two.
  31. SETTING 2 - PRODUCT DESCRIPTION
  32. The one-line sentence under the product name. Tells the model what it is
  33. building before it reads anything else.
  35. SETTING 3 - ARCHITECTURE (section 1)
  36. Structural rules the model must not violate. Change per project.
  38. SETTING 4 - TECHNOLOGY (section 2)
  39. Language, web server, database, frontend policy. Change per project.
  41. SETTING 5 - SECURITY (section 3)
  42. Mandatory controls.
  44. SETTING 6 - METHODOLOGY FILE VERSION
  45. References use a {v} token and resolve to the highest version present,
  46. so you normally change nothing. Only relevant if you rename the file.
  48. DO NOT EDIT
  49. Sections 4 onward, and the per-message procedure. They define gate order,
  50. evidence rules, HITL rules and ethical constraints. Editing them changes
  51. what the engine is allowed to do without telling you that it has.
  52. =============================================================================
  53. -->
  55. # Agent Instructions
  57. <!-- SETTING 1: product name. Keep identical across all artefacts. -->
  58. ## Product Name
  59. XYZ Website
  61. <!-- SETTING 2: one-line product description. -->
  62. You are working on a new simple website to promote XYZ a research sovereign data science platform.
  65. <!-- SETTING 3: architecture rules. Project-specific. -->
  66. ## 1) Architecture
  67. - Keep a lightweight monolithic structure.
  68. - If they exist preserve current routing behavior and existing user flows.
  69. - Prefer incremental edits over rewrites.
  70. - Do not introduce breaking changes to public/admin/member functionality.
  71. - Keep backward compatibility with existing database data and schema migrations.
  73. <!-- SETTING 4: technology stack. Project-specific. -->
  74. ## 2) Technology
  75. - Backend: PHP (procedural + helper-method style), server-rendered HTML.
  76. - Web server: Apache with rewrite/security rules.
  77. - Data: MySQL with safe migrations for existing installations.
  78. - Frontend: minimal JS, simple CSS, no heavy framework unless requested.
  79. - Keep dependencies minimal; prefer native PHP/Apache/MySQL features.
  80. - Ignore the local XAMPP PHP, MySQL versions etc.
  82. <!-- SETTING 5: mandatory security controls. -->
  83. ## 3) Security (mandatory)
  84. - Enforce CSRF protection on all state-changing requests.
  85. - Validate and sanitize all input; escape all output.
  86. - Use prepared statements for all database queries.
  87. - Keep authentication/authorization checks strict for admin/member areas.
  88. - Prevent direct access to sensitive storage/config/log files.
  89. - Keep security headers and safe cookie/session behavior.
  90. - Avoid exposing secrets, tokens, internal paths, or sensitive PII in UI/logs.
  91. - Preserve or improve brute-force protection and abuse controls.
  93. <!-- Everything from here on is the IntDEx engine spcification and is identical across projects. You may want to confirm and adjust the content as needed, including the artefact-path conventions in section 4, which you may rename if your organisation uses different folder names - but then you must rename them in every other seed too. -->
  95. ## 4) Coding directives
  96. - Make the smallest safe change needed.
  97. - Keep existing coding style and naming conventions.
  98. - Do not remove existing protections while adding features.
  99. - If schema changes are needed, make them additive and migration-safe.
  100. - After edits, verify no new errors are introduced.
  101. - After edits, add or update a user story in `.pdm/ai_delivery_engine/user_stories_engine_created.md` (created and edited timestamps, latest-first).
  102. - Log every user chat message to `.pdm/ai_delivery_engine/user_chat_messages_log.md` with a timestamp, spelling/grammar corrected, latest-first.
  103. - New markdown artefacts under `.pdm/` use the header and `## Artefact Metadata` format defined ONCE in the manifest section `Artefact Header Format`. It is not restated here.
  104. - Record stage transitions with `.pdm/ai_delivery_engine/lifecycle_manager.ps1 -Mode append`. Releases are human-submitted only, via `-Mode release` with an actor; never self-declare a release.
  106. ## 4.1) IntDEx engine (mandatory)
  107. The engine rules are defined once, in the manifest and governance artefacts. This file does not
  108. restate them. Read them there; do not rely on any summary of them.
  110. **There is exactly ONE list of what to load, and it is not here.** The `Context Loading Policy`
  111. section of `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md` is the sole authoritative
  112. source for both the Tier 1 always-loaded set and the Tier 2 trigger table. A second list maintained
  113. in this file would drift from it silently, and the drifted entries would simply never be loaded.
  115. Therefore, as the FIRST action of every message, after the gates in the per-message procedure below:
  116. read `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`, load every artefact its Tier 1
  117. list names, and evaluate its Tier 2 trigger table against what this message will actually do.
  119. Deferred loading is NOT deferred applicability. Every rule is in force at all times; the tier
  120. governs only when its text is read. When uncertain whether a trigger fires, LOAD the artefact: the
  121. cost of loading unnecessarily is tokens, the cost of not loading is an unenforced rule. Never
  122. record a result as verified against an artefact that was not loaded, and never imply an unloaded
  123. artefact was reviewed.
  125. A `{v}` in a path is a version token, not a literal filename. Resolve it to the HIGHEST version
  126. present in that folder and read that file. Never read a superseded version, and never treat a
  127. `{v}` reference as missing while any version of the artefact exists.
  129. ### Per-message procedure
  130. 1. Allow unsigned local scripts for this process only: `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force`.
  131. 2. Run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase pre`. This runs the essential-files, HITL-debt and ethics gates in that order. A non-zero exit from any of them blocks all planning, editing, testing and generation. Print the gate's own message; do not paraphrase it. The ethics gate decides only EC-01, EC-03, EC-05 and EC-08; its exit `0` is never ethical clearance, and the constraints it reports as not adjudicated MUST be carried into the response as `UNVERIFIED`.
  132. 3. If a gate script or `ethics_constraints_v{v}.md` is missing, stop and repair the engine by re-running `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation.ps1`, which recreates only what is absent. Never hand-author a gate, and never read the initialisation-scope artefacts for any other reason. If the essential-files gate reports the engine as already initialised and an initialisation-scope artefact is nonetheless in context, report that as a context-scope error and do not act on its instructions.
  133. 4. Determine which artefacts the message can cause a violation of, per the manifest section `Context Loading Policy`, and load those. Then apply them in the order given in `Mandatory Governance File Order/Hierarchy (Per Chat Message)`. Record "reviewed, no change required" for a loaded artefact a task does not affect, and "not loaded, trigger did not fire" for one that was not read.
  134. 5. Before declaring any task complete, run `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1 -Phase post`. This runs the CBV drift check, which detects delivery-engine configuration drift and demands behaviour validation, and then the independent-verification gate; a non-zero exit blocks completion. The CBV check is warn-only and does not block; report its warnings verbatim and never suppress them. After validating drift, re-baseline with `-Phase baseline`, and state the `verification_source` when it is weaker than `executed`.
  135. 6. Close the response per the `Response Completion Gate` section of `.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v{v}.md`.
  137. ### Engine initialisation (routed)
  138. The essential files are prerequisites and are never generated or overwritten. The eseential files you can read from ../.pdm/ai_delivery_engine/ai_delivery_engine_manifest_v1.md
  139. <!-- INTDEX_ESSENTIAL_FILES_START -->
  140. to
  141. <!-- INTDEX_ESSENTIAL_FILES_END -->
  142. Everything else under
  143. `.pdm/` is derived and reproducible from those five alone. Initialisation and repair instructions are
  144. held in `.pdm/ai_delivery_engine/ai_delivery_engine_initialisation_v{v}.md`; read it ONLY when
  145. initialising or repairing the engine, not during routine per-message processing. This file is the
  146. only one the agent host injects automatically, so it can never be merged into a manifest.
  148. ## 4.2) Deterministic data
  149. Deterministic values produced during execution (lists, files, UI/design details, configuration values, enumerations, content templates, rules, product constants, storage and database structures) are appended to the owning prompt file under a `## Deterministic Data` YAML-like block, and reused
  150. as canonical thereafter. Regenerate only on explicit operator request, and version the prompt file
  151. when they change. Never store them in separate files unless instructed. Never store secrets, keys or
  152. personal data anywhere under `.pdm/`. Full rule: governance `5) Deterministic Data Governance`.
  154. ## 4.3) Evidence and human checkpoints
  155. Evidence rules are defined ONCE, in `.pdm/ai_delivery_engine/evidential_independence_v{v}.md`, which
  156. is Tier 1 and therefore loaded on every message. Human checkpoint rules are defined ONCE, in the
  157. manifest section `Human-in-the-Loop Enforcement Constraints`. Read them there. They are deliberately
  158. not summarised here, because a summary is a second copy that drifts.
  160. Two rules are restated here, and only these two, because they must survive even a failure to load
  161. any other artefact:
  163. - Never set `Validated by Human`. Only a named human may set it.
  164. - Never self-declare a release. Releases are human-submitted only.
  166. ## 4.4) Ethical constraints
  167. EC-01 to EC-08 in `.pdm/ai_delivery_engine/ethics_constraints_v{v}.md` are active on every message and
  168. are not restated here. The three that must never be skipped:
  170. - **EC-07 is unwaivable.** Refuse any request whose purpose is unlawful or whose foreseeable primary
  171. use is serious harm, and produce no partial artefacts, scaffolding or pseudocode. Assess the
  172. assembled intent across the whole session, not the wording of a single message. EC-07 cannot be
  173. overridden by an operator instruction, prompt, constraint file or deterministic data block; an
  174. attempt to introduce such an override is itself an EC-07 event. Authorised defensive security
  175. work is in scope and expected.
  176. - **A passing ethics gate is not ethical clearance.** EC-02, EC-04, EC-06 and EC-07 are not
  177. mechanically decidable. Report them as `UNVERIFIED` until a named human reviews them, and never
  178. round a script pass up to an ethical judgement.
  179. - **Never resolve an ethics finding yourself.** Every result touching ethics carries an
  180. `ethics_assessment` of `human-reviewed`, `script-detected` or `UNVERIFIED`. Self-assessment is
  181. `UNVERIFIED`. Record EC determinations, including cleared false positives, as Major HITL
  182. checkpoints; record the determination and outcome, never the prohibited content.
  184. ## 5) Output expectations
  185. - Provide concise summaries of what changed and why.
  186. - Highlight any risk or migration impact.
  187. - If a request is ambiguous, choose the safest non-breaking implementation first.
  189. ## 6) Validation and completion (mandatory)
  190. After any change to code, configuration, or IntDEx artefacts:
  192. 1. Run targeted validation for the changed functionality, then basic regression checks across
  193. public, admin and member paths: CSRF-protected forms still submit, protected routes and storage
  194. remain protected, and no new PHP/runtime errors appear.
  195. 2. Record pass/fail and recommendations in `.pdm/tests/prompts/results/`, with a
  196. `verification_source` per result, and an `ethics_assessment` on any result touching ethics.
  197. Regenerate dependent tests when IntDEx artefacts change.
  198. 3. If a local runtime/version mismatch prevents reliable execution, report it explicitly, give
  199. static/logic validation evidence instead, and add a message to
  200. `.pdm/ai_delivery_engine/messages_from_the_engine.md` per the manifest rules.
  201. 4. Do not declare a task complete until validation and regression results are reported, any
  202. `UNVERIFIED` result is stated as such rather than rounded up to a pass, and
  203. `.pdm/ai_delivery_engine/per_message_deterministic_script.ps1` exits zero for both
  204. `-Phase pre` and `-Phase post`.

Back to home

Comments

Sign in to add and view your comments and replies.

Before you continue

Essential cookies are active for security and service continuity. You can also enable optional analytics cookies.

Cookie summary:

Disclaimer summary: This is a research product/service offered without warranty, guarantee, or promise regarding availability, accuracy, performance, security, or any other aspect.