From 95795bed4d6dba96aec1bd4b8d3dcb7d01e0a885 Mon Sep 17 00:00:00 2001 From: Wilkin Santana <28665914+wilkinsantana@users.noreply.github.com> Date: Fri, 6 Nov 2026 19:10:06 -0500 Subject: [PATCH] Add coding-agent documentation and shared project instructions Signed-off-by: Wilkin Santana <28665914+wilkinsantana@users.noreply.github.com> --- AGENTS.md | 74 ++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 3 ++ CONTRIBUTING.md | 3 ++ README.md | 7 ++++ content/agents.html | 51 ++++++++++++++++++++++++++ content/overview.html | 1 + docs.go | 3 +- tests/browser/site.spec.js | 2 +- 8 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 content/agents.html diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ffb5fa1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# Working on TendUI-web + +This repository is the Go website at https://tendui.com. It consumes the TendUI +library; it is not the library source. Read relevant code and tests before editing, +preserve unrelated work, and follow [CONTRIBUTING.md](CONTRIBUTING.md). + +## Structure + +- `main.go` wires the HTTP server, embedded assets and mounted library demos. +- `docs.go` registers guides, navigation and the sitemap. Guide bodies live in + `content/*.html` as Go HTML templates with a `body` definition. +- `docs.templ` renders the documentation shell. `site_header.templ` is shared by + home, docs, catalog and demos; preserve that single header and theme behavior. +- `static/` contains website CSS and brand assets. Preserve content-hashed asset + URLs, favicon coverage, canonical URLs and existing cache/security headers. +- `library-version.json`, `go.mod`, `go.sum` and `vendor/` record one exact library + dependency. Do not hand-edit vendor or ship local module replacements. +- Library changes belong in `Tend-Stack/TendUI`. To update an authorized dependency + from a clean library checkout, use `python3 tools/vendor-library.py /path/to/TendUI` + and commit all resulting metadata and vendor changes together. + +## Product rules + +- Use TendUI components and semantic HTML. Keep the public site usable without + JavaScript; do not add frontend build tools, remote fonts or runtime downloads. +- The browser test suite may use Node/npm; building and serving the site need Go + only. Read `go.mod` for Go and templ versions. +- Use the installed library API, not guessed props or examples from a newer tag. + Keep installation instructions pinned and accurate; do not silently upgrade. +- Preserve native forms/links, focus, labels, theme cookies, reduced motion and + narrow-screen layouts. Keep the shared header and 1920px maximum consistent. +- Demos are bounded examples, not production account creation or persistence. + Do not weaken origin validation or cookie protections to make a demo pass. +- Keep public documentation free of private infrastructure, credentials and local + workstation paths. Retain asset provenance and license notices. + +## Commands and validation + +Run from the repository root: + +```sh +go run . # local server; PORT defaults to 8080 +go test -race ./... +go vet ./... +``` + +For template edits, use the generator matching `go.mod`, run `templ fmt .` and +`templ generate`, and commit `.templ` and `_templ.go` together. Never hand-edit +generated output. Normal builds use the committed output and vendored modules. + +For new guides, update `docs.go` and its navigation labels together; the sitemap +uses the guide registry. Add the route to the existing browser guide audit in +`tests/browser/site.spec.js`. HTTP tests already exercise each registered guide. +Check links and code samples, mobile containment and keyboard navigation. + +Use focused checks while editing and CI for full verification. Follow +[CONTRIBUTING.md](CONTRIBUTING.md) for browser tooling. Store task artifacts under +ignored `tests/results/`; remove only owned disposable output and keep concise +failure evidence. Do not create duplicate environments or discard unrelated work. + +## Delivery + +- Submit focused PRs to GitHub `Tend-Stack/TendUI-web` main. MIT + DCO applies; + human contributors review and authorize their own sign-offs. Never fabricate + someone else's identity, certification or test results. +- A push to main can trigger Tend deployment. Publish only within the user's + authorized scope, preserve active work and existing data, and verify CI and + deployment separately. Do not add deployment credentials to this repository. +- Settings in `.github/settings/` are prepared configurations, not proof that + GitHub rules or a Project are active. +- Verify changed routes through the public domain after an authorized deployment; + check actual served content, not only a successful build status. +- Report what changed, tests actually run, live verification when applicable, + and remaining limitations. Do not claim a deployed result from a local test. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..23e6c36 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Shared project instructions + +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94c484f..ebab27f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,9 @@ For your own last commit, use `git commit --amend --signoff`; coordinate with reviewers before rewriting an already-pushed contribution branch. Maintainers do not add missing contributor certifications on someone else's behalf. +Coding agents should read [AGENTS.md](AGENTS.md) for repository structure and +validation guidance; `CLAUDE.md` imports that same file. + AI-assisted contributions follow exactly the same rules: a human contributor must understand, review and test the result and certify the right to submit it. Identify significant generated material or reused sources in the PR description. diff --git a/README.md b/README.md index e281427..ac1cdce 100644 --- a/README.md +++ b/README.md @@ -105,3 +105,10 @@ sets a longer browser cache lifetime. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, review and MIT + DCO sign-off. Report vulnerabilities privately using [SECURITY.md](SECURITY.md); community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). + +## Coding agents + +Repository contributors should read [AGENTS.md](AGENTS.md); `CLAUDE.md` imports +the same instructions for Claude Code. For applications using TendUI, see +[the coding-agent guide](https://tendui.com/docs/agents) and merge its suggested +section into your own project instructions. diff --git a/content/agents.html b/content/agents.html new file mode 100644 index 0000000..66f72d0 --- /dev/null +++ b/content/agents.html @@ -0,0 +1,51 @@ +{{define "body"}} +

Give your agent the right starting point.

+

TendUI works with coding agents just as it does with people: use the installed API, semantic HTML and your application's existing stack. Tell the agent whether you use plain HTML, Go's html/template, or Go with templ. HTMX is optional.

+
Using TendUI or contributing to it?

The instructions below are for your own application. To change the library or this website, use the repository instructions linked at the end of this page.

+

1. Add context to your project

+

Merge this section into AGENTS.md in your application root. Preserve your existing instructions and adapt the validation commands to your project. Installing a Go dependency does not install project instructions into your app.

+
## TendUI in this application
+
+- Read go.mod (or the pinned CSS source) to identify the installed TendUI version.
+  Do not upgrade it or guess component props/classes to complete a task.
+- Prefer semantic HTML and native browser controls. Do not add Node/npm, a CSS
+  build step, or client JavaScript solely to use TendUI.
+- With Go, import github.com/Tend-Stack/TendUI/v2026 as package tendui.
+  Mount tendui.AssetHandler() at tendui.AssetPath without StripPrefix and link
+  tendui.StylesheetURL. CSS is embedded and ships inside the executable.
+- With templ, use typed components from the /components package. Inspect the
+  installed API before writing props. Edit .templ files, regenerate with the
+  generator matching the application's templ dependency, and commit generated Go.
+- For plain HTML or html/template, serve the pinned stylesheet as a local asset;
+  keep existing escaping and server-side rendering. templ is optional.
+- Applications own routes, validation, authentication, CSRF protection, sessions
+  and persistence. Never copy demo handlers as production security logic.
+- HTMX attributes alone do not execute requests. Add the optional runtime only
+  when requested; keep native form/link fallbacks and correct fragment responses.
+- Use documented --tendui-* tokens and data-theme="light" or "dark"; omit the
+  theme attribute for system preference. Preserve labels, focus, keyboard access,
+  responsive layout, error messages and reduced-motion behavior.
+- Run the application's relevant tests and build. Check the page and stylesheet
+  routes and the requested user flow; report checks performed and limitations.
+

Start from the Go and templ quickstart or HTML and CSS guide. Use the catalog to find a pattern, then check the source and props at your installed version; online examples may describe a newer release.

+

2. Connect your coding tool

+

Codex

+

Codex reads project AGENTS.md files. Keep the shared instructions in your project root and follow the official instruction-discovery guide for directory scope and overrides.

+

Claude Code

+

Add this import to a neighboring CLAUDE.md, preserving existing content. Put the import on its own line outside a code fence in the actual file:

+
@AGENTS.md
+

The documented import mechanism lets you maintain one shared policy, including in sessions that do not load AGENTS.md directly.

+

Other tools

+

Select this file in the tool's project-context settings or ask it explicitly to read it. Automatic discovery varies. Start a fresh session after setup and ask the agent to summarize the applicable instructions and installed TendUI version before editing.

+

Instruction files guide behavior. Tests, human review and tool permissions still matter; the files do not enforce permissions or guarantee correctness.

+

3. Give it a concrete task

+

Read our project instructions and installed TendUI API. Add a labeled settings form using our existing stack and server routes. Preserve native submission, light/dark themes and keyboard behavior. Show the changed files, run relevant tests, and explain anything you could not verify. Do not add dependencies.

+

Review the result in the browser, including keyboard focus, narrow screens and error states. Verify that the stylesheet loads and native interactions work with JavaScript disabled. If you intentionally enable HTMX, test both enhanced and ordinary requests.

+

Contributing to TendUI itself

+ +

Both repositories include a CLAUDE.md import of their own AGENTS.md. AI-assisted contributions follow MIT + DCO contribution rules: a human reviews, tests and authorizes their own sign-off.

+{{end}} diff --git a/content/overview.html b/content/overview.html index c9856e9..42cd051 100644 --- a/content/overview.html +++ b/content/overview.html @@ -10,5 +10,6 @@

What your application supplies

Three packages

Production package responsibilities
Import suffixResponsibility
tendui (module root)Embedded stylesheet and asset handler.
/componentsTyped templ components and appearance settings.
/renderFull-page and fragment HTTP responses.

The asset and render helpers use the Go standard library. Components depend on templ. Generated Go is included, so consuming the library does not require its generator; authoring your own templ pages does.

+

Working with a coding agent

Give Codex, Claude Code or another assistant project instructions for TendUI, including the installed API, native behavior and validation steps.

Explore by doing

Use the playground to test states and appearance, the application examples to see complete flows, and the component reference to take a recipe into your own app.

{{end}} diff --git a/docs.go b/docs.go index d068048..0fc7852 100644 --- a/docs.go +++ b/docs.go @@ -20,6 +20,7 @@ var guides = []guide{ {"/docs", "Build something thoughtful.", "A practical guide to semantic interfaces with Go, templ, and optional HTMX.", "overview"}, {"/docs/install", "From module to interface.", "Install TendUI, serve its embedded CSS, and render your first page.", "install"}, {"/docs/html", "Start with HTML. Add your stack.", "Use TendUI with two static files and no build tools.", "html"}, + {"/docs/agents", "Build with a coding agent.", "Give Codex, Claude Code and other tools practical TendUI project instructions.", "agents"}, {"/docs/theming", "Make it feel like yours.", "Choose a color mode, compose appearance settings, or override the tokens.", "theming"}, {"/docs/forms", "Forms that work with the browser.", "Native submission first. Validation and persistence belong to your application.", "forms"}, {"/docs/htmx", "Enhance a working page.", "Use optional HTMX attributes with explicit full-page and fragment responses.", "htmx"}, @@ -37,7 +38,7 @@ func registerDocs(mux *http.ServeMux) { } var buf bytes.Buffer navigation := make([]components.NavItem, 0, len(guides)+1) - labels := []string{"Introduction", "Installation", "HTML & CSS", "Appearance", "Forms & validation", "HTMX", "Accessibility", "Deployment", "Examples"} + labels := []string{"Introduction", "Installation", "HTML & CSS", "Coding agents", "Appearance", "Forms & validation", "HTMX", "Accessibility", "Deployment", "Examples"} for i, entry := range guides { navigation = append(navigation, components.NavItem{Label: labels[i], Href: entry.Path, Current: entry.Path == g.Path}) } diff --git a/tests/browser/site.spec.js b/tests/browser/site.spec.js index 6ca510c..defb286 100644 --- a/tests/browser/site.spec.js +++ b/tests/browser/site.spec.js @@ -12,7 +12,7 @@ async function siteNavigation(page) { test('guides, examples, and homepage remain accessible and contained', async ({ page }, testInfo) => { test.setTimeout(180000); - for (const route of ['/', '/docs', '/docs/install', '/docs/html', '/docs/theming', '/docs/forms', '/docs/htmx', '/docs/accessibility', '/docs/deploy', '/examples']) { + for (const route of ['/', '/docs', '/docs/install', '/docs/html', '/docs/agents', '/docs/theming', '/docs/forms', '/docs/htmx', '/docs/accessibility', '/docs/deploy', '/examples']) { const response = await page.goto(route); expect(response.status()).toBe(200); await expect(page.locator('main')).toHaveCount(1);