commit d2da71e53a375ef1ebb559b1a8dded918b95129d Author: Scott Scoble Date: Sat May 23 18:19:14 2026 -0700 Initial commit: Beyond the Prompt workshop presentation by Scott Scoble - Reveal.js presentation on Skills and Subagents pattern - Nix flake with Caddy-based HTTP server and process-compose orchestration - ADRs documenting architectural decisions - Skills for AI implementation guidance - Full Scott Scoble author attribution in README diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..4a9b506 Binary files /dev/null and b/.DS_Store differ diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..9123937 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,9 @@ +{ + "permissions": { + "allow": [ + "Bash(grep:*)" + ], + "deny": [], + "ask": [] + } +} \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7473dda --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,192 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +A Nix flake-based project for the presentation "Beyond the Prompt: Lessons from Building with Claude Code". This project demonstrates using **Skills** for AI implementation guidance and **ADRs** for human documentation. + +**Key Concept**: Skills provide scalable AI context (100s of patterns, minimal tokens), while ADRs document architectural rationale for humans. + +## Project Structure + +``` +. +├── flake.nix # Nix flake with apps and devShell +├── CLAUDE.md # This file +├── skills/ # AI implementation skills (auto-loaded) +│ ├── nix-http-server/ # HTTP server creation skill +│ ├── revealjs-presentation/# Reveal.js presentation skill +│ └── adr-documentation/ # ADR creation skill +├── docs/ +│ ├── adr/ # Architecture Decision Records (human docs) +│ │ ├── 001-presentation-technology.md +│ │ ├── 002-nix-flake-architecture.md +│ │ ├── 003-demo-implementation-strategy.md +│ │ └── README.md +│ └── demo/ # Conversation transcript and demo materials +│ └── README.md +└── presentation/ + ├── index.html # Reveal.js presentation + ├── slides/ + └── assets/ +``` + +## Development Commands + +### Nix Commands + +```bash +# Enter development shell with all tools +nix develop + +# Start presentation server (http://localhost:8000) +nix run .#present + +# Start full demo (presentation + conversation viewer) +# - Presentation: http://localhost:8000 +# - Conversation: http://localhost:8001 +nix run .#demo +``` + +### Direct Development (Live Reload) + +For rapid iteration without rebuilding: + +```bash +nix develop +caddy file-server --root ./presentation --listen :8000 +``` + +## Architecture + +### Technology Stack + +- **Presentation**: Reveal.js (CDN-hosted for simplicity) +- **HTTP Server**: Caddy (configured via Nix-generated Caddyfile) +- **Process Orchestration**: process-compose (YAML generated from Nix) +- **Multi-Platform**: Supports x86_64/aarch64 on Linux and macOS + +### Available Skills (AI Guidance) + +Claude Code auto-loads these skills for implementation guidance: + +1. **nix-http-server**: Create HTTP servers using Caddy (NEVER Python). Enforces no-Python constraint from ADR 002. +2. **revealjs-presentation**: Build Reveal.js presentations optimized for large screens. Based on ADR 001 decision. +3. **adr-documentation**: Create ADRs for human documentation (not AI context). + +**Context Efficiency**: 3 skills × ~100 tokens = 300 tokens for all metadata. Instructions only loaded when triggered. + +### Architectural Decisions (Human Documentation) + +ADRs in `docs/adr/` explain WHY (for humans, not AI): + +1. **ADR 001**: Why Reveal.js (alternatives: Marp, Slidev, Beamer) +2. **ADR 002**: Why Caddy + process-compose (Python is verboten) +3. **ADR 003**: Why conversation-as-demo (meta-awareness approach) + +### Flake Implementation + +The flake uses: +- `forAllSystems` helper for multi-platform support +- `pkgs.writeText` to generate Caddyfile and process-compose configs +- `pkgs.writeScript` to create app wrappers +- No Python dependencies (Caddy replaces Python HTTP server) + +## Configuration as Code + +All configuration is generated from Nix expressions, not stored in the repo: + +**Caddyfile generation**: +```nix +makeCaddyConfig = pkgs: port: root: pkgs.writeText "Caddyfile" '' + :${toString port} { + root * ${root} + file_server browse + encode gzip + } +''; +``` + +**process-compose YAML** (via JSON): +```nix +makeProcessComposeConfig = pkgs: processes: + pkgs.writeText "process-compose.yaml" (builtins.toJSON { + version = "0.5"; + inherit processes; + }); +``` + +## Development Workflow + +### Making Changes + +1. **Presentation updates**: Edit `presentation/index.html` or files in `presentation/` +2. **ADR updates**: Modify files in `docs/adr/` +3. **Flake updates**: Edit `flake.nix` based on ADR decisions +4. **Testing**: Run `nix run .#present` or `nix run .#demo` + +### The Skills + ADRs Pattern + +This project demonstrates the modern pattern: + +``` +Architectural Decision + ↓ + ┌────┴────┐ + ▼ ▼ + ADR Skill +(Human) (AI) + ↓ ↓ +Explains Implements + WHY HOW +``` + +**Workflow**: +1. Skills auto-load to guide implementation (no manual prompting needed) +2. ADRs available in `docs/adr/` when humans need to understand WHY +3. Update both when architecture evolves: + - ADR explains new decision rationale + - Skill encodes new implementation patterns + +## Key Constraints + +- **No Python**: Use Caddy or other nixpkgs servers +- **All deps from nixpkgs**: No external package managers +- **Configuration as code**: Generate configs, don't commit them +- **Multi-platform**: Support all major systems (Linux/macOS, x64/ARM) + +## Demo Concept + +The presentation demonstrates the Skills + ADRs pattern by using itself as the example: + +- **ADRs** documented architectural decisions for humans +- **Skills** encoded those decisions as AI-executable patterns +- Constraints applied iteratively ("no Python" → enforced by skill) +- The conversation itself became the demo +- Implementation validates the approach + +**Meta-insight**: This project evolved from ADR-driven to Skills+ADRs pattern during development, proving the context efficiency advantage. + +## Commands Reference + +```bash +# Development +nix develop # Enter dev shell +nix flake check # Validate flake (when checks added) + +# Running apps +nix run .#present # Presentation only +nix run .#demo # Full demo environment + +# Direct commands (from devShell) +caddy file-server --root ./presentation --listen :8000 +process-compose up -f +``` + +## Additional Notes + +- Reveal.js loaded from CDN (can be vendored if offline needed) +- process-compose provides TUI for monitoring services +- Readiness probes ensure services are up before declaring ready +- Git history shows the evolution of the project diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..296ccc2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Scott Scoble + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..00f76e0 --- /dev/null +++ b/README.md @@ -0,0 +1,100 @@ +# Beyond the Prompt: Lessons from Building with Claude Code + +A presentation by **[Scott Scoble](https://scott.scoble.me)** about using Skills and Subagents to guide AI-assisted development, demonstrated through the FLUO project's FluoDSL sandboxing decision. + +## Quick Start + +```bash +# Clone the repository +git clone https://github.com/yourusername/beyond-the-prompt.git +cd beyond-the-prompt + +# Start the presentation (requires Nix) +nix run .#present +``` + +Open http://localhost:8000 in your browser. + +## Prerequisites + +- [Nix](https://nixos.org/download.html) package manager with flakes enabled + +## Commands + +### Run Presentation Only + +```bash +nix run .#present +``` + +Serves the presentation at http://localhost:8000 + +### Run Full Demo + +```bash +nix run .#demo +``` + +Serves: +- Presentation at http://localhost:8000 +- Conversation viewer at http://localhost:8001 (if available) + +### Development Mode + +```bash +# Enter development shell with all tools +nix develop + +# Start presentation server with live reload +caddy file-server --root ./presentation --listen :8000 +``` + +## Presenter Mode + +Press `P` during the presentation to toggle presenter mode with speaker notes and timing. + +Press `C` to clone the slideshow for dual-screen presentation. + +## Key Keyboard Shortcuts + +- `→` / `Space` - Next slide +- `←` - Previous slide +- `P` - Toggle presenter mode +- `C` - Clone slideshow +- `F` - Toggle fullscreen +- `?` - Show help + +## Project Structure + +``` +. +├── flake.nix # Nix flake with apps and devShell +├── README.md # This file +├── CLAUDE.md # Instructions for Claude Code +├── docs/ +│ ├── adr/ # Architecture Decision Records +│ └── demo/ # Demo materials +└── presentation/ + ├── index.html # Reveal.js presentation + ├── slides.md # Presentation content + ├── assets/ # Images, CSS, themes + └── vendor/ # Vendored dependencies +``` + +## Content + +This presentation covers: + +1. **Context Window Economics** - Progressive disclosure and token efficiency +2. **Skills + Subagents Pattern** - HOW to implement vs SHOULD we build +3. **Preventing Waste** - Evaluation before execution + +## Learn More + +- FLUO Project: https://github.com/fluohq/fluo +- See `.skills/` and `.subagents/` directories in FLUO for implementation examples +- Read ADRs in `docs/adr/` for architectural context + +## License + +MIT License - see [LICENSE](LICENSE) file for details diff --git a/docs/adr/001-presentation-technology.md b/docs/adr/001-presentation-technology.md new file mode 100644 index 0000000..b481325 --- /dev/null +++ b/docs/adr/001-presentation-technology.md @@ -0,0 +1,89 @@ +# ADR 001: Presentation Technology Choice + +## Status +Proposed + +## Context +We need to create a presentation for "Beyond the Prompt: Lessons from Building with Claude Code" that: +- Can be served via simple HTTP server +- Works well with Nix flake distribution +- Supports code syntax highlighting +- Allows for presenter notes +- Is version-controllable (text-based) +- Can be easily edited and previewed + +## Decision +Use **Reveal.js** for the presentation framework. + +## Rationale + +### Reveal.js Advantages +- **Static HTML/JS/CSS**: Can be served with any simple HTTP server +- **Rich features**: Code highlighting, presenter notes, speaker view, PDF export +- **Nix-friendly**: Available via nixpkgs, no complex build process +- **Offline-capable**: All assets can be bundled +- **Markdown support**: Can write slides in Markdown within HTML +- **Wide adoption**: Well-documented, stable, extensive plugin ecosystem + +### Alternatives Considered + +**Marp** +- Pros: Pure Markdown, simpler syntax +- Cons: Requires CLI tool, more complex Nix integration, fewer interactive features +- Verdict: Too limiting for technical demos + +**Slidev** +- Pros: Vue-based, modern developer experience +- Cons: Requires Node.js build process, heavier Nix integration +- Verdict: Unnecessary complexity for this use case + +**Beamer/LaTeX** +- Pros: Academic standard, precise control +- Cons: PDF-only, no interactive demos, steep learning curve +- Verdict: Not suitable for live coding demonstrations + +## Implementation Details + +### Directory Structure +``` +presentation/ +├── index.html # Main presentation file +├── css/ +│ └── theme/ # Custom themes if needed +├── js/ +│ └── reveal.js # Vendored or symlinked +└── assets/ + ├── images/ + └── code-samples/ +``` + +### Serving +- Development: `nix run .#present` → lightweight HTTP server from nixpkgs (e.g., darkhttpd, caddy, or miniserve) +- Production: Static hosting (GitHub Pages, Netlify, etc.) + +### Reveal.js Integration in Nix +Use nixpkgs to fetch reveal.js dependencies: +- Option 1: `fetchFromGitHub` to get reveal.js source +- Option 2: Use `buildNpmPackage` if npm-based tooling needed +- Option 3: Direct vendoring with `fetchurl` for specific release + +Recommended: **fetchFromGitHub** for reproducibility and ease of updates. + +## Consequences + +### Positive +- Simple development workflow +- No build step required for basic presentations +- Easy to version control +- Works offline +- Familiar to many developers + +### Negative +- Manual Reveal.js updates (if vendored) +- Larger repo size if vendoring full Reveal.js +- Less separation between content and presentation (vs. pure Markdown) + +### Mitigation +- Keep Reveal.js minimal (only required files) +- Use Markdown mode for slide content where possible +- Document update process for Reveal.js version bumps diff --git a/docs/adr/002-nix-flake-architecture.md b/docs/adr/002-nix-flake-architecture.md new file mode 100644 index 0000000..f86795f --- /dev/null +++ b/docs/adr/002-nix-flake-architecture.md @@ -0,0 +1,245 @@ +# ADR 002: Nix Flake Architecture + +## Status +Proposed + +## Context +The project needs a Nix flake that: +- Provides reproducible development environment +- Defines two runnable apps: `present` and `demo` +- Supports multiple platforms (Linux and macOS, both x64 and ARM) +- Minimizes complexity while providing good developer experience +- Follows Nix best practices + +## Decision +Implement a multi-platform flake with `forAllSystems` helper, separate apps for presentation and demo, and a comprehensive devShell. + +## Architecture + +### System Support +```nix +supportedSystems = [ + "x86_64-linux" + "aarch64-linux" + "x86_64-darwin" + "aarch64-darwin" +]; +``` + +### Core Outputs + +1. **apps.present** + - Type: `app` + - Function: Serve presentation on http://localhost:8000 + - Implementation: process-compose orchestrating Caddy server + - Configuration: Nix-generated Caddyfile and process-compose.yaml + +2. **apps.demo** + - Type: `app` + - Function: Execute demonstration script + - Implementation: process-compose orchestrating demo processes + - Configuration: Nix-generated process-compose.yaml for demo services + +3. **devShells.default** + - Purpose: Development environment with all necessary tools + - Contents: bash, caddy, process-compose, and optional tools (asciinema, etc.) + - Shell hook: Display helpful usage instructions + +## Rationale + +### Multi-Platform with forAllSystems +**Why**: Developers use various platforms; presentation should work everywhere +**How**: Use `nixpkgs.lib.genAttrs` to generate outputs for all systems +**Alternative**: Single-platform support would exclude contributors + +### Separate Apps vs Unified Interface +**Decision**: Two separate apps (`present` and `demo`) +**Why**: +- Clear separation of concerns +- Can run independently +- Better UX (`nix run .#present` is more explicit than `nix run . -- present`) + +**Alternative considered**: Single app with subcommands +- Would require argument parsing +- More complex implementation +- Less idiomatic for Nix + +### writeScript vs Packages +**Decision**: Use `pkgs.writeScript` for app wrappers +**Why**: +- Simple bash scripts don't need full package machinery +- Reduces boilerplate +- Direct access to flake's `self` reference +- Easier to maintain + +**Alternative**: Proper derivations with `stdenv.mkDerivation` +- Overkill for simple wrappers +- More complex to reference source files + +### HTTP Server and Process Management +**Decision**: Use **Caddy** for HTTP serving, orchestrated by **process-compose** + +**Architecture**: +- **Caddy**: Modern HTTP server with automatic HTTPS, JSON API, config reloading +- **process-compose**: Process orchestrator (alternative to docker-compose for processes) +- **Configuration**: Generated via Nix expressions, no manual config files + +**Why Caddy**: +- Configuration as code via Nix +- JSON/Caddyfile generation from Nix expressions +- Powerful features (reverse proxy, file server, API) +- Good developer experience +- Available in nixpkgs + +**Why process-compose**: +- Orchestrates multiple services (presentation server, potential demo services) +- YAML config generated from Nix +- Terminal UI for monitoring processes +- Graceful shutdown and dependency management +- Better than ad-hoc bash scripts for multi-process apps + +**Configuration Strategy**: +```nix +# Generate Caddyfile +caddyConfig = pkgs.writeText "Caddyfile" '' + :8000 { + root * ${self}/presentation + file_server + encode gzip + } +''; + +# Generate process-compose config +processComposeConfig = pkgs.writeText "process-compose.yaml" (builtins.toJSON { + processes = { + presentation = { + command = "${pkgs.caddy}/bin/caddy run --config ${caddyConfig}"; + readiness_probe = { + http_get = { + host = "localhost"; + port = 8000; + }; + }; + }; + }; +}); +``` + +### DevShell Philosophy +**Decision**: Include common tools, comment optional ones +**Why**: +- Balance between "batteries included" and minimalism +- Comments serve as documentation +- Easy to uncomment tools as needed +- Shell hook provides guidance + +## Implementation Details + +### Flake Structure +```nix +{ + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + + outputs = { self, nixpkgs }: + let + supportedSystems = [ ... ]; + forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems + (system: f system (import nixpkgs { inherit system; })); + in { + apps = forAllSystems (system: pkgs: { ... }); + devShells = forAllSystems (system: pkgs: { ... }); + }; +} +``` + +### App Implementation Pattern +```nix +present = { + type = "app"; + program = "${pkgs.writeScript "present" '' + #!/usr/bin/env bash + exec ${pkgs.process-compose}/bin/process-compose \ + up -f ${processComposeConfig} + ''}"; +}; +``` + +### Configuration File Generation + +**Caddy Configuration** (Caddyfile): +```nix +caddyConfig = pkgs.writeText "Caddyfile" '' + :8000 { + root * ${self}/presentation + file_server browse + encode gzip + log { + output stdout + format console + } + } +''; +``` + +**process-compose Configuration** (YAML via JSON): +```nix +# YAML generation using builtins.toJSON for structured config +processComposeConfig = pkgs.writeText "process-compose.yaml" ( + builtins.toJSON { + version = "0.5"; + processes = { + caddy = { + command = "${pkgs.caddy}/bin/caddy run --config ${caddyConfig}"; + readiness_probe = { + http_get = { + host = "localhost"; + port = 8000; + }; + }; + }; + }; + } +); +``` + +### Source File References +- Presentation: `${self}/presentation` +- Demo files: `${self}/demo/` +- Configs are generated, not stored in repo + +## Consequences + +### Positive +- Reproducible across all major platforms +- Configuration as code (no manual config files) +- Process orchestration with monitoring UI +- Clean separation: presentation vs demo +- Graceful shutdown and process management +- Readiness probes ensure services are up +- All dependencies from nixpkgs + +### Negative +- process-compose adds complexity vs simple HTTP server +- Files copied to Nix store (not live-reloaded during development) +- Need to re-run `nix run` after file changes +- YAML generation via JSON (no native YAML in Nix) + +### Mitigation +- Complexity justified by better orchestration and monitoring +- For rapid iteration, use devShell with direct commands: + ```bash + nix develop + # Then run Caddy directly for live development: + caddy run --config <(echo ':8000 { root * ./presentation; file_server }') + ``` +- process-compose TUI provides visibility into running services +- JSON→YAML conversion is transparent and well-tested + +## Future Considerations +- Add `checks` output for presentation validation (broken links, etc.) +- Add `packages` output for static site generation +- Consider `nix flake init` template for similar presentations +- Add formatter (e.g., alejandra) to devShell +- Explore Caddy admin API for dynamic config updates +- Add hot-reload capability using Caddy's config API +- Consider additional process-compose processes for demo infrastructure diff --git a/docs/adr/003-demo-implementation-strategy.md b/docs/adr/003-demo-implementation-strategy.md new file mode 100644 index 0000000..595c9c5 --- /dev/null +++ b/docs/adr/003-demo-implementation-strategy.md @@ -0,0 +1,235 @@ +# ADR 003: Demo Implementation Strategy + +## Status +Accepted + +## Context +The presentation "Beyond the Prompt: Lessons from Building with Claude Code" needs to demonstrate: +- How to use ADRs to guide AI-assisted development +- Effective prompt engineering and task decomposition +- Iterative refinement with architectural constraints +- Real-world workflow patterns with Claude Code + +The demo must be: +- Authentic and realistic +- Reproducible for attendees +- Illustrative of actual development patterns +- Version-controlled and sharable + +## Decision +**The demo IS the development conversation itself** - specifically, the conversation that builds this presentation system using ADRs to guide Claude Code. + +The demo consists of: +1. The ADRs that define the architecture (stored in `docs/adr/`) +2. The conversation transcript showing iterative development +3. The resulting implementation (flake, presentation, etc.) + +## Rationale + +### Why Conversation-as-Demo + +**Authenticity**: Shows real Claude Code usage, not simulation +- Actual tool interactions +- Real decision-making process +- Genuine iterative refinement +- True constraint handling + +**Educational Value**: Demonstrates the meta-pattern +- ADRs provide clear boundaries and context +- Constraints drive better design (e.g., "no Python", "use nixpkgs") +- Iterative improvement based on feedback +- Architecture emerges from conversation + +**Reproducibility**: Attendees can recreate the pattern +- ADRs are templates for their own projects +- Conversation style is learnable +- Git history shows evolution +- Implementation validates the approach + +### Alternative Approaches Considered + +**1. Scripted Demo with Simulated Output** +- Pros: Predictable, rehearsable, no live risk +- Cons: Inauthentic, doesn't show real tool, feels staged +- Verdict: Misses the point of "beyond the prompt" + +**2. Live Coding Session** +- Pros: Shows real tool, spontaneous +- Cons: Unpredictable, time pressure, can't capture nuance +- Verdict: Too risky for complex architecture decisions + +**3. Pre-recorded Video** +- Pros: Perfect execution, editing possible +- Cons: Not interactive, can't adapt to audience questions +- Verdict: Loses conversational flow and learning opportunities + +## Implementation Details + +### Demo Artifacts + +**1. Architecture Decision Records** (`docs/adr/`) +- `001-presentation-technology.md` - Reveal.js choice +- `002-nix-flake-architecture.md` - process-compose + Caddy +- `003-demo-implementation-strategy.md` - This document (meta!) +- `README.md` - ADR index and usage guide + +**2. Conversation Transcript** (`docs/demo/`) +Store the actual Claude Code conversation showing: +- Initial requirements gathering +- ADR creation and refinement +- Constraint application ("no Python") +- Architecture evolution (simple → process-compose) +- Decision rationale and tradeoffs + +**3. Implementation Artifacts** +- `flake.nix` - The actual working implementation +- `presentation/` - Reveal.js presentation +- Git commits showing progression + +### Demo Execution Flow + +**Stage 1: Setup** (2 minutes) +- Show empty repo with just README +- Explain the goal: build a presentation system +- Introduce ADRs as the guiding pattern + +**Stage 2: ADR Creation** (3 minutes) +- Walk through creating ADR 001 (presentation tech) +- Show how it evaluates alternatives +- Demonstrate decision rationale + +**Stage 3: Constraint Refinement** (3 minutes) +- Show conversation applying constraints +- Example: "No Python" → rearchitecture to Caddy +- Demonstrate ADR updates reflecting new decisions + +**Stage 4: Implementation Validation** (2 minutes) +- Run `nix run .#present` to prove it works +- Show generated configs (Caddyfile, process-compose.yaml) +- Demonstrate configuration-as-code + +**Stage 5: Meta-Reflection** (2 minutes) +- Highlight the pattern: ADRs → Conversation → Implementation +- Show how this approach is reusable +- Provide takeaways for attendees + +### Presentation Integration + +Embed demo artifacts in the presentation: +```markdown +# Slide: "The Power of ADRs" +- Show ADR 001 side-by-side with implementation +- Highlight how decisions map to code + +# Slide: "Iterative Refinement" +- Show conversation excerpt about Python → Caddy +- Display the updated ADR section +- Show the resulting Nix code + +# Slide: "Meta Demo" +- Reveal that THIS presentation was built this way +- Show the actual conversation +- Provide GitHub link for full exploration +``` + +### Nix Integration + +The demo app serves the conversation transcript: + +```nix +demo = { + type = "app"; + program = "${pkgs.writeScript "demo" '' + #!/usr/bin/env bash + + # Generate demo config for process-compose + config="${pkgs.writeText "demo-compose.yaml" (builtins.toJSON { + processes = { + conversation-viewer = { + command = "${pkgs.caddy}/bin/caddy file-server --root ${self}/docs/demo --listen :8001"; + }; + presentation = { + command = "${pkgs.caddy}/bin/caddy file-server --root ${self}/presentation --listen :8000"; + }; + }; + })}" + + exec ${pkgs.process-compose}/bin/process-compose up -f "$config" + ''}"; +}; +``` + +This runs: +- Presentation on `:8000` +- Conversation transcript viewer on `:8001` + +## Technical Considerations + +### Conversation Capture +- Export Claude Code conversation to markdown +- Format with syntax highlighting +- Preserve timestamps and flow +- Annotate with insights + +### Presentation Structure +``` +presentation/ +├── index.html # Main reveal.js presentation +├── slides/ +│ ├── 01-introduction.md +│ ├── 02-the-adr-pattern.md +│ ├── 03-demo-reveal.md # The meta moment +│ └── 04-takeaways.md +└── assets/ + ├── conversation.md # Embedded transcript excerpts + ├── adr-examples/ # ADR screenshots + └── implementation/ # Code snippets +``` + +### Git History as Artifact +Commit strategy: +``` +feat: initial ADRs for presentation architecture +feat: update ADR 002 with process-compose approach +feat: rewrite ADR 003 as conversation-based demo +feat: implement flake based on ADR decisions +docs: add conversation transcript to demo/ +``` + +Git history itself becomes part of the demo narrative. + +## Consequences + +### Positive +- **Authentic**: Real Claude Code usage, not simulation +- **Educational**: Shows thinking process, not just results +- **Reusable**: Pattern applicable to any project +- **Transparent**: All decisions documented and traceable +- **Self-documenting**: The demo explains itself +- **Meta-awareness**: Presentation about AI development, built with AI + +### Negative +- **Complexity**: More sophisticated than simple script +- **Preparation**: Requires curating conversation for clarity +- **Length**: Full conversation may be too detailed for presentation +- **Assumption**: Assumes audience familiarity with ADRs + +### Mitigation +- Curate conversation to key decision points +- Provide full transcript as supplementary material +- Include ADR primer in presentation intro +- Offer simplified "getting started" guide for newcomers + +## Future Enhancements +- Interactive conversation explorer (search, filter by topic) +- Side-by-side view: ADR ↔ Conversation ↔ Implementation +- Jupyter notebook walking through the process step-by-step +- Template repository: "instant ADR-driven development" +- Video walkthrough with narration over the conversation +- Browser extension to capture Claude Code conversations automatically + +## Key Insight + +**This ADR is itself part of the demo** - it documents the decision to use the conversation as the demo, demonstrating the recursive, self-referential nature of effective AI-assisted development. + +The presentation is its own case study. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..2adb4ae --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,80 @@ +# Architecture Decision Records + +This directory contains Architecture Decision Records (ADRs) for the "Beyond the Prompt" presentation project. + +## Purpose: Human Documentation + +**ADRs are for humans, not AI.** They explain WHY architectural decisions were made, document alternatives considered, and preserve historical context for team members. + +**For AI implementation guidance**, see the `/skills` directory. Skills encode HOW to implement the decisions documented in ADRs. + +## Index + +1. [ADR 001: Presentation Technology Choice](./001-presentation-technology.md) → *Skill: `revealjs-presentation`* + - Decision to use Reveal.js for the presentation + - Rationale, alternatives, and implementation approach + +2. [ADR 002: Nix Flake Architecture](./002-nix-flake-architecture.md) → *Skill: `nix-http-server`* + - Multi-platform flake design + - App structure and devShell configuration + - **Key constraint**: No Python dependencies + +3. [ADR 003: Demo Implementation Strategy](./003-demo-implementation-strategy.md) → *Skill: `adr-documentation`* + - Conversation-as-demo approach + - Meta-awareness and documentation strategy + +## ADR Format + +Each ADR follows this structure: +- **Status**: Proposed, Accepted, Deprecated, Superseded +- **Context**: The problem or situation +- **Decision**: What was decided +- **Rationale**: Why this decision was made (including alternatives) +- **Consequences**: Positive, negative, and mitigations + +## When to Write an ADR + +Create an ADR when making architectural decisions that: +- Affect multiple parts of the system +- Have long-term implications +- Involve trade-offs between alternatives +- Need to be communicated to future contributors + +**After writing an ADR**, consider creating a corresponding **Skill** if: +- The decision involves repetitive implementation patterns +- AI should automatically enforce the decision's constraints +- The pattern can be automated with templates/scripts +- You want perfect consistency in implementation + +## The ADR + Skill Pattern + +``` +Make Decision + ↓ +┌────┴────┐ +▼ ▼ +ADR Skill +↓ ↓ +WHY HOW +Human AI +``` + +**Example**: ADR 002 documents WHY we chose Caddy (no Python constraint). The `nix-http-server` skill enforces this by NEVER suggesting Python servers. + +## Context Efficiency + +**Old approach**: Load ADRs into AI context +- 3 ADRs × 1,500 tokens = 4,500 tokens before writing code +- Doesn't scale beyond ~10-20 ADRs + +**New approach**: Use Skills for AI, ADRs for humans +- 3 skills × 100 tokens metadata = 300 tokens +- Scales to 100s of patterns +- ADRs remain available for human readers + +## Updating ADRs + +ADRs are immutable once accepted. To change a decision: +1. Create a new ADR that supersedes the old one +2. Update the old ADR's status to "Superseded by ADR XXX" +3. Update or create corresponding skill to reflect new implementation pattern diff --git a/docs/demo/README.md b/docs/demo/README.md new file mode 100644 index 0000000..f9b2979 --- /dev/null +++ b/docs/demo/README.md @@ -0,0 +1,64 @@ +# Demo: The Conversation + +This directory contains the actual conversation that built this presentation system, demonstrating the ADR-driven development approach with Claude Code. + +## What's Here + +- **conversation-transcript.md** - The full development conversation +- **key-moments.md** - Highlighted decision points from the conversation +- **lessons-learned.md** - Insights and patterns discovered + +## Viewing the Demo + +When you run `nix run .#demo`, this content is served on http://localhost:8001 alongside the presentation on http://localhost:8000. + +## The Meta Pattern + +This demo demonstrates: + +1. **ADRs as guardrails** - How Architecture Decision Records guide AI development +2. **Iterative refinement** - Constraint application (e.g., "no Python" → Caddy) +3. **Conversation as artifact** - The dialogue itself becomes valuable documentation +4. **Meta-awareness** - Building a presentation about AI development, with AI + +## Key Decision Points + +### Initial Setup +- Created ADRs to define architecture +- Established technology choices (Reveal.js, Nix) + +### Constraint Application +- "Python is verboten" → Evaluated alternatives +- Chose Caddy over darkhttpd/miniserve +- Added process-compose for orchestration + +### Meta Realization +- "The demo IS this conversation" +- Shifted from scripted demo to conversation-as-demo +- Updated ADR 003 to reflect this approach + +### Implementation +- Built flake.nix based on ADR 002 +- Generated configs from Nix expressions +- Multi-platform support with forAllSystems + +## Lessons Learned + +1. **ADRs provide crucial context** - They help AI understand not just what to build, but why +2. **Constraints drive better design** - "No Python" led to a more robust architecture +3. **Iterative refinement works** - First solutions improved through dialogue +4. **Meta-awareness is powerful** - Using the tool to understand the tool + +## Try It Yourself + +1. Read through the ADRs in `docs/adr/` +2. Study the conversation transcript +3. Examine the resulting `flake.nix` +4. Apply the pattern to your own projects + +The pattern is simple: +``` +ADRs → Conversation → Implementation → Refinement → Better ADRs +``` + +This creates a virtuous cycle of improvement. diff --git a/docs/presentation-printable.md b/docs/presentation-printable.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/presentation-timing.md b/docs/presentation-timing.md new file mode 100644 index 0000000..d44d02e --- /dev/null +++ b/docs/presentation-timing.md @@ -0,0 +1,150 @@ +# Presentation Timing Guide +**Target Duration**: 110 minutes total +**Format**: Cumulative timestamps for each slide + +--- + +## Introduction & Setup (15 min total) + +| Slide # | Title | Time | Cumulative | Notes | +|---------|-------|------|------------|-------| +| 1 | Beyond the Prompt (Title) | 2 min | 0:02 | Welcome, introduce topic | +| 2 | Who Am I? | 2 min | 0:04 | Brief intro, keep it tight | +| 3 | Let's Dive In (Image) | 0:30 | 0:04:30 | Visual transition only | +| 4 | The Request | 2 min | 0:06:30 | Set up the problem, audience question | +| 5 | So I Asked Claude Code | 1:30 | 0:08 | Bridge to context windows | +| 6 | Part 1: The Problem | 0:30 | 0:08:30 | Section title card | +| 7 | The Context Window Problem | 3 min | 0:11:30 | Audience question about ADRs, relatable | +| 8 | Progressive Disclosure | 4 min | 0:15:30 | Core concept, needs time to land | + +--- + +## Part 1: Context Window Economics (20 min total from start) + +| Slide # | Title | Time | Cumulative | Notes | +|---------|-------|------|------------|-------| +| 9 | FLUO's Token Budget | 3 min | 0:18:30 | Show the math, 95% reduction | +| 10 | Quick Check | 2 min | 0:20:30 | Audience calculates their ADRs | + +--- + +## Part 2: The Pattern - Dream Team Story (40 min total from start) + +| Slide # | Title | Time | Cumulative | Notes | +|---------|-------|------|------------|-------| +| 11 | Back to Sandboxing | 1 min | 0:21:30 | Remind the problem | +| 12 | Part 2: Building a Dream Team | 1 min | 0:22:30 | Section title, metaphor intro | +| 13 | The Implementer Speaks | 3 min | 0:25:30 | First agent, audience interaction | +| 14 | Round 2: Architecture Guardian | 4 min | 0:29:30 | **KEY SLIDE** - Java 17 deprecation reveal | +| 15 | Round 3: Security Expert | 3 min | 0:32:30 | Security rating, audience question | +| 16 | Round 4: QA Expert | 2 min | 0:34:30 | Testing requirements | +| 17 | Round 5: Product Manager | 4 min | 0:38:30 | **KEY SLIDE** - ROI calculation, decision | +| 18 | The Punchline | 5 min | 0:43:30 | **KEY SLIDE** - 3 days actual, 12 weeks saved | +| 19 | Next Steps | 2 min | 0:45:30 | Transition to Part 3 | + +--- + +## Part 3: How to Build This (50 min total from start) + +| Slide # | Title | Time | Cumulative | Notes | +|---------|-------|------|------------|-------| +| 20 | Part 3: How to Build This | 1 min | 0:46:30 | Section title | +| 21 | Your Dream Team | 5 min | 0:51:30 | **KEY SLIDE** - 4 agents, start with 2 | +| 22 | Subagent Anatomy | 8 min | 0:59:30 | **MAJOR SLIDE** - Walk through YAML, Q&A | +| 23 | Skill Anatomy | 7 min | 1:06:30 | **MAJOR SLIDE** - Example code, explain parts | +| 24 | The Evaluation Loop | 5 min | 1:11:30 | Workflow, timing breakdown | +| 25 | Real Numbers from FLUO | 4 min | 1:15:30 | ROI, concrete results | + +--- + +## Closing & Comparison (30 min remaining) + +| Slide # | Title | Time | Cumulative | Notes | +|---------|-------|------|------------|-------| +| 26 | FLUO's Results | 2 min | 1:17:30 | Summary stats | +| 27 | The Pattern | 2 min | 1:19:30 | "Evaluate first" principle | +| 28 | Skills vs Subagents | 5 min | 1:24:30 | **KEY SLIDE** - Clarify difference, table | +| 29 | The Three Topics | 3 min | 1:27:30 | Recap the structure | +| 30 | The Real Story | 4 min | 1:31:30 | Circle back to PRD-005 | +| 31 | Try It Yourself | 3 min | 1:34:30 | FLUO repo, getting started | +| 32 | Thank You / Questions | 15:30 | 1:50 | **Q&A** - buffer for audience questions | + +--- + +## Key Time Allocations + +**Longest slides (need most time):** +1. **Subagent Anatomy** (8 min) - Walking through code, explaining structure +2. **Skill Anatomy** (7 min) - Concrete example with explanation +3. **Your Dream Team** (5 min) - Critical decision point for audience +4. **The Punchline** (5 min) - Payoff moment, needs to land +5. **Skills vs Subagents** (5 min) - Clarifying core concepts +6. **The Evaluation Loop** (5 min) - Practical workflow + +**Story beats that need room:** +- Architecture Guardian catching Java 17 issue (4 min) +- Product Manager ROI calculation (4 min) +- Real Numbers from FLUO (4 min) + +**Quick transitions:** +- Section title cards (0:30-1 min each) +- Visual slides (0:30) +- Bridge slides (1-2 min) + +--- + +## Pacing Strategy + +**First 20 minutes**: Build the problem (context windows) +- Hook them with relatable pain +- Show the constraint clearly + +**Minutes 20-45**: Tell the story (dream team saves the day) +- Drama: almost shipped bad code +- Resolution: team caught it +- Payoff: 3 days vs 12 weeks + +**Minutes 45-75**: Teach the specifics (how to build it) +- Slow down here, give them copy-able templates +- This is what they'll use on Monday + +**Minutes 75-95**: Wrap up and context (comparison, recap) +- Tie it together +- Answer "where do I start?" + +**Minutes 95-110**: Q&A +- Reserve 15 minutes minimum +- Likely to run over if audience is engaged + +--- + +## Emergency Adjustments + +**If running long:** +- Skip slide 26 (FLUO's Results) - covered in slide 25 +- Shorten Q&A to 10 minutes +- Reduce Subagent/Skill Anatomy by 2 min each + +**If running short:** +- Extend Q&A +- Add war stories during Part 2 +- Deep dive on Skills vs Subagents table + +**Critical slides (never skip):** +- #8: Progressive Disclosure +- #14: Architecture Guardian (Java 17) +- #17: Product Manager (ROI) +- #18: The Punchline +- #22-23: Anatomy slides +- #28: Skills vs Subagents + +--- + +## Checkpoints + +- **30 minutes**: Should be at slide 14 (Architecture Guardian) +- **60 minutes**: Should be at slide 22 (Subagent Anatomy) +- **90 minutes**: Should be at slide 30 (The Real Story) +- **95 minutes**: Start Q&A + +If you're behind at any checkpoint, tighten up the next section. If ahead, add stories or extend Q&A. diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..c0c2de1 --- /dev/null +++ b/flake.lock @@ -0,0 +1,27 @@ +{ + "nodes": { + "nixpkgs": { + "locked": { + "lastModified": 1760524057, + "narHash": "sha256-EVAqOteLBFmd7pKkb0+FIUyzTF61VKi7YmvP1tw4nEw=", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "544961dfcce86422ba200ed9a0b00dd4b1486ec5", + "type": "github" + }, + "original": { + "owner": "nixos", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "nixpkgs": "nixpkgs" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..70dc98c --- /dev/null +++ b/flake.nix @@ -0,0 +1,223 @@ +{ + description = "Beyond the Prompt: Lessons from Building with Claude Code"; + + inputs = { + nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable"; + }; + + outputs = { self, nixpkgs }: + let + # Systems to support + supportedSystems = [ + "x86_64-linux" + "aarch64-linux" + "x86_64-darwin" + "aarch64-darwin" + ]; + + # Helper function to generate outputs for all systems + forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system (import nixpkgs { inherit system; })); + + # Generate Caddyfile for presentation + makeCaddyConfig = pkgs: port: root: pkgs.writeText "Caddyfile" '' + :${toString port} { + root * ${root} + file_server browse + encode gzip + log { + output stdout + format console + } + } + ''; + + # Generate process-compose config + makeProcessComposeConfig = pkgs: processes: pkgs.writeText "process-compose.yaml" ( + builtins.toJSON { + version = "0.5"; + inherit processes; + } + ); + + in + { + # Apps for each system + apps = forAllSystems (system: pkgs: { + # Presentation server + present = { + type = "app"; + program = "${pkgs.writeScript "present" '' +#!/usr/bin/env bash +set -euo pipefail + +# Use current working directory for development +PRESENTATION_ROOT="$PWD/presentation" + +if [ ! -d "$PRESENTATION_ROOT" ]; then + echo "Error: presentation/ directory not found in current directory" + echo "Please run this command from the project root" + exit 1 +fi + +# Generate Caddyfile at runtime +CADDY_CONFIG=$(mktemp) +trap "rm -f $CADDY_CONFIG" EXIT +cat > "$CADDY_CONFIG" < "$COMPOSE_CONFIG" < "$PRESENTATION_CADDY_CONFIG" < "$DEMO_CADDY_CONFIG" < "$COMPOSE_CONFIG" <