AGENT-FLOW (AI-Powered Development Workflow Assistant)

Що це за проєкт

AI-Powered Development Workflow Assistant — це система автоматизації процесу розробки програмного забезпечення, яка допомагає розробнику перетворювати неформальні обговорення та ідеї у структуровані завдання, а потім супроводжує весь цикл їх виконання: від створення гілки у Git до ревʼю коду штучним інтелектом та оновлення документації.

Що робить система

1. Перетворення обговорень у структуровані плани

Ви обговорюєте проєкт з колегою, ШІ-асистентом або просто робите нотатки про те, що потрібно зробити. Потім копіюєте весь цей текст у систему, і вона:

• Аналізує неструктуровану інформацію
• Виділяє ключові рішення та завдання
• Формує чіткий структурований план
• Дає вам можливість перевірити й виправити план перед тим, як він піде у роботу

2. Автоматичне створення завдань

Після вашого підтвердження система:

• Перетворює план в ієрархію завдань (епіки, задачі, підзадачі)
• Генерує критерії готовності для кожного завдання
• Прикріплює артефакти (файли, посилання, скриншоти)
• Додає завдання у вашу робочу дошку

3. Канбан-управління завданнями

Система надає візуальну дошку завдань у стилі Kanban зі стовпчиками:

• Нові завдання — щойно створені, ще не заплановані
• Наступні завдання — заплановані до виконання
• У роботі — ви активно над ними працюєте
• На доопрацюванні — потребують виправлень після ревʼю
• Виконано — завершені та змерджені

Ви можете переміщати завдання простими кліками кнопок.

4. Автоматизація Git workflow

Коли ви берете завдання у роботу, система:

• Автоматично створює feature-гілку на GitHub з правильною назвою
• Ви працюєте у цій гілці локально, робите коміти та пушите зміни
• Коли готові — одна кнопка ініціює процес ревʼю

5. Автоматичне ревʼю коду через ШІ

Після вашого запиту на ревʼю система:

• Створює Pull Request на GitHub
• Передає всі зміни у коді штучному інтелекту
• ШІ аналізує код на предмет проблем, вразливостей, помилок
• ШІ може дати одну з трьох відповідей:
  • APPROVED — все добре, код можна мерджити
  • REQUEST_CHANGES — є проблеми, які треба виправити
  • QUESTIONS — треба щось пояснити або уточнити

6. Інтерактивний процес доопрацювання

Якщо ШІ запитує або вимагає змін:

• Коментарі та питання публікуються безпосередньо у Pull Request
• Ви читаєте їх, відповідаєте або виправляєте код
• Запускаєте повторне ревʼю однією кнопкою
• Процес повторюється до схвалення

7. Автоматичний мердж та закриття

Коли ШІ схвалює код:

• Pull Request автоматично мерджиться до основної гілки
• Feature-гілка видаляється
• PR закривається
• Завдання переміщується у "Виконано"

8. Оновлення документації

Після успішного завершення завдання:

• Система аналізує зроблені зміни
• Автоматично оновлює відповідні розділи документації
• Документація завжди актуальна

Чим може бути корисним

Для індивідуальних розробників:

• ✅ Структурування хаосу ідей — перетворення безладних думок у чіткий план
• ✅ Автоматизація рутини — не треба вручну створювати гілки, PR, писати шаблони
• ✅ Додатковий погляд на код — ШІ може помітити те, що ви пропустили
• ✅ Самодисципліна — структурований workflow допомагає не забувати про важливі етапи
• ✅ Актуальна документація — документація оновлюється автоматично, а не коли "знайдеться час"

Для малих команд:

• ✅ Єдиний workflow — усі працюють за однією схемою
• ✅ Прозорість процесу — чітко видно, хто над чим працює
• ✅ Зменшення навантаження на ревʼю — ШІ виловлює базові помилки, людина дивиться на архітектуру
• ✅ Швидший onboarding — новачки одразу розуміють процес

Для навчання:

• ✅ Вчитися best practices — ШІ коментує код з поясненнями
• ✅ Розуміння Git flow — система демонструє правильний робочий процес
• ✅ Формування навичок планування — учитися розбивати завдання на підзадачі

Для MVP та стартапів:

• ✅ Швидкий старт — не треба налаштовувати складні CI/CD спочатку
• ✅ Гнучкість — легко адаптувати під свій процес
• ✅ Економія часу — автоматизація дає більше часу на продукт

Основні переваги системи

• Єдине місце для всього процесу — від ідеї до виконання
• Мінімум ручної роботи — більшість рутини автоматизована
• ШІ як асистент, не замінник — ви контролюєте процес, ШІ допомагає
• Прозорість та історія — усе фіксується у GitHub та БД
• Гнучкість — можна адаптувати під свій workflow

Швидкий старт

# Clone
git clone https://github.com/your-org/ai-workflow-assistant.git
cd ai-workflow-assistant

# Install
pnpm install

# Setup environment
cp .env.example .env
# Заповніть .env файл

# Run dev
pnpm dev

Розробка

Git Workflow

⚠️ ВАЖЛИВО: Перш ніж почати розробку, прочитайте Git Workflow Guide

Коротко:

1. Створіть issue, потім гілку від main:

   git checkout main
   git pull origin main
   git checkout -b feature/0123-your-feature-name

   ⚠️ Номер issue обов'язковий (мінімум 4 цифри, наприклад: 0001, 0042, 1234)

2. Робіть коміти за Conventional Commits:

   git commit -m "feat(scope): description"

3. Відкрийте Pull Request коли готово

4. Після мерджу видаліть гілку

Детальніше: docs/guides/git-workflow.md

Naming Conventions

Гілки:

• feature/0001-architect-agent-implementation
• fix/0042-kanban-drag-drop-issue
• docs/0099-api-documentation

⚠️ Номер issue обов'язковий (мінімум 4 цифри)

Commits:

• feat(architect): add draft creation service
• fix(kanban): resolve mobile drag issue
• docs(readme): update setup instructions

Детальніше: docs/guides/naming-conventions.md

Код

# Lint
pnpm lint

# Format
pnpm format

    # Type check
    pnpm type-check

# Test
pnpm test

Архітектурні рішення

Всі архітектурні рішення документовані у Architecture Decision Records (ADR):

• ADR-001: Backend Framework (NestJS)
• ADR-015: Git Workflow
• Повний список ADR

Структура проєкту

Використовується Flat Modular Architecture with Shared Layer ( див. ADR-024):

agent-flow-v2/
├── src/                         # 🎯 ВЕСЬ КОД ТУТ
│   ├── modules/                 # 🤖 Domain modules (бізнес-логіка)
│   │   ├── architect-agent/     #    AI агент аналізу та планування
│   │   ├── workflow-agent/      #    AI агент виконання завдань
│   │   ├── code-review-agent/   #    AI агент code review
│   │   └── documentation-agent/ #   AI агент документації
│   └── components/              # ⚙️  Shared components (інфраструктура)
│       ├── api/                 # 🌐 API Gateway
│       ├── database/            # 🗄️  Database service (Prisma)
│       ├── queue/               # 📬 Event Queue (BullMQ)
│       ├── logger/              # 📝 Logging (Pino)
│       ├── config/              # ⚙️  Configuration
│       ├── ai-provider/         # 🤖 AI Provider integration
│       ├── github/              # 🔌 GitHub integration
│       └── dashboard/           # 🎨 Frontend (Next.js)
├── tests/                       # 🧪 E2E tests
├── scripts/                     # 🛠️  Utility scripts
├── docs/                        # 📚 Documentation
└── [config files]

Правила архітектури:

• 🔒 modules/ — тільки доменні модулі, незалежні один від одного
• 📬 Взаємодія між модулями — тільки через Event Queue (рідко через HTTP)
• ⚙️ components/ — shared інфраструктура, може залежати від інших компонентів
• ❌ components/ НЕ може залежати від modules/ (виняток: components/api/)

Документація

• Для розробників:

  • Git Workflow ⭐
  • Coding Standards/Conventions ⭐
  • Testing Guide
  • System Design
  • Requirements
  • Deployment

• Архітектура:

  • Architecture Overview
  • ADR Index
  • Module Structure

• API:

  • API Documentation
  • Event Schema

Available Scripts

Script	Description
pnpm dev	Start backend + dashboard in dev mode
pnpm build	Build backend + dashboard for production
pnpm test	Run all unit tests
pnpm lint	Lint all TypeScript/JavaScript files
pnpm format	Format all files with Prettier
pnpm type-check	TypeScript type check
pnpm setup	One-time project setup after clone
pnpm release	Create a new release
pnpm check:structure	Validate project directory structure
pnpm generate:agent	Scaffold a new agent module
pnpm generate:api	Scaffold a new API endpoint
pnpm generate:integration	Scaffold a new integration
pnpm prisma:migrate	Run database migrations (dev)
pnpm prisma:studio	Open Prisma Studio

Security

Please report security vulnerabilities responsibly. See SECURITY.md for our disclosure policy.

Contributing

Прочитайте CONTRIBUTING.md перед тим як почати розробку.

License

MIT