Skip to content

Commit 14d1dae

Browse files
ducdmdevducdmdev
committed
docs: add landing page design spec
1 parent 8c515a0 commit 14d1dae

1 file changed

Lines changed: 211 additions & 0 deletions

File tree

‎docs/specs/2026-03-24-landing-page-design.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Agent Team Landing Page — Design Spec
2+
3+
**Date**: 2026-03-24
4+
**Status**: Draft
5+
6+
## Overview
7+
8+
A single-page landing page for the agent-team-plugin, hosted on GitHub Pages. Primary audience: developers already using Claude Code who want to discover and install plugins. Goal: install conversion (hero) + architecture education (scrolling sections).
9+
10+
**Style**: Terminal Dark — dark background (#0f0f23), monospace fonts, terminal-inspired UI, code snippets as visual anchors.
11+
12+
**Tech stack**: Single `index.html` with inline CSS and JS. No build tools, no dependencies, no frameworks. Deployed via GitHub Pages from a `site/` directory.
13+
14+
---
15+
16+
## Section 1: Hero
17+
18+
**Layout**: Centered, minimal, dark background.
19+
20+
**Content**:
21+
- Headline: `Agent Team` — large monospace, white
22+
- Subheadline: `Orchestrate parallel AI teammates in Claude Code` — smaller, muted gray
23+
- Install command in a terminal block with copy button: `$ claude plugin install agent-team`
24+
- Version badge: `v3.2.0` — small, muted
25+
- Scroll cue: "Watch the demo ↓" pointing to terminal section
26+
27+
**Design details**:
28+
- Background: `#0f0f23`
29+
- No navigation bar — single page, just scroll
30+
- Small GitHub icon in top-right corner linking to repo
31+
- Hero is intentionally short — exists to give context before the terminal demo
32+
33+
---
34+
35+
## Section 2: Terminal Demo
36+
37+
**The centerpiece.** A realistic terminal window that auto-types the full 3-stage pipeline.
38+
39+
### Visual
40+
- Dark terminal chrome: title bar with 3 colored dots (red/yellow/green), window title "claude"
41+
- Monospace font (system monospace stack)
42+
- Blinking cursor
43+
- Each stage has a colored left border accent:
44+
- Plan: purple (#a78bfa)
45+
- Execute: blue (#60a5fa)
46+
- Audit: green (#4ade80)
47+
48+
### Animation Sequence (~30 seconds)
49+
1. Type effect: `You > use agent team to refactor the auth module`
50+
2. Pause (500ms), then Stage 1 — Plan output appears line by line:
51+
- `━━ Stage 1 — Plan ━━`
52+
- `[Planning team created: 2 Researchers + 1 Plan Reviewer]`
53+
- Researcher FINDING lines (2-3 lines)
54+
- `plan-reviewer: PLAN_REVIEW: status=approved`
55+
- Team plan summary (teammates, task breakdown)
56+
- `[Planning team shut down]`
57+
- `Approve?`
58+
3. Type: `You > y`
59+
4. Stage 2 — Execute output:
60+
- `━━ Stage 2 — Execute ━━`
61+
- `[Execution team created: 2 Implementers + 1 Reviewer + 1 Execute Reviewer]`
62+
- PLAN_PROPOSAL → PLAN_APPROVED
63+
- STARTING → COMPLETED lines
64+
- BLOCKED with error_type=recoverable + Recovery
65+
- EXECUTE_REVIEW: status=ready_for_audit
66+
- `[Execution team shut down]`
67+
5. Stage 3 — Audit output:
68+
- `━━ Stage 3 — Audit ━━`
69+
- `[Audit team created: 1 Reviewer + 1 Elegance Reviewer + 1 Audit Reviewer]`
70+
- Completion gate (8/8 passed)
71+
- ELEGANCE_REVIEW: overall_score=4.2
72+
- Lessons captured
73+
- AUDIT_REVIEW: status=approved
74+
- Final summary line
75+
- `[Audit team shut down]`
76+
77+
### Controls
78+
- Auto-starts when scrolled into view (IntersectionObserver)
79+
- "Skip" button in top-right corner of terminal to jump to final state
80+
- Click terminal to replay from start
81+
- Lines appear with ~50ms delay between characters, ~200ms pause between lines
82+
- Stage headers appear with 500ms pause before content
83+
84+
### Content Source
85+
Directly from the README demo walkthrough (lines 24-104 of README.md). Proven accurate against v3.2.0 architecture.
86+
87+
---
88+
89+
## Section 3: Pipeline Overview
90+
91+
**Layout**: 3-column grid below the terminal, centered.
92+
93+
### Columns
94+
95+
| Column | Accent Color | Header | Team |
96+
|--------|-------------|--------|------|
97+
| Plan | Purple (#a78bfa) | Stage 1: Plan | Researcher + Analyst + Plan Reviewer |
98+
| Execute | Blue (#60a5fa) | Stage 2: Execute | Implementers + Tester + Reviewer + Execute Reviewer |
99+
| Audit | Green (#4ade80) | Stage 3: Audit | Reviewer + Elegance Reviewer + Audit Reviewer |
100+
101+
### Content per Column
102+
- Stage name with colored top border
103+
- Team composition (role list)
104+
- 3 key features as bullet points:
105+
- Plan: Prior context loading, plan-mode gate, 7-check plan audit
106+
- Execute: Error recovery loop, coordination patterns, file ownership enforcement
107+
- Audit: 8 completion gates, elegance scoring (1-5), lessons capture + pattern library
108+
109+
### Design
110+
- Dark cards (#1a1a2e background)
111+
- Colored top border (4px, stage color)
112+
- Monospace for role names, sans-serif for descriptions
113+
- Responsive: stacks to single column on mobile
114+
115+
---
116+
117+
## Section 4: Features Grid
118+
119+
**Layout**: 2x3 grid of feature cards.
120+
121+
### Cards
122+
123+
| Card | Accent Text | Description |
124+
|------|------------|-------------|
125+
| 13 Hooks | `exit 2` | Block premature completion, enforce file ownership, validate task graphs, limit plan revisions, enforce pre-shutdown commits |
126+
| 13 Roles | `SendMessage` | Implementers, researchers, reviewers, analysts, elegance reviewer — each with scoped tools and recovery class |
127+
| Error Recovery | `error_type=recoverable` | Classify errors (retry/recoverable/design_flaw), auto-retry with pattern library, bounded recovery cycles |
128+
| Elegance Review | `score=4.2/5` | 5-dimension quality: simplicity, consistency, readability, testability, minimal impact. Advisory, not blocking |
129+
| Lessons Capture | `lessons.md` | Post-execution insights feed future teams. Global error pattern library at ~/.claude/agent-team-patterns.json |
130+
| Team Per Stage | `TeamCreate → TeamDelete` | Each stage owns its lifecycle. Ephemeral teams, persistent workspace. 3 teams per pipeline run |
131+
132+
### Design
133+
- Dark cards (#1a1a2e background)
134+
- Accent text in monospace, colored per feature category
135+
- 2-line description in muted gray
136+
- No icons/emojis — code snippets as visual anchors
137+
- Responsive: 2x3 → 1x6 on mobile
138+
139+
---
140+
141+
## Section 5: Install + Footer
142+
143+
### Install
144+
- Centered section with prominent heading: "Get Started"
145+
- Two terminal blocks side by side (or stacked):
146+
```
147+
# Install from marketplace
148+
$ claude plugin marketplace add ducdmdev/agent-team-plugin
149+
$ claude plugin install agent-team
150+
```
151+
```
152+
# Enable agent teams feature
153+
$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
154+
```
155+
- Each block has a copy button
156+
- Prerequisites listed below: Claude Code CLI (required), `jq` (required for hooks, graceful fallback), `git` (optional)
157+
158+
### Footer
159+
- Single line: GitHub repo link | v3.2.0 | "Made for Claude Code developers"
160+
- Dark background, muted text
161+
- No social links, no newsletter
162+
163+
---
164+
165+
## Technical Implementation
166+
167+
### File Structure
168+
```
169+
site/
170+
├── index.html # Single file — all CSS and JS inline
171+
└── assets/
172+
└── demo.gif # Fallback for no-JS (copy from repo root assets/)
173+
```
174+
175+
### GitHub Pages Deployment
176+
- Source: `site/` directory on main branch
177+
- Settings: GitHub repo → Settings → Pages → Source: Deploy from branch, folder: `/site`
178+
- URL: `https://ducdmdev.github.io/agent-team-plugin/`
179+
180+
### Responsive Breakpoints
181+
- Desktop: ≥1024px — 3-column pipeline, 2x3 features grid
182+
- Tablet: 768-1023px — 2-column features, stacked pipeline
183+
- Mobile: <768px — single column everything, terminal demo still full width
184+
185+
### Performance
186+
- No external dependencies (no CDN, no fonts, no analytics)
187+
- Single HTTP request (inline CSS + JS)
188+
- Terminal animation uses requestAnimationFrame for smooth typing
189+
- IntersectionObserver for scroll-triggered animation start
190+
- Total page weight target: <50KB
191+
192+
### Accessibility
193+
- Semantic HTML (header, main, section, footer)
194+
- Terminal demo has aria-label describing what it shows
195+
- Skip button is keyboard-accessible
196+
- Color contrast meets WCAG AA for text on dark background
197+
- Reduced motion: respect `prefers-reduced-motion` — show final state immediately instead of animation
198+
199+
---
200+
201+
## Content Source
202+
203+
All content derives from existing documentation:
204+
- Demo output: `README.md` lines 24-104
205+
- Hook descriptions: `README.md` Hooks section
206+
- Role list: `docs/teammate-roles.md`
207+
- Pipeline flow: `README.md` How It Works section
208+
- Install commands: `README.md` Installation section
209+
- Feature details: `CHANGELOG.md` v3.0.0-v3.2.0 entries
210+
211+
No new content needs to be written — only reformatted for the landing page layout.

0 commit comments

Comments
 (0)