Workflows

How keywords chain together into complete operations. Single words are charms. Sequences are rituals.

---

Development Workflows

Feature Development

Say a keyword, the orchestration agent routes, specialized agents execute, output code.

"saas billing"
  → orchestration agent
  → prisma agent (schema) + block agent (UI) + stripe MCP
  → Complete billing feature with all layers

Dev Server (dev)

1. Hook: Kill port 3000
2. Run: pnpm dev
3. Hook: Open Chrome to localhost:3000
4. Hook: Auto-format on every file change

Build and Validate (build)

1. Run pnpm build
2. Scan TypeScript errors
3. Auto-fix lint + type errors
4. Re-build and verify clean

Commit and Push (push / quick)

1. Lint check
2. Auto-fix issues
3. Git add + conventional commit
4. Git push to remote

Deployment (deploy / ship)

1. Build verification
2. Vercel MCP deploy
3. Poll status
4. Retry up to 5 times
5. Report deployment URL

Testing (test [target])

1. Read target code
2. Generate Vitest + Playwright tests
3. Execute test suite
4. Report coverage + results

Handover QA (handover [block])

5-pass testing on both localhost and production:

Fix, re-test, loop until all 5 passes clean.

Report to Fix (report [repo])

User submits "Report an Issue" dialog → GitHub issue created with report label → Claude Code auto-fixes.

User clicks "Report an issue" (footer link on every page)
        ↓
GitHub Issue created (label: report)
        ↓
Session start: Claude checks for open report issues
        ↓
  ┌─────────────────────────┐
  │  1. READ                │  gh issue view → page URL + description
  │  2. LOCATE              │  URL → route dir + component dir
  │  3. CONTEXT             │  CLAUDE.md, README.md, ISSUE.md
  │  4. VALIDATE            │  Real bug? Planned? Safe to fix?
  │  5. SEE + DEBUG         │  Screenshot + console errors
  │  6. IDENTIFY            │  Root cause from report + visual + errors
  │  7. FIX                 │  Minimum code change
  │  8. BUILD               │  pnpm build — no regressions
  │  9. PUSH                │  fix: commit + push to main
  │  10. VERIFY             │  See page again after deploy
  │  11. CLOSE              │  Close issue with fix summary
  └─────────────────────────┘

Trigger: say report (all repos) or report hogwarts (one repo).

Automatic: every session checks for open report issues at start.

Escalation: cannot reproduce → cannot-reproduce label. Needs judgment → needs-human label.

URL to directory mapping (hogwarts example):

---

Content Workflows

Textbook to Markdown twin (textbook <book-dir>)

Every curriculum textbook.pdf gets a textbook.md beside it, read by a vision model — not OCR — and trusted only as far as a blind second read agrees with it. Disagreements are adjudicated against the scan, never averaged away.

Modes: full · verify (a twin already on disk) · repair (the saved queue only). The headline is the random sample's agreement; A ≥ 0.95 is provisional.

Textbook benchmark (textbook bench [book-id])

A blind transcription of the corpus's hardest pages into bench-runs/<label>/, scored against objective per-page assertions (repair traps that must survive, interpretive words that must not appear, label sets, table shapes, the crop-verified rightmost column), then the transcript audit that voids a run that peeked. Every entry records the gold hash, the contract hash and the model, so a contract or model change is a comparable number.

Full page: Textbook — run commands, arguments, configuration, the record.

---

Component Creation

Atom (atom [name])

Check codebase, compose shadcn/ui primitives, style with Tailwind + RTL, type with TypeScript, register in memory.

Template (template [name])

Check registry, design full-page layout, responsive breakpoints, mobile-first RTL, connect data layer, register.

Block (block [name])

Check codebase, design UI + business logic, create component + actions + schema, 100-point quality scoring, test, register.

SaaS Feature (saas [feature])

Generate all layers: Prisma model, Server Actions, React components, Next.js pages, auth checks, i18n keys, tests.

---

Hogwarts Pilot Workflows

Admission Block Development

Developer (Abdout):
  > "handover admission"
  1. Navigate admission pages (forms, tables, detail views)
  2. Test enrollment workflow end-to-end
  3. Verify at 375px, 768px, 1440px
  4. Check Arabic RTL layout
  5. Scan for missing translations
  6. Fix → re-test until clean
  7. Deploy to ed.databayt.org

King Fahad Schools Onboarding

QA + Sales (Ali):
  > Test admission flow end-to-end, report issues on GitHub
  > Prepare pitch materials for Ahmed Baha
  > Continue outreach: other schools, sponsors, investors, contributors

R&D (Samia):
  > Research sharing economy pitch framing
  > Study open-source school solution positioning
  > Arabic content for pitch and documentation

---

Team Daily Workflows

Abdout — Builder

> "dev"                         # Start dev server
> [feature development]         # Build with full agent fleet
> "build"                       # Validate
> "push"                        # Commit + push
> "deploy"                      # Ship to Vercel

Ali — QA + Sales

QA:
  > Test features from URL checklists on GitHub Issues
  > Report bugs as comments
  > Re-verify fixes, check off boxes

Sales (sales@databayt.org):
  > Outreach: schools, sponsors, investors, early adopters, contributors
  > Draft proposals, follow up leads

Samia — R&D

Cowork:
  > Research Claude/Anthropic products
  > Study sharing economy models
  > Investigate revenue distribution
  > Take care of Kun engine

Sedon — Executor

> [clear task map]               # Well-defined tasks with steps
> Saudi operations               # Bank, payments, presence
> Batch weekly                   # Monday map, Friday delivery

---

Cross-Device Workflows

Desktop to Phone to Terminal

Desktop (CLI):  Start feature work → /desktop hand off
Phone (iOS):    Remote Control to monitor → Dispatch: "finish and deploy"
Terminal:       /teleport pull session back → "handover" → run QA

Design to Code

"figma https://figma.com/design/abc/..."
  → Figma MCP: get_design_context
  → Map to existing shadcn/ui + atoms
  → Generate components with Tailwind (RTL-aware)
  → Deploy preview

---

Agent Teams (Parallel Development)

"Build settings: profile tab, notifications tab, billing tab"
  → Lead Agent dispatches:
    ├── Agent A (worktree) → Profile form + avatar
    ├── Agent B (worktree) → Notification preferences
    └── Agent C (worktree) → Billing + Stripe
  → Lead merges → resolve conflicts → single PR → tests

---

Scheduled Tasks

---

Business Workflows

Client Communication

Cowork (Ali):
  > "Draft project update for Ahmed Baha"
  1. GitHub MCP: Fetch merged PRs this week
  2. Summarize features + fixes
  3. Draft Arabic email
  4. Output as artifact

Financial Tracking

Cowork + Stripe MCP:
  > "Monthly burn and runway report"
  1. Track expenses: Claude Max 5x ($100) + services (~$300)
  2. Current burn: ~$400-500/month
  3. Runway: $5K / burn ≈ 10 months
  4. Revenue: track when it starts coming in

Sharing Economy Research

Cowork (Samia):
  > Study sharing economy models
  > Investigate revenue distribution
  > Research startup sustainability
  > Design databayt's revenue model

---

Captain Weekly Rhythm

Monday: Plan

1. Check Abdout's instructions (Dispatch inbox)
2. Check revenue (Stripe MCP)
3. Check product health (Sentry MCP)
4. Set weekly priorities
5. Allocate team
6. Dispatch plan

Wednesday: Check

1. On track?
2. Blockers?
3. Adjust allocations
4. Handle escalations

Friday: Review

1. What shipped this week?
2. Revenue update
3. Customer feedback
4. Set up next Monday

---

Communication Channels

Channel 1: Native Push + Cowork Bridge (Async)

Channel 2: GitHub Issues (Structured Work)

Every piece of work = a GitHub issue. 22 labels, 3 milestones (Phase 1/2/3).

Channel 3: Claude Native (Real-time)

---

Quick Reference