Skip to content

README.md

Latest commit

 

History

History
98 lines (72 loc) · 5.94 KB

README.md

File metadata and controls

98 lines (72 loc) · 5.94 KB

Services Interface Builder

A Claude Cowork workspace template that turns Airtable Delivery Consultants — none of whom write code or use the command line — into builders of custom Airtable Interface Extensions.

This repository is the template that the Extension Manager macOS app pulls from each time a consultant starts a new customer project. It contains the orchestration logic (CLAUDE.md) and six specialized skills that Claude follows to walk a consultant through requirements gathering, code generation, QA, and customer handoff.

How It Fits Together

┌──────────────────────────────┐         ┌──────────────────────────────┐
│  Extension Manager (macOS)   │  pulls  │  services-interface-builder  │
│  - Project scaffolding        │ ───────▶│  (this repo)                 │
│  - Dev server / publish       │         │  - CLAUDE.md                 │
│  - Local Git ops              │         │  - 6 skills                  │
└──────────────┬───────────────┘         └──────────────────────────────┘
               │
               ▼
┌──────────────────────────────┐
│   Customer Project Folder    │
│   .claude/  (from template)  │  ◀── opened in Claude Cowork
│   status.md, prd.md, ...     │
│   <project-name>/frontend/   │  ◀── extension code lives here
└──────────────────────────────┘

The consultant never interacts with this repo directly. The Extension Manager app handles all local-machine operations (CLI install, project init, dev server, publish, Git). Cowork — guided by the contents of this template — handles all the AI work.

The Six-Stage Workflow

Every extension build follows this sequence. Each stage produces a concrete artifact that gates the next.

Stage Name Skill Outputs
1 Schema Discovery schema-analyzer schema.md
2 Requirements & Planning extension-planner prd.md, mockups/mockup.html, customer sign-off
3 Project Setup cli-manager Initialized <project-name>/ directory with SDK rules
4 Code Generation extension-builder <project-name>/frontend/ with full extension code
5 QA & Deployment qa-generator qa-checklist.html, published extension
6 GitHub & Customer Handoff github-manager GitHub repo with README

Stages cannot be skipped. The orchestrator (CLAUDE.md) blocks forward motion until the prior stage's outputs exist and meet the requirements (e.g., a PRD must contain a real customer sign-off before the project can be set up).

The Skills

Each skill is a directory under .claude/skills/ following the Agent Skills spec: a SKILL.md with YAML frontmatter and markdown body, plus optional reference/, standards/, and templates/ subdirectories for progressive disclosure.

  • schema-analyzer — Pulls the customer's Airtable base structure via the Airtable MCP connector and writes a structured reference doc.
  • extension-planner — Turns a consultant's verbal description plus the schema into a PRD and a self-contained HTML mockup for customer review.
  • cli-manager — Walks the consultant through one-time CLI setup and per-project block init via the Extension Manager app.
  • extension-builder — Reads the SDK rules from the initialized project (.cursor/rules/) and the consultant's PRD/mockup, then generates a complete Interface Extension. Iterates with the consultant on changes.
  • qa-generator — Builds an interactive QA checklist from the PRD and walks the consultant through testing before publishing.
  • github-manager — Generates a customer-facing README and either zips the extension code or pushes it to a GitHub repo for handoff.

Repository Structure

.claude/
├── CLAUDE.md                    # Orchestrator: stage routing, blocking rules, conversation flow
└── skills/
    ├── schema-analyzer/
    ├── extension-planner/
    ├── cli-manager/
    ├── extension-builder/
    ├── qa-generator/
    └── github-manager/

Technical Stack the Skills Generate

Extensions produced by this workspace target the Airtable Interface Extensions SDK:

  • @airtable/blocks/interface/ui (not the legacy dashboard blocks SDK)
  • initializeBlock({ interface: ... }) mounting
  • HTML + Tailwind CSS (with Airtable design tokens preconfigured by block init) — no SDK UI components
  • useCustomProperties for user-configurable field bindings — no hardcoded field IDs
  • @phosphor-icons/react for icons
  • Plain .js files (not TypeScript)
  • Dark-mode required via Tailwind class strategy

The authoritative SDK reference lives in each project's .cursor/rules/interface-extensions.mdc (created by block init). The skills read it at code-generation time rather than relying on this repo to stay in sync with SDK updates.

Updating This Template

Changes pushed to main are picked up by the Extension Manager app on the next project creation. Existing projects keep the version of the template they were created with — there is no in-place upgrade.

When updating skills:

  1. Edit files under .claude/
  2. Test locally by copying the updated .claude/ into a scratch project and running through the affected stage in Cowork
  3. Commit and push to main

For Consultants Who Found This Repo

You don't need to clone or download this repo. Open the Extension Manager app, click "New Project", and the workspace template is pulled in automatically. The app guides you from there.

License

Internal — Airtable, Inc.