generated from Labyricorn/labyricorn-project-template
213 lines
6.6 KiB
Markdown
213 lines
6.6 KiB
Markdown
# Labyricorn Project Template
|
|
|
|
A starter template and baseline structure for projects compatible with
|
|
[Labyricorn](https://www.labyricorn.com).
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## 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). |