Heyvhuang Ship Faster Workflow Project Intake

Project Intake (Brainstorm + Clarify + Route)

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)

1. Pass paths only, not content: agents/sub-agents only pass ..._path, let the executor read the file itself.
2. Files are first-class citizens: Every step must persist artifacts; failures can be retried; replayable; traceable.
3. 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.
4. 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.
5. 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.)

D) Constraints (Optional but Recommended)

• Launch timeline (if any)
• Risk preference (aggressive/conservative)
• Existing design constraints (brand colors/fonts/existing component library)

Run Directory Specification

Default (recommended): create in target project root: runs/<workflow>/active/<run_id>/

OpenSpec-compatible mode (when openspec/project.md exists, or user forces it via context.json):

• Active: openspec/changes/<change-id>/
• Archive: openspec/changes/archive/YYYY-MM-DD-<change-id>/

Backend selection rule (deterministic):

1. If context.json includes "artifact_store": "runs" or "openspec", follow it.
2. Else if openspec/project.md exists in repo_root, use OpenSpec mode.
3. Else use runs/.

Recommended structure (OpenSpec-style, low ceremony):

• proposal.md: User goal (original question + expected output + constraints + acceptance criteria + non-goals)
• tasks.md: Executable checklist (- [ ] → - [x]) + approval gates
• context.json: Key context (repo_root, need_* switches, risk preference, known IDs)
• evidence/ (optional): Evidence/analysis from each analyzer (keep big output out of chat)
• logs/ (optional):
  • events.jsonl: Structured event log (append one line per step)
  • state.json: Optional machine-readable state (what’s next / what’s complete)

Archive convention (after completion): move active/<run_id>/ → archive/YYYY-MM-DD-<run_id>/

Event Log Format (Recommended)

One JSON per line:

{"ts":"2026-01-11T12:00:00Z","step":"evidence","action":"cloudflare.query_worker_observability","status":"ok","artifacts":["evidence/observability.md"],"note":"p95 latency spike"}

Don't log sensitive content (token/email/phone/secret). Write redacted versions when necessary.

Checkpoint Protocol (Required for Write Operations)

Before executing write operations:

1. Write the approval plan into tasks.md under an Approvals section (object ID, impact scope, verification method)
2. Show same summary in conversation, wait for explicit user reply "confirm/yes/proceed"
3. Execute only after user confirms, write results to evidence/ (and optionally logs/events.jsonl)

Artifacts (This Skill Must Persist)

Before routing/execution, write clarification results to:

• proposal.md: Goals, scope, acceptance criteria, non-goals, timeline
• context.json: repo_root, entry_type, need_* switches, risk preference, etc.

If this Intake includes "design spec" phase (from workflow-brainstorm module), also persist:

• evidence/YYYY-MM-DD-<topic>-design.md: Confirmed design and key decisions (for downstream plan/implementation reference)

Notes:

• If file already exists: Only add missing fields / append information, don't blindly overwrite (avoid duplicate writes with downstream workflow)
• Goal is to let downstream workflow "start running directly" without another round of clarification

context.json (recommended minimal structure):

{
  "entry_type": "idea",
  "repo_root": "",
  "scope": "full",
  "artifact_store": "auto",
  "need_database": false,
  "need_billing": false,
  "need_auth": false,
  "need_deploy": false,
  "need_seo": false
}

Routing: Which Workflow / Skill to Choose (Default to Ship Faster)

Priority recommendations:

1. From idea/small prototype to launch (default): Use workflow-ship-faster

• workflow-ship-faster will persist to runs/ship-faster/active/<run_id>/ by default (or openspec/changes/<change-id>/ when OpenSpec mode is selected), and decide whether to execute DB/payment/deploy/SEO optional steps based on context.json switches
• Just style/design system: Use tool-design-style-selector
• Just one feature iteration (split+deliver): Use workflow-feature-shipper
• Just React/Next.js performance review (waterfalls/bundle/re-renders): Use review-react-best-practices
• Just DB-side actions (SQL/migration/logs/type generation): Use supabase skill
• Just Stripe-side operations (products/prices/payment links/refunds etc.): Use stripe skill

If unsure: Complete Intake Checklist first → Write proposal.md/context.json → Then route (don't execute big actions upfront).

Conversation Convergence at End (Required)

Before handing off control to downstream skill, end this skill with 3 paragraphs:

1. Restate understanding (goal + acceptance criteria + non-goals)
2. Clarify the route to take (default workflow-ship-faster, and explain why)
3. Ask user if they want to start execution now:
   • "Ready to start workflow-ship-faster? (Will write artifacts to runs/ship-faster/active/<run_id>/ 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/<task-name>/, 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.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.