TheModernSoftware NotebookLM

Overview

Run an agent-first workflow where Codex is the controller. Crawl weekly course materials from themodernsoftware.dev, ingest them into NotebookLM, and produce deep-study outputs without requiring a custom standalone agent service.

The workflow is deterministic through state files and templates:

• Use templates/course.yaml and templates/weeks.json as the single source of run state.
• Use agent-browser for page crawling and link extraction.
• Use notebooklm for source ingestion and output generation.

Workflow

Step 0: Initialize runtime workspace

Create a runtime folder and copy templates:

./themodernsoftware-notebooklm/scripts/init-workspace.sh ./runtime

This creates:

• ./runtime/course.yaml
• ./runtime/weeks.json
• ./runtime/prompts/*.prompt.md

Step 1: Preflight checks

Verify required tools before crawling:

agent-browser --help
notebooklm status --json

If notebooklm status --json fails, run notebooklm login.

Step 2: Crawl weekly materials (Codex-controlled)

Open https://themodernsoftware.dev/ with agent-browser and recursively discover week pages.

For each week, extract and classify links into:

• syllabus
• ppt
• reference

Persist each discovered week entry into weeks.json with status: "discovered".

Use crawl and classification rules from references/crawl-rules.md.

Step 3: Ingest into NotebookLM

For each status: discovered week:

1. Ensure notebook exists (from course.yaml.notebook_id; create once if empty).
2. Add all URLs/files for the week to NotebookLM sources.
3. Wait for source processing.
4. Write source_ids back into weeks.json.
5. Move status to ingested.

Use generation behavior and retries from references/notebooklm-deep-mode.md.

Step 4: Generate deep outputs

For each status: ingested week:

1. Generate bilingual lesson plan using prompts/lesson-plan.prompt.md.
2. Generate bilingual lecture notes using prompts/lecture-notes.prompt.md.
3. Generate video overview task using prompts/video.prompt.md.
4. Wait for video artifact completion.
5. Download video to local output path.
6. Update week status:
   • drafted after document outputs
   • video_pending while video is generating/downloading
   • completed only when all required artifacts exist

Step 5: Failure policy

Apply strict policy from references/failure-handling.md:

• If themodernsoftware.dev is unreachable: fail the current run immediately.
• No automatic fallback source.
• Keep failure reason in weeks.json.error for the affected week/run.

Output Contract

Each completed week must include:

• lesson_plan_path
• lecture_notes_path
• video_artifact_id
• video_local_path
• status: completed

Do not mark completed if video generation is unfinished.

Resources

• references/crawl-rules.md: URL discovery and week classification rules.
• references/notebooklm-deep-mode.md: source ingestion, output generation, language and quality requirements.
• references/failure-handling.md: stop/retry/error recording policy.
• references/execution-checklist.md: runbook checklist.
• templates/course.yaml: runtime config template.
• templates/weeks.json: runtime state template.
• templates/weeks.schema.json: structure contract for state validation.
• templates/prompts/*.prompt.md: prompt templates.
• scripts/init-workspace.sh: initialize runtime workspace.
• scripts/verify-week-state.sh: validate weeks.json structure.

Common mistakes

• Running generation before source processing finishes.
• Marking week as completed before video download succeeds.
• Losing state by not persisting source_ids and artifact IDs.
• Mixing unrelated links into week assets.