specmem-hardwicksoftware 3.5.99

package/commands/specmem-team-member.md

@@ -0,0 +1,409 @@
+# SpecMem Team Member - Team Coordination Tools
+
+## REQUIRED: Check Arguments First
+
+**IF no arguments provided OR args is empty/whitespace/help/-h/--help:**
+
+OUTPUT THIS HELP AND STOP:
+
+```
+SpecMem Team Member - Team Coordination
+
+USAGE:
+  /specmem-team-member <subcommand> [args]
+
+SUBCOMMANDS:
+
+  status              Show team status, active claims, help requests
+  messages            Read recent team messages (last 10)
+  send <message>      Send a message to the team
+  claim <description> Claim a task to prevent conflicts
+  release [claimId]   Release task claims (default: all)
+  broadcast <message> Broadcast status update to all members
+  help-request <text> Request help from the team
+  help-respond <id> <response> Respond to a help request
+  clear               Clear team messages (requires confirmation)
+
+EXAMPLES:
+
+  /specmem-team-member status
+  /specmem-team-member messages
+  /specmem-team-member send Working on auth module
+  /specmem-team-member claim Implementing user login
+  /specmem-team-member release
+  /specmem-team-member broadcast API endpoints ready
+  /specmem-team-member help-request How does token refresh work?
+  /specmem-team-member help-respond abc-123 Try using JWT refresh tokens
+  /specmem-team-member clear
+
+MCP TOOLS:
+  send_team_message, read_team_messages, broadcast_to_team,
+  claim_task, release_task, get_team_status,
+  request_help, respond_to_help, clear_team_messages
+```
+
+**DO NOT PROCEED WITHOUT A SUBCOMMAND.**
+
+---
+
+## Has Subcommand - Parse and Execute
+
+Parse the first word as the subcommand, rest as arguments.
+
+---
+
+### SUBCOMMAND: status
+
+**VALIDATION:**
+- No arguments required
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__get_team_status` with parameters:
+```json
+{}
+```
+
+**Display results showing:**
+- Active task claims (who is working on what)
+- Recent team activity (messages, claims)
+- Open help requests count
+
+---
+
+### SUBCOMMAND: messages (or read)
+
+**VALIDATION:**
+- No arguments required (uses defaults)
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__read_team_messages` with parameters:
+```json
+{
+  "limit": 10,
+  "compress": true,
+  "include_broadcasts": true
+}
+```
+
+**Display:** Recent team messages with sender, content, timestamp, and unread status.
+
+**NOTE:**
+- Use `mentions_only: true` to filter for @mentions
+- Use `unread_only: true` to show only unread messages
+- Use `since: "2025-01-21T10:00:00Z"` to filter by time
+
+---
+
+### SUBCOMMAND: send <message>
+
+Extract everything after "send" as the message content.
+
+**VALIDATION:**
+- **IF no message text provided:** Output "Error: No message provided. Usage: /specmem-team-member send <message>" and STOP.
+- Message must not be empty or only whitespace
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__send_team_message` with parameters:
+```json
+{
+  "message": "<extracted message text>",
+  "type": "update",
+  "priority": "normal"
+}
+```
+
+**VALID VALUES:**
+- `type`: "status" | "question" | "update" | "broadcast" | "help_request" | "help_response"
+- `priority`: "low" | "normal" | "high" | "urgent"
+- `task_id`: (optional) string - send to task-specific channel
+- `project_id`: (optional) string - send to project-specific channel
+- `thread_id`: (optional) string - reply to a thread
+- `sender_name`: (optional) string - display name for sender
+
+**Display:** Confirmation that message was sent, including messageId and mentions found.
+
+**SUPPORTS @MENTIONS:** Use @member-id in the message to notify specific team members.
+
+---
+
+### SUBCOMMAND: claim <description>
+
+Extract everything after "claim" as the task description.
+
+**VALIDATION:**
+- **IF no description provided:** Output "Error: No task description. Usage: /specmem-team-member claim <description>" and STOP.
+- Description must not be empty or only whitespace
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__claim_task` with parameters:
+```json
+{
+  "description": "<extracted description>",
+  "files": []
+}
+```
+
+**VALID VALUES:**
+- `description`: string (required) - what you're working on
+- `files`: string[] (optional) - array of file paths you'll be working on
+
+**Display:**
+- Claim ID (for use with release)
+- Confirmation message
+- Any warnings about conflicting file claims
+
+**NOTE:** If files are already claimed by another member, you'll get a warning but the claim will still succeed.
+
+---
+
+### SUBCOMMAND: release [claimId]
+
+Extract claimId after "release" if provided, otherwise use "all".
+
+**VALIDATION:**
+- If claimId provided, it must be a valid UUID or "all"
+- Default to "all" if no claimId specified
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__release_task` with parameters:
+```json
+{
+  "claimId": "<claimId or 'all'>"
+}
+```
+
+**VALID VALUES:**
+- `claimId`: string (required) - specific claim UUID or "all" to release all your claims
+
+**Display:**
+- Confirmation showing number of claims released
+- List of released claim IDs
+
+---
+
+### SUBCOMMAND: broadcast <message>
+
+Extract everything after "broadcast" as the message content.
+
+**VALIDATION:**
+- **IF no message text provided:** Output "Error: No message provided. Usage: /specmem-team-member broadcast <message>" and STOP.
+- Message must not be empty or only whitespace
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__broadcast_to_team` with parameters:
+```json
+{
+  "message": "<extracted message text>",
+  "broadcast_type": "status",
+  "priority": "normal",
+  "cross_project": false
+}
+```
+
+**VALID VALUES:**
+- `message`: string (required) - the broadcast message
+- `broadcast_type`: "status" | "progress" | "announcement" (default: "status")
+- `priority`: "low" | "normal" | "high" | "urgent" (default: "normal")
+- `metadata`: object (optional) - e.g., { progress: 75 }
+- `cross_project`: boolean (default: false) - if true, broadcast to ALL projects (use sparingly!)
+
+**Display:** Confirmation that broadcast was sent with messageId.
+
+**NOTE:** By default, broadcasts only reach team members in the SAME PROJECT. Use cross_project: true for system-wide announcements.
+
+---
+
+### SUBCOMMAND: help-request <question>
+
+Extract everything after "help-request" as the question.
+
+**VALIDATION:**
+- **IF no question provided:** Output "Error: No question provided. Usage: /specmem-team-member help-request <question>" and STOP.
+- Question must not be empty or only whitespace
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__request_help` with parameters:
+```json
+{
+  "question": "<extracted question>",
+  "context": null,
+  "skills_needed": []
+}
+```
+
+**VALID VALUES:**
+- `question`: string (required) - the question or issue you need help with
+- `context`: string (optional) - additional context about the problem
+- `skills_needed`: string[] (optional) - e.g., ["database", "typescript"]
+
+**Display:**
+- Help request ID (save this for tracking responses!)
+- Confirmation that broadcast was sent to team
+- Reminder to check messages for responses
+
+---
+
+### SUBCOMMAND: help-respond <requestId> <response>
+
+Parse arguments: first word is requestId, rest is response text.
+
+**VALIDATION:**
+- **IF no requestId provided:** Output "Error: Missing request ID. Usage: /specmem-team-member help-respond <requestId> <response>" and STOP.
+- **IF no response text provided:** Output "Error: No response provided. Usage: /specmem-team-member help-respond <requestId> <response>" and STOP.
+- requestId must be a valid UUID format
+- Response must not be empty or only whitespace
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__respond_to_help` with parameters:
+```json
+{
+  "requestId": "<extracted requestId>",
+  "response": "<extracted response text>"
+}
+```
+
+**VALID VALUES:**
+- `requestId`: string (required) - the ID of the help request
+- `response`: string (required) - your answer or guidance
+
+**Display:**
+- Confirmation that response was sent
+- Who the response was sent to (the original requester)
+- Response ID for tracking
+
+---
+
+### SUBCOMMAND: clear
+
+**VALIDATION:**
+- Requires explicit confirmation for safety
+
+**ASK USER FOR CONFIRMATION:**
+
+Output this prompt:
+```
+⚠️  WARNING: This will delete team communication data!
+
+This will clear:
+- All team messages in this project
+- All task claims in this project
+- All help requests in this project
+
+Confirm deletion? Type 'yes' to proceed.
+```
+
+**IF user confirms with "yes":**
+
+**CALL THIS MCP TOOL NOW** (do not just display it, actually invoke it):
+
+Use `mcp__specmem__clear_team_messages` with parameters:
+```json
+{
+  "confirm": true,
+  "clear_claims": true,
+  "clear_help_requests": true
+}
+```
+
+**VALID VALUES:**
+- `confirm`: boolean (required) - must be true to actually delete
+- `older_than_minutes`: number (optional) - only delete older than N minutes
+- `clear_claims`: boolean (default: true) - also clear task claims
+- `clear_help_requests`: boolean (default: true) - also clear help requests
+
+**IF user does NOT confirm:**
+
+Output: "Clear cancelled. No data was deleted."
+
+**Display:**
+- Number of messages deleted
+- Number of claims cleared
+- Number of help requests cleared
+
+**USE CASE:** Call this BEFORE spawning new team members to ensure they start fresh without old context.
+
+---
+
+### UNKNOWN SUBCOMMAND
+
+If subcommand is not recognized, output:
+
+```
+Error: Unknown subcommand '<subcommand>'
+
+Valid subcommands:
+  - status
+  - messages (or read)
+  - send
+  - claim
+  - release
+  - broadcast
+  - help-request
+  - help-respond
+  - clear
+
+Run /specmem-team-member help for usage.
+```
+
+---
+
+## TOOL PARAMETER VALIDATION
+
+**Always validate tool parameters BEFORE calling MCP tools:**
+
+1. **String parameters**: Must not be empty/null/undefined after trimming
+2. **Enum parameters**: Must match exact values from schema
+3. **Array parameters**: Can be empty array `[]` but must be valid JSON array
+4. **Boolean parameters**: Must be true/false, not string "true"/"false"
+5. **UUID parameters**: Should match UUID format (8-4-4-4-12 hex pattern)
+
+**If validation fails**:
+- Output clear error message explaining what's wrong
+- Show correct usage example
+- DO NOT call the MCP tool
+
+---
+
+## BEST PRACTICES
+
+**Workflow:**
+1. Start work: `claim` → prevents conflicts
+2. Update team: `send` → share progress
+3. Need help: `help-request` → broadcast to team
+4. Help others: `help-respond` → answer questions
+5. Finish work: `release` → free up files
+6. Check status: `status` + `messages` → stay coordinated
+
+**Token Efficiency:**
+- `read_team_messages` uses Chinese compression by default (compress: true)
+- `get_team_status` returns ultra-compact summaries
+- Use `limit` parameter to control message count
+
+**Project Isolation:**
+- All tools are automatically scoped to current project
+- Use `cross_project: true` in broadcast for system-wide announcements
+- Messages from other projects are NOT visible (except global broadcasts)
+
+---
+
+## ERROR HANDLING
+
+**Common Errors:**
+
+1. **"Claim not found"** → Invalid claimId in release command
+2. **"Help request not found"** → Invalid requestId in help-respond
+3. **"Message content cannot be empty"** → Empty message in send/broadcast
+4. **"Cannot release claim owned by another member"** → Trying to release someone else's claim
+
+**Always:**
+- Show the error message to the user
+- Explain what went wrong
+- Provide the correct usage example