From a4ad2ad10a510e69107c4f8f53c4b71f0e3ac965 Mon Sep 17 00:00:00 2001 From: Labyricorn Date: Tue, 11 Aug 2026 22:48:09 -0700 Subject: [PATCH] Add scoped Labyricorn authoring guidance --- .labyricorn/AGENTS.md | 63 +++++++++++++++++++++++++++++++++++ .labyricorn/devlog/AGENTS.md | 54 ++++++++++++++++++++++++++++++ .labyricorn/project/AGENTS.md | 43 ++++++++++++++++++++++++ 3 files changed, 160 insertions(+) create mode 100644 .labyricorn/AGENTS.md create mode 100644 .labyricorn/devlog/AGENTS.md create mode 100644 .labyricorn/project/AGENTS.md diff --git a/.labyricorn/AGENTS.md b/.labyricorn/AGENTS.md new file mode 100644 index 0000000..f82856f --- /dev/null +++ b/.labyricorn/AGENTS.md @@ -0,0 +1,63 @@ +# Instructions for Labyricorn publishing content + +These instructions apply to the entire `.labyricorn/` directory. More specific +instructions in `project/AGENTS.md` and `devlog/AGENTS.md` also apply within +those directories. + +## Purpose and ownership + +- This directory is the repository-owned source for Thinkloom's exhibition page + and development log on Labyricorn. +- The Thinkloom repository is authoritative for this content. The Labyricorn + site imports it as read-only content. +- Read `.labyricorn/README.md` and the nearest scoped `AGENTS.md` before editing + a publishing record. +- Keep publishing changes focused. Do not alter application code merely to + support an exhibition or devlog edit unless the user separately requests it. + +## Authorization and communication + +- When the user says **discussion only**, do not edit files, run mutating + commands, commit, push, request synchronization, or change external systems. +- An implementation request authorizes only its clearly stated scope. Ask + before changing project identity, content structure, schema, publication + status, or synchronization behavior. +- Do not commit or push unless the user explicitly requests it. +- Before pushing, explain that the pushed publishing content may be imported + into the public Labyricorn site. +- Preserve unrelated and uncommitted work. Never discard changes to obtain a + clean worktree. + +## Content contract + +- Use native Lektor records named `contents.lr`. +- Preserve `schema_version: 1` until a coordinated schema migration is approved + in both the project and Labyricorn site repositories. +- Do not add templates, models, plugins, workflows, executable files, generated + builds, or application state below `.labyricorn/`. +- Keep attachments inside the record subtree that owns them. +- Use UTF-8 text, `YYYY-MM-DD` dates, and stable lowercase hyphenated slugs. +- Do not use raw HTML, scripts, embedded credentials, or active third-party + content in Markdown fields. +- Treat published URLs as durable. Ask before renaming or removing a published + record; redirects or archival behavior may be required first. + +## Security and synchronization + +- Never store or print passwords, API tokens, refresh credentials, private keys, + `.netrc` contents, or other secrets in this directory. +- Never place a refresh credential in a URL, query string, tracked script, or + command example. +- Do not claim that content is public merely because a push succeeded. Report + push status and synchronization/publication status separately. +- When an authenticated refresh mechanism is implemented and documented, use + only its approved wrapper command and request at most one refresh for a pushed + commit. Until then, do not invent or bypass a trigger mechanism. + +## Validation and handoff + +- Parse every changed `contents.lr` file with Lektor's native record parser. +- Confirm required fields are present and referenced source commits exist. +- Run `git diff --check` and review the exact diff before committing. +- At handoff, report changed publishing records, validation performed, commit + and push status, and synchronization status if known. diff --git a/.labyricorn/devlog/AGENTS.md b/.labyricorn/devlog/AGENTS.md new file mode 100644 index 0000000..c5b7117 --- /dev/null +++ b/.labyricorn/devlog/AGENTS.md @@ -0,0 +1,54 @@ +# Instructions for the Thinkloom development log + +These instructions supplement `.labyricorn/AGENTS.md` and apply to the +`devlog/` directory. + +## Index and entry structure + +- Keep the devlog index at `devlog/contents.lr` using `_model: devlog`. +- Store each published entry at `devlog//contents.lr` using + `_model: devlog-entry`. +- Use a lowercase hyphenated directory name that describes the milestone. The + directory name becomes part of the public URL and must remain stable. +- Every entry must include `schema_version`, `title`, `date`, `author`, + `summary`, `tags`, `source_commit`, and `body`. +- Set `source_commit` to the full 40-character commit ID most directly + associated with the entry. Confirm that it resolves in this repository. +- Use the commit's actual calendar date for retrospective entries. Do not use + the date on which the devlog prose was written. + +## Editorial guidance + +- Base retrospective entries on verifiable repository history, existing project + documents, and implemented behavior. +- Do not invent motivations, conversations, results, release status, user + feedback, or completion claims. +- A devlog should explain the milestone, why it mattered, and what changed. It + should not merely expand a commit message or enumerate every changed file. +- Distinguish a design or schema contract from a completed runtime + implementation. +- Keep one main milestone per entry. Link to the relevant canonical commit using + the Gitea HTTPS URL. +- Write summaries that work in chronological listings without requiring the + reader to open the entry. +- Use focused tags consistently; avoid creating capitalization or spelling + variants of an existing tag without a reason. + +## Chronology and lifecycle + +- The Labyricorn site orders entries by `date` and provides links back to the + project and to older/newer entries. Do not add manual next/previous links. +- Multiple entries may share a date; ordering ties should be resolved by the + importer from source history rather than invented timestamps in prose. +- Do not rewrite old entries merely because the implementation later changed. + Add a new entry or a clearly labelled correction when historical context is + needed. +- Do not delete or rename a published entry without explicit approval and a + redirect or archival decision for its existing URL. + +## Review requirements + +- Verify the entry date and `source_commit` against `git log`. +- Check that the source-commit link targets the same full commit ID. +- Check prose against the referenced commit and current documentation. +- Parse the record with Lektor and run `git diff --check` before committing. diff --git a/.labyricorn/project/AGENTS.md b/.labyricorn/project/AGENTS.md new file mode 100644 index 0000000..8817789 --- /dev/null +++ b/.labyricorn/project/AGENTS.md @@ -0,0 +1,43 @@ +# Instructions for the Thinkloom exhibition record + +These instructions supplement `.labyricorn/AGENTS.md` and apply to the +`project/` directory. + +## Record structure + +- Maintain exactly one project record at `project/contents.lr` using + `_model: project`. +- Keep `project_id: thinkloom` stable. It is the durable identity used by the + Labyricorn importer and public URL. +- Keep the repository URL pointed at the canonical Thinkloom source repository. + Ask before changing the repository, default branch, project status, author, + or start date. +- Store project-owned visual attachments in this directory and reference them + by filename from `contents.lr`. +- Use descriptive, web-appropriate alternative text whenever the content schema + introduces images that require it. + +## Editorial guidance + +- Write the exhibition page as a concise project narrative, not as a copy of + `README.md` and not as release documentation. +- Verify technical and status claims against the current repository before + editing them. +- Distinguish completed work, formal design work, experimental work, and future + work. Do not imply implementation or conformance that the repository does not + support. +- Preserve Thinkloom's established product boundaries: native, local-first, + user-controlled, preview-first model assistance, and no hosted browser + companion unless the project itself explicitly changes those boundaries. +- Do not manually add latest-commit, README, license, language, release, issue, + or other repository-derived metadata to the body. The Labyricorn importer and + repository information card own those values. +- Keep the summary suitable for project listings and social previews. Keep the + body useful to visitors who want to understand the project rather than build + it. + +## Review requirements + +- Check that `logo` and other attachment references resolve within `project/`. +- Check that Markdown links are intentional and use HTTPS. +- Re-read the rendered prose for unsupported claims before committing.