design-harvest

Design Harvest

The on-ramp. Three modes.

Mode 1: harvest (/mddesign:harvest)

Goal: produce a structurally valid DESIGN.md at project root from the existing codebase.

Step 1: Pre-flight

• Glob for DESIGN.md at project root.
• If it exists and the user did NOT pass --overwrite, refuse: print "DESIGN.md already exists. Use /mddesign:critique instead, or pass --overwrite to replace."
• Confirm npx is available (bash -c "command -v npx").

Step 2: Dispatch the design-archeologist subagent

Call the Agent tool with subagent_type: design-archeologist and a prompt containing this PhaseSpec:

phase_id: harvest-<short-uuid>
parent_plan_ref: ./task_plan.md
goal: Extract de-facto design tokens from this codebase and return a draft DESIGN.md body following the Google Labs spec.
done_when:
  - draft_design_md is non-empty
  - draft_design_md contains YAML frontmatter and 8 ordered markdown sections
  - draft_design_md includes a section #9 "Agent Prompt Guide"
inputs:
  files: []  # the subagent globs the project itself
tools_allowed: ["Read", "Glob", "Grep", "Bash"]
tools_denied: ["Write", "Edit", "WebFetch"]
budget:
  max_tool_calls: 200
  max_wall_seconds: 600
hitl_checkpoints:
  - before_returning_draft
return_contract:
  format: markdown+frontmatter
  fields: [summary, draft_design_md, open_questions]

The subagent has its own dedicated SKILL/agent definition at agents/design-archeologist.md.

Step 3: Receive the draft, write to DESIGN.md

• Take the draft_design_md field from the subagent's return.
• Write it to <project_root>/DESIGN.md. This write goes through the PreToolUse HITL gate (named checkpoint: before_design_md_write).

Step 4: Lint and iterate

Run:

npx --yes @google/design.md lint DESIGN.md

If exit code is 0, you are done.

If non-zero, capture the linter output. Re-dispatch design-archeologist with an additional input field lint_errors: <output> and instruction "fix every reported error and return a new draft." Loop up to 3 times. After 3 failed iterations, surface the final lint errors to the user and stop.