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