@rubytech/taskmaster 1.12.2 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/dist/agents/auth-profiles/consolidate.js +72 -0
  2. package/dist/agents/auth-profiles/oauth.js +0 -24
  3. package/dist/agents/auth-profiles/paths.js +4 -4
  4. package/dist/agents/auth-profiles/store.js +8 -100
  5. package/dist/agents/model-fallback.js +26 -1
  6. package/dist/agents/pi-embedded-runner/run/payloads.js +8 -0
  7. package/dist/agents/session-transcript-repair.js +3 -2
  8. package/dist/agents/system-prompt.js +1 -0
  9. package/dist/agents/taskmaster-tools.js +2 -0
  10. package/dist/agents/tool-policy.js +2 -0
  11. package/dist/agents/tools/opening-hours-tool.js +92 -0
  12. package/dist/agents/tools/web-fetch.js +8 -3
  13. package/dist/agents/tools/web-search.js +7 -4
  14. package/dist/agents/workspace-migrations.js +47 -0
  15. package/dist/build-info.json +3 -3
  16. package/dist/commands/agents.commands.add.js +1 -32
  17. package/dist/config/defaults.js +1 -1
  18. package/dist/config/legacy.migrations.part-3.js +25 -4
  19. package/dist/config/sessions/transcript.js +31 -0
  20. package/dist/config/types.business.js +1 -0
  21. package/dist/config/zod-schema.js +33 -0
  22. package/dist/control-ui/assets/{index-CpaEIgQy.css → index-B8I8lMfz.css} +1 -1
  23. package/dist/control-ui/assets/{index-CP9IoaZp.js → index-BWqMMgRV.js} +537 -425
  24. package/dist/control-ui/assets/index-BWqMMgRV.js.map +1 -0
  25. package/dist/control-ui/index.html +2 -2
  26. package/dist/gateway/config-reload.js +1 -0
  27. package/dist/gateway/server-close.js +8 -0
  28. package/dist/gateway/server-methods/business.js +31 -0
  29. package/dist/gateway/server-methods/network.js +19 -6
  30. package/dist/gateway/server-methods/tailscale.js +2 -2
  31. package/dist/gateway/server-methods.js +5 -1
  32. package/dist/gateway/server.impl.js +42 -0
  33. package/dist/infra/heartbeat-infra-alert.js +54 -0
  34. package/dist/memory/manager.js +5 -5
  35. package/dist/web/auto-reply/monitor/process-message.js +24 -0
  36. package/dist/web/inbound/access-control.js +2 -1
  37. package/dist/web/inbound/monitor.js +32 -10
  38. package/dist/web/inbound/owner-mirror.js +35 -0
  39. package/package.json +1 -1
  40. package/skills/anthropic/SKILL.md +30 -0
  41. package/skills/anthropic/references/setup-guide.md +146 -0
  42. package/skills/google-ai/SKILL.md +3 -2
  43. package/skills/google-ai/references/setup-guide.md +94 -0
  44. package/skills/log-review/SKILL.md +45 -0
  45. package/skills/log-review/cron-template.json +21 -0
  46. package/skills/log-review/references/review-protocol.md +65 -0
  47. package/skills/openai/SKILL.md +28 -0
  48. package/skills/openai/references/setup-guide.md +122 -0
  49. package/taskmaster-docs/USER-GUIDE.md +31 -2
  50. package/templates/beagle-taxi/memory/public/investors-knowledge-base.md +230 -0
  51. package/templates/beagle-taxi/skills/beagle-taxi/SKILL.md +3 -1
  52. package/templates/customer/agents/admin/BOOTSTRAP.md +14 -2
  53. package/templates/customer/agents/public/AGENTS.md +15 -0
  54. package/templates/education-hero/agents/admin/BOOTSTRAP.md +14 -2
  55. package/templates/real-agent/agents/admin/AGENTS.md +139 -0
  56. package/templates/real-agent/agents/admin/HEARTBEAT.md +12 -0
  57. package/templates/real-agent/agents/admin/IDENTITY.md +11 -0
  58. package/templates/real-agent/agents/admin/SOUL.md +38 -0
  59. package/templates/real-agent/agents/public/AGENTS.md +183 -0
  60. package/templates/real-agent/agents/public/IDENTITY.md +8 -0
  61. package/templates/real-agent/agents/public/SOUL.md +75 -0
  62. package/templates/real-agent/memory/admin/.gitkeep +0 -0
  63. package/templates/real-agent/memory/public/contributors/adam-mackay.md +7 -0
  64. package/templates/real-agent/memory/public/contributors/alex-pelosi-buchanan.md +7 -0
  65. package/templates/real-agent/memory/public/contributors/jamie-fisher.md +7 -0
  66. package/templates/real-agent/memory/public/contributors/john-savage.md +7 -0
  67. package/templates/real-agent/memory/public/contributors/melanie-attwater.md +7 -0
  68. package/templates/real-agent/memory/public/contributors/regina-mangan.md +7 -0
  69. package/templates/real-agent/memory/public/contributors/richard-rawlings.md +7 -0
  70. package/templates/real-agent/memory/public/contributors/roger-black.md +7 -0
  71. package/templates/real-agent/memory/public/contributors/steve-backley.md +7 -0
  72. package/templates/real-agent/memory/public/courses/agency-blueprint/.gitkeep +0 -0
  73. package/templates/real-agent/memory/public/courses/podcast/.gitkeep +0 -0
  74. package/templates/real-agent/memory/public/courses/real-business/.gitkeep +0 -0
  75. package/templates/real-agent/memory/public/courses/real-coaching/.gitkeep +0 -0
  76. package/templates/real-agent/memory/public/courses/real-marketing/.gitkeep +0 -0
  77. package/templates/real-agent/memory/public/resources/.gitkeep +0 -0
  78. package/templates/real-agent/memory/shared/.gitkeep +0 -0
  79. package/templates/real-agent/memory/users/.gitkeep +0 -0
  80. package/templates/real-agent/skills/bespoke-coaching/SKILL.md +29 -0
  81. package/templates/real-agent/skills/bespoke-coaching/references/coaching-boundaries.md +56 -0
  82. package/templates/real-agent/skills/bespoke-coaching/references/feedback-framework.md +61 -0
  83. package/templates/real-agent/skills/bootstrap/SKILL.md +27 -0
  84. package/templates/real-agent/skills/bootstrap/references/onboarding-flow.md +63 -0
  85. package/templates/real-agent/skills/content-directory/SKILL.md +40 -0
  86. package/templates/real-agent/skills/content-directory/references/module-delivery.md +65 -0
  87. package/templates/real-agent/skills/content-directory/references/progress-tracking.md +47 -0
  88. package/templates/tradesupport/agents/admin/BOOTSTRAP.md +14 -2
  89. package/dist/control-ui/assets/index-CP9IoaZp.js.map +0 -1
@@ -0,0 +1,146 @@
1
+ # Anthropic / Claude — Setup Guide
2
+
3
+ Walk the user through connecting Taskmaster to Claude. There are two options — determine which one is right for the user, then guide them through it.
4
+
5
+ ---
6
+
7
+ ## The two options
8
+
9
+ | | Option A: Claude Pro sign-in | Option B: API key |
10
+ |---|---|---|
11
+ | **Best for** | Users with a Claude Pro/Team/Enterprise subscription | Users who want pay-per-use or don't have a Claude subscription |
12
+ | **Cost** | Included in existing subscription | Pay per API call (requires billing setup at Anthropic) |
13
+ | **How it works** | OAuth sign-in — no key to manage | Paste a secret key from console.anthropic.com |
14
+ | **Setup location** | Setup page → "Connect to Claude" | Setup page → API Keys → Add provider |
15
+
16
+ ---
17
+
18
+ ## Step 1: Determine which option
19
+
20
+ Ask the user which situation applies:
21
+
22
+ > "There are two ways to connect Claude:
23
+ >
24
+ > **Option A (recommended):** If you have a **Claude Pro subscription** (the one you use at claude.ai), you can sign in directly — no API key needed. This is the easiest option.
25
+ >
26
+ > **Option B:** If you don't have a Claude subscription, or you prefer pay-per-use, you can paste an **API key** from Anthropic's developer console.
27
+ >
28
+ > Which would you like to do?"
29
+
30
+ If the user isn't sure:
31
+
32
+ > "Do you pay for Claude Pro (at claude.ai)? If yes, go with Option A — it's simpler and uses your existing subscription. If you don't have a Claude subscription, go with Option B."
33
+
34
+ ---
35
+
36
+ ## Option A: Claude Pro sign-in (recommended)
37
+
38
+ This uses OAuth device-code flow — the user signs in on their computer and pastes a code back into Taskmaster.
39
+
40
+ ### A1: Navigate to Setup
41
+
42
+ > "Go to your Taskmaster **Setup** page. Under **Connect to Claude**, click the **Connect to Claude** button."
43
+
44
+ If the user can't find it:
45
+
46
+ > "Open your browser and go to your Taskmaster's address followed by **/setup** — for example: `http://taskmaster.local:18789/setup`. You should see a section called **Connect to Claude** with a button."
47
+
48
+ ### A2: Sign in and copy the code
49
+
50
+ > "After clicking the button, a sign-in page will open on your computer (or you'll be given a link to open). Sign in with your **Claude account** — the same email you use at claude.ai.
51
+ >
52
+ > After signing in, the page will show a **code**. Copy that code."
53
+
54
+ ### A3: Paste the code
55
+
56
+ > "Paste the code into Taskmaster where it says to enter the code, then click **Submit**."
57
+
58
+ ### A4: Verify connection
59
+
60
+ > "You're done when the Claude/LLM status light goes **green**. That means Taskmaster is connected and ready to use your Claude subscription."
61
+
62
+ If the status light doesn't go green:
63
+
64
+ > "If the status light stays red or amber, try refreshing the Setup page. If it still doesn't work, the sign-in might have timed out — click **Connect to Claude** again to start over."
65
+
66
+ **Done.** No further setup needed — OAuth handles everything automatically, including token refresh.
67
+
68
+ ---
69
+
70
+ ## Option B: Paste an API key
71
+
72
+ This uses a direct API key from Anthropic's developer console. The user pays per API call.
73
+
74
+ ### B1: Get the key from Anthropic
75
+
76
+ > "You'll need an API key from Anthropic's developer console. Here's how to get one:
77
+ >
78
+ > 1. Go to **console.anthropic.com** in your browser
79
+ > 2. Sign in or create an account (you'll need to set up billing — Anthropic charges per API call)
80
+ > 3. Once logged in, go to **API Keys** (in the left sidebar or top menu)
81
+ > 4. Click **Create Key**
82
+ > 5. Give it a name like **Taskmaster**
83
+ > 6. Copy the key — it starts with **sk-ant-** and is quite long
84
+ >
85
+ > **Copy it now** — Anthropic only shows it once. If you lose it, you'll need to create a new one.
86
+ >
87
+ > Send me the key when you have it."
88
+
89
+ If the user navigated away or can't find API Keys:
90
+
91
+ > "On console.anthropic.com, look for **API Keys** in the left sidebar. If you don't see it, click on the **Settings** icon or look under your account menu."
92
+
93
+ ### B2: Verify the key format
94
+
95
+ When the user sends a key, verify it looks correct:
96
+
97
+ - Starts with `sk-ant-`
98
+ - Usually 90+ characters long
99
+
100
+ If it doesn't match:
101
+
102
+ > "That doesn't look like an Anthropic API key — it should start with **sk-ant-** and be quite long (about 100 characters). Can you check you copied the full key?"
103
+
104
+ ### B3: Store the key
105
+
106
+ Use the `api_keys` tool to store the key:
107
+
108
+ ```
109
+ api_keys({ action: "set", provider: "anthropic", apiKey: "<the key>" })
110
+ ```
111
+
112
+ The key is applied immediately — no restart needed. Confirm to the user:
113
+
114
+ > "Done — I've saved your Anthropic API key. Claude is now connected. You can start chatting and I'll use Claude for all my responses."
115
+
116
+ ---
117
+
118
+ ## If the user already has a connection
119
+
120
+ If the user has a working Claude connection (OAuth or API key) and is asking about API keys for a different reason:
121
+
122
+ > "You're already connected to Claude — I can see your connection is active. Were you looking to set up a different provider (like OpenAI or Google), or is there a problem with your current connection?"
123
+
124
+ ---
125
+
126
+ ## Troubleshooting
127
+
128
+ | Problem | Solution |
129
+ |---------|----------|
130
+ | "Connection expired" on Setup page | Try sending a message first — the connection auto-refreshes. Reload the Setup page after. If it persists, click **Connect to Claude** to sign in again. |
131
+ | OAuth code expired before pasting | Click **Connect to Claude** again to get a fresh code. The code is only valid for a few minutes. |
132
+ | API key rejected | Verify it starts with `sk-ant-`. Check that billing is set up on console.anthropic.com — keys don't work without an active billing method. |
133
+ | "Which provider should I pick?" | For most users, **Anthropic / Claude** is the right choice. It powers all of Taskmaster's conversations and reasoning. |
134
+ | User has both OAuth and API key | OAuth takes precedence. If the user wants to switch to an API key, they can disconnect OAuth on the Setup page first. |
135
+
136
+ ---
137
+
138
+ ## Common questions
139
+
140
+ | Question | Answer |
141
+ |----------|--------|
142
+ | "Is Claude Pro enough?" | Yes — Option A uses your existing Claude Pro subscription. No additional cost. |
143
+ | "How much does the API cost?" | Anthropic charges per API call. For small business use, typical costs are a few dollars per month. See anthropic.com/pricing for current rates. |
144
+ | "Can I use both OAuth and an API key?" | Yes, but OAuth takes precedence when active. The API key acts as a fallback. |
145
+ | "Do I need to restart?" | No — both OAuth and API keys are applied immediately. |
146
+ | "What if my subscription lapses?" | Taskmaster will show a connection error. Renew your subscription or switch to an API key. |
@@ -24,6 +24,7 @@ Guides users through obtaining a Google AI (Gemini) API key using browser automa
24
24
 
25
25
  | Task | When to use | Reference |
26
26
  |------|-------------|-----------|
27
- | Browser-assisted setup | User wants help getting the key | `references/browser-setup.md` |
27
+ | Guided setup (conversational) | User asks for help getting the key (default) | `references/setup-guide.md` |
28
+ | Browser-assisted setup | Browser tool available and user wants hands-free setup | `references/browser-setup.md` |
28
29
 
29
- Load the reference and follow its instructions. Send screenshots at each step so the user can see progress.
30
+ Load the appropriate reference and follow its instructions. Prefer the conversational guide unless browser automation is available and the user wants a hands-free experience.
@@ -0,0 +1,94 @@
1
+ # Google AI — Setup Guide (Conversational)
2
+
3
+ Walk the user through getting a Google AI (Gemini) API key with step-by-step instructions. Use this guide when browser automation is unavailable or the user prefers to navigate themselves.
4
+
5
+ ---
6
+
7
+ ## Prerequisites
8
+
9
+ - User has a Google account (Gmail or business email)
10
+ - Chat channel for sending instructions
11
+
12
+ ---
13
+
14
+ ## Step 1: Explain
15
+
16
+ Tell the user what this is and why they need it:
17
+
18
+ > "I need a Google AI key so I can understand voice notes and videos you send me. It also powers image generation and acts as a backup AI model.
19
+ >
20
+ > Google AI Studio gives you a free API key — no credit card needed. The whole thing takes about 2 minutes."
21
+
22
+ ## Step 2: Open Google AI Studio
23
+
24
+ > "Go to **aistudio.google.com/app/apikey** in your browser. Sign in with your Google account if asked."
25
+
26
+ If the user doesn't have a Google account:
27
+
28
+ > "You'll need a Google account first. Go to **accounts.google.com** and click **Create account**. Once that's done, come back and we'll get the API key."
29
+
30
+ ## Step 3: Get the key
31
+
32
+ > "On the API keys page, you'll see one of two things:
33
+ >
34
+ > **If you already have a key listed:** Click on it to see the full key, then copy it.
35
+ >
36
+ > **If there are no keys:** Click **Create API key** and follow any prompts. Google will generate a key for you — copy it.
37
+ >
38
+ > The key starts with **AIza** and is about 39 characters long. Send me the key when you have it."
39
+
40
+ If the user can't find the page:
41
+
42
+ > "Go directly to **aistudio.google.com/app/apikey** — that takes you straight to the API keys section. If you see a different page, look for an **API keys** option in the left sidebar or menu."
43
+
44
+ ## Step 4: Verify the key format
45
+
46
+ When the user sends a key, verify it looks correct:
47
+
48
+ - Starts with `AIza`
49
+ - About 39 characters long
50
+
51
+ If it doesn't match:
52
+
53
+ > "That doesn't look like a Google AI key — it should start with **AIza** and be about 39 characters long. Can you check you copied the right key?"
54
+
55
+ ## Step 5: Store the key
56
+
57
+ Use the `api_keys` tool to store the key:
58
+
59
+ ```
60
+ api_keys({ action: "set", provider: "google", apiKey: "<the key>" })
61
+ ```
62
+
63
+ The key is applied immediately — no restart needed. Confirm to the user:
64
+
65
+ > "Done — I've saved the Google AI key. You can send me voice notes and videos now and I'll understand them both. Image generation is also enabled."
66
+
67
+ ---
68
+
69
+ ## If the user already has a Google AI key configured
70
+
71
+ > "You already have a Google AI key set up. Would you like to replace it with a new key, or is there something else I can help with?"
72
+
73
+ ---
74
+
75
+ ## Troubleshooting
76
+
77
+ | Problem | Solution |
78
+ |---------|----------|
79
+ | "Enable API" prompt appears | Click the enable button, wait a moment, then proceed. Google may need to activate the API for your account. |
80
+ | Key exists but user can't see the full value | Click on the key name/row in the table to expand it and reveal the full key. |
81
+ | Sign-in required repeatedly | Make sure you're using the same Google account. Try clearing cookies or using an incognito window. |
82
+ | "API key not valid" error after saving | The key may be restricted to specific APIs. On the API keys page, click the key → check that it's unrestricted or includes "Generative Language API". |
83
+
84
+ ---
85
+
86
+ ## Common questions
87
+
88
+ | Question | Answer |
89
+ |----------|--------|
90
+ | "Is it free?" | Yes — Google AI Studio provides a free tier with generous monthly quotas. No credit card required. |
91
+ | "Do I need to restart?" | No — the key is applied immediately. |
92
+ | "What does it do?" | Powers voice note transcription (audio to text), video analysis (understanding what's in videos you send), image generation, and serves as a backup AI model. |
93
+ | "I already have a Google Cloud API key" | Google Cloud and Google AI Studio are different. You need a key from **aistudio.google.com**, not console.cloud.google.com. |
94
+ | "Can I use this for other Google services?" | The key is specifically for Google's AI models (Gemini). It doesn't affect your Gmail, Drive, or other Google services. |
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: log-review
3
+ description: "Daily log review — scans system and session logs for errors and warnings, triages issues, provides root-cause analysis, and sends a prioritised health report to admins. Advises escalation to Taskmaster support when issues exceed local resolution."
4
+ metadata: {"taskmaster":{"emoji":"🩺"}}
5
+ ---
6
+
7
+ # Log Review
8
+
9
+ ## When to Activate
10
+
11
+ - Triggered by the daily log review cron job
12
+ - Admin asks to review system health, logs, errors, or warnings
13
+ - Admin asks "are there any issues?", "how is the system doing?", or similar health questions
14
+
15
+ ## Behaviour
16
+
17
+ Load `references/review-protocol.md` for the full review and analysis protocol.
18
+
19
+ **Core principle:** Surface issues with analysis and actionable advice — don't dump raw logs. Every issue reported should include what happened, why, and what to do about it.
20
+
21
+ ### Rules
22
+
23
+ 1. **Scan system logs** — use `logs_read(action: "system")` for gateway-level errors and warnings
24
+ 2. **Scan session logs** — use `logs_read(action: "sessions")` across all agents for tool failures and agent errors
25
+ 3. **Triage by severity** — critical, warning, info. Deduplicate repeated errors.
26
+ 4. **Analyse each issue** — plain-language explanation, likely root cause, suggested admin action
27
+ 5. **Escalation guidance** — for issues beyond local resolution, advise forwarding this report to the Taskmaster public agent on WhatsApp for support
28
+ 6. **All-clear confirmation** — if no issues found, confirm briefly so admins know the review ran
29
+
30
+ ### Output Format
31
+
32
+ The report should follow this structure:
33
+
34
+ - **Critical** — service-affecting issues requiring immediate attention
35
+ - **Warnings** — degraded behaviour or emerging problems
36
+ - **Info** — notable patterns worth awareness
37
+ - **Escalation** — if any issues warrant Taskmaster support, advise forwarding this report
38
+ - **Summary** — issue count or all-clear confirmation
39
+
40
+ ### Constraints
41
+
42
+ - Keep total execution under 2 minutes
43
+ - Be honest — if nothing surfaced, say "all clear" rather than padding the report
44
+ - Use plain language — the admin is not a developer
45
+ - Deduplicate repeated errors — report once with count
@@ -0,0 +1,21 @@
1
+ {
2
+ "templateId": "log-review-daily",
3
+ "name": "🩺 Daily Log Review",
4
+ "description": "Scans system and session logs for errors and warnings, provides analysis and suggested actions",
5
+ "enabled": false,
6
+ "agentId": "admin",
7
+ "schedule": { "kind": "cron", "expr": "0 17 * * *" },
8
+ "sessionTarget": "isolated",
9
+ "wakeMode": "next-heartbeat",
10
+ "payload": {
11
+ "kind": "agentTurn",
12
+ "message": "Run the daily log review. Use the log-review skill.",
13
+ "deliver": true,
14
+ "to": "admins",
15
+ "bestEffortDeliver": true
16
+ },
17
+ "isolation": {
18
+ "postToMainMode": "summary",
19
+ "postToMainPrefix": "🩺 Log Review"
20
+ }
21
+ }
@@ -0,0 +1,65 @@
1
+ # Log Review Protocol
2
+
3
+ Run this protocol on schedule or when triggered by an admin. Be thorough in analysis but concise in output.
4
+
5
+ ## Step 1: System Log Scan
6
+
7
+ Use `logs_read` with `action: "system"` to pull recent gateway logs.
8
+
9
+ Focus on entries containing `[ERROR]` and `[WARN]`. Ignore routine info-level entries unless they reveal a pattern (e.g. repeated restarts, auth refresh cycles).
10
+
11
+ Look for:
12
+ - Service crashes or unexpected restarts
13
+ - Channel disconnections (WhatsApp, iMessage)
14
+ - Authentication failures or token expiry
15
+ - Integration errors (API calls, webhook failures)
16
+ - Resource warnings (memory, disk, rate limits)
17
+ - Startup errors or configuration problems
18
+
19
+ ## Step 2: Session Log Scan
20
+
21
+ Use `logs_read` with `action: "sessions"` to pull recent session transcripts across all agents.
22
+
23
+ Look for:
24
+ - Tool call failures or errors
25
+ - Agent errors or unexpected exceptions
26
+ - Repeated failed operations (retries that never succeed)
27
+ - Sessions that ended abnormally
28
+ - Patterns across agents (same tool failing for multiple agents)
29
+
30
+ ## Step 3: Triage
31
+
32
+ Categorise each distinct issue by severity:
33
+
34
+ - **Critical** — service down, channel disconnected, repeated crashes, data loss risk
35
+ - **Warning** — intermittent errors, degraded performance, auth issues approaching expiry, tool failures
36
+ - **Info** — notable but non-urgent patterns (unusual token usage spikes, brief transient errors that self-resolved)
37
+
38
+ Deduplicate: if the same error appears 50 times, report it once with the count.
39
+
40
+ ## Step 4: Analysis
41
+
42
+ For each issue provide:
43
+ 1. **What happened** — plain language, no jargon. An admin who isn't a developer should understand this.
44
+ 2. **Likely root cause** — your best assessment based on the log context
45
+ 3. **Suggested action** — what the admin can do (restart gateway, check API key, reconnect WhatsApp, etc.)
46
+
47
+ Be specific with actions. "Check the logs" is not a useful suggestion — the whole point of this skill is that the admin doesn't have to.
48
+
49
+ ## Step 5: Escalation Guidance
50
+
51
+ If any issue meets these criteria, advise the admin to escalate to Taskmaster support:
52
+ - Errors that persist across multiple review cycles
53
+ - Issues in core platform code (not configuration or API keys)
54
+ - Unexplained crashes with no clear root cause
55
+ - Data integrity concerns
56
+
57
+ Escalation advice: tell the admin to forward this report to the Taskmaster public agent on WhatsApp for support.
58
+
59
+ ## Step 6: Compose Report
60
+
61
+ Follow the output format defined in SKILL.md. The cron job handles delivery automatically — your text response IS the message.
62
+
63
+ If no issues were found, send a brief all-clear so admins know the review ran successfully. Don't pad the report.
64
+
65
+ Keep total execution under 2 minutes.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: openai
3
+ description: Guide users through getting an OpenAI API key for alternative AI models.
4
+ metadata: {"taskmaster":{"emoji":"🔑"}}
5
+ ---
6
+
7
+ # OpenAI Setup
8
+
9
+ Walks users through obtaining an OpenAI API key. OpenAI is an alternative AI provider — most users connect Claude (Anthropic) as their primary model. OpenAI is useful as a secondary option or for users who prefer GPT models.
10
+
11
+ ## When to activate
12
+
13
+ - User asks for help getting an OpenAI key or connecting GPT models
14
+ - User selects OpenAI from the API keys provider dropdown and needs help
15
+ - User wants to set up an alternative AI model alongside Claude
16
+
17
+ ## What it unlocks
18
+
19
+ - GPT models as an alternative or fallback AI provider
20
+ - Alternative audio transcription (Whisper)
21
+
22
+ ## References
23
+
24
+ | Task | When to use | Reference |
25
+ |------|-------------|-----------|
26
+ | Guided setup | User wants help getting the key | `references/setup-guide.md` |
27
+
28
+ Load the reference and follow its instructions.
@@ -0,0 +1,122 @@
1
+ # OpenAI — Setup Guide
2
+
3
+ Walk the user through getting an OpenAI API key and adding it to Taskmaster. Guide with clear instructions.
4
+
5
+ **Important:** OpenAI requires billing setup before API keys work. The user needs a payment method on file with OpenAI. Free trial credits may be available for new accounts, but the user still needs to create a billing account.
6
+
7
+ ---
8
+
9
+ ## Prerequisites
10
+
11
+ - User wants OpenAI/GPT models as an alternative or fallback provider
12
+ - Chat channel for sending instructions
13
+
14
+ ---
15
+
16
+ ## Step 1: Explain
17
+
18
+ Tell the user what this is and why they might want it:
19
+
20
+ > "OpenAI gives you access to GPT models as an alternative AI provider. Most users run on Claude (Anthropic) as the primary model, but you can add OpenAI as a fallback or secondary option.
21
+ >
22
+ > You'll need an OpenAI account with billing set up. I'll walk you through it."
23
+
24
+ If the user doesn't have Claude connected yet:
25
+
26
+ > "Before setting up OpenAI, you might want to connect Claude first — it's the primary AI that powers Taskmaster. Would you like to set up Claude instead, or do you specifically want OpenAI?"
27
+
28
+ ## Step 2: Create an OpenAI account (if needed)
29
+
30
+ > "If you don't already have an OpenAI account:
31
+ >
32
+ > 1. Go to **platform.openai.com** in your browser
33
+ > 2. Click **Sign up**
34
+ > 3. You can sign up with Google, Microsoft, Apple, or an email address
35
+ > 4. Complete the verification steps
36
+ >
37
+ > Let me know when you're logged in."
38
+
39
+ ## Step 3: Set up billing
40
+
41
+ > "Before an API key will work, you need billing set up:
42
+ >
43
+ > 1. On **platform.openai.com**, click your profile icon (top-right) → **Settings**
44
+ > 2. In the left sidebar, click **Billing**
45
+ > 3. Add a payment method (credit card or debit card)
46
+ > 4. Add some credit — $5 or $10 is plenty to start
47
+ >
48
+ > Let me know when billing is set up."
49
+
50
+ If the user already has billing:
51
+
52
+ > "Great — skip ahead to the next step."
53
+
54
+ ## Step 4: Get an API key
55
+
56
+ > "Now let's get your API key:
57
+ >
58
+ > 1. Go to **platform.openai.com/api-keys** in your browser
59
+ > 2. Click **Create new secret key**
60
+ > 3. Give it a name like **Taskmaster**
61
+ > 4. Click **Create secret key**
62
+ > 5. Copy the key — it starts with **sk-** and is quite long
63
+ >
64
+ > **Copy it now** — OpenAI only shows the full key once. If you lose it, you'll need to create a new one.
65
+ >
66
+ > Send me the key when you have it."
67
+
68
+ If the user can't find the API keys page:
69
+
70
+ > "On platform.openai.com, click your profile icon in the top-right corner, then go to **Settings** → **API keys** in the left sidebar. Or go directly to **platform.openai.com/api-keys**."
71
+
72
+ ## Step 5: Verify the key format
73
+
74
+ When the user sends a key, verify it looks correct:
75
+
76
+ - Starts with `sk-`
77
+ - Usually 50+ characters long
78
+
79
+ If it doesn't match:
80
+
81
+ > "That doesn't look like an OpenAI API key — it should start with **sk-** and be quite long. Can you check you copied the full key?"
82
+
83
+ ## Step 6: Store the key
84
+
85
+ Use the `api_keys` tool to store the key:
86
+
87
+ ```
88
+ api_keys({ action: "set", provider: "openai", apiKey: "<the key>" })
89
+ ```
90
+
91
+ The key is applied immediately — no restart needed. Confirm to the user:
92
+
93
+ > "Done — I've saved your OpenAI API key. GPT models are now available as an alternative AI provider."
94
+
95
+ ---
96
+
97
+ ## If the user already has an OpenAI key configured
98
+
99
+ > "You already have an OpenAI key set up. Would you like to replace it with a new key, or is there something else I can help with?"
100
+
101
+ ---
102
+
103
+ ## Troubleshooting
104
+
105
+ | Problem | Solution |
106
+ |---------|----------|
107
+ | Key rejected or doesn't work | Check that billing is set up on platform.openai.com. API keys don't work without an active billing method, even on free tier. |
108
+ | "You exceeded your current quota" | The account has run out of credit. Add more credit under Settings → Billing on platform.openai.com. |
109
+ | Can't find API keys page | Go directly to platform.openai.com/api-keys, or use the profile menu → Settings → API keys. |
110
+ | "Create new secret key" button is greyed out | The account may have hit its key limit. Delete an unused key first, or check account permissions. |
111
+
112
+ ---
113
+
114
+ ## Common questions
115
+
116
+ | Question | Answer |
117
+ |----------|--------|
118
+ | "Do I need OpenAI if I have Claude?" | No — Claude handles everything. OpenAI is optional, as a fallback or alternative. |
119
+ | "How much does it cost?" | OpenAI charges per API call. For small business use, typical costs are a few dollars per month. See openai.com/pricing for current rates. |
120
+ | "Do I need to restart?" | No — the key is applied immediately. |
121
+ | "Can I use this for ChatGPT Plus?" | No — ChatGPT Plus is a separate subscription for chat.openai.com. API keys are for the developer platform and are billed separately. |
122
+ | "Which GPT model will it use?" | Taskmaster selects the best available model automatically based on your configuration. |
@@ -144,7 +144,7 @@ After setup, you'll see a navigation bar at the top of the screen linking to all
144
144
  | **Contacts** | Manage verified contact records (payment status, account details) that your assistant can look up but not change |
145
145
  | **Files** | Browse and manage your assistant's knowledge files and memory |
146
146
  | **Browser** | See what the assistant sees when it browses the web for you |
147
- | **Advanced** | View events (automated tasks), sessions, skills, and logs |
147
+ | **Advanced** | Opening hours, events (automated tasks), skills, and logs |
148
148
 
149
149
  You'll land on the Setup page by default. From there, the nav bar takes you anywhere.
150
150
 
@@ -568,6 +568,7 @@ Your assistant can check and manage many system settings directly through chat
568
568
  | Channel settings | Change the AI model, thinking level, DM policy, or group chat policy for your WhatsApp accounts |
569
569
  | Branding | Update your accent or background colour |
570
570
  | Public chat | Enable or disable the public chat widget, change the greeting, set visitor verification |
571
+ | Opening hours | Check, set, or toggle business opening hours |
571
572
  | Skills | List, create, delete, or toggle skills |
572
573
  | Logs | Review system and session logs for troubleshooting |
573
574
 
@@ -577,6 +578,8 @@ Your assistant can check and manage many system settings directly through chat
577
578
  - "Is WhatsApp connected?"
578
579
  - "Switch WhatsApp to a cheaper model"
579
580
  - "Change the accent colour to blue"
581
+ - "Set opening hours to Mon-Fri 9am to 5pm"
582
+ - "Are we currently open?"
580
583
  - "Enable public chat"
581
584
  - "Show me the recent logs"
582
585
 
@@ -828,7 +831,33 @@ To remove all custom branding and return to the default colours, open the Brandi
828
831
 
829
832
  ## Advanced
830
833
 
831
- The **Advanced** page has four tabs for monitoring and managing your assistant behind the scenes. You don't need these day-to-day, but they're useful when you want to see what's happening under the hood.
834
+ The **Advanced** page has five tabs for monitoring and managing your assistant behind the scenes. You don't need these day-to-day, but they're useful when you want to see what's happening under the hood.
835
+
836
+ ### Opening Hours
837
+
838
+ The Opening Hours tab has two independent switches that control when your public assistant responds to customers:
839
+
840
+ - **Public agent responds** — master switch. Turn this off to silence the assistant entirely, regardless of schedule. Useful when you want to handle all messages manually for a while.
841
+ - **Enable opening hours** — schedule gate. When on, the assistant only responds during the hours you configure. Outside those hours it goes fully silent — no reply, no read receipt, no acknowledgement.
842
+
843
+ To set up a schedule:
844
+
845
+ 1. Go to the **Advanced** page and select the **Opening Hours** tab
846
+ 2. Make sure **Public agent responds** is on
847
+ 3. Toggle **Enable opening hours** on
848
+ 4. Set the **weekly schedule** — for each day, enter opening and closing times (e.g., 09:00–17:00), or tick **Closed** to mark the day as fully closed
849
+ 5. Optionally add **closed dates** for specific days (e.g., bank holidays, annual leave)
850
+ 6. Tap **Save**
851
+
852
+ Changes take effect on the next incoming message — no restart needed. Times are in your local timezone — the system detects it automatically.
853
+
854
+ **What happens when the assistant is silent (agent off or outside hours):**
855
+
856
+ - Customer messages on WhatsApp stay as "delivered" (grey ticks) — read receipts are suppressed so customers don't see "read" with no reply
857
+ - Messages are stored in the conversation history so the assistant picks up context when it resumes
858
+ - If you reply manually via WhatsApp, the assistant is aware of your reply and won't contradict it when it resumes
859
+
860
+ You can also ask your admin assistant to check or change these settings in chat using the `opening_hours` command.
832
861
 
833
862
  ### Events
834
863