atlas-workflow 0.9.2 → 0.9.4

package/hosts/zcode/skills/atlas-plan-execute/references/plan-contract.md

@@ -0,0 +1,88 @@
+# Plan Contract
+
+Input plans must follow `atlas-plan-handoff` and align with `PLAN_TEMPLATE.md` / `BOUNDARY_PRD_PLAN.md` (compact template, sections 1–8). Locate both in the Atlas Workflow plugin bundle at `packages/templates/`; do not use workspace-local templates as primary sources.
+
+If `packages/templates/PLAN_TEMPLATE.md` or `packages/templates/BOUNDARY_PRD_PLAN.md` is absent from the bundle, stop with a clear `Template canônico ausente: <nome-do-template>` error. Do not fall back silently to old local, vault, or global copies.
+
+Legacy 15-section plans (handoff prompt, architecture impact block in PRD, etc.) are **not** the target format.
+
+## Required execution metadata
+
+Near the top of the artifact:
+
+- `Plan prefix: atlas`
+- `Execution mode: sequencial (T01→TN)` | `orchestrated-per-slice`
+- `Executor skill: atlas-plan-execute`
+- `Internal validator: atlas-task-validator`
+- `External review: atlas-slice-review` (optional)
+
+## Required plan sections (match by meaning)
+
+| § | Purpose |
+|---|---------|
+| 1 | Executive translation (`Tradução executiva`) — scope link to PRD, reference module, diffs vs mirror |
+| 2 | Execution invariants (derived from `PRD §3` — cite D* IDs, do not paste full table) |
+| 3 | Pitfalls (anti-pattern → fix) |
+| 4 | State at sprint opening (3–6 bullets; not a global file inventory) |
+| 5 | Execution tasks `#### T01.` … `TNN` |
+| 6 | Technical contracts (only where PRD → code is ambiguous) |
+| 8 | Validation and validator checklist (derived from `PRD §6` + §2 invariants) |
+
+Section 7 (Slices) is required only when `execution_mode: orchestrated-per-slice`.
+
+**Not required:** handoff prompt, planner readiness gate, full `project-rules` rules dump, full PRD scope copy, global touched-files inventory.
+
+**Optional:** section 9 open questions / real blockers (executor must stop if active blockers remain).
+
+## Minimum task shape (section 5)
+
+Each `#### TNN.` should include when applicable:
+
+- `Objetivo` / `Objective`
+- `Referência` (module or pattern — not a long path laundry list)
+- `Pré-condições` / `Preconditions`
+- `Mudança esperada` / `Expected change`
+- `Invariantes preservados`
+- `Não mudar` / `Não fazer` / `Do not do`
+- `Dependências` / `Dependencies`
+- `Riscos` (if not obvious)
+- `Critério de done` / `Done criteria`
+- `Validação local` / `Task-local validation` (command with package path)
+- `Quality gates` (optional on critical tasks)
+- `Casos mínimos` (test tasks only)
+
+Paths may appear in **Referência** or **Validação local**; prefer module-level pointers per boundary policy.
+
+## Executor consumption map
+
+| Contract need | Plan section |
+|---------------|--------------|
+| Translation, PRD links, reference module | §1 |
+| Execution invariants | §2 |
+| Pitfalls | §3 |
+| Current codebase state | §4 |
+| Tasks, done criteria, local validation | §5 |
+| Technical contracts | §6 |
+| Slice boundaries | §7 (orchestrated mode) |
+| Validator checklist | §8 |
+| Business acceptance (when §8 is thin) | PRD §4–6 (read PRD path from plan header) |
+
+## Why this matters
+
+Prefix and mode are part of the execution contract, not chat memory.
+
+If `Plan prefix` or `Execution mode` is missing, stop — do not guess the chain.
+
+Thin tasks (`refactor bootstrap` only) are not ready for gated execution; ask for a denser plan.
+
+Pitfalls, contracts, and invariants are binding — not commentary.
+
+## Parsing notes
+
+The bundled `extract_plan_contract.py` uses heading heuristics:
+
+- `#` … `####` headings
+- task headings `#### T01. …`
+- bullet lines `- …`
+
+Normalize non-standard plans before execution or extend the parser aliases.

package/hosts/zcode/skills/atlas-plan-execute/references/quality-gates.md

@@ -0,0 +1,60 @@
+# Quality Gates
+
+Choose the lightest gate that still protects the current task.
+
+## Gate selection order
+
+1. Prove the task with deterministic checks.
+2. Add semantic review against plan invariants.
+3. Add targeted runtime verification only when behavior changed in a way static checks cannot prove.
+4. Escalate to broader validation only when the task blast radius justifies it.
+
+## Common gate matrix
+
+### Pure refactor
+
+- targeted tests for touched modules
+- typecheck or analyze for touched package
+- diff scan for forbidden scope expansion
+
+### Contract or DTO change
+
+- compilation or typecheck
+- serialization or mapper tests if available
+- search for all consumers of renamed or reshaped fields
+- compare with plan constraints and declared contract
+- verify generated artifacts or localization files named by the plan before wiring consumers
+
+### UI-only change
+
+- component, widget, or snapshot tests when available
+- targeted runtime verification for changed flow
+- search for accessibility or localization regressions if the repo has such rules
+- verify role/permission gating when the plan distinguishes who can see or mutate related resources
+
+### State management or orchestration change
+
+- focused tests around the changed store, controller, or service
+- validation of loading, error, and success transitions
+- explicit invariant review so closed architectural decisions are not violated
+- rapid repeat-action or stale async check when the slice changes user-triggered operations
+
+### Data migration or cleanup
+
+- migration-specific validation
+- idempotency or rollback reasoning
+- stronger stop conditions if external systems are involved
+
+## What not to do
+
+- Do not run every available check after every edit.
+- Do not promote unrelated warnings into mandatory work.
+- Do not claim semantic safety from lint alone.
+- Do not keep retrying the same failing check with no code or environment change.
+- Do not repair by weakening a permission matrix, source-of-truth decision, or explicit negative scope.
+
+## Failure classification
+
+- `pass`: checks passed and no unresolved high-severity invariant break remains
+- `fixable`: a current-diff issue is clear and repair budget remains
+- `blocked`: repair would require scope change, external dependency, environment fix, or repeated speculative retries

package/hosts/zcode/skills/atlas-plan-execute/scripts/check_budget_state.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Track bounded repair attempts for a gated execution task."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class BudgetState:
+    task_id: str
+    max_attempts: int = 2
+    max_same_failure: int = 2
+    attempts: int = 0
+    same_failure_count: int = 0
+    last_failure_key: str = ""
+    blocked: bool = False
+
+
+def load_state(path: pathlib.Path) -> BudgetState:
+    if not path.exists():
+        raise FileNotFoundError(f"State file not found: {path}")
+    return BudgetState(**json.loads(path.read_text(encoding="utf-8")))
+
+
+def save_state(path: pathlib.Path, state: BudgetState) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(state), indent=2) + "\n", encoding="utf-8")
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    state = BudgetState(
+        task_id=args.task_id,
+        max_attempts=args.max_attempts,
+        max_same_failure=args.max_same_failure,
+    )
+    save_state(pathlib.Path(args.state_file), state)
+    print(json.dumps(asdict(state), indent=2))
+    return 0
+
+
+def cmd_record(args: argparse.Namespace) -> int:
+    path = pathlib.Path(args.state_file)
+    state = load_state(path)
+    state.attempts += 1
+
+    if args.failure_key:
+        if args.failure_key == state.last_failure_key:
+            state.same_failure_count += 1
+        else:
+            state.last_failure_key = args.failure_key
+            state.same_failure_count = 1
+
+    if state.attempts >= state.max_attempts or state.same_failure_count >= state.max_same_failure:
+        state.blocked = True
+
+    save_state(path, state)
+    print(json.dumps(asdict(state), indent=2))
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    state = load_state(pathlib.Path(args.state_file))
+    print(json.dumps(asdict(state), indent=2))
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init")
+    init_parser.add_argument("state_file")
+    init_parser.add_argument("task_id")
+    init_parser.add_argument("--max-attempts", type=int, default=2)
+    init_parser.add_argument("--max-same-failure", type=int, default=2)
+    init_parser.set_defaults(func=cmd_init)
+
+    record_parser = subparsers.add_parser("record")
+    record_parser.add_argument("state_file")
+    record_parser.add_argument("--failure-key", default="")
+    record_parser.set_defaults(func=cmd_record)
+
+    status_parser = subparsers.add_parser("status")
+    status_parser.add_argument("state_file")
+    status_parser.set_defaults(func=cmd_status)
+
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/zcode/skills/atlas-plan-execute/scripts/extract_plan_contract.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Extract execution-relevant sections from a atlas-plan-handoff markdown artifact."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import re
+import sys
+from typing import Any
+
+HEADING_RE = re.compile(r"^(#{1,4})\s+(.*\S)\s*$")
+TASK_RE = re.compile(r"^T\d{2}\.\s+")
+
+
+def normalize_heading(text: str) -> str:
+    text = re.sub(r"^\d+\.\s*", "", text.strip())
+    text = re.sub(r"\(§\d+\)", "", text, flags=re.IGNORECASE)
+    return re.sub(r"[^a-z0-9]+", "_", text.lower()).strip("_")
+
+
+def has_any(summary: dict[str, list[str]], keys: list[str]) -> bool:
+    return any(key in summary for key in keys)
+
+
+def first_section(summary: dict[str, list[str]], keys: list[str]) -> list[str]:
+    for key in keys:
+        if key in summary:
+            return summary[key]
+    return []
+
+
+def parse_plan(text: str) -> dict[str, Any]:
+    sections: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        match = HEADING_RE.match(line)
+        if match:
+            level = len(match.group(1))
+            title = match.group(2).strip()
+            current = {
+                "level": level,
+                "title": title,
+                "key": normalize_heading(title),
+                "lines": [],
+            }
+            sections.append(current)
+            continue
+        if current is not None:
+            current["lines"].append(line)
+
+    tasks = []
+    for section in sections:
+        if section["level"] == 4 and TASK_RE.match(section["title"]):
+            tasks.append(
+                {
+                    "id": section["title"].split(".", 1)[0],
+                    "title": section["title"],
+                    "body": [line for line in section["lines"] if line.strip()],
+                }
+            )
+
+    summary = {section["key"]: [line for line in section["lines"] if line.strip()] for section in sections}
+    metadata = {
+        "plan_prefix": "",
+        "execution_mode": "",
+        "executor_skill": "",
+        "internal_validator": "",
+        "external_review": "",
+    }
+
+    metadata_section = first_section(
+        summary,
+        ["execution_metadata", "metadados_de_execu_o", "metadados_execu_o"],
+    )
+    for line in metadata_section:
+        lowered = line.lower()
+        if "plan prefix" in lowered:
+            metadata["plan_prefix"] = line.split(":", 1)[-1].strip().strip("`")
+        elif "execution mode" in lowered:
+            metadata["execution_mode"] = line.split(":", 1)[-1].strip().strip("`")
+        elif "executor skill" in lowered:
+            metadata["executor_skill"] = line.split(":", 1)[-1].strip().strip("`")
+        elif "internal validator" in lowered:
+            metadata["internal_validator"] = line.split(":", 1)[-1].strip().strip("`")
+        elif "external review" in lowered:
+            metadata["external_review"] = line.split(":", 1)[-1].strip().strip("`")
+
+    # Compact PLAN_TEMPLATE (sections 1–8); legacy aliases kept for older artifacts.
+    required_groups = {
+        "execution_metadata": ["execution_metadata", "metadados_de_execu_o", "metadados_execu_o"],
+        "executive_translation": [
+            "tradu_o_executiva",
+            "executive_summary",
+            "executive_translation",
+            "resumo_executivo",
+        ],
+        "execution_invariants": [
+            "invariantes_de_execu_o",
+            "invariantes_de_execu_o_derivados_do_prd",
+            "execution_invariants",
+        ],
+        "pitfalls": ["pitfalls"],
+        "sprint_opening_state": [
+            "estado_na_abertura_da_sprint",
+            "estado_na_abertura_da_sprint_pr_implementa_o",
+            "current_state_relevant_to_execution",
+            "estado_atual_relevante_para_execu_o",
+        ],
+        "execution_tasks": ["tarefas_de_execu_o", "execution_tasks", "tarefas"],
+        "technical_contracts": [
+            "contratos_t_cnicos",
+            "contratos_t_cnicos_s_ambiguidade_prd_c_digo",
+            "technical_contracts",
+        ],
+        "validation_checklist": [
+            "valida_o_e_checklist",
+            "valida_o_e_checklist_validator",
+            "validation_and_checklist",
+            "validation",
+            "valida_o",
+            "valida_o_final",
+        ],
+    }
+
+    optional_groups = {
+        "slices": ["slices", "slices_somente_se_execution_mode_orchestrated_per_slice"],
+        "open_questions_blockers": [
+            "perguntas_em_aberto_e_bloqueios_reais",
+            "open_questions_and_real_blockers",
+            "open_questions",
+            "real_blockers",
+        ],
+        # Legacy sections — extracted if present, never required.
+        "handoff_prompt": ["handoff_prompt", "executor_guidance"],
+        "legacy_scope": ["scope", "escopo"],
+        "legacy_architecture": [
+            "solution_design_and_architecture",
+            "design_e_arquitetura_da_solu_o",
+        ],
+    }
+
+    missing = [name for name, aliases in required_groups.items() if not has_any(summary, aliases)]
+
+    execution_mode = metadata.get("execution_mode", "").lower()
+    if "orchestrated" in execution_mode and not has_any(summary, optional_groups["slices"]):
+        missing.append("slices")
+
+    return {
+        "sections": [
+            {"title": section["title"], "key": section["key"], "level": section["level"]}
+            for section in sections
+        ],
+        "tasks": tasks,
+        "missing_required_sections": missing,
+        "execution_metadata": metadata,
+        "summary": {
+            "execution_metadata": metadata_section,
+            "executive_translation": first_section(summary, required_groups["executive_translation"]),
+            "execution_invariants": first_section(summary, required_groups["execution_invariants"]),
+            "pitfalls": first_section(summary, required_groups["pitfalls"]),
+            "sprint_opening_state": first_section(summary, required_groups["sprint_opening_state"]),
+            "execution_tasks": first_section(summary, required_groups["execution_tasks"]),
+            "technical_contracts": first_section(summary, required_groups["technical_contracts"]),
+            "validation_checklist": first_section(summary, required_groups["validation_checklist"]),
+            "slices": first_section(summary, optional_groups["slices"]),
+            "open_questions_blockers": first_section(
+                summary, optional_groups["open_questions_blockers"]
+            ),
+            "handoff_prompt": first_section(summary, optional_groups["handoff_prompt"]),
+        },
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("plan", help="Path to a markdown plan artifact")
+    args = parser.parse_args()
+
+    plan_path = pathlib.Path(args.plan)
+    payload = parse_plan(plan_path.read_text(encoding="utf-8"))
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/zcode/skills/atlas-plan-execute/scripts/validate_gate_result.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Classify a gate outcome into pass, fixable, or blocked."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from typing import Any
+
+
+def load_json(path: pathlib.Path) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(f"JSON file not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("gate_result", help="JSON file describing the gate outcome")
+    parser.add_argument("--budget-state", help="Optional budget state JSON file")
+    args = parser.parse_args()
+
+    try:
+        payload = load_json(pathlib.Path(args.gate_result))
+        budget = load_json(pathlib.Path(args.budget_state)) if args.budget_state else {}
+    except FileNotFoundError as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 1
+
+    failed_checks = payload.get("failed_checks", [])
+    invariant_breaks = payload.get("invariant_breaks", [])
+    external_blockers = payload.get("external_blockers", [])
+    diff_attributed = payload.get("diff_attributed", True)
+
+    if external_blockers or budget.get("blocked"):
+        status = "blocked"
+    elif failed_checks or invariant_breaks:
+        status = "fixable" if diff_attributed else "blocked"
+    else:
+        status = "pass"
+
+    result = {
+        "status": status,
+        "failed_checks": failed_checks,
+        "invariant_breaks": invariant_breaks,
+        "external_blockers": external_blockers,
+        "diff_attributed": diff_attributed,
+    }
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/zcode/skills/atlas-plan-handoff/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: atlas-plan-handoff
+description: Skill `atlas-plan-handoff`. Produz um handoff executável da família Atlas, fechando prefixo, modo de execução e gates no próprio artefato para consumo por `atlas-plan-execute` e `atlas-slice-review`.
+---
+
+# Atlas Plan Handoff
+
+Use esta skill quando o usuário pedir um plano executável da cadeia `atlas-*`.
+
+O artefato segue `PLAN_TEMPLATE.md` e `BOUNDARY_PRD_PLAN.md` — **localize ambos em `<raiz-do-plugin>/packages/templates/`**. O plano **não** depende de memória do chat para prefixo, modo ou executor.
+
+## Resolução Canônica de Templates
+
+* Fonte única: `packages/templates/` empacotado no plugin Atlas Workflow.
+* Resolver `PLAN_TEMPLATE.md` e `BOUNDARY_PRD_PLAN.md` a partir da raiz do plugin/bundle, antes de olhar qualquer arquivo do repo consumidor.
+* Template local do repo consumidor nunca sobrepõe o template empacotado.
+* Se `packages/templates/PLAN_TEMPLATE.md` ou `packages/templates/BOUNDARY_PRD_PLAN.md` não existir, abortar com erro claro: `Template canônico ausente: <nome-do-template>`.
+* Não usar fallback silencioso para cópias antigas, vault local ou templates globais.
+
+## State persistence
+
+Use `atlas_run_state` como fonte primária de estado da run. Não leia/escreva estado por file IO direto. Se o MCP estiver indisponível, avise que o gate não pode ser comprovado e aborte a fase em vez de seguir por fallback narrativo.
+
+## Plan path resolution
+
+Os paths são fornecidos pelo adapter de host: consultar `atlas_capabilities` e ler `plan_paths` (`write` + `read_order`). Referência canônica: `packages/orchestrator/references/host-adapters.md`. Valores atuais (iguais em todo host):
+
+Escrita de novos planos: somente `.atlas/plans/`.
+
+Leitura/migração por 1 release (ordem de `plan_paths.read_order`):
+
+1. `.atlas/plans/`
+2. `.cursor/plans/` com warning de depreciação
+3. `.codex/plans/` com warning de depreciação
+
+Se um plano legado for lido, o próximo artefato gerado deve ser salvo em `.atlas/plans/`.
+
+## Cadeia de execução
+
+```text
+atlas-plan-handoff → atlas-plan-execute → atlas-task-validator → atlas-slice-review (opcional, via `--review`)
+```
+
+No workflow `full`, `atlas-plan-handoff` é autoria documental do agente principal/orquestrador. O primeiro sub-agent da cadeia só nasce em `atlas-plan-execute`.
+
+---
+
+## Fluxo obrigatório
+
+1. **Classificação da tarefa:** feature, ui, contract, navigation, shared, security, diagnostic, refactoring, testing. Leia instruções reais aplicáveis do repo; `project-rules/` é apenas um formato possível, nunca requisito universal.
+2. **Grounding no código:** confirme padrões, contratos, manifests e comandos reais antes de inferir. Resolva baseline/perfis via `../_shared/references/stack-profiles.md` + `detectStackProfiles(project_root, declared_commands, boundary_paths)`; não presuma Flutter nem aplique perfil fora do package correspondente.
+3. **Decisões estáveis:** sanar bloqueios com perguntas ao usuário; registrar no plano (não recopiar tabela D* do PRD — referenciar `PRD §3`).
+4. **Escrita:** artefato markdown no path canônico `.atlas/plans/`. Teto orientativo ~250–350 linhas (até ~450 com slices).
+
+---
+
+## Metadados obrigatórios (topo do artefato)
+
+```md
+## Metadados de execução
+- Plan prefix: `atlas`
+- Execution mode: `sequencial (T01→TN)` | `orchestrated-per-slice`
+- Executor skill: `atlas-plan-execute`
+- Internal validator: `atlas-task-validator`
+- External review: `atlas-slice-review` (optional)
+```
+
+Regras:
+
+- `Plan prefix` é sempre `atlas`.
+- Se o modo não estiver decidido, o plano **não** está pronto para execução.
+- Deixe explícito por que o modo escolhido é adequado, checks por task vs fechamento de slice e quando parar em `blocked`.
+
+---
+
+## Estrutura do plano (seções 1 a 8)
+
+### 1. Tradução executiva
+
+- O que será implementado e o resultado observável técnico.
+- Padrão de referência no monorepo e tabela **referência vs esta entrega** (ligar a `PRD §3` D*, não recopiar a tabela).
+- Link ao PRD: `PRD §2` escopo, `PRD §3` decisões.
+
+### 2. Invariantes de execução (derivados do PRD)
+
+- Invariantes técnicos inegociáveis (ex.: sem refetch ao filtrar).
+- Referenciar IDs: `PRD §3 D12` — não colar a tabela D* inteira.
+
+### 3. Pitfalls
+
+- `anti-padrão observado` → `padrão canônico correto` (ancorado no repo).
+
+### 4. Estado na abertura da sprint (pré-implementação)
+
+- 3–6 bullets sobre o código hoje (comportamento/ausência — não inventário global de arquivos).
+- Se já implementado: tratar como checklist de verificação.
+
+### 5. Tarefas de execução
+
+Tarefas `#### T01.` … `#### TNN.` com schema de `BOUNDARY_PRD_PLAN.md` canônico empacotado:
+
+- **Objetivo**
+- **Referência** (módulo/padrão no monorepo — evite listas longas de paths; o executor descobre no repo)
+- **Pré-condições**
+- **Mudança esperada**
+- **Invariantes preservados**
+- **Não mudar** / **Não fazer**
+- **Dependências**
+- **Riscos** (se não óbvio)
+- **Critério de done**
+- **Validação local** (comando com path do package)
+- **Quality gates** (opcional em tasks críticas)
+- **Casos mínimos** (somente em tasks de teste)
+
+**Regra de minimalismo estrutural (autoria de task):** ao redigir `Mudança esperada`, prefira a forma mínima viável que cumpre o `Critério de done` — reusar módulo/símbolo já existente no repo antes de introduzir nova abstração; usar stdlib/feature nativa antes de dependência nova; evitar indireção, factory, wrapper, camada ou opção de config não exigida por PRD/invariante. A regra recai **somente** sobre abstração/indireção/arquivo/dependência nova. **Nunca** reduz: validação de trust-boundary, error-handling, data-loss, invariantes §2, cobertura de cenário/teste e negative paths. Em dúvida entre enxuto e seguro, escolha seguro.
+
+Última task típica: **Validação final** (checks reais da stack ativa e passos manuais alinhados a **PRD §4–6**). Flutter usa `flutter analyze/test`; Node e Python usam somente scripts/ferramentas declarados no repo/plano.
+
+### 6. Contratos técnicos (só ambiguidade PRD → código)
+
+- Assinaturas, shapes e mapeamentos onde o PRD §5 não fecha implementação.
+
+### 7. Slices (somente se `execution_mode: orchestrated-per-slice`)
+
+- Tabela: slice, tasks, objetivo, boundary de diff esperado.
+
+### 8. Validação e checklist (validator)
+
+- Critérios derivados de **PRD §6** + invariantes **§2** deste plano.
+- Título recomendado: `## 8. Validação e checklist (validator)`.
+- Comandos globais aplicáveis ao package, derivados de manifests/scripts reais; nunca inventar `flutter`, `npm` ou `pytest`.
+
+---
+
+## Seção opcional
+
+### 9. Perguntas em aberto e bloqueios reais
+
+- Só bloqueios que impedem execução segura. O executor **para** se houver itens ativos aqui.
+- **Não** confundir com PRD §7 Apêndice (Referências).
+
+---
+
+## O que NÃO incluir (propositalmente)
+
+- Handoff prompt final no artefato (o executor lê o arquivo; ver `BOUNDARY_PRD_PLAN.md` no repo ativo).
+- Gate de prontidão do autor do plano.
+- Lista integral de rules do `project-rules` (o executor carrega via `AGENTS.md`).
+- Cópia integral do escopo/fora de escopo do PRD.
+- Inventário global de todos os arquivos tocados.
+
+---
+
+## Uso standalone vs protocolo interno no workflow (PRD D10/D11)
+
+Esta skill é de **autoria documental** (redigir um `PLAN_*.md`). A fronteira de determinismo do Atlas é a **mutação de código** (PRD D10): como redigir um plano não muta código, **autoria é livre, execução é gateada**.
+
+### (a) Uso standalone permitido
+
+Você pode invocar `atlas-plan-handoff` diretamente, fora do pipeline, para escrever um plano. Não há restrição: autoria documental não muta o produto. O `PLAN_*.md` resultante é livre para existir e ser editado.
+
+### (b) O artefato NÃO é confiável só por existir
+
+Um plano escrito standalone **não vale como gate aprovado** só porque existe — nem mesmo com nome `PLAN_*.md`. Ao entrar em execução (modos `full`/`direct`/`execute`), o plano é **re-gateado obrigatoriamente** por `atlas_verify_artifact` + `atlas_verify_template_conformance` (TC); no modo `execute`, essa reverificação na entrada é o equivalente ao gate pós-plano (PRD D13). Plano velho, manual, renomeado ou fora de conformidade **trava na entrada da execução**, não na autoria. Esta skill não declara o plano "executável de forma determinística" só por tê-lo escrito.
+
+### (c) Standalone vs protocolo interno no workflow
+
+- **Standalone:** o usuário conduz a skill diretamente; o produto é o `PLAN_*.md`, sujeito a re-validação na entrada de execução.
+- **No workflow:** quem conduz a fase de plano é o **orquestrador principal** (agente principal), que despacha/autora o plano antes de validá-lo e roda os gates MCP. Uma vez que o plano passa `atlas_verify_artifact` + TC, o orquestrador fica de mãos atadas (não edita mais o plano). A skill é a mesma; o que muda é quem orquestra e os gates que cercam a fase.
+
+> **Invariante:** autoria é livre, execução é gateada. Um plano só vira confiável para execução após `atlas_verify_artifact` + TC na entrada (PRD D11).
+
+---
+
+## Consistência da cadeia
+
+O próximo agente, só lendo o artefato, deve saber:
+
+- usar apenas skills `atlas-*` declaradas nos metadados;
+- respeitar `execution_mode`;
+- rodar `atlas-task-validator` antes de fechar a slice;
+- usar `atlas-slice-review` como segunda camada fria, não substituto do validator interno;
+- cruzar aceite de negócio com **PRD §4–6** quando o checklist do §8 for fino.

package/hosts/zcode/skills/atlas-plan-handoff/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Atlas Plan Handoff"
+  short_description: "Handoff executável da família atlas-* com prefixo e modo fechados"
+  default_prompt: "Use $atlas-plan-handoff para produzir um plano executável da cadeia atlas-* com prefixo fechado, execution mode explícito, executor correto, validator interno obrigatório e review externo opcional."
+
+policy:
+  allow_implicit_invocation: true