Add design-and-plan skill: interactive design → ticket + plan artifacts

[williamthorsen]

Problem

The current brainstorming → writing-plans pipeline produces hyper-prescriptive implementation plans that are counterproductive when the downstream executor is orchestrate-dev. The writing-plans skill prescribes commit messages, TDD step-by-step ceremony, and exact shell commands — details that:

1. Waste tokens three times — the planner writes them, the coder reads them, reviewers check against them
2. Shift the coder from engineering to transcription — a coder given exact code to type stops exercising judgment, reducing quality
3. Are most prescriptive where decisions are easiest (commit messages, test commands) and most vague where decisions are hardest (complex integration logic)
4. Conflict with the review pipeline — orchestrate-dev already has code review, silent-failure review, test review, and holistic review. Over-specifying the plan doesn't reduce review findings; it's pure overhead.

Meanwhile, the interactive Q&A session from the brainstorming skill is highly valuable for converging on requirements and approach. But brainstorming is hardcoded to flow into writing-plans — there is no path from interactive design exploration to a plan format suited for orchestrate-dev.

Context and considerations

The brainstorming → writing-plans coupling

brainstorming ends with: "The terminal state is invoking writing-plans. The ONLY skill you invoke after brainstorming is writing-plans." This means the interactive design value is locked behind a plan format designed for zero-context subagent executors, not for orchestrate-dev.

Decision timing

The prescriptive plan forces decisions (exact code, commit messages) to be made during planning, before the coder has seen the actual codebase state. Decisions made during implementation are better-informed — the coder has strictly more information than the planner. Prescribing too early produces plan-implementation mismatches that the coder must either follow (wrong) or deviate from (unauthorized).

The ticket as the contract

When the plan doesn't perfectly describe how to reach the goal (and it never does), the ticket's acceptance criteria are the source of truth. The coder should be able to deviate from the plan while still meeting the ticket's criteria. This requires a well-written ticket — which the current workflow doesn't produce.

The existing plan skill

The plan skill already has the right philosophy: "Focus on clarity and actionability. Keep the plan concise — detail belongs in implementation, not planning." But it's a formatting template, not a workflow.

Compatibility with refine-plan

For high-stakes work, the user runs refine-plan between planning and implementation. The plan artifact must be compatible with refine-plan (which takes a plan path + ticket source).

Solution

Create a design-and-plan skill that combines interactive design exploration with ticket refinement and implementation planning. The skill produces two artifacts:

1. Refined ticket — problem, context, solution, acceptance criteria
2. Implementation plan — task decomposition, file decisions, key interfaces, acceptance criteria per task. No commit messages, no shell commands, no TDD ceremony.

Workflow

Task source (GitHub issue, file, or description)
  → Phase 1: Explore context, ask clarifying questions (one at a time)
  → Phase 2: Converge on design (propose approaches only when non-obvious)
  → Phase 3: Refine the ticket (present for approval; offer to update GitHub issue)
  → Phase 4: Generate implementation plan (plan-style, not writing-plans-style)
  → Phase 5: Save both artifacts → STOP

The skill does not automatically invoke any downstream skill. The user decides when to run refine-plan and when to invoke orchestrate-dev.

Plan content guidelines

Include: task decomposition, file-level decisions, key interfaces/types that embody design decisions, acceptance criteria per task, risks and unknowns.

Exclude: commit messages, shell commands, TDD step-by-step, implementation code for straightforward logic. Include code only when it captures a design decision.

Draft skill

A draft SKILL.md has been written at packages/agents/content/skills/design-and-plan/SKILL.md. It should be reviewed and refined as part of implementation.

Acceptance criteria

• design-and-plan skill exists and is installable
• Interactive Q&A phase asks questions one at a time, supports multiple choice
• Does not force multiple approaches when the solution is obvious
• Produces a ticket artifact with problem, context, solution, acceptance criteria
• Offers to update GitHub issue when source is a GitHub URL
• Produces a plan artifact with tasks, files, key decisions, acceptance criteria — no commit messages or TDD ceremony
• Artifacts follow save-artifact naming conventions
• Plan artifact is compatible with refine-plan (accepted as plan path input)
• Skill terminates after saving artifacts — does not invoke downstream skills
• brainstorming and writing-plans remain unchanged (they serve other workflows)