tinqs/blog

Files

T

ozan 7bde9c3159 Standardize: reference docs/.agents/, remove duplicate skills/

2026-06-06 01:07:28 +01:00

6.2 KiB

Raw Blame History

agents.md — Tinqs Blog Agent Guide

This file teaches AI agents (Pi, Cursor, Claude Code) how to work with the Tinqs blog repo. Read it before making any changes.

Shared context

Shared agent identity, team roster, skills, and cross-project rules live in ../docs/.agents/. Read at session start:

../docs/.agents/SOUL.md — shared identity
../docs/ai/company.md — team roster
../docs/ai/siblings.md — repo locations
../docs/.agents/rules/shared-context.md — cross-repo conventions

Blog architecture

tinqs-ltd/blog/
├── _template.html          # Post shell — wraps a single blog post
├── _index_template.html    # Listing shell — blog index page
├── build.js                # Zero-dep Node script: posts/*.md + templates → *.html
├── posts/                  # Markdown posts with YAML frontmatter
│   ├── agent-harness.md
│   ├── agentic-workflow.md
│   └── ...
├── *.html                  # Generated output (never hand-edit regular posts)
├── pi-flow-native-brain.html  # Hand-authored HTML post (SVGs + tables)
├── agents.md               # This file
└── skills/                 # Reusable skill playbooks

Two kinds of posts

Regular posts — Markdown in posts/*.md, built via node build.js into *.html. Always edit the .md, never the .html.
Hand-authored HTML posts — pi-flow-native-brain.html is the only one. It contains inline SVGs and styled tables that build.js can't emit. Edit the HTML directly, never create a .md for it. Cards for hand-authored posts are hardcoded in _index_template.html.

Build pipeline

node build.js  # reads posts/*.md → generates *.html + index.html

build.js has zero npm dependencies — pure Node.js built-ins. It handles:

YAML frontmatter parsing
Minimal markdown → HTML conversion (headings, bold/italic, inline code, fenced code blocks, lists, figures, links, hr)
 /  blocks for raw HTML passthrough
Lead paragraph separation (first paragraph after frontmatter → .post__lead)
Date formatting
Index page generation (newest-first sorted cards)

How to add a post

Regular markdown post

Create posts/<slug>.md:

---
title: "Post Title — with optional subtitle"
slug: url-friendly-slug
date: "2026-06-03"
description: "Full meta description for SEO (150-160 chars ideal)."
og_description: "Shorter OG/Twitter description (optional)."
og_image: "https://www.tinqs.com/img/og-cover.jpg"
excerpt: "Card text shown on the blog index page."
author: "Ozan Bozkurt"
author_initials: "OB"
author_role: "CTO & Developer, Tinqs"
---
First paragraph becomes the lead. Keep it punchy — two sentences max.

Everything after the first blank line is the post body. Use standard markdown.

Then:

node build.js    # generates <slug>.html + rebuilds index.html
git add posts/<slug>.md <slug>.html index.html
git commit -m "post: <title>"

Hand-authored HTML post

Copy pi-flow-native-brain.html as a template. Keep the <style> block and nav/footer wrapper. Key rules:

Always add a card to _index_template.html so it appears on the listing page
Never create a corresponding .md in posts/ — build.js will overwrite it
Use the same class structure: .post, .post__title, .post__body, etc.

Adding a card for a hand-authored HTML post

In _index_template.html, add before {{CARDS}}:

    <a href="your-slug" class="blog-card">
      <span class="blog-card__date">3 June 2026</span>
      <h2 class="blog-card__title">Your Title</h2>
      <p class="blog-card__excerpt">Card excerpt text.</p>
      <span class="blog-card__read">Read &rarr;</span>
    </a>

Styling

Three layers (cascade order)

../style.css — external, served by Git Studio. Nav, footer, base typography, --c-accent: #c9935a. Never edit.
<style> in _template.html — post-page overrides (inline, at end of <head>)
<style> in _index_template.html — index-page overrides

The inline <style> blocks come AFTER the ../style.css link, so same-specificity rules win by cascade order. No !important needed.

Adding a style rule

Open _template.html (or _index_template.html for listing-only styles)
Find the <style> block at end of <head> (marked with /* ── Team guide aesthetic ── */)
Add your rule using the existing palette:
- Amber #c9935a (brand anchor), gold #f59e0b (emphasis)
- Blue #38bdf8 (links, pills), purple #a855f7 (h3, hover)
- Dark #0a0e14 (code bg), border #2a3340
node build.js to regenerate
Verify: grep "your-selector" *.html

Never

Edit ../style.css (outside this repo)
Hand-edit generated *.html (build.js clobbers them)
Restyle .nav, .footer, or mobile menu (belongs to parent site)
Introduce new colours without a strong reason
Add external font loads, CDN deps, or @import

Post structure (writing guide)

Good technical posts follow this pattern:

Lead paragraph — what this is about, one punchy sentence
The hook — why it matters, what problem it solves
How it works — concrete examples, code, metrics
What we learned — insights, surprises, trade-offs
Closing — what's next, internal links to related posts

Voice: direct, concrete, no marketing fluff. Show numbers. Show code. Tell stories.

SEO checklist

Title under 60 characters
Description 150-160 characters
og_image set (falls back to /img/og-cover.jpg)
Meaningful excerpt for index card
Internal links where relevant ([other post](other-slug))

Conventions

Slugs: kebab-case matching filename: my-post.md → slug my-post
Dates: ISO format 2026-06-03
Canonical URLs: https://www.tinqs.com/blog/<slug>
Em dashes: --- in markdown renders as —, -- as –

Deploy

git add -A
git commit -m "post: <description>"
git push origin main

Git Studio serves this repo directly. A push to main is a deploy. No build step on the server — static HTML files.

Skills

Skills live in the hub: ../docs/.agents/skills/ (image-generation, concept-art-pipeline, sora2-video, tripo-browser-workflow, and more). Read skill SKILL.md files from there when needed.

6.2 KiB Raw Blame History