@orderful/droid 0.25.2 → 0.27.0

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

@@ -0,0 +1,218 @@
+---
+name: tech-design
+description: "Technical design authoring with three-document approach - research doc (codebase discoveries), thought doc (design iteration), and roll-up (clean summary). Use when writing tech designs, drafting sections, exploring architectural ideas, or publishing to codex. User prompts like 'start tech design for X', 'draft the rollout section', 'let's think through the API design', 'publish this to codex'."
+globs: []
+alwaysApply: false
+allowed-tools:
+  [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Task]
+---
+
+# Tech Design Skill
+
+> Tech designs are where architectural decisions get made. Make them AI-friendly.
+
+Technical design authoring for engineers using a three-document approach: research doc captures codebase discoveries, thought doc for design iteration, roll-up for reviewers. Markdown in GitHub, version-controlled, PR-reviewed.
+
+## Why This Matters
+
+Tech designs are often:
+
+- Written in Confluence (slow, disconnected from code)
+- Missing key sections (no template enforcement)
+- Hard to iterate on (not AI-friendly)
+- Siloed (reviewer can't see the author's thinking)
+- Re-discovering the same patterns every time
+
+The `/tech-design` skill brings tech design authoring into the same AI-augmented workflow engineers already use for coding, with persistent codebase knowledge.
+
+## Prerequisites
+
+Before using tech-design, verify:
+
+1. **Brain skill configured:** Check if `~/.droid/skills/brain/overrides.yaml` exists
+2. **Codex skill configured:** Check if `~/.droid/skills/codex/overrides.yaml` exists
+3. **gh CLI:** Required for PR workflows
+
+If prerequisites fail, guide user to configure:
+
+- Brain missing: Direct to `/brain` command to set up brain directory
+- Codex missing: Direct to `/codex` command to set up codex repository
+- gh missing: `brew install gh && gh auth login`
+
+## Configuration
+
+Tech-design has no configuration of its own. It delegates to:
+
+- **Brain skill** for research + thought doc location (`brain_dir`, `inbox_folder`)
+- **Codex skill** for repository location (`codex_repo`)
+
+## Three-Document Approach
+
+| Document        | Created When | Purpose                                         | Location      | Audience    |
+| --------------- | ------------ | ----------------------------------------------- | ------------- | ----------- |
+| **Research**    | `/start`     | Deep dive: codex project + codebase discoveries | Brain         | Author + AI |
+| **Thought doc** | `/start`     | Design iteration: decisions, @mentions, drafts  | Brain         | Author + AI |
+| **Roll-up**     | `/publish`   | Clean summary: decisions only, reviewable       | Codex project | Reviewers   |
+
+**Why three documents?**
+
+1. **Research doc** = Persistent memory of codebase exploration
+   - Project-specific patterns discovered
+   - Existing implementations found
+   - Dependencies identified
+   - Stack/framework details
+   - Lives across sessions, not just context window
+
+2. **Thought doc** = Design workspace
+   - References research doc for context
+   - Focuses on architectural decisions
+   - Iterates with `@droid`/`@user` comments
+   - Captures the "why" behind choices
+
+3. **Roll-up** = Reviewer artifact
+   - Synthesized from thought doc
+   - 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".
+
+Both thought doc and roll-up are published to codex. Research doc stays in brain as project-specific knowledge base.
+
+## Commands
+
+| Command                                     | Action                                                   | Status |
+| ------------------------------------------- | -------------------------------------------------------- | ------ |
+| `/tech-design start --from codex:{project}` | Create research + thought docs, pull PRD/DESIGN context  | v1     |
+| `/tech-design draft [section]`              | Auto-generate from research doc + codebase exploration   | v1     |
+| `/tech-design think [topic]`                | Guided exploration, updates research doc with findings   | v1     |
+| `/tech-design gaps`                         | Checklist of missing/empty sections                      | v1     |
+| `/tech-design publish`                      | Generate roll-up, publish thought doc + roll-up to codex | v1     |
+| `/tech-design critic [persona]`             | Multi-persona review with severity scoring               | v2     |
+| `/tech-design respond {question}`           | Author tool: search thought doc to draft reply           | v2     |
+| `/tech-design ask {question}`               | Reviewer tool: search both docs to answer questions      | v2     |
+
+## Conversational Skill Matching
+
+Commands are explicit entry points, but most usage will be natural conversation. Match these patterns:
+
+| User says                              | Interpret as                                         |
+| -------------------------------------- | ---------------------------------------------------- |
+| "Let's draft the rollout section"      | `/draft rollout` - draft that section with research  |
+| "Can you write up the data model?"     | `/draft data-model` - draft Data Model section       |
+| "I'm thinking about using events here" | `/think` - explore first, stress-test the idea       |
+| "Write that up"                        | After `/think`, transition to `/draft` for that idea |
+| "What's missing?"                      | `/gaps` - show checklist of empty sections           |
+| "Let's think through the API"          | `/think api` - guided exploration of API design      |
+
+## Starting a Tech Design
+
+**Trigger:** `/tech-design start --from codex:{project}` or user wants to start a new tech design
+
+**TLDR:** Create research + thought docs in brain, pull PRD/DESIGN context from codex, perform deep codebase dive, set as active.
+
+**Full procedure:** See `references/start.md` for detailed implementation steps, error handling, and examples.
+
+## Drafting Content
+
+**Trigger:** `/tech-design draft [section]` or user wants to generate content
+
+**TLDR:** Research doc first, then draft. Use research doc as knowledge base. Explore codebase if needed, update research doc with findings.
+
+**Full procedure:** See `references/draft.md` for research strategies, section-specific guidance, and examples.
+
+## Thinking Through Ideas
+
+**Trigger:** `/tech-design think [topic]` or user wants to explore an idea
+
+**TLDR:** Think = explore/stress-test; Draft = write to doc. Updates research doc with findings. Often flows: think → decide → draft.
+
+**Full procedure:** See `references/think.md` for questioning strategies, directed vs freeform modes, and examples.
+
+**Cross-platform approach:** Use prose-based questioning (works on OpenCode + Claude Code). Don't rely on interactive prompts.
+
+## Gap Analysis
+
+**Trigger:** `/tech-design gaps` or user asks "what's missing?"
+
+**TLDR:** Show checklist of sections that are empty or missing. Offer `/think` for each.
+
+**Full procedure:** See `references/gaps.md` for criticality logic, PRD-based inference, and examples.
+
+## Publishing to Codex
+
+**Trigger:** `/tech-design publish` or user wants to create PR for review
+
+**TLDR:** Generate clean roll-up from thought doc, publish thought doc + roll-up to codex (research doc stays in brain).
+
+**Full procedure:** See `references/publish.md` for roll-up generation, git workflow, quality checklist, and examples.
+
+## Active Doc Tracking
+
+Leverage brain's active doc tracking:
+
+- When `/tech-design start` creates research + thought docs, thought doc becomes active
+- Subsequent commands operate on active thought doc without specifying path
+- Research doc is referenced by path when needed (stays as reference knowledge)
+- User can also use `/brain` or `/scratchpad` to work on the thought doc
+
+**Integration nudge:** Always remind users they can use brain commands:
+
+- "You can add notes with `/brain add` or check comments with `/brain check`"
+
+## Template Philosophy
+
+**Research doc:** Codebase discovery log - captures patterns, implementations, stack details. Project-specific knowledge base.
+
+**Thought doc:** Start minimal (3 sections), grow as needed:
+
+- **Background** - Why we're doing this
+- **Proposal** - What we're building
+- **Open Questions** - What we don't know yet
+
+Use `/gaps` to surface what's missing. Don't overwhelm at the start.
+
+**Roll-up:** Clean summary for reviewers - decisions only, no exploration noise.
+
+## Related Skills
+
+- **Brain** - Thought doc drafting location, active doc tracking, @mention comments
+- **Codex** - Context input (PRD/DESIGN), output location (TECH-DESIGN.md), PR creation
+- **Project** - Personal working memory (different from shared codex knowledge)
+
+## V2 Features (Not Yet Implemented)
+
+The following features are planned for v2 but not yet available:
+
+### Critic Personas
+
+Run thought doc through multiple personas via parallel sub-agents:
+
+| Persona           | Focus                                     |
+| ----------------- | ----------------------------------------- |
+| Security          | Input validation, auth, rate limiting     |
+| Ops/SRE           | Monitoring, alerting, runbooks            |
+| Junior Engineer   | Clarity, documentation, "why X over Y?"   |
+| Product Owner     | Does this solve the user problem?         |
+| Future Maintainer | Will someone understand this in 6 months? |
+
+Output with severity scoring:
+
+```
+🔴 Security: No input validation mentioned for user-provided templates
+🔴 Ops: Missing monitoring/alerting strategy
+🟡 Future Maintainer: Decision rationale for X over Y is thin
+🟢 Product: Aligns well with PRD requirements
+🟢 Junior: Implementation plan is clear
+```
+
+### Interaction Tools
+
+- `/tech-design respond {question}` - Author tool: search thought doc to draft reply to reviewer questions
+- `/tech-design ask {question}` - Reviewer tool: search both docs to answer questions
+
+## Notes
+
+- Only create thought docs when user explicitly starts a tech design (don't be proactive)
+- Always check for existing thought doc before creating new one
+- Respect user's draft location preference (don't hardcode paths)
+- If codex project missing: warn but continue (common during early adoption)

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

@@ -0,0 +1,321 @@
+# Drafting Content
+
+**Trigger:** `/tech-design draft [section]` or user wants to generate content
+
+**Goal:** Use research doc as knowledge base, do additional exploration if needed, draft content into thought doc.
+
+**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.
+
+## Procedure
+
+### 1. Determine Scope
+
+```bash
+if [ -z "$section" ]; then
+  # Whole doc - draft all three initial sections
+  sections=("Background" "Proposal" "Open Questions")
+else
+  # Specific section
+  sections=("$section")
+fi
+```
+
+### 2. Load Research Doc
+
+**Research doc should exist** - created during `/tech-design start`.
+
+- Read research doc: `tech-design-{project}-research.md`
+- Extract relevant findings for the section being drafted
+- Use as knowledge base to inform draft
+
+**If research doc missing:**
+
+- Warn user: "Research doc not found. Run `/tech-design start` first to create research + thought docs."
+- Option to continue without research context
+
+### 3. Section-Specific Drafting
+
+For each section, use research doc findings and do additional exploration as needed.
+
+#### Background Section
+
+**Sources:**
+
+- PRD context from research doc → "Codex Context" section
+- Current state from research doc → "Similar Implementations"
+
+**Draft structure:**
+
+```markdown
+## Background
+
+### Problem
+
+{Why we're doing this - from PRD in research doc}
+
+### Current State
+
+{What exists today - from research doc discoveries}
+
+Reference findings from research:
+
+- Existing pattern: {file path from research}
+- Current approach: {description from research}
+
+### Context
+
+{Who needs this and why - from PRD}
+```
+
+#### Proposal Section
+
+**Sources:**
+
+- Architecture patterns from research doc
+- Integration points from research doc
+- Dependencies from research doc
+- Additional codebase exploration if needed
+
+**Draft structure:**
+
+```markdown
+## Proposal
+
+### Overview
+
+{High-level approach - informed by patterns in research doc}
+
+### Architecture
+
+{How it fits - reference integration points from research}
+
+Follows pattern from: {file path from research doc}
+Integrates with: {modules/services from research doc}
+
+### Data Model
+
+{Tables, schemas, types needed}
+
+### API Surface
+
+{New endpoints, methods, interfaces}
+
+### Implementation Approach
+
+{Step-by-step - leverage dependencies already identified in research}
+```
+
+**Additional exploration:**
+
+- If research doc doesn't have enough detail for a subsection, explore further
+- Add new discoveries back to research doc
+- Keep research doc as living knowledge base
+
+#### Open Questions Section
+
+**Sources:**
+
+- Scan PRD for ambiguous requirements
+- Gaps identified during proposal drafting
+- Missing information from research phase
+
+**Draft structure:**
+
+```markdown
+## Open Questions
+
+- [ ] {Question from PRD ambiguity}
+- [ ] {Question from technical exploration}
+- [ ] {Question about integration - e.g., "How should X handle Y?"}
+```
+
+### 4. Write to Thought Doc
+
+- Read existing thought doc
+- Replace or populate the section being drafted
+- Preserve any existing `@droid`/`@{user}` comments
+- Keep content outside the target section unchanged
+
+### 5. Output Summary
+
+```
+✓ Drafted: {section}
+
+Key points from research doc:
+  • {Finding 1 referenced}
+  • {Finding 2 referenced}
+
+{If additional exploration was done:}
+Additional discoveries:
+  • {New finding}
+  • {Added to research doc}
+
+Next steps:
+  • Review and refine: Open {thought_doc_path}
+  • Draft another section: /tech-design draft {section-name}
+  • Explore an idea: /tech-design think {topic}
+  • Check completeness: /tech-design gaps
+```
+
+## Section-Specific Guidance
+
+### Rollout Plan
+
+**Research doc reference:**
+
+- Deployment patterns
+- Feature flag setup (if found)
+- Monitoring/observability setup
+
+**Explore if needed:**
+
+- How are similar features rolled out?
+- What rollback mechanisms exist?
+
+**Draft:**
+
+```markdown
+## Rollout Plan
+
+### Phases
+
+| Phase | Audience | Timeline | Success Criteria |
+| ----- | -------- | -------- | ---------------- |
+| 1     | ...      | ...      | ...              |
+
+### Feature Flags
+
+{Based on feature flag patterns from research}
+
+### Rollback Strategy
+
+{Based on deployment patterns from research}
+
+### Monitoring
+
+{Based on observability setup from research}
+```
+
+### Data Model
+
+**Research doc reference:**
+
+- Existing database/storage patterns
+- Schema conventions
+- ORM/database tooling used
+
+**Explore if needed:**
+
+- Similar data models in codebase
+- Migration patterns
+
+**Draft:**
+
+```markdown
+## Data Model
+
+### Entities
+
+{Based on patterns from research doc}
+
+### Relationships
+
+{How entities relate}
+
+### Migrations
+
+{Following migration pattern from research}
+```
+
+### API Surface
+
+**Research doc reference:**
+
+- Existing API patterns (REST, GraphQL, gRPC, etc.)
+- Authentication/authorization patterns
+- Rate limiting setup
+
+**Explore if needed:**
+
+- Similar endpoint implementations
+- Validation patterns
+
+**Draft:**
+
+```markdown
+## API Surface
+
+### Endpoints
+
+{Following API pattern from research}
+
+### Authentication
+
+{Using auth pattern from research}
+
+### Validation
+
+{Based on validation patterns found}
+```
+
+### Security Considerations
+
+**Research doc reference:**
+
+- Auth patterns
+- Input validation setup
+- Audit logging
+
+**Explore if needed:**
+
+- How are similar features secured?
+- What security reviews exist?
+
+**Draft:**
+
+```markdown
+## Security Considerations
+
+### Authentication & Authorization
+
+{Based on auth patterns from research}
+
+### Input Validation
+
+{Based on validation patterns from research}
+
+### Audit Logging
+
+{Based on logging patterns from research}
+
+### Risk Assessment
+
+| Risk | Mitigation |
+| ---- | ---------- |
+| ...  | ...        |
+```
+
+## Error Handling
+
+- **Thought doc not found:** Remind user to run `/tech-design start` first
+- **Research doc not found:** Warn but offer to continue with limited context
+- **Section not recognized:** List valid sections, suggest `/tech-design gaps` to see what's missing
+- **Exploration fails:** Gracefully continue, note what couldn't be found
+
+## Example Output
+
+```
+✓ Loaded research doc for transaction-templates
+
+✓ Drafted: Proposal
+
+Key points from research doc:
+  • Template storage pattern: Found in {file path}
+  • Validation service: Integration point at {module}
+  • Dependencies: {library} already available
+
+Next steps:
+  • Review and refine: Open {brain_dir}/0-Inbox/plans/tech-design-transaction-templates.md
+  • Draft another section: /tech-design draft rollout
+  • Check completeness: /tech-design gaps
+```