# Agentic Frontend, CMS, and Design Orchestration Specification ## Purpose This specification defines the target architecture, roles, handoffs, operational contracts, and implementation guidance for an agentic web development platform centered on Claude Code, NotebookLM, Obsidian GitReport, GitHub, Penpot, Stitch, EmDash, the CSA artifact pipeline, and the ADW development pipeline.[cite:17][cite:47][cite:55][cite:100][cite:105][cite:111][cite:116] The platform is intended to support scalable CMS development, advanced frontend implementation, interactive component delivery, architecture communication, and AI-assisted high-end design workflows while preserving traceability from issue intake through delivery and value communication.[cite:17][cite:43][cite:47][cite:105][cite:111][cite:120] The architecture assumes Claude Code is the primary execution environment, GitHub is the canonical source for repositories, branches, issues, pull requests, and review workflows, NotebookLM is the research and specification memory layer, GitReport is the DevOps system of record, Penpot is the approved design system registry, Stitch is the rapid design ideation layer, EmDash is the secure AI-native CMS and content operations platform, CSA is the artifact communication pipeline, and ADW is the issue-driven agentic development workflow pipeline.[cite:17][cite:47][cite:55][cite:100][cite:105][cite:111][cite:116] This document formalizes the handoff model so each system has one authoritative responsibility and each pipeline has a clearly bounded role in planning, building, reviewing, delivering, and communicating work.[cite:43][cite:47][cite:100][cite:111][cite:120] ## Architecture principles The platform is governed by seven principles: - Single authoritative source per artifact domain: research in NotebookLM, repositories and issue/PR lifecycle in GitHub, operational truth in GitReport, approved design in Penpot, implementation in code repositories, content structures in EmDash, and communication artifacts in CSA.[cite:47][cite:55][cite:100][cite:105][cite:111][cite:115] - Supervisor-led orchestration: a routing layer coordinates specialized agents rather than allowing unrestricted cross-system writes.[cite:17][cite:43][cite:46] - Spec-first implementation: agents consume structured artifacts such as issues, specs, `DESIGN.md`, token exports, schema definitions, and implementation rules before modifying code.[cite:17][cite:22][cite:25][cite:47][cite:55][cite:115] - GitHub-native execution lifecycle: all development work originates from or is linked to GitHub Issues and is delivered through pull requests with review and merge controls.[cite:111][cite:112][cite:115][cite:120] - Shared design and component contracts across CMS and app surfaces: EmDash/Astro and Next.js/React must consume the same semantic token model and component rules where practical.[cite:23][cite:32][cite:55][cite:105] - Read-heavy integrations by default: external systems should initially expose retrieval, inspect, export, and validation operations before enabling mutation operations.[cite:17][cite:47][cite:56][cite:105] - Delivery must be communicable: every significant implementation outcome should be representable through CSA-generated interactive artifacts that explain delivered value, follow-up items, architectural state, and decision context.[cite:1] ## System roles | System | Primary role | Authoritative outputs | Allowed writes | Notes | |---|---|---|---|---| | Claude Code | Execution core and coding agent runtime | Code changes, tests, task plans, repo automation artifacts | Git repos, CI jobs, controlled MCP tools | Supports MCP, custom instructions, hooks, and multi-agent workflows.[cite:17] | | GitHub | Canonical engineering workflow system | Repos, issues, branches, pull requests, reviews, merge history | Git objects, issue/PR state | Pull requests and reviews are the formal collaboration mechanism for changes.[cite:111][cite:112][cite:120] | | NotebookLM | Research memory and source-grounded specification workspace | Research notebooks, synthesis docs, PRD context packs | Notebook artifacts only | Enterprise path supports programmatic notebook management and enterprise controls.[cite:98][cite:100][cite:103] | | Obsidian GitReport | DevOps system of record | Project status, issue histories, value-delivered metrics, repo intelligence, delivery evidence | Vault content | User-defined authoritative operational ledger based on current pipeline description.[cite:1] | | Penpot | Approved design system registry and design-to-code handoff source | Design tokens, inspectable layouts, components, annotations, approved frames | Design projects, component libraries | Speaks CSS, Grid, Flexbox, SVG, tokens, and supports MCP/server-side integration paths.[cite:47][cite:55][cite:56][cite:58] | | Stitch | Generative design exploration | Early concepts, candidate layouts, exported screens, design briefs, `DESIGN.md`-style artifacts | Temporary design artifacts | Best used for ideation and proposal generation, not durable truth.[cite:22][cite:25][cite:31][cite:104] | | EmDash | CMS, content schema, editorial automation, Astro theme delivery | Collections, schemas, content, CMS themes, plugin manifests | CMS environment and theme repos | Designed as Astro-based open-source CMS with CLI and MCP-friendly content operations.[cite:2][cite:26][cite:105] | | CSA pipeline | Communication artifact generation pipeline | Internal/external interactive artifacts explaining value, follow-up items, architecture state, and decision points | CSA dashboards and presentation artifacts | Existing Claude Code skills and dashboard pipeline defined by current internal workflow description.[cite:1] | | ADW pipeline | Agentic development workflow pipeline | Queued work, orchestration state, implementation progression from issue/spec to PR/review/delivery | Workflow state and automation outputs | Existing Claude Code-driven issue/spec-to-PR pipeline defined by current internal workflow description.[cite:1] | | LangGraph or internal supervisor | Multi-agent orchestration and policy control | Routed tasks, approval states, execution graphs, retries | Orchestration state only | Strong fit for reliable multi-agent control flows and supervision patterns.[cite:43][cite:46] | | Next.js app tier | Advanced frontend application delivery | App UIs, interactive components, authenticated experiences | App repos | Best target for complex interactive product surfaces.[cite:32][cite:34] | | Astro/EmDash theme tier | Content-heavy public delivery | Marketing sites, editorial surfaces, docs, publishing themes | Theme repos and CMS content | Best target for performant CMS-driven surfaces.[cite:2][cite:23][cite:26] | ## Logical architecture The target architecture is a layered system with a central execution plane, bounded knowledge systems, bounded design systems, bounded content systems, and explicit delivery and communication pipelines.[cite:17][cite:43][cite:47][cite:100][cite:105][cite:111] Claude Code is the implementation hub because it is repo-aware and able to invoke tools, follow repository instructions, and coordinate code changes across environments and GitHub workflows.[cite:17][cite:116] GitHub is the canonical engineering control plane for repositories, issues, pull requests, reviews, and merge records.[cite:111][cite:112][cite:120] ADW sits on top of GitHub as the operational pipeline that turns issue/spec intake into queued agent work, implementation, pull request generation, review, refinement, and delivery.[cite:1] NotebookLM and GitReport sit upstream of execution as distinct context providers.[cite:100][cite:1] NotebookLM provides source-grounded research, feature rationale, PRD synthesis, and decision support, while GitReport provides project state, issue history, value metrics, and delivery evidence from ongoing engineering work.[cite:100][cite:1] Penpot and Stitch sit in the design plane.[cite:22][cite:25][cite:47][cite:55] Stitch generates candidate design directions quickly, while Penpot stores only approved and normalized designs, token sets, component definitions, annotations, and inspectable handoff details.[cite:22][cite:25][cite:47][cite:55] CSA sits downstream of implementation and review as the communication plane.[cite:1] CSA transforms architectural states, delivered value, follow-up work, and decision records into interactive artifacts for internal coordination and external stakeholder communication.[cite:1] EmDash and the app/web repos sit as delivery planes for content and frontend experiences.[cite:2][cite:23][cite:32][cite:105] EmDash provides the AI-operable CMS for content-heavy surfaces, and Next.js provides the app shell and advanced interactive component runtime for richer user experiences.[cite:2][cite:32] ## Agent-readable architecture diagram ```mermaid flowchart TD N[NotebookLM\nResearch + PRDs + source-grounded memory] --> O[Supervisor / Orchestrator\nLangGraph or internal routing layer] GR[GitReport\nOps truth + metrics + value ledger] --> O GH[GitHub\nRepos + Issues + PRs + Reviews] --> O S[Google Stitch\nGenerative design ideation] --> P[Penpot\nApproved design system registry] P --> O O --> ADW[ADW Pipeline\nIssue/spec to agentic execution] ADW --> C[Claude Code\nExecution core] C --> GH O --> E[EmDash\nCMS + content ops + Astro themes] C --> R1[Next.js / React repos] C --> R2[Shared UI package] C --> R3[Astro / EmDash theme repos] E --> R3 R2 --> R1 R2 --> R3 C --> CI[Tests / QA / CI] CI --> GH CI --> GR GH --> CSA[CSA Pipeline\nInteractive delivery artifacts] GR --> CSA C --> CSA ``` The governing rule in this diagram is that GitHub is the canonical execution workflow, ADW is the agentic production line operating over that workflow, and CSA is the communication layer that turns implementation and operational outcomes into high-clarity artifacts.[cite:111][cite:112][cite:115][cite:120][cite:1] Approved design artifacts flow from Stitch into Penpot, and only approved Penpot artifacts flow into code execution.[cite:22][cite:25][cite:47] ## Trust domains and authoritative artifacts | Artifact type | Authoritative system | Secondary consumers | Mutation policy | |---|---|---|---| | Research dossiers | NotebookLM | Claude Code, supervisor, ADW | Mutable only in NotebookLM.[cite:100][cite:103] | | PRDs and feature briefs | NotebookLM, mirrored to repo docs when approved | Claude Code, Stitch, Penpot, ADW | Promotion required before implementation.[cite:100] | | Work intake, issues, branch lineage, PR review history | GitHub | ADW, Claude Code, GitReport, CSA | Mutable through GitHub workflow only.[cite:111][cite:112][cite:120] | | Delivery metrics and issue histories | GitReport | Supervisor, Claude Code, CSA, leadership reporting | Mutable only by ops/update workflows.[cite:1] | | Visual concepts | Stitch | Penpot, Claude Code | Disposable unless approved.[cite:22][cite:25][cite:104] | | Approved tokens, components, annotations | Penpot | Claude Code, theme/app repos | Mutable under design governance only.[cite:47][cite:55][cite:58] | | Component implementation contracts | Repo docs + shared UI package | Claude Code, verification agents, ADW | Version-controlled in code repos.[cite:17][cite:45] | | Content schemas and editorial models | EmDash | Claude Code, frontend repos | Mutable under CMS governance.[cite:2][cite:105] | | Content instances | EmDash | Frontend delivery surfaces | Controlled editorial or agentic writes.[cite:105] | | Stakeholder-facing delivery narratives | CSA | Leadership, clients, internal product and delivery teams | Generated from approved source records.[cite:1] | ## Environments and runtime model The development pipeline currently includes Claude Code on both a VPS and a local XT12 environment, which should be formalized as distinct execution tiers for different classes of work.[cite:1] The VPS tier should handle long-running remote tasks, CI-adjacent automations, GitHub-triggered agent workflows, and shared orchestration services, while the XT12 tier should handle local iteration, visual implementation, asset refinement, and lower-latency coding sessions tied to active development.[cite:1][cite:17][cite:116] A recommended environment split is: - Local workstation (XT12): interactive development, visual QA, component refinement, Penpot asset consumption, and design-to-code tasks.[cite:1] - VPS: orchestrator runtime, ADW queue workers, scheduled jobs, remote Claude Code sessions, notebook ingestion tasks, Penpot/EmDash integration services, GitHub-triggered automation, and verification agents.[cite:1][cite:17][cite:116] - GitHub: canonical issue intake, review, merge gating, and traceable development lifecycle.[cite:111][cite:112][cite:120] - Self-hosted Penpot: internal design collaboration, token registry, approved component documentation, inspect, and MCP-accessible design data.[cite:47][cite:56] - EmDash environment: CMS content operations, theme testing, and staging/production content workflows.[cite:2][cite:105] - CSA dashboard/runtime: generation and presentation of internal/external interactive delivery artifacts.[cite:1] ## Handoff model ### Handoff 0: Intake to GitHub and ADW All implementable work must begin as a GitHub Issue, linked specification, or equivalent GitHub-native intake artifact.[cite:111][cite:115] ADW consumes GitHub Issues and attached specs as the queueing and orchestration substrate for agentic development, ensuring every implementation task has a traceable work item, owner context, and lifecycle state.[cite:1][cite:116] Required intake fields: - `issue_id` - `initiative_id` - `problem_statement` - `requested_outcome` - `linked_specs` - `priority` - `labels` - `acceptance_criteria` - `delivery_constraints` - `review_requirements` ### Handoff 1: Research to planning NotebookLM provides source-grounded research packets to the supervisor, ADW, and Claude Code for planning and implementation.[cite:100] These packets should be normalized into machine-consumable context bundles containing problem statement, goals, constraints, references, known risks, open questions, and acceptance criteria.[cite:100] Required bundle fields: - `initiative_id` - `issue_id` - `objective` - `business_context` - `user_problem` - `feature_scope` - `constraints` - `source_links` - `acceptance_criteria` - `non_goals` - `risks` - `dependent_systems` ### Handoff 2: Planning to design ideation Claude Code, ADW, or the supervisor creates a design brief from the research packet and sends it to Stitch for visual exploration when the work requires visual concept generation or UI reframing.[cite:25][cite:104] The output of Stitch must be treated as proposal material only and should include named variants, rationale, and exportable visual artifacts for review.[cite:22][cite:25] Required output package: - `design_brief.md` - `variant_a/`, `variant_b/`, `variant_c/` - screenshots - exported HTML/CSS where available - `DESIGN.md` or equivalent structured design notes - `related_issue_ids` ### Handoff 3: Design approval to Penpot Approved Stitch concepts are recreated or normalized in Penpot with semantic naming, token alignment, reusable component mapping, and implementation annotations.[cite:47][cite:55] Penpot becomes the sole approved design authority after this step.[cite:47] Required Penpot normalization rules: - Semantic token naming for color, spacing, type, and motion. - Component library structure aligned to repo component names where possible. - State coverage for default, hover, active, focus, disabled, loading, empty, and error states.[cite:47] - Notes for accessibility, responsive behavior, and interaction intent.[cite:47][cite:55] - Linkback to originating GitHub Issue and design review record. ### Handoff 4: Penpot to implementation via ADW Claude Code consumes Penpot exports, inspect output, annotations, token definitions, and linked GitHub Issue data to implement production code in shared UI packages, Next.js apps, or Astro/EmDash themes.[cite:17][cite:47][cite:55][cite:111] ADW is responsible for packaging the execution context, spawning or routing the right agent set, and ensuring all resulting work remains attached to the originating GitHub Issue and branch/PR lineage.[cite:1] Required implementation packet: - GitHub issue id - branch naming target - Penpot project id and frame/component ids - token export JSON - screenshots or export bundle - annotation summary - target repo/module - acceptance checklist - test expectations - PR template requirements ### Handoff 5: Implementation to pull request All meaningful code output must be delivered through a GitHub pull request tied to the originating issue, using topic branches and preserving reviewability.[cite:111][cite:112] Pull requests are the formal collaboration and review artifact, and required reviews or requested changes must be resolved before merge under protected branch policies.[cite:112][cite:120] Required PR contents: - linked issue references - implementation summary - test evidence - screenshots or artifact previews where relevant - follow-up items - review notes for architectural or design decisions ### Handoff 6: Pull request review to refinement Reviewers submit comment, approve, or request-changes states through GitHub review workflows, and ADW or Claude Code may be re-invoked for refinement tasks linked directly to PR review feedback.[cite:120][cite:116] This creates a closed-loop refinement process where agentic work remains subordinate to human review and repository governance.[cite:112][cite:120] ### Handoff 7: Implementation to CMS/content Once design and frontend implementation are stable, EmDash receives schema definitions, block/component mappings, and editorial templates needed for content operations.[cite:2][cite:105] This step ensures CMS-backed surfaces use the same component primitives and token model rather than diverging from the application layer.[cite:23][cite:55][cite:105] Required CMS handoff packet: - collection definitions - field schemas - content block/component map - preview templates - theming token references - seed content format - publishing workflow rules - linked issue/PR references ### Handoff 8: Delivery to GitReport and CSA Once work is merged or otherwise accepted, GitReport receives the operational record of what changed, what value was delivered, what remains open, and what metrics were affected.[cite:1] CSA then consumes approved source records from GitHub, GitReport, architecture docs, and implementation artifacts to generate internal and external interactive artifacts communicating delivered value, follow-up items, architectural states, and decision points.[cite:1] Required CSA source bundle: - issue and PR references - delivery summary - architecture state snapshot - screenshots or interaction previews - follow-up list - decision log excerpts - audience designation (`internal`, `client`, `leadership`, `engineering`) ## Updated delivery lifecycle ```mermaid flowchart LR I[GitHub Issue / Spec Intake] --> A[ADW Queue] A --> B[Research + planning context] B --> C{Design needed?} C -- Yes --> D[Stitch ideation] D --> E[Penpot approval + normalization] C -- No --> E E --> F[Claude Code multi-agent implementation] F --> G[GitHub Pull Request] G --> H{Review outcome} H -- Request changes --> F H -- Approve --> J[Merge / Delivery] J --> K[EmDash content/theme ops if applicable] J --> L[GitReport operational update] J --> M[CSA communication artifacts] ``` This lifecycle makes GitHub the intake and review spine, ADW the execution conveyor, and CSA the communication output layer.[cite:111][cite:112][cite:115][cite:120][cite:1] It also ensures that merged work can be operationally recorded and narratively communicated without reinterpreting delivery state from scratch.[cite:1] ## Role definitions ### Human roles | Role | Responsibilities | Primary systems | |---|---|---| | Product architect | Defines initiative goals, acceptance criteria, and system boundaries; ensures issues/specs are intake-ready | GitHub, NotebookLM, GitReport | | Design lead | Approves Stitch outputs, governs Penpot system, signs off on tokens and components | Stitch, Penpot | | Frontend lead | Owns shared UI architecture, implementation standards, and review of agent-produced code | Claude Code, GitHub, repos | | CMS/content architect | Defines EmDash schemas, content operations, and theme boundaries | EmDash, Astro repos | | DevOps lead | Owns VPS runtime, CI/CD, ADW services, secrets, and observability | GitHub, GitReport, VPS, CI | | Delivery/communication lead | Curates CSA artifacts for internal and external audiences | CSA, GitReport, GitHub | ### Agent roles | Agent | Function | Read sources | Write targets | |---|---|---|---| | Intake/triage agent | Normalize GitHub Issues and specs for ADW queueing | GitHub, approved docs | ADW state | | Research retrieval agent | Assemble source-grounded context from NotebookLM and approved docs | NotebookLM, repo docs | planning bundles | | Project state agent | Retrieve issue, metric, and delivery history | GitReport, GitHub | status summaries | | Design ideation agent | Generate candidate layouts and interaction concepts | design briefs | Stitch outputs | | Design normalization agent | Convert approved concepts into tokenized Penpot structures | Stitch outputs, Penpot | Penpot projects | | Implementation agent | Build components, themes, and app surfaces | Penpot, repo docs, NotebookLM, GitHub Issue context | code repos, branches | | PR agent | Open or update GitHub pull requests and attach evidence | GitHub, repo outputs | GitHub PRs | | Refinement agent | Address review comments and requested changes | GitHub PR reviews, repo context | branch updates | | CMS agent | Create/update schemas, seed content, manage publishing tasks | EmDash definitions, implementation contracts | EmDash | | Verification agent | Run tests, accessibility, visual diff, and policy checks | repos, Penpot references, GitHub PRs | CI reports, GitHub checks, GitReport updates | | CSA artifact agent | Produce interactive artifacts explaining delivery and decisions | GitHub, GitReport, architecture docs, screenshots | CSA artifacts | | Supervisor agent | Route work, manage approvals, and enforce boundaries | all approved read sources | orchestration state | ## Component definitions The architecture requires a shared component system that can target both Next.js and Astro/EmDash surfaces and can be referenced in GitHub Issues, Penpot assets, implementation repos, and CSA outputs.[cite:23][cite:32][cite:47][cite:55] Component definitions should be stored in a shared UI package and mirrored visually in Penpot as approved primitives.[cite:47][cite:55] Required component metadata fields: - `component_name` - `github_issue_refs` - `design_asset_id` - `component_family` - `description` - `supported_framework_targets` - `props_schema` - `state_matrix` - `a11y_requirements` - `responsive_rules` - `motion_rules` - `content_slots` - `cms_bindings` - `token_dependencies` - `test_cases` - `artifact_communication_notes` ## Specification for shared tokens Penpot token outputs should be transformed into a shared design token package that is consumable by both Next.js and Astro/EmDash implementations.[cite:55] The token package must support CSS variables first, with optional projection to Tailwind config, TypeScript theme objects, and CSA-friendly artifact views when needed for architecture communication.[cite:55][cite:1] Recommended token families: - color - typography - spacing - radius - shadow - border - motion - z-index - layout/container - breakpoints - semantic-status tokens for issue/decision/state communication ## Repository and workflow structure A monorepo or coordinated multi-repo layout can work, but the shared UI package and token package must be centrally versioned and all work must be GitHub-linked.[cite:17][cite:32][cite:55][cite:111] A recommended structure is: ```text /apps /web # Next.js application surfaces /cms-theme # Astro / EmDash theme surfaces /packages /ui # Shared component primitives /tokens # Generated and curated design tokens /schemas # Shared content and validation schemas /agents # ADW prompts, policies, adapters, queue logic /csa # CSA templates, artifact generators, dashboards /design /exports # Approved export bundles from Penpot /tokens # Raw and transformed token outputs /briefs # Design briefs and approved summaries /docs /architecture /handoffs /playbooks /decision-records /ops /scripts /deploy /observability /.github /ISSUE_TEMPLATE /PULL_REQUEST_TEMPLATE.md /workflows ``` ## Developer implementation guide ### Phase 1: Foundation 1. Establish the supervisor/orchestration layer and policy boundaries for each integrated system.[cite:43][cite:46] 2. Normalize GitHub issue templates, labels, branch conventions, PR templates, and review requirements.[cite:111][cite:112][cite:115][cite:120] 3. Normalize repo conventions through `CLAUDE.md`, coding standards, testing rules, branching strategy, and environment policies.[cite:17] 4. Define shared token transformation pipeline from Penpot outputs to code-consumable packages.[cite:55] 5. Define GitReport update conventions for issue closure, value-delivered metrics, and initiative state transitions.[cite:1] 6. Define CSA artifact classes and audience mappings.[cite:1] ### Phase 2: Intake and ADW 1. Ensure all new work enters through GitHub Issues with required structured metadata.[cite:111][cite:115] 2. Build ADW queue processors that resolve issue/spec context and classify work by type: design, frontend, CMS, infra, artifact, or mixed.[cite:1] 3. Add Claude Code GitHub automation triggers where appropriate for issue comments, assignment, PR review comments, and refinement cycles.[cite:116][cite:119] 4. Define branch naming, PR ownership, and retry/refinement policies.[cite:111][cite:112] ### Phase 3: Design system integration 1. Create the Penpot project structure for foundations, primitives, patterns, and product-specific frames.[cite:47] 2. Define Stitch prompt templates and export requirements for early ideation.[cite:25][cite:104] 3. Establish approval criteria for promotion from Stitch artifacts to Penpot-approved assets.[cite:22][cite:47] 4. Build initial token transformation scripts and validate parity across light/dark mode and responsive variants.[cite:55] ### Phase 4: Code generation and implementation 1. Create the shared UI package with token ingestion, base primitives, and test scaffolding.[cite:17][cite:55] 2. Configure Claude Code instruction hierarchy for shared components, app tier, CMS theme tier, and artifact generation paths.[cite:17] 3. Implement Storybook or equivalent visual component catalog to serve as the engineering verification surface.[cite:45] 4. Build a pilot set of components spanning buttons, cards, nav, form inputs, CMS blocks, and interactive panels.[cite:47][cite:55] ### Phase 5: CMS and delivery communication 1. Stand up EmDash schemas for collections, blocks, assets, and editorial workflows.[cite:2][cite:105] 2. Map shared components to CMS-renderable blocks and define preview behavior.[cite:23][cite:105] 3. Implement agent-safe content operations via CLI/MCP with approval gates for destructive or production writes.[cite:105] 4. Create CSA templates for delivered value, architecture state snapshots, follow-up items, and decision summaries.[cite:1] 5. Bind CSA artifact generation to GitHub/GitReport delivery events where appropriate.[cite:1] ### Phase 6: Verification and observability 1. Add accessibility, performance, and visual regression checks to CI and PR workflows.[cite:17][cite:45][cite:123] 2. Persist verification outcomes and delivery notes into GitReport.[cite:1] 3. Track design drift by comparing implementation states to approved Penpot artifacts.[cite:47][cite:55] 4. Add orchestration logs, approval events, and tool execution traces for debugging and auditability.[cite:43][cite:46] 5. Ensure CSA outputs cite or reference approved delivery records rather than ad hoc interpretations.[cite:1] ## Agent-readable data flow ```mermaid sequenceDiagram participant GH as GitHub participant N as NotebookLM participant O as Orchestrator participant A as ADW participant S as Stitch participant P as Penpot participant C as Claude Code participant E as EmDash participant G as GitReport participant X as CSA GH->>A: Issue/spec intake N-->>A: Research context bundle A->>O: Queue classified work O->>S: Submit design brief when needed S-->>O: Return variants + design artifacts O->>P: Promote approved concept for normalization P-->>O: Return approved tokens + inspect data + annotations O->>C: Assign implementation task with issue + design packet C->>GH: Push branch / open PR / update status C->>E: Apply schemas/themes/content bindings when needed C-->>O: Return code, tests, status GH-->>O: Review comments / approvals / change requests O->>C: Route refinement tasks if needed GH-->>G: Merge history and linked issue outcomes G-->>X: Delivery metrics and value notes GH-->>X: PR and issue evidence C-->>X: Screens, demos, artifact inputs ``` This sequence should be treated as the default delivery path for net-new work.[cite:111][cite:116][cite:120][cite:1] Fast-path work may skip Stitch only when changes are clearly incremental and already covered by an existing Penpot-approved component system.[cite:47] ## User and stakeholder flow model ```mermaid flowchart LR U[End User] --> W[Public Web or App Surface] W --> A[Next.js App Tier] W --> T[Astro / EmDash Theme Tier] T --> M[EmDash Content API / Render Layer] A --> X[Shared UI Components] T --> X X --> K[Shared Tokens] D[Delivery Team] --> GH[GitHub Workflow] GH --> GR[GitReport] GH --> CSA[CSA Artifacts] GR --> CSA CSA --> ST[Stakeholders / Clients / Leadership] ``` The user experience layer must remain visually and behaviorally consistent regardless of whether a surface is rendered through the Next.js app tier or the EmDash/Astro CMS tier.[cite:23][cite:32][cite:55] The stakeholder communication layer must remain traceable to GitHub and GitReport records so that delivered value and follow-up items can be audited and reused.[cite:1][cite:111] ## Integration specifications ### GitHub GitHub is the formal system for issues, repositories, pull requests, branch workflows, and review gates.[cite:111][cite:112][cite:120] Every implementation effort must be linked to an issue or equivalent intake item, and every substantive code change must flow through a pull request with explicit review state.[cite:111][cite:112][cite:115][cite:120] Minimum configuration requirements: - structured issue templates - PR template with implementation, evidence, and follow-up sections - branch protection rules - required status checks - label taxonomy aligned to ADW routing - linked issue conventions ### Claude Code Claude Code must be configured as the primary execution plane with repository-specific `CLAUDE.md` guidance, tool policies, GitHub integration, and separation between app, CMS, infra, CSA, and ADW tasks.[cite:17][cite:116] Repositories should include explicit instructions for coding standards, framework conventions, token usage, testing, and safe write boundaries.[cite:17] Minimum configuration requirements: - repo-level `CLAUDE.md` - environment profiles for local XT12 and VPS - task templates for frontend, design-system, CMS, verification, and CSA work - hooks or scripts for formatting, tests, and policy checks - GitHub Actions integration where beneficial.[cite:116] ### ADW pipeline ADW is the controlled workflow that transforms GitHub Issues and specs into queued agentic execution, code implementation, PR generation, review response, and delivery closure.[cite:1] It should not become a separate source of work truth; instead it should operationalize GitHub-native work items.[cite:1][cite:111] Minimum requirements: - issue-to-queue ingestion - work classification - agent routing rules - branch and PR creation rules - review feedback reinjection - delivery closure update hooks ### CSA pipeline CSA is the artifact communication layer responsible for generating internal and external interactive artifacts illustrating delivered value, follow-up items, architectural states, and decision points.[cite:1] CSA outputs must be generated from approved sources such as GitHub, GitReport, architecture docs, screenshots, and merged implementation state.[cite:1] Minimum requirements: - artifact templates by audience - source bundle schema - delivery evidence requirements - architecture-state capture format - follow-up issue extraction - publication or dashboard display rules ### NotebookLM NotebookLM should be treated as the research memory and specification retrieval layer, ideally through enterprise-managed notebooks where available.[cite:98][cite:100][cite:103] Notebook content should be exported or summarized into stable context bundles before being used in planning or execution loops.[cite:100] ### GitReport GitReport is the operational source of truth and must receive structured updates from project and verification workflows.[cite:1] It should not store raw exploratory design or raw research as primary artifacts.[cite:1] ### Penpot Penpot must be organized into foundation libraries, component libraries, and product/project-specific files.[cite:47][cite:55] Approved designs should include inspect-ready layout details, state coverage, annotation layers, and token alignment.[cite:47][cite:58] ### Stitch Stitch should be integrated as an ideation service with explicit export expectations and bounded lifecycle.[cite:25][cite:104] Generated outputs should be tagged by initiative and variant, then either promoted to Penpot or archived.[cite:22][cite:25] ### EmDash EmDash should be integrated as a CMS platform with code-defined schemas, approved theme boundaries, and gated content operations.[cite:2][cite:26][cite:105] Theme development should use shared tokens and shared design-system contracts rather than ad hoc duplication.[cite:23][cite:55] ## Security and governance Secrets and credentials must remain outside notebooks, chat transcripts, and repo docs, and should instead be stored in a vault or environment management layer.[cite:1] Write-capable integrations to Penpot, GitHub automation, and EmDash must be gated through approvals, especially in production contexts.[cite:47][cite:56][cite:105][cite:116] Governance rules: - Read-only integrations by default. - Production writes require explicit approval state. - Research and design proposals cannot directly publish code or content. - Verification failures block promotion to release. - All destructive operations are logged and attributable. - CSA artifacts must derive from approved and traceable delivery records. ## Quality gates Every implementation must pass the following gates before release: - GitHub issue linkage and PR traceability.[cite:111][cite:112] - Design parity against approved Penpot artifact.[cite:47][cite:55] - Accessibility checks across states and breakpoints.[cite:47] - Performance checks for CMS and app surfaces.[cite:2][cite:23][cite:32][cite:123] - Content/schema validation for EmDash-backed pages.[cite:105] - Operational update recorded in GitReport.[cite:1] - CSA source bundle completeness for communication-worthy deliverables.[cite:1] ## Acceptance criteria This architecture is considered successfully implemented when: - All systems have documented and enforced boundaries.[cite:43][cite:46] - GitHub is the canonical intake, review, and merge workflow for all substantive development work.[cite:111][cite:112][cite:120] - ADW reliably converts issues/specs into traceable agentic execution paths.[cite:1] - Design truth exists only in approved Penpot assets after concept approval.[cite:47] - Shared tokens drive both Next.js and EmDash/Astro surfaces.[cite:23][cite:55] - Claude Code can execute implementation tasks from structured context packets without ambiguous inputs.[cite:17] - GitReport reliably reflects delivered value, issues, and operational state.[cite:1] - CSA reliably converts delivery outcomes into reusable communication artifacts.[cite:1] - Research, design, implementation, content, review, and communication workflows are traceable end to end.[cite:100][cite:105][cite:111] ## Formal handoff checklists ### Intake handoff checklist - GitHub issue created - Labels and priority set - Acceptance criteria present - Linked specs attached - Review requirements defined - ADW routing class assigned ### Research handoff checklist - Problem statement defined - Sources attached or referenced - Constraints documented - Acceptance criteria written - Non-goals captured - Risks captured ### Design handoff checklist - Approved concept identified - Penpot frame/component ids included - Token export included - State coverage documented - Responsive behavior documented - Accessibility notes included - GitHub issue linkage included ### Implementation handoff checklist - Target repo/module identified - Shared component dependency identified - Test plan included - CMS binding needs documented - Performance concerns listed - Branch/PR path identified ### PR handoff checklist - Linked issue references included - Summary written - Evidence attached - Review notes attached - Follow-up items captured - Checks passing or exceptions documented ### CMS handoff checklist - Collection schema included - Block/component map included - Preview pattern included - Seed content format included - Editorial permissions/path included - Production write policy confirmed - Linked issue/PR references included ### CSA handoff checklist - Delivery summary available - GitHub evidence linked - GitReport notes linked - Architecture snapshot available - Follow-up items extracted - Audience identified ### Ops handoff checklist - Verification complete - Release notes prepared - GitReport updated - Metrics captured - Regressions logged if any - Rollback or remediation path defined ## Immediate next implementation steps 1. Update `/docs/handoffs` and `/packages/agents` to reflect GitHub, ADW, and CSA as first-class pipeline systems.[cite:1][cite:111] 2. Align GitHub issue templates, PR templates, labels, and branch protections to the new handoff model.[cite:111][cite:112][cite:115][cite:120] 3. Establish token export and transform pipeline from Penpot into `/packages/tokens`.[cite:55] 4. Define Stitch promotion rules and archive strategy.[cite:25][cite:47] 5. Stand up EmDash staging with initial schema registry and shared theme conventions.[cite:2][cite:105] 6. Add GitReport automation for status and verification ingestion.[cite:1] 7. Add CSA source bundle schema and dashboard generation triggers based on merged PRs and approved delivery records.[cite:1] 8. Pilot the full updated flow on one bounded surface: one CMS-backed marketing page plus one advanced interactive frontend component, each originating from GitHub Issues and closing with CSA artifacts.[cite:23][cite:32][cite:105][cite:111]