@orderful/droid 0.25.2 → 0.27.0

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

@@ -0,0 +1,353 @@
+# Starting a Tech Design
+
+**Trigger:** `/tech-design start --from codex:{project}` or user wants to start a new tech design
+
+**Goal:** Create research doc + thought doc via brain skill. Deep dive into codex project and codebase, persist discoveries.
+
+**Security Note:** All user-provided inputs (project names, section names, etc.) must be validated/sanitized before use in shell commands or file paths. Strip special characters and validate against expected patterns to prevent command injection and path traversal attacks.
+
+## Procedure
+
+### 1. Validate Prerequisites
+
+Check that required tools are configured:
+
+- **Brain skill:** Check if `~/.droid/skills/brain/overrides.yaml` exists
+- **Codex skill:** Check if `~/.droid/skills/codex/overrides.yaml` exists
+
+If prerequisites fail, guide user to configure:
+
+- Brain missing: "Please set up brain first by running `/brain`"
+- Codex missing: "Please set up codex first by running `/codex`"
+
+### 2. Load Codex Project Context
+
+Use the codex skill to load project context:
+
+```
+/codex project {projectName}
+```
+
+The codex skill will:
+
+- Find the project in the codex repository
+- Load PRD.md, DESIGN.md, and other project files
+- Return project context (or error if not found)
+
+**If project not found:**
+
+- Codex will warn: "⚠️ No project found for '{project}' in codex."
+- Offer options:
+  1. Create it with: `/codex new {project}`
+  2. Start fresh without codex context
+- Get user confirmation to continue
+
+**If project found:**
+
+- Extract key context for research doc:
+  - Problem statement (from PRD)
+  - Goals and scope
+  - UI/UX considerations (from DESIGN.md if present)
+  - Key constraints or requirements
+
+### 3. Create Research Doc via Brain Skill
+
+Use the brain skill to create a research document:
+
+```
+/brain research tech-design-{project}-research
+```
+
+**Research doc template:**
+
+```markdown
+# Research: {Project Name}
+
+**Type:** research
+**Status:** exploring
+**Created:** {current date}
+**PRD:** [[codex:projects/{project}/PRD]]
+
+Research for tech design: {brief description from PRD}
+
+## Codex Context
+
+{2-3 paragraph summary from step 2:}
+
+- Problem statement
+- Goals and scope
+- Key requirements
+- UI/UX considerations (if applicable)
+
+## Codebase Discoveries
+
+{This section populated in step 4}
+
+## Key Findings
+
+{Summary - populated after research complete}
+```
+
+### 4. Deep Dive into Codebase
+
+Explore code repositories to discover patterns, similar features, integration points, and dependencies.
+
+**Note:** The specific repositories to search should be discovered from the project context or user's workspace. Common patterns to look for:
+
+- **Existing similar features:**
+  - Search for related functionality
+  - Note file paths and patterns used
+- **Integration points:**
+  - Where will this feature connect to existing code?
+  - What modules/services will it interact with?
+- **Dependencies:**
+  - What libraries/packages are relevant?
+  - What's already available in the codebase?
+- **Technical patterns:**
+  - Architecture patterns (service layer, controllers, etc.)
+  - Data access patterns
+  - API patterns
+  - Testing patterns
+
+**Populate research doc with findings:**
+
+Update the "Codebase Discoveries" section with specific discoveries:
+
+```markdown
+## Codebase Discoveries
+
+### Existing Patterns
+
+- Pattern: {Description}
+- Found in: {file paths}
+- How it works: {brief explanation}
+
+### Similar Implementations
+
+- Feature: {Similar feature name}
+- Location: {file paths}
+- Relevant parts: {what to learn from it}
+
+### Integration Points
+
+- Module/Service: {name}
+- Location: {file path}
+- How to integrate: {approach}
+
+### Dependencies
+
+- Library: {name} - {already available / need to add}
+- Purpose: {why needed}
+
+### Technical Stack Notes
+
+{Framework-specific observations discovered during exploration}
+
+- Architecture: {e.g., layered, modular, microservices}
+- Patterns: {e.g., dependency injection, event-driven}
+- Testing: {e.g., unit test setup, integration test patterns}
+```
+
+### 5. Create Thought Doc via Brain Skill
+
+Use the brain skill to create the planning document:
+
+```
+/brain plan tech-design-{project}
+```
+
+**Thought doc template:**
+
+```markdown
+# [Tech Design] {Project Name}
+
+**Type:** plan
+**Status:** exploring
+**Created:** {current date}
+**PRD:** [[codex:projects/{project}/PRD]]
+**Research:** [[tech-design-{project}-research]]
+
+Tech design for {project}.
+
+## Background
+
+{2-3 paragraphs from PRD context:}
+
+- What problem we're solving
+- Who it's for and why it matters
+- Key constraints or requirements
+
+See research doc for codebase context and discovered patterns.
+
+## Proposal
+
+{What we're building - to be drafted}
+
+## Open Questions
+
+{What we don't know yet - to be explored}
+```
+
+Set thought doc as active in brain's session tracking.
+
+### 6. Provide Links to User
+
+After creating both docs, give the user the file paths:
+
+```
+✓ Research doc created: {full_path_to_research_doc}
+✓ Tech design created: {full_path_to_thought_doc}
+
+Research doc includes:
+  • Codex project context from {project}
+  • Codebase discoveries: {count} patterns found, {count} integration points identified
+  • Technical stack notes
+
+You can continue working on this with:
+  • /tech-design draft - Auto-generate sections from research
+  • /tech-design think {topic} - Explore specific ideas
+  • /brain add {text} - Quick additions to active doc
+  • /brain or /scratchpad - Work on either doc directly
+
+What would you like to do next?
+```
+
+## Error Handling
+
+- **Brain not configured:** "Brain skill not configured. Please run `/brain` to set up your brain directory first."
+- **Codex not configured:** "Codex skill not configured. Please run `/codex` to set up your codex repository first."
+- **PRD missing:** Offer to create via `/codex new {project}` or continue without context
+- **Docs already exist:** "Tech design docs for '{project}' already exist. Open existing or create new?"
+- **Codebase exploration fails:** Gracefully note what couldn't be found, continue with what's available
+
+## Example Output
+
+```
+✓ Loaded PRD context from codex:transaction-templates
+✓ Deep diving into codebase...
+
+Research findings:
+  📁 Found 3 similar patterns for template handling
+  🔗 Identified 5 integration points (validation, storage, API)
+  📦 Dependencies: 2 already available, 1 to add
+
+✓ Research doc created: {brain_dir}/0-Inbox/research/tech-design-transaction-templates-research.md
+✓ Tech design created: {brain_dir}/0-Inbox/plans/tech-design-transaction-templates.md
+
+Research doc includes:
+  • Codex project context from transaction-templates
+  • Codebase discoveries: 3 patterns found, 5 integration points identified
+  • Technical stack notes
+
+You can continue working on this with:
+  • /tech-design draft - Auto-generate sections from research
+  • /tech-design think {topic} - Explore specific ideas
+  • /brain add {text} - Quick additions to active doc
+  • /brain or /scratchpad - Work on either doc directly
+
+What would you like to do next?
+```
+
+The codex skill will:
+
+- Find the project in the codex repository
+- Load PRD.md, DESIGN.md, and other project files
+- Return project context (or error if not found)
+
+**If project not found:**
+
+- Codex will warn: "⚠️ No project found for '{project}' in codex."
+- Offer options:
+  1. Create it with: `/codex new {project}`
+  2. Start fresh without codex context
+- Get user confirmation to continue
+
+**If project found:**
+
+- Extract key context from the codex response:
+  - Problem statement (from PRD)
+  - Goals and scope
+  - UI/UX considerations (from DESIGN.md if present)
+  - Key constraints or requirements
+
+Create a concise summary (2-3 paragraphs) for the Background section.
+
+### 3. Create Thought Doc via Brain Skill
+
+Use the brain skill to create the planning doc. This ensures the doc goes to the user's configured brain location.
+
+**Template content to create:**
+
+```markdown
+# [Tech Design] {Feature Name}
+
+**Type:** plan
+**Status:** exploring
+**Created:** {current date YYYY-MM-DD}
+**PRD:** [[codex:projects/{project}/PRD]]
+
+Tech design for {project}.
+
+## Background
+
+{Insert PRD/DESIGN summary from step 3, or leave empty if no context}
+
+## Proposal
+
+{What we're building}
+
+## Open Questions
+
+{What we don't know yet}
+```
+
+**How to create via brain:**
+
+- Use the brain skill's document creation logic (reads `brain_dir` and `inbox_folder` from brain's config)
+- Create in the plans/ subfolder
+- Filename: `tech-design-{project}.md`
+- Populate Background section with codex context summary from step 2
+- Set as active doc in brain's session tracking
+
+### 4. Provide Link to User
+
+After creating the doc, give the user the file path:
+
+```
+✓ Tech design created: {full_path_to_doc}
+
+{If PRD context was loaded:}
+Background section populated with PRD context from codex:{project}
+
+You can continue working on this with:
+  • /tech-design draft - Auto-generate full doc from codebase research
+  • /tech-design think {topic} - Explore specific sections or ideas
+  • /brain add {text} - Quick additions to active doc
+  • /brain or /scratchpad - Work on it directly
+
+What would you like to do next?
+```
+
+## Error Handling
+
+- **Brain not configured:** "Brain skill not configured. Please run `/brain` to set up your brain directory first."
+- **Codex not configured:** "Codex skill not configured. Please run `/codex` to set up your codex repository first."
+- **PRD missing:** Offer to create via `/codex new {project}` or continue without context
+- **Thought doc already exists:** "A tech design for '{project}' already exists at {path}. Open existing or create new?"
+
+## Example Output
+
+```
+✓ Loaded PRD context from codex:transaction-templates
+✓ Tech design created: {brain_dir}/0-Inbox/plans/tech-design-transaction-templates.md
+
+Background section populated with PRD context from codex:transaction-templates
+
+You can continue working on this with:
+  • /tech-design draft - Auto-generate full doc from codebase research
+  • /tech-design think {topic} - Explore specific sections or ideas
+  • /brain add {text} - Quick additions to active doc
+  • /brain or /scratchpad - Work on it directly
+
+What would you like to do next?
+```

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

@@ -0,0 +1,356 @@
+# Thinking Through Ideas
+
+**Trigger:** `/tech-design think [topic]` or user wants to explore an idea
+
+**Goal:** Explore, stress-test, decide. Think before drafting. Often flows: think → decide → draft.
+
+## Think vs Draft
+
+| Mode      | Purpose                                               | Output                                         |
+| --------- | ----------------------------------------------------- | ---------------------------------------------- |
+| **Think** | Explore an idea, stress-test it, decide if it belongs | Discussion, possibly @{user} comment for later |
+| **Draft** | Write content into the doc (whole doc or section)     | Updates thought doc directly                   |
+
+## Procedure
+
+### 1. Determine Mode
+
+```bash
+if [ -n "$topic" ]; then
+  # Directed or freeform based on topic type
+  if is_section_name "$topic"; then
+    mode="directed"  # e.g., "rollout", "API design"
+  else
+    mode="freeform"  # e.g., "Should we use events or polling?"
+  fi
+else
+  # No args - scan for empty sections
+  mode="scan"
+fi
+```
+
+### 2. Scan Mode (No Args)
+
+**Scan thought doc for empty sections:**
+
+```bash
+# Read thought doc
+# Identify sections with no content (just headers)
+# Pick the first important empty section
+
+echo "I see these sections are empty:"
+echo "  • Data Model"
+echo "  • Rollout Plan"
+echo "  • Security Considerations"
+echo ""
+echo "Want to walk through Data Model? We can explore:"
+echo "  • What tables/schemas you need"
+echo "  • Relationships between entities"
+echo "  • Migration strategy"
+```
+
+### 3. Directed Mode (Topic is a Section)
+
+**Questions focused on that section:**
+
+#### Rollout
+
+- Phased or big bang?
+- Feature flags? Which service?
+- What's the rollback strategy?
+- How do we know it's working? (metrics)
+- What's the blast radius if it fails?
+
+```
+Let's think through the rollout plan.
+
+❓ Phased rollout or all at once?
+   Context: {Impact from PRD - who/what is affected}
+
+❓ Feature flags?
+   {Check research doc for feature flag setup discovered}
+   Should we add a flag for this feature?
+
+❓ Rollback strategy?
+   If things go wrong, how quickly can we revert?
+
+❓ Monitoring?
+   What metrics tell us it's healthy vs broken?
+```
+
+#### Data Model
+
+- What tables do we need?
+- What are the relationships?
+- How does this relate to existing schema?
+- Migration strategy? (backfill needed?)
+- Indexing considerations?
+
+```
+Let's design the data model.
+
+❓ What entities do we need?
+   Based on the PRD, I'm thinking:
+   - {Entity 1}
+   - {Entity 2}
+   - {Entity 3}
+
+❓ Relationships?
+   {Entity} (1) → (many) {Related}?
+   Or keep it simple with just one table?
+
+❓ Existing schema?
+   {Check research doc for existing tables/entities discovered}
+   How does this relate to what's already there?
+
+❓ Indexes?
+   What queries will be hot? What lookups are critical?
+```
+
+#### API Surface
+
+- Who calls this API?
+- What data do they need?
+- Rate limiting concerns?
+- Versioning strategy?
+- Error responses?
+
+```
+Let's think through the API design.
+
+❓ Who's calling this?
+   Internal services? External clients? Both?
+
+❓ What data do they actually need?
+   The PRD mentions {feature} - what specifically?
+
+❓ Rate limits?
+   {Check research doc for rate limiting patterns discovered}
+   What's appropriate for this endpoint?
+
+❓ Versioning?
+   /v1/{resource} or /{resource}?
+   Room to evolve later?
+```
+
+#### Security
+
+- Input validation?
+- Authentication? Authorization?
+- Data sensitivity?
+- Audit logging?
+- Rate limiting / DoS protection?
+
+```
+Let's think through security.
+
+❓ Input validation?
+   User-provided {data} - what's the attack surface?
+   SQL injection? Script injection? File upload risks?
+
+❓ Who can access/modify this?
+   Just internal admins? End users too?
+   What's the authorization model?
+
+❓ Sensitive data?
+   {Check research doc for auth/security patterns discovered}
+   Does this contain PII, credentials, or business-critical data?
+   Encryption needed?
+
+❓ Audit trail?
+   Should we log who created/modified/accessed this?
+```
+
+### 4. Freeform Mode (Open-Ended Question)
+
+**Stress-test the specific idea:**
+
+Example: "Should we use events or polling for status updates?"
+
+```
+Let's explore: events vs polling for status updates
+
+❓ What triggers the status update?
+   Is it a state change in the system?
+   Or external webhook?
+
+❓ What data needs to be in the event?
+   Just "status changed" or full state snapshot?
+
+❓ Who consumes these updates?
+   One service? Multiple? External partners?
+
+❓ Failure modes?
+   If event delivery fails, what happens?
+   Can we replay? Do we need exactly-once delivery?
+
+❓ Performance?
+   How many status updates/sec do we expect?
+   Is polling's latency acceptable?
+
+❓ Existing patterns?
+   {Check research doc for event/messaging patterns discovered}
+   Would this fit those patterns?
+
+Based on your answers:
+  ✓ Events: If low-latency, many consumers, or triggering workflows
+  ✓ Polling: If simpler, external consumers, or status changes infrequent
+```
+
+### 5. Capture Exploration
+
+**After exploration, ask where to put it:**
+
+```
+Good discussion! How should I capture this?
+
+1. Add to thought doc now
+   → Write to appropriate section (or Open Questions if undecided)
+
+2. Keep in chat
+   → You can reference it later if needed
+
+3. Create @{user} comment in thought doc
+   → Leaves a marker for you to review later
+
+Which would you prefer?
+```
+
+**If option 1 (add to doc):**
+
+```bash
+# Write to appropriate section
+# If decision made: add to Proposal or Key Decisions
+# If still exploring: add to Open Questions with context
+```
+
+**If option 3 (create comment):**
+
+```bash
+# Read user_mention from ~/.droid/config.yaml
+# Add comment to thought doc:
+
+> @{user} Explored events vs polling for status updates
+>
+> Key considerations:
+> - Latency requirement: <100ms
+> - Multiple consumers: dashboard, webhooks, alerts
+> - Volume: ~1000 updates/day
+>
+> Recommendation: Events using existing event-emitter pattern
+> Rationale: Low latency needed, multiple consumers, fits existing architecture
+>
+> Next step: Draft this into Proposal section?
+```
+
+## Cross-Platform Approach
+
+**Use prose-based questioning** - works on OpenCode + Claude Code:
+
+```
+# Instead of:
+Select an option: [Events | Polling | Hybrid]
+
+# Use:
+What's your latency requirement?
+(e.g., "under 100ms", "a few seconds is fine", "real-time")
+```
+
+**Response patterns to watch for:**
+
+- "real-time" / "immediate" → suggests events
+- "eventually" / "doesn't matter" → suggests polling
+- "multiple consumers" → suggests pub/sub events
+- "simple" / "straightforward" → suggests polling
+
+## Example Output (Directed)
+
+```
+Let's think through the rollout plan.
+
+❓ Phased rollout or all at once?
+   Context: {Impact from PRD - scale, users affected, risk level}
+
+> User: Let's do phased - this is risky
+
+❓ Feature flags?
+   {Check research doc for feature flag system discovered}. Should we add `{feature-name}` flag?
+
+> User: Yes, good idea
+
+❓ What phases make sense?
+   10% → 50% → 100%? Or something else?
+
+> User: Let's do 10% for a week, then 50%, then 100%
+
+❓ Rollback strategy?
+   If validation starts failing, how quickly can we revert?
+
+> User: Just toggle the flag off. Should be instant.
+
+❓ Monitoring?
+   What metrics tell us it's healthy vs broken?
+
+> User: Error rate, success rate, latency
+
+✓ Got it! Summary:
+  • 3-phase rollout: 10% (1 week) → 50% (1 week) → 100%
+  • Feature flag: `{feature-name}` ({system from research doc})
+  • Rollback: Toggle flag off, <1 min to take effect
+  • Monitoring: error rate, success rate, p95 latency
+
+How should I capture this?
+1. Add to Rollout Plan section now
+2. Keep in chat
+3. Create @{user} comment to review later
+```
+
+## Example Output (Freeform)
+
+```
+Let's explore: events vs polling for status updates
+
+❓ What triggers the status update?
+
+> User: When a transaction moves to "completed" or "failed"
+
+❓ Who needs to know?
+   One service? Multiple? External partners?
+
+> User: Our dashboard, partner webhooks, and internal alerting
+
+❓ How many status updates per day?
+
+> User: About 10,000 - roughly 10/min steady state, spikes to 100/min
+
+❓ Latency requirement?
+
+> User: Dashboard should update within a few seconds. Webhooks can be delayed a bit.
+
+❓ Existing patterns?
+   {Check research doc for event/messaging patterns discovered}
+
+> User: Yeah, we use {pattern} for internal events
+
+✓ Analysis:
+  Events are a better fit:
+    ✓ Multiple consumers (dashboard, webhooks, alerts)
+    ✓ Moderate volume (10-100/min) - well within event system capacity
+    ✓ Fits existing architecture ({pattern from research doc})
+    ✓ Low latency for dashboard (few seconds acceptable)
+
+  Implementation:
+    • Emit `{feature}.{event}` event
+    • Dashboard subscribes via {mechanism from research}
+    • Webhooks subscribe and batch deliver
+    • Alerts subscribe for failures only
+
+Should I add this to the Proposal section?
+```
+
+## Error Handling
+
+- **Thought doc not found:** Remind user to run `/tech-design start` first
+- **Empty thought doc:** Suggest running `/tech-design draft` first to have context
+- **User gives terse answers:** Ask follow-up questions to dig deeper
+- **User says "I don't know":** Offer to research codebase or flag as Open Question