Giuice Agent Skills
Reusable Open Agent Skills for AI coding agents and agentic workflows.
Recommended: the current spec-to-done
The current end-to-end workflow lives in giuice/spec-to-done and is available on skills.sh. Install its single self-contained skill:
npx skills add giuice/spec-to-done --skill spec-to-done
That one installation includes specification, planning, execution/replanning, and reporting. Do not install plan-from-spec, execute-plan, and completion-report separately for the current composite workflow. Describe the outcome in your own words, or explicitly request a single stage; the composite satisfies missing prerequisites and stops at the requested stage.
Standalone spec-from-scratch
spec-from-scratch remains an independent, fully usable skill in this repository. It interviews you and produces a SPEC without requiring the composite or any other skill. The current composite includes its own specification stage; installing it does not require a separate spec-from-scratch installation. If you only want the independent specification skill:
npx skills add giuice/giuice-agent-skills --skill spec-from-scratch
Existing users of the legacy workflow
The four legacy skills here are spec-to-done (the router), plan-from-spec, execute-plan, and completion-report. Their procedures remain available for existing users; the sections below describe that legacy architecture. explorar-planejar-executar remains a separate pt-BR workflow.
Switching is not a drop-in artifact migration. Before planning or execution, the current composite checks SPEC readiness and user approval; existing specifications must satisfy its prerequisites. It uses TRACK.md / SNAPSHOT.md instead of the legacy LEDGER.md. Preserve existing work and review the current workflow before resuming it there; installing the new skill alone does not convert a run.
Legacy workflow
Five cooperating skills take work from an unclear idea to an evidence-grounded outcome: the four legacy workflow skills plus the independent spec-from-scratch when a specification interview is needed. The legacy stages also accept a stated goal without a SPEC; the current composite has different prerequisites.
SPECIFY → PLAN → EXECUTE ↔ REPLAN → REPORT
What actually happens
| Stage | Skill | What you see |
|---|
| 0. Route | spec-to-done | It tells you whether this work needs the loop, and where you already are in it |
| 1. Specify | spec-from-scratch | Rounds of clickable questions until every requirement domain is clear, then SPEC.md |
| 2. Plan | plan-from-spec | It inspects your actual current state, then writes PLAN.md — tasks with observable "done when" conditions |
| 3. Execute | execute-plan | One task at a time, each verified against reality, each recorded in LEDGER.md |
| 4. Replan | plan-from-spec again | After every task: is the rest of the plan still true? Usually yes, and nothing changes |
| 5. Report | completion-report | What became true, what was verified, what remains — and nothing else |
Each piece of work gets its own folder, named after a slug derived from your goal. Features never share a folder, and the router checks a folder's stored goal before resuming it, so different work never silently collides:
spec-interview/
auto-triage/ ← derived from "auto-triage the support inbox"
SPEC.md what counts as success (optional — a stated goal also works)
PLAN.md how to get there (rewritten as reality intervenes)
LEDGER.md what actually became true (the resume point)
REPORT.md what you are told at the end
billing-export/ ← a different feature, its own independent run
SPEC.md
PLAN.md
spec-interview/ is just the parent directory the workflow uses. auto-triage is an example slug, not a fixed name — start a new feature and you get a new folder beside it. The tree shows the four execution-stage artifacts; interview files (state.md, round-*.html) live in the same folder.
Because the state lives in files rather than in the conversation, you can close the session, come back tomorrow, and continue.
When not to use it
Most work does not need this. The loop costs an interview, a plan file, a verification and a ledger entry per task. On a small, reversible change that overhead buys nothing, and spec-to-done will tell you so instead of running the ceremony.
The middle path is usually the right one: skip the SPEC interview, state the goal directly, and run plan → execute → report.
The design in one paragraph
Each stage has a strict boundary. The SPEC defines success. The plan is mutable strategy. The ledger is the observable record, written as work happens rather than reconstructed from memory afterwards. The report is a projection of contract × final state × evidence — not a summary of what the agent did. The load-bearing invariant is that a plan may change, but the contract may not change silently because the plan did: if execution makes an acceptance criterion unreachable, the workflow stops and asks you, rather than quietly satisfying a weaker goal.
The plan/execute/replan separation follows Erdogan et al., PLAN-AND-ACT, where dynamic replanning was the single largest ablation gain — evidence that plan quality, not action execution, is the bottleneck on long tasks. The specification gate, the incremental ledger, and the reporting stage are additions.
The execution shape is hub-and-spoke, not a serial pipeline — and that is deliberate. Serial multi-agent pipelines degrade at their handoffs: each agent compresses what it found into a summary for the next, and evidence, confidence, and detail fall out of the chain. Here every performer returns to the same orchestrator, which keeps the whole line of reasoning, and the ledger accumulates state, evidence, and provenance incrementally as each task ends instead of being reconstructed from memory afterwards. This reduces handoff degradation without pretending to eliminate compression: the ledger deliberately keeps state deltas, evidence, and material facts, and deliberately drops deliberation, discarded alternatives, and raw output — a controlled, auditable compression, not a lossless channel.
Skills
spec-to-done
The entry point. Decides whether work warrants the full loop, detects which stage it is already in by reading the working folder, and routes. Holds no planning or reporting rules of its own.
spec-from-scratch
Creates a complete product SPEC from an unclear idea through an exhaustive requirements interview — goals, users, scope, business rules, constraints, edge cases, acceptance criteria — and refuses to draft until a readiness gate passes. Useful on its own, whatever you plan to do with the SPEC afterwards.
plan-from-spec
Turns a SPEC or a stated goal into a plan of outcome-shaped tasks, each with an observable postcondition, and regenerates that plan when execution proves it wrong. Replanning may change the strategy, never the definition of success.
execute-plan
Executes a plan task by task as an orchestrator: dispatches each task to a subagent, to itself, or to a person, verifies the postcondition itself against observable state, and records what became true in a semantic ledger that doubles as the resume point.
completion-report
Produces the smallest user-facing report that preserves every material fact about the outcome. No activity narration, no unsupported success claims, no hidden unverified state.
explorar-planejar-executar
A separate pt-BR workflow, not part of the loop above. Turns vague goals into concrete execution through /explorar, /planejar, and /executar. Lighter weight and more conversational — it keeps its own planning file rather than the four-artifact folder, and has no spec contract, ledger, or verification step.
Domain neutrality
spec-to-done, plan-from-spec, execute-plan, and completion-report assume no web, no code, and no repository. They work for research, writing, operations, and physical-world tasks, and they accept a plain stated goal when no SPEC exists.
spec-from-scratch is narrower: its interview and output are shaped for product work. For non-product domains, let the router send you straight to plan-from-spec with the goal stated directly.
Legacy repository installation
These commands target this repository, not the current composite recommended above. Prefer an explicit skill name when you only need the standalone specification skill or the separate pt-BR workflow.
List what is available:
npx skills add giuice/giuice-agent-skills --list
Install everything in this legacy repository:
npx skills add giuice/giuice-agent-skills
Install the legacy router only:
npx skills add giuice/giuice-agent-skills --skill spec-to-done
