From 17cb6297ec6487043d65fce31d526699dc5f2f14 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 16:42:16 +0100 Subject: [PATCH 1/9] Add GitHub Pages site for the workshop guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Publishes GettingStartedWithSpec-DrivenDev.md and reference.md as a navigable Jekyll site under docs/, with a sticky per-page heading TOC (minimal-mistakes theme, toc: true via defaults). Source files are symlinked into docs/ so they remain the single source of truth. Fixes one broken link in reference.md — a leftover Google-Docs anchor (?tab=t.0#heading=...) — now pointing at the "Safety first! Sandboxing" section. Deploys via GitHub Actions (push to main + workflow_dispatch), so the PR branch can be previewed before merge. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/pages.yml | 45 +++++++++++ .gitignore | 6 ++ docs/Gemfile | 7 ++ docs/Gemfile.lock | 98 ++++++++++++++++++++++++ docs/GettingStartedWithSpec-DrivenDev.md | 1 + docs/_config.yml | 52 +++++++++++++ docs/_data/navigation.yml | 5 ++ docs/assets | 1 + docs/index.md | 12 +++ docs/reference.md | 1 + reference.md | 2 +- 11 files changed, 229 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/pages.yml create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock create mode 120000 docs/GettingStartedWithSpec-DrivenDev.md create mode 100644 docs/_config.yml create mode 100644 docs/_data/navigation.yml create mode 120000 docs/assets create mode 100644 docs/index.md create mode 120000 docs/reference.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..0856541 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,45 @@ +name: Deploy GitHub Pages + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.2" + bundler-cache: true + working-directory: docs + - uses: actions/configure-pages@v5 + - name: Build + working-directory: docs + run: bundle exec jekyll build + env: + JEKYLL_ENV: production + - uses: actions/upload-pages-artifact@v3 + with: + path: docs/_site + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deploy.outputs.page_url }} + steps: + - id: deploy + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index e762e60..13ef3ab 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,9 @@ recording.jfr # OS X .DS_Store + +# Jekyll / GitHub Pages +docs/_site/ +docs/.jekyll-cache/ +docs/.jekyll-metadata +docs/vendor/ diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..506fda2 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,7 @@ +source "https://rubygems.org" + +gem "jekyll", "~> 4.3" +gem "jekyll-remote-theme" +gem "jekyll-optional-front-matter" +gem "jekyll-relative-links" +gem "jekyll-include-cache" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..02f3d75 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,98 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (4.1.2) + colorator (1.1.0) + concurrent-ruby (1.3.6) + csv (3.3.5) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.4-arm64-darwin) + forwardable-extended (2.6.0) + google-protobuf (4.34.1-arm64-darwin) + bigdecimal + rake (~> 13.3) + http_parser.rb (0.8.1) + i18n (1.14.8) + concurrent-ruby (~> 1.0) + jekyll (4.4.1) + addressable (~> 2.4) + base64 (~> 0.2) + colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (~> 0.3, >= 0.3.6) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-relative-links (0.7.0) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-watch (2.2.1) + listen (~> 3.0) + json (2.19.4) + kramdown (2.5.2) + rexml (>= 3.4.4) + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.10.0) + logger + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (7.0.5) + rake (13.4.2) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.4) + rouge (4.7.0) + rubyzip (2.4.1) + safe_yaml (1.0.5) + sass-embedded (1.99.0-arm64-darwin) + google-protobuf (~> 4.31) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + webrick (1.9.2) + +PLATFORMS + arm64-darwin-23 + +DEPENDENCIES + jekyll (~> 4.3) + jekyll-include-cache + jekyll-optional-front-matter + jekyll-relative-links + jekyll-remote-theme + +BUNDLED WITH + 2.4.22 diff --git a/docs/GettingStartedWithSpec-DrivenDev.md b/docs/GettingStartedWithSpec-DrivenDev.md new file mode 120000 index 0000000..81f29ce --- /dev/null +++ b/docs/GettingStartedWithSpec-DrivenDev.md @@ -0,0 +1 @@ +../GettingStartedWithSpec-DrivenDev.md \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..6f1947d --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,52 @@ +title: Spec-Driven Development Workshop +description: A workshop on spec-driven development and lightweight formal methods. +remote_theme: mmistakes/minimal-mistakes@4.26.2 +minimal_mistakes_skin: default + +plugins: + - jekyll-optional-front-matter + - jekyll-relative-links + - jekyll-include-cache + - jekyll-remote-theme + +optional_front_matter: + remove_originals: true + +relative_links: + enabled: true + collections: false + +kramdown: + input: GFM + auto_ids: true + +defaults: + - scope: + path: "GettingStartedWithSpec-DrivenDev.md" + values: + layout: single + title: "Getting Started with Spec-Driven Development" + toc: true + toc_sticky: true + toc_label: "On this page" + permalink: /guide.html + - scope: + path: "reference.md" + values: + layout: single + title: "Reference" + toc: true + toc_sticky: true + toc_label: "On this page" + permalink: /reference.html + - scope: + path: "index.md" + values: + layout: single + title: "Home" + +exclude: + - Gemfile + - Gemfile.lock + - vendor/ + - _site/ diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml new file mode 100644 index 0000000..f50364d --- /dev/null +++ b/docs/_data/navigation.yml @@ -0,0 +1,5 @@ +main: + - title: "Getting Started" + url: /guide.html + - title: "Reference" + url: /reference.html diff --git a/docs/assets b/docs/assets new file mode 120000 index 0000000..ec2e4be --- /dev/null +++ b/docs/assets @@ -0,0 +1 @@ +../assets \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5d65ed4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +--- +layout: single +title: "Home" +permalink: / +--- + +This is a workshop repo designed to help engineers learn about spec-driven development (and lightweight formal methods) through a series of exercises. + +- **[Getting Started with Spec-Driven Development](guide.html)** — the full workshop guide, with exercises. +- **[Reference](reference.html)** — quick summary of the main points, desired outcome, and the tooling support needed for success. + +The source lives at [adzerk/spec-driven-workshop](https://github.com/adzerk/spec-driven-workshop). See the `main-more` branch for additional material. diff --git a/docs/reference.md b/docs/reference.md new file mode 120000 index 0000000..ca3b908 --- /dev/null +++ b/docs/reference.md @@ -0,0 +1 @@ +../reference.md \ No newline at end of file diff --git a/reference.md b/reference.md index d333fda..8c56228 100644 --- a/reference.md +++ b/reference.md @@ -32,4 +32,4 @@ We need to have high confidence and assurance in the artifacts produced by our c * Extended checking with code verifiers and similar tools * Subagents for code-review, testing, and code optimization passes (we’ll cover these in the workshop) -Regardless of the language and runtime of your project, you should have support for each of these critical areas. You also need a [strong sandbox](?tab=t.0#heading=h.1fgtjot5p1vd). \ No newline at end of file +Regardless of the language and runtime of your project, you should have support for each of these critical areas. You also need a [strong sandbox](GettingStartedWithSpec-DrivenDev.md#safety-first-sandboxing). \ No newline at end of file From dcb7e62670dbf50b5a17d02c5643611a457269e8 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 16:49:10 +0100 Subject: [PATCH 2/9] Trigger Pages workflow on pull_request so first deploy happens pre-merge workflow_dispatch needs the workflow YAML on the default branch before it can be invoked. Adding a pull_request trigger lets the PR preview deploy without that chicken-and-egg. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/pages.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 0856541..7764d67 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -3,6 +3,8 @@ name: Deploy GitHub Pages on: push: branches: [main] + pull_request: + branches: [main] workflow_dispatch: permissions: From f1cbdedcae0e59fdc4aa9818fb14c0fd232d1686 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 16:49:55 +0100 Subject: [PATCH 3/9] Add x86_64-linux platform to Gemfile.lock for CI GitHub runners are x86_64-linux; the lock was arm64-darwin-only from the local macOS build. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/Gemfile.lock | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 02f3d75..ba9fb98 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -13,10 +13,14 @@ GEM http_parser.rb (~> 0) eventmachine (1.2.7) ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86_64-linux-gnu) forwardable-extended (2.6.0) google-protobuf (4.34.1-arm64-darwin) bigdecimal rake (~> 13.3) + google-protobuf (4.34.1-x86_64-linux-gnu) + bigdecimal + rake (~> 13.3) http_parser.rb (0.8.1) i18n (1.14.8) concurrent-ruby (~> 1.0) @@ -79,6 +83,8 @@ GEM safe_yaml (1.0.5) sass-embedded (1.99.0-arm64-darwin) google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-gnu) + google-protobuf (~> 4.31) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) unicode-display_width (2.6.0) @@ -86,6 +92,7 @@ GEM PLATFORMS arm64-darwin-23 + x86_64-linux DEPENDENCIES jekyll (~> 4.3) From f7015209ec4362822f76a6cd0eb0fe68f1f99429 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 16:51:04 +0100 Subject: [PATCH 4/9] Auto-enable Pages via configure-pages@v5 Lets the first run of this workflow flip the repo Pages source to GitHub Actions rather than requiring a manual Settings toggle. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/pages.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 7764d67..1430772 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -27,6 +27,8 @@ jobs: bundler-cache: true working-directory: docs - uses: actions/configure-pages@v5 + with: + enablement: true - name: Build working-directory: docs run: bundle exec jekyll build From 227c957c4fa39e6f81d89b1836418b9c6a5dbbca Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 16:53:19 +0100 Subject: [PATCH 5/9] Switch Pages trigger from pull_request to push pull_request-triggered runs use refs/pull/N/merge, which can't match a branch policy on the github-pages environment. Triggering on push uses the branch ref directly, which the environment can allow via its custom branch policy list. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/pages.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 1430772..96ecbd2 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -2,9 +2,9 @@ name: Deploy GitHub Pages on: push: - branches: [main] - pull_request: - branches: [main] + branches: + - main + - worktree-github-pages workflow_dispatch: permissions: From 8f2b24f523771947eb0ac473de94e5ad4075b855 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 17:55:09 +0100 Subject: [PATCH 6/9] Set baseurl so CSS and images resolve on the project-subpath site configure-pages@v5 injects baseurl into _config.yml at repo root by default, but ours lives in docs/, so the injection silently missed and the site was served with domain-absolute /assets/... URLs that 404'd against adzerk.github.io/spec-driven-workshop/. Setting url and baseurl explicitly fixes it without needing the workflow to know where the Jekyll config lives. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/_config.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_config.yml b/docs/_config.yml index 6f1947d..bd1d318 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,5 +1,7 @@ title: Spec-Driven Development Workshop description: A workshop on spec-driven development and lightweight formal methods. +url: "https://adzerk.github.io" +baseurl: "/spec-driven-workshop" remote_theme: mmistakes/minimal-mistakes@4.26.2 minimal_mistakes_skin: default From df6bced6953d455b6c718a357036c90dcf032cd4 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 18:32:48 +0100 Subject: [PATCH 7/9] Hide theme's page title on the guide to avoid duplicate H1 The guide source starts with a H1 of its own, and the theme's single layout also renders page.title as a heading, so the rendered page showed the same title twice. A scoped hide_page_title flag + a conditional style in the custom head include suppresses the theme heading only on pages that already carry an in-content H1. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/_config.yml | 1 + docs/_includes/head/custom.html | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 docs/_includes/head/custom.html diff --git a/docs/_config.yml b/docs/_config.yml index bd1d318..86a0368 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -28,6 +28,7 @@ defaults: values: layout: single title: "Getting Started with Spec-Driven Development" + hide_page_title: true toc: true toc_sticky: true toc_label: "On this page" diff --git a/docs/_includes/head/custom.html b/docs/_includes/head/custom.html new file mode 100644 index 0000000..dd61f64 --- /dev/null +++ b/docs/_includes/head/custom.html @@ -0,0 +1,3 @@ +{% if page.hide_page_title %} + +{% endif %} From 30bf5b5e7bce5b631c427fc2e6ccb2a5a1b33164 Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 18:35:45 +0100 Subject: [PATCH 8/9] Add GitHub repo link to the top nav --- docs/_data/navigation.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml index f50364d..67844cd 100644 --- a/docs/_data/navigation.yml +++ b/docs/_data/navigation.yml @@ -3,3 +3,5 @@ main: url: /guide.html - title: "Reference" url: /reference.html + - title: "GitHub" + url: https://github.com/adzerk/spec-driven-workshop From c33e5d931e9a9bd8957083d5dc2da1a8bca9f84c Mon Sep 17 00:00:00 2001 From: Laurence Pakenham-Smith Date: Fri, 24 Apr 2026 18:37:45 +0100 Subject: [PATCH 9/9] Hide RSS/atom feed from footer and head --- docs/_config.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/_config.yml b/docs/_config.yml index 86a0368..fe59e17 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,6 +5,9 @@ baseurl: "/spec-driven-workshop" remote_theme: mmistakes/minimal-mistakes@4.26.2 minimal_mistakes_skin: default +atom_feed: + hide: true + plugins: - jekyll-optional-front-matter - jekyll-relative-links