tp-design

High-Level Design

Create or revise the high-level design for a TDD project through conversation with the user.

Argument: {design-name} (required) — kebab-case name, becomes the directory under three-pillars-docs/tp-designs/.

Steps

1. Run first-run preflight per skills/_shared/first-run.md.

2. Resolve the design directory: three-pillars-docs/tp-designs/{design-name}/. Create it if it doesn't exist.

3. Run collaboration preflight per skills/_shared/collaboration.md with phase: "design". This verifies the branch and acquires or refreshes the lock for this design. Honor --force-takeover if passed.

   Seat-context note: if the collaboration preflight notes that you are on the base branch ({base} / master), treat that as an affirmation — being on {base} in the resolved seat (the base checkout / worktree host) is the correct coordination point for spinning up a new design worktree. It is not a reason to pause or seek an alternative checkout. See skills/_shared/topology.md for the canonical seat and worktree layout; the collaboration preflight's branch check is seat-aware — in the seat it offers worktree provisioning (provision-and-instruct), never an in-place checkout.

2b. Update .claude/last-design MRU — now that the lock/branch are claimed, run the MRU snippet at the bottom of skills/_shared/validate-name.md (the bash that prepends the design name, dedupes, caps at 10). This is the moment a subsequent /clear + /tp-session-restore (no argument) needs to resolve to this design, not whatever was active before. The snippet handles the .gitignore append; do not git add the file. 2c. Repo-map preamble (optional) per skills/_shared/repo-map-preamble.md. If aider is on PATH, generate a structural map of the codebase to inform the design conversation; if absent, skip silently and proceed. 3. Read project context per skills/_shared/read-project-docs.md. Read three-pillars-docs/vision.md first — every question you ask in the design conversation should be framed against the vision's Problem, Users, Principles, and Non-goals. If three-pillars-docs/vision.md is missing, tell the user and recommend /tp-setup but don't block. If the roadmap has a ## Current Focus table, note where this new design fits relative to current priorities — mention this during the design conversation so the user can decide its priority. 4. Check for existing design.md. If it exists, read it and ask the user whether they want to revise it or start fresh. If starting fresh, warn that downstream artifacts (detailed-design.md, plan.md) will become stale. 5. Vision alignment check. Before the main design conversation, explicitly ask: "How does this design advance the problem or principles stated in three-pillars-docs/vision.md?" Write the user's answer as the seed for the Problem section of design.md. If the answer is weak or the design obviously touches a stated non-goal, surface that tension now — it is much cheaper to reject or reshape a design at this stage than to fight it through detailed-design and audit later. If three-pillars-docs/vision.md doesn't exist, skip this step but note it. 5b. Declare the weight class. Read weight-class from the frontmatter of three-pillars-docs/tp-designs/{design-name}/seed.md if the seed exists and carries one. If absent, ask the user once, rubric-assisted: score the four axes (risk, blast radius, reversibility, novelty — each low/medium/high) and run python3 "$TP_ROOT"/skills/_shared/weight_class.py recommend --risk … --blast-radius … --reversibility … --novelty … for the recommendation, then let the user confirm or override. Protocol reference: skills/_shared/weight-class.md. The declared class is stamped onto design.md in step 7 and propagates to every artifact generated downstream.