WalksWithASwagger · WalksWithASwagger · May 3, 2026
diff --git a/.github/ISSUE_TEMPLATE/roadmap-feature.md b/.github/ISSUE_TEMPLATE/roadmap-feature.md
@@ -0,0 +1,41 @@
+---
+name: Roadmap feature
+about: Add or refine feature work that should be tracked from the roadmap into Linear and GitHub.
+title: ""
+labels: ["kind:feature", "eval:required"]
+assignees: ""
+---
+
+## Summary
+
+Describe the user-facing or delivery outcome in one paragraph.
+
+## Roadmap
+
+- Roadmap ID:
+- Phase:
+- Linear issue:
+
+## Acceptance Criteria
+
+- [ ]
+- [ ]
+- [ ]
+
+## Eval Commands
+
+- [ ] `npm run eval`
+
+## Tests
+
+- [ ]
+- [ ]
+
+## Relevant Paths
+
+- [ ]
+
+## Definition Of Done
+
+- [ ]
+- [ ]
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,25 @@
+## Summary
+
+## Tracking
+
+- GitHub issue:
+- Linear issue:
+- Roadmap ID:
+
+## What Changed
+
+- 
+
+## Eval
+
+- [ ] `npm run eval`
+- [ ] Manual checks listed in the issue are covered
+
+## Docs And Handoff
+
+- [ ] Updated roadmap or session handoff docs if scope or blockers changed
+- [ ] Added notes reviewers need in the PR body
+
+## Risks
+
+- 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  eval:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run eval suite
+        run: npm run eval
diff --git a/.github/workflows/roadmap-sync.yml b/.github/workflows/roadmap-sync.yml
@@ -0,0 +1,43 @@
+name: Roadmap Sync
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "ops/roadmap/**"
+      - "scripts/lib/roadmap.mjs"
+      - "scripts/sync-roadmap-issues.mjs"
+      - ".github/workflows/roadmap-sync.yml"
+  workflow_dispatch:
+    inputs:
+      roadmap_id:
+        description: "Optional roadmap item id to sync"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Validate roadmap registry
+        run: npm run check:roadmap
+
+      - name: Sync roadmap issues
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          ROADMAP_ID: ${{ inputs.roadmap_id }}
+        run: node scripts/sync-roadmap-issues.mjs --write
diff --git a/SESSION-HANDOFF.md b/SESSION-HANDOFF.md
@@ -226,3 +226,41 @@ Continuing from these commits. Documentation lands first (this entry +
 [`docs/PROJECT-ROADMAP.md`](./docs/PROJECT-ROADMAP.md)). Then the eight remaining
 issues — see `docs/PROJECT-ROADMAP.md#portal-phase` for the running ledger of what
 shipped and what's still blocked.
+
+---
+
+## Linear + Agentic Pipeline Setup — May 3, 2026
+
+Linear project seeded: **Punk Rock AI Portal** in team `Bc-ai`.
+
+Repo-side automation:
+- Backlog registry: `ops/roadmap/features.json`
+- Operating guide: `docs/LINEAR-GITHUB-PIPELINE.md`
+- PR gate: `.github/workflows/ci.yml` running `npm run eval`
+- Roadmap issue sync: `.github/workflows/roadmap-sync.yml`
+- Issue template: `.github/ISSUE_TEMPLATE/roadmap-feature.md`
+- PR template: `.github/pull_request_template.md`
+
+Linear issues created:
+
+| Linear | GitHub | State | Notes |
+|--------|--------|-------|-------|
+| `BC-8` | `#8` | Backlog | Cloudflare Pages project and staging URL |
+| `BC-9` | `#9` | In Progress | Taste Audit / Cutting Room Floor |
+| `BC-10` | `#10` | In Progress | Name What You See |
+| `BC-11` | `#11` | Todo + `status:blocked` | Audio sync; GitHub issue is already closed as completed, external audio/R2 work remains tracked as blocker context |
+| `BC-12` | `#12` | In Progress | `/library` searchable; GitHub issue is already closed as completed |
+| `BC-13` | `#13` | Todo + `status:blocked` | Pattern Finder LLM; GitHub issue is already closed as completed, API/deploy credentials remain blocked |
+| `BC-14` | `#14` | Todo + `status:blocked` | Release Day portal; GitHub issue is already closed as completed, Notion/deploy credentials remain blocked |
+| `BC-15` | `#15` | In Progress | `/posse` audience map; GitHub issue is already closed as completed |
+| `BC-16` | `#16` | In Progress | Decisions log; GitHub issue is already closed as completed |
+
+Verification:
+- `npm run eval` passes locally.
+- GitHub issues `#8` through `#16` have roadmap bodies with Linear links.
+- Linear labels were created for area, kind, phase, priority, blocked status, and eval requirements.
+
+Still external / account-level:
+- Enable Linear's GitHub integration in the Linear UI for `WalksWithASwagger/cmvan-keynote`.
+- Re-authenticate local `gh`; current local token is invalid.
+- Provide Cloudflare, Anthropic, Notion, and ElevenLabs credentials to unblock deployed worker/audio work.
diff --git a/docs/LINEAR-GITHUB-PIPELINE.md b/docs/LINEAR-GITHUB-PIPELINE.md
@@ -0,0 +1,62 @@
+# Linear + GitHub delivery pipeline
+
+This repo now has a machine-readable backlog at [`ops/roadmap/features.json`](../ops/roadmap/features.json). The narrative roadmap in [`docs/PROJECT-ROADMAP.md`](./PROJECT-ROADMAP.md) remains the human-facing source; the JSON file is the queue that automation reads.
+
+Linear project: [Punk Rock AI Portal](https://linear.app/bc-ai/project/punk-rock-ai-portal-e9aec6edd886), team `Bc-ai`.
+
+## What is automated
+
+- **Roadmap Sync**: [`.github/workflows/roadmap-sync.yml`](../.github/workflows/roadmap-sync.yml) syncs backlog items into GitHub issues whenever the roadmap registry changes on `main`, or on manual dispatch.
+- **Issue bodies**: `scripts/sync-roadmap-issues.mjs` renders acceptance criteria, eval commands, tests, blockers, and relevant paths into each issue so Linear mirrors complete implementation context.
+- **PR gate**: [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) runs `npm run eval` on every PR and push to `main`.
+- **Eval surface**: `npm run eval` validates the roadmap registry, site data contracts, JavaScript syntax, and the static site contract test suite.
+- **Linear seed**: Linear project issues `BC-8` through `BC-16` have been created with labels, priorities, states, and links back to the GitHub issue numbers already referenced by the roadmap.
+
+## Seeded Linear Work
+
+| Linear | GitHub | Status | Title |
+|--------|--------|--------|-------|
+| [BC-8](https://linear.app/bc-ai/issue/BC-8/cloudflare-pages-project-and-staging-url) | [#8](https://github.com/WalksWithASwagger/cmvan-keynote/issues/8) | Backlog | Cloudflare Pages project and staging URL |
+| [BC-9](https://linear.app/bc-ai/issue/BC-9/taste-audit-cutting-room-floor) | [#9](https://github.com/WalksWithASwagger/cmvan-keynote/issues/9) | In Progress | Taste Audit / Cutting Room Floor |
+| [BC-10](https://linear.app/bc-ai/issue/BC-10/name-what-you-see) | [#10](https://github.com/WalksWithASwagger/cmvan-keynote/issues/10) | In Progress | Name What You See |
+| [BC-11](https://linear.app/bc-ai/issue/BC-11/audio-sync) | [#11](https://github.com/WalksWithASwagger/cmvan-keynote/issues/11) | Todo, blocked | Audio sync |
+| [BC-12](https://linear.app/bc-ai/issue/BC-12/library-searchable) | [#12](https://github.com/WalksWithASwagger/cmvan-keynote/issues/12) | In Progress | /library searchable |
+| [BC-13](https://linear.app/bc-ai/issue/BC-13/pattern-finder-llm) | [#13](https://github.com/WalksWithASwagger/cmvan-keynote/issues/13) | Todo, blocked | Pattern Finder LLM |
+| [BC-14](https://linear.app/bc-ai/issue/BC-14/release-day-portal) | [#14](https://github.com/WalksWithASwagger/cmvan-keynote/issues/14) | Todo, blocked | Release Day portal |
+| [BC-15](https://linear.app/bc-ai/issue/BC-15/posse-audience-map) | [#15](https://github.com/WalksWithASwagger/cmvan-keynote/issues/15) | In Progress | /posse audience map |
+| [BC-16](https://linear.app/bc-ai/issue/BC-16/decisions-log) | [#16](https://github.com/WalksWithASwagger/cmvan-keynote/issues/16) | In Progress | Decisions log |
+
+## One-time setup outside the repo
+
+1. In Linear, connect the GitHub integration to `WalksWithASwagger/cmvan-keynote`.
+2. Enable PR, commit, and review linking in Linear so branch and PR activity stays attached to the same work item.
+3. If you enable GitHub issue import later, map imported issues to the existing `BC-8` through `BC-16` work instead of creating duplicates.
+4. In GitHub, enable Actions for this repository if they are not already enabled.
+5. Re-authenticate local GitHub CLI access if you want to run sync commands from this machine. Right now `gh auth status` reports an invalid token.
+
+## Working loop
+
+1. Add or refine a backlog item in [`ops/roadmap/features.json`](../ops/roadmap/features.json).
+2. Merge that change to `main` or dispatch `Roadmap Sync` manually.
+3. Update or create the matching Linear issue in the `Punk Rock AI Portal` project.
+4. Branch from the synced work item. Prefer the Linear issue key if one exists; otherwise use a `codex/issue-<n>-...` branch.
+5. Implement the change, run `npm run eval`, and open a PR with the repo template.
+6. When the PR lands, update [`docs/PROJECT-ROADMAP.md`](./PROJECT-ROADMAP.md) and [`SESSION-HANDOFF.md`](../SESSION-HANDOFF.md) if the change altered scope, status, or blockers.
+
+## Commands
+
+```sh
+npm run check:roadmap
+npm run sync:github:dry
+npm run sync:github
+npm run eval
+```
+
+`npm run sync:github` needs `GITHUB_TOKEN`. The GitHub Action already provides that token automatically for the repo workflow.
+
+## Current external blockers
+
+- Local `gh` authentication is invalid on this machine.
+- No Linear CLI or local Linear API token is configured.
+- The Linear plugin is connected in Codex and was used to seed the project, but Linear's account-level GitHub integration still has to be enabled in the Linear UI.
+- Cloudflare, Anthropic, ElevenLabs, and Notion credentials are still required for the blocked roadmap items.
diff --git a/docs/PROJECT-ROADMAP.md b/docs/PROJECT-ROADMAP.md
@@ -106,6 +106,8 @@ https://github.com/WalksWithASwagger/kk-kb/pull/new/chore/cmvan-2026-creative-mo
 
 The interactive learning portal that turns the talk into a working set of widgets. Vanilla HTML/CSS/JS, zero runtime deps. Tracked as epic [#1](https://github.com/WalksWithASwagger/cmvan-keynote/issues/1). Dev onboarding lives at [`site/README.md`](../site/README.md).
 
+Machine-readable delivery queue: [`ops/roadmap/features.json`](../ops/roadmap/features.json). Linear/GitHub operating model: [`docs/LINEAR-GITHUB-PIPELINE.md`](./LINEAR-GITHUB-PIPELINE.md). Linear project: [Punk Rock AI Portal](https://linear.app/bc-ai/project/punk-rock-ai-portal-e9aec6edd886), seeded as `BC-8` through `BC-16`.
+
 ### Phase 1 — Foundation + four widgets (shipped)
 
 | Issue | Title | Commit | Notes |