Imported from ibanFR/ibanfr.github.io (AGENTS.md). Install upstream with npx skills add ibanFR/ibanfr.github.io. Copyright stays with the author.

AGENTS.md

Common instructions for any coding agent working in this repository. Tool-specific files (.github/copilot-instructions.md, CLAUDE.md) reference this file rather than duplicating its content.

What this is

Personal technical blog and knowledge base for Iván Fernández (Software Engineering Director), covering BDD, DDD, XP, Lean, Scrum, technical coaching, software architecture, and AI tooling. It is a static site — content is Markdown (kramdown) with YAML front matter, plus theme configuration. There is no application code, test suite, or lint step.

Tech stack

• Runtime: Ruby 3.1+ (CI uses Ruby 3.3)
• Framework: Jekyll ~> 4.3 with the Minimal Mistakes theme (installed as a gem)
• Markup: Markdown (kramdown) with YAML front matter
• Dependency manager: Bundler 2.x (Gemfile, Gemfile.lock)
• Deployment: GitHub Pages via GitHub Actions (.github/workflows/jekyll.yml)

Commands

bundle install                         # install gems
bundle exec jekyll serve               # local dev server at http://127.0.0.1:4000
bundle exec jekyll build --trace 2>&1  # verify build (see below)
bundle exec jekyll build               # one-off build into _site/

Verify before committing

Build once — don't start the dev server. jekyll build exits on its own, no Ctrl+C needed:

bundle exec jekyll build --trace > /tmp/jekyll-build.log 2>&1; echo "exit=$?"
grep -E "^\s*(Error|Liquid Exception)" /tmp/jekyll-build.log

Check both, because one is not enough:

• exit=0. Non-zero means a fatal error, usually a Liquid tag.
• No grep match. Malformed YAML front matter prints Error: YAML Exception reading <file> and still exits 0, silently dropping the page's front matter.

Fix the root cause before proceeding.

Sass slash-division deprecation warnings (~230) come from the upstream minimal-mistakes-jekyll gem. Expected, ignore them.

Start the dev server only to look at a page in a browser. To check rendered output, grep _site/ instead.

Deployment

.github/workflows/jekyll.yml builds and deploys to GitHub Pages on push to the minimal-mistakes branch (this is the active working branch, not main).

Project layout

_config.yml            # Main Jekyll config — site title, plugins, collections, defaults
Gemfile                # Ruby gem dependencies
.github/
  workflows/jekyll.yml # CI/CD: build and deploy to GitHub Pages (branch: minimal-mistakes)
  git-commit-instructions.md
_data/navigation.yml   # Top nav (main) and one sidebar menu per collection
_posts/                # Blog posts — filename: YYYY-MM-DD-slug.md
_pages/                # Static pages (about, home, 404, portfolio index)
_guides/               # Guide index pages (one per topic)
_portfolio/            # Portfolio case studies
_bdd/ _ddd/ _xp/ _lean/ _coaching/ _scrum/ _architecture/
                       # Topic knowledge bases (Diátaxis subfolders)
_includes/             # Custom HTML overrides (head.html, footer.html)
assets/                # Static assets (css/, images/, js/)
_cache/                # jekyll-linkpreview cache (gitignored, auto-managed)
_site/                 # Build output (gitignored — never edit)

Content architecture

The site is organized as Jekyll collections, one per topic, each declared in _config.yml under collections: with per-collection defaults: (layout, sidebar nav, toc) applied by type. Knowledge-base collections follow the Diátaxis structure — subfolders explanation/, reference/, tutorials/, how-to/.

When adding a new collection or page: declare the collection in _config.yml (with a defaults scope) and add its sidebar menu / entry in _data/navigation.yml. Missing either breaks navigation.

Content conventions

All content requires YAML front matter. Layout, sidebar, toc, and similar keys come from _config.yml defaults scoped by collection type — don't repeat inherited keys per file; set only what's specific to the page.

Posts (_posts/)

• Filename _posts/YYYY-MM-DD-slug.md, lowercase hyphenated slug.

• Front matter:

  ---
  title: "Post Title"
  date: YYYY-MM-DD
  header:
    image: /assets/images/posts/<image>.jpg
  categories:
    - Category
  tags:
    - Tag One
    - Tag Two
  ---

• Headings in sentence case.

• Prefer short paragraphs and bullet lists.

• layout: single, author profile, toc, comments, share, related, and the posts sidebar are inherited from defaults — don't repeat them.

Collections (_guides/, _portfolio/, _bdd/, _ddd/, _xp/, _lean/, _coaching/, _scrum/, _architecture/)

• Each collection is declared in _config.yml and wired into _data/navigation.yml (see Content architecture). Knowledge bases follow the Diátaxis subfolders.
• Content pages typically need only title: — layout, sidebar, and toc are inherited from the collection's defaults.
• Collection index page sets layout: collection, collection: <name>, permalink:, and hidden: true.
• Guide index pages also use header.teaser and an order: for sorting.

Pages (_pages/)

• One-off static pages (about, home, 404, portfolio index).
• Minimal front matter — usually just permalink: and title:; layout: single is inherited.

Quotes and citations

Attribute every quotation to its author, using <cite> inside the blockquote — never as a paragraph after it. The theme styles blockquote cite and prefixes it with an em-dash, so a trailing — Author line renders as ordinary body copy instead.

> Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure
> without changing its external behavior.
>
> <cite>Martin Fowler on his site [Refactoring]</cite>

• Separate quote and citation with a blank > line — kramdown then renders the citation as its own <p> inside the blockquote.
• Give the author's full name on first mention (Jeff Patton, not Patton).
• Link the source from inside the <cite>, reference-style, with the definition at the bottom of the file. Link the work or page, not the author's name.
• Phrasing follows the source type: <cite>{Author} on his site [{Page}]</cite> for a web page, <cite>[{Book Title}] by {Authors}</cite> for a book.
• Existing examples to match: _xp/explanation/refactoring.md, _coaching/explanation/coaching-goodreads.md, _bdd/explanation/user-story-mapping.md.
• Quote only sources you have verified. Prefer the primary source (the author's own site or book) over a blog repeating it.

Images

• Location: post images go in /assets/images/posts/. Top-level /assets/images/ is for site-wide assets only.
• feature_row / teaser images: use 500 × 300 px (5:3 aspect ratio) — the Minimal Mistakes recommended teaser size. Keep every image in a given feature_row at the same ratio so cards render uniformly.
• Post header images (header.image): use 1280 × 320 px (4:1 aspect ratio). The theme renders header.image full-width at its natural ratio, so size the source file rather than adding custom CSS. When a post's header and teaser differ in ratio, use separate files (e.g. -header / -teaser).
• Overlay header images (header.overlay_image): no fixed aspect ratio — the theme renders it as a background-size: cover layer whose height is driven by the overlay text, so it crops per page. Use a wide, centered landscape source ≥ 1280 px wide (≈ 1600 × 600 works well); do not size these to a specific ratio.

Safety rails

• Never edit or commit files under _site/ — gitignored, generated at build time.
• Never edit or commit files under _cache/ — gitignored, auto-managed.
• _config.yml is not live-reloaded — restart the server after editing it.
• Avoid modifying Minimal Mistakes theme gem files — override via _includes/, assets/, and _config.yml.

Commit convention

• Read .github/git-commit-instructions.md — it defines the commit message format for this repository.
• Before committing: present the proposed commit message to the user and ask for confirmation to commit and push. Do not commit or push until they approve.

Atlassian Rovo MCP

When connected to atlassian-rovo-mcp:

• MUST use Jira project key SITE.
• MUST use cloudId https://ibanfr.atlassian.net (do NOT call getAccessibleAtlassianResources).
• MUST use maxResults: 10 / limit: 10 for all Jira JQL and Confluence CQL searches.