diff --git a/AGENTS.md b/AGENTS.md index 47f66e6b..ec7e3f68 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,7 @@ When you change or add any of the following, please update this file to reflect - scripts/* (collector, build scripts, live-serve helpers) - rollup.config.js or rollup-plugins/ - docs/ content, co-located examples, or test collection logic +- skills/* (installable AI skill specifications) - .github/workflows/* (CI / Pages deployment) For convenience, include this exact sentence in the PR description when you want the assistant to update AGENTS.md automatically: @@ -360,6 +361,20 @@ When you discover a new pattern, fix a bug caused by an undocumented constraint, 3. **Correct inaccurate entries** whenever you verify that something documented is wrong. 4. You do not need a special PR description sentence to update `AGENTS/` files — just do it as part of your normal work. +## Agent Skills Directory (`skills/`) + +The `skills/` directory contains installable skill specifications that can be +copied into AI tools (opencode and similar) to enforce SmarkForm-specific +implementation behavior. + +| File | Purpose | +|------|---------| +| `skills/SmarkForm-Form-Builder.skill.md` | Core skill for implementing SmarkForm forms with required rules and a mandatory compliance checklist | +| `skills/SmarkForm-Advanced-Internals.skill.md` | Optional advanced skill for internals-heavy work (action semantics, list/context edge cases, security-sensitive patterns) | + +Maintenance rule: +- When `docs/_resources/AGENTS/SmarkForm-Forms.md` or `docs/_resources/AGENTS/SmarkForm-Usage.md` changes, review and update both skill files in `skills/` if affected; when in doubt, update both in the same PR so installable skills stay aligned with canonical docs. + - **Contributing**: See `CONTRIBUTING.md` - **Documentation**: [https://smarkform.bitifet.net](https://smarkform.bitifet.net) diff --git a/docs/_resources/ai-agents.md b/docs/_resources/ai-agents.md index 3a0c447d..eeeb5846 100644 --- a/docs/_resources/ai-agents.md +++ b/docs/_resources/ai-agents.md @@ -17,11 +17,16 @@ nav_order: 6 * [Agent Knowledge Files](#agent-knowledge-files) * [How to Use These Files When Prompting an AI](#how-to-use-these-files-when-prompting-an-ai) - * [Quick Reference Prompts](#quick-reference-prompts) + * [Quick Reference Prompts](#quick-reference-prompts) +* [Installable Skills](#installable-skills) + * [Core Skill (recommended)](#core-skill-recommended) + * [Optional Advanced Skill](#optional-advanced-skill) + * [Import into opencode or similar tools](#import-into-opencode-or-similar-tools) +* [Maintenance Rules for Skill Files](#maintenance-rules-for-skill-files) * [Prompt Templates](#prompt-templates) - * [Simple form](#simple-form) - * [Form with a repeating list](#form-with-a-repeating-list) - * [Adding SmarkForm to an existing page](#adding-smarkform-to-an-existing-page) + * [Simple form](#simple-form) + * [Form with a repeating list](#form-with-a-repeating-list) + * [Adding SmarkForm to an existing page](#adding-smarkform-to-an-existing-page) " | markdownify }} @@ -62,6 +67,54 @@ Load SmarkForm from CDN (pin to the latest stable version). --- +## Installable Skills + +The repository includes installable skill specs so AI tools can enforce +SmarkForm-specific implementation rules. + +### Core Skill (recommended) + +- `skills/SmarkForm-Form-Builder.skill.md` + +Use this for general SmarkForm form implementation. It enforces: +- source-priority lookups (deployed docs first) +- event/action-first implementation patterns +- required `await myForm.rendered` timing +- list/context/template rules +- root-level security option rules +- mandatory “SmarkForm compliance checklist” in outputs + +### Optional Advanced Skill + +- `skills/SmarkForm-Advanced-Internals.skill.md` + +Use this when handling advanced internals and edge cases. + +### Import into opencode or similar tools + +1. Open the desired skill file from `skills/`. +2. Copy its full content into your tool's skill/instruction definition. +3. Keep the source-priority section unchanged so the agent always prefers: + - `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Forms` + - `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage` +4. If your tool supports separate skills, install: + - core skill as default + - advanced skill as opt-in + +--- + +## Maintenance Rules for Skill Files + +- When `docs/_resources/AGENTS/SmarkForm-Forms.md` or `docs/_resources/AGENTS/SmarkForm-Usage.md` changes, review and update both `skills/SmarkForm-Form-Builder.skill.md` and `skills/SmarkForm-Advanced-Internals.skill.md` if affected; when in doubt, update both in the same PR. +- Apply the same update rule when their deployed equivalents change: + `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Forms` and + `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage`. +- Keep the source-priority order intact so deployed docs remain the primary + knowledge source for agents. +- If behavioral rules change, update both the skill file(s) and this page. + +--- + ## Prompt Templates The following ready-to-use prompts are reproduced from the diff --git a/skills/SmarkForm-Advanced-Internals.skill.md b/skills/SmarkForm-Advanced-Internals.skill.md new file mode 100644 index 00000000..7365c165 --- /dev/null +++ b/skills/SmarkForm-Advanced-Internals.skill.md @@ -0,0 +1,38 @@ +# SmarkForm Advanced Internals — Optional Skill Spec + +## Goal + +Handle advanced SmarkForm internals safely (complex list semantics, action decorator nuances, context/target path edge-cases, and security-related options). + +## Scope + +Use this optional skill for: +- Nested list/template edge cases +- Programmatic action invocation nuances +- Complex `context` / `target` path behavior +- Mixin/security-option-sensitive implementations + +For standard form implementation, use: +- `skills/SmarkForm-Form-Builder.skill.md` + +## Source Priority + +Use the exact source-priority order defined in: +- `skills/SmarkForm-Form-Builder.skill.md` + +Additionally, for internals-first tasks, start by reading: +- https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage + +## Non-negotiable Internals Rules + +- Respect `@action` calling conventions (including argument position semantics). +- Respect action context resolution and target resolution semantics. +- Respect list template role lifecycle and cloning behavior. +- Apply security-related options at root-level constructor options. + +## Output Requirement + +Provide a short “advanced compliance check” confirming: +- source pages consulted +- internals rules applied +- unresolved ambiguity (if any) diff --git a/skills/SmarkForm-Form-Builder.skill.md b/skills/SmarkForm-Form-Builder.skill.md new file mode 100644 index 00000000..4d8a034c --- /dev/null +++ b/skills/SmarkForm-Form-Builder.skill.md @@ -0,0 +1,86 @@ +# SmarkForm Form Builder — Installable Skill Spec + +## Goal + +Generate production-ready SmarkForm forms that follow current SmarkForm patterns and avoid common implementation mistakes. + +## Source Priority (mandatory) + +When implementing or modifying forms, consult sources in this order: + +1. **Primary (always first):** + - https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Forms + - https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage +2. **Fallback (repo source of canonical pages):** + - `docs/_resources/AGENTS/SmarkForm-Forms.md` + - `docs/_resources/AGENTS/SmarkForm-Usage.md` +3. **Last fallback (repo pointers):** + - `AGENTS/SmarkForm-Forms.md` + - `AGENTS/SmarkForm-Usage.md` + +If sources disagree, prefer the highest-priority source. + +## Required Rules (hard requirements) + +1. **Event/action integration** + - Use SmarkForm actions and SmarkForm events (`BeforeAction_*` / `AfterAction_*`) for form workflows. + - Do not replace SmarkForm action flows with arbitrary ad-hoc DOM listeners on managed form controls. +2. **Render timing** + - Always wait for `await myForm.rendered` before any `find()` usage or component-tree-dependent logic. +3. **List/template/context semantics** + - Follow list template role rules (`item`, `empty_list`, `header`, `footer`, etc.). + - Respect context/target resolution semantics for triggers. + - For controls inside cloned item templates that target sub-lists, use safe placement patterns documented in SmarkForm Usage. +4. **Security/root options** + - Security-sensitive options must be configured on the root SmarkForm constructor options (not via nested `data-smark` inheritance tricks). + - Keep secure defaults unless explicit requirement justifies opt-in. +5. **Naming convention in examples** + - Use `myForm` as the SmarkForm instance variable in generated JS examples. + +## Standard Implementation Workflow + +1. Read primary source pages. +2. Draft HTML with `data-smark` attributes on all managed fields. +3. Initialize with: + - `const myForm = new SmarkForm(document.getElementById("myForm"), options);` + - `await myForm.rendered;` +4. Wire behavior through SmarkForm actions/events. +5. Validate against the compliance checklist below. + +## Output Contract + +Every response that delivers SmarkForm code must include: + +1. The implementation. +2. A **SmarkForm compliance checklist** section showing pass/fail for each item. + +If any checklist item fails, the skill must treat output as incomplete and revise +it before finalizing. If revision is not possible, add a clear warning header +(`SmarkForm compliance incomplete`) and explicitly report unmet items and why. + +## SmarkForm Compliance Checklist (mandatory) + +Template below is intentionally unchecked in this skill spec. In generated +outputs, agents must replace it with explicit pass/fail marks per item. + +When generating output, evaluate each item and report explicit pass/fail status. +Replace template markers with: +- `[x]` for pass +- `[ ]` for fail +Do not leave this section as an untouched unchecked template. + +- [ ] Managed fields include `data-smark`. +- [ ] Root element is passed to `new SmarkForm(...)` correctly. +- [ ] Uses `myForm` variable naming convention. +- [ ] `await myForm.rendered` before `find()` and component-dependent logic. +- [ ] Uses SmarkForm actions/events for form workflows (`BeforeAction_*` / `AfterAction_*`) where applicable. +- [ ] List template roles and placement rules are respected. +- [ ] `context` / `target` paths follow SmarkForm rules. +- [ ] No conflicting dual defaults (`value=""` plus JSON `"value"` on same element). +- [ ] Security-sensitive options are set at root constructor options when needed. +- [ ] Production CDN examples use explicit version numbers (for example `@0.16.0`) and do not use `@latest`. + +## Distribution Notes + +- This file is the canonical core skill artifact in-repo. +- For external tools (opencode, similar), adapt this spec to tool-specific front matter/format without changing behavioral rules.