@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/pipeline.en.md

@@ -0,0 +1,400 @@
+# Development pipeline
+
+The canonical pipeline of the harness goes from **discovery** (understanding the problem) to **delivery** (merge with green tests and vault recording). Each stage has a responsible agent, concrete input/output artifacts, and checkpoints for the human.
+
+This document describes the full path. For trivial changes or hotfixes, shortcuts are documented at the end.
+
+## Macro view
+
+```
+discovery → specification → planning → architecture → execution → validation → recording
+                                                          │
+                                                          ▼
+                                                  gate-keeper blocks
+                                                  if thresholds fail
+```
+
+## Full pipeline diagram
+
+```
+┌──────────┐    ┌────────┐    ┌──────────┐    ┌─────────┐    ┌───────────┐    ┌──────────┐
+│ grill-me │ -> │ to-prd │ -> │to-issues │ -> │ analyst │ -> │ architect │ -> │tech-lead │
+│(skill)   │    │(skill) │    │ (skill)  │    │ (agent) │    │  (agent)  │    │ (approve)│
+└──────────┘    └────────┘    └──────────┘    └─────────┘    └───────────┘    └────┬─────┘
+                                                                                   │
+                                                                                   ▼
+                              ┌────────────────────────────────────────────────────────┐
+                              │ sprint-runner (skill+agent)                            │
+                              │   ├─► qa-engineer (TDD: failing tests)                 │
+                              │   ├─► backend-developer  ┐                             │
+                              │   ├─► frontend-developer ├─ parallel                   │
+                              │   ├─► database-engineer  ┘                             │
+                              │   └─► gate-keeper (validate senior+)                   │
+                              └────────────────────────────────┬───────────────────────┘
+                                                               │
+                                                               ▼
+                                            ┌─────────────────────────────────┐
+                                            │ code-reviewer → tech-lead (rev) │
+                                            └────────────┬────────────────────┘
+                                                         │
+                                                         ▼
+                                            ┌─────────────────────────────────┐
+                                            │ api-integration-test (curl+MCP) │
+                                            └────────────┬────────────────────┘
+                                                         │
+                                                         ▼
+                                            ┌─────────────────────────────────┐
+                                            │ prd-ready-check (GO / NO-GO)    │
+                                            └────────────┬────────────────────┘
+                                                         │
+                                                         ▼
+                                            ┌─────────────────────────────────┐
+                                            │ tech-lead (merge OR return)     │
+                                            └────────────┬────────────────────┘
+                                                         │
+                                                         ▼
+                                            ┌─────────────────────────────────┐
+                                            │ brain-keeper (Obsidian vault)   │
+                                            └─────────────────────────────────┘
+```
+
+## Stages in detail
+
+### 1. Discovery (`grill-me`)
+
+**When it fires**: user says "grill me", "interview me about X", "stress-test the plan". Opt-in — never auto-triggered.
+
+**Input**: vague initial description ("I want to allow product signup").
+
+**How it works**: the skill runs an interactive interview, one question at a time, with recommendations. Continues until requirements are clear (typically 5-15 questions).
+
+**Output**: `docs/discovery/DISCOVERY_<feature-slug>.md` containing:
+- Problem
+- Personas involved
+- Constraints (legal, technical, business)
+- Hypotheses validated and to be validated
+- Handoff to `analyst` or proposed ADR
+
+**Next step**: `to-prd` (if it becomes a product) or directly to `analyst` (if it becomes an immediate sprint).
+
+⏸️ **Checkpoint**: human confirms the DISCOVERY before continuing.
+
+### 2. PRD (`to-prd`)
+
+**When it fires**: "to-prd", "generate PRD", "create PRD". Opt-in — requires `grill-me` to have run first.
+
+**Input**: `docs/discovery/DISCOVERY_<slug>.md`.
+
+**Output**: `docs/prd/PRD_<slug>.md` with 6 mandatory sections:
+1. Overview
+2. Goals
+3. User Stories (in prose, with persona + motivation)
+4. Functional Requirements
+5. Non-functional Requirements
+6. Out of scope
+
+**Next step**: `to-issues`.
+
+Idempotent — can be re-run; overwrites with merge.
+
+### 3. Issues (`to-issues`)
+
+**When it fires**: "to-issues", "break into issues". Opt-in — requires an existing PRD.
+
+**Input**: `docs/prd/PRD_<slug>.md`.
+
+**Output**: `docs/issues/ISSUES_<slug>.md` with `[ISSUE-N]` blocks ready for `gh issue create`:
+
+```
+[ISSUE-1]
+Labels: backend, api, sprint-1
+Body: |
+  Implement POST /api/v1/products...
+Acceptance criteria:
+- DTO validates required name
+- Returns 201 with Location header
+- Persists product + audit log
+```
+
+**Next step**: `analyst`.
+
+### 4. Plan (`analyst`)
+
+**When it fires**: direct call by `project-manager`, `sprint-runner`, or via "create plan for X".
+
+**Input**: `DISCOVERY_*.md` + `PRD_*.md` + `ISSUES_*.md` (when present). On the human path, requires a discovery artifact (`DISCOVERY_*.md`, PLAN seed, or Proposed ADR) — see ADR-013 + ADR-017. Autonomous callers (`sprint-runner`, `release-engineer`) are exempt via `caller: sprint-runner|autonomous` in the Task prompt.
+
+**Output**: `docs/plans/PLAN_<slug>.md` with:
+- Goal-ready DoD (verifiable by `/goal` command)
+- Sprints (1, 2, 3...) with tasks (T1, T2...)
+- Dependencies between tasks
+- Estimates (in "complexity", not hours)
+- Definition of Done per task
+
+**Next step**: `architect` (if there is a new macro decision) or directly to `tech-lead` (if it is only an established pattern).
+
+⏸️ **Checkpoint**: human confirms the PLAN.
+
+### 5. Architecture (`architect`)
+
+**When it fires**: PLAN includes a new macro decision (new lib, new pattern, new bounded context, relevant tech choice).
+
+**Input**: PLAN + project context + prior decisions in `docs/decisions/`.
+
+**Output**: `docs/decisions/ADR-NNN-<slug>.md` (proposed) following the MADR template:
+- Status: Proposed
+- Context
+- Decision drivers
+- Considered options
+- Decision outcome
+- Consequences
+
+**Next step**: `tech-lead` reviews and approves (Status: Accepted) or requests revision (Status: Rejected → back).
+
+### 6. Approval (`tech-lead`)
+
+**When it fires**: after `architect` produces an ADR; or at the end of the PLAN when there are patterns to approve.
+
+**Input**: PLAN + proposed ADR(s).
+
+**Output**: ADR with Status: Accepted (or Rejected with reason). Updates `CLAUDE.md` if the decision changes a stack rule.
+
+**Next step**: `sprint-runner`.
+
+⏸️ **Checkpoint**: human confirms ADRs before execution.
+
+### 7. Execution (`sprint-runner`)
+
+**When it fires**: "run sprint X", "execute the sprint". Skill that orchestrates the full execution.
+
+**Input**: `docs/plans/PLAN_<slug>.md`, Sprint N parameter.
+
+**How it works**: mandatory TDD cycle per task:
+
+#### 7a. `qa-engineer` writes failing tests
+
+For each sprint task, `qa-engineer` creates tests **before** the implementation:
+- Backend: JUnit 5 + Mockito + Testcontainers
+- Frontend: Jest + Testing Library + jest-axe
+- E2E: Playwright + @axe-core/playwright
+
+The tests fail (the implementation does not yet exist). That is correct.
+
+#### 7b. Developers implement in parallel
+
+`sprint-runner` dispatches in parallel (when tasks do not share files):
+- `backend-developer` — implements controller, service, repo, security
+- `frontend-developer` — implements component, service, route
+- `database-engineer` — generates Flyway migration + indexes
+
+Each developer runs the tests locally until green before marking the task done.
+
+#### 7c. `gate-keeper` validates senior+ thresholds
+
+After developers finish, `gate-keeper` runs the full gate (see [Quality gate](quality-gate)):
+- JaCoCo coverage >= 85% lines, >= 80% branches
+- PIT mutation >= 70% in `domain/`+`application/`
+- Jest >= 85% statements, >= 80% branches
+- SpotBugs, ESLint, npm audit, OWASP DC
+- Playwright, jest-axe, Lighthouse
+- E2E test pyramid <= 30%
+
+If any fails → blocks + returns to the responsible task.
+
+**Output**: implemented code + green tests + GREEN gate.
+
+### 8. Code review (`code-reviewer`)
+
+**When it fires**: after sprint-runner finishes a task or sprint.
+
+**Input**: branch diff.
+
+**Output**: structured feedback: bugs, edge cases, questions, refactor suggestions.
+
+**Next step**: developer fixes (or `tech-lead` decides whether feedback is valid).
+
+### 9. Integration test (`api-integration-test`)
+
+**When it fires**: "test integration", "smoke", or auto-triggered at the end of sprint-runner.
+
+**Input**: local backend + frontend deploy.
+
+**How it works**:
+- Boots backend (`./mvnw spring-boot:run` or via Docker Compose)
+- Boots frontend (`npm run dev` or via Docker Compose)
+- Runs critical flow via:
+  - `curl` to validate API (status, schema, headers)
+  - Chrome MCP to validate UI (navigation, console errors, form submit)
+
+**Output**: smoke report with real errors (not mocks).
+
+⏸️ **Checkpoint**: human reads the report.
+
+### 10. Final gate (`prd-ready-check`)
+
+**When it fires**: "PRD-ready?", "can we deploy?", "DoD". Terminal skill.
+
+**Input**: full project state.
+
+**How it works**: runs everything again (build, test, lint, E2E, security scan) + checks:
+- No `@Disabled` / `.skip()` in tests
+- No `// TODO` in production code
+- No hardcoded secrets
+- Coverage maintained above thresholds
+- ADRs referenced by the PLAN are accepted
+
+**Output**: GO or NO-GO. NO-GO includes exact list of what needs to be fixed.
+
+### 11. Final review (`tech-lead`)
+
+**When it fires**: after prd-ready-check GREEN.
+
+**Output**: approves merge OR returns with reason.
+
+⏸️ **Checkpoint**: human triggers the merge on GitHub/GitLab.
+
+### 12. History (`brain-keeper`)
+
+**When it fires**: at the end of the PLAN (or explicitly "record in the brain").
+
+**Input**: full state of the closed sprint.
+
+**Output**: updates `docs/brain/` (Obsidian vault):
+- `daily/YYYY-MM-DD.md` — daily log
+- `features/<slug>.md` — feature note
+- `decisions/<adr-id>.md` — link to accepted ADRs
+- `bugs/<slug>.md` — bugs found during the sprint
+- `tech-debt.md` — deferred items
+- `MOC.md` — updates the Map of Content with links
+
+On first run, it provisions `docs/brain/.obsidian/` with the per-folder color snippet.
+
+## Return loop
+
+When something fails, the pipeline returns — it does not end. Canonical returns:
+
+```
+gate-keeper FAIL              → back to responsible developer (with list of failures)
+code-reviewer with bugs       → back to developer
+api-integration-test FAIL     → back to `qa-engineer` to debug
+prd-ready-check NO-GO         → back to `gate-keeper` or specific specialist
+tech-lead returns in review   → back to developer
+ADR rejected                  → back to architect to re-propose
+```
+
+## Shortcuts
+
+The full pipeline is for new features. Shortcuts exist for other cases:
+
+### Trivial change (1 file, no new domain)
+
+- Skip discovery/PRD/issues/PLAN.
+- Edit directly via appropriate agent (`backend-developer`, `frontend-developer`).
+- `gate-keeper` still runs mandatorily.
+- `brain-keeper` records as a simple entry in the daily.
+
+### Hotfix in production
+
+```
+hotfix request → architect (quick proposal) → sprint-runner (1 task) → gate-keeper → tech-lead → merge → brain-keeper (bug entry)
+```
+
+- Skip `grill-me`/`to-prd`/`to-issues`.
+- ADR optional (only if a decision changed).
+- Git Flow: `hotfix/<slug>` based on `main`, merges to `main` AND `develop` (see [Git Flow](git-flow)).
+
+### Internal technical refactor (no behavior change)
+
+```
+tech-lead identifies → analyst (technical PLAN) → sprint-runner → gate-keeper → tech-lead → merge
+```
+
+- No PO, no `grill-me`/`to-prd`.
+- `qa-engineer` adds regression tests if they do not already exist.
+
+## Concrete example — "implement product signup"
+
+Follow the full pipeline on a realistic feature.
+
+**1. `grill-me`** — interview produces `DISCOVERY_product-signup.md`:
+```
+Persona: catalog manager
+Constraints: unique name per tenant, price >= 0, integer stock >= 0
+Hypotheses: batch signup (CSV) will come later (out of scope MVP)
+```
+
+**2. `to-prd`** — produces `PRD_product-signup.md`:
+```
+User story: as a manager, I want to register a product with name, price
+and stock, to make it available in the catalog.
+Functional req: POST /api/v1/products, validation, 201 return.
+Non-functional req: p95 latency < 300ms, creation audit log.
+Out of scope: batch signup.
+```
+
+**3. `to-issues`** — produces `ISSUES_product-signup.md` with 3 issues:
+- [ISSUE-1] Backend: POST endpoint + DTO + validation
+- [ISSUE-2] Backend: migration + repo + service
+- [ISSUE-3] Frontend: signup screen + form + integration
+
+**4. `analyst`** — produces `PLAN_product-signup.md` with 2 sprints:
+- Sprint 1: backend (T1: migration, T2: service, T3: controller, T4: tests)
+- Sprint 2: frontend (T1: component, T2: Angular service, T3: E2E)
+
+**5. `architect`** — does not fire (patterns already established).
+
+**6. `tech-lead`** — approves PLAN.
+
+**7. `sprint-runner` Sprint 1** — dispatches in parallel:
+- `qa-engineer` writes JUnit tests for Service + controller
+- `database-engineer` generates `V20260527_001__create_product.sql`
+- `backend-developer` implements Service + Controller + DTOs (record)
+
+After 30 min, `gate-keeper` runs:
+- JaCoCo lines: 87% ✓
+- JaCoCo branches: 82% ✓
+- PIT mutation: 73% ✓
+- SpotBugs: 0 issues ✓
+- OWASP DC: 0 CVE ✓
+
+**8. `code-reviewer`** suggests extracting unique-name validation to a domain service. `backend-developer` applies.
+
+**9. `tech-lead`** approves Sprint 1.
+
+**10. `sprint-runner` Sprint 2** — dispatches:
+- `qa-engineer` writes Playwright E2E + jest-axe component test
+- `ux-designer` produces wireframe + tokens
+- `frontend-developer` implements component (3 files: `.ts`, `.html`, `.scss`)
+
+`gate-keeper` runs:
+- Jest statements: 88% ✓
+- Jest branches: 84% ✓
+- jest-axe: 0 violations ✓
+- Playwright: 100% green ✓
+- Lighthouse perf: 0.84 ✓
+- LCP: 1820ms ✓, CLS: 0.04 ✓, TBT: 210ms ✓
+- E2E pyramid: 18% ✓
+
+**11. `api-integration-test`** boots local stack, validates POST + UI via Chrome MCP. Clean console.
+
+**12. `prd-ready-check`** returns GO.
+
+**13. `tech-lead`** approves merge. Human triggers merge on GitHub.
+
+**14. `brain-keeper`** updates `docs/brain/`:
+- `features/product-signup.md` — feature summary
+- `daily/2026-05-27.md` — daily entry
+- `MOC.md` — link to `product-signup` under Catalog
+
+Total: ~3-4 wall-clock hours, 0 human interruptions beyond the 4 checkpoints.
+
+## Cross-references
+
+- [Agents reference](agents-reference) — details of each agent invoked in the pipeline
+- [Skills reference](skills-reference) — exact triggers of each skill
+- [Quality gate](quality-gate) — thresholds enforced by `gate-keeper` and `prd-ready-check`
+- [Architecture overview](architecture-overview) — Skill + Agent macro model
+- [Autonomy matrix](autonomy-matrix) — who decides at each stage without the human
+- [Git Flow](git-flow) — branch model used at merge time
+- [Stack rules](stack-rules) — versions and conventions applied during execution
+- [Hooks reference](hooks-reference) — hooks that run along the pipeline