@orderful/droid 0.38.0 → 0.39.1

package/dist/tools/tech-design/skills/tech-design/references/summary-template.md

@@ -0,0 +1,94 @@
+# {Feature Name} - Summary
+
+> **Quick Overview:** {2-3 sentences: what we're building, why it matters, expected impact}
+
+**Related Documents:**
+- [Full Tech Design](./TECH-DESIGN.md) - Complete technical design with all decisions
+- [PRD](./PRD.md) - Product requirements
+- [Thought Doc](./artifacts/thought-doc.md) - Full exploration and working notes
+
+---
+
+## The Problem
+
+{2-3 paragraphs: current pain, impact if not solved, who's affected}
+
+---
+
+## The Solution
+
+### Core Concept
+
+{1-2 paragraphs: high-level approach, how it works}
+
+**Flow:**
+```
+{Simple diagram or step-by-step flow}
+```
+
+### Key Components
+
+{3-5 bullet points with brief explanations of main pieces}
+
+---
+
+## Scope
+
+### In Scope (MVP)
+✅ {Feature 1}
+✅ {Feature 2}
+✅ {Feature 3}
+
+### Out of Scope
+❌ {Deferred feature 1}
+❌ {Deferred feature 2}
+
+---
+
+## Key Design Decisions
+
+### 1. {Decision Topic}
+{What we chose}
+
+**Why:** {Brief rationale}
+
+### 2. {Decision Topic}
+{What we chose}
+
+**Why:** {Brief rationale}
+
+---
+
+## Implementation Timeline
+
+{Brief phase overview with status}
+
+See [Full Tech Design](./TECH-DESIGN.md) for complete details.
+
+---
+
+## Success Metrics
+
+**MVP Success Criteria:**
+- {Metric 1}
+- {Metric 2}
+- {Metric 3}
+
+**Long-Term Impact:**
+- {Goal 1}
+- {Goal 2}
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| {Risk} | {How we handle it} |
+
+---
+
+## For More Details
+
+- **Full technical design:** [TECH-DESIGN.md](./TECH-DESIGN.md)
+- **{Additional artifact}:** [artifacts/{file}.md](./artifacts/{file}.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.38.0",
+  "version": "0.39.1",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/bin/droid.ts

@@ -16,6 +16,7 @@ import {
   reposRemoveCommand,
   reposGetCommand,
 } from '../commands/repos';
+import { authSlackCommand, authStatusCommand } from '../commands/auth';
 import { getVersion } from '../lib/version';
 import { loadConfig, saveConfig, configExists } from '../lib/config';
 import { syncNewPlatforms } from '../lib/platforms';
@@ -109,6 +110,24 @@ program
   .allowUnknownOption()
   .action(execCommand);
 
+// Auth command with subcommands
+const auth = program
+  .command('auth')
+  .description('Set up authentication for external services');
+
+auth
+  .command('slack')
+  .description('Set up Slack authentication for status updates')
+  .action(authSlackCommand);
+
+auth
+  .command('status')
+  .description('Show authentication status')
+  .action(authStatusCommand);
+
+// Default: show auth status if no subcommand
+auth.action(authStatusCommand);
+
 // Sync new platforms before running any command
 // This ensures that newly installed platforms (e.g., Codex) get all existing tools
 if (configExists()) {

package/src/commands/auth.ts

@@ -0,0 +1,150 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { hasSlackToken } from '../lib/secrets';
+
+// Slack OAuth configuration
+const SLACK_SCOPES = 'chat:write,canvases:write';
+const REDIRECT_URI = 'https://localhost:9876/callback';
+
+/**
+ * Get the user's shell config file path
+ */
+function getShellConfig(): string {
+  const shell = process.env.SHELL || '/bin/zsh';
+  if (shell.includes('zsh')) return '~/.zshrc';
+  if (shell.includes('bash')) return '~/.bashrc';
+  if (shell.includes('fish')) return '~/.config/fish/config.fish';
+  return '~/.profile';
+}
+
+export async function authSlackCommand(): Promise<void> {
+  console.log(chalk.bold('\n🔐 Slack Authentication Setup\n'));
+
+  // Check current status
+  if (hasSlackToken()) {
+    console.log(chalk.green('✓ SLACK_USER_TOKEN is already set in your environment\n'));
+    const { reauth } = await inquirer.prompt<{ reauth: boolean }>([
+      {
+        type: 'confirm',
+        name: 'reauth',
+        message: 'Re-authenticate anyway?',
+        default: false,
+      },
+    ]);
+
+    if (!reauth) {
+      return;
+    }
+    console.log('');
+  }
+
+  // Check for client credentials
+  const clientId = process.env.SLACK_CLIENT_ID;
+  const clientSecret = process.env.SLACK_CLIENT_SECRET;
+
+  if (!clientId || !clientSecret) {
+    const shellConfig = getShellConfig();
+    console.log(chalk.yellow('Missing Slack app credentials.\n'));
+    console.log(chalk.gray('Get Client ID and Client Secret from 1Password ("Droid Slack App")'));
+    console.log(chalk.gray(`and add to your ${shellConfig}:\n`));
+    console.log(chalk.white('  export SLACK_CLIENT_ID="your-client-id"'));
+    console.log(chalk.white('  export SLACK_CLIENT_SECRET="your-client-secret"\n'));
+    console.log(chalk.gray('Then reload and run this again:\n'));
+    console.log(chalk.white(`  source ${shellConfig} && droid auth slack\n`));
+    return;
+  }
+
+  // Step 1: Direct user to authorize
+  const authorizeUrl = `https://slack.com/oauth/v2/authorize?client_id=${clientId}&user_scope=${SLACK_SCOPES}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`;
+
+  console.log(chalk.yellow('Step 1: Authorize in Slack\n'));
+  console.log(chalk.gray('  Go to the "Droid Setup" canvas in #rnd-updates and click "Install Droid Slack App"'));
+  console.log(chalk.gray('  Or open this URL:\n'));
+  console.log(chalk.cyan(`  ${authorizeUrl}\n`));
+  console.log(chalk.gray('  After clicking Allow, you\'ll be redirected to a URL that won\'t load.'));
+  console.log(chalk.gray('  Copy the "code" parameter from the URL bar.\n'));
+
+  // Step 2: Get the code
+  const { code } = await inquirer.prompt<{ code: string }>([
+    {
+      type: 'input',
+      name: 'code',
+      message: 'Paste the code:',
+      validate: (input: string) => input.length > 0 || 'Code is required',
+    },
+  ]);
+
+  // Step 3: Exchange code for token
+  console.log(chalk.yellow('\nStep 2: Exchanging code for token...\n'));
+
+  try {
+    const response = execSync(
+      `curl -s -X POST https://slack.com/api/oauth.v2.access \
+        -d "client_id=${clientId}" \
+        -d "client_secret=${clientSecret}" \
+        -d "code=${code}" \
+        -d "redirect_uri=${REDIRECT_URI}"`,
+      { encoding: 'utf-8' }
+    );
+
+    const result = JSON.parse(response);
+
+    if (!result.ok) {
+      console.log(chalk.red(`✗ Slack API error: ${result.error}`));
+      if (result.error === 'invalid_code') {
+        console.log(chalk.gray('  The code may have expired. Try again with a fresh code.'));
+      }
+      return;
+    }
+
+    const token = result.authed_user?.access_token;
+    if (!token) {
+      console.log(chalk.red('✗ No user token in response'));
+      console.log(chalk.gray('  Response:'), JSON.stringify(result, null, 2));
+      return;
+    }
+
+    // Success!
+    const shellConfig = getShellConfig();
+    console.log(chalk.green('✓ Got token!\n'));
+    console.log(chalk.yellow('Step 3: Save the token\n'));
+    console.log(chalk.gray(`  Add to your ${shellConfig}:\n`));
+    console.log(chalk.white(`  export SLACK_USER_TOKEN="${token}"\n`));
+    console.log(chalk.gray('  Then reload your shell:\n'));
+    console.log(chalk.white(`  source ${shellConfig}\n`));
+
+  } catch (error) {
+    console.log(chalk.red('✗ Failed to exchange code for token'));
+    if (error instanceof Error) {
+      console.log(chalk.gray(`  ${error.message}`));
+    }
+  }
+}
+
+export async function authStatusCommand(): Promise<void> {
+  console.log(chalk.bold('\n🔐 Auth Status\n'));
+
+  const clientId = process.env.SLACK_CLIENT_ID;
+  const clientSecret = process.env.SLACK_CLIENT_SECRET;
+  const hasCredentials = clientId && clientSecret;
+
+  if (hasCredentials) {
+    console.log(chalk.green('✓ Slack app credentials configured'));
+  } else {
+    console.log(chalk.yellow('✗ Slack app credentials missing'));
+    console.log(chalk.gray('  Run: droid auth slack'));
+  }
+
+  if (hasSlackToken()) {
+    const token = process.env.SLACK_USER_TOKEN!;
+    const masked = token.slice(0, 10) + '...' + token.slice(-4);
+    console.log(chalk.green('✓ Slack user token configured'));
+    console.log(chalk.gray(`  Token: ${masked}`));
+  } else {
+    console.log(chalk.yellow('✗ Slack user token missing'));
+    if (hasCredentials) {
+      console.log(chalk.gray('  Run: droid auth slack'));
+    }
+  }
+}

package/src/lib/secrets.ts

@@ -0,0 +1,12 @@
+/**
+ * Secret/token helpers - reads from environment variables only
+ * Users manage their own tokens in shell config (e.g., ~/.zshrc)
+ */
+
+export function getSlackToken(): string | undefined {
+  return process.env.SLACK_USER_TOKEN;
+}
+
+export function hasSlackToken(): boolean {
+  return !!process.env.SLACK_USER_TOKEN;
+}

package/src/tools/status-update/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "droid-status-update",
+  "version": "0.1.0",
+  "description": "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "status-update"
+  ],
+  "skills": [
+    "./skills/status-update/SKILL.md"
+  ],
+  "commands": [
+    "./commands/status-update.md"
+  ]
+}

package/src/tools/status-update/TOOL.yaml

@@ -0,0 +1,21 @@
+name: status-update
+description: "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal."
+version: 0.1.0
+status: beta
+
+includes:
+  skills:
+    - name: status-update
+      required: true
+  commands:
+    - name: status-update
+      is_alias: false
+  agents: []
+
+dependencies: []
+
+config_schema:
+  default_crosspost_channel:
+    type: string
+    description: Default channel for cross-posting updates (e.g., rnd-updates)
+    required: false

package/src/tools/status-update/commands/status-update.md

@@ -0,0 +1,27 @@
+---
+name: status-update
+description: "Generate and post project status updates. Pulls from codex, Jira, and manual input. Posts to Slack or prints to terminal."
+argument-hint: "[{project}]"
+---
+
+# /status-update
+
+**User invoked:** `/status-update $ARGUMENTS`
+
+**Your task:** Invoke the **status-update skill** with these arguments.
+
+## Examples
+
+- `/status-update` → Prompt for project or use active project
+- `/status-update partnership-automation` → Generate update for specific project
+- `/status-update --no-slack` → Generate update but print to terminal instead of posting
+
+## Quick Reference
+
+```
+/status-update                      # Interactive - prompts for everything
+/status-update {project}            # Use codex project for metadata
+/status-update --no-slack           # Output to terminal instead of Slack
+```
+
+See the **status-update skill** for complete documentation.

package/src/tools/status-update/skills/status-update/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: status-update
+description: "Generate and post project status updates. Aggregates context from codex projects, Jira epics, and manual input. Posts to Slack or prints to terminal."
+argument-hint: "[{project}]"
+allowed-tools:
+  [
+    Read,
+    Glob,
+    Grep,
+    Bash(git:*),
+    Bash(curl:*),
+    Bash(droid:*),
+  ]
+---
+
+# Status Update Skill
+
+Generate formatted project status updates from multiple sources and post to Slack (or print to terminal).
+
+## Data Sources (All Optional)
+
+| Source | When available | What it provides |
+|--------|----------------|------------------|
+| **Codex project** | If project name matches a codex project | Metadata (slack, jira, links) + git history |
+| **Jira MCP** | If jira.epic configured + MCP connected | Ticket status for in-flight/up-next drafts |
+| **Manual input** | Always | User-provided status, phase, bullets |
+
+## Output Destinations
+
+| Destination | When available | Fallback |
+|-------------|----------------|----------|
+| **Slack** | If slack.channel configured + SLACK_USER_TOKEN set | Print to terminal |
+
+## Procedure
+
+### 1. Resolve Project Context
+
+**If project name provided:**
+
+1. Check if codex is configured:
+   ```bash
+   droid config --get tools.codex
+   ```
+
+2. If codex configured, look for matching project:
+   ```bash
+   ls {codex_repo}/projects/ | grep -i {project}
+   ```
+
+3. If found, read CONTEXT.md frontmatter:
+   - `title` - Project name
+   - `slack.channel` - Primary Slack channel
+   - `slack.crosspost_channel` - Optional crosspost channel
+   - `slack.canvas_id` - Optional canvas for update log
+   - `jira.epic` - Optional Jira epic key
+   - `links.prd`, `links.tech_design`, `links.figma` - Optional doc links
+
+**If no project name provided:**
+
+1. Check for active project in conversation context
+2. If none, ask: "Which project is this update for?"
+3. If user provides a name, attempt to match to codex project
+4. If no match, continue without codex metadata (prompt for details manually)
+
+**If no codex match:**
+
+Prompt user for:
+- Project name (for display)
+- Slack channel (optional - skip to print to terminal)
+- Jira epic key (optional)
+
+### 2. Generate Draft Content
+
+Attempt to generate draft bullets from available sources.
+
+#### Source A: Codex Git History (if codex project found)
+
+```bash
+git -C {codex_repo} log --oneline --since="7 days ago" -- projects/{project}/
+```
+
+Parse commits to understand recent activity:
+- DECISIONS.md changes → decisions made
+- New artifacts → meetings, documents produced
+- CONTEXT.md changes → project evolution
+- PRD.md/TECH-DESIGN.md changes → documentation progress
+
+Generate human-readable draft bullets from the git history.
+
+#### Source B: Jira MCP (if configured)
+
+**Check MCP availability:**
+```
+mcp__atlassian__getAccessibleAtlassianResources
+```
+
+If available and `jira.epic` is set, run two JQL queries:
+
+1. **Recently completed + in progress:**
+   ```
+   parent = {jira.epic} AND (status changed to Done AFTER -7d OR statusCategory in ("In Progress"))
+   ```
+
+2. **Up next:**
+   ```
+   parent = {jira.epic} AND statusCategory = "To Do"
+   ```
+
+Categorise tickets:
+
+| Jira Status | Category |
+|-------------|----------|
+| Done (last 7 days) | In flight (completed) |
+| In Progress, In Review, In QA | In flight (active) |
+| To Do, Backlog | Up next |
+
+#### Combine Sources
+
+If multiple sources available:
+- Deduplicate where codex change and Jira ticket describe the same work
+- Prefer Jira summaries for ticket-tracked work
+- Include codex-only changes (decisions, meetings) not in Jira
+
+**Present draft to user** for review/editing before finalising.
+
+### 3. Gather Update Content
+
+Ask user for (pre-fill from drafts where available):
+
+1. **Status** - One of:
+   - `on_track` (green) - Everything proceeding as planned
+   - `at_risk` (yellow) - Some concerns or blockers emerging
+   - `blocked` (red) - Cannot proceed without resolution
+
+2. **Current phase** - One of:
+   - `discovery` - Research and requirements gathering
+   - `post_discovery_feedback` - Incorporating discovery feedback
+   - `design` - Prototype and design work
+   - `post_design_feedback` - Incorporating design feedback
+   - `prd` - Writing PRD
+   - `tech_design` - Writing Tech Design
+   - `development` - Active implementation
+   - `qa` - QA & Testing
+   - `release` - Released to production
+
+3. **In flight this week** - Bullet points (from draft or manual)
+
+4. **Up next** - Bullet points (from draft or manual)
+
+### 4. Format Message
+
+See `references/formatting.md` for detailed formatting rules.
+
+**Structure:**
+```
+*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 if configured}
+
+Posted with help from :droid:
+```
+
+Add ` & :codex:` to footer if codex project was used.
+
+### 5. Output
+
+#### If Slack configured (channel + SLACK_USER_TOKEN):
+
+**Post to primary channel:**
+```bash
+curl -s -X POST https://slack.com/api/chat.postMessage \
+  -H "Authorization: Bearer $SLACK_USER_TOKEN" \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -d '{
+    "channel": "{slack.channel}",
+    "text": "{formatted_message}",
+    "unfurl_links": false
+  }'
+```
+
+Check response for `"ok": true`. Save `ts` and `channel` from response.
+
+**Crosspost (if crosspost_channel configured):**
+
+Post summary version with link to full update:
+```
+*{project_title}*
+
+{status_line}
+{current_phase_only}
+
+{in_flight_section}
+
+:link: <{message_url}|View full update>
+```
+
+Message URL format: `https://orderful.slack.com/archives/{channel_id}/p{ts_without_dot}`
+
+**Update canvas log (if canvas_id configured):**
+```bash
+curl -s -X POST https://slack.com/api/canvases.edit \
+  -H "Authorization: Bearer $SLACK_USER_TOKEN" \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -d '{
+    "canvas_id": "{slack.canvas_id}",
+    "changes": [{
+      "operation": "insert_at_start",
+      "document_content": {
+        "type": "markdown",
+        "markdown": "### {date}\n{status} · {current_phase}\n[View update]({message_url})\n\n---"
+      }
+    }]
+  }'
+```
+
+**Confirm to user:**
+- "Posted update to #{channel}"
+- "Cross-posted to #{crosspost_channel}" (if applicable)
+- "Added to canvas log" (if applicable)
+
+#### If Slack NOT configured:
+
+Print the formatted message to terminal.
+
+Tell user: "Slack not configured. To post updates directly, add `slack.channel` to your project's CONTEXT.md and set `SLACK_USER_TOKEN` in your environment."
+
+### Error Handling
+
+| Error | Action |
+|-------|--------|
+| No SLACK_USER_TOKEN | Print to terminal, suggest setup |
+| Slack API error | Show error, offer to print instead |
+| Jira MCP not available | Skip Jira, continue with other sources |
+| No codex project found | Continue with manual input |
+
+## Configuration
+
+No required configuration. Optional settings via `droid config`:
+
+| Setting | Description |
+|---------|-------------|
+| `default_crosspost_channel` | Default channel for cross-posts if not in project metadata |