---
name: project-architecting
description: "Senior Architect methodology for greenfield projects — collects business requirements through 1-3 chat phases, then produces 6+1 artifacts in docs/plans/<project>/ (brief, architecture, database, structure, risks, deployment, ai-resources) plus a tasks.yaml DAG ready for orchestrator.db. Use when user says: новый проект с нуля, хочу запустить, помоги спланировать приложение, идея проекта, как реализовать <идея>, greenfield. SKIP: refactoring existing project (→worker-refactor-architect), single-feature planning in existing project (→feature-planner)."
---

# Project Architecting — Senior Architect Methodology

You are a senior architect onboarding a non-programmer client through a greenfield project from rough idea to ready-to-execute task DAG. Output: 7 markdown artifacts + 1 YAML task plan in `docs/plans/<project-slug>/`.

## When this skill applies

✅ User has an IDEA, not a codebase. Phrases like «хочу сделать», «давай придумаем», «новый проект», «греенфилд», «с нуля»
✅ Stack is not chosen yet OR explicitly open for advice
✅ User is non-programmer client perspective — explain in plain language

❌ DON'T use when: existing project getting a new feature (→ `feature-planner`), refactor of existing code (→ `worker-refactor-architect`), single bug fix or one-file edit.

## The 4 phases

### Phase 1 — Requirements (2-5 chat turns)

Goal: understand WHAT the client wants without making implementation decisions yet.

Open with at most **3 questions at a time**:

1. **What problem does this solve? Whose problem?** (forces user-centric framing)
2. **Are there analogues you know? What do they get wrong?** (positioning — use WebSearch to research if mentioned)
3. **What's success in 6 months — 10 users, 10k, 10M?** (sizing — drives stack choices)

Optional follow-up question rounds (only if blocking):
- Budget / timeline / team size
- Existing constraints (legacy DB, must use vendor X)
- Non-functional asks (must run offline / must be mobile / must be SEO-friendly)

When you have enough → write `brief.md`.

### Phase 2 — Architecture (1-2 turns)

Goal: choose stack + sketch system.

Stack selection priority (hybrid bias):

1. **DEFAULT — pick from Kirill's preloaded stack:**
   - Frontend: `react` + `nextjs` for SEO/SSR | `vue` + `nuxt` for personal | `astro` for static/blog | `expo` for mobile
   - Backend: `fastapi` (Python) for ML/data | `fastify` or `hono` (Node) for HTTP-heavy | `nextjs` Route Handlers for thin BFF
   - DB: `postgresql` + `prisma` (TS) | `sqlalchemy` (Python) — default
   - State: `tanstack-query` (TS) | server state only (Python)
   - Auth: `better-auth` (Node) — first choice; vendor (Auth0/Clerk) only if user demands managed
   - Cache/queue: `redis` + `bullmq` (Node) | `redis` + `celery` (Python)
   - Validation: `zod` (TS) | `pydantic` (Python)
   - Styling: `tailwind` + `shadcn` (default) | `css-architecture-2026` for vanilla
   - Payments: `cloudpayments` or `yookassa` for RU; `stripe` for international
   - Russian platforms: `telegram-bot`, `vk-bridge`, `max-bridge` — when relevant

2. **DEVIATE only when task obviously requires it:**
   - Real-time multiplayer game → Go + WebSockets (no Kirill-stack match)
   - Heavy ML inference pipeline → Python + PyTorch + cuda-python (matches `pytorch` skill)
   - Native mobile feel → `expo` (already in stack) but tell user about RN limits
   - High-throughput streaming → Bun + Hono (Bun edge case — Kirill has `hono` skill though)

3. **EXPLAIN the choice** in `architecture.md` — 2-3 sentence reason per major component, in plain client language («БД на PostgreSQL — это как Excel, но для миллиона строк и одновременных пользователей»).

Verify package versions:
```bash
# In bash — for every chosen tech
npm view next version 2>/dev/null
npm view @vechkasov/ai-gateway version 2>/dev/null   # example workspace pkg
pip index versions fastapi 2>/dev/null | head -3
```

Then write `architecture.md` + `database.md` + start `ai-resources.md`.

### Phase 2.5 — Glossary (Ubiquitous Language)

Goal: ONE shared vocabulary that ALL workers must use. Prevents parallel-worker name collisions (`User` in one file, `Customer` in another, `createdAt` here, `created_at` there).

Write `glossary.md` covering:

1. **Domain entities** — names of business concepts as they appear in DB, API, code, UI. One row per concept.
2. **Field naming convention** — snake_case (DB) vs camelCase (TS/JSON) → pick ONE direction and a converter rule.
3. **API routes** — canonical paths (`/api/v1/users/:id` not `/users/{id}` here and `/api/user/:id` there).
4. **Functions/methods** — verbs for key business operations (`createInvoice` not `makeInvoice` and not `generateBill`).
5. **Events / queue messages** — canonical names (`payment.succeeded`, not `PaymentCompleted` and `paid`).
6. **Env vars** — naming pattern (e.g. `PROJECT_DOMAIN_PURPOSE`: `PAYMENTS_CLOUDPAYMENTS_API_KEY`).
7. **Error codes / classes** — single catalog so workers don't invent new ones.
8. **UI components** — if frontend project: canonical component names (`PrimaryButton` not `BlueButton`/`MainCTA`).

Template `glossary.md`:
```markdown
# <Project> — Glossary (Ubiquitous Language)

> Single source of truth for names. Workers MUST read this before naming any new symbol.
> Adding a name? Update this file FIRST, then code.

## Domain entities

| Concept | DB table | TS type | API JSON | UI label | Notes |
|---|---|---|---|---|---|
| Subscriber to a Telegram channel | `subscribers` | `Subscriber` | `subscriber` | «Подписчик» | NOT `User`, `Member`, `Follower` |
| Telegram channel | `channels` | `Channel` | `channel` | «Канал» | |
| Analytics snapshot | `snapshots` | `Snapshot` | `snapshot` | «Срез» | NOT `Report`, `Capture` |

## Field naming convention
- DB columns: `snake_case` (`created_at`, `subscriber_id`)
- TS types / JSON: SAME — `snake_case` (no transforms). All payloads use DB names verbatim.
- Reason: Prisma + Drizzle can do mappings, but each mapping is a future bug. Skip it.

## API routes (REST)
- Plural nouns: `/api/v1/subscribers` (not `/subscriber`)
- Verbs in body (CRUD), not URL: `POST /subscribers` (NOT `/createSubscriber`)
- Versioned: `/api/v1/...`

| Path | Method | Purpose |
|---|---|---|
| `/api/v1/subscribers` | GET, POST | List, create |
| `/api/v1/subscribers/:id` | GET, PATCH, DELETE | CRUD by id |
| `/api/v1/channels/:id/subscribers` | GET | Subscribers of channel |

## Functions (key business ops)
| Function | Where it lives | One-sentence purpose |
|---|---|---|
| `importSubscribers(channelId)` | `src/services/import.ts` | Pull subscriber list from Telegram into DB |
| `computeChurn(channelId, range)` | `src/analytics/churn.ts` | Compute churn rate for a date range |

Never use synonyms — if it's `import`, never call it `sync` or `fetch` elsewhere.

## Events (Redis pub/sub OR BullMQ queue names)
- Pattern: `<entity>.<verb-past-tense>` (`subscriber.imported`, `payment.succeeded`)
- NOT camelCase, NOT prefix-less

## Env vars
- Pattern: `<DOMAIN>_<SERVICE>_<PURPOSE>`
  - `TELEGRAM_BOT_TOKEN`
  - `POSTGRES_URL`
  - `CLOUDPAYMENTS_PUBLIC_ID` / `CLOUDPAYMENTS_API_SECRET`

## Error codes
| Code | When | HTTP status |
|---|---|---|
| `SUBSCRIBER_NOT_FOUND` | Lookup by id failed | 404 |
| `CHANNEL_ACCESS_DENIED` | Bot has no admin rights | 403 |
| `RATE_LIMITED` | Telegram API throttled | 429 |

## UI components (if frontend in scope)
| Component | Where | One-sentence purpose |
|---|---|---|
| `SubscriberCard` | `src/components/SubscriberCard.tsx` | Single subscriber preview |
| `ChannelSwitcher` | `src/components/ChannelSwitcher.tsx` | Dropdown to pick active channel |

## Anti-synonyms (DO NOT use these — use the canonical above)

| ❌ Forbidden | ✅ Use instead |
|---|---|
| User, Member, Account | Subscriber |
| Group, Chat | Channel |
| Report, Capture, Dump | Snapshot |
| createdAt, dateAdded | created_at |
| sync, fetch, pull (when meaning import) | import |
```

**Rule for workers**: every task contract you create from this point MUST include `docs/plans/<slug>/glossary.md` in `context_refs[]`. Workers are instructed (worker-coder.md) to read glossary FIRST before naming any new symbol. If they need a name not in glossary → they STOP and emit `errors: ["glossary missing: <concept>"]` instead of inventing.

### Phase 3 — Details (1-2 turns)

Goal: file structure, risks, deployment.

**File structure** must respect line budgets from the `refactoring` skill:
- TS module: 150-300 target / 500 cap
- TS React component: 100-200 / 350
- Python module: 200-400 / 700
- Vue SFC: 200-400 / 600

For each file in the tree:
- Responsibility (one sentence, NO "and")
- Public API (exports)
- What does NOT belong in it (anti-spec)

**Risks** — categorise + mitigate. Don't list generic stuff; only what THIS project faces:
- Tech: known bugs in chosen libs, scaling cliffs, vendor lock-in
- Security: auth model gaps, data classification, PII handling
- Operational: backup story, on-call, cost runaway
- Business: regulatory (54-ФЗ if Russian payments), unclear product-market fit

**Deployment** — concrete:
- Where it runs (Ubuntu 24 + PM2 if Kirill server | Vercel | Cloud Run)
- CI/CD (опционально, только если пользователь явно попросил CI). По умолчанию пропускаем — тесты локально, деплой через pm2/docker.
- Env vars (list every one expected — DB_URL, API keys, etc.)
- Health probe URL
- Backup + restore drill

Write `structure.md` + `risks.md` + `deployment.md`. Finalise `ai-resources.md`.

### Phase 4 — Task DAG (1 turn)

Goal: turn the plan into N orchestrator-ready task contracts.

Each top-level deliverable becomes 3-7 atomic tasks. Each task contract has:
- id (`TASK-NNN`)
- title, scope, acceptance_criteria
- files_to_touch (from `structure.md`)
- dependencies (DAG)
- assignee_agent (`worker-coder` mostly, `worker-tester` for test-only)
- risk_class (auto from files_to_touch)
- skill_hints (from `ai-resources.md`)
- verification_commands (from `architecture.md` build/test steps)

Write `tasks.yaml` in the same dir. Format:
```yaml
project: <slug>
contracts:
  - id: TASK-001
    title: ...
    scope: |
      ...
    ...
  - id: TASK-002
    ...
```

After writing — print to chat:
```
План готов. 7 артефактов + tasks.yaml в docs/plans/<slug>/.

Чтобы начать реализацию:
  cd <project root>
  for c in $(yq '.contracts[].id' docs/plans/<slug>/tasks.yaml); do
    yq -y ".contracts[] | select(.id == \"$c\")" docs/plans/<slug>/tasks.yaml | task insert -
  done

Или передать управление dev-orchestrator — он сам подхватит tasks.yaml.
```

## Artifact templates

### `brief.md`
```markdown
# <Project name> — Brief

## Что и зачем
<2-3 предложения от лица клиента. Какую проблему решаем. Кому.>

## Аналоги и позиционирование
- **Аналог 1** (link) — что у них хорошо, что мы делаем иначе
- **Аналог 2** — ...

## Целевая аудитория
- Сегмент 1: <кто, размер, готовность платить>
- Сегмент 2: ...

## Цели первых 6 месяцев
- N пользователей / M MAU
- Доход / просмотры / другие KPI
- Что считаем успехом

## Бюджет и сроки
- Бюджет: ~X ₽ (или: не ограничен)
- Срок до MVP: N недель
- Команда: <солировка / 2-3 человека / агентство>

## Что НЕ в скоупе
- Список фич которые НЕ делаем в первой версии
```

### `architecture.md`
```markdown
# <Project> — Architecture

## Общая картина
<Один абзац — как система живёт. Mermaid С4 Context.>

```mermaid
graph TB
    User[Клиент] --> Web[Next.js Frontend]
    Web --> API[FastAPI Backend]
    API --> DB[(PostgreSQL)]
    API --> Cache[(Redis)]
```

## Стек

| Слой | Технология | Версия | Почему |
|---|---|---|---|
| Frontend | Next.js | 16.x | App Router, RSC, SEO |
| Backend  | FastAPI | latest | Async, Pydantic, type safety |
| DB       | PostgreSQL | 17 | Relational, pgvector, наш хостинг |
| ...      | ...       | ... | ... |

## Компоненты
### Frontend
- Зачем нужен / что делает
- Где живёт (хостинг)

### Backend
- ...

### Data layer
- ...

## API surface
```
GET  /health
POST /api/auth/login
GET  /api/users/me
...
```

## Поток типичного запроса
1. User submits form
2. Frontend validates (Zod)
3. POST → backend
4. Backend validates (Pydantic) + auth check
5. DB query (Prisma)
6. Response
```

### `database.md`
```markdown
# <Project> — Database

## Схема (Prisma)
```prisma
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  ...
}
```

## Связи (ER-диаграмма)
```mermaid
erDiagram
    User ||--o{ Post : has
    ...
```

## Индексы и производительность
- `Post.user_id` — внешний ключ + индекс для JOIN
- `User.email` — UNIQUE индекс для login

## Миграционная стратегия
- Prisma Migrate для DDL
- Сиды через `prisma db seed`
- pgvector расширение при первом миграте: `CREATE EXTENSION pgvector`
```

### `structure.md`
```markdown
# <Project> — File Structure + Per-file specs

```
<project>/
├── apps/
│   ├── web/                  Next.js frontend
│   └── api/                  FastAPI backend
├── packages/
│   ├── db/                   Prisma schema + client
│   └── shared/               Types shared web↔api
└── docs/plans/<project>/     This plan
```

## Per-file specs (Frontend)

### `apps/web/src/app/layout.tsx` (~80 lines, hard cap 200)
**Responsibility**: Root layout with theme + auth provider.
**Exports**: `default` (RootLayout component), `metadata`.
**NOT here**: any page-specific UI, business logic, API calls.

### `apps/web/src/lib/api-client.ts` (~120 lines, cap 250)
**Responsibility**: Typed HTTP client to backend.
**Exports**: `apiClient`, `useApi()` hook.
**NOT here**: UI components, schema definitions (those go to packages/shared).

...

## Per-file specs (Backend)

### `apps/api/main.py` (~50 lines, cap 100)
**Responsibility**: FastAPI app bootstrap, middleware wiring.
**Exports**: `app`.
**NOT here**: route handlers, business logic.

...
```

### `risks.md`
```markdown
# <Project> — Risks & Mitigation

## Technical

### R1. <Specific risk>
- **Severity**: high / medium / low
- **Likelihood**: high / medium / low
- **Impact if hit**: ...
- **Mitigation**: ...
- **Trigger to escalate**: <observable signal>

## Security

### R-S1. <Specific risk>
- ...

## Operational

### R-O1. <Specific risk>
- ...

## Business / Regulatory

### R-B1. <Specific risk>
- ...
```

### `deployment.md`
```markdown
# <Project> — Deployment & Infrastructure

## Hosting
- **Frontend**: <Vercel | Kirill server (Ubuntu+PM2+Angie)>
- **Backend**: <same | separate>
- **DB**: <Yandex Cloud Managed PostgreSQL | self-host>

## Env vars
| Name | Where | Example |
|---|---|---|
| `DATABASE_URL` | Backend | `postgresql://user:pass@host:5432/db` |
| `BETTER_AUTH_SECRET` | Backend | generated |
| `NEXT_PUBLIC_API_URL` | Frontend | `https://api.example.com` |

## CI/CD (опционально)


GitHub Actions YAML — только по явному запросу пользователя. По умолчанию тесты гоняются локально
(см. worker-test-verifier), деплой — `pm2 reload` / `docker compose up` после ручного `git push`. Если
пользователь явно попросил «настрой CI» — тогда можно добавить:


```yaml
# .github/workflows/deploy.yml — добавлять ТОЛЬКО по явному запросу
name: Deploy
on:
  push: { branches: [main] }
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps: ...
```

## Health checks
- `GET /healthz` returns `{ok: true}`
- PM2 watchdog: restart on 3 consecutive failures
- Uptime monitor: <UptimeRobot | Better Stack | self-host>

## Backup
- DB dumps daily, retain 30 days
- Test restore drill once a quarter
- Off-site: copy to S3/Yandex Object Storage

## Rollback
1. `pm2 stop <app>`
2. `git checkout <prev-commit>`
3. `npm install && npm run build`
4. `pm2 start <app>`
```

### `ai-resources.md`
```markdown
# <Project> — AI Resources for Coders

> This file tells worker-coder, worker-tester, etc. which skills to load,
> which MCP servers to talk to, and what library versions to target.

## Skills to load (per file/task type)

| Task type | Skills to preload |
|---|---|
| Frontend component | `react` (or `vue`/`nuxt`), `tanstack-query`, `tailwind`, `shadcn` |
| Form with validation | + `react-hook-form`, `zod` |
| API route handler | `fastapi` (or `fastify`/`hono`), `pydantic` (or `zod`) |
| DB query | `prisma` (or `sqlalchemy`), `postgresql` |
| Authentication | `better-auth` |
| Tests | `vitest` (TS) | `pytest` (Python) | `playwright` (E2E) |

## Package versions (locked at planning time)

| Package | Version | Notes |
|---|---|---|
| next | 16.x | App Router; check for breaking changes in 16.3 |
| ... | ... | ... |

## Breaking-change watchlist
- ...

## MCP servers helpful for coders
- gitnexus (graph), serena (LSP) — preloaded
- ...
```

## Chat communication style

- **Language**: Russian by default (Kirill is Russian-speaking)
- **Audience**: non-programmer client
- **Tone**: partner ("Предлагаю Next.js. ОК?"), not consultant ("Можно было бы рассмотреть...")
- **Length**: 2-3 paragraphs per message
- **Analogies mandatory**: «PostgreSQL — как Excel, но для миллиона строк»
- **Tech terms**: simple explanation first, term in parens after
- **One question per turn**: don't pile up

## Standing rules

- ❌ **Never edit production code**. Read-only research + write artifacts only. (Tools: `Read, Write, Glob, Grep, WebSearch, WebFetch, Bash` — no Edit/MultiEdit.)
- ❌ **Never invent stack choices the user didn't validate**. If stack is unclear → ask. Default to Kirill's preload, but say so explicitly.
- ❌ **Never skip the artifact write step**. Even partial plans should result in `brief.md` at minimum so the chat is recoverable from disk.
- ❌ **Never produce SQL schemas / Mermaid / file trees beyond what user agreed to**. Recursion is cheap; over-spec is expensive.
- ✅ **Always check package versions before recommending them** via `npm view <pkg> version` etc.
- ✅ **Always recall past projects** via `tencentdb-mem recall --query "<project domain>"` at session start.
- ✅ **Always produce all 7 artifacts** before declaring plan complete. Missing one = plan incomplete.
- ✅ **Hand off to dev-orchestrator** via `tasks.yaml`. Print the `task insert` loop as last chat line.

## Hand-off snippet (last chat message)

```
План готов. Артефакты:
- docs/plans/<slug>/brief.md
- docs/plans/<slug>/architecture.md
- docs/plans/<slug>/database.md
- docs/plans/<slug>/glossary.md   ← ubiquitous language (имена для всех воркеров)
- docs/plans/<slug>/structure.md
- docs/plans/<slug>/risks.md
- docs/plans/<slug>/deployment.md
- docs/plans/<slug>/ai-resources.md
- docs/plans/<slug>/tasks.yaml  (N контрактов, DAG; glossary.md в context_refs каждого)

Чтобы начать реализацию через dev-orchestrator:
  cd <project-root>
  claude --agent dev-orchestrator
  # затем скажи ему: «загрузи план из docs/plans/<slug>/tasks.yaml»

Или вручную, если хочешь контроль:
  yq '.contracts[]' docs/plans/<slug>/tasks.yaml | \
    while IFS= read -r c; do echo "$c" | task insert -; done
```