Treat Skills as "stateless execution units", externalize all state to the file system.
This skill is positioned as
"project entry / requirements clarification"
:
When user only has a vague idea: help them clarify requirements (minimum information set) before entering execution chain
When user provides repo / clear objectives: quickly confirm understanding, then enter the correct workflow/step
This skill is
not responsible
for actual large-scale implementation (that's the job of execution skills like
workflow-ship-faster
/
workflow-feature-shipper
). It's responsible for converging "conversation" into "executable input", then handing off control.
Core Principles (Must Follow)
Pass paths only, not content
agents/sub-agents only pass
..._path
, let the executor read the file itself.
Files are first-class citizens
Every step must persist artifacts; failures can be retried; replayable; traceable.
Write operations must have checkpoints
Any action with external side effects (delete/modify cloud resources/DB writes/refunds/cancel subscriptions) must write a plan first and wait for explicit user confirmation.
Ask one question at a time
If information is missing, ask follow-ups, but each message asks only 1 question (prefer multiple choice); break complex topics into multiple rounds.
Hooks doctor (required check; non-blocking)
If running under Claude Code and you want the evolution loop active, run
tool-hooks-doctor
once early; if hooks are missing, offer to install project-level hooks (continue either way).
0) Brainstorm Module (Replaces Old Approach)
When user input is still "idea/direction/vague requirement", first use
workflow-brainstorm
module to refine it into an executable design, then enter Intake Checklist.
workflow-brainstorm
module requirements:
Check project context first (if repo exists)
Ask only 1 question at a time (prefer multiple choice)
Provide 2-3 options with trade-offs explained
Output design in segments (~200-300 words each), ask "Does this look good?" at the end of each segment
Minimum Information Set to Produce (Intake Checklist)
Converge user input into the following information (ask for what's missing; if user already provided it, don't ask again).
Questioning Protocol (Required):
Each message asks
1 question
only
Prefer multiple choice; use open questions only when necessary
Ask direction-determining questions first (success criteria/non-goals/constraints), then implementation details
A) Entry Type
entry_type
:
idea
|
prototype
If
prototype
:
repo_root
(local path or repo link)
B) Success Criteria (Required)
The "one core loop" user wants to implement first (one sentence)
Acceptance criteria (3-5 items)
Clear non-goals (1-3 items)
C) Ship Faster Key Switches (Must Clarify)
need_database
Whether database is needed (default Supabase)
need_billing
Whether billing/payment is needed (default Stripe)
need_auth
Whether authentication is needed (default: false)
need_deploy
Whether deployment to production is needed (default GitHub + Vercel)
need_seo
Whether SEO is needed (sitemap/robots/llms.txt etc.)
in your project by default, and require confirmation before critical write operations)"
Parallel Execution (Subagent)
When any of these situations occur, split into parallel subtasks:
Need to scan by directory/module
Need to review by dimension (naming/functions/duplication/...)
Need to generate multiple alternatives (Plan A/B/C)
Parallel subtask conventions:
Input: Only receive paths (
proposal_path
,
context_path
,
output_dir
)
Output: Write artifacts to
evidence/parallel//
, return list of artifact paths
Resume from Checkpoint
When running again:
Read
tasks.md
first; use
logs/state.json
only if it exists and you need machine state
Don't repeat completed steps; only fill in missing artifacts or continue from failure point
Deliverables (Minimum Requirements)
tasks.md
Checklist reflects reality + execution summary + next steps
Optional:
logs/events.jsonl
for traceability
After completion, do a
skill-evolution
Evolution checkpoint
(3 questions); if user chooses "want to optimize", call
skill-improver
to review this run and propose minimal patch suggestions.