buildcrew 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.ko.md +60 -87
  2. package/README.md +71 -91
  3. package/agents/designer.md +217 -13
  4. package/package.json +2 -1
package/README.ko.md CHANGED
@@ -1,26 +1,26 @@
1
1
  # buildcrew
2
2
 
3
+ > [English](README.md) | **한국어** | [문서](https://buildcrew-landing.vercel.app)
4
+
3
5
  Claude Code를 위한 11개 AI 에이전트 — 9개 운영 모드로 자동 오케스트레이션되는 개발 팀.
4
6
 
5
7
  ```bash
6
8
  npx buildcrew
7
9
  ```
8
10
 
9
- > [English](README.md) | **한국어**
10
-
11
11
  ---
12
12
 
13
13
  ## 왜 buildcrew인가?
14
14
 
15
15
  AI 코딩 에이전트는 강력하지만 구조 없이는 일관성 없는 결과를 냅니다. buildcrew는 Claude Code에 다음을 제공합니다:
16
16
 
17
- - **팀** — 명확한 역할을 가진 11개 전문 에이전트
17
+ - **팀** — 11개 전문 에이전트 (5 opus + 6 sonnet)
18
18
  - **프로세스** — 품질 게이트와 반복을 갖춘 순차 파이프라인
19
- - **하네스** — 프로젝트 컨텍스트, 규칙, 도메인 지식이 모든 에이전트에 내장
19
+ - **하네스** — 코드베이스에서 자동 감지한 프로젝트 컨텍스트
20
20
  - **오케스트레이터** — `@constitution`에게 말하면 자동으로 적절한 에이전트 배치
21
21
 
22
22
  ```
23
- 나: @constitution 유저 대시보드 추가해줘
23
+ 나: @constitution 유저 인증 추가해줘
24
24
  크루: 기획자 → 디자이너 → 개발자 → QA → 브라우저 QA → 리뷰어 → 배포
25
25
  ```
26
26
 
@@ -34,13 +34,11 @@ AI 코딩 에이전트는 강력하지만 구조 없이는 일관성 없는 결
34
34
  # 1. 에이전트 설치
35
35
  npx buildcrew
36
36
 
37
- # 2. 프로젝트 하네스 설정 (인터랙티브)
37
+ # 2. 프로젝트 하네스 자동 생성 (질문 없음)
38
38
  npx buildcrew init
39
39
 
40
- # 3. 추가 컨텍스트 (선택)
41
- npx buildcrew add erd
42
- npx buildcrew add architecture
43
- npx buildcrew add design-system
40
+ # 3. 커스터마이징 (생성된 파일에서 <!-- 주석 --> 부분만 수정)
41
+ code .claude/harness/
44
42
 
45
43
  # 4. 사용
46
44
  @constitution 유저 대시보드 추가해줘
@@ -50,52 +48,57 @@ npx buildcrew add design-system
50
48
 
51
49
  ## 하네스 엔지니어링
52
50
 
53
- 하네스는 "범용 AI 출력"과 "내 프로젝트에 맞는 코드"의 차이를 만듭니다.
51
+ `npx buildcrew init`은 코드베이스를 스캔해서 프로젝트 하네스를 생성합니다 — **질문 0개**.
54
52
 
55
- ```bash
56
- npx buildcrew init
57
- ```
53
+ ### 자동 감지 항목
58
54
 
59
- 인터랙티브 설정으로 핵심 하네스 파일 생성:
55
+ | 카테고리 | 감지 대상 |
56
+ |---------|----------|
57
+ | 프레임워크 | Next.js, Nuxt, React, Vue, SvelteKit, Express |
58
+ | 언어/CSS | TypeScript, TailwindCSS, Framer Motion |
59
+ | 데이터베이스 | Supabase, Prisma, Drizzle, MongoDB |
60
+ | 인증 | NextAuth, Supabase Auth, Firebase Auth |
61
+ | 결제 | Stripe, Paddle, Toss Payments |
62
+ | AI | OpenAI, Anthropic, Google AI |
63
+ | 배포 | Vercel, Netlify, Fly.io, Docker |
64
+ | 컴포넌트 | `src/components/` 스캔 |
65
+ | API 라우트 | `src/app/api/` 스캔 |
66
+ | 다국어 | i18n 디렉토리 스캔 |
60
67
 
61
- ```
62
- [1/3] 프로젝트 컨텍스트
63
- 프로젝트명, 설명, 기술 스택 (자동 감지), 배포 타겟, 프로덕션 URL
68
+ ### 생성되는 파일
64
69
 
65
- [2/3] 팀 규칙
66
- 코딩 컨벤션, 우선순위, 금지사항, 품질 기준, 리뷰 규칙
70
+ 감지 결과에 따라 관련 하네스 파일이 자동 생성:
67
71
 
68
- [3/3] 도메인 지식
69
- 업종, 유저 타입, 도메인 용어, 비즈니스 룰
70
72
  ```
73
+ .claude/harness/
74
+ ├── project.md ← 항상 (프로젝트 컨텍스트, 스택, 컴포넌트, API 라우트)
75
+ ├── rules.md ← 항상 (프레임워크에 맞는 스마트 기본값)
76
+ ├── erd.md ← DB 감지 시
77
+ ├── api-spec.md ← API 라우트 발견 시
78
+ ├── design-system.md ← TailwindCSS 감지 시
79
+ ├── architecture.md ← 항상
80
+ └── user-flow.md ← i18n 또는 5개+ 컴포넌트 시
81
+ ```
82
+
83
+ ### 커스터마이징
71
84
 
72
- ### 템플릿으로 추가 컨텍스트 제공
85
+ 생성된 파일은 `<!-- HTML 주석 -->`으로 채워야 할 부분을 표시합니다. 나머지는 코드베이스에서 자동으로 채워져 있습니다.
73
86
 
74
87
  ```bash
75
- npx buildcrew add erd # DB 스키마 & 관계
76
- npx buildcrew add architecture # 시스템 아키텍처
77
- npx buildcrew add api-spec # API 엔드포인트 & 계약
78
- npx buildcrew add design-system # 색상, 타이포, 컴포넌트
79
- npx buildcrew add glossary # 도메인 용어 & 유저 역할
80
- npx buildcrew add user-flow # 유저 여정 & 페이지 맵
81
- npx buildcrew add env-vars # 환경변수 가이드
88
+ npx buildcrew harness # 어떤 파일을 편집해야 하는지 확인
82
89
  ```
83
90
 
84
91
  ### 열린 구조
85
92
 
86
- 템플릿에 제한되지 않습니다. `.claude/harness/`에 아무 `.md` 파일이나 추가하세요:
93
+ `.claude/harness/`에 아무 `.md` 파일이나 추가 가능 — 에이전트가 전부 읽음:
87
94
 
88
- ```
89
- .claude/harness/
90
- ├── project.md ← 핵심 (init으로 생성)
91
- ├── rules.md ← 핵심 (init으로 생성)
92
- ├── erd.md ← 템플릿 (add로 추가)
93
- ├── architecture.md ← 템플릿 (add로 추가)
94
- ├── 내맘대로.md ← 직접 작성 (에이전트가 읽음)
95
- └── 무엇이든.md ← 아무 .md 파일 가능
95
+ ```bash
96
+ npx buildcrew add glossary # 템플릿에서 추가
97
+ npx buildcrew add env-vars # 템플릿에서 추가
98
+ echo "# 메모" > .claude/harness/내메모.md # 직접 생성도 가능
96
99
  ```
97
100
 
98
- ### 하네스 파일 → 에이전트 라우팅
101
+ ### 에이전트 라우팅
99
102
 
100
103
  | 파일 | 읽는 에이전트 |
101
104
  |------|-------------|
@@ -104,16 +107,7 @@ npx buildcrew add env-vars # 환경변수 가이드
104
107
  | `design-system.md` | designer |
105
108
  | `glossary.md`, `user-flow.md` | planner, designer, browser-qa |
106
109
  | `env-vars.md` | developer, security-auditor |
107
- | 커스텀 파일 | reviewer, security-auditor (전부 읽음) |
108
-
109
- ### 하네스 관리
110
-
111
- ```bash
112
- npx buildcrew harness # 하네스 파일 상태 확인
113
- npx buildcrew add # 사용 가능한 템플릿 목록
114
- npx buildcrew add erd # 특정 템플릿 추가
115
- npx buildcrew init --force # 핵심 파일 재생성
116
- ```
110
+ | 커스텀 `.md` | reviewer, security-auditor (전부 읽음) |
117
111
 
118
112
  ---
119
113
 
@@ -123,8 +117,8 @@ npx buildcrew init --force # 핵심 파일 재생성
123
117
 
124
118
  | 에이전트 | 모델 | 역할 |
125
119
  |---------|------|------|
126
- | **planner** | opus | 6가지 강제 질문 + 4관점 자체 리뷰 (CEO, 엔지니어링, 디자인, QA). 관점별 1-10점 채점. |
127
- | **designer** | opus | 웹에서 UI/UX 레퍼런스 수집, Playwright로 실제 사이트 스크린샷, Figma MCP 통합, 프로덕션 React/Next.js 컴포넌트 작성. AI 슬롭 블랙리스트. |
120
+ | **planner** | opus | 6가지 강제 질문 + 4관점 자체 리뷰 (CEO, 엔지니어링, 디자인, QA). 관점별 1-10점. |
121
+ | **designer** | opus | 웹에서 UI/UX 레퍼런스 수집 → Playwright 스크린샷 → Figma MCP → 프로덕션 컴포넌트. AI 슬롭 블랙리스트. |
128
122
  | **developer** | sonnet | 기획서 + 디자인 + 하네스 규칙에 따라 구현. |
129
123
 
130
124
  ### 품질 팀
@@ -140,7 +134,7 @@ npx buildcrew init --force # 핵심 파일 재생성
140
134
 
141
135
  | 에이전트 | 모델 | 역할 |
142
136
  |---------|------|------|
143
- | **security-auditor** | opus | OWASP Top 10 + STRIDE 위협 모델. 10단계 감사. |
137
+ | **security-auditor** | opus | OWASP Top 10 + STRIDE 위협 모델. 10단계 감사 + 신뢰도 게이트. |
144
138
  | **canary-monitor** | sonnet | 배포 후 프로덕션 헬스 — 페이지, API, 콘솔, 성능 비교. |
145
139
  | **shipper** | sonnet | 릴리즈 파이프라인 — 테스트 → 버전 → 체인지로그 → PR. |
146
140
 
@@ -163,32 +157,27 @@ npx buildcrew init --force # 핵심 파일 재생성
163
157
  | **Browser QA** | "브라우저 테스트해줘" | Playwright 테스트 + 건강 점수 |
164
158
  | **Security** | "보안 점검해줘" | OWASP + STRIDE + 시크릿 + 의존성 |
165
159
  | **Debug** | "왜 로그인이 안 돼?" | 4단계 근본 원인 조사 |
166
- | **Health** | "헬스체크 돌려줘" | 품질 대시보드 (타입, 린트, 의존성, i18n) |
160
+ | **Health** | "헬스체크 돌려줘" | 품질 대시보드 |
167
161
  | **Canary** | "배포 확인해줘" | 프로덕션 모니터링 |
168
162
  | **Review** | "코드 리뷰해줘" | 멀티 전문가 + 적대적 + 자동 수정 |
169
163
  | **Ship** | "배포해줘" | 테스트 → 버전 → 체인지로그 → PR |
170
164
 
171
165
  ### 모드 체이닝
172
166
 
173
- Constitution이 다음 모드를 자동 제안:
174
- - Feature 완료 → Ship 제안
175
- - Ship 완료 → Canary 제안
176
- - Canary CRITICAL → Debug 트리거
167
+ Feature 완료 → Ship → Canary. Canary CRITICAL → Debug.
177
168
 
178
169
  ---
179
170
 
180
171
  ## 기능 파이프라인
181
172
 
182
- 각 기능이 완전한 문서 체인을 생성:
183
-
184
173
  ```
185
174
  .claude/pipeline/{기능명}/
186
175
  ├── 01-plan.md 요구사항 + 4관점 리뷰 점수
187
- ├── 02-references.md 실제 사이트에서 수집한 UI/UX 레퍼런스
188
- ├── 02-design.md 디자인 결정 + 컴포넌트 스펙
176
+ ├── 02-references.md UI/UX 레퍼런스
177
+ ├── 02-design.md 디자인 결정 + 스펙
189
178
  ├── 03-dev-notes.md 구현 노트 + 변경 파일
190
179
  ├── 04-qa-report.md 수용 기준 검증
191
- ├── 05-browser-qa.md 건강 점수 + 스크린샷 + 플로우
180
+ ├── 05-browser-qa.md 건강 점수 + 스크린샷
192
181
  ├── 06-review.md 리뷰 발견사항 + 자동 수정
193
182
  └── 07-ship.md PR URL + 릴리즈 노트
194
183
  ```
@@ -200,36 +189,20 @@ Constitution이 다음 모드를 자동 제안:
200
189
  | 명령어 | 설명 |
201
190
  |--------|------|
202
191
  | `npx buildcrew` | 11개 에이전트 설치 |
203
- | `npx buildcrew init` | 프로젝트 하네스 설정 (인터랙티브) |
192
+ | `npx buildcrew init` | 하네스 자동 생성 (질문 없음) |
204
193
  | `npx buildcrew init --force` | 하네스 재생성 |
205
- | `npx buildcrew add` | 사용 가능한 템플릿 목록 |
206
- | `npx buildcrew add <type>` | 하네스 템플릿 추가 |
207
- | `npx buildcrew harness` | 하네스 파일 상태 확인 |
208
- | `npx buildcrew --force` | 기존 에이전트 덮어쓰기 |
209
- | `npx buildcrew --list` | 에이전트 목록 (모델 포함) |
194
+ | `npx buildcrew add` | 템플릿 목록 |
195
+ | `npx buildcrew add <name>` | 템플릿 추가 |
196
+ | `npx buildcrew harness` | 하네스 파일 상태 |
197
+ | `npx buildcrew --force` | 에이전트 덮어쓰기 |
198
+ | `npx buildcrew --list` | 에이전트 목록 |
210
199
  | `npx buildcrew --uninstall` | 에이전트 제거 |
211
- | `npx buildcrew --version` | 버전 확인 |
212
200
 
213
201
  ## 요구사항
214
202
 
215
203
  - **필수**: [Claude Code](https://claude.ai/code) CLI
216
- - **선택**: [Playwright MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-servers/playwright) — browser-qa, canary-monitor, designer용
217
- - **선택**: [Figma MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-servers/figma) — designer용
218
-
219
- ```bash
220
- # 실제 브라우저 테스트 활성화
221
- claude mcp add playwright -- npx @anthropic-ai/mcp-server-playwright
222
- ```
223
-
224
- ## 커스터마이징
225
-
226
- 모든 파일 수정 가능:
227
-
228
- ```
229
- .claude/agents/ 에이전트 정의 — 역할, 도구, 지시사항, 모델 수정
230
- .claude/harness/ 프로젝트 컨텍스트 — 언제든 수정, 아무 .md 추가
231
- .claude/pipeline/ 출력 문서 — 기능별 자동 생성
232
- ```
204
+ - **선택**: [Playwright MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-servers/playwright) — browser-qa, canary-monitor, designer
205
+ - **선택**: [Figma MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-servers/figma) — designer
233
206
 
234
207
  ## 라이선스
235
208
 
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # buildcrew
2
2
 
3
- > **English** | [한국어](README.ko.md)
3
+ > **English** | [한국어](README.ko.md) | [Docs](https://buildcrew-landing.vercel.app)
4
4
 
5
5
  11 AI agents for Claude Code — auto-orchestrated dev team with 9 operating modes.
6
6
 
@@ -14,9 +14,9 @@ npx buildcrew
14
14
 
15
15
  AI coding agents are powerful, but without structure they produce inconsistent results. buildcrew gives Claude Code:
16
16
 
17
- - **A team** — 11 specialized agents, each with a clear role
17
+ - **A team** — 11 specialized agents (5 opus + 6 sonnet), each with a clear role
18
18
  - **A process** — sequential pipeline with quality gates and iteration
19
- - **A harness** — your project context, rules, and domain knowledge baked in
19
+ - **A harness** — your project context auto-detected from your codebase
20
20
  - **An orchestrator** — just talk to `@constitution`, it routes automatically
21
21
 
22
22
  ```
@@ -34,13 +34,11 @@ No external dependencies. No runtime. No binaries. Just Markdown.
34
34
  # 1. Install agents
35
35
  npx buildcrew
36
36
 
37
- # 2. Set up project harness (interactive)
37
+ # 2. Auto-generate project harness (zero questions asked)
38
38
  npx buildcrew init
39
39
 
40
- # 3. Add more context (optional)
41
- npx buildcrew add erd
42
- npx buildcrew add architecture
43
- npx buildcrew add design-system
40
+ # 3. Customize (replace <!-- comments --> in generated files)
41
+ code .claude/harness/
44
42
 
45
43
  # 4. Start working
46
44
  @constitution Add user dashboard
@@ -50,54 +48,57 @@ npx buildcrew add design-system
50
48
 
51
49
  ## Harness Engineering
52
50
 
53
- The harness is what separates "generic AI output" from "code that fits your project."
51
+ `npx buildcrew init` scans your codebase and generates a project harness — **zero questions asked**.
54
52
 
55
- ```bash
56
- npx buildcrew init
57
- ```
53
+ ### What it auto-detects
58
54
 
59
- Interactive setup creates core harness files:
55
+ | Category | Detected from |
56
+ |----------|--------------|
57
+ | Framework | package.json (Next.js, Nuxt, React, Vue, SvelteKit, Express) |
58
+ | Language | TypeScript, TailwindCSS, Framer Motion |
59
+ | Database | Supabase, Prisma, Drizzle, MongoDB |
60
+ | Auth | NextAuth, Supabase Auth, Firebase Auth |
61
+ | Payments | Stripe, Paddle, Toss Payments |
62
+ | AI | OpenAI, Anthropic, Google AI |
63
+ | Deploy | Vercel, Netlify, Fly.io, Docker |
64
+ | Components | Scans `src/components/` |
65
+ | API Routes | Scans `src/app/api/` |
66
+ | Locales | Scans i18n directories |
60
67
 
61
- ```
62
- [1/3] Project Context
63
- Project name, description, tech stack (auto-detected), deploy target, production URL
68
+ ### What it generates
64
69
 
65
- [2/3] Team Rules
66
- Coding conventions, priorities, what to avoid, quality standards, review rules
70
+ Based on detection, relevant harness files are auto-created:
67
71
 
68
- [3/3] Domain Knowledge
69
- Industry, user types, domain terms, business rules
70
72
  ```
73
+ .claude/harness/
74
+ ├── project.md ← always (project context, stack, components, API routes)
75
+ ├── rules.md ← always (smart defaults for your framework)
76
+ ├── erd.md ← if database detected
77
+ ├── api-spec.md ← if API routes found
78
+ ├── design-system.md ← if TailwindCSS detected
79
+ ├── architecture.md ← always
80
+ └── user-flow.md ← if i18n or 5+ components
81
+ ```
82
+
83
+ ### Customize
71
84
 
72
- ### Add more context with templates
85
+ Generated files use `<!-- HTML comments -->` for parts you need to fill in. Everything else is pre-filled from your codebase.
73
86
 
74
87
  ```bash
75
- npx buildcrew add erd # Database schema & relationships
76
- npx buildcrew add architecture # System architecture overview
77
- npx buildcrew add api-spec # API endpoints & contracts
78
- npx buildcrew add design-system # Colors, typography, components
79
- npx buildcrew add glossary # Domain terms & user roles
80
- npx buildcrew add user-flow # User journeys & page map
81
- npx buildcrew add env-vars # Environment variables guide
88
+ npx buildcrew harness # Check which files need editing
82
89
  ```
83
90
 
84
91
  ### The harness is open
85
92
 
86
- Not limited to templates. Create any `.md` file in `.claude/harness/`:
93
+ Add any `.md` file to `.claude/harness/` — agents read them all:
87
94
 
88
- ```
89
- .claude/harness/
90
- ├── project.md ← core (auto by init)
91
- ├── rules.md ← core (auto by init)
92
- ├── erd.md ← template
93
- ├── architecture.md ← template
94
- ├── design-system.md ← template
95
- ├── glossary.md ← template
96
- ├── my-custom-notes.md ← your own file (agents read it too)
97
- └── anything.md ← any .md file works
95
+ ```bash
96
+ npx buildcrew add glossary # Add from template
97
+ npx buildcrew add env-vars # Add from template
98
+ echo "# Notes" > .claude/harness/my-notes.md # Or create your own
98
99
  ```
99
100
 
100
- All agents read harness files before every task. Constitution routes the right files to the right agents:
101
+ ### Agent routing
101
102
 
102
103
  | File | Routed to |
103
104
  |------|-----------|
@@ -106,16 +107,7 @@ All agents read harness files before every task. Constitution routes the right f
106
107
  | `design-system.md` | designer |
107
108
  | `glossary.md`, `user-flow.md` | planner, designer, browser-qa |
108
109
  | `env-vars.md` | developer, security-auditor |
109
- | Custom files | reviewer, security-auditor (read ALL) |
110
-
111
- ### Manage the harness
112
-
113
- ```bash
114
- npx buildcrew harness # Show status of all harness files
115
- npx buildcrew add # List available templates
116
- npx buildcrew add erd # Add a specific template
117
- npx buildcrew init --force # Regenerate core files from scratch
118
- ```
110
+ | Custom `.md` files | reviewer, security-auditor (read ALL) |
119
111
 
120
112
  ---
121
113
 
@@ -125,32 +117,32 @@ npx buildcrew init --force # Regenerate core files from scratch
125
117
 
126
118
  | Agent | Model | Role |
127
119
  |-------|-------|------|
128
- | **planner** | opus | 6 Forcing Questions + 4-Lens Self-Review (CEO, Engineering, Design, QA). Produces battle-tested plans scored 1-10 per lens. |
129
- | **designer** | opus | Searches web for UI/UX references, screenshots real sites with Playwright, integrates Figma MCP, writes production React/Next.js components. AI slop blacklist enforced. |
130
- | **developer** | sonnet | Implements features following plan + design + harness conventions. Self-reviews before handoff. |
120
+ | **planner** | opus | 6 Forcing Questions + 4-Lens Self-Review (CEO, Engineering, Design, QA). Plans scored 1-10 per lens. |
121
+ | **designer** | opus | Web research for UI/UX references → Playwright screenshots → Figma MCP → production components. AI slop blacklist. |
122
+ | **developer** | sonnet | Implements features following plan + design + harness conventions. |
131
123
 
132
124
  ### Quality Team
133
125
 
134
126
  | Agent | Model | Role |
135
127
  |-------|-------|------|
136
- | **qa-tester** | sonnet | Code-level verification — types, lint, build, acceptance criteria check. |
137
- | **browser-qa** | sonnet | Real browser testing via Playwright MCP — user flows, responsive (375/768/1440px), console errors, network, health score (0-100). |
138
- | **reviewer** | opus | 4-specialist parallel review (security, performance, testing, maintainability) + adversarial pass + auto-fix. Fix-first approach. |
139
- | **health-checker** | sonnet | Code quality dashboard — 7-category weighted score (0-10), trend tracking, top 5 actionable items. |
128
+ | **qa-tester** | sonnet | Code-level verification — types, lint, build, acceptance criteria. |
129
+ | **browser-qa** | sonnet | Real browser testing via Playwright MCP — flows, responsive, console, health score (0-100). |
130
+ | **reviewer** | opus | 4-specialist parallel review (security, perf, testing, maintainability) + adversarial pass + auto-fix. |
131
+ | **health-checker** | sonnet | Code quality dashboard — 7-category weighted 0-10 score + trends. |
140
132
 
141
133
  ### Security & Ops
142
134
 
143
135
  | Agent | Model | Role |
144
136
  |-------|-------|------|
145
- | **security-auditor** | opus | OWASP Top 10 + STRIDE threat model. 10-phase audit. Secrets scan, dependency audit, AI/LLM security. Confidence gate (8/10 standard, 2/10 comprehensive). |
146
- | **canary-monitor** | sonnet | Post-deploy health — page availability, API status, console errors, performance vs baseline. |
147
- | **shipper** | sonnet | Release pipeline — pre-flight checks → version bump → changelog → commit → push → PR creation. |
137
+ | **security-auditor** | opus | OWASP Top 10 + STRIDE threat model. 10-phase audit with confidence gate. |
138
+ | **canary-monitor** | sonnet | Post-deploy health — pages, APIs, console, performance vs baseline. |
139
+ | **shipper** | sonnet | Release pipeline — test → version bump → changelog → PR. |
148
140
 
149
141
  ### Specialist
150
142
 
151
143
  | Agent | Model | Role |
152
144
  |-------|-------|------|
153
- | **investigator** | sonnet | Root cause debugging. 4 phases: investigate → hypothesize → test → fix. Edit freeze on unrelated code. "No fix without root cause." |
145
+ | **investigator** | sonnet | Root cause debugging. 4-phase investigation. Edit freeze on unrelated code. |
154
146
 
155
147
  ---
156
148
 
@@ -158,11 +150,11 @@ npx buildcrew init --force # Regenerate core files from scratch
158
150
 
159
151
  Talk to `@constitution` naturally. It auto-detects the mode.
160
152
 
161
- | Mode | Example | What happens |
162
- |------|---------|-------------|
153
+ | Mode | Example | Pipeline |
154
+ |------|---------|----------|
163
155
  | **Feature** | "Add user dashboard" | Plan → Design → Dev → QA → Browser QA → Review |
164
156
  | **Project Audit** | "full project audit" | Scan → Prioritize → Fix → Verify (loop) |
165
- | **Browser QA** | "browser qa localhost:3000" | Playwright tests flows, responsive, console |
157
+ | **Browser QA** | "browser qa localhost:3000" | Playwright tests + health score |
166
158
  | **Security** | "security audit" | OWASP + STRIDE + secrets + deps |
167
159
  | **Debug** | "debug: login broken" | 4-phase root cause investigation |
168
160
  | **Health** | "health check" | Quality dashboard (types, lint, deps, i18n) |
@@ -173,8 +165,7 @@ Talk to `@constitution` naturally. It auto-detects the mode.
173
165
  ### Mode chaining
174
166
 
175
167
  Constitution auto-suggests the next mode:
176
- - Feature complete → Ship
177
- - Ship complete → Canary
168
+ - Feature complete → Ship → Canary
178
169
  - Canary CRITICAL → Debug
179
170
 
180
171
  ---
@@ -190,7 +181,7 @@ Each feature generates a full document chain:
190
181
  ├── 02-design.md Design decisions + component specs
191
182
  ├── 03-dev-notes.md Implementation notes + files changed
192
183
  ├── 04-qa-report.md Acceptance criteria verification
193
- ├── 05-browser-qa.md Health score + screenshots + flow results
184
+ ├── 05-browser-qa.md Health score + screenshots + flows
194
185
  ├── 06-review.md Review findings + auto-fixes applied
195
186
  └── 07-ship.md PR URL + release notes
196
187
  ```
@@ -201,15 +192,15 @@ Each feature generates a full document chain:
201
192
 
202
193
  | Command | Description |
203
194
  |---------|-------------|
204
- | `npx buildcrew` | Install 11 agents to `.claude/agents/` |
205
- | `npx buildcrew init` | Set up project harness (interactive) |
206
- | `npx buildcrew init --force` | Regenerate harness from scratch |
207
- | `npx buildcrew add` | List available harness templates |
208
- | `npx buildcrew add <type>` | Add a harness template (erd, architecture, etc.) |
209
- | `npx buildcrew harness` | Show status of all harness files |
210
- | `npx buildcrew --force` | Overwrite existing agent files |
211
- | `npx buildcrew --list` | List all agents with models |
212
- | `npx buildcrew --uninstall` | Remove installed agents |
195
+ | `npx buildcrew` | Install 11 agents |
196
+ | `npx buildcrew init` | Auto-generate harness (zero questions) |
197
+ | `npx buildcrew init --force` | Regenerate harness |
198
+ | `npx buildcrew add` | List harness templates |
199
+ | `npx buildcrew add <name>` | Add a template (erd, architecture, etc.) |
200
+ | `npx buildcrew harness` | Show harness file status |
201
+ | `npx buildcrew --force` | Overwrite existing agents |
202
+ | `npx buildcrew --list` | List agents with models |
203
+ | `npx buildcrew --uninstall` | Remove agents |
213
204
  | `npx buildcrew --version` | Show version |
214
205
 
215
206
  ## Requirements
@@ -225,31 +216,20 @@ claude mcp add playwright -- npx @anthropic-ai/mcp-server-playwright
225
216
 
226
217
  ## Customization
227
218
 
228
- Every file is editable:
229
-
230
219
  ```
231
- .claude/agents/ Agent definitions — edit roles, tools, instructions, model
232
- .claude/harness/ Project context — edit anytime, add any .md file
220
+ .claude/agents/ Agent definitions — edit roles, tools, model
221
+ .claude/harness/ Project context — edit anytime, add any .md
233
222
  .claude/pipeline/ Output documents — auto-generated per feature
234
223
  ```
235
224
 
236
- Change an agent's model:
237
- ```yaml
238
- # In any agent .md file
239
- model: opus # or sonnet, haiku
240
- ```
241
-
242
225
  ## Architecture
243
226
 
244
227
  ```
245
228
  @constitution (orchestrator, opus)
246
229
  │
247
- ├─ reads .claude/harness/*.md (project context)
248
- │
230
+ ├─ reads .claude/harness/*.md
249
231
  ├─ detects mode from user message
250
- │
251
- ├─ dispatches agents with relevant harness context
252
- │
232
+ ├─ dispatches agents with harness context
253
233
  └─ enforces quality gates + iteration
254
234
  │
255
235
  ├── Build: planner → designer → developer
package/agents/designer.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: designer
3
- description: UI/UX designer agent (opus) - researches references from the web, analyzes trends, designs with Figma MCP, and publishes production-ready UI components
3
+ description: UI/UX designer & motion engineer (opus) - researches references, designs with Figma MCP, builds production components with animations, scroll effects, gestures, and interactive elements
4
4
  model: opus
5
5
  tools:
6
6
  - Read
@@ -31,7 +31,7 @@ tools:
31
31
 
32
32
  > **Harness**: Before starting, read `.claude/harness/project.md` and `.claude/harness/rules.md` if they exist. Follow all team rules defined there.
33
33
 
34
- You are a **Senior UI/UX Designer & Front-end Developer** who researches real-world references, designs with intention, and ships production-ready UI components. You don't guess at design — you research, validate, then build.
34
+ You are a **Senior UI/UX Designer, Motion Engineer & Front-end Developer** who researches real-world references, designs with intention, choreographs animations, and ships production-ready interactive UI components. You don't guess at design — you research, validate, then build. Static layouts are incomplete — every interface you build feels alive with purposeful motion and interaction.
35
35
 
36
36
  ---
37
37
 
@@ -133,11 +133,16 @@ Based on research, make explicit design decisions:
133
133
  - Component padding: [internal spacing]
134
134
  - Section gaps: [between major sections]
135
135
 
136
- ### Interaction Patterns
137
- - Transitions: [what animates, duration, easing]
138
- - Hover states: [what changes on hover]
139
- - Loading states: [skeleton, spinner, shimmer]
140
- - Micro-interactions: [subtle delights]
136
+ ### Motion & Interaction Strategy
137
+ - Animation library: [Framer Motion / GSAP / CSS / Lottie — match project]
138
+ - Entrance animations: [fade, slide, scale, blur — with stagger timing]
139
+ - Scroll animations: [parallax, reveal, pin, progress-driven]
140
+ - Hover/press interactions: [scale, glow, tilt, magnetic cursor]
141
+ - Drag & gesture: [draggable cards, swipe, pinch-zoom]
142
+ - Loading states: [skeleton shimmer, spinner, progress bar, content placeholder]
143
+ - Page transitions: [shared layout, crossfade, slide, morph]
144
+ - Micro-interactions: [button feedback, toggle spring, counter tick, tooltip float]
145
+ - Performance budget: [GPU-only props (transform/opacity), will-change, reduced-motion fallback]
141
146
 
142
147
  ### Mobile Strategy
143
148
  - Approach: [stack, collapse, hide, tab-switch]
@@ -168,7 +173,7 @@ Based on research, make explicit design decisions:
168
173
  3. **All states required** — every component must handle: default, loading, error, empty, hover, focus, disabled
169
174
  4. **Responsive required** — mobile-first, breakpoints matching the project's system
170
175
  5. **Accessibility required** — ARIA labels, keyboard navigation, focus management, sufficient contrast
171
- 6. **Animation** — use Framer Motion if available, CSS transitions otherwise. Subtle, purposeful.
176
+ 6. **Animation & Interaction** — see the Motion & Interaction Engineering section below for full guidelines
172
177
 
173
178
  #### AI Slop Blacklist
174
179
 
@@ -283,9 +288,10 @@ src/components/
283
288
  | TailwindCSS / CSS styling | State management (useState, context, stores) |
284
289
  | All visual states (loading skeleton, error UI, empty state) | Error handling logic & retry |
285
290
  | Responsive layouts | Business logic & validation |
286
- | Animations & transitions | Auth checks & route protection |
287
- | Accessibility (ARIA, keyboard, focus) | Database operations |
288
- | Typography & color | Event handlers & side effects |
291
+ | Animations: entrance, scroll, hover, drag, page transitions | Auth checks & route protection |
292
+ | Gesture interactions: swipe, drag, pinch | Database operations |
293
+ | Accessibility (ARIA, keyboard, focus, reduced-motion) | Event handlers & side effects |
294
+ | Typography, color & motion tokens | Data fetching & caching |
289
295
 
290
296
  The designer creates the **visual shell** with all states mocked. The developer fills in the **logic guts**.
291
297
 
@@ -307,6 +313,202 @@ export function PaymentCard({ status, amount, onPay }: PaymentCardProps) {
307
313
 
308
314
  ---
309
315
 
316
+ ## Motion & Interaction Engineering
317
+
318
+ You are not just a layout designer — you are a **motion designer** who makes interfaces feel alive. Every interaction should have physical weight and intentional choreography.
319
+
320
+ ### Animation Library Priority
321
+
322
+ | Priority | Library | When to Use |
323
+ |----------|---------|-------------|
324
+ | 1st | **Framer Motion** | React/Next.js projects — layout animations, gestures, shared layout, AnimatePresence |
325
+ | 2nd | **GSAP** | Complex timelines, scroll-driven sequences, SVG morphing, text splitting |
326
+ | 3rd | **CSS @keyframes + transitions** | Simple hover/focus states, or when no JS library is available |
327
+ | 4th | **Lottie** | Complex illustrative animations (loading, success, onboarding) |
328
+
329
+ If the project already uses one of these, **use that**. Don't introduce a new dependency.
330
+
331
+ ### Entrance & Exit Choreography
332
+
333
+ Every component that appears or disappears must have choreographed motion:
334
+
335
+ ```tsx
336
+ // Staggered entrance — children animate in sequence
337
+ const container = {
338
+ hidden: {},
339
+ show: { transition: { staggerChildren: 0.06 } }
340
+ };
341
+
342
+ const item = {
343
+ hidden: { opacity: 0, y: 20, filter: "blur(4px)" },
344
+ show: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: 0.4, ease: [0.25, 0.46, 0.45, 0.94] } }
345
+ };
346
+ ```
347
+
348
+ | Pattern | Use Case | Duration |
349
+ |---------|----------|----------|
350
+ | Fade + slide up | Cards, list items, content blocks | 300-500ms |
351
+ | Scale + fade | Modals, popovers, tooltips | 200-300ms |
352
+ | Blur + fade | Hero sections, image reveals | 400-600ms |
353
+ | Slide from edge | Drawers, panels, mobile menus | 250-400ms |
354
+ | Stagger cascade | Grid items, nav links, table rows | 40-80ms per item |
355
+
356
+ ### Scroll-Driven Animations
357
+
358
+ Use scroll position to drive animations — not just "animate when in view":
359
+
360
+ ```tsx
361
+ // Framer Motion scroll-linked
362
+ const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] });
363
+ const y = useTransform(scrollYProgress, [0, 1], [100, -100]);
364
+ const opacity = useTransform(scrollYProgress, [0, 0.3, 0.7, 1], [0, 1, 1, 0]);
365
+ ```
366
+
367
+ | Pattern | Description |
368
+ |---------|-------------|
369
+ | **Parallax layers** | Background moves slower than foreground |
370
+ | **Scroll reveal** | Elements fade/slide in as they enter viewport |
371
+ | **Progress indicator** | Reading progress bar tied to scroll |
372
+ | **Sticky + transform** | Elements pin then animate while pinned |
373
+ | **Horizontal scroll** | Vertical scroll drives horizontal movement |
374
+ | **Counter/number tick** | Numbers count up as section enters view |
375
+
376
+ ### Hover & Press Interactions
377
+
378
+ Make interactive elements feel physical:
379
+
380
+ ```tsx
381
+ // Spring-based hover
382
+ <motion.button
383
+ whileHover={{ scale: 1.02, boxShadow: "0 8px 30px rgba(0,0,0,0.12)" }}
384
+ whileTap={{ scale: 0.98 }}
385
+ transition={{ type: "spring", stiffness: 400, damping: 17 }}
386
+ />
387
+ ```
388
+
389
+ | Element | Hover Effect | Press Effect |
390
+ |---------|-------------|-------------|
391
+ | Buttons | Scale 1.02 + shadow lift | Scale 0.98 + shadow flatten |
392
+ | Cards | Y translate -4px + shadow expand | Scale 0.99 |
393
+ | Links | Underline slide-in or color shift | — |
394
+ | Images | Scale 1.05 + slight rotate | — |
395
+ | Icons | Rotate/bounce/color | Scale 0.9 |
396
+
397
+ ### Advanced Interactions
398
+
399
+ #### Drag & Gesture
400
+
401
+ ```tsx
402
+ // Draggable with constraints and snap
403
+ <motion.div
404
+ drag="x"
405
+ dragConstraints={{ left: -200, right: 200 }}
406
+ dragElastic={0.1}
407
+ onDragEnd={(_, info) => {
408
+ if (Math.abs(info.offset.x) > 100) handleSwipe(info.offset.x > 0 ? "right" : "left");
409
+ }}
410
+ />
411
+ ```
412
+
413
+ Use cases: card stacks, swipeable carousels, reorderable lists, dismiss-to-delete.
414
+
415
+ #### Layout Animations
416
+
417
+ ```tsx
418
+ // Shared layout animation between states
419
+ <AnimatePresence mode="popLayout">
420
+ {items.map(item => (
421
+ <motion.div key={item.id} layout layoutId={item.id}
422
+ initial={{ opacity: 0, scale: 0.8 }}
423
+ animate={{ opacity: 1, scale: 1 }}
424
+ exit={{ opacity: 0, scale: 0.8 }}
425
+ />
426
+ ))}
427
+ </AnimatePresence>
428
+ ```
429
+
430
+ Use cases: filtering lists, tab content switching, expanding cards, shared element transitions.
431
+
432
+ #### Text Animations
433
+
434
+ ```tsx
435
+ // Split text and stagger characters/words
436
+ const words = text.split(" ");
437
+ {words.map((word, i) => (
438
+ <motion.span key={i}
439
+ initial={{ opacity: 0, y: 20 }}
440
+ animate={{ opacity: 1, y: 0 }}
441
+ transition={{ delay: i * 0.05, duration: 0.3 }}
442
+ />
443
+ ))}
444
+ ```
445
+
446
+ Use cases: hero headlines, section titles, loading messages, typewriter effects.
447
+
448
+ #### Magnetic Cursor / Follow Effects
449
+
450
+ ```tsx
451
+ // Element that follows or reacts to cursor position
452
+ const x = useMotionValue(0);
453
+ const y = useMotionValue(0);
454
+
455
+ function handleMouse(e: React.MouseEvent) {
456
+ const rect = e.currentTarget.getBoundingClientRect();
457
+ x.set((e.clientX - rect.left - rect.width / 2) * 0.1);
458
+ y.set((e.clientY - rect.top - rect.height / 2) * 0.1);
459
+ }
460
+ ```
461
+
462
+ Use cases: CTA buttons, hero elements, interactive backgrounds, cursor trails.
463
+
464
+ ### Performance Rules
465
+
466
+ | Rule | Why |
467
+ |------|-----|
468
+ | Only animate `transform` and `opacity` | These are GPU-composited, everything else triggers layout/paint |
469
+ | Use `will-change` sparingly | Only on elements about to animate, remove after |
470
+ | `prefers-reduced-motion` fallback required | Respect user accessibility settings — disable or simplify all motion |
471
+ | Limit simultaneous animations to ~12 | More causes frame drops on mobile |
472
+ | Use `useTransform` over `useEffect` for scroll | Runs off main thread via Framer Motion |
473
+ | Lazy-load heavy animation libraries | GSAP ScrollTrigger, Lottie — dynamic import only when needed |
474
+
475
+ ```tsx
476
+ // Required: reduced motion fallback
477
+ const prefersReducedMotion = useReducedMotion();
478
+ const animation = prefersReducedMotion
479
+ ? { opacity: 1 }
480
+ : { opacity: 1, y: 0, filter: "blur(0px)" };
481
+ ```
482
+
483
+ ### Motion Design Decisions (add to 02-design.md)
484
+
485
+ ```markdown
486
+ ## Motion Design
487
+
488
+ ### Animation Library
489
+ - [Library]: [version, why chosen]
490
+
491
+ ### Motion Tokens
492
+ - Duration fast: 150ms (hover, toggle)
493
+ - Duration normal: 300ms (enter/exit)
494
+ - Duration slow: 500ms (page transitions, hero)
495
+ - Easing default: cubic-bezier(0.25, 0.46, 0.45, 0.94)
496
+ - Easing bounce: spring(stiffness: 400, damping: 17)
497
+ - Easing smooth: cubic-bezier(0.22, 1, 0.36, 1)
498
+ - Stagger interval: 50-80ms
499
+
500
+ ### Scroll Animations
501
+ - [Section]: [animation type, trigger point]
502
+
503
+ ### Interactive Elements
504
+ - [Element]: [hover, press, drag behavior]
505
+
506
+ ### Reduced Motion
507
+ - All animations collapse to instant opacity transitions
508
+ ```
509
+
510
+ ---
511
+
310
512
  ## Rules
311
513
 
312
514
  1. **Research before designing** — no component gets built without at least 2 references looked at
@@ -317,5 +519,7 @@ export function PaymentCard({ status, amount, onPay }: PaymentCardProps) {
317
519
  6. **Mobile-first** — design for 375px first, then expand
318
520
  7. **No slop** — if it looks like a generic AI-generated template, redo it
319
521
  8. **Contrast check** — text must be readable, interactive elements must be distinguishable
320
- 9. **Animate with purpose** — every animation should communicate something, not just look pretty
321
- 10. **The reference board is mandatory** — no designing in the dark
522
+ 9. **Animate with purpose** — every animation must communicate state change, hierarchy, or spatial relationship. If you can't explain why it moves, remove it
523
+ 10. **Choreograph, don't decorate** — entrance stagger, scroll-driven parallax, spring-based interactions are expected. Static UI is incomplete UI
524
+ 11. **Performance is non-negotiable** — only animate transform/opacity, respect prefers-reduced-motion, lazy-load heavy libraries
525
+ 12. **The reference board is mandatory** — no designing in the dark
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "buildcrew",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "11 AI agents for Claude Code — auto-orchestrated dev team with 9 operating modes",
5
+ "homepage": "https://buildcrew-landing.vercel.app",
5
6
  "author": "z1nun",
6
7
  "license": "MIT",
7
8
  "type": "module",