Skip to content

Commit 3a505a9

Browse files
vweeksclaude
vweeks
and
claude
committed
Add Astro site with landing page, framework collection, and docs
Astro v6 + Tailwind CSS v4 site structure with Content Collections, component library (Nav, Footer, Hero, FeatureCard), BaseLayout and FrameworkLayout, landing page with feature cards, About page linking to BSSw fellow profile, and framework section with dynamic routing. Includes development log and implementation plan. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 5d2e24c commit 3a505a9

24 files changed

Lines changed: 6442 additions & 0 deletions

‎.vscode/extensions.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"recommendations": ["astro-build.astro-vscode"],
3+
"unwantedRecommendations": []
4+
}

‎.vscode/launch.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"command": "./node_modules/.bin/astro dev",
6+
"name": "Development server",
7+
"request": "launch",
8+
"type": "node-terminal"
9+
}
10+
]
11+
}

‎CLAUDE.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Scientific Agentic Engineering
2+
3+
## Project
4+
5+
2026 BSSw Fellowship project by Victor Weeks (NSF NCAR). Developing methodology for integrating AI agents into scientific software workflows.
6+
7+
**Architecture**: Bare Astro + Tailwind CSS + Pagefind + Content Collections. No Starlight governance. Quarto used only for interactive notebook tutorials (M2+). Each milestone extends the component library — the site grows incrementally from a simple foundation.
8+
9+
**Plan**: See `docs/plan.md` for the current implementation plan with milestone roadmap and file details.
10+
11+
## Sensitive Content — DO NOT COMMIT
12+
13+
The SOW document lives one directory up (`../2026_BSSw-SOW_VictorWeeks_revised_20260212.docx`). Never reference specific financial amounts, SOW text, or budget details in any committed file. The `.gitignore` blocks `*.docx`, `SOW*`, `budget*`, etc., but remain vigilant.
14+
15+
## Development Log (`docs/development-log.md`)
16+
17+
This file transparently records how AI-assisted development was used to build this project. It is a **pedagogical artifact** — the site is about responsible AI-assisted development, and the log demonstrates that methodology in practice.
18+
19+
### When to update the development log
20+
21+
Update the log after **every significant interaction** — defined as any interaction that:
22+
- Makes an architectural or design decision
23+
- Creates, modifies, or deletes files in the repo
24+
- Involves research that informed a decision
25+
- Surfaces a pattern worth documenting (AI behavior, human override, quality issue)
26+
- Results in a rejected approach (failed attempts are as educational as successes)
27+
28+
Do NOT log routine, mechanical actions (typo fixes, formatting, etc.) unless they reveal something interesting.
29+
30+
### How to update the development log
31+
32+
1. **Append a new entry** at the end of the current session section, before the "Template for Future Entries" section
33+
2. **Use the template** from the bottom of the log file:
34+
- `### Interaction N: [Title]` — increment N from the last entry
35+
- `**Human prompt (paraphrased):**` — what was asked (paraphrase, do not copy verbatim)
36+
- `**What the AI did:**` — tools used, agents launched, files created/modified
37+
- `**Key findings/output:**` — what was produced or discovered
38+
- `**Human decisions:**` — what the human chose, modified, or rejected
39+
- `**Observation:**` — what this reveals about AI-assisted development
40+
3. **Start a new session section** (`## Session N — YYYY-MM-DD: [Theme]`) when the conversation is a new Claude Code session
41+
4. **Be honest** about AI missteps, over-engineering, and human corrections — these are the most pedagogically valuable entries
42+
5. **Update the "Patterns Observed" section** when a new pattern emerges across multiple interactions
43+
44+
### Tone
45+
46+
Write as a neutral technical observer, not as marketing. The log should read like a well-kept lab notebook: factual, specific, reflective. Attribute decisions clearly — who decided what and why.
47+
48+
## Milestones
49+
50+
- **M1** (due July 2026): Landing page + Framework document layout + Framework draft
51+
- **M2** (due Oct 2026): Catalog + Tutorial layouts, Quarto/Pyodide integration, US-RSE'26
52+
- **M3** (due Jan 2027): Failure mode exhibits + Full tutorial series
53+
- **M4** (due April 2027): Workshop recordings, HPC webinar, BSSw.io blog post
54+
55+
## Conventions
56+
57+
- **Licensing**: Content is CC-BY-4.0 (`LICENSE-CONTENT`), code is MIT (`LICENSE-CODE`)
58+
- **BSSw acknowledgment**: Must appear on every page footer and in README
59+
- **Component naming**: PascalCase `.astro` files in `src/components/`
60+
- **Content Collections**: Typed schemas in `src/content/config.ts`, one collection per deliverable type
61+
- **Commit style**: Focused commits; split foundation/structure/CI into separate commits

‎astro.config.mjs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// @ts-check
2+
import { defineConfig } from 'astro/config';
3+
import tailwindcss from '@tailwindcss/vite';
4+
5+
// https://astro.build/config
6+
export default defineConfig({
7+
site: 'https://vweeks.github.io',
8+
base: '/scientific-agentic-engineering',
9+
vite: {
10+
plugins: [tailwindcss()],
11+
},
12+
});

‎docs/development-log.md‎

Lines changed: 398 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/plan.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Plan: Scientific Agentic Engineering — Repository & Website Scaffold
2+
3+
## Context
4+
5+
Victor Weeks is a 2026 BSSw Fellow at NSF NCAR developing "Scientific Agentic Engineering" — methodology for integrating AI agents into scientific software workflows. The project needs a professional, public-facing GitHub repo with an incrementally-built website. Git repo already initialized at `/Users/vweeks/NCAR/BSSw/scientific-agentic-engineering/`.
6+
7+
**Sensitive material constraint**: The SOW (`../2026_BSSw-SOW_VictorWeeks_revised_20260212.docx`) is one directory up. Budget, financial details, and SOW contents must never enter version control.
8+
9+
## Architecture Decision
10+
11+
**Bare Astro + Tailwind + Pagefind + Content Collections.** Not Starlight as a framework, not pure Quarto. Cherry-pick Starlight components where useful. Quarto's role is reduced to computational notebook rendering only (tutorials with Pyodide in later milestones).
12+
13+
**Why this architecture:**
14+
- Each milestone extends the component library rather than bolting on new architectural patterns
15+
- The site grows organically from a simple foundation into a rich resource
16+
- Mirrors the methodology the fellowship teaches: principled, incremental, AI-assistable
17+
- Maximum control — no framework opinions constraining layout or navigation
18+
- Content Collections with typed schemas map cleanly to fellowship deliverables
19+
20+
**Milestone-aligned component growth:**
21+
- **M1** (July 2026): Landing page layout + Framework document layout
22+
- **M2** (Oct 2026): Catalog layout (community repo) + Tutorial layout (with Quarto/Pyodide)
23+
- **M3** (Jan 2027): Failure mode exhibit layout + Full tutorial series
24+
- **M4** (April 2027): Workshop recording layout
25+
26+
## Decisions
27+
28+
- **Repo**: `scientific-agentic-engineering` on Victor's personal GitHub
29+
- **Framework**: Astro (bare, no Starlight governance)
30+
- **Styling**: Tailwind CSS
31+
- **Search**: Pagefind (static, framework-independent)
32+
- **Content**: Astro Content Collections with typed schemas
33+
- **Notebooks**: Quarto + Pyodide for interactive tutorials (M2+)
34+
- **License**: Dual — `LICENSE-CODE` (MIT) + `LICENSE-CONTENT` (CC-BY-4.0)
35+
- **Deployment**: GitHub Actions (Astro build → GitHub Pages)
36+
37+
---
38+
39+
## Implementation Steps
40+
41+
### Batch 0: Prerequisites
42+
43+
1. **Verify Node.js** is installed (`node --version`, need 18+)
44+
2. **Create Astro project** via `npm create astro@latest` in the existing repo directory
45+
3. **Add integrations**: `npx astro add tailwind`, add Pagefind
46+
4. **Create GitHub repo**: `gh repo create scientific-agentic-engineering --public --source=. --remote=origin`
47+
48+
### Batch 1: Foundation (Commit 1 — "Initial project setup")
49+
50+
| File | Purpose |
51+
|------|---------|
52+
| `.gitignore` | Broad defensive patterns (*.docx, *.mov, SOW*, node_modules, dist, .astro) |
53+
| `LICENSE-CODE` | MIT license, copyright 2026 Victor Weeks |
54+
| `LICENSE-CONTENT` | CC-BY-4.0 full text |
55+
| `README.md` | Badges (BSSw Fellow, licenses, website, CI), project overview, acknowledgment |
56+
| `CITATION.cff` | CFF 1.2.0 with dual license, ORCID, keywords |
57+
| `CONTRIBUTING.md` | How to contribute, dual license notice |
58+
59+
**Key `.gitignore` additions beyond Astro defaults:**
60+
```
61+
# Block sensitive/large file types broadly
62+
*.docx *.xlsx *.pptx *.mov *.mp4 *.zip
63+
SOW* sow* budget* *statement*of*work*
64+
```
65+
66+
### Batch 2: Astro Site Structure (Commit 2 — "Add Astro site with landing page")
67+
68+
**Astro project structure:**
69+
70+
```
71+
scientific-agentic-engineering/
72+
├── astro.config.mjs # Astro config with Tailwind, site URL
73+
├── tailwind.config.mjs # Tailwind config
74+
├── tsconfig.json # TypeScript config (Astro default)
75+
├── package.json # Dependencies
76+
│
77+
├── src/
78+
│ ├── content/
79+
│ │ ├── config.ts # Content Collection schemas (typed)
80+
│ │ └── framework/ # M1: Framework documents (markdown)
81+
│ │ └── _placeholder.md
82+
│ │
83+
│ ├── layouts/
84+
│ │ ├── BaseLayout.astro # HTML shell: head, meta, nav, footer
85+
│ │ └── FrameworkLayout.astro # M1: Layout for framework docs
86+
│ │
87+
│ ├── components/
88+
│ │ ├── Nav.astro # Top navigation bar
89+
│ │ ├── Footer.astro # Footer with BSSw acknowledgment + licenses
90+
│ │ ├── Hero.astro # Landing page hero section
91+
│ │ └── FeatureCard.astro # Landing page feature cards
92+
│ │
93+
│ ├── pages/
94+
│ │ ├── index.astro # Landing page
95+
│ │ ├── about.astro # About Victor / fellowship
96+
│ │ └── framework/
97+
│ │ └── [...slug].astro # Dynamic routes from content collection
98+
│ │
99+
│ └── styles/
100+
│ └── global.css # Tailwind directives + any global styles
101+
│
102+
├── public/
103+
│ ├── favicon.svg # Simple placeholder favicon
104+
│ └── robots.txt # Allow all crawlers
105+
│
106+
└── docs/
107+
└── development-log.md # Already exists — meta-documentation
108+
```
109+
110+
**Content Collection schema** (`src/content/config.ts`):
111+
```typescript
112+
import { defineCollection, z } from 'astro:content';
113+
114+
const framework = defineCollection({
115+
type: 'content',
116+
schema: z.object({
117+
title: z.string(),
118+
description: z.string(),
119+
order: z.number(),
120+
draft: z.boolean().default(false),
121+
}),
122+
});
123+
124+
// Future collections added per-milestone:
125+
// M2: tutorials, community (catalog items)
126+
// M3: failure-modes
127+
// M4: workshops
128+
129+
export const collections = { framework };
130+
```
131+
132+
**Landing page** (`src/pages/index.astro`):
133+
- Hero component: project title, one-line description, CTA button → Framework
134+
- 4 FeatureCard components: Framework, Tutorials (coming M2), Community (coming M2), Workshops (coming M4)
135+
- BSSw acknowledgment block
136+
- Clean, minimal — Tailwind utility classes, no complex styling
137+
138+
**Nav component**: Home, Framework, About. Tutorials/Community/Workshops links added as milestones deliver them.
139+
140+
**Footer component**: © 2026 Victor Weeks | Content: CC-BY-4.0 | Code: MIT | Supported by the BSSw Fellowship Program
141+
142+
**After creating files**: `npm run dev` to verify local rendering.
143+
144+
### Batch 3: CI/CD (Commit 3 — "Add GitHub Actions deployment")
145+
146+
| File | Purpose |
147+
|------|---------|
148+
| `.github/workflows/deploy.yml` | Astro build → GitHub Pages |
149+
150+
**GitHub Actions workflow:**
151+
```yaml
152+
name: Deploy to GitHub Pages
153+
on:
154+
push:
155+
branches: [main]
156+
workflow_dispatch:
157+
158+
permissions:
159+
contents: read
160+
pages: write
161+
id-token: write
162+
163+
jobs:
164+
build:
165+
runs-on: ubuntu-latest
166+
steps:
167+
- uses: actions/checkout@v4
168+
- uses: actions/setup-node@v4
169+
with:
170+
node-version: 20
171+
cache: npm
172+
- run: npm ci
173+
- run: npm run build
174+
- uses: actions/upload-pages-artifact@v3
175+
with:
176+
path: dist/
177+
178+
deploy:
179+
needs: build
180+
runs-on: ubuntu-latest
181+
environment:
182+
name: github-pages
183+
url: ${{ steps.deployment.outputs.page_url }}
184+
steps:
185+
- id: deployment
186+
uses: actions/deploy-pages@v4
187+
```
188+
189+
**Post-push**: In GitHub repo Settings → Pages → Source: "GitHub Actions".
190+
191+
---
192+
193+
## Files Deferred to Later Milestones
194+
195+
| What | When | Why |
196+
|------|------|-----|
197+
| `FrameworkLayout.astro` content | M1 (July 2026) | Layout exists in scaffold; real content comes with framework draft |
198+
| Tutorial layout + Quarto integration | M2 (Oct 2026) | Tutorials are M2 deliverable |
199+
| Catalog layout (community repo) | M2 (Oct 2026) | Community repo launches at M2 |
200+
| Pagefind integration | M2 (Oct 2026) | Not enough content to search until M2 |
201+
| Failure mode exhibit layout | M3 (Jan 2027) | Failure modes documented at M3 |
202+
| Workshop recording layout | M4 (April 2027) | Workshops happen at M4 |
203+
| Quarto notebooks + Pyodide | M2 (Oct 2026) | Interactive tutorials are M2+ |
204+
| `.devcontainer` | M2+ | No contributors yet |
205+
| Pre-commit hooks | M2+ | No Python code yet |
206+
207+
---
208+
209+
## Milestone Component Roadmap
210+
211+
### M1 (July 2026): Foundation
212+
**New components**: `Hero`, `FeatureCard`, `Nav`, `Footer`, `BaseLayout`, `FrameworkLayout`
213+
**Content**: Framework draft documents in `src/content/framework/`
214+
**Site sections live**: Home, Framework, About
215+
216+
### M2 (October 2026): Catalog + Tutorials
217+
**New components**: `CatalogCard`, `CatalogLayout`, `TutorialLayout`, `CodeBlock` (Pyodide wrapper)
218+
**New collections**: `tutorials`, `community`
219+
**Integrations**: Pagefind for search, Quarto for notebook rendering
220+
**Site sections live**: + Tutorials, + Community
221+
222+
### M3 (January 2027): Failure Modes + Full Tutorials
223+
**New components**: `FailureModeExhibit`, `BeforeAfter` (comparison layout)
224+
**New collection**: `failure-modes`
225+
**Content**: Full tutorial series, failure mode visual documentation
226+
**Site sections live**: + Failure Modes gallery
227+
228+
### M4 (April 2027): Workshops
229+
**New components**: `WorkshopCard`, `VideoEmbed`, `WorkshopLayout`
230+
**New collection**: `workshops`
231+
**Content**: Workshop recordings, HPC webinar, BSSw.io blog post draft
232+
**Site sections live**: + Workshops archive
233+
234+
---
235+
236+
## Verification
237+
238+
After each batch:
239+
240+
1. **Batch 1**: `git status` clean, no sensitive files. `grep -ri "SOW\|budget\|25,000" .` returns nothing
241+
2. **Batch 2**: `npm run dev` → landing page renders at localhost, nav works, feature cards display, footer shows acknowledgment + licenses, dark mode if configured
242+
3. **Batch 3**: Push → GitHub Actions succeeds → site live at Pages URL
243+
4. **CITATION.cff**: GitHub shows "Cite this repository" on repo page
244+
5. **Lighthouse**: Run accessibility audit on local dev server
245+
246+
---
247+
248+
## Critical Files
249+
250+
- `.gitignore` — First file created; broad defensive patterns prevent SOW leak
251+
- `astro.config.mjs` — Central Astro config (site URL, integrations, output mode)
252+
- `src/content/config.ts` — Content Collection schemas; typed foundation for all deliverables
253+
- `src/layouts/BaseLayout.astro` — HTML shell shared by every page; nav, footer, meta
254+
- `.github/workflows/deploy.yml` — Deployment automation; must use Pages v4 action pattern
255+
- `src/pages/index.astro` — Landing page; first impression of the project

0 commit comments

Comments
 (0)
⚡