gepetto

Overview of gepetto skill

What gepetto does

The gepetto skill is a structured planning workflow for turning a rough feature idea into a detailed implementation package before coding starts. Instead of jumping from a short prompt straight into code, gepetto walks through research, clarifying interview questions, spec synthesis, implementation planning, external review, and section-by-section breakdown.

Who gepetto is best for

This gepetto skill fits best if you are:

• planning a non-trivial feature with unclear scope
• working across backend, frontend, infra, or integrations
• trying to reduce rework before implementation
• using AI for Requirements Planning rather than only code generation
• willing to provide a markdown spec file and review follow-up questions

If you just want a quick code snippet or a tiny one-file change, gepetto is probably heavier than needed.

The real job-to-be-done

Most users do not need “more AI planning” in the abstract. They need a way to convert vague requests like “build auth,” “add billing,” or “support file sync” into a plan that captures edge cases, dependencies, rollout concerns, and implementation order. That is where gepetto is stronger than a generic prompt.

What makes gepetto different

The main differentiators of gepetto are practical:

• it requires a spec file, which gives the workflow a durable planning anchor
• it explicitly asks clarifying questions instead of silently assuming missing requirements
• it can perform research before finalizing the plan
• it includes an external review step using other model CLIs if available
• it produces sectionized outputs intended for execution, not just one long essay

That combination makes the gepetto skill more decision-oriented than a normal “write me a plan” prompt.

What users care about before installing

Before adopting gepetto, most users should check four things:

1. Do you have a markdown spec file? The skill expects one.
2. Do you want files written into a planning directory? gepetto is file-output oriented.
3. Can your environment support the broader workflow? Some steps assume research and optional external review tooling.
4. Is your task complex enough to justify the process? The payoff grows with feature complexity.

How to Use gepetto skill

Install gepetto in your skill environment

If you use the toolkit’s install pattern, add the skill from the repository:

npx skills add softaworks/agent-toolkit --skill gepetto

Then invoke the skill from an agent session that supports slash-skill usage. The repository path is:

skills/gepetto

If your environment uses a different skill-loading mechanism, use the repo files directly and mirror the same invocation contract.

Understand the required input contract

The most important adoption detail: gepetto expects a markdown spec file path at invocation time. The skill checks for an @file input ending in .md, and if that is missing, it stops and asks for the correct input.

Practical implication: do not start gepetto with only a loose chat request. Start it with something like:

/gepetto @planning/auth-spec.md

The parent directory of that spec becomes the planning workspace where gepetto writes additional .md outputs.

What your spec file should contain

Your starting spec does not need to be perfect, but stronger inputs produce much better planning output. A good initial file usually includes:

• the feature or problem statement
• user types and key workflows
• known constraints
• technology stack
• existing system context
• unknowns or open questions
• success criteria
• non-goals

Even a vague spec is acceptable, but the more concrete the operational context, the less time gepetto spends recovering missing assumptions.

A strong gepetto spec template

For better gepetto usage, seed your spec with short sections like:

• Goal: what should exist when this is done
• Users: who interacts with it
• Current system: relevant services, repos, or modules
• Constraints: deadlines, compliance, performance, budget
• Interfaces: APIs, events, storage, third-party dependencies
• Risks/unknowns: things you are unsure about
• Definition of done: what makes the plan actionable

This is usually enough to get a high-quality first pass.

What happens during the gepetto workflow

From the repository evidence, gepetto follows a clear progression:

1. validate the spec file input
2. set up the planning session
3. decide whether research is needed
4. run research and synthesize findings
5. interview the user with focused questions
6. write a consolidated implementation plan
7. run external review on the plan
8. split the work into implementation sections

That makes gepetto especially useful for requirements that have hidden edge cases or architectural tradeoffs.

How to turn a rough goal into a usable invocation

Weak starting point:

Build authentication

Stronger starting point for gepetto:

Create email/password and Google OAuth login for our SaaS app. Stack: Next.js, Postgres, Stripe, existing RBAC. Need session handling, audit logging, admin user provisioning, password reset, account lockout, and migration plan from legacy auth. Must support SOC 2 audit needs. Unknown: whether to use our current session store or move to JWT.

Why this works better:

• it gives research targets
• it surfaces integration points
• it reveals compliance and migration concerns
• it creates better interview questions
• it reduces generic planning fluff

Best workflow for gepetto for Requirements Planning

For gepetto for Requirements Planning, the best workflow is usually:

1. write a rough-but-real spec file
2. run gepetto on that file
3. answer clarifying questions with operational detail, not slogans
4. review the generated plan for missing business rules
5. use the section outputs as implementation units or tickets
6. rerun or resume after major requirement changes

This is much more effective than asking for one giant final spec in a single shot.

Repository files to read first

If you want to judge the skill before full adoption, read these in order:

1. skills/gepetto/SKILL.md
2. skills/gepetto/README.md
3. skills/gepetto/references/research-protocol.md
4. skills/gepetto/references/interview-protocol.md
5. skills/gepetto/references/external-review.md
6. skills/gepetto/references/section-index.md
7. skills/gepetto/references/section-splitting.md

This reading path tells you more about real behavior than a quick skim of the main README alone.

Output files and why they matter

gepetto is not just a conversational prompt. It is designed to write planning artifacts into your chosen directory. The repo indicates outputs such as:

• research notes
• a main implementation plan
• sections/index.md
• individual section files

That matters because the workflow is resumable and easier to hand off than ephemeral chat output.

External review is useful but optional in practice

One of gepetto’s strongest ideas is the external review pass. The references show it expects review of the generated plan via other model CLIs such as Gemini and Codex. This can materially improve plan quality by surfacing:

• security gaps
• edge cases
• performance concerns
• ambiguous requirements
• architectural footguns

But this also means full-value gepetto usage depends on your environment. If you lack those external tools, the rest of the planning workflow can still be useful, but that review layer may need adaptation.

Practical tips that improve first-run quality

A few details will materially change your gepetto results:

• include existing patterns or file paths if you already have a codebase
• mention expected scale, traffic, and failure handling
• state what must not change
• list any compliance, privacy, or audit needs
• answer interview questions concretely, not with “whatever is standard”
• review generated sections for dependency order before execution

gepetto performs best when it is allowed to expose ambiguity early instead of hiding it.

gepetto skill FAQ

Is gepetto better than a normal planning prompt?

For simple work, not necessarily. For multi-step features, gepetto is usually stronger because it enforces a planning process: spec validation, research, interview, synthesis, review, and sectioning. A normal prompt may feel faster, but it is also more likely to skip hidden assumptions.

Is gepetto beginner-friendly?

Yes, if you can write a basic markdown spec and answer follow-up questions. You do not need a perfect spec up front. However, absolute beginners may still need help judging whether the resulting plan matches real engineering constraints.

When should I not use the gepetto skill?

Skip gepetto when:

• the task is tiny and low-risk
• you already have an approved implementation plan
• you cannot provide a spec file
• you do not want file-based outputs
• the environment cannot support the workflow you need

The process overhead is intentional, so it is a poor fit for throwaway tasks.

Does gepetto require codebase access?

Not always, but it helps. The skill can still work from a product-style requirements document. It becomes more valuable when it can research existing patterns and architecture in a real repo or project context.

What is the biggest adoption blocker?

Usually input quality and invocation format. Users often try to start gepetto as if it were a freeform chatbot. It is not. The skill expects a markdown spec path and a directory where planning files can be written.

Is gepetto mainly for Requirements Planning or implementation?

Its core strength is Requirements Planning that is close to implementation. It is not just product discovery, and it is not just code generation. It sits in the middle: turning requirements and constraints into a plan developers can execute with fewer surprises.

How to Improve gepetto skill

Start with a better spec, not a longer one

The best way to improve gepetto output is to improve the signal in the input spec. Add specifics, not padding. These details help most:

• current architecture
• affected systems
• expected scale
• security/compliance needs
• migration or rollout constraints
• failure modes you care about

A one-page concrete spec usually beats a five-page vague brief.

Feed gepetto the constraints it cannot infer

gepetto can ask clarifying questions, but it cannot reliably infer hidden business rules. State things like:

• “Must preserve backward compatibility for existing API clients”
• “Admin actions need audit logs retained for 1 year”
• “No new infrastructure vendors this quarter”
• “Feature must degrade gracefully when provider X is down”

These constraints sharply improve plan realism.

Give stronger answers during the interview step

The interview protocol is one of the highest-value parts of gepetto. Treat it seriously. Weak answers create generic plans; precise answers create execution-ready sections.

Less useful:

• “standard auth”
• “make it scalable”
• “just follow best practices”

More useful:

• “session invalidation must be immediate after password reset”
• “org admins can invite users, but only owners can change billing”
• “we expect 50k monthly active users within 6 months”

Review the plan for missing operational details

After the first gepetto pass, inspect whether the plan covers:

• monitoring and alerting
• rollback or migration strategy
• data model changes
• permissions and abuse cases
• test strategy
• deployment sequencing
• documentation updates

These are common blind spots when the initial prompt is feature-centric.

Use the section files as execution units

The sectioning system is one of the most practical parts of gepetto. To improve results, make sure sections are:

• named clearly
• dependency-aware
• sized for implementation, not just documentation
• parallelizable where possible

If a section blocks too many others or mixes unrelated concerns, split it before handing it to coding agents.

Adapt external review to your actual toolchain

The references assume external review via CLI tools. If your setup differs, keep the same review intent even if the mechanics change. The key is not the specific tool; it is getting independent criticism of the generated plan before implementation begins.

Common failure modes in gepetto usage

The most frequent issues are predictable:

• starting without a .md spec file
• giving only a slogan-level feature request
• skipping concrete answers in the interview phase
• treating the first plan draft as final
• ignoring section dependencies
• omitting repo-specific conventions

Most of these are fixable with better setup, not better model temperature.

How to iterate after the first gepetto output

A good second pass usually looks like this:

1. mark unclear or wrong assumptions in the plan
2. add missing business rules to the spec
3. rerun or resume gepetto
4. compare revised sections against implementation reality
5. only then convert sections into tickets or coding tasks

That loop is where the gepetto guide becomes genuinely useful: it reduces expensive ambiguity before build work starts.

Best way to get long-term value from gepetto

Do not use gepetto only for one-off ideation. Use it as a repeatable planning standard for medium-to-large features. Teams get the most value when they standardize:

• where specs live
• what minimum detail a spec must contain
• how review comments are folded back in
• how section files map to implementation work

That turns gepetto from a clever prompt into a dependable planning workflow.