Universal AI Agent Guide: CO3DEX

This document provides definitive guidance for all AI assistants, agents, and autonomous coding tools (including GitHub Copilot, Claude Code, OpenAI Codex, Cursor, Windsurf, Gemini, etc.) working within the CO3DEX repository.

1. Project Overview & Architecture

  • Project: CO3DEX (https://www.co3dex.com) — personal tech art, programming, and gamedev static blog.
  • Engine: Jekyll 4.x static site generator based on the devlopr-jekyll theme.
  • Backend / Database: None. Pure static HTML/CSS/JS generation outputted to ./build/.
  • Primary Languages: Liquid templates, HTML5, SCSS/Sass, Markdown, YAML.

2. Essential Commands

# Install dependencies (Ruby Gems via Bundler)
bundle install

# Local development server with live reload at http://localhost:4000
bundle exec jekyll serve --livereload

# Production build (outputs compiled site to ./build)
bundle exec jekyll build

# Clean build artifacts and Jekyll cache
bundle exec jekyll clean

# Local CMS admin UI at http://localhost:4000/admin (via jekyll-admin gem)
# (Automatically available when running jekyll serve)

# Preview native Jekyll drafts (_drafts/ directory)
bundle exec jekyll serve --livereload --drafts

On Windows PowerShell, use the helper scripts in scripts/:

  • .\scripts\install.ps1
  • .\scripts\serve.ps1
  • .\scripts\build.ps1
  • .\scripts\clean.ps1

3. Directory Layout & Workflow Roles

Directory / File Purpose & Lifecycle
_posts/ Live blog posts formatted as YYYY-MM-DD-slug.md.
_drafts/ Jekyll’s native draft holding area. Post-shaped, not built unless --drafts is passed.
.docs/wip/ Free-form Markdown concept memos, thesis drafts, and unstructured writing. Outside Jekyll source tree.
_layouts/ HTML page templates (post.html, home.html, page.html, author.html, etc.).
_includes/ Reusable HTML partials (blog_post_article.html, blog_sidebar.html, head.html, etc.).
_authors/ Author profile Markdown files (e.g. hogjonny.md).
_data/ YAML data files (e.g. authors.yml, galleries).
categories/ Dedicated category landing pages. Every category used in a post must have a corresponding file here.
assets/ Static media, CSS, JS, images (assets/img/posts/).
_sass/ SCSS stylesheets.
build/ Output directory generated during build (gitignored).

4. Strict Rules for AI Coding & Content Generation

A. Post Front Matter Standard

All posts in _posts/ and _drafts/ must adhere to this YAML front matter schema:

---
layout: post
title: "Post Title Here"
summary: "Concise summary for previews and social embeds"
author: hogjonny
date: "YYYY-MM-DD 00:00:00 -0600"
modified_date: "YYYY-MM-DD 00:00:00 -0600"
category: <category-slug>
thumbnail: /assets/img/posts/YYYY-MM-DD-slug.png
keywords: comma,separated,keywords
permalink: /blog/slug/
usemathjax: false
---

B. Mandatory Rule: Never Use Future Dates

CRITICAL: Jekyll silently ignores posts whose date: timestamp is in the future. The post will not build or appear on the website, and no error or warning will be emitted. Always set date: to the current date or earlier.

C. Mandatory Rule: Category Pages Must Exist

Jekyll does not auto-generate category archive pages because jekyll-archives is disabled. Every unique category: slug used in any post MUST have a corresponding Markdown file in categories/<slug>.md.

If a post introduces a new category <slug>:

  1. Create categories/<slug>.md:

    ---
layout: page
title: <Display Name>
permalink: /blog/categories/<slug>/
---

<h5> Posts by Category : Universal AI Agent Guide: CO3DEX </h5>

<div class="card">
   
</div>

  2. Update the categories list in CLAUDE.md / AGENTS.md.

Currently defined categories: info, jekyll, life, guides, python, techart, gamedev.

D. Draft vs. WIP Management

  • Do not publish directly from .docs/wip/ without converting into post format (proper front matter, slug naming, category, thumbnail).
  • Staged posts ready for scheduling belong in _drafts/.
  • Publishing involves moving the file to _posts/YYYY-MM-DD-slug.md with a valid non-future date.

E. Template & SEO Integrity

  • _layouts/post.html delegates post content rendering to _includes/blog_post_article.html.
  • SEO tags are generated by jekyll-seo-tag via _includes/head.html and rely on thumbnail, keywords, description/summary, and title.
  • Keep permalinks structured consistently: /blog/<slug>/.

5. Instructions & Prompt Alignment

For tool-specific setups: