@igor-guari/pi-skill-implement-spec 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Matt Pocock
+Copyright (c) 2025 Igor Guariroba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# pi-skill-implement-spec
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Pi Package](https://img.shields.io/badge/pi--package-skill-blue)](https://github.com/IgorGuariroba/pi-skill-implement-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**implement-spec** skill for the **[Pi coding agent](https://pi.dev)**, adapted from Matt Pocock's Engineering Skills.
+
+> Implement a spec and its ticket graph on one integration branch using Pi workers.
+
+---
+
+## Installation
+
+Install directly into Pi using `pi install`:
+
+```bash
+pi install git:github.com/IgorGuariroba/pi-skill-implement-spec
+```
+
+Or clone into your local/global skills directory:
+
+```bash
+# Global Pi skills directory:
+git clone https://github.com/IgorGuariroba/pi-skill-implement-spec.git ~/.pi/agent/skills/implement-spec
+
+# Or Agent Skills standard path:
+git clone https://github.com/IgorGuariroba/pi-skill-implement-spec.git ~/.agents/skills/implement-spec
+```
+
+---
+
+## Usage
+
+Trigger it explicitly in your session:
+
+```text
+/skill:implement-spec
+```
+
+Or let Pi automatically route to it based on conversation context and need.
+
+---
+
+## Credits
+
+- **Original concept & methodology**: [Matt Pocock](https://github.com/mattpocock)
+- **Adapted for Pi Agent**: [Igor Guariroba](https://github.com/IgorGuariroba)
+
+---
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: implement-spec
+description: Implement a spec and its ticket graph on one integration branch using
+  Pi workers.
+disable-model-invocation: true
+license: MIT
+metadata:
+  author: Matt Pocock
+  adapted_by: Igor Guariroba
+  version: 1.0.0
+---
+
+
+# Implement spec
+
+Implement the provided spec and tickets on one **integration branch**. Tickets form a **task graph**: the **frontier** contains only tickets whose dependencies have been integrated and validated.
+
+Read `references/pi-workers.md` before delegating. Workers are fresh Pi processes, not native subagents. Share absolute context pointers to the spec, tickets, exploration notes and commits. Keep notes and execution artifacts outside the repository.
+
+## Steps
+
+1. **Map the graph.** Read the spec and every ticket; record acceptance criteria, dependencies and tracker workflow. Use `docs/agents/issue-tracker.md` when present, otherwise the relevant installed tracker skill. Ask for any missing spec, tickets or tracker information that blocks execution. This step is complete when every ticket is accounted for and the graph has no unresolved dependency ambiguity or cycles.
+
+2. **Explore when needed.** Use a read-only exploration worker for unresolved codebase/documentation questions. Have it return evidence and pointers; the coordinator saves useful notes outside the repo. Exploration is complete when each blocking question has an answer or an explicit blocker.
+
+3. **Prepare integration.** Record the starting SHA and existing local changes, then create the integration branch without disturbing them. The coordinator is its sole writer and performs merges serially. If the tracker closes work through PRs, or the user requests one, open a draft after the first integrated commit; reference the spec and tickets using the tracker's closing convention.
+
+4. **Dispatch the frontier.** Create a dedicated branch/worktree from the current integration tip for each ready ticket, then start a fresh implementer worker there. The prompt must require the worker to:
+   - confirm its worktree, branch and base SHA before editing; report a mismatch to the coordinator rather than resetting;
+   - read `../tdd/SKILL.md` (pass an absolute path) and implement the ticket's acceptance criteria;
+   - run relevant checks, commit only its own work and report commit SHA(s), acceptance evidence, checks/results and blockers;
+   - leave integration and other workers' worktrees to the coordinator.
+
+   Start independent tickets concurrently through the shared worker guide. A ticket is ready for integration only after the coordinator verifies its commit(s), report and clean worktree.
+
+5. **Integrate serially.** Merge each completed ticket into integration. If the tip advanced, resolve conflicts and validate the combined state before accepting it. Delegate conflict resolution only to a fresh worker with exclusive ownership of the integration worktree while the coordinator pauses writes. Unresolved conflicts or failed checks keep the ticket blocked. Recompute the frontier only after a successful merge and relevant integration checks; return to step 4 until every ticket is integrated.
+
+6. **Review the whole spec.** Read `../code-review/SKILL.md` and review integration against the starting SHA from step 3. Supply the spec and all ticket criteria. Fix actionable findings in a fresh implementer worktree and integrate serially. Run the full validation suite and re-review affected areas. This step is complete when every criterion has evidence, both review axes have results (or an explicit unavailable source), and outstanding issues are resolved or reported as blockers.
+
+7. **Deliver and clean up.** Only after validation, mark the draft PR ready, or resolve tickets using the tracker's workflow when no PR exists. Do not mark incomplete work resolved. Report integration branch, commits/PR, checks and ticket outcomes. Remove only worktrees created by this run that are clean and whose commits are integrated; preserve blocked/unmerged work and execution artifacts for recovery. Avoid forced cleanup.

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@igor-guari/pi-skill-implement-spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Implement a spec and its ticket graph on one integration branch using Pi workers.",
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "pi",
+    "implement-spec",
+    "engineering-skills"
+  ],
+  "author": "Igor Guariroba",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorGuariroba/pi-skill-implement-spec.git"
+  },
+  "homepage": "https://github.com/IgorGuariroba/pi-skill-implement-spec#readme",
+  "pi": {
+    "skills": [
+      "."
+    ]
+  },
+  "files": [
+    "SKILL.md",
+    "*.md",
+    "references/"
+  ]
+}

package/references/pi-workers.md

@@ -0,0 +1,33 @@
+# Workers no Pi
+
+Referência compartilhada para delegação em processos Pi independentes. Um **worker** é outro processo Pi com contexto próprio; o coordenador continua responsável pelo resultado.
+
+## Preparar e executar
+
+1. Confira `pi --help` para as opções da instalação. Crie um diretório de execução fora do repositório (`mktemp -d`) e um prompt por tarefa. Registre papel, cwd absoluto, escopo permitido, referências absolutas à spec/tickets/skills, resultado esperado e critério de conclusão. Compartilhe ponteiros, não o histórico da conversa.
+2. Execute cada tarefa com cwd explícito e contexto novo. Exemplo de comando para `process_start` (substitua os caminhos):
+
+   ```bash
+   cd /absolute/worktree && pi --print --no-session @/absolute/run/task.md > /absolute/run/result.md 2> /absolute/run/stderr.log
+   ```
+
+   Use o modelo/provider solicitado, se houver; caso contrário, mantenha os defaults configurados. `--no-session` evita persistir/reutilizar a conversa; configurações e instruções do projeto continuam disponíveis. Carregue outras skills lendo seus `SKILL.md` por caminho absoluto no prompt. Pi não precisa de uma ferramenta `Skill` para isso.
+3. Inicie tarefas independentes com chamadas separadas de `process_start`, cada uma com `watch`: `success: {exitCode: {eq: 0}}`, `failure: {exitCode: {ne: 0}}` e `timeoutMs` finito conforme o trabalho (por exemplo, 600000 para revisão). Após registrar os watches, informe a espera e encerre o turno. Os resultados chegam automaticamente; use `process_logs` para diagnóstico, não polling manual.
+4. Ao receber a conclusão, leia resultado e stderr e confira os artefatos. Exit code zero comprova execução, não cumprimento da tarefa. Uma resposta sem evidência, com bloqueio ou trabalho parcial é incompleta. Em timeout, inspecione e pare o processo antes de repetir ou liberar seu worktree. Preserve prompts, resultados e logs até entregar o trabalho.
+
+Se `process_start`/watch não estiverem disponíveis, escolha o caminho Herdr abaixo quando aplicável; caso contrário, execute tarefas sequencialmente com timeout explícito na ferramenta disponível. Registre a perda de paralelismo. Falha de autenticação ou diálogo que exija interação deve ser reportado ao usuário; não invente aprovações nem transfira segredos em prompts.
+
+## Contratos e isolamento
+
+- **Implementação:** um worktree e branch exclusivos por worker escritor. O resultado informa commit(s), critérios atendidos, comandos/testes e resultados, pendências e status Git. Só aceite conclusão após conferir esses itens.
+- **Revisão/exploração:** leitura apenas do código; saída final em stdout, capturada pelo coordenador. Autorize escrita de notas externas apenas quando a tarefa exigir. Com `bash`, uma instrução de leitura não é sandbox: mantenha o escopo explícito e verifique o status Git antes/depois. Para leitura estrita sem shell, a instalação oferece `--tools read,grep,find,ls --no-mcp`; o coordenador pode fornecer diff e commits em arquivos externos.
+- **Integração:** um único escritor na branch de integração. O coordenador serializa merges; workers de tickets não atualizam essa branch. Nenhum reset destrutivo ou limpeza forçada de alterações alheias.
+- **Conclusão:** o coordenador valida commits, testes e critérios de aceitação. Estado de processo/pane não substitui essa validação.
+
+## Herdr: acompanhamento visível
+
+Quando o usuário mencionar/pedir Herdr e `HERDR_ENV=1`, leia `../skills/herdr/SKILL.md` (relativo a este arquivo) e consulte a CLI instalada antes de controlar panes. Fora do Herdr, continue com processos Pi; Herdr não é pré-requisito.
+
+Use os comandos documentados de pane para executar o mesmo comando `pi --print --no-session` em um shell disponível, preservando foco e cwd explícito. Capture saída, stderr e exit code em arquivos exclusivos fora do repositório. Aguarde via `watch_create` com polling barato do arquivo de exit code, sucesso zero, falha não zero e timeout finito. Publique esse arquivo apenas depois que o Pi terminar. Após registrar o watch, encerre o turno. Em timeout, inspecione o pane antes de repetir.
+
+Se preferir um Pi interativo reconhecido por Herdr, confira primeiro se a CLI instalada oferece esse kind e siga a skill Herdr para iniciar, enviar prompt e aguardar. Cada tarefa independente começa em um processo/sessão nova. `idle`/`done` indica estado da interface, não aceitação do trabalho: leia a resposta e valide os artefatos. Crie workspaces/tabs ou outra topologia somente quando o usuário os solicitar; encerre apenas recursos criados para esta execução.