diff --git a/landing/.gitignore b/landing/.gitignore index 392f1564..f4956f78 100644 --- a/landing/.gitignore +++ b/landing/.gitignore @@ -5,6 +5,7 @@ node_modules .env --host/ product-docs/.vitepress/dist/ +product-docs/.vitepress/cache/ # Large video files public/video/*.mp4 diff --git a/landing/product-docs/.vitepress/config.ts b/landing/product-docs/.vitepress/config.ts index 18b48fa5..02bed4f2 100644 --- a/landing/product-docs/.vitepress/config.ts +++ b/landing/product-docs/.vitepress/config.ts @@ -40,6 +40,7 @@ const rootGuide: DefaultTheme.SidebarItem[] = [ text: "Start", items: [ { text: "Installation", link: "/guide/installation" }, + { text: "Beginner workflow", link: "/guide/beginner-workflow" }, { text: "Quickstart", link: "/guide/quickstart" }, { text: "Runtime setup", link: "/guide/runtime-setup" } ] @@ -47,7 +48,10 @@ const rootGuide: DefaultTheme.SidebarItem[] = [ { text: "Guide", items: [ - { text: "Create a team", link: "/guide/create-team" }, + { text: "Create your first team", link: "/guide/create-first-team" }, + { text: "Run and monitor work", link: "/guide/run-and-monitor-work" }, + { text: "Review and approve", link: "/guide/review-and-approve" }, + { text: "Team configuration", link: "/guide/create-team" }, { text: "Agent workflow", link: "/guide/agent-workflow" }, { text: "Code review", link: "/guide/code-review" }, { text: "MCP integration", link: "/guide/mcp-integration" }, @@ -83,6 +87,7 @@ const ruGuide: DefaultTheme.SidebarItem[] = [ text: "Старт", items: [ { text: "Установка", link: "/ru/guide/installation" }, + { text: "Путь новичка", link: "/ru/guide/beginner-workflow" }, { text: "Быстрый старт", link: "/ru/guide/quickstart" }, { text: "Настройка рантайма", link: "/ru/guide/runtime-setup" } ] @@ -90,7 +95,10 @@ const ruGuide: DefaultTheme.SidebarItem[] = [ { text: "Руководство", items: [ - { text: "Создание команды", link: "/ru/guide/create-team" }, + { text: "Создать первую команду", link: "/ru/guide/create-first-team" }, + { text: "Запуск и мониторинг", link: "/ru/guide/run-and-monitor-work" }, + { text: "Проверка и approval", link: "/ru/guide/review-and-approve" }, + { text: "Настройка команды", link: "/ru/guide/create-team" }, { text: "Работа агентов", link: "/ru/guide/agent-workflow" }, { text: "Код-ревью", link: "/ru/guide/code-review" }, { text: "Интеграция MCP", link: "/ru/guide/mcp-integration" }, @@ -122,7 +130,7 @@ const ruGuide: DefaultTheme.SidebarItem[] = [ ]; const rootNav: DefaultTheme.NavItem[] = [ - { text: "Guide", link: "/guide/quickstart", activeMatch: "^/guide/(?!troubleshooting(?:/|$))" }, + { text: "Guide", link: "/guide/beginner-workflow", activeMatch: "^/guide/(?!troubleshooting(?:/|$))" }, { text: "Developers", link: "/developers/", activeMatch: "^/developers/" }, { text: "Reference", link: "/reference/concepts", activeMatch: "^/reference/" }, { @@ -136,7 +144,7 @@ const rootNav: DefaultTheme.NavItem[] = [ const ruNav: DefaultTheme.NavItem[] = [ { text: "Руководство", - link: "/ru/guide/quickstart", + link: "/ru/guide/beginner-workflow", activeMatch: "^/ru/guide/(?!troubleshooting(?:/|$))" }, { text: "Разработчикам", link: "/ru/developers/", activeMatch: "^/ru/developers/" }, diff --git a/landing/product-docs/.vitepress/theme/DocsCardGrid.vue b/landing/product-docs/.vitepress/theme/DocsCardGrid.vue index 85035089..d249547e 100644 --- a/landing/product-docs/.vitepress/theme/DocsCardGrid.vue +++ b/landing/product-docs/.vitepress/theme/DocsCardGrid.vue @@ -20,10 +20,12 @@ const cards = computed(() => { { icon: "?", title: "FAQ", desc: "Короткие ответы на частые вопросы.", link: "/ru/reference/faq" } ] : [ - { icon: "01", title: "Быстрый старт", desc: "Поставить приложение и создать первую команду.", link: "/ru/guide/quickstart" }, - { icon: "02", title: "Установка", desc: "Платформы, релизы и запуск из исходников.", link: "/ru/guide/installation" }, - { icon: "03", title: "Создание команды", desc: "Роли, lead prompt и границы работы.", link: "/ru/guide/create-team" }, - { icon: "04", title: "Код-ревью", desc: "Проверка изменений по задачам и hunk-level decisions.", link: "/ru/guide/code-review" } + { icon: "01", title: "Путь новичка", desc: "Понять весь первый запуск от проекта до approval.", link: "/ru/guide/beginner-workflow" }, + { icon: "02", title: "Быстрый старт", desc: "Поставить приложение и проверить базовый запуск.", link: "/ru/guide/quickstart" }, + { icon: "03", title: "Первая команда", desc: "Lead, builder, reviewer, роли, модели и Worktree.", link: "/ru/guide/create-first-team" }, + { icon: "04", title: "Запуск работы", desc: "Brief для lead, task board, comments и monitoring.", link: "/ru/guide/run-and-monitor-work" }, + { icon: "05", title: "Review и approval", desc: "Task detail, logs, diff и hunk-level decisions.", link: "/ru/guide/review-and-approve" }, + { icon: "06", title: "Рантаймы", desc: "Claude, Codex, OpenCode и multimodel setup.", link: "/ru/guide/runtime-setup" } ]; } @@ -36,10 +38,12 @@ const cards = computed(() => { { icon: "?", title: "FAQ", desc: "Short answers to common questions.", link: "/reference/faq" } ] : [ - { icon: "01", title: "Quickstart", desc: "Install the app and create your first team.", link: "/guide/quickstart" }, - { icon: "02", title: "Installation", desc: "Platforms, releases, and running from source.", link: "/guide/installation" }, - { icon: "03", title: "Create a team", desc: "Roles, lead prompt, and task boundaries.", link: "/guide/create-team" }, - { icon: "04", title: "Code review", desc: "Review task changes with hunk-level decisions.", link: "/guide/code-review" } + { icon: "01", title: "Beginner workflow", desc: "Understand the first run from project to approval.", link: "/guide/beginner-workflow" }, + { icon: "02", title: "Quickstart", desc: "Install the app and validate the base launch.", link: "/guide/quickstart" }, + { icon: "03", title: "First team", desc: "Lead, builder, reviewer, roles, models, and Worktree.", link: "/guide/create-first-team" }, + { icon: "04", title: "Run work", desc: "Lead brief, task board, comments, and monitoring.", link: "/guide/run-and-monitor-work" }, + { icon: "05", title: "Review and approve", desc: "Task detail, logs, diff, and hunk-level decisions.", link: "/guide/review-and-approve" }, + { icon: "06", title: "Runtime setup", desc: "Claude, Codex, OpenCode, and multimodel setup.", link: "/guide/runtime-setup" } ]; }); diff --git a/landing/product-docs/guide/beginner-workflow.md b/landing/product-docs/guide/beginner-workflow.md new file mode 100644 index 00000000..91efd44e --- /dev/null +++ b/landing/product-docs/guide/beginner-workflow.md @@ -0,0 +1,108 @@ +--- +title: "Beginner Workflow - Agent Teams Docs" +description: "A structured first-run path for new users. Learn the project, team, task board, task detail, and review surfaces before launching larger teams." +--- + +# Beginner Workflow + +Use this path when you are new to Agent Teams and want a clear sequence from "open the app" to "approve useful work". + +The first run should prove four things: + +1. The app can open your project. +2. A small team can launch with the selected runtime. +3. Tasks move through the board in a visible way. +4. You can review and approve changes before they are treated as done. + +## The basic model + +Agent Teams has four working surfaces: + +| Surface | What you do there | +| --- | --- | +| Project and team selector | Pick the project and the team that will work on it. | +| Team editor | Name the team, add members, choose roles, models, and worktree settings. | +| Task board | Watch work move through Todo, In Progress, Review, Done, and Approved. | +| Task detail and review | Read the task, inspect logs, check changes, and approve or request fixes. | + + + +## Recommended guide order + +Follow these guides in order for the first successful run: + +1. [Create your first team](/guide/create-first-team) - set up a small lead-builder-reviewer team. +2. [Run and monitor work](/guide/run-and-monitor-work) - give the lead a concrete goal and watch the task board. +3. [Review and approve](/guide/review-and-approve) - inspect task details, logs, and code changes. +4. [Troubleshooting](/guide/troubleshooting) - use this if launch, messages, or task logs do not look healthy. + +## Before you launch + +Start with a Git-tracked project and a known baseline: + +```bash +git status --short +``` + +You do not need a perfectly clean tree, but you should know which files are already changed. That makes review safer after agents start editing. + +For the first run, keep the team small: + +| Member | Good first responsibility | +| --- | --- | +| Lead | Split the goal into tasks and coordinate status. | +| Builder | Implement scoped tasks. | +| Reviewer | Review completed tasks and ask for fixes. | + +Avoid launching many teammates at once. More agents increase logs, concurrent edits, provider usage, and review load. + +## First goal template + +Use a goal that has clear scope, boundaries, and verification: + +```text +Improve the documentation quickstart. Keep edits inside landing/product-docs, add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done. +``` + +Good first goals are specific, testable, and limited to a known area. Avoid prompts like "make the app better" until you understand the workflow. + +## What healthy progress looks like + +During a healthy run: + +- The lead creates small tasks rather than one huge task. +- Each teammate posts a plan or progress comment. +- Work moves from Todo to In Progress. +- Finished work moves to Review before approval. +- The task detail shows the description, attachments, changes, and execution logs. +- The final comment includes the verification command and result. + +## When to intervene + +Intervene when a task is vague, too broad, blocked, or missing verification. Use a task comment when the message belongs to one task. Use a direct message when you need to redirect a teammate or the lead. + +Common intervention prompts: + +```text +Split this into smaller tasks. Each task should have a narrow file scope and a clear verification step. +``` + +```text +Before continuing, post the files you plan to change and the command you will run to verify the result. +``` + +```text +This task is too broad. Keep the change inside the docs guide pages and avoid touching app runtime code. +``` + +## Completion checklist + +Before you call the first run successful, verify: + +- The team launched without runtime errors. +- At least one task moved through Review. +- You inspected the task diff. +- The result comment includes a verification result. +- You understand which files changed and why. + +Then continue to [Create your first team](/guide/create-first-team). diff --git a/landing/product-docs/guide/create-first-team.md b/landing/product-docs/guide/create-first-team.md new file mode 100644 index 00000000..bba545a7 --- /dev/null +++ b/landing/product-docs/guide/create-first-team.md @@ -0,0 +1,111 @@ +--- +title: "Create Your First Team - Agent Teams Docs" +description: "Step-by-step setup for a first Agent Teams team with lead, builder, reviewer, roles, models, worktree isolation, and a clear launch brief." +--- + +# Create Your First Team + +This guide walks through the first team setup. The goal is not to build the biggest team possible. The goal is to create a small team that launches reliably and produces reviewable tasks. + +## 1. Open the target project + +Open the project you want agents to work in. Prefer a Git-tracked project so Agent Teams can show diffs, task-linked changes, and review state. + +Before launching, check the baseline: + +```bash +git status --short +``` + +If there are existing user changes, keep them in mind during review. Agent Teams can work in a dirty tree, but review is clearer when you know what existed before launch. + +## 2. Create the team + +Use the team selector, then create a new team for the current project. Give it a short operational name, such as `docs-onboarding`, `landing-fixes`, or `runtime-audit`. + + + +## 3. Start with three roles + +Use this first-team shape: + +| Role | Responsibility | Why it helps | +| --- | --- | --- | +| Lead | Splits the goal into tasks, assigns owners, tracks blockers. | Keeps work coordinated. | +| Builder | Implements scoped tasks. | Produces the actual change. | +| Reviewer | Reviews completed tasks and asks for fixes. | Prevents unreviewed output from being treated as complete. | + +You can add specialists later. For the first run, a small team is easier to debug and review. + +## 4. Choose provider and model per member + +Each member needs a provider and model. Use the most reliable runtime for the lead, because the lead controls task breakdown and coordination. + +Common first setup: + +| Member | Suggested provider style | +| --- | --- | +| Lead | The most reliable model you have available. | +| Builder | A fast model that can handle scoped implementation. | +| Reviewer | A careful model with stronger reasoning. | + +If a provider is missing, fix runtime setup before launching. See [Runtime setup](/guide/runtime-setup). + +## 5. Decide on Worktree + +Enable **Worktree** when teammates may edit the same repository in parallel and you want Git isolation. Keep it off for a very small first run if you want the simplest setup. + +Use Worktree when: + +- multiple teammates can edit code at the same time +- you want cleaner diffs per member +- the project is already Git-tracked + +Avoid Worktree when: + +- the project is not a Git repo +- you are only testing the UI flow +- you want the fewest moving parts for the first launch + +## 6. Write member instructions + +Give each member a short workflow. The member prompt should describe responsibility, not the whole project. + +Lead example: + +```text +Split the user goal into small tasks. Assign clear owners, avoid broad refactors, keep task comments updated, and request review before approval. +``` + +Builder example: + +```text +Implement only the assigned task. Keep changes scoped, post the files you changed, and include the verification command and result before marking work complete. +``` + +Reviewer example: + +```text +Review completed tasks for correctness, regressions, missing tests, and scope creep. Ask for fixes with specific comments before approving. +``` + +## 7. Launch with a narrow goal + +Use a launch brief with outcome, scope, boundaries, and verification: + +```text +Improve the docs onboarding path. Keep changes inside landing/product-docs. Create a beginner-friendly guide sequence, add practical examples, preserve VitePress syntax, and run `pnpm --dir landing docs:build`. +``` + +## 8. Confirm the launch is healthy + +After launch: + +- The lead should create tasks. +- At least one teammate should start a task. +- The board should show movement into In Progress. +- Task comments or logs should show what the teammate is doing. + +If launch hangs or no tasks appear, go to [Troubleshooting](/guide/troubleshooting#team-does-not-launch). + +Next: [Run and monitor work](/guide/run-and-monitor-work). diff --git a/landing/product-docs/guide/review-and-approve.md b/landing/product-docs/guide/review-and-approve.md new file mode 100644 index 00000000..9a32c5c5 --- /dev/null +++ b/landing/product-docs/guide/review-and-approve.md @@ -0,0 +1,88 @@ +--- +title: "Review and Approve - Agent Teams Docs" +description: "A beginner-friendly review workflow for task details, execution logs, code changes, hunk decisions, approvals, and fix requests." +--- + +# Review and Approve + +Do not treat agent work as finished until you have checked the task result, logs, and changes. Review is where you keep quality and scope under control. + +## 1. Open the task + +Start from a task in Review or Done. Read the title, owner, status, and description first. + + + +Look for: + +- a clear task goal +- files or areas that match the requested scope +- a final comment from the teammate +- a verification command and result + +## 2. Check execution evidence + +Execution Logs answer the basic trust questions: + +| Question | What to look for | +| --- | --- | +| Did the agent actually work on this task? | Tool calls, comments, and status changes inside the task timeline. | +| Did it run verification? | Build, test, lint, or docs commands with visible results. | +| Did it coordinate with others? | Messages or comments that explain handoffs and blockers. | +| Did it touch unexpected files? | Changes that do not match the task description. | + +If logs and final comment disagree, ask for clarification before approving. + +## 3. Review the diff + +Open **Changes** and inspect each changed file. + + + +Use this order: + +1. Read the file list. +2. Open each changed file. +3. Check whether the changes match the task. +4. Keep correct hunks. +5. Undo or reject risky hunks. +6. Approve only after all important files are reviewed. + +## 4. Request fixes clearly + +When something is wrong, do not just reject the task. Leave a specific fix request: + +```text +Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting. +``` + +Good fix requests name: + +- what to keep +- what to change +- what to avoid +- what verification is required + +## 5. Approve only when the result is complete + +Approve when: + +- the task scope is satisfied +- the diff matches the task +- verification passed or the missing verification is explicitly justified +- no unrelated changes are mixed in +- comments explain important decisions + +If the task changed docs or UI, also open the relevant page or app screen before approval. + +## 6. Final checklist + +Before closing the review: + +- Files changed are expected. +- The task has a final result comment. +- Verification result is present. +- Risky hunks were checked individually. +- The lead or reviewer marked the task approved. + +If anything is unclear, request changes instead of approving. diff --git a/landing/product-docs/guide/run-and-monitor-work.md b/landing/product-docs/guide/run-and-monitor-work.md new file mode 100644 index 00000000..e498b8d8 --- /dev/null +++ b/landing/product-docs/guide/run-and-monitor-work.md @@ -0,0 +1,100 @@ +--- +title: "Run and Monitor Work - Agent Teams Docs" +description: "Learn how to brief the lead, read the task board, use messages and comments, open task details, and keep agent work moving." +--- + +# Run and Monitor Work + +After the team launches, your job is to keep the work visible, scoped, and reviewable. The board is the main operating surface. + +## 1. Brief the lead clearly + +The lead needs a goal that can be split into tasks. Include: + +- the outcome +- the allowed files or product area +- what not to touch +- verification commands +- when to ask for review + +Good brief: + +```text +Create a beginner docs path. Keep edits inside landing/product-docs. Add screenshots where they clarify actions. Do not touch runtime code. Run `pnpm --dir landing docs:build` before marking tasks complete. +``` + +Weak brief: + +```text +Improve docs. +``` + +The weak brief can work, but it gives the lead too much freedom and makes review harder. + +## 2. Read the board by lane + + + +| Lane | What it means | What you should do | +| --- | --- | --- | +| Todo | Tasks exist but are not active yet. | Check whether task titles are specific enough. | +| In Progress | A teammate is actively working. | Watch for updates and avoid assigning duplicate work. | +| Review | Work needs inspection. | Open the task and review changes. | +| Done | Work is completed but may still need review flow. | Confirm review state before trusting it. | +| Approved | Review passed. | Treat as completed output. | + +## 3. Use messages and comments deliberately + +Use task comments for task-specific context: + +```text +Please keep this task scoped to the quickstart page. Do not change runtime setup wording in this pass. +``` + +Use direct messages for coordination: + +```text +Lead, pause new task creation until the current review queue is cleared. +``` + +Prefer task comments when possible. They stay attached to the work and make review easier. + +## 4. Open task detail when a card needs attention + +Open the task detail when: + +- the title is too vague +- the task has been in progress too long +- the task is ready for review +- the output mentions files you did not expect +- you need to inspect attachments, changes, or logs + + + +## 5. Keep work unblocked + +If a teammate is blocked, ask for the smallest next step: + +```text +Post the blocker, the file or command involved, and the next action you need from the lead or user. +``` + +If the task is too large, ask the lead to split it: + +```text +Split this into separate tasks for copy edits, screenshot assets, and navigation updates. Keep each task independently reviewable. +``` + +## 6. Decide when to stop the team + +Stop or pause when: + +- the review queue is larger than you can inspect +- the lead creates vague tasks repeatedly +- runtime errors appear in multiple tasks +- agents start editing unrelated files +- verification is missing from completed work + +You can always relaunch after tightening the brief. + +Next: [Review and approve](/guide/review-and-approve). diff --git a/landing/product-docs/index.md b/landing/product-docs/index.md index 625c77c5..0a679fd0 100644 --- a/landing/product-docs/index.md +++ b/landing/product-docs/index.md @@ -8,8 +8,8 @@ hero: tagline: Create teams, watch work move across a kanban board, review code changes, and coordinate Claude, Codex, OpenCode, and multimodel workflows without giving up local control. actions: - theme: brand - text: Quickstart - link: /guide/quickstart + text: Beginner workflow + link: /guide/beginner-workflow - theme: alt text: Install link: /guide/installation @@ -62,6 +62,10 @@ Agent Teams is a free desktop app for orchestrating AI agent teams. You are not After creating your first team, explore these guides to go further: - **Runtime setup** - configure Claude, Codex, OpenCode, or multimodel providers: [Configure runtimes](/guide/runtime-setup) +- **Beginner workflow** - follow the complete first-run path from project to approval: [Start the walkthrough](/guide/beginner-workflow) +- **Create your first team** - set up lead, builder, reviewer, roles, models, and Worktree: [Create the team](/guide/create-first-team) +- **Run and monitor work** - read the board, comments, task detail, and logs: [Run the team](/guide/run-and-monitor-work) +- **Review and approve** - inspect task results and code changes before approval: [Review work](/guide/review-and-approve) - **Agent workflow** - understand how agents coordinate through the task board: [Understand workflow](/guide/agent-workflow) - **Team brief examples** - learn prompt patterns from real-world briefs: [See examples](/guide/team-brief-examples) - **Code review** - inspect diffs, accept or reject changes: [Review changes](/guide/code-review) @@ -77,4 +81,4 @@ Use the reference pages when you need exact terminology, provider behavior, cont ## Product preview - + diff --git a/landing/product-docs/ru/guide/beginner-workflow.md b/landing/product-docs/ru/guide/beginner-workflow.md new file mode 100644 index 00000000..9dd2670a --- /dev/null +++ b/landing/product-docs/ru/guide/beginner-workflow.md @@ -0,0 +1,109 @@ +--- +title: "Путь новичка - Документация Agent Teams" +description: "Структурированный первый запуск для новых пользователей: проект, команда, доска задач, карточка задачи и ревью." +lang: ru-RU +--- + +# Путь новичка + +Этот маршрут нужен, если вы впервые открыли Agent Teams и хотите пройти путь от запуска приложения до безопасного approval результата. + +Первый запуск должен доказать четыре вещи: + +1. Приложение открывает ваш проект. +2. Небольшая команда запускается с выбранным runtime. +3. Задачи двигаются по доске и их состояние видно. +4. Вы можете проверить изменения до approval. + +## Базовая модель + +В Agent Teams есть четыре основные рабочие поверхности: + +| Поверхность | Что там делать | +| --- | --- | +| Project и team selector | Выбрать проект и команду, которая будет в нём работать. | +| Team editor | Назвать команду, добавить участников, выбрать роли, модели и worktree-настройки. | +| Task board | Смотреть, как задачи проходят Todo, In Progress, Review, Done и Approved. | +| Task detail и review | Читать задачу, проверять логи, смотреть изменения и approve/request fixes. | + + + +## Рекомендуемый порядок гайдов + +Для первого успешного запуска идите в таком порядке: + +1. [Создать первую команду](/ru/guide/create-first-team) - собрать небольшую команду lead-builder-reviewer. +2. [Запустить и отслеживать работу](/ru/guide/run-and-monitor-work) - дать lead конкретную цель и следить за task board. +3. [Проверить и approve](/ru/guide/review-and-approve) - проверить task detail, logs и code changes. +4. [Диагностика](/ru/guide/troubleshooting) - если запуск, сообщения или task logs выглядят неправильно. + +## Перед запуском + +Начинайте с Git-проекта и понятного baseline: + +```bash +git status --short +``` + +Чистое дерево не обязательно, но важно понимать, какие изменения уже были до запуска агентов. + +Для первого запуска держите команду маленькой: + +| Участник | Первая ответственность | +| --- | --- | +| Lead | Разбивает цель на задачи и координирует статус. | +| Builder | Делает ограниченные implementation tasks. | +| Reviewer | Проверяет завершённые задачи и просит исправления. | + +Не запускайте сразу много участников. Больше агентов - больше логов, параллельных правок, provider usage и review-нагрузки. + +## Шаблон первой цели + +Цель должна иметь scope, границы и verification: + +```text +Improve the documentation quickstart. Keep edits inside landing/product-docs, add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done. +``` + +Хорошая первая цель конкретная, проверяемая и ограничена известной областью. + +## Как выглядит здоровый прогресс + +В здоровом запуске: + +- lead создаёт маленькие задачи, а не одну огромную +- каждый teammate пишет план или progress comment +- работа двигается из Todo в In Progress +- завершённая работа попадает в Review до approval +- task detail показывает description, attachments, changes и execution logs +- финальный comment содержит verification command и result + +## Когда вмешиваться + +Вмешивайтесь, если задача слишком широкая, размытая, заблокирована или без verification. Пишите task comment, если сообщение относится к конкретной задаче. Пишите direct message, если надо перенаправить teammate или lead. + +Примеры: + +```text +Split this into smaller tasks. Each task should have a narrow file scope and a clear verification step. +``` + +```text +Before continuing, post the files you plan to change and the command you will run to verify the result. +``` + +```text +This task is too broad. Keep the change inside the docs guide pages and avoid touching app runtime code. +``` + +## Checklist завершения + +Первый запуск можно считать успешным, если: + +- команда запустилась без runtime errors +- хотя бы одна задача прошла через Review +- вы открыли и проверили diff +- result comment содержит verification result +- понятно, какие файлы изменились и почему + +Дальше: [Создать первую команду](/ru/guide/create-first-team). diff --git a/landing/product-docs/ru/guide/create-first-team.md b/landing/product-docs/ru/guide/create-first-team.md new file mode 100644 index 00000000..3307dfda --- /dev/null +++ b/landing/product-docs/ru/guide/create-first-team.md @@ -0,0 +1,112 @@ +--- +title: "Создать первую команду - Документация Agent Teams" +description: "Пошаговая настройка первой команды: lead, builder, reviewer, роли, модели, worktree isolation и launch brief." +lang: ru-RU +--- + +# Создать первую команду + +Цель первого setup - не собрать самую большую команду, а создать маленькую команду, которая стабильно запускается и делает reviewable tasks. + +## 1. Откройте проект + +Откройте проект, в котором агенты будут работать. Лучше использовать Git-проект, чтобы Agent Teams мог показывать diff, task-linked changes и review state. + +Перед запуском проверьте baseline: + +```bash +git status --short +``` + +Если уже есть ваши изменения, учитывайте их при review. + +## 2. Создайте команду + +Через team selector создайте новую команду для текущего проекта. Название держите коротким и рабочим: `docs-onboarding`, `landing-fixes`, `runtime-audit`. + + + +## 3. Начните с трёх ролей + +Рекомендуемая первая форма команды: + +| Роль | Ответственность | Зачем | +| --- | --- | --- | +| Lead | Делит цель на задачи, назначает owners, отслеживает blockers. | Держит работу скоординированной. | +| Builder | Делает scoped implementation tasks. | Создаёт основное изменение. | +| Reviewer | Проверяет completed tasks и просит fixes. | Не даёт непроверенному результату стать финальным. | + +Специалистов можно добавить позже. Для первого запуска маленькую команду легче диагностировать и ревьюить. + +## 4. Выберите provider и model для каждого + +Каждому участнику нужен provider и model. Для lead выбирайте самый надёжный runtime, потому что lead управляет decomposition и coordination. + +Обычная первая настройка: + +| Участник | Какой provider выбрать | +| --- | --- | +| Lead | Самую надёжную модель из доступных. | +| Builder | Быструю модель для scoped implementation. | +| Reviewer | Более аккуратную модель с сильным reasoning. | + +Если provider отсутствует, сначала исправьте runtime setup: [Настройка рантайма](/ru/guide/runtime-setup). + +## 5. Решите, нужен ли Worktree + +Включайте **Worktree**, когда участники могут параллельно менять один репозиторий и нужна Git-изоляция. Для самого простого первого запуска можно оставить выключенным. + +Worktree полезен, когда: + +- несколько teammates могут одновременно менять код +- нужны более чистые diffs по участникам +- проект уже является Git-репозиторием + +Не включайте Worktree, если: + +- проект не в Git +- вы только проверяете UI flow +- хотите минимум движущихся частей в первом запуске + +## 6. Напишите инструкции участникам + +Member prompt должен описывать ответственность участника, а не весь проект. + +Lead: + +```text +Split the user goal into small tasks. Assign clear owners, avoid broad refactors, keep task comments updated, and request review before approval. +``` + +Builder: + +```text +Implement only the assigned task. Keep changes scoped, post the files you changed, and include the verification command and result before marking work complete. +``` + +Reviewer: + +```text +Review completed tasks for correctness, regressions, missing tests, and scope creep. Ask for fixes with specific comments before approving. +``` + +## 7. Запустите с узкой целью + +Launch brief должен содержать outcome, scope, boundaries и verification: + +```text +Improve the docs onboarding path. Keep changes inside landing/product-docs. Create a beginner-friendly guide sequence, add practical examples, preserve VitePress syntax, and run `pnpm --dir landing docs:build`. +``` + +## 8. Проверьте, что запуск здоровый + +После запуска: + +- lead создаёт задачи +- хотя бы один teammate начинает задачу +- board показывает движение в In Progress +- task comments или logs показывают, что делает teammate + +Если запуск завис или задач нет, откройте [Диагностику](/ru/guide/troubleshooting#team-does-not-launch). + +Дальше: [Запустить и отслеживать работу](/ru/guide/run-and-monitor-work). diff --git a/landing/product-docs/ru/guide/review-and-approve.md b/landing/product-docs/ru/guide/review-and-approve.md new file mode 100644 index 00000000..b3de221d --- /dev/null +++ b/landing/product-docs/ru/guide/review-and-approve.md @@ -0,0 +1,89 @@ +--- +title: "Проверить и approve - Документация Agent Teams" +description: "Понятный workflow ревью: task detail, execution logs, code changes, hunk decisions, approvals и fix requests." +lang: ru-RU +--- + +# Проверить и approve + +Не считайте работу агента завершённой, пока не проверили результат задачи, logs и changes. Review удерживает качество и scope. + +## 1. Откройте задачу + +Начните с задачи в Review или Done. Сначала прочитайте title, owner, status и description. + + + +Проверьте: + +- понятная ли цель задачи +- совпадают ли файлы с ожидаемым scope +- есть ли final comment от teammate +- есть ли verification command и result + +## 2. Проверьте execution evidence + +Execution Logs отвечают на базовые вопросы доверия: + +| Вопрос | Что искать | +| --- | --- | +| Агент реально работал над этой задачей? | Tool calls, comments и status changes внутри task timeline. | +| Он запускал verification? | Build, test, lint или docs commands с результатом. | +| Он координировался с другими? | Messages или comments с handoffs и blockers. | +| Он трогал неожиданные файлы? | Changes, которые не совпадают с task description. | + +Если logs и final comment расходятся, попросите уточнение до approval. + +## 3. Проверьте diff + +Откройте **Changes** и просмотрите каждый changed file. + + + +Порядок: + +1. Прочитать file list. +2. Открыть каждый changed file. +3. Проверить, что изменения совпадают с задачей. +4. Keep для правильных hunks. +5. Undo или reject для рискованных hunks. +6. Approve только после проверки важных files. + +## 4. Просите fixes конкретно + +Если что-то не так, не ограничивайтесь reject. Оставьте конкретный fix request: + +```text +Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting. +``` + +Хороший fix request называет: + +- что оставить +- что изменить +- чего избегать +- какая verification обязательна + +## 5. Approve только полный результат + +Approve уместен, когда: + +- task scope закрыт +- diff совпадает с задачей +- verification прошёл или отсутствие verification объяснено +- нет unrelated changes +- comments объясняют важные решения + +Если task менял docs или UI, перед approval откройте соответствующую страницу или экран приложения. + +## 6. Финальный checklist + +Перед закрытием review: + +- изменённые files ожидаемые +- есть final result comment +- есть verification result +- risky hunks проверены отдельно +- lead или reviewer поставил approved + +Если что-то непонятно, request changes лучше, чем approve. diff --git a/landing/product-docs/ru/guide/run-and-monitor-work.md b/landing/product-docs/ru/guide/run-and-monitor-work.md new file mode 100644 index 00000000..a926b308 --- /dev/null +++ b/landing/product-docs/ru/guide/run-and-monitor-work.md @@ -0,0 +1,101 @@ +--- +title: "Запустить и отслеживать работу - Документация Agent Teams" +description: "Как дать lead понятный brief, читать task board, использовать messages и comments, открывать task detail и удерживать работу в движении." +lang: ru-RU +--- + +# Запустить и отслеживать работу + +После запуска команды ваша задача - держать работу видимой, ограниченной и готовой к review. Главная поверхность - board. + +## 1. Дайте lead понятный brief + +Lead нужна цель, которую можно разбить на задачи. Укажите: + +- outcome +- разрешённые файлы или область продукта +- что не трогать +- verification commands +- когда просить review + +Хороший brief: + +```text +Create a beginner docs path. Keep edits inside landing/product-docs. Add screenshots where they clarify actions. Do not touch runtime code. Run `pnpm --dir landing docs:build` before marking tasks complete. +``` + +Слабый brief: + +```text +Improve docs. +``` + +Слабый brief даёт lead слишком много свободы и усложняет review. + +## 2. Читайте board по колонкам + + + +| Колонка | Что значит | Что делать | +| --- | --- | --- | +| Todo | Задачи есть, но ещё не активны. | Проверить, достаточно ли конкретные titles. | +| In Progress | Teammate активно работает. | Смотреть updates и не назначать duplicate work. | +| Review | Работу нужно проверить. | Открыть task и review changes. | +| Done | Работа завершена, но может требовать review flow. | Проверить review state перед доверием результату. | +| Approved | Review прошёл. | Считать результат завершённым. | + +## 3. Используйте messages и comments осознанно + +Task comments подходят для контекста конкретной задачи: + +```text +Please keep this task scoped to the quickstart page. Do not change runtime setup wording in this pass. +``` + +Direct messages подходят для координации: + +```text +Lead, pause new task creation until the current review queue is cleared. +``` + +Если возможно, предпочитайте task comments. Они остаются привязанными к работе. + +## 4. Открывайте task detail, когда карточке нужно внимание + +Открывайте task detail, если: + +- title слишком размытый +- задача слишком долго in progress +- задача готова к review +- output упоминает неожиданные файлы +- нужно проверить attachments, changes или logs + + + +## 5. Разблокируйте работу + +Если teammate заблокирован, попросите минимальный следующий шаг: + +```text +Post the blocker, the file or command involved, and the next action you need from the lead or user. +``` + +Если задача слишком большая, попросите lead разделить её: + +```text +Split this into separate tasks for copy edits, screenshot assets, and navigation updates. Keep each task independently reviewable. +``` + +## 6. Когда остановить команду + +Остановите или поставьте на паузу, если: + +- review queue больше, чем вы можете проверить +- lead повторно создаёт размытые задачи +- runtime errors появляются в нескольких задачах +- агенты начали менять unrelated files +- completed work не содержит verification + +Команду можно перезапустить после уточнения brief. + +Дальше: [Проверить и approve](/ru/guide/review-and-approve). diff --git a/landing/product-docs/ru/index.md b/landing/product-docs/ru/index.md index f74cde89..50dde499 100644 --- a/landing/product-docs/ru/index.md +++ b/landing/product-docs/ru/index.md @@ -9,8 +9,8 @@ hero: tagline: Создавайте команды, наблюдайте за канбан-доской, ревьюйте изменения и координируйте Claude, Codex, OpenCode и multimodel workflows без потери локального контроля. actions: - theme: brand - text: Быстрый старт - link: /ru/guide/quickstart + text: Путь новичка + link: /ru/guide/beginner-workflow - theme: alt text: Установка link: /ru/guide/installation @@ -63,6 +63,10 @@ Agent Teams - бесплатное desktop-приложение для орке После создания первой команды изучите эти руководства: - **Настройка рантайма** - настройте Claude, Codex, OpenCode или multimodel-провайдеров: [Настроить рантаймы](/ru/guide/runtime-setup) +- **Путь новичка** - полный первый маршрут от проекта до approval: [Начать walkthrough](/ru/guide/beginner-workflow) +- **Создать первую команду** - lead, builder, reviewer, роли, модели и Worktree: [Создать команду](/ru/guide/create-first-team) +- **Запустить и отслеживать работу** - board, comments, task detail и logs: [Запустить работу](/ru/guide/run-and-monitor-work) +- **Проверить и approve** - task results и code changes до approval: [Проверить работу](/ru/guide/review-and-approve) - **Workflow агентов** - как агенты координируются через task board: [Разобрать workflow](/ru/guide/agent-workflow) - **Примеры team briefs** - паттерны промптов из реальных примеров: [Примеры](/ru/guide/team-brief-examples) - **Код-ревью** - проверяйте diff, принимайте или отклоняйте изменения: [Ревью изменений](/ru/guide/code-review) @@ -78,4 +82,4 @@ Agent Teams - бесплатное desktop-приложение для орке ## Превью продукта - + diff --git a/landing/product-docs/tsconfig.json b/landing/product-docs/tsconfig.json new file mode 100644 index 00000000..ef62ebe0 --- /dev/null +++ b/landing/product-docs/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "Bundler", + "lib": ["ES2022", "DOM", "DOM.Iterable"], + "types": ["vitepress/client"], + "strict": true, + "skipLibCheck": true, + "resolveJsonModule": true, + "isolatedModules": true, + "noEmit": true + }, + "include": [".vitepress/**/*.ts", ".vitepress/**/*.vue"] +} diff --git a/landing/public/screenshots/guides/code-review-annotated.png b/landing/public/screenshots/guides/code-review-annotated.png new file mode 100644 index 00000000..33688239 Binary files /dev/null and b/landing/public/screenshots/guides/code-review-annotated.png differ diff --git a/landing/public/screenshots/guides/create-team-annotated.png b/landing/public/screenshots/guides/create-team-annotated.png new file mode 100644 index 00000000..b93cf64b Binary files /dev/null and b/landing/public/screenshots/guides/create-team-annotated.png differ diff --git a/landing/public/screenshots/guides/task-board-annotated.png b/landing/public/screenshots/guides/task-board-annotated.png new file mode 100644 index 00000000..ec57cbc8 Binary files /dev/null and b/landing/public/screenshots/guides/task-board-annotated.png differ diff --git a/landing/public/screenshots/guides/task-detail-annotated.png b/landing/public/screenshots/guides/task-detail-annotated.png new file mode 100644 index 00000000..be8517aa Binary files /dev/null and b/landing/public/screenshots/guides/task-detail-annotated.png differ diff --git a/landing/public/screenshots/product-preview.jpg b/landing/public/screenshots/product-preview.jpg new file mode 100644 index 00000000..d1ae6f0d Binary files /dev/null and b/landing/public/screenshots/product-preview.jpg differ