title: SPARC upgrade — план переведення PM-Agent і Dev Crew date: 2026-05-10 status: draft, чекаю ОК Сергія author: VPS Claude

SPARC upgrade — план

TL;DR

Переводимо PM-Agent (v0.3 → v0.4) і Dev Crew (v1 → v2) на SPARC-методологію (Specification → Pseudocode → Architecture → Refinement → Completion). Ефект: предсказувані артефакти на кожній фазі, readiness_pct рахується точно (= завершених фаз / 5), Dev Crew працює waterfall-pipeline'ом замість fan-out.

Старі версії в backup'ах для миттєвого rollback. Поточні проекти не ламаємо — мігруємо поступово.

Стан "як є" (baseline)

PM-Agent v0.3 (`/srv/services/pm-agent/pm_agent.py`, 712 рядків)

Щоночі:

Читає /srv/wiki/projects/, оновлює last_updated frontmatter
Пропонує readiness_pct зміни (safety: ±10%/добу)
Додає ## 🤖 PM Changelog → ### YYYY-MM-DD секції у index.md
git commit у /srv/wiki з підписом «🤖 PM Agent v0.3»
Збирає відповіді Сергія з /srv/services/pm-agent/answers/

Dev Crew v1 (`/srv/projects/dev-crew/crew.py`, 332 рядки)

IT Director аналізує задачу → JSON з підзадачами
Fan-out 6 ролям паралельно: backend_dev, frontend_dev, code_analyst, qa_tester, ui_ux, devops
Збирає всі відповіді у JSON
Не працює послідовно, не має артефактів за фазами

Стан "як буде" (after SPARC upgrade)

Концепція

Кожен проект (новий або поточний) має 5 SPARC-артефактів у /srv/wiki/projects/<area>/<slug>/sparc/:

sparc/
├── 01-specification.md   # S — що робимо і навіщо
├── 02-pseudocode.md      # P — flow без коду
├── 03-architecture.md    # A — стек, файлова структура, інтерфейси
├── 04-refinement.md      # R — TDD-цикл, тести, реалізація
└── 05-completion.md      # C — рев'ю, документація, deploy verification

readiness_pct рахується автоматично: (completed_phases / 5) * 100, з гранулярністю 20%.

PM-Agent v0.4

Додаємо до v0.3 функціоналу:

Phase detector — для кожного проекту визначає поточну SPARC-фазу
- Перевіряє наявність артефактів у sparc/
- Перевіряє frontmatter: sparc_phase: S|P|A|R|C|complete
Readiness recalculation — readiness тепер = функція від фази
- Видаляємо ручні ±10% оцінки → фіксована формула
Phase advancement notifications — у Telegram digest пише:
- «proj-X: завершено фаза S, переходимо до P»
- «proj-Y: фаза R активна 5 днів, нагадую про CTO-review перед C»
SPARC bootstrap — для проекту без sparc/ папки вміє згенерувати 01-specification.md з існуючого index.md (legacy migration)

Dev Crew v2

Переробляємо на pipeline по SPARC-фазах. Кожна роль закріплена за фазою:

Фаза	Відповідальний	Артефакт
S — Specification	IT Director (як Spec Author)	`01-specification.md`
P — Pseudocode	Code Analyst	`02-pseudocode.md`
A — Architecture	UI/UX + Code Analyst (паралельно)	`03-architecture.md`
R — Refinement	Backend + Frontend + QA Tester (TDD-цикл)	`04-refinement.md` + tests + код
C — Completion	QA Tester + DevOps	`05-completion.md` + smoke + deploy verification

Запуск:

python3 crew.py --project <name> --phase S      # тільки S фаза
python3 crew.py --project <name> --phase auto   # авто-перехід через всі 5
python3 crew.py --project <name> --resume       # продовжити з поточної фази

Не fan-out, а waterfall: фаза P не починається поки S не апрувнута (Telegram review gate, як у Case Builder).

Slash-команди (новий додаток)

Інтерактивні скіли для мене (Telegram bot) і Desktop:

/sparc-spec <task> — створює 01-specification.md з вимогами
/sparc-pseudocode — переходить до P, генерує flow
/sparc-arch — переходить до A
/sparc-refine — TDD-цикл (R)
/sparc-complete — фінальна перевірка (C)
/sparc-status <project> — показує поточну фазу + блокери

План впровадження (4 етапи)

Etap 1 — Foundation (1 день)

[ ] Створити /srv/wiki/_templates/sparc/ з 5 шаблонами артефактів
[ ] Документувати SPARC у /srv/wiki/_meta/sparc-methodology.md (canonical reference)
[ ] Додати правило #18 у rules.md: «новий проект → SPARC pipeline; старий → migration через bootstrap»

Etap 2 — PM-Agent v0.4 (1 день)

[ ] Backup pm_agent.py.bak-v0.3
[ ] Додати phase detector + readiness recalc
[ ] Додати SPARC bootstrap для legacy проектів
[ ] Тестовий run на 1 проекті (наприклад, med-detective/filtrum/ — він в pre-S стані, ідеально для bootstrap)

Etap 3 — Dev Crew v2 (1.5 дні)

[ ] Backup crew.py.bak-v1
[ ] Перепис на waterfall pipeline з phase-gating
[ ] Telegram review gate перед кожним переходом фази
[ ] Тестовий run на real-world задачі (взяти найбільш «свіжу»)

Etap 4 — Slash-команди (0.5 дня)

[ ] Налаштувати 6 slash-команд через /usr/local/bin/claude-skill-*
[ ] Додати у MEMORY.md / agents_inventory новий розділ «SPARC Skills»

Загалом: 4 дні активної роботи.

Migration legacy проектів (15 проектів у MEMORY.md)

Не примусово. Кожен існуючий проект отримує SPARC bootstrap при першому PM-Agent run:

Якщо немає sparc/ папки → PM-Agent генерує 01-specification.md з index.md
Frontmatter оновлюється: sparc_phase: bootstrap
Сергій ревью'є / редагує / переводить у sparc_phase: S
Далі — звичайний flow через slash-команди або Dev Crew v2

Активні проекти у пріоритеті: ad-analytics-hub підпроекти (5 шт), med-detective підпроекти (4 шт), interactive-banners (2-3 шт), pediatric-news, biogaia-story.

Що НЕ робимо у цьому апгрейді

Не чіпаємо інші crews (Case Builder, Google Ads, legal-advisor, Scout) — вони доменні, SPARC їм не релевантний
Не міняємо Reports Hub, Wiki structure, Passepartout, Memory system
Не додаємо AgentDB / semantic search (це наступна ітерація після SPARC, окремий план)
Не переходимо на ruflo як фреймворк — просто запозичуємо ідею SPARC

Ризики

Ризик	Mitigation
PM-Agent v0.4 ламає wiki commit cycle	Backup + миттєвий rollback `mv pm_agent.py.bak-v0.3 pm_agent.py`
Dev Crew v2 не вміє з legacy задачами	Залишаємо v1 як `crew_v1.py`, перемикаємо CLI flag
SPARC занадто формальний для маленьких задач	Додаємо `--quick` режим: тільки S+R+C, пропускаємо P і A
Migration 15 проектів зайня тиждень	Поетапно: 1-2 проекти на день, у фоні

Запитання до Сергія перед стартом

ОК на 4 дні роботи (Etap 1-4) — починаємо зараз послідовно, чи з паузами?
Telegram review gate перед кожним переходом фази (як у Case Builder) — чи занадто шумно? Можна гейтити лише на S→P і R→C, проміжні авто.
Який проект взяти першим для тестового SPARC-bootstrap'у? Пропоную med-detective/filtrum (новий, у pre-S стані).
Запозичуємо --quick режим (S+R+C) для маленьких задач, щоб не оверкіл — згоден?

Артефакти цього плану

Після ОК Сергія:

Цей файл переходить у status: approved, готую 01-specification.md для самого SPARC-upgrade'у (іронія — починаємо з SPARC-S)
Створюю TaskList з 4 фаз
Виходжу на Etap 1