@orderful/droid 0.37.0 → 0.38.0

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

@@ -2,7 +2,7 @@
 
 **Trigger:** `/tech-design publish` or user wants to create PR for review
 
-**Goal:** Generate clean roll-up from thought doc, publish thought doc + roll-up to codex. Research doc stays in brain.
+**Goal:** Generate rollup and publish to codex. Draft = skip completeness checks + GitHub draft PR. Ready = run completeness checks + regular PR. Files published are always the same.
 
 **Security Note:** Project names and all user input must be validated/sanitized before use in file paths, git commands, or PR content to prevent command injection and path traversal.
 
@@ -15,16 +15,17 @@
 if [ ! -f "$thought_doc_path" ]; then
   echo "Error: No active tech design found."
   echo "Start one with: /tech-design start --from codex:{project}"
+  echo "Or resume with: /tech-design search {term}"
   exit 1
 fi
 
-# Research doc should exist (not required but helpful)
+# Research doc should exist (optional but helpful)
 if [ ! -f "$research_doc_path" ]; then
-  echo "⚠️  Warning: Research doc not found."
+  echo "⚠️  Warning: Research doc not found in same folder."
   echo "This is unusual - research doc is typically created during /tech-design start"
 fi
 
-# Codex repo must be configured (read from codex skill config)
+# Codex repo must be configured
 codex_repo=$(droid config --get tools.codex | grep -o '"codex_repo": *"[^"]*"' | cut -d'"' -f4)
 if [ -z "$codex_repo" ]; then
   echo "Error: Codex not configured."
@@ -39,35 +40,17 @@ if ! git -C "$codex_repo" status &>/dev/null; then
 fi
 ```
 
-### 2. Check Completeness
-
-Run gap analysis and warn if critical sections missing:
+### 2. Extract Project Name
 
 ```bash
-# Check critical sections
-missing_critical=$(check_critical_sections "$thought_doc_path")
-
-if [ -n "$missing_critical" ]; then
-  echo "⚠️  Warning: Critical sections are missing:"
-  echo "$missing_critical"
-  echo ""
-  echo "You can publish anyway, but reviewers may ask for these."
-  echo ""
-  echo "Continue publishing? (y/n)"
-  # Get user confirmation
-fi
-```
-
-### 3. Extract Project Name
-
-```bash
-# Get project name from thought doc path or metadata
-# e.g., {brain_dir}/1-Projects/transaction-templates/tech-design-transaction-templates.md
+# Get project name from design folder
+# e.g., {brain_dir}/0-Inbox/tech-designs/transaction-templates/
 # → transaction-templates
 
-project=$(basename "$(dirname "$thought_doc_path")")
+design_folder=$(dirname "$thought_doc_path")
+project=$(basename "$design_folder")
 
-# Verify project exists in codex
+# Verify project exists in codex or offer to create
 if [ ! -d "$codex_repo/projects/$project" ]; then
   echo "⚠️  Project not found in codex: $project"
   echo ""
@@ -76,138 +59,198 @@ if [ ! -d "$codex_repo/projects/$project" ]; then
   echo "  2. Specify different project name"
   echo ""
   echo "Which project should this go to?"
-  # Get user input
+  # Get user input for project name
 fi
 ```
 
-### 4. Generate Roll-up
+### 3. Determine Publish Type and Check for Existing PR
 
-**Read thought doc and synthesize into roll-up template:**
+Check if this is first publish or update:
 
 ```bash
-# Read template
-rollup_template=$(cat references/rollup-template.md)
-
-# Extract content from thought doc
-background=$(extract_section "$thought_doc_path" "Background")
-proposal=$(extract_section "$thought_doc_path" "Proposal")
-scope=$(extract_section "$thought_doc_path" "Scope")
-decisions=$(extract_section "$thought_doc_path" "Key Decisions")
-risks=$(extract_section "$thought_doc_path" "Risks")
-rollout=$(extract_section "$thought_doc_path" "Rollout")
-implementation=$(extract_section "$thought_doc_path" "Implementation")
-
-# Generate TL;DR (2-3 sentence summary)
-# Use AI to synthesize from Background + Proposal
-tldr=$(generate_tldr "$background" "$proposal")
-
-# Generate Problem statement
-# Extract from Background, focus on "what's broken/missing"
-problem=$(extract_problem "$background")
-
-# Generate Solution
-# From Proposal, assuming decisions are accepted
-solution=$(synthesize_solution "$proposal" "$decisions")
-
-# Populate template
-rollup=$(echo "$rollup_template" | \
-  sed "s/{Feature Name}/$project/g" | \
-  sed "s/{2-3 sentence summary}/$tldr/g" | \
-  sed "s/{What we're solving}/$problem/g")
-# ... continue for all sections
-```
-
-**Roll-up generation guidelines:**
-
-- **TL;DR**: Concise, jargon-free, answers "what and why"
-- **Problem**: Focus on current pain, not solution
-- **Scope**: Clear in/out boundaries
-- **Solution**: Assumes recommended decisions accepted, omits rejected alternatives
-- **Key Decisions**: Show options with pros/cons, mark recommended vs rejected
-- **Risks**: Table format, each risk with mitigation
-- **Rollout**: Phases with risk mitigation per phase
-- **Implementation**: High-level phases, not detailed tasks
-
-### 5. Create Git Branch
-
-Use codex git scripts for safety:
-
-```bash
-# Use codex skill's git-start-write script
-droid config --get tools.codex | droid exec droid-codex git-start-write \
-  --config - \
-  --branch "codex/tech-design-$project"
-```
-
-### 6. Write Files to Codex
-
-```bash
-# Write roll-up
-rollup_path="$codex_repo/projects/$project/TECH-DESIGN.md"
-echo "$rollup" > "$rollup_path"
-
-# Write thought doc to artifacts
-artifacts_dir="$codex_repo/projects/$project/artifacts"
-mkdir -p "$artifacts_dir"
-cp "$thought_doc_path" "$artifacts_dir/thought-doc.md"
-
-# Update frontmatter in both files
-add_frontmatter "$rollup_path" "tech-design" "$project"
-add_frontmatter "$artifacts_dir/thought-doc.md" "tech-design-thought" "$project"
-```
-
-**Frontmatter for roll-up:**
-
-```yaml
----
-title: "[Tech Design] $project"
-type: tech-design
-status: draft
-created: $(date +%Y-%m-%d)
-updated: $(date +%Y-%m-%d)
-confidence: medium
----
-```
-
-**Frontmatter for thought doc:**
+# Check if project folder exists in codex
+project_exists=false
+if [ -d "$codex_repo/projects/$project" ]; then
+  project_exists=true
+fi
 
-```yaml
----
-title: "[Tech Design Thought Doc] $project"
-type: tech-design-thought
-status: draft
-created: $(date +%Y-%m-%d)
-updated: $(date +%Y-%m-%d)
-confidence: medium
-note: "Working document with full context, exploration, and @mentions"
----
+# Check for existing PR
+existing_pr=$(gh pr list --repo "$codex_repo" --head "tech-design/$project" --json number --jq '.[0].number')
+pr_is_draft=false
+if [ -n "$existing_pr" ]; then
+  pr_is_draft=$(gh pr view "$existing_pr" --repo "$codex_repo" --json isDraft --jq '.isDraft')
+fi
 ```
 
-### 7. Create PR
-
-```bash
-# Commit message
-commit_msg="Add tech design for $project
-
-Roll-up: projects/$project/TECH-DESIGN.md
-Thought doc: projects/$project/artifacts/thought-doc.md"
-
-# PR title
-pr_title="Tech Design: $project"
-
-# PR body
-pr_body="## Summary
-
-Technical design for **$project**.
+**First publish (no existing project/PR):**
+- Ask: "Draft (WIP for early feedback) or Ready (complete design for review)?"
+- Proceed to step 4
+
+**Update existing PR:**
+- Show current PR status (draft or ready)
+- Ask: "Keep as [current status] or change to [other status]?"
+- Proceed to step 4
+- Will regenerate rollup and update all files
+
+### 4. Unified Publish Workflow
+
+**This workflow is the same for both draft and ready publish. The only differences are:**
+- Draft: Skip completeness checks
+- Ready: Run completeness checks (warn if issues, allow proceed)
+- PR status: Draft PR vs regular PR
+
+**Steps:**
+
+1. **Completeness checks (Ready only):**
+
+   If publishing as "Ready", check critical sections in thought doc:
+
+   ```bash
+   # Check critical sections in thought doc
+   missing_critical=$(check_critical_sections "$thought_doc_path")
+
+   if [ -n "$missing_critical" ]; then
+     echo "⚠️  Warning: Critical sections are missing or empty:"
+     echo "$missing_critical"
+     echo ""
+     echo "Common missing sections:"
+     echo "  - Background / Problem statement"
+     echo "  - Proposal / Solution"
+     echo "  - Key Decisions"
+     echo "  - Risks & Mitigations"
+     echo ""
+     echo "Continue publishing anyway? (y/n)"
+     # Get user confirmation
+   fi
+   ```
+
+   If publishing as "Draft", skip this step entirely.
+
+2. **Ask about research doc:**
+   ```
+   Include research doc in tech-design/ folder? (helps reviewers/LLMs understand context)
+   - Yes: Copy research.md
+   - No: Only rollup and thought-doc
+   ```
+
+3. **Generate rollup from thought-doc:**
+
+   Read the template from `references/rollup-template.md` and populate it by extracting sections from thought-doc.md.
+
+   ```bash
+   # Read the canonical template structure
+   rollup_template=$(cat references/rollup-template.md)
+
+   # Extract sections from thought doc
+   background=$(extract_section "$thought_doc_path" "Background")
+   proposal=$(extract_section "$thought_doc_path" "Proposal")
+   scope=$(extract_section "$thought_doc_path" "Scope")
+   decisions=$(extract_section "$thought_doc_path" "Key Decisions")
+   risks=$(extract_section "$thought_doc_path" "Risks")
+   rollout=$(extract_section "$thought_doc_path" "Rollout")
+   implementation=$(extract_section "$thought_doc_path" "Implementation")
+   ```
+
+   **Rollup generation logic:**
+
+   - **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
+     - 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
+
+   See "Roll-up Generation Details" below for detailed examples.
+
+4. **Copy files to codex:**
+   ```bash
+   # Write rollup
+   rollup_path="$codex_repo/projects/$project/TECH-DESIGN.md"
+   echo "$rollup_content" > "$rollup_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"
+
+   if [ "$include_research" = "yes" ]; then
+     cp "$research_doc_path" "$codex_repo/projects/$project/tech-design/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/"
+   done
+   ```
+
+5. **Add frontmatter:**
+
+   **Rollup frontmatter:**
+   ```yaml
+   ---
+   title: "[Tech Design] $project"
+   type: tech-design
+   status: $(if draft: "draft", if ready: "ready")
+   created: $(date +%Y-%m-%d)
+   updated: $(date +%Y-%m-%d)
+   confidence: medium
+   ---
+   ```
+
+   **Thought doc frontmatter:**
+   ```yaml
+   ---
+   title: "[Tech Design - Working Doc] $project"
+   type: tech-design-working
+   status: $(if draft: "draft", if ready: "ready")
+   created: $(date +%Y-%m-%d)
+   updated: $(date +%Y-%m-%d)
+   note: $(if draft: "Work-in-progress", if ready: "Full working document with context and exploration")
+   ---
+   ```
+
+6. **Create or update branch and PR:**
+
+   **If first publish (no existing PR):**
+   ```bash
+   cd "$codex_repo"
+   git checkout -b "tech-design/$project"
+   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")
+   "
+
+   git push -u origin "tech-design/$project"
+
+   # Create PR (draft or regular based on user choice)
+   gh pr create \
+     $(if draft: "--draft") \
+     --title "$(if draft: "[Draft] ")Tech Design: $project" \
+     --body "$(cat <<'EOF'
+## Summary
+
+$(if draft: "🚧 **Work-in-progress** - sharing for early feedback." else: "Technical design for **$project**.")
 
 ## Documents
 
-- **TECH-DESIGN.md**: Clean, reviewable roll-up (start here)
-- **artifacts/thought-doc.md**: Full working document with exploration and context
+- **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")
 
 ## Two-Document Approach
 
-The roll-up synthesizes the thought doc into a clean, decision-focused format for reviewers.
+The rollup (TECH-DESIGN.md) synthesizes the thought doc into a clean, decision-focused format for reviewers.
 
 The thought doc contains the full exploration, research findings, @mentions, and working notes.
 
@@ -217,44 +260,77 @@ Both are included for full transparency.
 
 **For quick review:**
 - Read TECH-DESIGN.md only
-- Use GitHub's suggested reviewers
+- Comment on high-level approach and decisions
 
 **For deep review:**
 - Read TECH-DESIGN.md first
 - Reference thought-doc.md for context on decisions
-- Comment on either file as appropriate
+- Check research.md to understand codebase discoveries
 
 ## Next Steps
 
 After approval:
 - [ ] Create implementation tickets
 - [ ] Add key decisions to DECISIONS.md
-- [ ] Begin implementation"
-
-# Use codex skill's git-finish-write script with needs-review label
-droid config --get tools.codex | droid exec droid-codex git-finish-write \
-  --config - \
-  --message "$commit_msg" \
-  --pr-title "$pr_title" \
-  --pr-body "$pr_body" \
-  --labels "needs-review"
-```
+- [ ] Begin implementation
 
-### 8. Output Success
+---
+
+🤖 Created with [droid](https://github.com/Orderful/droid)
+EOF
+   )"
+   ```
+
+   **If updating existing PR:**
+   ```bash
+   # Update files
+   git add "projects/$project"
+   git commit -m "Update tech design for $project
+
+   Regenerated rollup and updated working files."
+   git push
+
+   # If changing draft status
+   if [ "$change_status" = "yes" ]; then
+     if [ "$new_status" = "ready" ]; then
+       gh pr ready "$existing_pr"
+       gh pr edit "$existing_pr" --title "Tech Design: $project"
+     else
+       # GitHub doesn't support marking ready → draft via CLI
+       echo "⚠️  To mark PR as draft, do it manually in GitHub UI"
+     fi
+   fi
+   ```
+
+7. **Output:**
+   ```
+   ✓ Tech design published!
+
+   PR $(if new: "created" else: "updated"): {pr_url}
+   $(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)")
+
+   Next steps:
+     • $(if draft: "Share PR with teammates for early feedback" else: "Share PR with reviewers")
+     • Continue iterating in brain folder: {design_folder}
+     • Run /tech-design publish again to update PR with latest changes
+     • $(if draft: "When ready: change publish type to 'Ready' to mark PR ready for formal review")
+   ```
+
+### 6. Never Delete Brain Files
+
+**CRITICAL:** Brain folder is the working copy. Codex is the published copy.
 
 ```bash
-echo "✓ Tech design published!"
-echo ""
-echo "PR created: $pr_url"
-echo ""
-echo "Files in PR:"
-echo "  • projects/$project/TECH-DESIGN.md (reviewable roll-up)"
-echo "  • projects/$project/artifacts/thought-doc.md (full working doc)"
-echo ""
-echo "Next steps:"
-echo "  • Share PR with reviewers"
-echo "  • Address feedback with: /tech-design respond \"question\""
-echo "  • After approval: /codex decision to capture key decisions"
+# NEVER do this:
+# rm -rf "$design_folder"
+
+# Brain files stay untouched after publish
+# User can continue iterating and republish
 ```
 
 ## Roll-up Generation Details
@@ -285,7 +361,7 @@ We're building reusable transaction templates that partners can customize for th
 
 - Solution discussion (save for Solution section)
 - Historical context (save for artifacts if needed)
-- Excessive detail (roll-up is concise)
+- Excessive detail (rollup is concise)
 
 ### Solution Synthesis
 
@@ -345,54 +421,17 @@ Services poll the database for status changes every 5 seconds.
 
 ## Error Handling
 
-- **Thought doc not found:** Remind to run `/tech-design start` first
-- **Critical sections missing:** Warn, get confirmation to proceed
+- **Thought doc not found:** Remind to run `/tech-design start` or `/tech-design search` first
+- **Critical sections missing (ready only):** Warn, get confirmation to proceed
 - **Project not in codex:** Offer to create or specify different project
-- **Git operations fail:** Use codex skill's error handling (auto-recover)
-- **PR creation fails:** Show error, suggest manual PR creation
+- **Git operations fail:** Show error, leave partial state with clear error message for manual fix
+- **PR creation fails:** Show error, provide git commands for manual PR creation
 - **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."
 
-## Example Output
-
-```
-Analyzing thought doc...
-✓ All critical sections present
-✓ Project exists in codex: transaction-templates
-
-Generating roll-up...
-✓ Synthesized TL;DR from Background + Proposal
-✓ Extracted Problem statement
-✓ Synthesized Solution (assuming recommended decisions)
-✓ Formatted 3 Key Decisions with recommendations
-✓ Generated Risk mitigation table
-✓ Formatted 3-phase rollout plan
-
-Writing to codex...
-✓ Created: projects/transaction-templates/TECH-DESIGN.md
-✓ Created: projects/transaction-templates/artifacts/thought-doc.md
-
-Creating PR...
-✓ Branch: codex/tech-design-transaction-templates
-✓ Commit: Add tech design for transaction-templates
-✓ PR: {git_repo_link}/pull/42
-
-✓ Tech design published!
-
-PR created: {git_repo_link}/pull/42
-
-Files in PR:
-  • projects/transaction-templates/TECH-DESIGN.md (reviewable roll-up)
-  • projects/transaction-templates/artifacts/thought-doc.md (full working doc)
-
-Next steps:
-  • Share PR with reviewers
-  • Address feedback (v2 feature: /tech-design respond)
-  • After approval: /codex decision to capture key decisions
-```
-
-## Roll-up Quality Checklist
+## Roll-up Quality Checklist (Ready Publish Only)
 
-Before creating PR, verify roll-up:
+Before creating PR, verify rollup:
 
 - [ ] TL;DR is 2-3 sentences, jargon-free
 - [ ] Problem is clear, focused on pain (not solution)
@@ -404,7 +443,24 @@ Before creating PR, verify roll-up:
 - [ ] Risks have concrete mitigations (not just "monitor closely")
 - [ ] Rollout has phases with specific risk mitigation per phase
 - [ ] Implementation phases are high-level milestones, not tasks
-- [ ] No @mentions in roll-up (those stay in thought doc)
+- [ ] No @droid/@user mentions in rollup (those stay in thought doc)
 - [ ] No exploratory content (those stay in thought doc)
 
 If any fail, note in output and offer to refine before PR.
+
+## Directory Structure Summary
+
+**Published structure (same for both draft and ready):**
+```
+projects/{name}/
+├── TECH-DESIGN.md         (rollup - always generated)
+└── tech-design/
+    ├── thought-doc.md     (full working document)
+    └── research.md        (optional - if user chose to include)
+```
+
+**Key points:**
+- Rollup is always generated (it's a build artifact 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.)