Template
Initialize Labyricorn project publishing records, assistant instructions, and devlog editor
This commit is contained in:
+23
@@ -0,0 +1,23 @@
|
||||
# Byte-compiled / optimized / DLL files
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*.class
|
||||
|
||||
# Environments
|
||||
.venv/
|
||||
env/
|
||||
venv/
|
||||
ENV/
|
||||
|
||||
# Caches and builds
|
||||
.cache/
|
||||
build/
|
||||
dist/
|
||||
|
||||
# Operating system files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Temporary and editor files
|
||||
*.swp
|
||||
*~
|
||||
@@ -0,0 +1,42 @@
|
||||
# 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 the project's exhibition
|
||||
page and development log on Labyricorn.
|
||||
- This project repository is authoritative for the 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 content contract
|
||||
|
||||
- Preserve unrelated and uncommitted work. Never discard changes to obtain a
|
||||
clean working tree.
|
||||
- Do not commit or push unless the user explicitly requests publication.
|
||||
- Use native Lektor records named `contents.lr` and preserve `schema_version: 1`
|
||||
until a coordinated schema migration is approved.
|
||||
- Keep attachments inside the record subtree that owns them.
|
||||
- Use UTF-8 text, `YYYY-MM-DD` dates, and stable lowercase hyphenated slugs.
|
||||
- Do not add templates, models, plugins, workflows, executable files, builds,
|
||||
application state, credentials, raw HTML, scripts, or active third-party
|
||||
content below `.labyricorn/`.
|
||||
- Treat published URLs as durable. Ask before renaming or removing a published
|
||||
record; redirects or archival behavior may be required first.
|
||||
|
||||
## Security, synchronization, and review
|
||||
|
||||
- Never store or print passwords, API tokens, refresh credentials, private keys,
|
||||
`.netrc` contents, or other secrets in this directory.
|
||||
- Do not claim content is public merely because a push succeeded. Report push
|
||||
status and Labyricorn synchronization status separately.
|
||||
- Parse changed records, confirm referenced source commits exist, run
|
||||
`git diff --check`, and review the exact publishing diff before committing.
|
||||
- At handoff, report changed publishing records, validation performed, commit
|
||||
and push status, and synchronization status if known.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Labyricorn publishing content
|
||||
|
||||
This directory is the repository-owned source for this project's exhibition
|
||||
and development log on Labyricorn. The project repository remains the source
|
||||
of truth; the Labyricorn site imports this content as read-only.
|
||||
|
||||
The content uses native Lektor records:
|
||||
|
||||
```text
|
||||
.labyricorn/
|
||||
├── AGENTS.md
|
||||
├── README.md
|
||||
├── project/
|
||||
│ ├── AGENTS.md
|
||||
│ ├── contents.lr
|
||||
│ └── <optional image>
|
||||
└── devlog/
|
||||
├── AGENTS.md
|
||||
├── contents.lr
|
||||
└── <entry-slug>/
|
||||
├── contents.lr
|
||||
└── <optional images>
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `project/contents.lr` uses the `project` model.
|
||||
- `devlog/contents.lr` uses the `devlog` model.
|
||||
- Each entry is a directory below `devlog/` containing a `contents.lr` record
|
||||
using the `devlog-entry` model.
|
||||
- Entry directory names are stable public slugs. Do not rename a published entry
|
||||
without arranging a redirect on the Labyricorn site.
|
||||
- Dates use `YYYY-MM-DD`; `source_commit` uses the full relevant commit ID.
|
||||
- Publishing attachments stay inside the record subtree that owns them.
|
||||
- Do not put credentials, builds, application state, or executable code here.
|
||||
|
||||
Editing these records does not itself prove that the public site synchronized.
|
||||
Report repository publication and Labyricorn synchronization separately.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Instructions for the Labyricorn development log
|
||||
|
||||
These instructions apply to `.labyricorn/devlog/` and help coding assistants
|
||||
maintain the project's public development narrative safely.
|
||||
|
||||
## Format and ownership
|
||||
|
||||
- Keep the devlog index at `devlog/contents.lr` using `_model: devlog` and
|
||||
`schema_version: 1`.
|
||||
- Store each entry at `devlog/<stable-slug>/contents.lr` using
|
||||
`_model: devlog-entry` and `schema_version: 1`.
|
||||
- Use lowercase hyphenated entry slugs. Published slugs are durable public URLs;
|
||||
do not rename or delete them without explicit approval and a redirect or
|
||||
archival decision.
|
||||
- Every entry must contain `title`, `date`, `author`, `summary`, `tags`,
|
||||
`source_commit`, and Markdown `body` fields.
|
||||
- Keep entry attachments in that entry's directory. Only PNG, JPEG, and WebP
|
||||
images are accepted by the Labyricorn importer.
|
||||
- Do not add templates, models, plugins, executable code, builds, application
|
||||
state, credentials, or active third-party content below this directory.
|
||||
|
||||
## Content guidance
|
||||
|
||||
- Base entries on verifiable repository history, project documentation, and
|
||||
implemented behavior. Do not invent motivations, results, release status,
|
||||
user feedback, or completion claims.
|
||||
- Explain the milestone, why it mattered, and what changed. Keep one main
|
||||
milestone per entry and write a summary that works in a chronological list.
|
||||
Do not merely expand a commit message or enumerate every changed file.
|
||||
- Distinguish design and schema contracts from completed runtime behavior.
|
||||
- Link to the relevant canonical commit using the repository's HTTPS web URL.
|
||||
- Use the referenced commit's actual `YYYY-MM-DD` calendar date for retrospective
|
||||
entries, not the date on which the prose was drafted.
|
||||
- Set `source_commit` to the full lowercase 40-character commit ID most directly
|
||||
associated with the milestone. It must be an ancestor of the published branch.
|
||||
- Topics are comma-separated display labels. Unknown topics are allowed: the
|
||||
site keeps them visible but unlinked. Do not create or edit the site's tracked
|
||||
tag registry from this project repository.
|
||||
- Use Markdown without raw HTML, scripts, embedded credentials, or active
|
||||
external content.
|
||||
- Multiple entries may share a date. The site resolves ties from source history;
|
||||
do not invent timestamps or manual next/previous links.
|
||||
- Do not rewrite older entries merely because the implementation later changed.
|
||||
Add a new entry or a clearly labelled correction when historical context is
|
||||
needed.
|
||||
|
||||
## Safety and review
|
||||
|
||||
- Preserve unrelated project files and uncommitted work. The devlog owns only
|
||||
`.labyricorn/devlog/`.
|
||||
- Do not commit or push unless the user explicitly requests publication.
|
||||
- Before publication, verify claims against the referenced commit, validate all
|
||||
records, check that the source-commit link uses the same full commit ID, review
|
||||
the exact devlog diff, and confirm unrelated files are not staged in the
|
||||
publishing commit.
|
||||
- Prefer the repository-root `devlog_editor.py` for routine validation and safe
|
||||
publication when it is available.
|
||||
@@ -0,0 +1,7 @@
|
||||
_model: devlog
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
title: Labyricorn Project Template development log
|
||||
---
|
||||
summary: Milestones and development log entries for the Labyricorn project template.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Instructions for the Labyricorn project 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` and `schema_version: 1`.
|
||||
- Keep `project_id` stable. It is the durable identity used by the importer and
|
||||
public URL.
|
||||
- Ask before changing the repository URL, default branch, project status,
|
||||
author, start date, or project identity.
|
||||
- Store project-owned images in this directory and reference them by filename
|
||||
from `contents.lr`. Only PNG, JPEG, and WebP images are accepted.
|
||||
|
||||
## Editorial guidance
|
||||
|
||||
- Write the exhibition page as a concise project narrative, not as a copy of
|
||||
the repository README or as release documentation.
|
||||
- Verify technical and status claims against the repository before editing.
|
||||
- Distinguish completed work, formal design work, experiments, and future work.
|
||||
- Do not manually add repository-derived commit, license, language, release,
|
||||
issue, star, or fork metadata. The Labyricorn importer owns those values.
|
||||
- Keep the summary suitable for listings and social previews.
|
||||
|
||||
## Review requirements
|
||||
|
||||
- Confirm all required project fields are present and any image reference stays
|
||||
inside `project/`.
|
||||
- Check Markdown links are intentional HTTPS links and prose makes no unsupported
|
||||
claims.
|
||||
- Validate the record and run `git diff --check` before committing.
|
||||
@@ -0,0 +1,27 @@
|
||||
_model: project
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
project_id: labyricorn-project-template
|
||||
---
|
||||
title: Labyricorn Project Template
|
||||
---
|
||||
summary:
|
||||
|
||||
Initial template and publishing structure for Labyricorn-compatible projects and development logs.
|
||||
---
|
||||
status: active
|
||||
---
|
||||
started: 2026-08-23
|
||||
---
|
||||
author: Labyricorn
|
||||
---
|
||||
repository_url: https://git.labyricorn.com/Labyricorn/labyricorn-project-template
|
||||
---
|
||||
default_branch: main
|
||||
---
|
||||
tags: template, lektor, python
|
||||
---
|
||||
body:
|
||||
|
||||
Starter template providing the standard .labyricorn/ publishing records, assistant instructions, devlog structure, and repository tooling for publication on Labyricorn.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Instructions for coding assistants
|
||||
|
||||
These instructions apply to this repository. Read `README.md` and the relevant
|
||||
scoped `AGENTS.md` files before making changes.
|
||||
|
||||
## Communication and authorization
|
||||
|
||||
- Do not assume the user's desired behavior, architecture, or content structure
|
||||
when the answer would materially affect the result.
|
||||
- When the user requests discussion or review, do not edit files, run mutating
|
||||
commands, commit, or push.
|
||||
- An implementation request authorizes work only within its clearly stated
|
||||
scope. Routine steps within that scope may proceed, but confirm before
|
||||
expanding scope or making irreversible choices.
|
||||
- Before implementation, state the intended files and systems to be changed.
|
||||
- Do not commit or push unless the user explicitly requests it.
|
||||
- Preserve unrelated edits and uncommitted work. Never discard changes merely
|
||||
to obtain a clean working tree.
|
||||
|
||||
## Project and publishing boundaries
|
||||
|
||||
- Application and project source code lives at the repository root and normal
|
||||
subdirectories.
|
||||
- The `.labyricorn/` directory is the repository-owned source for project
|
||||
exhibition records and development logs published on Labyricorn.
|
||||
- Keep publishing records in `.labyricorn/` aligned with actual repository
|
||||
implementation and history.
|
||||
- Read `.labyricorn/AGENTS.md`, `.labyricorn/project/AGENTS.md`, and
|
||||
`.labyricorn/devlog/AGENTS.md` when modifying publishing records.
|
||||
|
||||
## Content contract and devlog practices
|
||||
|
||||
- Use native Lektor records named `contents.lr` with `schema_version: 1`.
|
||||
- Keep attachments inside the record subtree that owns them (PNG, JPEG, WebP).
|
||||
- Do not introduce raw HTML, scripts, executable files, builds, or credentials
|
||||
below `.labyricorn/`.
|
||||
- For devlog entries, base records on verifiable repository commits and history.
|
||||
Set `source_commit` to the full 40-character commit ID on the branch.
|
||||
- Devlog dates should reflect the commit's calendar date (`YYYY-MM-DD`).
|
||||
|
||||
## Validation and review
|
||||
|
||||
- Run `python devlog_editor.py --validate` to verify that `.labyricorn/` records,
|
||||
project identity, devlog index, and devlog entries adhere to the schema.
|
||||
- Alternatively, launch the graphical editor with `python devlog_editor.py` for
|
||||
interactive management of devlog entries and publishing status.
|
||||
- Run `git diff --check` and review diffs carefully before staging or committing.
|
||||
- At handoff, summarize files changed, validation performed, and any next steps.
|
||||
@@ -1,7 +1,213 @@
|
||||
# labyricorn-project-template
|
||||
# Labyricorn Project Template
|
||||
|
||||
Included AGENTS.md files, initial Lektor files and file system
|
||||
A starter template and baseline structure for projects compatible with
|
||||
[Labyricorn](https://www.labyricorn.com).
|
||||
|
||||
To the acting agent. Read this file then replace all existing text in the README.md with proper documentation. You do not need to retain this text or instructions afterward.
|
||||
This template provides the required `.labyricorn/` publishing records, assistant
|
||||
guidance files (`AGENTS.md`), devlog structure, and the standalone
|
||||
`devlog_editor.py` management utility for local validation and GUI editing.
|
||||
|
||||
Setup the workspace to act as an initial labyricorn.com compatible project with devlogs. You can find the needed documentation at: https://git.labyricorn.com/OpenAI/labyricorn-site
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Projects published on Labyricorn maintain their own exhibition pages and
|
||||
development logs directly inside their Git repositories under the `.labyricorn/`
|
||||
directory. The Labyricorn site importer periodically synchronizes these records
|
||||
as read-only content.
|
||||
|
||||
This template includes:
|
||||
|
||||
- **`.labyricorn/` publishing structure**: Validated Lektor-format records for
|
||||
project identity and development logs.
|
||||
- **`devlog_editor.py`**: Standalone GUI and CLI tool for managing devlog entries,
|
||||
validating publishing contracts, and safely publishing changes.
|
||||
- **`AGENTS.md` instructions**: Scoped assistant instructions at repository root
|
||||
and publishing directories to ensure AI assistants adhere to the publishing
|
||||
contract.
|
||||
- **`.gitignore`**: Configured exclusions for Python environments, caches, and build
|
||||
artifacts.
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```text
|
||||
.
|
||||
├── .gitignore
|
||||
├── .labyricorn/
|
||||
│ ├── AGENTS.md # Assistant instructions for publishing content
|
||||
│ ├── README.md # Publishing structure documentation
|
||||
│ ├── project/
|
||||
│ │ ├── AGENTS.md # Instructions for the project exhibition record
|
||||
│ │ ├── contents.lr # Project identity and exhibition narrative
|
||||
│ │ └── <optional logo> # Project logo (PNG, JPEG, WebP)
|
||||
│ └── devlog/
|
||||
│ ├── AGENTS.md # Instructions for devlog records
|
||||
│ ├── contents.lr # Devlog index record
|
||||
│ └── <entry-slug>/ # (Optional) Devlog entry directories
|
||||
│ ├── contents.lr # Devlog entry record
|
||||
│ └── <optional img> # Entry attachments (PNG, JPEG, WebP)
|
||||
├── AGENTS.md # Assistant instructions for the repository
|
||||
├── devlog_editor.py # Standalone devlog editor & validator
|
||||
├── LICENSE # License file
|
||||
└── README.md # Project documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Configure the Project Identity
|
||||
|
||||
Edit `.labyricorn/project/contents.lr` to set your project details:
|
||||
|
||||
```ini
|
||||
_model: project
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
project_id: my-project-id
|
||||
---
|
||||
title: My Project Title
|
||||
---
|
||||
summary:
|
||||
|
||||
A concise summary of the project for listings and cards.
|
||||
---
|
||||
status: active
|
||||
---
|
||||
started: 2026-08-23
|
||||
---
|
||||
author: Author Name
|
||||
---
|
||||
repository_url: https://git.labyricorn.com/Owner/my-project
|
||||
---
|
||||
default_branch: main
|
||||
---
|
||||
tags: python, web, tool
|
||||
---
|
||||
body:
|
||||
|
||||
An exhibition narrative describing the project background, goals, and features.
|
||||
```
|
||||
|
||||
#### Project Fields:
|
||||
- `project_id`: Stable lowercase hyphenated slug (e.g. `my-project`).
|
||||
- `title`: Display title for the project.
|
||||
- `summary`: Short multi-line summary.
|
||||
- `status`: One of `active`, `released`, `maintained`, or `archived`.
|
||||
- `started`: Start date in `YYYY-MM-DD` format.
|
||||
- `author`: Author or organization name.
|
||||
- `repository_url`: Public credential-free HTTPS Git URL.
|
||||
- `default_branch`: Target branch name (e.g. `main`).
|
||||
- `logo`: (Optional) Local filename of an image inside `.labyricorn/project/`.
|
||||
- `tags`: Comma-separated technology or topic labels.
|
||||
- `body`: Markdown narrative of the project.
|
||||
|
||||
### 2. Configure the Devlog Index
|
||||
|
||||
Edit `.labyricorn/devlog/contents.lr` to customize the devlog title and summary:
|
||||
|
||||
```ini
|
||||
_model: devlog
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
title: My Project development log
|
||||
---
|
||||
summary: Milestones and development updates for My Project.
|
||||
```
|
||||
|
||||
### 3. Add Devlog Entries
|
||||
|
||||
To add an entry manually, create a directory under `.labyricorn/devlog/<entry-slug>/`
|
||||
containing `contents.lr`:
|
||||
|
||||
```ini
|
||||
_model: devlog-entry
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
title: Initial Project Milestone
|
||||
---
|
||||
date: 2026-08-23
|
||||
---
|
||||
author: Author Name
|
||||
---
|
||||
summary:
|
||||
|
||||
Overview of the milestone accomplishments.
|
||||
---
|
||||
tags: release, setup
|
||||
---
|
||||
source_commit: <40-character-commit-hash>
|
||||
---
|
||||
body:
|
||||
|
||||
Detailed Markdown description of the milestone, technical decisions, and progress.
|
||||
```
|
||||
|
||||
Alternatively, use `devlog_editor.py` to create and edit entries interactively.
|
||||
|
||||
---
|
||||
|
||||
## Devlog Editor
|
||||
|
||||
The included `devlog_editor.py` script is a standalone utility with zero external
|
||||
dependencies (uses Python standard library and Tkinter).
|
||||
|
||||
### CLI Validation
|
||||
|
||||
Validate all project and devlog records without opening a GUI:
|
||||
|
||||
```bash
|
||||
python devlog_editor.py --validate
|
||||
```
|
||||
|
||||
### Graphical Editor
|
||||
|
||||
Launch the Tkinter management interface to view repository status, draft entries,
|
||||
and publish updates:
|
||||
|
||||
```bash
|
||||
python devlog_editor.py
|
||||
```
|
||||
|
||||
Features of the GUI editor:
|
||||
- **Repository status**: Displays current branch, remote, and ahead/behind counts.
|
||||
- **Entry manager**: Create, edit, and delete devlog entries with automatic slug and date handling.
|
||||
- **Publishing safety**: Stages and commits only `.labyricorn/` publishing files, leaving application source files untouched.
|
||||
|
||||
---
|
||||
|
||||
## Publishing Rules & Constraints
|
||||
|
||||
The Labyricorn site importer enforces strict validation rules on imported repositories:
|
||||
|
||||
1. **Native Lektor Records**: Records must be named `contents.lr` and declare `schema_version: 1`.
|
||||
2. **No Raw HTML**: HTML tags (`<script>`, `<style>`, `<div>`, etc.) are prohibited in text fields and Markdown bodies.
|
||||
3. **Approved Images**: Attachments must be PNG, JPEG, or WebP files located within the record directory. Files must match their magic-byte signatures.
|
||||
4. **Limits**: Up to 100 imported files, maximum 5 MiB per file, and maximum 20 MiB total per project snapshot.
|
||||
5. **Source Commits**: Devlog `source_commit` values must be valid 40-character commit hashes existing on the branch history.
|
||||
6. **No Symlinks or Executables**: Linked paths and executable scripts under `.labyricorn/` are rejected.
|
||||
|
||||
---
|
||||
|
||||
## Assistant Guidance (`AGENTS.md`)
|
||||
|
||||
This repository uses hierarchical `AGENTS.md` files to guide coding assistants:
|
||||
|
||||
- **`AGENTS.md` (Root)**: General project guidelines, authorization boundaries, and devlog practices.
|
||||
- **`.labyricorn/AGENTS.md`**: Publishing boundary contract and security rules.
|
||||
- **`.labyricorn/project/AGENTS.md`**: Rules for editing project exhibition metadata.
|
||||
- **`.labyricorn/devlog/AGENTS.md`**: Standards for crafting verifiable devlog entries.
|
||||
|
||||
Coding assistants working in this repository should always review the nearest
|
||||
applicable `AGENTS.md` before making changes.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This template is released into the public domain under the [Unlicense](LICENSE).
|
||||
+1797
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user