Openspec.md

H

Make these changes to theme JustGoodUI/dante-astro-theme#48

ere is a simple example of how to build a blog using Astro and the Dante theme using the OpenSpec, BDD, and ADR approach. [1] We will structure this into a clean, modular repository layout that an AI coding assistant can instantly interpret and execute.

Step 1: Initialize Your Project Directory

Create a structured repository containing both your Astro site code and your AI-grounding documents (openspec/).

my-astro-blog/ ├── openspec/ │ ├── adrs/ │ │ └── 0001-use-astro-and-dante-theme.md <-- Why we chose this stack │ └── changes/ │ └── 0001-blog-post-listing.md <-- What and How (Specs + BDD) ├── src/ │ └── content/ │ └── blog/ <-- Where the actual code lives

---

Step 2: Write the ADR (The "Why")

This establishes our structural boundary. It tells the AI assistant exactly which framework and theme we are locked into so it does not hallucinate components from other frameworks like Next.js or Tailwind UI.

openspec/adrs/0001-use-astro-and-dante-theme.md

ADR 1: Use Astro with Dante Theme for the Blog## StatusAccepted

ContextWe need a lightweight, fast, content-focused blog with dark mode support and minimalist design.

DecisionWe will use Astro combined with the JustGoodUI Dante Theme.

Consequences* Content must be driven via Astro's standard Markdown/MDX content collections.* The design must adhere to Dante's minimalist, single-author aesthetic.* AI generation must respect Dante's pre-configured CSS and layout variables.

---

Step 3: Create the OpenSpec Proposal & BDD Scenarios (The "What" and "How")

Now, we create a change proposal in our OpenSpec directory to add a blog post listing. This includes the explicit BDD tests that the AI must satisfy.

openspec/changes/0001-blog-post-listing.md

Spec Change: Core Blog Post Listing## System Requirements (What)The blog must list all published markdown files from the src/content/blog/ directory sorted by publication date descending.

BDD Acceptance Scenarios (How to Verify)

Feature: Blog Post Listing Grid As a blog visitor I want to see a clean list of posts So I can choose what to read

Scenario: Displaying multiple published blog posts Given the directory "src/content/blog/" contains the following files:

  | slug         | title          | date       | draft |
  | first-post   | My First Post  | 2026-05-10 | false |
  | second-post  | Learning Astro | 2026-05-14 | false |
When the user visits the home page "/"
Then they should see "Learning Astro" listed above "My First Post"

Scenario: Hiding draft posts Given a blog post file exists with "draft: true" When the user visits the home page "/" Then they should not see the draft post listed

AI Implementation Checklist- [ ] Read files using getCollection('blog')

• Filter out entries where data.draft === true
• Sort remaining entries by data.date in descending order
• Map sorted items to the Dante <PostPreview /> component layout

---

Step 4: Run the AI Agent to Generate the Code

With this context strictly established, you feed this directory into your AI coding assistant (like Claude Code, Cursor, or Aider). Your prompt is simple:

"Implement the OpenSpec proposal located in openspec/changes/0001-blog-post-listing.md. Strictly follow the architectural constraints outlined in openspec/adrs/0001-use-astro-and-dante-theme.md."

The AI will parse your BDD constraints and accurately generate your Astro logic without deviating from your tech stack:

src/pages/index.astro (Auto-Generated by AI)

---

import { getCollection } from 'astro:content'; import BaseLayout from '../layouts/BaseLayout.astro'; import PostPreview from '../components/PostPreview.astro';

// AI satisfied the OpenSpec filters & BDD sorting criteria perfectly: const allPosts = await getCollection('blog', ({ data }) => { return data.draft !== true; });

const sortedPosts = allPosts.sort((a, b) => new Date(b.data.date).getTime() - new Date(a.data.date).getTime() );

Recent Musings

{sortedPosts.map((post) => ( ))}

---

Would you like me to write a GitHub Actions workflow blueprint that automatically validates these BDD specs whenever someone pushes a change, or should we create another OpenSpec file for handling a tag-filtering feature?

[1] https://github.com