Skip to content

PRD-WEBSITE.md

Latest commit

 

History

History
451 lines (334 loc) · 11.7 KB

PRD-WEBSITE.md

File metadata and controls

451 lines (334 loc) · 11.7 KB
Raw

PRD: Binder Documentation Website

Overview

Create a single-page marketing/documentation website for Binder CLI, inspired by agents.md. The site will serve as the primary landing page for the tool, explaining its purpose, demonstrating usage, and driving adoption.

Goals

  1. Communicate value proposition - Clearly explain what Binder does and why developers need it
  2. Enable quick adoption - Provide copy-paste installation and usage examples
  3. Establish credibility - Professional design that signals production-ready tooling
  4. SEO presence - Rank for "multi-repo AI workspace", "AI agent permissions", etc.

Target Audience

  • Developers working across multiple repositories
  • Teams using AI coding assistants (Cursor, Copilot, Claude Code, etc.)
  • Engineering leads setting up AI-assisted development workflows
  • Open source maintainers managing related repos

Technical Stack

Component Technology Rationale
Framework Astro Fast static output, component islands, great DX
Styling Tailwind CSS Rapid prototyping, consistent design system
Hosting GitHub Pages Free, automatic deploys via Actions
Domain TBD (e.g., binder.dev, getbinder.dev) Optional custom domain

Repository Structure

binder-website/
├── .github/
│   └── workflows/
│       └── deploy.yml        # GitHub Pages deployment
├── src/
│   ├── components/
│   │   ├── Header.astro
│   │   ├── Hero.astro
│   │   ├── Features.astro
│   │   ├── Scopes.astro
│   │   ├── CodeExample.astro
│   │   ├── QuickStart.astro
│   │   ├── ContextMapDemo.astro
│   │   └── Footer.astro
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   └── index.astro
│   └── styles/
│       └── global.css
├── public/
│   ├── favicon.svg
│   └── og-image.png          # Social sharing image
├── astro.config.mjs
├── tailwind.config.mjs
└── package.json

Page Structure & Content

1. Header/Navigation

  • Logo: "Binder" text logo (no image needed initially)
  • Nav Links: Scroll anchors to page sections
  • CTA Button: "Get Started" → scrolls to Quick Start section
  • GitHub Link: Icon link to repo

2. Hero Section

Headline:

Orchestrate multi-repo workspaces with scoped permissions for AI agents

Subheadline:

Define your workspace topology once. Let AI understand where it can—and can't—make changes.

Primary CTA: npm install -g binder-cli Secondary CTA: "View on GitHub"

Visual: Terminal mockup or animated demo showing:

$ binder init
✔ Created binder.yaml

$ binder pull
✔ Cloned my-service (owner)
✔ Cloned shared-platform (platform)
✔ Cloned legacy-api (reference)

$ binder context
✔ Generated CONTEXT_MAP.md

3. Problem Statement Section

Headline: "The Multi-Repo AI Problem"

Content:

AI coding assistants are powerful—but they don't understand your workspace topology.

When you work across multiple repositories, AI doesn't know:

  • Which repos you own vs. which you're just referencing
  • Where it can refactor freely vs. where it should tread carefully
  • What context from adjacent repos is relevant

Binder solves this by giving AI agents a semantic map of your workspace with explicit permissions.

4. Scopes Section (Core Concept)

Headline: "Three Scopes. Clear Boundaries."

Display three cards/columns:

🟢 OWNER

  • Tagline: "Your domain. Full authority."
  • Permissions: Full read/write access
  • AI Behavior: Refactor freely, improve architecture, make breaking changes
  • Use For: Your primary services, apps you maintain

🟡 PLATFORM

  • Tagline: "Guest contributor. Tread carefully."
  • Permissions: Limited write access
  • AI Behavior: Follow existing patterns, minimal changes only, no refactoring
  • Use For: Shared infrastructure, internal platforms, upstream dependencies

🔴 REFERENCE

  • Tagline: "Read-only. For context."
  • Permissions: No modifications
  • AI Behavior: Read for understanding, never suggest changes
  • Use For: Legacy systems, external examples, documentation repos

5. How It Works Section

Headline: "How Binder Works"

Step 1: Define

Create a binder.yaml that maps your workspace topology

name: my-workspace

repos:
  - name: my-service
    url: git@github.com:org/my-service.git
    scope: owner
    notes: "Core backend service"

  - name: shared-platform
    url: git@github.com:org/platform.git
    scope: platform
    notes: "Shared infrastructure - follow existing patterns"

  - name: legacy-api
    url: git@github.com:org/legacy-api.git
    scope: reference
    depth: 1

Step 2: Pull

Binder clones and checks out all repositories idempotently

$ binder pull
✔ Cloned my-service → ./repos/my-service (owner)
✔ Cloned shared-platform → ./repos/shared-platform (platform)
✔ Cloned legacy-api → ./repos/legacy-api (reference)

Step 3: Generate Context

Generate CONTEXT_MAP.md for your AI assistant

$ binder context
✔ Generated CONTEXT_MAP.md

Step 4: Use with AI

Add to your AI system prompt, .cursorrules, or Claude Code context

6. CONTEXT_MAP.md Demo Section

Headline: "What AI Sees"

Show a styled preview of generated CONTEXT_MAP.md:

# WORKSPACE TOPOLOGY & SCOPE DEFINITIONS

**Workspace:** my-workspace
**Generated:** 2025-01-03T12:00:00Z

---

## 🟢 SCOPE: OWNER (Full Authority)

**Repositories:**
- `my-service` at `./repos/my-service`
  - *Core backend service*

**Permissions:** Full read/write access

**Instructions:**
- You are responsible for architecture, implementation, and refactoring
- Make changes freely to improve code quality and functionality
- You may create, modify, or delete files as needed
- Consider impacts on PLATFORM and REFERENCE scopes when making changes

---

## 🟡 SCOPE: PLATFORM (Restricted Contributor)

**Repositories:**
- `shared-platform` at `./repos/shared-platform`
  - *Shared infrastructure - follow existing patterns*

**Permissions:** Limited write access

**Instructions:**
- Only make minimal, necessary changes to support OWNER scope work
- Strictly adhere to existing patterns and conventions
- Do not refactor or restructure code
- When in doubt, ask before modifying

---

## 🔴 SCOPE: REFERENCE (Read-Only)

**Repositories:**
- `legacy-api` at `./repos/legacy-api`

**Permissions:** Read-only access

**Instructions:**
- Use for understanding context, patterns, and interfaces
- Do NOT suggest modifications to these repositories
- Reference for validation and historical context only

7. Quick Start Section

Headline: "Get Started in 60 Seconds"

# Install
npm install -g binder-cli

# Initialize workspace
binder init

# Edit binder.yaml to add your repos...

# Clone everything
binder pull

# Generate AI context
binder context

# Check status anytime
binder status

8. Features Grid

Feature Description
Idempotent Operations Run binder pull repeatedly—it only clones what's missing
Branch Management Specify branches per-repo, Binder handles checkout
Shallow Clones Use depth: 1 for large reference repos
Status Dashboard See dirty repos, branch mismatches, orphaned clones
AI-Native Output CONTEXT_MAP.md designed for LLM consumption
Zero Lock-in Plain YAML config, standard git repos

9. Compatibility Section

Headline: "Works With Your AI Tools"

Grid of logos/names:

  • Cursor
  • GitHub Copilot
  • Claude Code
  • Windsurf
  • Cody
  • Continue
  • Aider
  • Any LLM-based coding assistant

Note: "Binder generates markdown context that works with any AI tool that accepts system prompts or context files."

10. Philosophy Section

Headline: "Topology vs. Task"

Binder separates workspace definition from feature implementation.

Binder's job: "Here are the repos. You own these, you're a guest here, read-only there."

Your job: "We are building Feature X. Please implement Y."

This separation lets AI understand its permissions without you re-explaining context every session.

11. Installation Section

Headline: "Installation"

# npm
npm install -g binder-cli

# yarn
yarn global add binder-cli

# pnpm
pnpm add -g binder-cli

Requirements:

  • Node.js 18+
  • Git installed and configured

12. Footer

  • GitHub repository link
  • npm package link
  • License (MIT)
  • "Built by [your name/org]"

Design Direction

Visual Style

Inspired by agents.md:

  • Clean, minimal aesthetic - lots of whitespace
  • Dark code blocks - syntax highlighted, copy buttons
  • Muted color palette - grays, with scope colors as accents (green/yellow/red)
  • Monospace for code - JetBrains Mono or Fira Code
  • Sans-serif for prose - Inter or system fonts

Color Palette

/* Background */
--bg-primary: #ffffff;
--bg-secondary: #f8fafc;
--bg-code: #1e293b;

/* Text */
--text-primary: #0f172a;
--text-secondary: #64748b;
--text-code: #e2e8f0;

/* Scope Colors */
--scope-owner: #22c55e;      /* Green */
--scope-platform: #eab308;   /* Yellow */
--scope-reference: #ef4444;  /* Red */

/* Accent */
--accent: #3b82f6;           /* Blue for CTAs */

Typography

  • Headings: Bold, large, high contrast
  • Body: 16-18px, comfortable line height (1.6-1.75)
  • Code: 14-15px monospace, generous padding

Responsive Behavior

  • Mobile-first design
  • Single column on mobile, multi-column on desktop
  • Code blocks horizontally scroll on small screens
  • Sticky header on scroll

SEO & Metadata

Title

Binder - Multi-Repo Workspaces for AI Agents

Description

Define workspace topology and scoped permissions for AI coding assistants. Orchestrate multiple repositories with clear boundaries for owner, platform, and reference access.

Keywords

  • multi-repo workspace
  • AI coding assistant
  • repository permissions
  • workspace orchestration
  • AI agent context
  • monorepo alternative

Open Graph

<meta property="og:title" content="Binder - Multi-Repo Workspaces for AI Agents">
<meta property="og:description" content="Define workspace topology and scoped permissions for AI coding assistants.">
<meta property="og:image" content="/og-image.png">
<meta property="og:type" content="website">

Future Enhancements (Out of Scope for V1)

  1. Interactive Demo - In-browser playground to try binder.yaml
  2. Docs Section - Multi-page documentation site
  3. Blog - Release notes, tutorials, use cases
  4. Community Showcase - Example configs from real projects
  5. Video Walkthrough - Embedded demo video

Success Metrics

  1. Adoption: npm weekly downloads
  2. Engagement: GitHub stars, forks
  3. SEO: Organic search impressions for target keywords
  4. Conversion: Visitors → GitHub repo visits

Implementation Checklist

  • Create binder-website repository
  • Initialize Astro project with Tailwind
  • Set up GitHub Pages workflow
  • Build Hero section
  • Build Problem Statement section
  • Build Scopes section (3-column cards)
  • Build How It Works section (4 steps)
  • Build CONTEXT_MAP.md demo section
  • Build Quick Start section
  • Build Features grid
  • Build Compatibility section
  • Build Philosophy section
  • Build Installation section
  • Build Header and Footer
  • Add syntax highlighting for code blocks
  • Add copy-to-clipboard for code
  • Mobile responsive testing
  • SEO metadata
  • Create OG image
  • Favicon
  • Deploy to GitHub Pages
  • (Optional) Configure custom domain