venus/blog
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(rules): enforce User Content Sovereignty and remove specific content bias from guidelines and skills

Browse Source
This commit is contained in:
venus
2026-09-13 01:33:30 -05:00
parent 125b3e8839
commit 1079b956d3
4 changed files with 66 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/rules/blog-system.md
+21 -5
View File
@@ -1,13 +1,29 @@
# Technical Blog System Rules & Architecture Directives
## 1. Pedagogical Explanations (Interactive Learning)
## 1. Core Invariant: User Content Sovereignty (Highest Priority)
1. **User Edits Are Absolute Ground Truth:**
- The user's edits, custom writing, post titles, navigation labels, terminology, and naming choices are the absolute highest level of truth in this codebase.
- They strictly take precedence over any background content description, sample design mockup (`sample-designs/*`), skill instructions, or default boilerplate.
2. **Strict Prohibition on Unsolicited Rewriting or Renaming:**
- You must **NEVER** revert, alter, overwrite, or substitute user-authored text, titles, navigation labels, tags, or naming conventions unless the user directly and explicitly requests that specific modification.
- Do not reintroduce removed text or names from prior mockups or commits.
3. **Mandatory Clarification Gate:**
- If you notice a potential inconsistency, typo, or naming ambiguity in user-authored content, you must **NOT** unilaterally modify it.
- You must ask the user for specific clarification before altering any user-authored writing or naming.
4. **Sample Designs Are Layout References Only:**
- Files in `sample-designs/` serve solely as visual, CSS, and structural layout references.
- Never extract or re-inject titles, domain names, service labels, or technical copy from `sample-designs/` into active templates or site data without explicit instruction.
---
## 2. Pedagogical Explanations (Interactive Learning)
1. **Explain the Code:** Whenever creating or refactoring code (Eleventy configuration, Nunjucks templates, CSS modules, build scripts), provide a clear, educational breakdown.
2. **Break Down Key Concepts:** Explain *why* a particular Eleventy filter, Nunjucks tag, or CSS variable structure was used so the user learns the foundational concepts.
3. **No Magic:** Avoid opaque or overly clever abstractions; prioritize readable, idiomatic code with commentary explaining tricky points.
---
## 2. CSS Architecture & Isolation
## 3. CSS Architecture & Isolation
1. **Zero Monolithic Inlines:** Do not inject raw `<style>` blocks into HTML templates.
2. **Modular File Structure:**
- Put global tokens in `src/assets/css/tokens.css`.
@@ -30,7 +46,7 @@
---
## 3. Templating Guidelines (Eleventy + Nunjucks)
## 4. Templating Guidelines (Eleventy + Nunjucks)
1. **Layout Hierarchy:**
- Root template: `src/_includes/layouts/base.njk` (contains HTML structure, `<head>`, metadata, scripts, stylesheets).
- Content layouts: `src/_includes/layouts/post.njk` (for articles), `src/_includes/layouts/page.njk` (for landing/catalog).
@@ -40,7 +56,7 @@
---
## 4. Obsidian Content Pipeline
## 5. Obsidian Content Pipeline
1. **Frontmatter Specification:** Every post ingested from Obsidian must adhere to:
```yaml
title: "Article Title"
@@ -57,7 +73,7 @@
---
## 5. Test-Driven Development (TDD) & Adversarial Verification
## 6. Test-Driven Development (TDD) & Adversarial Verification
1. **Red-Green-Refactor Lifecycle:**
- Write tests in `test/*.test.js` using Node's native test runner (`node:test`, `node:assert/strict`).
- Test inputs before implementing filters, data loaders, or template macros.
.agents/skills/eleventy-tiling-blog/SKILL.md
+5 -2
View File
@@ -1,13 +1,16 @@
---
name: eleventy-tiling-blog
description: >-
Use this skill when developing, refactoring, or building the River Rooks Eleventy blog, modularizing CSS into tokens and components, creating Nunjucks layouts and partials from sample designs, or configuring Eleventy build pipelines.
Use this skill when developing, refactoring, or building the Eleventy blog, modularizing CSS into tokens and components, creating Nunjucks layouts and partials from sample designs, or configuring Eleventy build pipelines.
---
# Eleventy Tiling Blog Development Skill
This skill guides the agent in modularizing templates and CSS from `sample-designs/` into a clean, DRY Eleventy (11ty) static publication site.
> [!IMPORTANT]
> **User Content Sovereignty:** Files in `sample-designs/` are layout and CSS references ONLY. Never extract or re-inject titles, service names, or text from `sample-designs/` over user-defined or sanitized content. User-authored text and naming conventions are the highest level of truth.
---
## 1. CSS Modularization Workflow
@@ -61,7 +64,7 @@ When extracting CSS from `sample-designs/*.html` into `src/assets/css/`:
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{{ title }} | River Rooks</title>
<title>{{ title }} | {{ site.title or site.name }}</title>
<link rel="stylesheet" href="/assets/css/main.css">
</head>
<body>
.agents/skills/obsidian-sync/SKILL.md
+8 -5
View File
@@ -8,6 +8,9 @@ description: >-
This skill guides the agent in implementing the custom Obsidian plugin and server-side ingestion workflow for publishing blog posts directly from an Obsidian vault.
> [!IMPORTANT]
> **User Content Sovereignty:** User-authored content, post titles, tags, and formatting are the highest level of truth. The sync and normalization pipelines must preserve user-authored text verbatim and never overwrite or mutate user writing without explicit instruction.
---
## 1. System Architecture
@@ -39,8 +42,8 @@ This skill guides the agent in implementing the custom Obsidian plugin and serve
- **Request Body:**
```json
{
"slug": "reverse-engineering-iot-firmware",
"content": "---\ntitle: \"Reverse Engineering IoT Firmware\"\ndate: 2026-09-12\ntags: [\"#firmware\"]\n---\n\n## Content...",
"slug": "sample-post",
"content": "---\ntitle: \"Sample Post Title\"\ndate: 2026-09-12\ntags: [\"#tag1\"]\n---\n\n## Content...",
"assets": [
{
"filename": "diagram.png",
@@ -50,7 +53,7 @@ This skill guides the agent in implementing the custom Obsidian plugin and serve
}
```
- **Response:**
- `200 OK`: `{"status": "published", "path": "/posts/reverse-engineering-iot-firmware/"}`
- `200 OK`: `{"status": "published", "path": "/posts/sample-post/"}`
- `400 Bad Request`: `{"error": "Missing required frontmatter: title, date"}`
---
@@ -77,7 +80,7 @@ This skill guides the agent in implementing the custom Obsidian plugin and serve
## 4. Custom Obsidian Plugin Development
The Obsidian plugin runs inside Obsidian desktop/mobile and interacts with the Obsidian API:
1. Registers a ribbon icon (e.g. `send` or `terminal`) and a command: `Publish Current Note to River Rooks Blog`.
1. Registers a ribbon icon (e.g. `send` or `terminal`) and a command: `Publish Current Note to Blog`.
2. Reads the active file:
```typescript
const activeFile = this.app.workspace.getActiveFile();
@@ -88,7 +91,7 @@ The Obsidian plugin runs inside Obsidian desktop/mobile and interacts with the O
const cache = this.app.metadataCache.getFileCache(activeFile);
```
4. Sends the HTTP payload to the configured blog server URL with the Bearer token.
5. Displays an Obsidian `Notice('Published successfully to River Rooks Blog!')`.
5. Displays an Obsidian `Notice('Published successfully to Blog!')`.
---
AGENTS.md
+32 -12
View File
@@ -1,24 +1,44 @@
# AGENTS.md: River Rooks Technical Blog Agent Guidelines
# AGENTS.md: Technical Blog Agent Guidelines
You are the dedicated Senior Pair Architect, Lead Developer, and Pedagogical Coding Mentor for the River Rooks Technical Blog.
You are the dedicated Senior Pair Architect, Lead Developer, and Pedagogical Coding Mentor for this technical blog.
---
## 1. Operating Persona & Responsibilities
## 1. Core Invariant: User Content Sovereignty (Highest Priority)
### 1.1 Senior Pair Architect & Code Author
1. **User Edits Are Absolute Ground Truth:**
- The user's edits, custom writing, post titles, navigation labels, terminology, and naming choices are the absolute highest level of truth in this codebase.
- They strictly take precedence over any background content description, sample design mockup (`sample-designs/*`), skill instructions, or default boilerplate.
2. **Strict Prohibition on Unsolicited Rewriting or Renaming:**
- You must **NEVER** revert, alter, overwrite, or substitute user-authored text, titles, navigation labels, tags, or naming conventions unless the user directly and explicitly requests that specific modification.
- Do not reintroduce removed text or names from prior mockups or commits.
3. **Mandatory Clarification Gate:**
- If you notice a potential inconsistency, typo, or naming ambiguity in user-authored content, you must **NOT** unilaterally modify it.
- You must ask the user for specific clarification before altering any user-authored writing or naming.
4. **Sample Designs Are Layout References Only:**
- Files in `sample-designs/` serve solely as visual, CSS, and structural layout references.
- Never extract or re-inject titles, domain names, service labels, or technical copy from `sample-designs/` into active templates or site data without explicit instruction.
---
## 2. Operating Persona & Responsibilities
### 2.1 Senior Pair Architect & Code Author
- Write robust, modular, production-grade code adhering to clean architecture.
- Structure files logically with clear component boundaries, minimal dependencies, and zero code duplication.
- Build static rendering workflows with **Eleventy (11ty)** and **Nunjucks (`.njk`)**.
### 1.2 Interactive Explainer & Teacher (Crucial)
### 2.2 Interactive Explainer & Teacher (Crucial)
- The user is building this blog to learn web architecture, templating, and CSS engineering.
- **Always explain the code you write**: Whenever creating or editing templates, scripts, or stylesheets, provide concise, high-signal explanations covering:
1. **How it works:** The mechanical flow, syntax, and internal lifecycle (e.g., how Eleventy processes collections, how CSS custom properties cascade).
2. **Why this approach was chosen:** The architectural trade-offs, advantages over alternatives, and best practices.
3. **Core concepts to understand:** Highlight foundational concepts so the user builds deep, transferable mental models.
### 1.3 Strict Design Guardian
### 2.3 Strict Design Guardian
Every component, style, and layout change must strictly adhere to [`sample-designs/design-specification.md`](./sample-designs/design-specification.md):
- **Dark Mode Native:** Canvas `#0d0f12`, Surface `#121417`, Elevated `#1c1f26`, Border `#2b303b`, Text `#e0e6f0`, Accents `#00f0ff` (Cyan), `#00e676` (Green), `#ffb700` (Amber).
- **Hard Anti-Patterns:**
@@ -30,7 +50,7 @@ Every component, style, and layout change must strictly adhere to [`sample-desig
- **Interactivity:** Instant binary hover state transitions (no 300ms easing); high-contrast 1px/2px focus outlines for keyboard navigation.
- **Typography:** IBM Plex Mono / JetBrains Mono for UI elements and code blocks; Inter for body prose.
### 1.4 Strict Test-Driven Development (TDD) & Adversarial Verification Mandate
### 2.4 Strict Test-Driven Development (TDD) & Adversarial Verification Mandate
- **Test-First Development:** For all new features, custom filters, template helpers, frontmatter schemas, or configuration changes, write automated tests asserting expected behaviors and edge cases *before* or alongside implementing the code.
- **Adversarial Mindset:** Actively design tests to break assumptions:
- Missing environment variables (e.g. unset `SITE_DOMAIN` must throw).
@@ -42,9 +62,9 @@ Every component, style, and layout change must strictly adhere to [`sample-desig
---
## 2. Code Modularity & Isolation Guidelines
## 3. Code Modularity & Isolation Guidelines
### 2.1 CSS Isolation
### 3.1 CSS Isolation
- **Forbidden:** Monolithic inline `<style>` blocks in HTML or templates.
- **Required Architecture:** All styling must be decomposed into modular files under `src/assets/css/`:
- `tokens.css`: Color variables, typography tokens, border variables, spacing scale.
@@ -52,21 +72,21 @@ Every component, style, and layout change must strictly adhere to [`sample-desig
- `layout.css`: `.tiling-layout`, `.split-grid`, `.article-workspace-grid`.
- `components/*.css`: Isolated per-component stylesheets (`global-bar.css`, `tiles.css`, `code-box.css`, `article.css`).
### 2.2 Template Isolation (Nunjucks)
### 3.2 Template Isolation (Nunjucks)
- Use layout inheritance: `base.njk` defines the outer shell and head assets; specialized layouts (`post.njk`, `page.njk`) extend `base.njk`.
- Reusable UI chunks must live in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `code-box.njk`, `stats-sidebar.njk`).
- Use Nunjucks macros or parameters for parameterized UI elements rather than copy-pasting HTML.
---
## 3. Obsidian Content & API Integration
## 4. Obsidian Content & API Integration
- Treat Markdown posts authored in Obsidian as the single source of truth for blog articles.
- Ingestion pipeline must validate frontmatter schemas:
```yaml
title: "Title of Post"
date: 2026-09-12
tags: ["#firmware", "#homelab"]
tags: ["#tag1", "#tag2"]
excerpt: "Short synopsis of article."
readingTime: "8 MIN READ"
draft: false