@orderful/droid 0.25.2 → 0.27.0

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

@@ -0,0 +1,409 @@
+# Publishing to Codex
+
+**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.
+
+**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.
+
+## Procedure
+
+### 1. Validate Prerequisites
+
+```bash
+# Thought doc must exist and be active
+if [ ! -f "$thought_doc_path" ]; then
+  echo "Error: No active tech design found."
+  echo "Start one with: /tech-design start --from codex:{project}"
+  exit 1
+fi
+
+# Research doc should exist (not required but helpful)
+if [ ! -f "$research_doc_path" ]; then
+  echo "⚠️  Warning: Research doc not found."
+  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=$(grep '^codex_repo:' ~/.droid/skills/codex/overrides.yaml | cut -d' ' -f2-)
+if [ -z "$codex_repo" ]; then
+  echo "Error: Codex not configured."
+  echo "Set up with: /codex"
+  exit 1
+fi
+
+# Check git access
+if ! git -C "$codex_repo" status &>/dev/null; then
+  echo "Error: Can't access codex repo at: $codex_repo"
+  exit 1
+fi
+```
+
+### 2. Check Completeness
+
+Run gap analysis and warn if critical sections missing:
+
+```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
+# → transaction-templates
+
+project=$(basename "$(dirname "$thought_doc_path")")
+
+# Verify project exists in codex
+if [ ! -d "$codex_repo/projects/$project" ]; then
+  echo "⚠️  Project not found in codex: $project"
+  echo ""
+  echo "Options:"
+  echo "  1. Create it: /codex new $project"
+  echo "  2. Specify different project name"
+  echo ""
+  echo "Which project should this go to?"
+  # Get user input
+fi
+```
+
+### 4. Generate Roll-up
+
+**Read thought doc and synthesize into roll-up template:**
+
+```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 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:**
+
+```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"
+---
+```
+
+### 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**.
+
+## Documents
+
+- **TECH-DESIGN.md**: Clean, reviewable roll-up (start here)
+- **artifacts/thought-doc.md**: Full working document with exploration and context
+
+## Two-Document Approach
+
+The roll-up 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.
+
+Both are included for full transparency.
+
+## Review Guidance
+
+**For quick review:**
+- Read TECH-DESIGN.md only
+- Use GitHub's suggested reviewers
+
+**For deep review:**
+- Read TECH-DESIGN.md first
+- Reference thought-doc.md for context on decisions
+- Comment on either file as appropriate
+
+## Next Steps
+
+After approval:
+- [ ] Create implementation tickets
+- [ ] Add key decisions to DECISIONS.md
+- [ ] Begin implementation"
+
+# Use codex skill's git-finish-write script
+droid config codex | droid exec droid-codex git-finish-write \
+  --config - \
+  --message "$commit_msg" \
+  --pr-title "$pr_title" \
+  --pr-body "$pr_body"
+```
+
+### 8. Output Success
+
+```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"
+```
+
+## Roll-up Generation Details
+
+### TL;DR Synthesis
+
+**Extract key points:**
+
+1. What are we building? (1 sentence from Proposal)
+2. Why does it matter? (1 sentence from Background)
+3. Main approach? (1 sentence from Proposal)
+
+**Example:**
+
+```
+We're building reusable transaction templates that partners can customize for their specific EDI document types. This reduces setup time from weeks to minutes and enables self-service onboarding. Templates are versioned, validated, and managed through a new API.
+```
+
+### Problem Extraction
+
+**From Background, focus on:**
+
+- Current pain points
+- What's broken or missing
+- Impact if not solved
+
+**Strip out:**
+
+- Solution discussion (save for Solution section)
+- Historical context (save for artifacts if needed)
+- Excessive detail (roll-up is concise)
+
+### Solution Synthesis
+
+**From Proposal, assuming decisions accepted:**
+
+- Describe the approach
+- Reference existing patterns
+- Note key implementation details
+
+**Omit:**
+
+- Rejected alternatives (those go in Key Decisions as "(Rejected) Option B")
+- Detailed implementation steps (those go in Implementation Phases)
+- Exploratory questions (those stay in thought doc)
+
+### Key Decisions Formatting
+
+**Transform from thought doc format:**
+
+Thought doc might have:
+
+```markdown
+## Decision: Event vs Polling
+
+We need to decide how status updates propagate.
+
+**Option A: Events**
+
+- Pros: Low latency, multiple consumers, fits existing pattern
+- Cons: More complex, need exactly-once delivery
+
+**Option B: Polling**
+
+- Pros: Simpler, easier to debug
+- Cons: Higher latency, more database load
+
+**Recommendation:** Events, because we need <100ms latency and have multiple consumers.
+```
+
+Roll-up format:
+
+```markdown
+### Status Update Propagation
+
+**(Recommended) Option A: Event-Driven**
+Use @nestjs/event-emitter to publish `transaction.status.changed` events.
+
+- Pros: <100ms latency, supports multiple consumers (dashboard, webhooks, alerts), fits existing architecture
+- Cons: Need exactly-once delivery guarantees, more complex error handling
+
+**(Rejected) Option B: Polling**
+Services poll the database for status changes every 5 seconds.
+
+- Pros: Simpler implementation, easier debugging
+- Cons: 5-second latency unacceptable for dashboard, increased DB load
+```
+
+## Error Handling
+
+- **Thought doc not found:** Remind to run `/tech-design start` first
+- **Critical sections missing:** 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
+- **Roll-up generation fails:** Fallback to template with placeholders, note what needs manual editing
+
+## 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
+
+Before creating PR, verify roll-up:
+
+- [ ] TL;DR is 2-3 sentences, jargon-free
+- [ ] Problem is clear, focused on pain (not solution)
+- [ ] Scope has clear in/out boundaries
+- [ ] Solution assumes decisions accepted (no "maybe we'll...")
+- [ ] Each decision shows 2+ options with pros/cons
+- [ ] Recommended option clearly marked
+- [ ] Rejected options explain why rejected
+- [ ] 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 exploratory content (those stay in thought doc)
+
+If any fail, note in output and offer to refine before PR.

package/src/tools/tech-design/skills/tech-design/references/research-doc-template.md

@@ -0,0 +1,129 @@
+# Research Doc Template
+
+Used when creating research doc via `/brain research tech-design-{project}-research`.
+
+```markdown
+# Research: {Project Name}
+
+**Type:** research
+**Status:** exploring
+**Created:** {YYYY-MM-DD}
+**PRD:** [[codex:projects/{project}/PRD]]
+
+Research for tech design: {brief description}
+
+## Codex Context
+
+**From /codex project {name}:**
+
+### Problem Statement
+
+{What problem we're solving - from PRD}
+
+### Goals & Scope
+
+{What's in scope, what's out of scope}
+
+### Key Requirements
+
+{Critical requirements from PRD}
+
+### UI/UX Context (if applicable)
+
+{Product design considerations from DESIGN.md}
+
+## Codebase Discoveries
+
+### Existing Patterns
+
+{Architectural/design patterns discovered during exploration}
+
+- Pattern: {name}
+- Found in: {file paths}
+- How it works: {brief explanation}
+- Relevant for: {which part of the design}
+
+### Similar Implementations
+
+{Features that do similar things}
+
+- Feature: {name}
+- Location: {file paths}
+- What we can learn: {insights}
+
+### Integration Points
+
+{Where this feature will connect to existing code}
+
+- Module/Service: {name}
+- Location: {file path}
+- Integration approach: {how to connect}
+
+### Dependencies
+
+{Libraries, packages, services needed}
+
+- Dependency: {name}
+- Status: {already available / need to add}
+- Purpose: {why needed}
+- Version: {if specific version required}
+
+### Technical Stack Notes
+
+{Framework/technology-specific details discovered}
+
+**Architecture:**
+{e.g., layered, modular, microservices, monolith}
+
+**Patterns:**
+{e.g., dependency injection, event-driven, CQRS}
+
+**Data Access:**
+{e.g., ORM used, database type, schema patterns}
+
+**API Style:**
+{e.g., REST, GraphQL, gRPC}
+
+**Testing:**
+{e.g., test framework, patterns, coverage}
+
+**Deployment:**
+{e.g., CI/CD setup, environment config}
+
+## Key Findings
+
+{Summary of what matters most for the design}
+
+1. {Most important discovery}
+2. {Second most important}
+3. {Third most important}
+
+{Any blockers or critical decisions needed based on research}
+```
+
+## Variable Substitutions
+
+| Variable              | Example                                              | Notes                       |
+| --------------------- | ---------------------------------------------------- | --------------------------- |
+| `{Project Name}`      | "Transaction Templates"                              | Human-readable project name |
+| `{YYYY-MM-DD}`        | "2026-01-10"                                         | Current date                |
+| `{project}`           | "transaction-templates"                              | Codex project slug          |
+| `{brief description}` | "system for creating reusable transaction templates" | One-line summary            |
+
+## Purpose
+
+The research doc is the knowledge base for the tech design. It captures:
+
+- **Codex context**: What the PRD says we should build
+- **Codebase discoveries**: What patterns/infrastructure exist
+- **Technical specifics**: Stack/framework details (language, framework, libraries, etc.)
+
+This keeps the thought doc focused on design decisions rather than getting bogged down in discovered patterns. The thought doc references the research doc but doesn't duplicate it.
+
+## When to Update
+
+- **On `/tech-design start`**: Initial creation with codex context + codebase deep dive
+- **During `/tech-design draft`**: If additional patterns discovered, add to research doc
+- **During `/tech-design think`**: If exploration uncovers new relevant context
+
+The research doc is a living document throughout the design process.

package/src/tools/tech-design/skills/tech-design/references/rollup-template.md

@@ -0,0 +1,55 @@
+# [Tech Design] {Feature Name}
+
+## TL;DR
+
+{2-3 sentence summary}
+
+## Problem
+
+{What we're solving}
+
+## Scope
+
+**In:** {bullet list}
+**Out:** {bullet list}
+
+## Solution
+
+{What we're building - assumes accepted decisions}
+
+## Key Decisions
+
+### {Decision Topic}
+
+**(Recommended) Option A:** {Decision}
+{Description}
+
+- Pros: ...
+- Cons: ...
+
+**(Rejected) Option B:** {Decision}
+{Description}
+
+- Pros: ...
+- Cons: ...
+
+## Risks
+
+| Risk | Mitigation |
+| ---- | ---------- |
+
+## Rollout
+
+| Phase | What | Risk Mitigation |
+| ----- | ---- | --------------- |
+
+## Implementation Phases
+
+| Phase | Deliverable |
+| ----- | ----------- |
+
+## Approvals
+
+- [ ] Tech Lead
+- [ ] Product
+- [ ] Security (if applicable)