# Build Pipeline Skill

Orchestrates the Build phase — creates a working web application from design artifacts.

## Overview

When a product proceeds to Build phase, this pipeline:
1. Reads design artifacts (brand guidelines, screens, design brief)
2. Scaffolds a Next.js + Tailwind + shadcn/ui application
3. Implements screens based on mockups
4. Deploys to Caddy (*.dev.apps.symph.co)
5. Pushes code to GitHub
6. Outputs the dev link

## Input Sources

**Priority order:**
1. **Figma** (if `design/figma-url.txt` exists) — use Figma designs
2. **Design artifacts** — use generated mockups and specs:
   - `design/brand-guidelines.md` — colors, typography
   - `design/design-brief.md` — UX principles, requirements
   - `design/screens.md` — screen inventory
   - `design/assets/*.png` — screen mockups

## Pipeline Execution

### Step 1: Setup (10%)

**Create project structure:**
```bash
cd /home/aria/projects
mkdir -p {product-slug}
cd {product-slug}
npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm
npm install
npx shadcn@latest init -d
```

**Read design artifacts and extract:**
- Color palette → `tailwind.config.ts` theme
- Typography → font configuration
- Screen list → page routes

**After setup:**
```
Update progress.md: [TIMESTAMP] ✓ Project scaffolded with Next.js + Tailwind + shadcn/ui
Update workflow.json: progress=10
```

### Step 2: Core Components (30%)

**Create shared components based on brand guidelines:**
- `src/components/ui/` — shadcn components
- `src/components/layout/` — header, sidebar, navigation
- `src/lib/` — utilities, constants (colors, etc.)

**Apply brand:**
- Update `tailwind.config.ts` with brand colors
- Create CSS variables in `globals.css`
- Set up fonts

**After components:**
```
Update progress.md: [TIMESTAMP] ✓ Core components and brand styling applied
Update workflow.json: progress=30
```

### Step 3: Implement Screens (70%)

**For each screen in `screens.md`:**
1. Create page at appropriate route
2. Reference the mockup image (`design/assets/screen-{name}.png`)
3. Implement layout and components
4. Add placeholder data/functionality

**Screen → Route mapping:**
- Dashboard → `/` or `/dashboard`
- Settings → `/settings`
- Feature screens → `/[feature-name]`

**After screens:**
```
Update progress.md: [TIMESTAMP] ✓ Implemented X screens: [list]
Update workflow.json: progress=70
```

### Step 4: Deploy to Caddy (85%)

**Get port from caddy-ports.json (ALWAYS use this as source of truth):**
```bash
# Get allocated port for this app
PORT=$(jq -r '.allocated["'${SLUG}'"]' /home/aria/.openclaw/workspace/agency/infra/caddy-ports.json)

# If no port allocated, use caddy-manager to allocate one
if [ "$PORT" = "null" ]; then
  ~/.openclaw/workspace/skills/caddy-manager/scripts/caddy-manager.sh add ${SLUG}
  PORT=$(jq -r '.allocated["'${SLUG}'"]' /home/aria/.openclaw/workspace/agency/infra/caddy-ports.json)
fi
```

**Build and start the server:**
```bash
cd /home/aria/products/{product-slug}/apps/main  # or /home/aria/projects/{slug}
npm run build
npm run start -- -p ${PORT} &
```

**After deploy:**
```
Update progress.md: [TIMESTAMP] ✓ Deployed to https://{slug}.dev.apps.symph.co
Update workflow.json: progress=85
```

### Step 5: Push to GitHub (100%)

**Initialize and push:**
```bash
cd /home/aria/projects/{product-slug}
git init
git add .
git commit -m "Initial commit: {product-name} MVP"

# Create GitHub repo in SymphonyAgents org (NOT symphco - that's legacy)
gh repo create SymphonyAgents/{product-slug} --private --source=. --remote=origin --push

# ALWAYS add symphdevtools as collaborator with write access
gh api -X PUT "/repos/SymphonyAgents/{product-slug}/collaborators/symphdevtools" -f permission=push
```

**After push:**
```
Update progress.md: [TIMESTAMP] ✓ Code pushed to GitHub: https://github.com/SymphonyAgents/{slug}
Update workflow.json: progress=100, status="complete"
```

## Output Artifacts

Create these files in `build/`:

### build-summary.md
```markdown
# Build Summary: {Product Name}

## Deployment
- **Dev URL:** https://{slug}.dev.apps.symph.co
- **GitHub:** https://github.com/SymphonyAgents/{slug}
- **Port:** {port}
- **Status:** ✅ Running

## Tech Stack
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- shadcn/ui

## Screens Implemented
1. Dashboard — `/`
2. [Screen] — `/[route]`
...

## Next Steps
- [ ] Connect to backend/API
- [ ] Add authentication
- [ ] Implement business logic
```

### build-summary.html
HTML card showing:
- Live preview link (prominent)
- GitHub link
- Tech stack badges
- Screen list with routes
- Status indicator

## HTML Card Design

Same dark theme as other phases:
```css
--bg: #0a0a0a;
--card: #141414;
--border: #262626;
--text: #fafafa;
--accent: #d4ff00;
```

Include:
- Big "View Live App" button with dev URL
- GitHub link
- Deployment status badge
- Screen/route list

## CRITICAL: Post-Build Restart (After Code Changes)

**When using Claude Code (copilot) to make changes, ALWAYS rebuild and restart:**

The server runs in production mode (`npm run start`), which serves pre-compiled files from `.next/`. 
Code changes are NOT visible until you rebuild and restart.

### After Every Code Change Session

```bash
# 1. Get the correct port from caddy-ports.json (ALWAYS use this!)
SLUG="your-app-slug"
PORT=$(jq -r '.allocated["'${SLUG}'"]' /home/aria/.openclaw/workspace/agency/infra/caddy-ports.json)

# 2. Build the updated code
cd /home/aria/products/${SLUG}/apps/main  # or /home/aria/projects/${SLUG}
npm run build

# 3. Kill the old server on this port
lsof -ti :${PORT} | xargs kill -TERM 2>/dev/null || true

# 4. Start the new server
npm run start -- -p ${PORT} &

# 5. Verify it's running
sleep 3
curl -s -o /dev/null -w "%{http_code}" http://localhost:${PORT}
```

### Why This Matters

```
WITHOUT restart:
  Edit code → Server still serves old .next/ → "Why isn't it updating?!"

WITH restart:
  Edit code → npm run build → kill old → start new → Changes visible ✓
```

**Rule:** Claude Code sessions should ALWAYS end with build + restart before reporting "done".

## Error Handling

If build fails:
1. Log error to progress.md
2. Set workflow status to "error"
3. Include error details for debugging
4. Don't delete partial work — human can review

## Key Points

1. **Read design artifacts first** — colors, screens, UX requirements
2. **Use web-app-builder patterns** — Next.js + Tailwind + shadcn
3. **Reference mockups** — implement based on screen-*.png images
4. **Deploy early** — get something running, then iterate
5. **Push to GitHub** — code should be version controlled
6. **Track the process** — update progress after each step
