ozan
56795b680f
Add .agents/ (AGENTS.md Knowledge-map + skills/plans/handoffs/wiki) so blog matches the cross-repo structure; human content (posts/HTML/templates) stays at repo root. Root agents.md points to .agents/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
168 lines
6.4 KiB
Markdown
168 lines
6.4 KiB
Markdown
# 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.
|
|
|
|
> **Repo agent context + Knowledge map:** [`.agents/AGENTS.md`](.agents/AGENTS.md) (skills, plans, handoffs, wiki). Human content (posts/HTML/templates) stays at the repo root.
|
|
|
|
## 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
|
|
|
|
1. **Regular posts** — Markdown in `posts/*.md`, built via `node build.js` into `*.html`. Always edit the `.md`, never the `.html`.
|
|
2. **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
|
|
|
|
```bash
|
|
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)
|
|
- `<!--raw-->` / `<!--/raw-->` 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`:
|
|
|
|
```yaml
|
|
---
|
|
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:
|
|
```bash
|
|
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}}`:
|
|
|
|
```html
|
|
<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 →</span>
|
|
</a>
|
|
```
|
|
|
|
## Styling
|
|
|
|
### Three layers (cascade order)
|
|
|
|
1. `../style.css` — external, served by Git Studio. Nav, footer, base typography, `--c-accent: #c9935a`. Never edit.
|
|
2. `<style>` in `_template.html` — post-page overrides (inline, at end of `<head>`)
|
|
3. `<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
|
|
|
|
1. Open `_template.html` (or `_index_template.html` for listing-only styles)
|
|
2. Find the `<style>` block at end of `<head>` (marked with `/* ── Team guide aesthetic ── */`)
|
|
3. 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`
|
|
4. `node build.js` to regenerate
|
|
5. 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:
|
|
|
|
1. **Lead paragraph** — what this is about, one punchy sentence
|
|
2. **The hook** — why it matters, what problem it solves
|
|
3. **How it works** — concrete examples, code, metrics
|
|
4. **What we learned** — insights, surprises, trade-offs
|
|
5. **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
|
|
|
|
```bash
|
|
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.
|