@guilhermefsousa/open-spec-kit 0.0.10 → 0.0.11

package/templates/github/skills/dev-orchestrator/SKILL.md

@@ -1,9 +1,623 @@
 ---
-name: dev-orchestrator
-description: "Orquestra implementacao: TDD a partir de scenarios.md, cria branches, MRs e atualiza docs vivas pos-merge."
+name: osk-build
+description: "Orchestrates feature implementation: reads approved spec, selects the right coding agent by stack, creates branches, runs TDD cycle, handles test failures, creates MRs, and updates living docs on Confluence post-merge."
+metadata:
+  works_on: [copilot, antigravity, claude]
+argument-hint: "[spec number, e.g. 001] or [spec number --post-merge]"
 ---
 
-# Dev Orchestrator (Copilot)
+# Dev Orchestrator
 
-> Source of truth: `.agents/skills/dev-orchestrator/SKILL.md`
-> Leia o SKILL.md completo em `.agents/skills/dev-orchestrator/` e siga todas as instrucoes de la.
+## Objective
+
+Take an approved spec and orchestrate its implementation end-to-end: select the right coding agent, create branches, implement with TDD, validate, create MRs, and update living documentation after merge.
+
+## Before you start
+
+### Validate prerequisites
+
+1. Check that `specs/NNN-name/` exists and contains all 5 files (brief.md, contracts.md, scenarios.md, tasks.md, links.md). If any file is missing: **stop** with message: "Spec incompleta. Execute /osk-spec antes de /osk-build."
+2. In Confluence (via MCP — same as /osk-init), check the feature page labels:
+   - If label `em-spec` is NOT present: **stop** — "Feature não passou pelo /osk-spec. Execute /osk-discover e /osk-spec antes de /osk-build."
+   - If label `prd-rejeitado` is present AND its addition date is MORE RECENT than `em-spec`: **stop** — "PRD foi rejeitado após a spec. Execute /osk-discover novamente para resolver." (Check via MCP — page metadata or label order.)
+   - Otherwise: proceed
+3. Check for concurrent execution: if there's an active branch `feat/NNN-*` in any repo, **WARN and PAUSE** — display message: "Branch ativa `feat/NNN-*` encontrada. Continuar mesmo assim? (pode causar conflitos)". Only proceed with explicit dev confirmation.
+
+### Read context
+
+Read these files FIRST:
+
+1. `projects.yml` — repos, stack, dependencies
+2. `docs/architecture.md` — system structure
+3. ALL files in `docs/lessons/` — past mistakes to avoid
+4. The approved spec in `specs/NNN-name/` (all 5 files)
+
+## Inputs
+
+- Approved spec number (e.g., `001`)
+- Spec files: `brief.md`, `contracts.md`, `scenarios.md`, `tasks.md`, `links.md`
+
+## Agent selection
+
+Read `projects.yml` → `agents` section to select agents dynamically.
+
+### Coding agents
+
+For each repo in tasks.md:
+1. Read the repo's `stack` from `projects.yml` repos[]
+2. Normalize the stack keyword to lowercase (e.g., ".NET" → "dotnet", "Node.js" → "nodejs")
+3. Look up in `projects.yml` → `agents.coding.{keyword}`
+4. If found: use that agent name
+5. If NOT found: **STOP** — "Stack '{stack}' sem agent configurado. Adicione o mapeamento em projects.yml → agents.coding."
+
+If multiple stacks (e.g., API in .NET, Front in React), use different agents per repo.
+
+### Support agents
+
+Read from `projects.yml` → `agents` section:
+
+| Role | Config key | If null or missing |
+|------|-----------|-------------------|
+| Security scan | `agents.security` | Skip scan, add note to MR: "Security scan manual necessário" |
+| Code review | `agents.code_review` | Skip pre-review, notify dev |
+| Design document | `agents.design_doc` | Update DD directly no Confluence (read → append → update) |
+
+**All agent names come from projects.yml. Skills NEVER hardcode agent names.**
+
+## Flow
+
+### Phase A — Preparation
+
+1. Read the full spec (contracts.md, scenarios.md, tasks.md)
+2. Read `specs/NNN-name/audit-report.md` — if it contains ⚠️ items, evaluate whether they block implementation. If it contains ❌ items, **stop**: "Spec não passou no audit. Execute /osk-spec novamente."
+3. Parse tasks.md to identify:
+   - Task groups per repo
+   - Dependencies between groups
+   - Parallelizable groups (marked `[P]`)
+   - Execution order
+4. **Check if repos exist** — for each repo referenced in tasks.md:
+   - Look up the repo in `projects.yml`
+   - If `status: active` and `url` is filled → repo exists, skip
+   - If `status: planned` and `url` is null → **create the repo** (see Phase A.1 below)
+   - If the repo is NOT declared in projects.yml → stop and ask the dev
+5. Create GitLab/GitHub Issues (1 per task) via API or terminal:
+   - Title: `[NNN] task description`
+   - Labels: `spec`, `NNN-feature-name`
+   - Assign to the repo's issue board
+
+### Phase A.1 — Auto-create repo (when needed)
+
+When a repo has `status: planned` in projects.yml:
+
+1. **Create the repo** on the VCS declared in `projects.yml` (`vcs` field):
+   - `github`: `gh repo create {vcs_org}/{repo-name} --private`
+   - `gitlab`: `glab project create {repo-name} --group {vcs_org}`
+   - If `vcs` field is missing in projects.yml: infer from existing repo URLs. If no repos exist yet, **stop** and ask the dev: "Qual VCS usar? Adicione `vcs: github` ou `vcs: gitlab` e `vcs_org: {org}` no projects.yml."
+2. **Clone locally** and initialize
+3. **Select the engineer agent** for the repo's stack (see Agent selection table)
+4. **Engineer agent scaffolds the project:**
+   - Project structure (folders, base files)
+   - CI/CD pipeline config (Dockerfile, docker-compose service, .gitlab-ci.yml or GitHub Actions)
+   - .gitignore, README.md
+   - Base dependencies (package.json, .csproj, pom.xml, etc.)
+   - Initial commit with scaffold
+5. **Push to remote**
+6. **Update projects.yml:**
+   - `url` → the new repo URL
+   - `status` → `active`
+7. **Commit projects.yml change** in the spec repo
+
+The scaffold should be minimal but functional — the engineer agent knows the stack conventions. No business logic at this point, just the skeleton.
+
+**Rollback on failure**: if any step of Phase A.1 fails AFTER the repo was created on the VCS, do NOT update projects.yml. Report to dev: "Repo '{name}' criado no VCS mas scaffold incompleto. Estado: {last_successful_step}. Resolução manual necessária."
+
+**docker-compose**: if the project uses Docker (check `projects.yml` stack), the scaffold MUST include:
+- `Dockerfile` for the component
+- Entry in the project's `docker-compose.yml` (if it exists) or creation of a new `docker-compose.yml` with the service + dependencies (PostgreSQL, RabbitMQ, etc.)
+
+### Phase B — Execution (per task, in dependency order)
+
+**Before starting execution**: change the feature label on Confluence → `em-dev`.
+
+**Dependency check**: before executing a task, verify that all tasks it depends on (from tasks.md dependency graph) are completed. If a dependency is `blocked`, mark the current task as `blocked-dependency` and skip it. Notify dev: "Task '{task}' bloqueada porque depende de '{blocked_task}' que está bloqueada."
+
+For each task (move GitLab Issue → `in-progress` when starting):
+
+B.1. Open/clone the correct repo (from projects.yml — now guaranteed to exist)
+B.2. Create branch: `feat/NNN-short-description`
+B.3. **Invoke the coding agent — RED phase (generate tests)**
+   - Invoke the coding agent for this repo's stack (see Agent selection table)
+   - Agent receives: `scenarios.md`, `contracts.md`, `tasks.md` (the specific task)
+   - Agent's goal: generate tests that translate EVERY CT-NNN-XX mapped to this task
+   - Each CT's Given/When/Then IS the test specification — the agent translates to the stack's test framework
+   - Tests MUST be a **faithful translation** — do NOT invent tests not in scenarios.md, do NOT skip scenarios
+   - Tests MUST fail initially (red phase) — if they pass before implementation, the test is wrong
+   - **Why test-first matters with AI agents**: without a failing test as objective criteria, the agent declares "done" without proof. The test is the contract between the spec and the code. (ref: arXiv 2402.13521, DORA 2025, TDAD arXiv 2603.17973)
+
+B.3.5. **Commit tests (RED) — MANDATORY before starting implementation**
+   After generating ALL tests, commit immediately — before any implementation code:
+   ```bash
+   git add -A
+   git commit -m "test(NNN): failing tests for {task-short-name} [RED]"
+   ```
+   This ensures tests are not lost if execution is interrupted. Without this commit, an interruption loses all RED phase work.
+
+B.4. **Orchestrator validates RED phase**
+   - Count CTs in scenarios.md that map to this task → count tests generated
+   - If count(CTs) != count(tests): list missing CTs and ask the coding agent to add them
+   - Run tests → confirm ALL fail (red). If any passes, flag it — the test may be testing nothing
+
+B.5. **Invoke the coding agent — GREEN phase (implement code)**
+   - Same coding agent, same context, PLUS the failing tests from B.3
+   - Agent's goal: implement the code to make ALL tests pass
+   - Agent MUST NOT modify the tests — only the implementation code
+   - If a test is wrong (contradicts contracts.md), the orchestrator fixes the test and re-runs — never the coding agent
+   - `docs/lessons/` provided as context — mistakes to avoid
+
+B.5.5. **Commit implementation (GREEN) — MANDATORY after all tests pass**
+   After ALL tests pass, commit immediately:
+   ```bash
+   git add -A
+   git commit -m "feat(NNN): implement {task-short-name} — all tests pass [GREEN]"
+   ```
+
+### Phase C — Validation
+
+C.1. Run tests
+C.2. **If tests fail:**
+    - Read the error output
+    - Attempt to fix (max 3 retries)
+    - If fixed → continue
+    - If not fixed after 3 retries:
+      - Move VCS Issue → `blocked`
+      - **Preservar trabalho antes de notificar**:
+        ```bash
+        git add -A
+        git commit -m "wip(NNN): blocked after 3 retries — {error-summary}"
+        ```
+      - Notify Google Chat:
+        ```bash
+        ./scripts/notify-gchat.sh --card \
+          --title "🚫 Task bloqueada" \
+          --subtitle "{project_name} — {feature_name}" \
+          --body "Task '{task_description}' falhou após 3 tentativas. Erro: {error_summary}. Salvo em docs/lessons/." \
+          --button-text "Ver Issue" \
+          --button-url "{vcs_issue_url}"
+        ```
+      - Save failure context to `docs/lessons/` for future reference
+      - SKIP to next task
+      - **Unblocking**: to resume a blocked task, the dev re-runs `/osk-build NNN`. The agent detects tasks with `blocked` status, displays the saved context from `docs/lessons/`, and asks the dev whether to retry. If the dev confirms, the 3-retry counter resets. If the same task blocks again after another 3 retries, escalate to TL via GChat and mark the task as `blocked-permanent`. Do NOT auto-retry without dev confirmation — this prevents infinite loops.
+
+C.3. **Conformance check** (inspired by OpenSpec's `/opsx:verify`)
+
+After tests pass, verify that the implementation faithfully reflects contracts.md. The orchestrator reads contracts.md and delegates verification to the coding agent for the repo's stack.
+
+**Dimension 1 — Completeness (endpoints)**:
+The orchestrator extracts the endpoint table from contracts.md (Method + Route columns) and asks the coding agent:
+> "List all registered routes in this application (HTTP method + path). Compare against this endpoint table from contracts.md. Report: endpoints in the spec but missing in code, and endpoints in code not in the spec."
+
+**Dimension 2 — Correctness (paths and response fields)**:
+The orchestrator extracts response type field names from contracts.md and asks the coding agent:
+> "For each endpoint, verify that the response object returned has EXACTLY the same field names as defined in contracts.md. Report missing, renamed, or extra fields."
+
+**Conformance report** — the coding agent returns:
+
+```
+## Conformance Report
+
+### Endpoints
+| Spec (contracts.md) | Code | Status |
+|---------------------|------|--------|
+| POST /api/auth/cadastro | POST /api/auth/cadastro | ✅ MATCH |
+| GET /api/listas | GET /api/listas | ✅ MATCH |
+| PUT /api/listas/{id} | — | ❌ MISSING |
+
+### Response Fields
+| Endpoint | Type (contracts.md) | Field | Status |
+|----------|---------------------|-------|--------|
+| GET /api/listas | PaginatedResponse | itens | ❌ implemented as "dados" |
+| POST /api/auth/cadastro | CadastroResponse | id, nome, email | ✅ MATCH |
+```
+
+**Action on divergences:**
+- ❌ MISSING endpoint → coding agent implements the missing endpoint
+- ❌ Different path → coding agent fixes the route in code (NOT in spec — spec is source of truth pre-merge)
+- ❌ Renamed field → coding agent fixes the field name in code to match contracts.md
+- After fixes → re-run tests (should still pass since tests were generated from the same spec)
+- If divergence was INTENTIONAL (spec was wrong, dev corrected during implementation) → update contracts.md and record the change in `docs/lessons/`
+
+> **Rule**: contracts.md is the source of truth PRE-implementation. Code is the source of truth POST-merge. The conformance check ensures alignment before the merge. To diverge intentionally, update the spec first.
+
+**Conformance report artifact**: after running the conformance check, save the report to `specs/NNN-name/conformance-report.json` in the spec repo with this schema:
+
+```json
+{
+  "feature": "NNN",
+  "timestamp": "2026-04-11T12:00:00Z",
+  "endpoints": {
+    "total": 4,
+    "matching": 4,
+    "missing": 0,
+    "divergent": 0,
+    "details": [
+      { "spec": "POST /api/listas", "code": "POST /api/listas", "status": "match" },
+      { "spec": "GET /api/listas", "code": "GET /api/listas", "status": "match" }
+    ]
+  },
+  "fields": {
+    "total": 12,
+    "matching": 12,
+    "divergent": 0,
+    "details": []
+  },
+  "result": "pass"
+}
+```
+
+This artifact enables CI Guard (see below) and provides audit trail for compliance.
+
+Also append a summary line to `specs/NNN-name/conformance-history.log` (create if it doesn't exist):
+```
+{timestamp} | {result} | {matching}/{total} endpoints | {matching}/{total} fields
+```
+This preserves history across multiple /osk-build runs.
+
+C.4. **Run extension hooks** (if any)
+
+If the spec repo has a `hooks/pre-merge/` directory with executable scripts, run each one in alphabetical order. Each script receives two arguments: `<spec-dir>` and `<repo-dir>`.
+
+- Exit 0 → hook passes, continue
+- Exit non-zero → hook fails, treat as blocked (same flow as test failure: log, retry, skip)
+
+This is the extension point for teams to add custom validations without modifying the SKILL. Examples:
+- Accessibility check on frontend
+- Performance budget validation
+- License compliance scan
+- Custom lint rules
+
+If `hooks/pre-merge/` doesn't exist or is empty, skip this step.
+
+C.5. **Run security scan** — read `projects.yml` → `agents.security`. If configured (not null), invoke that agent:
+    - Check for hardcoded secrets
+    - Check for injection vulnerabilities
+    - Check for unsafe dependencies
+    - If `agents.security` is null or missing: skip scan, add note to MR description: "⚠️ Security scan manual necessário — agent não configurado"
+C.6. **If tests pass + conformance OK + hooks OK + security OK:**
+    - Create MR via VCS API or terminal
+    - MR description references: spec number, task, REQ-NNN
+    - Move VCS Issue → `em-review`
+    - Read `projects.yml` → `agents.code_review`. If configured (not null), invoke that agent for automated pre-review. If null: skip pre-review, notify dev: "Code review automatizado indisponível — review manual necessário"
+C.7. Notify Google Chat (rich card format):
+    ```bash
+    ./scripts/notify-gchat.sh --card \
+      --title "🔀 MR criado" \
+      --subtitle "{project_name} — {feature_name}" \
+      --body "{body_text}" \
+      --next "{next_step}" \
+      --button-text "Revisar MR" \
+      --button-url "{mr_url}"
+    ```
+    **Body format** — use `<b>` for bold, `<br>` for line breaks, `•` for bullets:
+    ```
+    <b>{feature_name} — tasks implementadas:</b><br>• T-NNN-REPO-XX — descrição<br>• T-NNN-REPO-YY — descrição<br><br>🧪 <b>Total:</b> X testes passando | Y branches prontas pra review
+    ```
+
+### Phase C (branch) — MR rejected (if code review finds issues)
+
+If the code reviewer (human or agent) rejects the MR:
+
+1. Read the review feedback (comments, requested changes)
+2. Fix the issues in the same branch
+3. Re-run tests to ensure fixes don't break anything
+4. Re-run conformance check (C.3) if routes or response fields changed
+5. Push the fixes and update the MR
+6. Re-invoke the code review agent (from `projects.yml` → `agents.code_review`) for new review
+7. Repeat until approved — sem limite de correções
+
+### Phase D — Post-merge (after human CR approves)
+
+**How to trigger Phase D**: the dev re-executes `/osk-build NNN` after merging the MR. The agent detects merged MRs by checking links.md (MRs without "merged" status) or by querying the VCS API. Alternatively, the dev can run `/osk-build NNN --post-merge` to explicitly trigger Phase D.
+
+After the dev merges the MR:
+
+D.1. Update `specs/NNN-name/links.md` with merged MR link
+
+D.1.5. **Sync spec with implementation reality**
+If the conformance report (Phase C.3) detected INTENTIONAL divergences (spec was wrong, implementation corrected it), update the LOCAL spec files to match what was actually implemented:
+- `contracts.md`: fix endpoint paths, response fields, or types that diverged
+- `scenarios.md`: update Given/When/Then if behavior changed
+- Commit: `fix(NNN): sync spec with implementation — {summary of changes}`
+
+This ensures specs remain the source of truth for FUTURE features that reference them. Without this update, /osk-discover and /osk-spec for next features read stale contracts.
+
+If conformance report shows NO divergences → skip (specs already match).
+
+D.2. Move VCS Issue → `done`
+D.3. **Update living docs on Confluence** (via MCP):
+
+> **Ownership rule**: /osk-build is the LAST to touch living docs. Its updates reflect what WAS IMPLEMENTED (merged code), not what was planned in the spec. If the implemented behavior diverged from the spec (e.g., rule adjusted during dev), Confluence must reflect the REALITY of the code, not the original spec. Code is the source of truth post-merge.
+
+| Document | What to update | When |
+|----------|---------------|------|
+| DD (Design Document) | New components, flows, contracts | If feature changes architecture |
+| Dominio/Regras | New business rules implemented | If new rules were added |
+| Dominio/Fluxos | New or changed flows | If flows changed |
+| Dominio/Integracoes | New external integrations | If new integrations |
+| Glossario | New technical terms | If new domain concepts |
+| Feature page label | adicionar `done` | Always |
+
+**Note on labels**: the Confluence API only supports ADDING labels (not removing). Previous labels (discovery, aguardando-po, prd-review, etc.) accumulate as history. The CURRENT workflow label is always the most recently added one. To filter features by state, look for the most recent label.
+
+**Confluence unavailable fallback**: if Confluence access (MCP or REST API) is down during post-merge:
+- Save pending updates to `docs/pending-confluence-updates.md` with: target page, content to add, date
+- Notify the dev with message: "Confluence indisponível — atualizações salvas em docs/pending-confluence-updates.md. Execute manualmente quando o Confluence voltar."
+- On the next /osk-build execution, check if `docs/pending-confluence-updates.md` exists and attempt to apply pending updates
+
+D.4. **Post-implementation discoveries:**
+
+If implementation revealed:
+- a) A SURPRISE (unexpected behavior, edge case) → save to `docs/lessons/NNN-title.md` with template below
+- b) A NEW ARCHITECTURE DECISION (chose a pattern, discovered a constraint) → add to `docs/architecture.md` "Decisões em Aberto" table with Status: `resolvida — [decisão tomada durante implementação de {SIGLA}-NNN]`. This ensures architecture.md reflects decisions made during /osk-build, not just during /osk-discover.
+
+Lessons template:
+    ```
+    ## O que aconteceu
+    [description]
+    ## Causa raiz
+    [why it happened]
+    ## Como evitar
+    [what to do differently next time]
+    ```
+D.4.5. **Update CHANGELOG.md**
+
+In the MAIN repo (first repo in projects.yml), create or update `CHANGELOG.md` with an entry for this feature:
+
+```markdown
+## [{SIGLA}-NNN] Feature Name — YYYY-MM-DD
+
+### Adicionado
+- {list new endpoints from conformance report}
+- {list new entities from contracts.md}
+
+### Alterado
+- {list modified entities/endpoints, if evolution feature}
+
+### Observações
+- {any "A CONFIRMAR" items still pending}
+```
+
+If `CHANGELOG.md` doesn't exist, create it with header: `# Changelog` and a reference to [Keep a Changelog](https://keepachangelog.com/).
+
+D.5. Notify Google Chat (rich card format):
+    ```bash
+    ./scripts/notify-gchat.sh --card \
+      --title "🚀 Feature NNN implementada" \
+      --subtitle "{project_name}" \
+      --body "{body_text}" \
+      --next "{next_step}" \
+      --button-text "Ver {repo_name}" \
+      --button-url "{repo_url}"
+    ```
+    **Body format** — list ALL tasks from tasks.md with bullet points:
+    ```
+    <b>{feature_name} — todas as tasks:</b><br>• T-NNN-API-01 — descrição<br>• T-NNN-API-02 — descrição<br>• T-NNN-FRONT-01 — descrição<br>...<br><br>🧪 <b>Total:</b> X testes API passando | Y testes front passando
+    ```
+    **Rules for rich notifications:**
+    - List every task from tasks.md (API + Front + Worker)
+    - Include test count per repo
+    - `--next` must always state the concrete next step
+    - `--button-text` + `--button-url` link to the main repo or feature page
+    - All text in pt-BR with correct accents
+
+  Replace `{}` values with actual data from execution context. Notifications always in pt-BR.
+
+### Phase E — Infrastructure validation (optional, recommended before release)
+
+**How to trigger Phase E**: dev runs `/osk-build --validate`, or automatically after the last feature of the cycle. Not executed per feature — only when the dev wants to validate the complete system against real infrastructure.
+
+**Prerequisite**: the project has a `docker-compose.yml` (or equivalent infra) declared in `projects.yml`. If not, skip this phase.
+
+E.1. Start infrastructure via `docker-compose up -d` (database, messaging, etc.)
+   - If ports conflict, adjust in docker-compose and connection strings
+   - Wait for health checks to pass
+
+E.2. For EACH repo, invoke the stack's coding agent to:
+   - Apply pending schema/migrations (the agent knows the stack command)
+   - Start the service locally
+   - The orchestrator does NOT execute stack commands directly — delegates to the agent
+
+E.3. Validate the API (orchestrator does via curl):
+   - Health check (`GET /health` → 200)
+   - Minimum flow: register → login → 1 authenticated CRUD operation
+   - Verify CORS (front origin must be accepted)
+   - If the spec has NFR scenarios (performance targets): run a basic load smoke test against the critical endpoint (e.g., `hey -n 100 -c 10 {url}` or equivalent) and verify the p95 response time meets the target. If load testing tooling is not available, log: "NFR validation manual necessária — tooling de load test não disponível."
+
+E.4. Validate the frontend (orchestrator checks):
+   - Build passes (stack agent executes the build)
+   - `baseURL` points to the correct API port
+   - Login screen loads and can authenticate
+
+E.5. If any step fails:
+   - Log in `docs/lessons/` with root cause and applied fix
+   - Fix and retry the validation
+   - Notify dev via GChat if the issue requires manual decision
+
+E.6. Tear down infrastructure: `docker-compose down`
+
+E.7. Notify Google Chat (rich card format):
+    ```bash
+    ./scripts/notify-gchat.sh --card \
+      --title "✅ Validação de infraestrutura OK" \
+      --subtitle "{project_name}" \
+      --body "<b>Smoke test passou:</b><br>• Infra: PostgreSQL + RabbitMQ<br>• Migrações aplicadas<br>• Health check OK<br>• Fluxo cadastro → login → CRUD OK<br>• CORS OK<br>• Front build + conexão OK" \
+      --next "Pronto para deploy" \
+      --button-text "Ver projeto" \
+      --button-url "{repo_url}"
+    ```
+
+## Agents used
+
+All agent names are read from `projects.yml` → `agents` section. **Never hardcode agent names.**
+
+| Role | Config key | When | Purpose |
+|------|-----------|------|---------|
+| Coding agent | `agents.coding.{stack}` | Phase B | Code implementation (selected by repo stack) |
+| Security scan | `agents.security` | Phase C.5 | Security scan before MR |
+| Code review | `agents.code_review` | Phase C.6 | Automated pre-review of MR |
+| Design document | `agents.design_doc` | Phase D | Update DD if architecture changed |
+
+**Fallbacks (when agent config is null or agent unavailable):**
+- **Coding agent** not configured for stack: **STOP** — "Stack '{stack}' sem agent configurado. Adicione o mapeamento em projects.yml → agents.coding."
+- **Security**: skip scan, add note to MR: "⚠️ Security scan manual necessário"
+- **Code review**: skip pre-review, notify dev: "Code review automatizado indisponível — review manual necessário"
+- **Design doc**: update DD directly no Confluence (read storage → append → update)
+
+## CI Guard (optional — for teams with CI/CD pipelines)
+
+The conformance report generated in Phase C.3 (`specs/NNN-name/conformance-report.json`) enables automated spec compliance gates in CI/CD pipelines.
+
+### How to set up
+
+Add a step to your CI pipeline (GitHub Actions, GitLab CI, etc.) that reads the conformance report and blocks the merge if there are failures:
+
+```yaml
+# GitHub Actions example
+- name: Spec Conformance Guard
+  run: |
+    REPORT=$(cat specs/*/conformance-report.json 2>/dev/null | jq -s '.')
+    FAILURES=$(echo "$REPORT" | jq '[.[] | select(.result != "pass")] | length')
+    if [ "$FAILURES" -gt 0 ]; then
+      echo "❌ Spec conformance failed — $FAILURES feature(s) with divergences"
+      echo "$REPORT" | jq '.[] | select(.result != "pass") | {feature, endpoints: .endpoints.divergent, fields: .fields.divergent}'
+      exit 1
+    fi
+    echo "✅ All features conform to specs"
+```
+
+### What it blocks
+
+- ❌ Endpoints in contracts.md not implemented in code
+- ❌ Endpoint paths that don't match contracts.md exactly
+- ❌ Response field names that diverge from contracts.md types
+- ❌ Extension hooks (pre-merge) that failed
+
+### What it doesn't block
+
+- Spec updates (contracts.md changes) — those are intentional evolution
+- Test count mismatches — caught earlier in Phase B.4, not in CI
+- Security scan — separate CI step
+
+### When to adopt
+
+- **Now**: run conformance check manually during /osk-build (Phase C.3) — already implemented
+- **Next**: add CI Guard when the team sets up CI/CD pipelines
+- **Future**: add custom hooks for domain-specific validations
+
+## Extension System
+
+The kit is extensible via three mechanisms. Teams add custom behavior without modifying the core SKILLs.
+
+### 1. Agents (stack support)
+
+To add support for a new programming language or framework:
+
+1. Create an agent definition in `padrao-labs-agents/.agents/agents/{name}.agent.md`
+2. Add the stack → agent mapping in `projects.yml` → `agents.coding` (e.g., `go: my-go-engineer`)
+3. The /osk-build automatically selects the new agent when a repo in `projects.yml` declares that stack
+
+### 2. Rules (cross-cutting concerns)
+
+To add rules that apply across all skills:
+
+1. Create a `.md` file in `.agents/rules/` with frontmatter: `name`, `description`, `applyTo`
+2. All skills and agents that match `applyTo` will receive the rule as context
+3. Examples: coding standards, security policies, naming conventions
+
+### 3. Hooks (custom validations)
+
+To add custom validation steps to the /osk-build pipeline:
+
+1. Create a `hooks/` directory in the spec repo
+2. Add executable scripts to `hooks/pre-merge/` — they run in Phase C.4 before MR creation
+3. Each script receives: `$1` = spec directory path, `$2` = code repo path
+4. Exit 0 = pass, non-zero = fail (blocks the merge)
+
+**Hook examples:**
+
+```bash
+# hooks/pre-merge/check-accessibility.sh
+# Runs axe-core on the frontend build
+cd "$2" && npx axe-core --exit-code build/
+
+# hooks/pre-merge/check-license.sh  
+# Validates no GPL dependencies in a commercial project
+cd "$2" && npx license-checker --failOn "GPL"
+
+# hooks/pre-merge/check-bundle-size.sh
+# Blocks merge if frontend bundle exceeds 500KB
+BUNDLE_SIZE=$(du -sk "$2/dist/assets/" | cut -f1)
+[ "$BUNDLE_SIZE" -lt 500 ] || (echo "Bundle too large: ${BUNDLE_SIZE}KB" && exit 1)
+```
+
+**Hook lifecycle:**
+- `hooks/pre-merge/` — runs in Phase C.4, after conformance check, before security scan
+- Future: `hooks/post-merge/`, `hooks/pre-spec/`, `hooks/post-setup/` as needed
+
+## Rules
+
+1. ALWAYS generate tests before implementation (TDD) — tests MUST come from scenarios.md, not invented by the agent
+2. Max 3 retries on test failure — then mark as blocked and move on. **1 retry = 1 complete cycle of: read error → modify code → re-run tests.** Each cycle counts regardless of change size.
+3. Each task = 1 branch = 1 MR (never bundle)
+4. MR description must reference spec number and REQ-NNN
+5. Security scan is mandatory before creating MR
+6. Living docs on Confluence MUST be updated post-merge
+7. Lessons learned from failures MUST be saved to docs/lessons/
+8. All VCS Issues (GitLab/GitHub) must reflect current state (open → in-progress → em-review → done | blocked)
+9. **Language**: ALL generated content — Confluence pages AND local files — MUST be in **Brazilian Portuguese (pt-BR) with correct accents** (e.g., "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo"). Technical terms stay in English (e.g., endpoint, status, token). **When invoking coding agents**, pass this language rule explicitly — code comments MUST also use pt-BR with accents (e.g., `// Validação padrão` NOT `// Validacao padrao`).
+10. **Cross-platform scripts**: when running `./scripts/notify-gchat.*`, detect the OS. On Windows use `powershell -ExecutionPolicy Bypass -File ./scripts/notify-gchat.ps1`, on Linux/macOS use `bash ./scripts/notify-gchat.sh`. Parameters are the same for both.
+
+## Validation checklist
+
+- [ ] Audit-report.md read and evaluated (no ❌ items)
+- [ ] Repos auto-created if `status: planned` (Phase A.1)
+- [ ] Feature label changed to `em-dev` on Confluence
+- [ ] Correct coding agent selected per stack
+- [ ] VCS Issues created (1 per task)
+- [ ] Tests generated before implementation (TDD)
+- [ ] **Commit RED** (`test(NNN): failing tests [RED]`) done before starting GREEN
+- [ ] All tests pass
+- [ ] **Commit GREEN** (`feat(NNN): all tests pass [GREEN]`) done after all tests pass
+- [ ] Conformance check passed (endpoints + response fields match contracts.md)
+- [ ] Conformance report saved (`specs/NNN/conformance-report.json`) + history appended to `conformance-history.log`
+- [ ] Extension hooks passed (if any in `hooks/pre-merge/`)
+- [ ] Security scan passed
+- [ ] MR created with spec references
+- [ ] Pre-review by code-reviewer completed
+- [ ] MR rejected loop handled (if applicable — fix, re-test, re-check conformance)
+- [ ] links.md updated with MR links
+- [ ] Living docs updated on Confluence (DD, Dominio, Glossario)
+- [ ] Spec synced with implementation if intentional divergences (Phase D.1.5)
+- [ ] Architecture.md updated with new decisions if discovered during implementation (Phase D.4)
+- [ ] CHANGELOG.md updated in main repo (Phase D.4.5)
+- [ ] Feature label → `done` on Confluence
+- [ ] Lessons saved if applicable
+- [ ] GChat notifications sent at each transition
+- [ ] Phase E (infra validation) executed before release (if applicable)
+
+## Recovery after interruption
+
+If the agent was interrupted at any phase, on resume execute:
+
+```bash
+git status          # identify uncommitted files
+git log --oneline   # see where it stopped
+```
+
+| Detected state | Action |
+|----------------|--------|
+| Tests created, not committed | `git add -A && git commit -m "test(NNN): [RED] resumed"` → continue to B.5 |
+| Tests committed, partial implementation | `git add -A && git commit -m "wip(NNN): partial impl"` → continue GREEN |
+| Tests and impl committed, no PR | Create PR directly → Phase D |
+| Branch already exists with commits | Continue on it — do NOT create a new branch |
+
+**General rule**: never lose existing commits. Always `git status` before any decision.