@orderful/droid 0.38.0 → 0.39.1

package/dist/tools/status-update/skills/status-update/references/formatting.md

@@ -0,0 +1,203 @@
+# Formatting Reference
+
+Detailed formatting rules for status updates.
+
+## Status Emoji
+
+| Status | Emoji | Display Text |
+|--------|-------|--------------|
+| `on_track` | `:large_green_circle:` | On track |
+| `at_risk` | `:large_yellow_circle:` | At risk |
+| `blocked` | `:red_circle:` | Blocked |
+
+## Phase Checklist
+
+### Phases in Order
+
+1. `discovery` - Research and requirements gathering
+2. `post_discovery_feedback` - Incorporating discovery feedback
+3. `design` - Prototype and design work
+4. `post_design_feedback` - Incorporating design feedback
+5. `prd` - Writing PRD
+6. `tech_design` - Writing Tech Design
+7. `development` - Active implementation
+8. `qa` - QA & Testing
+9. `release` - Released to production
+
+### Phase Emoji
+
+| State | Emoji |
+|-------|-------|
+| completed | `:check:` |
+| current | `:work-in-progress-sign:` |
+| upcoming | `:waiting-to-start:` |
+
+### Collapsed Groups
+
+When all phases in a group are completed or upcoming (not current), collapse them:
+
+| Group | Phases | Collapsed Name |
+|-------|--------|----------------|
+| 1 | discovery, post_discovery_feedback | "Discovery & Post-Discovery Feedback" |
+| 2 | design, post_design_feedback | "Prototype, Design & Post-Design Feedback" |
+| 3 | prd, tech_design | "PRD & Tech Design" |
+| 4 | development | "Development" |
+| 5 | qa, release | "QA → Release" |
+
+### Display Rules
+
+1. **Completed phases** - Collapse into groups, show with `:check:`
+2. **Current phase** - Show on its own line with `:work-in-progress-sign:` and **bold**
+3. **Upcoming phases** - Collapse into chain with `→`, show with `:waiting-to-start:`
+
+### Examples
+
+**Current = `development`:**
+```
+*Where we're at*
+:check: Discovery & Post-Discovery Feedback
+:check: Prototype, Design & Post-Design Feedback
+:check: PRD & Tech Design
+:work-in-progress-sign: *Development*
+:waiting-to-start: QA → Release
+```
+
+**Current = `prd`:**
+```
+*Where we're at*
+:check: Discovery & Post-Discovery Feedback
+:check: Prototype, Design & Post-Design Feedback
+:work-in-progress-sign: *PRD*
+:waiting-to-start: Tech Design → Development → QA → Release
+```
+
+**Current = `post_discovery_feedback`:**
+```
+*Where we're at*
+:check: Discovery
+:work-in-progress-sign: *Post-Discovery Feedback*
+:waiting-to-start: Prototype, Design & Post-Design Feedback → PRD & Tech Design → Development → QA → Release
+```
+
+**Current = `design`:**
+```
+*Where we're at*
+:check: Discovery & Post-Discovery Feedback
+:work-in-progress-sign: *Prototype/Design*
+:waiting-to-start: Post-Design Feedback → PRD & Tech Design → Development → QA → Release
+```
+
+## Links Footer
+
+Only include links that are configured in project metadata:
+
+```
+:link: <{prd_url}|PRD> · <{tech_design_url}|Tech Design> · <{figma_url}|Figma>
+```
+
+Omit any link that isn't set. If no links configured, omit the entire footer.
+
+## Full Message Template
+
+```
+*Status:* {status_emoji} *{status_text}*
+
+*Where we're at*
+{phase_checklist}
+
+*In flight this week*
+• {bullet 1}
+• {bullet 2}
+
+*Up next*
+• {bullet 1}
+• {bullet 2}
+
+{links_footer}
+
+Posted with help from :droid:{ & :codex: if used}
+```
+
+## Crosspost Template (Summary Version)
+
+```
+*{project_title}*
+
+{status_line}
+{current_phase_only - e.g., ":work-in-progress-sign: *Development*"}
+
+{in_flight_section}
+
+:link: <{message_url}|View full update>
+```
+
+## Example Full Output
+
+**Example 1: Development phase, on track**
+```
+*Status:* :large_green_circle: *On track*
+
+*Where we're at*
+:check: Discovery & Post-Discovery Feedback
+:check: Prototype, Design & Post-Design Feedback
+:check: PRD & Tech Design
+:work-in-progress-sign: *Development*
+:waiting-to-start: QA → Release
+
+*In flight this week*
+• Implementing scenario template API
+• Adding copy endpoint for templates
+
+*Up next*
+• Fan-out orchestration design
+• Integration tests
+
+:link: <url|PRD> · <url|Tech Design> · <url|Figma>
+
+Posted with help from :droid: & :codex:
+```
+
+**Example 2: PRD phase, at risk**
+```
+*Status:* :large_yellow_circle: *At risk*
+
+*Where we're at*
+:check: Discovery & Post-Discovery Feedback
+:check: Prototype, Design & Post-Design Feedback
+:work-in-progress-sign: *PRD*
+:waiting-to-start: Tech Design → Development → QA → Release
+
+*In flight this week*
+• Finalising requirements with stakeholders
+• Waiting on legal review for data handling
+
+*Up next*
+• Tech design kickoff
+
+:link: <url|PRD>
+
+Posted with help from :droid: & :codex:
+```
+
+**Example 3: No Slack, printed to terminal**
+```
+Status: On track
+
+Where we're at
+✓ Discovery & Post-Discovery Feedback
+✓ Prototype, Design & Post-Design Feedback
+→ Development
+○ QA → Release
+
+In flight this week
+• Building the feature
+• Writing tests
+
+Up next
+• Code review
+• QA handoff
+
+---
+Tip: To post this to Slack, add slack.channel to your project's CONTEXT.md
+and set SLACK_USER_TOKEN in your environment.
+```

package/dist/tools/tech-design/skills/tech-design/SKILL.md

@@ -47,15 +47,16 @@ Tech-design has no configuration of its own. It delegates to:
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
-## Three-Document Approach
+## Four-Document Approach
 
-| Document        | Created When | Purpose                                         | Location                                         | Audience    |
-| --------------- | ------------ | ----------------------------------------------- | ------------------------------------------------ | ----------- |
-| **Research**    | `/start`     | Deep dive: codex project + codebase discoveries | `{brain_dir}/{inbox?}/tech-designs/{name}/`      | Author + AI |
-| **Thought doc** | `/start`     | Design iteration: decisions, @mentions, drafts  | `{brain_dir}/{inbox?}/tech-designs/{name}/`      | Author + AI |
-| **Roll-up**     | `/publish`   | Clean summary: decisions only, reviewable       | `{codex_repo}/projects/{name}/TECH-DESIGN.md`    | Reviewers   |
+| Document        | Created When | Purpose                                                  | Location                                         | Audience       | Length  |
+| --------------- | ------------ | -------------------------------------------------------- | ------------------------------------------------ | -------------- | ------- |
+| **Research**    | `/start`     | Deep dive: codex project + codebase discoveries          | `{brain_dir}/{inbox?}/tech-designs/{name}/`      | Author + AI    | Varies  |
+| **Thought doc** | `/start`     | Design iteration: decisions, @mentions, drafts           | `{brain_dir}/{inbox?}/tech-designs/{name}/`      | Author + AI    | ~2500L  |
+| **Summary**     | `/publish`   | Condensed presentation doc: problem/solution/key points  | `{codex_repo}/projects/{name}/SUMMARY.md`        | Presentations  | ~235L   |
+| **Tech Design** | `/publish`   | Complete technical design: all decisions/details         | `{codex_repo}/projects/{name}/TECH-DESIGN.md`    | Reviewers      | ~1000L  |
 
-**Why three documents?**
+**Why four documents?**
 
 1. **Research doc** = Persistent memory of codebase exploration
    - Project-specific patterns discovered
@@ -84,9 +85,20 @@ Tech-design has no configuration of its own. It delegates to:
    - Decision-focused, no exploration noise
    - Ready for PR review
 
-**Philosophy:** Research captures "what exists", thought doc explores "what we'll build", roll-up communicates "what we decided".
+3. **Summary** = Presentation artifact
+   - Condensed overview (~235 lines vs ~1000 for full design)
+   - Problem, solution, key decisions, timeline, metrics
+   - Links to full tech design for details
+   - For executives, presentations, status updates
 
-Both thought doc and roll-up are published to codex. Research doc stays in brain as project-specific knowledge base.
+4. **Tech Design** = Complete technical specification
+   - Full details, all sections, complete specifications
+   - Decision rationales with options considered
+   - Ready for implementation
+
+**Philosophy:** Research captures "what exists", thought doc explores "what we'll build", summary presents "the highlights", tech design specifies "what we decided in full".
+
+Summary, tech design, and thought doc are published to codex. Research doc stays in brain as project-specific knowledge base.
 
 ## Commands
 
@@ -181,6 +193,27 @@ Commands are explicit entry points, but most usage will be natural conversation.
 
 **Full procedure:** See `references/publish.md` for draft/ready workflows, roll-up generation, git workflow, and examples.
 
+## Writing Style
+
+**Follow discussions closely** - When iterating on content with the user, follow the conversation tightly. Don't inflate or add more than discussed. If the user agrees to add something, write that specific thing. If unsure whether to add more detail, write less and let the user prompt for more.
+
+**Minimal code snippets** - Avoid solutioning in tech designs. The rollup should focus on:
+- **What** needs to be built (requirements, data structures, flows)
+- **Why** design decisions were made (rationale, tradeoffs)
+- **NOT How** to implement it (code examples, specific function names, implementation details)
+
+Code snippets should be replaced with:
+- Schema definitions (data structures only)
+- Flow diagrams (conceptual, not code)
+- Prose descriptions of behaviour
+- Decision rationales
+
+This prevents confusion and allows engineers implementation flexibility.
+
+**Example from user feedback:**
+
+> "I want very minimal code snippet to avoid solutioning in the tech design and should focus on what needs to be built, requirements and structures. The design decisions that were made. And so we to avoid showing implementation. This also leaves the implementor the person that's going to implement whatever is being decided here. Give them the freedom to choose how they want to implement it."
+
 ## Active Doc Tracking
 
 Leverage brain's active doc tracking:
@@ -206,7 +239,11 @@ Leverage brain's active doc tracking:
 
 Use `/gaps` to surface what's missing. Don't overwhelm at the start.
 
-**Roll-up:** Clean summary for reviewers - decisions only, no exploration noise.
+**Thought doc can contain code for clarity** during design discussions, but these should be removed when generating the summary and tech design.
+
+**Summary:** Presentation-ready highlights (~235 lines) - problem, solution, key decisions, timeline. Links to full design for details.
+
+**Tech Design:** Complete specification (~1000 lines) - all decisions, rationales, specifications. Minimal/no code snippets.
 
 ## Related Skills
 

package/dist/tools/tech-design/skills/tech-design/references/draft.md

@@ -6,6 +6,14 @@
 
 **Security Note:** All user-provided inputs must be validated before use in shell commands. File paths and search patterns should be sanitized to prevent command injection.
 
+## Writing Style for Drafting
+
+**Conciseness over completeness** - When drafting, err on the side of writing less rather than more. It's easier for the user to ask "can you expand on X?" than to trim down over-written content.
+
+**Minimal code snippets** - In the thought doc, code snippets are acceptable for design discussion clarity. However, remind yourself that these will need to be removed or replaced with schema definitions / flow diagrams / prose when generating the summary and tech design.
+
+**Follow the discussion** - If the user asks you to draft a section, draft that section based on research doc findings. Don't add adjacent sections or expand scope beyond what was requested.
+
 ## Procedure
 
 ### 1. Determine Scope

package/dist/tools/tech-design/skills/tech-design/references/publish.md

@@ -99,6 +99,28 @@ fi
 - Ready: Run completeness checks (warn if issues, allow proceed)
 - PR status: Draft PR vs regular PR
 
+**CRITICAL - Git Branch Safety:**
+
+Before ANY git operations, you MUST ensure you are on the correct branch. **Never assume the local branch is correct** — the user may have been reviewing other tech designs, PRs, or doing other work that left them on a different branch.
+
+```bash
+cd "$codex_repo"
+
+if [ -n "$existing_pr" ]; then
+  # Updating existing PR — checkout its branch
+  pr_branch=$(gh pr view "$existing_pr" --repo "$codex_repo" --json headRefName --jq '.headRefName')
+  git fetch origin "$pr_branch"
+  git checkout "$pr_branch"
+  git pull origin "$pr_branch"
+else
+  # First publish — create branch from default branch
+  default_branch=$(git remote show origin | grep 'HEAD branch' | awk '{print $NF}')
+  git checkout "$default_branch"
+  git pull origin "$default_branch"
+  git checkout -b "tech-design/$project"
+fi
+```
+
 **Steps:**
 
 1. **Completeness checks (Ready only):**
@@ -130,10 +152,30 @@ fi
    ```
    Include research doc in tech-design/ folder? (helps reviewers/LLMs understand context)
    - Yes: Copy research.md
-   - No: Only rollup and thought-doc
+   - No: Only summary, tech design, and thought-doc
    ```
 
-3. **Generate rollup from thought-doc:**
+3. **Generate summary from thought-doc:**
+
+   Read the template from `references/summary-template.md` and populate it by synthesizing key points from thought-doc.md.
+
+   **Summary generation logic (~235 lines target):**
+
+   - **Quick Overview**: 2-3 sentences at top
+   - **The Problem**: 2-3 paragraphs from Background - current pain, impact, who's affected
+   - **The Solution**: Core concept (1-2 paragraphs), simple flow diagram, key components (3-5 bullet points)
+   - **Scope**: In/Out with checkmarks (✅/❌)
+   - **Key Design Decisions**: Top 3-5 decisions with brief rationale (not full options/pros/cons)
+   - **Implementation Timeline**: Brief phase overview with status
+   - **Success Metrics**: MVP criteria + long-term impact
+   - **Risks & Mitigations**: Table format
+   - **For More Details**: Links to TECH-DESIGN.md and artifacts
+
+   **Target length**: ~235 lines (presentation-ready)
+
+   See "Summary Generation Details" below for detailed examples.
+
+4. **Generate tech design from thought-doc:**
 
    Read the template from `references/rollup-template.md` and populate it by extracting sections from thought-doc.md.
 
@@ -151,46 +193,62 @@ fi
    implementation=$(extract_section "$thought_doc_path" "Implementation")
    ```
 
-   **Rollup generation logic:**
+   **Tech design generation logic (~1000 lines target):**
 
    - **TL;DR**: Synthesize 2-3 sentences from Background + Proposal
    - **Problem**: Extract from Background, focus on current pain
    - **Solution**: From Proposal, assuming recommended decisions accepted
    - **Scope**: Extract Scope section or infer from Proposal
    - **Key Decisions**: Transform from thought doc format:
-     - Show options with pros/cons
+     - Show ALL options with full pros/cons
      - Mark recommended vs rejected
      - Format: `(Recommended) Option A:` and `(Rejected) Option B:`
    - **Risks**: Extract Risks section, ensure mitigations present
    - **Rollout**: Extract Rollout section, phases with risk mitigation
    - **Implementation**: High-level phases from Implementation section
-   - **Preserve visual elements**: Mermaid diagrams, tables, code blocks from sections should be included in rollup
+   - **Minimal code snippets**: Remove or replace code with schema definitions, flow diagrams, prose
+   - **Preserve visual elements**: Mermaid diagrams, tables (non-code) from sections
 
-   See "Roll-up Generation Details" below for detailed examples.
+   See "Tech Design Generation Details" below for detailed examples.
 
-4. **Copy files to codex:**
+5. **Copy files to codex:**
    ```bash
-   # Write rollup
-   rollup_path="$codex_repo/projects/$project/TECH-DESIGN.md"
-   echo "$rollup_content" > "$rollup_path"
+   # Write summary
+   summary_path="$codex_repo/projects/$project/SUMMARY.md"
+   echo "$summary_content" > "$summary_path"
+
+   # Write tech design
+   tech_design_path="$codex_repo/projects/$project/TECH-DESIGN.md"
+   echo "$tech_design_content" > "$tech_design_path"
 
-   # Create/update tech-design folder
-   mkdir -p "$codex_repo/projects/$project/tech-design"
-   cp "$thought_doc_path" "$codex_repo/projects/$project/tech-design/thought-doc.md"
+   # Create/update artifacts folder
+   mkdir -p "$codex_repo/projects/$project/artifacts"
+   cp "$thought_doc_path" "$codex_repo/projects/$project/artifacts/thought-doc.md"
 
    if [ "$include_research" = "yes" ]; then
-     cp "$research_doc_path" "$codex_repo/projects/$project/tech-design/research.md"
+     cp "$research_doc_path" "$codex_repo/projects/$project/artifacts/research.md"
    fi
 
    # Copy diagrams and additional files
    for file in "$design_folder"/*.{png,jpg,svg,pdf} 2>/dev/null; do
-     [ -f "$file" ] && cp "$file" "$codex_repo/projects/$project/tech-design/"
+     [ -f "$file" ] && cp "$file" "$codex_repo/projects/$project/artifacts/"
    done
    ```
 
-5. **Add frontmatter:**
+6. **Add frontmatter:**
 
-   **Rollup frontmatter:**
+   **Summary frontmatter:**
+   ```yaml
+   ---
+   title: "[Summary] $project"
+   type: artifact
+   status: $(if draft: "draft", if ready: "ready")
+   created: $(date +%Y-%m-%d)
+   updated: $(date +%Y-%m-%d)
+   ---
+   ```
+
+   **Tech design frontmatter:**
    ```yaml
    ---
    title: "[Tech Design] $project"
@@ -205,8 +263,8 @@ fi
    **Thought doc frontmatter:**
    ```yaml
    ---
-   title: "[Tech Design - Working Doc] $project"
-   type: tech-design-working
+   title: "[Thought Doc] $project"
+   type: artifact
    status: $(if draft: "draft", if ready: "ready")
    created: $(date +%Y-%m-%d)
    updated: $(date +%Y-%m-%d)
@@ -214,21 +272,31 @@ fi
    ---
    ```
 
-6. **Create or update branch and PR:**
+7. **Confirm branch before push:**
+
+   ```bash
+   current_branch=$(git rev-parse --abbrev-ref HEAD)
+   echo "About to push to branch: $current_branch"
+   echo "Is this correct? (y/n)"
+   # Wait for user confirmation
+   # If no, abort with clear message
+   ```
+
+8. **Create or update branch and PR:**
 
    **If first publish (no existing PR):**
    ```bash
-   cd "$codex_repo"
-   git checkout -b "tech-design/$project"
+   # Branch already created in step 4
    git add "projects/$project"
    git commit -m "$(if draft: "Draft tech design" else "Tech design") for $project
 
    $(if draft: "Sharing work-in-progress for early feedback." else: "Complete technical design ready for review.")
 
    Files:
-   - TECH-DESIGN.md - Clean rollup for reviewers
-   - tech-design/thought-doc.md - Full working document
-   $([ "$include_research" = "yes" ] && echo "- tech-design/research.md - Context and research")
+   - SUMMARY.md - Presentation-ready highlights (~235 lines)
+   - TECH-DESIGN.md - Complete technical design (~1000 lines)
+   - artifacts/thought-doc.md - Full working document (~2500 lines)
+   $([ "$include_research" = "yes" ] && echo "- artifacts/research.md - Context and research")
    "
 
    git push -u origin "tech-design/$project"
@@ -244,28 +312,37 @@ $(if draft: "🚧 **Work-in-progress** - sharing for early feedback." else: "Tec
 
 ## Documents
 
-- **TECH-DESIGN.md**: Clean, reviewable rollup (start here)
-- **tech-design/thought-doc.md**: Full working document with exploration and context
-$([ "$include_research" = "yes" ] && echo "- **tech-design/research.md**: Codebase discoveries and research")
+- **SUMMARY.md**: Presentation-ready highlights (~235 lines) - problem, solution, key decisions, timeline
+- **TECH-DESIGN.md**: Complete technical design (~1000 lines) - full details for implementors
+- **artifacts/thought-doc.md**: Working document (~2500 lines) - exploration, @mentions, iteration
+$([ "$include_research" = "yes" ] && echo "- **artifacts/research.md**: Codebase discoveries and research")
+
+## Four-Document Approach
 
-## Two-Document Approach
+The summary provides presentation-ready highlights for executives and status updates.
 
-The rollup (TECH-DESIGN.md) synthesizes the thought doc into a clean, decision-focused format for reviewers.
+The tech design is the complete specification synthesized from the thought doc - all decisions, rationales, details.
 
 The thought doc contains the full exploration, research findings, @mentions, and working notes.
 
-Both are included for full transparency.
+All documents are included for full transparency.
 
 ## Review Guidance
 
+**For presentations / status updates:**
+- Read SUMMARY.md only (~235 lines)
+- Enough context for executive discussions
+
 **For quick review:**
-- Read TECH-DESIGN.md only
+- Read SUMMARY.md for overview
+- Read TECH-DESIGN.md for complete details (~1000 lines)
 - Comment on high-level approach and decisions
 
 **For deep review:**
-- Read TECH-DESIGN.md first
-- Reference thought-doc.md for context on decisions
-- Check research.md to understand codebase discoveries
+- Start with SUMMARY.md
+- Read TECH-DESIGN.md fully
+- Reference artifacts/thought-doc.md for context on decisions
+- Check artifacts/research.md to understand codebase discoveries
 
 ## Next Steps
 
@@ -302,7 +379,7 @@ EOF
    fi
    ```
 
-7. **Output:**
+9. **Output:**
    ```
    ✓ Tech design published!
 
@@ -310,9 +387,10 @@ EOF
    $(if changed_to_ready: "✓ Marked PR as ready for review")
 
    Files in PR:
-     • projects/$project/TECH-DESIGN.md (reviewable rollup)
-     • projects/$project/tech-design/thought-doc.md (full working doc)
-   $([ "$include_research" = "yes" ] && echo "  • projects/$project/tech-design/research.md (context and research)")
+     • projects/$project/SUMMARY.md (presentation highlights ~235 lines)
+     • projects/$project/TECH-DESIGN.md (complete design ~1000 lines)
+     • projects/$project/artifacts/thought-doc.md (working document ~2500 lines)
+   $([ "$include_research" = "yes" ] && echo "  • projects/$project/artifacts/research.md (context and research)")
 
    Next steps:
      • $(if draft: "Share PR with teammates for early feedback" else: "Share PR with reviewers")
@@ -321,7 +399,7 @@ EOF
      • $(if draft: "When ready: change publish type to 'Ready' to mark PR ready for formal review")
    ```
 
-### 6. Never Delete Brain Files
+### 10. Never Delete Brain Files
 
 **CRITICAL:** Brain folder is the working copy. Codex is the published copy.
 
@@ -333,7 +411,35 @@ EOF
 # User can continue iterating and republish
 ```
 
-## Roll-up Generation Details
+## Summary Generation Details
+
+**Target:** ~235 lines, presentation-ready
+
+**Template:** `references/summary-template.md`
+
+**Key sections:**
+
+1. **Quick Overview**: 2-3 sentences at very top
+2. **The Problem**: 2-3 paragraphs - current pain, impact, who's affected
+3. **The Solution**: Core concept (1-2 paragraphs), simple flow, 3-5 key components
+4. **Scope**: In/Out lists with ✅/❌
+5. **Key Design Decisions**: Top 3-5 decisions with brief "Why:" rationale (not full pros/cons)
+6. **Implementation Timeline**: Brief phase overview with status
+7. **Success Metrics**: MVP criteria + long-term impact
+8. **Risks & Mitigations**: Table format
+9. **For More Details**: Links to TECH-DESIGN.md and artifacts
+
+**Condensation strategy:**
+- Extract highlights, not everything
+- Focus on business value and decisions made
+- Remove technical implementation details
+- Link to full design for complete specs
+
+## Tech Design Generation Details
+
+**Target:** ~1000 lines, complete specification
+
+**Template:** `references/rollup-template.md`
 
 ### TL;DR Synthesis
 
@@ -429,9 +535,18 @@ Services poll the database for status changes every 5 seconds.
 - **Roll-up generation fails:** Fallback to template with placeholders, note what needs manual editing
 - **No changes to commit:** "No changes detected. Update files in brain folder first."
 
-## Roll-up Quality Checklist (Ready Publish Only)
+## Quality Checklist (Ready Publish Only)
+
+Before creating PR, verify summary and tech design:
+
+**Summary (~235 lines):**
+- [ ] Quick Overview is 2-3 sentences, business-focused
+- [ ] Problem section is 2-3 paragraphs (not pages)
+- [ ] Solution has simple flow diagram
+- [ ] Key Decisions shows top 3-5 only with brief rationale
+- [ ] Links to TECH-DESIGN.md for full details
 
-Before creating PR, verify rollup:
+**Tech Design (~1000 lines):**
 
 - [ ] TL;DR is 2-3 sentences, jargon-free
 - [ ] Problem is clear, focused on pain (not solution)
@@ -453,14 +568,15 @@ If any fail, note in output and offer to refine before PR.
 **Published structure (same for both draft and ready):**
 ```
 projects/{name}/
-├── TECH-DESIGN.md         (rollup - always generated)
-└── tech-design/
-    ├── thought-doc.md     (full working document)
+├── SUMMARY.md             (presentation highlights ~235 lines - always generated)
+├── TECH-DESIGN.md         (complete design ~1000 lines - always generated)
+└── artifacts/
+    ├── thought-doc.md     (working document ~2500 lines)
     └── research.md        (optional - if user chose to include)
 ```
 
 **Key points:**
-- Rollup is always generated (it's a build artifact from thought-doc)
+- Summary and tech design are always generated (build artifacts from thought-doc)
 - Draft vs Ready is indicated by GitHub PR status only
 - File structure is consistent regardless of draft/ready status
-- `artifacts/` folder is separate and not managed by tech-design (used for transcripts, meeting notes, etc.)
+- artifacts/ contains working documents and supporting materials