Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.
Shell agent-teamsai-agentai-automationanthropicautonomous-agentawsbusiness-operationsclaudeclaude-codeclaude-code-plugindevopsecommerceinbox-zeroklaviyomarketingmcpmorning-briefingpr-automationshopifyterminal
docs: add full project documentation suite
auroracapital1cb6ef1acc9b
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdnew file mode 100644index 00000000..1ce105a7--- /dev/null+++ b/docs/ARCHITECTURE.md@@ -0,0 +1,141 @@+<!-- generated-by: gsd-doc-writer -->+# Architecture++claude-ops is a Claude Code plugin (v0.8.0) that installs as a business operating system on top of the Claude Code CLI. It exposes 22 slash-command skills that orchestrate 12 autonomous agents, a persistent background daemon, and a bundled Telegram MCP server. The primary inputs are tool calls from Claude Code sessions; the primary outputs are structured reports, drafted communications, and autonomous code/infrastructure actions executed via shell and API calls.++---++## Component Diagram++```mermaid+graph TD+ User["User (Claude Code session)"]+ Skills["Skills Layer\n22 slash commands\nskills/<name>/SKILL.md"]+ Agents["Agents Layer\n12 autonomous agents\nagents/<name>.md"]+ Daemon["ops-daemon\nlaunchd-managed\nscripts/ops-daemon.sh"]+ Hooks["Hooks\nhooks/hooks.json"]+ Bin["Bin Scripts\nbin/ops-*"]+ TelegramMCP["Telegram MCP Server\ntelegram-server/index.js"]+ Registry["Project Registry\nscripts/registry.json"]+ Cache["Daemon Cache\n~/.claude/plugins/data/.../daemon-cache.json"]+ Prefs["User Preferences\nplugin.json userConfig"]+ Secrets["Secrets (Doppler / 1Password / env)"]++ User -->|slash command| Skills+ Skills -->|spawn| Agents+ Skills -->|read| Registry+ Skills -->|read| Cache+ Skills -->|call| Bin+ Agents -->|Bash + tool calls| Bin+ Daemon -->|writes| Cache+ Daemon -->|runs| Bin+ Hooks -->|PreToolUse / SessionStart / Stop| Skills+ TelegramMCP -->|MCP protocol| Skills+ Prefs -->|userConfig injection| Skills+ Secrets -->|env vars| Bin+ Secrets -->|env vars| TelegramMCP+```++---++## Data Flow++A typical `/ops:go` morning briefing flows as follows:++1. **SessionStart hook** — `hooks/hooks.json` fires `bin/ops-welcome` (displays setup status) and `scripts/setup.sh` (surfaces any unresolved configuration issues).+2. **Skill invocation** — the user runs `/ops:go`; the `skills/ops-go/SKILL.md` skill is loaded by Claude Code.+3. **Cache read** — the skill calls `bin/ops-gather` (or reads the pre-warmed `daemon-cache.json` written by the daemon's `briefing-pre-warm` service every 2 minutes).+4. **Agent fan-out (optional)** — for deeper analysis (`/ops:yolo`), the skill spawns 4 parallel agents (CEO, CTO, CFO, COO) via the Claude Agent SDK. Each agent runs independently using `claude-opus-4-6` and writes its analysis to a temp file.+5. **Merge + present** — the main skill orchestrator reads all agent output files, merges them into a unified report, and returns it to the user in the Claude Code session.+6. **Stop hook** — `bin/ops-post-session-cleanup` runs on session end to clean up temp files and stale PIDs.++For communication skills (`/ops:inbox`, `/ops:comms`), a PreToolUse hook (`bin/ops-pretool-wacli-health`) checks the WhatsApp daemon health file before any `wacli` Bash call and surfaces a warning if the sync is stale (>10 min).++---++## Key Abstractions++| Abstraction | Location | Description |+|-------------|----------|-------------|+| `plugin.json` | `claude-ops/.claude-plugin/plugin.json` | Plugin manifest: name, version, `userConfig` schema (20 configurable keys), MCP server declarations |+| `SKILL.md` | `claude-ops/skills/<name>/SKILL.md` | Each skill is a markdown prompt file loaded by Claude Code as a slash command |+| Agent `.md` files | `claude-ops/agents/<name>.md` | Each agent is a markdown prompt file with frontmatter declaring model, effort, maxTurns, and memory scope |+| `hooks.json` | `claude-ops/hooks/hooks.json` | Declares SessionStart, PreToolUse (Bash matcher), and Stop lifecycle hooks |+| `registry.json` | `claude-ops/scripts/registry.json` | User-maintained project index with alias, repo, infra platform, revenue model, and GSD flag per project |+| `ops-daemon.sh` | `claude-ops/scripts/ops-daemon.sh` | Shell supervisor for 7 persistent background services; managed via launchd |+| `daemon-cache.json` | `~/.claude/plugins/data/.../daemon-cache.json` | Pre-warmed briefing data written by `briefing-pre-warm` every 2 min; read by `/ops:go` for <3s load |+| `CLAUDE.md` | `claude-ops/CLAUDE.md` | Plugin-root rules (Rules 0–5) that override individual skill instructions for all agents |+| Telegram MCP server | `claude-ops/telegram-server/index.js` | Node.js MCP server providing MTProto user-auth Telegram access (personal account, not bot API) |++---++## Directory Structure Rationale++```+claude-ops/+├── .claude-plugin/+│ └── plugin.json # Plugin manifest and userConfig schema+├── agents/ # 12 agent prompt files (.md) — spawned by skills+├── bin/ # 22 shell/node scripts (ops-*) — the executable layer+├── docs/ # Reference documentation for plugin internals+├── hooks/+│ └── hooks.json # Lifecycle hook declarations (SessionStart, PreToolUse, Stop)+├── output-styles/ # Output formatting guides used by skills+├── scripts/ # Daemon, cron jobs, setup wizard, project registry+├── skills/ # 22 skill directories, each containing a SKILL.md prompt+├── telegram-server/ # Bundled MCP server for Telegram MTProto access+├── tests/ # Bash test suite (no-secrets, skills-lint, hooks, bin-scripts)+├── CHANGELOG.md # Version history+├── CLAUDE.md # Plugin-root rules applied to all skills and agents+├── LICENSE # MIT+└── package.json # Runtime deps for bin .mjs scripts (telegram, playwright)+```++- **`skills/`** — User-facing layer. Each subdirectory is one slash command. Skills are markdown prompt files; they contain no executable code, only instructions for Claude.+- **`agents/`** — Background worker layer. Agent `.md` files are spawned by skills using the Claude Agent SDK. They have declared resource budgets (model, maxTurns, effort) and memory scopes.+- **`bin/`** — Executable layer. Shell and Node.js scripts that interact with external CLIs (`wacli`, `aws`, `gh`, `doppler`, `gog`) and APIs. Skills and agents call these via Bash tool calls.+- **`scripts/`** — Infrastructure layer. The daemon supervisor, launchd plists, cron scripts, and the project registry live here.+- **`telegram-server/`** — Bundled MCP server. Provides Telegram access via MTProto (personal account authentication, not bot tokens). Declared in `.mcp.json` and auto-started by Claude Code.+- **`hooks/`** — Automation layer. Three lifecycle hooks: SessionStart (welcome + setup check), PreToolUse/Bash (WhatsApp health check), and Stop (cleanup).+- **`tests/`** — Validation layer. Bash scripts that check for committed secrets, skill markdown lint, hook schema validity, and bin script executability. Run via `tests/run-all.sh`.++---++## Daemon Architecture++The `ops-daemon` is a launchd-managed supervisor that runs 7 background services continuously:++| Service | Cadence | Purpose |+|---------|---------|---------|+| `briefing-pre-warm` | every 2 min | Runs `bin/ops-gather` to keep `/ops:go` cache hot |+| `wacli-sync` | persistent | Keeps WhatsApp connected via wacli, auto-reconnects |+| `memory-extractor` | every 30 min | Spawns `memory-extractor` agent to refresh `memories/` |+| `inbox-digest` | every 15 min | Pre-classifies communications across all channels |+| `store-health` | every 10 min | Shopify orders and inventory polling (if configured) |+| `competitor-intel` | hourly | Background market and competitor monitoring |+| `message-listener` | persistent | Surfaces urgent patterns ("urgent", "ASAP", "fire", "down") |++The daemon installs at setup Step 2c — deliberately early — so the briefing cache is pre-warmed while the user completes the remaining integration configuration steps.++---++## Agent Model Assignments++| Agent class | Model | Use case |+|-------------|-------|----------|+| C-suite analysts (`yolo-ceo`, `yolo-cto`, `yolo-cfo`, `yolo-coo`) | `claude-opus-4-6` | High-depth strategic, technical, financial, operational analysis |+| Scanner, fix, and daemon agents | `claude-sonnet-4-6` | Efficient read-scan-report loops and targeted code fixes |+| `memory-extractor` | `claude-haiku-4-5-20251001` | High-frequency (every 30 min) low-cost contact extraction |++---++## Plugin Rule Enforcement++`claude-ops/CLAUDE.md` defines 6 rules (Rule 0 through Rule 5) that apply to every skill and agent in the plugin, overriding any conflicting instruction in individual files:++- **Rule 0** — No personal data ever committed (public open-source repo)+- **Rule 1** — Maximum 4 options per `AskUserQuestion` call+- **Rule 2** — Never delegate commands to the user; use Bash tool instead+- **Rule 3** — Never auto-skip channels or integrations during setup+- **Rule 4** — Background by default during setup and configuration flows+- **Rule 5** — Destructive actions require explicit per-action confirmationdiff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdnew file mode 100644index 00000000..d76cc2da--- /dev/null+++ b/docs/CONFIGURATION.md@@ -0,0 +1,227 @@+<!-- generated-by: gsd-doc-writer -->+# Configuration++claude-ops has four distinct layers of configuration: plugin `userConfig` fields set inside Claude Code, a project registry file, a daemon services file, and a runtime preferences file written by the setup wizard. This document covers all four.++---++## Plugin Settings (`userConfig`)++These fields are set through the Claude Code plugin UI (`/plugin` → `ops` → Settings) or via `/ops:setup`. They map directly to the `userConfig` schema in `.claude-plugin/plugin.json`. Sensitive values are stored encrypted by Claude Code and are never written to disk in plaintext.++| Field | Required | Default | Description |+|---|---|---|---|+| `telegram_api_id` | Optional | `""` | Numeric API ID from [my.telegram.org/apps](https://my.telegram.org/apps). Run `/ops:setup telegram` to auto-configure. |+| `telegram_api_hash` | Optional | `""` | API hash from [my.telegram.org/apps](https://my.telegram.org/apps). Run `/ops:setup telegram` to auto-configure. |+| `telegram_phone` | Optional | `""` | Your Telegram phone number in E.164 format (e.g. `+14155550100`). |+| `telegram_session` | Optional | `""` | gram.js `StringSession` token. Generated automatically by `/ops:setup telegram`. |+| `sentry_org` | Optional | `""` | Sentry organization slug (e.g. `my-org`). Used by `/ops:triage` and `/ops:fires`. |+| `linear_team` | Optional | `""` | Default Linear team key (e.g. `HEA`). Used by `/ops:linear`. |+| `aws_region` | Optional | `us-east-1` | Default AWS region for infra checks. Used by `/ops:deploy`, `/ops:fires`, `/ops:revenue`. |+| `klaviyo_private_key` | Optional | `""` | Private API key from Klaviyo Settings → API Keys (starts with `pk_` or `ck_`). Used by `/ops:marketing`. |+| `meta_ads_token` | Optional | `""` | Meta Marketing API access token from Facebook Business. Used by `/ops:marketing`. |+| `meta_ad_account_id` | Optional | `""` | Meta ad account ID in `act_XXXXXXXXX` format. Used by `/ops:marketing`. |+| `ga4_property_id` | Optional | `""` | GA4 property ID (numeric, from Admin → Property Settings). Used by `/ops:marketing`. |+| `google_search_console_site` | Optional | `""` | Site URL as registered in Google Search Console (e.g. `https://example.com`). |+| `shopify_store_url` | Optional | `""` | Shopify store URL (e.g. `mystore.myshopify.com`). Used by `/ops:ecom`. |+| `shopify_admin_token` | Optional | `""` | Shopify Admin API access token from Shopify Partners or a custom app. Used by `/ops:ecom`. |+| `shipbob_access_token` | Optional | `""` | ShipBob Personal Access Token for fulfillment tracking. Used by `/ops:ecom`. |+| `bland_ai_api_key` | Optional | `""` | API key from [app.bland.ai](https://app.bland.ai). Used by `/ops:voice` for outbound calls. |+| `elevenlabs_api_key` | Optional | `""` | API key from [elevenlabs.io](https://elevenlabs.io). Used by `/ops:voice` for TTS. |+| `groq_api_key` | Optional | `""` | API key from [console.groq.com](https://console.groq.com). Used by `/ops:voice` for Whisper transcription. |+| `stripe_secret_key` | Optional | `""` | Stripe secret key (`sk_live_...` or `sk_test_...`). Prefer a Doppler reference. Used by `/ops:revenue`. |+| `revenuecat_api_key` | Optional | `""` | RevenueCat V1 API key for mobile subscription revenue tracking. Used by `/ops:revenue`. |+| `revenuecat_project_id` | Optional | `""` | RevenueCat project ID (visible in the app.revenuecat.com URL). Used by `/ops:revenue`. |++**Sensitive fields** (`telegram_api_id`, `telegram_api_hash`, `telegram_phone`, `telegram_session`, `klaviyo_private_key`, `meta_ads_token`, `shopify_admin_token`, `shipbob_access_token`, `bland_ai_api_key`, `elevenlabs_api_key`, `groq_api_key`, `stripe_secret_key`, `revenuecat_api_key`) are marked `"sensitive": true` in the schema and are encrypted at rest by Claude Code.++---++## Telegram MCP Server (`.mcp.json`)++The bundled Telegram MCP server is wired in `.mcp.json` at the plugin root. It reads all four Telegram credentials directly from `userConfig` at runtime — no manual file editing is required.++```json+{+ "mcpServers": {+ "telegram": {+ "command": "node",+ "args": ["${CLAUDE_PLUGIN_ROOT}/telegram-server/index.js"],+ "env": {+ "TELEGRAM_API_ID": "${user_config.telegram_api_id}",+ "TELEGRAM_API_HASH": "${user_config.telegram_api_hash}",+ "TELEGRAM_PHONE": "${user_config.telegram_phone}",+ "TELEGRAM_SESSION": "${user_config.telegram_session}"+ }+ }+ }+}+```++`CLAUDE_PLUGIN_ROOT` is resolved at runtime to the plugin's installed cache directory. It is also exported into your shell profile by `/ops:setup` so shell scripts can reference it.++---++## Project Registry (`scripts/registry.json`)++The registry tells every skill which projects you own, where they live on disk, and how they are deployed. It is **gitignored** — copy `scripts/registry.example.json` to `scripts/registry.json` and fill in your values.++```json+{+ "version": "1.0",+ "owner": "Your Name",+ "projects": [+ {+ "alias": "my-app",+ "paths": ["~/Projects/my-app"],+ "repos": ["your-org/my-app"],+ "org": "your-org",+ "type": "monorepo",+ "infra": {+ "platform": "vercel"+ },+ "revenue": { "model": "saas", "stage": "pre-launch" },+ "gsd": true,+ "priority": 1+ },+ {+ "alias": "my-api",+ "paths": ["~/Projects/my-api"],+ "repos": ["your-org/my-api"],+ "org": "your-org",+ "type": "monorepo",+ "infra": {+ "ecs_clusters": ["my-api-production", "my-api-staging"],+ "platform": "aws"+ },+ "revenue": { "model": "saas", "stage": "growth" },+ "gsd": true,+ "priority": 2+ }+ ]+}+```++### Registry fields++| Field | Required | Description |+|---|---|---|+| `version` | Required | Schema version. Always `"1.0"`. |+| `owner` | Required | Your display name, used in briefing headings. |+| `projects[].alias` | Required | Short name used in skill commands (e.g. `/ops:fires my-api`). |+| `projects[].paths` | Required | Array of local directory paths for this project. Multi-repo projects list multiple paths. |+| `projects[].repos` | Required | Array of `org/repo` slugs on GitHub. |+| `projects[].org` | Required | GitHub org or username. |+| `projects[].type` | Required | `"monorepo"` or `"multi-repo"`. |+| `projects[].infra.platform` | Optional | `"aws"` or `"vercel"`. Determines which deploy checks run. |+| `projects[].infra.ecs_clusters` | Optional | Array of ECS cluster names (AWS only). Used by `/ops:deploy` and `/ops:fires`. |+| `projects[].revenue.model` | Optional | `"saas"`, `"subscription"`, `"ecom"`, etc. |+| `projects[].revenue.stage` | Optional | `"pre-launch"`, `"growth"`, etc. Shown in `/ops:revenue`. |+| `projects[].revenue.mrr` | Optional | Current MRR in USD. Used in revenue dashboard. |+| `projects[].gsd` | Optional | `true` if the project uses GSD planning. Enables GSD phase display in `/ops:projects`. |+| `projects[].priority` | Optional | Integer. Skills process projects in ascending priority order. |++The interactive wizard (`/ops:setup registry`) builds this file project-by-project via structured prompts.++---++## Daemon Services (`scripts/daemon-services.example.json`)++The ops-daemon is managed by launchd and runs shell services on cron schedules or as persistent processes. To customize which services run, copy `scripts/daemon-services.example.json` to `~/.claude/plugins/data/ops-ops-marketplace/daemon-services.json`.++**All optional services are disabled by default in the example file.** The `wacli-sync` service is enabled; `memory-extractor` is **disabled** and must be explicitly enabled.++### Available services++| Service | Default | Type | Schedule | Notes |+|---|---|---|---|---|+| `wacli-sync` | **enabled** | persistent | — | Keeps WhatsApp connected. Restarts up to 10 times with a 60 s delay. Requires `wacli` installed. |+| `memory-extractor` | **disabled** | cron + persistent | every 30 min | Extracts contact profiles and conversation context via a background Haiku agent. |+| `inbox-digest` | disabled | cron | every 4 hours | Sends an inbox summary to Telegram. Requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, and `gog` for email. |+| `store-health` | disabled | cron | daily at 09:00 | Sends Shopify store health report to Telegram. Requires `SHOPIFY_STOREFRONT_TOKEN`, `SHOPIFY_STORE_DOMAIN`, `TELEGRAM_BOT_TOKEN`. |+| `competitor-intel` | disabled | cron | Mondays at 10:00 | Weekly competitor research delivered to Telegram. Requires `TELEGRAM_BOT_TOKEN`. Optional: `TAVILY_API_KEY`. |+| `message-listener` | disabled | persistent | — | Listens for incoming messages and triggers responses. Requires `wacli`. Optional: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_OWNER_ID`. Restarts up to 20 times with a 30 s delay. |++### Service schema++```json+{+ "services": {+ "memory-extractor": {+ "enabled": false,+ "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ops-memory-extractor.sh",+ "health_file": "~/.claude/plugins/data/ops-ops-marketplace/memories/.health",+ "restart_delay": 3600,+ "cron": "*/30 * * * *"+ }+ }+}+```++| Field | Description |+|---|---|+| `enabled` | `true` to activate the service. `false` to disable (daemon ignores it). |+| `command` | Shell command to run. Use `${CLAUDE_PLUGIN_ROOT}` for portability. |+| `cron` | Cron expression for scheduled services. Omit for persistent services. |+| `health_file` | Path the service writes to signal it is healthy. Read by the daemon for restart decisions. |+| `restart_delay` | Seconds to wait before restarting a crashed service. |+| `max_restarts` | Maximum restart attempts before the daemon gives up. |++The default daemon configuration (before any user customization) is in `scripts/daemon-services.default.json`. It enables `briefing-pre-warm`, `wacli-sync`, and `memory-extractor` — but the **user-facing example disables `memory-extractor`** so it is opt-in.++The `_variables` block in the example documents two runtime substitution variables:++- `CLAUDE_PLUGIN_ROOT` — resolved at runtime to the plugin install directory.+- `OPS_DATA_DIR` — overrides the default data directory (`~/.claude/plugins/data/ops-ops-marketplace`).++---++## Runtime Preferences (`preferences.json`)++The `/ops:setup` wizard writes a `preferences.json` file to `~/.claude/plugins/data/ops-ops-marketplace/preferences.json`. This file is **outside the plugin source tree** and survives plugin reinstalls and version bumps. It stores your display name, timezone, briefing verbosity, default channels, and channel-specific tokens that are not managed through plugin `userConfig`.++<!-- VERIFY: Full schema of preferences.json — fields written by /ops:setup are not documented in the repository source files accessible here. -->++---++## Hooks (`hooks/hooks.json`)++Three Claude Code lifecycle hooks are registered automatically when the plugin is installed.++| Hook | Trigger | Command |+|---|---|---|+| `SessionStart` | Every new Claude Code session | `ops-welcome` — shows a startup dashboard; `setup.sh` — prints any unresolved config issues (first 3 lines). |+| `PreToolUse` (Bash matcher) | Before every `Bash` tool call | `ops-pretool-wacli-health` — checks WhatsApp connection health before any shell command runs. |+| `Stop` | Session end | `ops-post-session-cleanup` — runs cleanup tasks after the session closes. |++Hooks are wired via `hooks/hooks.json` and reference scripts via `${CLAUDE_PLUGIN_ROOT}`. No user configuration is required.++---++## Environment Variables (daemon cron services)++These environment variables are read by optional cron service shell scripts. They are not managed by plugin `userConfig` and must be available in the daemon's shell environment (e.g. via Doppler, your shell profile, or a secrets manager).++| Variable | Required by | Description |+|---|---|---|+| `TELEGRAM_BOT_TOKEN` | `inbox-digest`, `store-health`, `competitor-intel`, `message-listener` | Telegram Bot API token for sending notifications. |+| `TELEGRAM_CHAT_ID` | `inbox-digest` | Telegram chat ID to send the inbox digest to. |+| `TELEGRAM_OWNER_ID` | `message-listener` | Optional. Telegram user ID of the owner for message routing. |+| `SHOPIFY_STOREFRONT_TOKEN` | `store-health` | Shopify Storefront API token. |+| `SHOPIFY_STORE_DOMAIN` | `store-health` | Shopify store domain (e.g. `mystore.myshopify.com`). |+| `TAVILY_API_KEY` | `competitor-intel` | Optional. Improves web search quality for competitor research. |+| `CLAUDE_PLUGIN_ROOT` | All daemon scripts | Path to the plugin install directory. Exported by `/ops:setup`. |++---++## Per-Environment Overrides++claude-ops does not use `.env` files. All secrets resolve through the following chain in priority order:++1. **Doppler** — if `doppler` CLI is installed and configured, `/ops:setup` will link it. Skills read secrets via `doppler run --` or environment injection.+2. **Password manager** — 1Password (`op`), Dashlane (`dcli`), or Bitwarden (`bw`) vaults are scanned by `/ops:setup` during credential collection.+3. **macOS Keychain** — the Telegram wizard stores `api_id`, `api_hash`, `phone`, and `session` in the system keychain automatically.+4. **Plugin `userConfig`** — values set in Claude Code plugin settings (see Plugin Settings section above).+5. **Shell environment** — variables exported in your shell profile (e.g. `~/.zshrc`).++For production deployments, Doppler is the recommended secrets source. Skills degrade gracefully when optional credentials are absent — features that require a missing credential are skipped rather than erroring.diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.mdnew file mode 100644index 00000000..819d5fd2--- /dev/null+++ b/docs/DEVELOPMENT.md@@ -0,0 +1,335 @@+<!-- generated-by: gsd-doc-writer -->+# Development Guide++This guide covers everything you need to contribute to claude-ops — from understanding the nested directory layout to adding new skills, agents, and bin scripts.++---++## Local Setup++```bash+git clone https://github.com/Lifecycle-Innovations-Limited/claude-ops.git+cd claude-ops++# Load the plugin directly from the local checkout+claude --plugin-dir ./claude-ops/claude-ops+```++After making any change to a skill, agent, hook, or CLAUDE.md, reload without restarting Claude Code:++```bash+/reload-plugins+```++No additional install step is required for the plugin itself. The `claude-ops/node_modules/` directory (used by the `.mjs` autolink scripts) is committed, so no `npm install` is needed unless you are adding new bin-script dependencies.++---++## Repo Structure++The repository uses a two-level layout required by the Claude Code plugin marketplace:++```+claude-ops/ ← marketplace root (the GitHub repo)+├── .claude-plugin/+│ └── marketplace.json # points "source" to ./claude-ops+├── README.md+├── CONTRIBUTING.md+├── LICENSE+├── SECURITY.md+│+└── claude-ops/ ← plugin root (Claude Code loads from here)+ ├── .claude-plugin/plugin.json # plugin manifest (name, version, userConfig)+ ├── CLAUDE.md # 6 non-negotiable plugin rules (Rule 0–5)+ ├── skills/ # 22 slash commands — one subdirectory per skill+ ├── agents/ # 12 autonomous agents (Opus/Sonnet/Haiku)+ ├── bin/ # ops-* shell scripts called by skills+ ├── hooks/+ │ └── hooks.json # SessionStart / PreToolUse / Stop hooks+ ├── scripts/ # daemon plists, cron scripts, registry.json+ ├── telegram-server/ # bundled MTProto MCP server (gram.js)+ ├── templates/ # Shopify Admin scaffolding+ ├── tests/ # bash validation suites+ ├── output-styles/ # reusable output format templates+ ├── node_modules/ # runtime deps for .mjs autolink scripts+ └── package.json # claude-ops-bin v0.2.2+```++**Why the nested `claude-ops/claude-ops/` layout?** Claude Code's marketplace resolves the plugin root from the `"source"` field in `marketplace.json`. The outer directory is the marketplace container; the inner directory is what Claude Code actually loads. This cannot be flattened — the marketplace system requires exactly this two-level structure.++---++## Adding a Skill++Each skill is a subdirectory under `claude-ops/claude-ops/skills/` containing a single `SKILL.md` file.++```+skills/+└── ops-myfeature/+ └── SKILL.md+```++`SKILL.md` format (YAML frontmatter + markdown body):++```markdown+---+name: ops-myfeature+description: One-sentence description shown in the skills list.+argument-hint: "[optional-arg]"+allowed-tools:+ - Bash+ - Read+ - Grep+ - Glob+ - AskUserQuestion+effort: low # low | medium | high+maxTurns: 20+---++# OPS ► MY FEATURE++Skill body — instructions Claude follows when this slash command is invoked.+```++**Key frontmatter fields:**++| Field | Required | Notes |+|---|---|---|+| `name` | Yes | Must match the directory name exactly |+| `description` | Yes | Shown in `/ops` dashboard |+| `allowed-tools` | Yes | Allowlist of Claude tools the skill can use |+| `effort` | No | `low` / `medium` / `high` — controls token budget hint |+| `maxTurns` | No | Hard turn limit for the skill |+| `argument-hint` | No | Displayed after the slash command in autocomplete |++After adding a skill, run `/reload-plugins` and verify it appears in `/ops`.++---++## Adding an Agent++Agents live under `claude-ops/claude-ops/agents/` as individual `.md` files:++```+agents/+└── my-agent.md+```++Agent `.md` format:++```markdown+---+name: my-agent+description: What this agent does and when it is invoked.+model: claude-sonnet-4-6 # claude-opus-4-6 | claude-sonnet-4-6 | claude-haiku-4-5+effort: medium+maxTurns: 25+tools:+ - Bash+ - Read+ - Grep+disallowedTools:+ - Write+ - Edit+ - Agent+memory: project # project | user | none+---++# MY AGENT++Agent instructions here.+```++**Model selection convention:**+- `claude-opus-4-6` — C-suite agents (`yolo-ceo`, `yolo-cfo`, `yolo-coo`, `yolo-cto`)+- `claude-sonnet-4-6` — Scanner, monitor, and fix agents+- `claude-haiku-4-5` — High-frequency lightweight agents (memory extraction)++Agents are invoked from skills via the `Agent` tool. They never call other agents (note `Agent` in `disallowedTools` for most agents — this prevents recursive spawning).++---++## Adding a Bin Script++Bin scripts live under `claude-ops/claude-ops/bin/` and are called directly by skills via the `Bash` tool or from `hooks.json`.++**Naming convention:** all scripts use the `ops-` prefix (e.g., `ops-gather`, `ops-prs`, `ops-infra`).++**Standard structure:**++```bash+#!/usr/bin/env bash+# ops-myscript — Short description of what this script does+# Usage: ops-myscript [--json] [args...]++set -euo pipefail++SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"++# ... implementation ...++# Output: emit JSON to stdout+jq -n --arg key "value" '{"key": $key}'+```++**`--json` convention:** scripts that can be called in two modes (human-readable summary vs. machine-readable data) accept a `--json` flag. When present, output is pure JSON consumed by `ops-gather` or skills. Without the flag, output is formatted for direct terminal display.++`ops-gather` runs all data-collecting scripts in parallel and merges their JSON output into a single payload:++```bash+"$SCRIPT_DIR/ops-git" > "$TMPDIR_OPS/git.json" 2>/dev/null &+"$SCRIPT_DIR/ops-infra" > "$TMPDIR_OPS/infra.json" 2>/dev/null &+"$SCRIPT_DIR/ops-prs" > "$TMPDIR_OPS/prs.json" 2>/dev/null &+wait+```++New data-gathering scripts should be added to `ops-gather` so they are included in pre-warm briefing data.++---++## Hooks++Hooks are declared in `claude-ops/claude-ops/hooks/hooks.json`. Three event types are supported:++```json+{+ "hooks": {+ "SessionStart": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/ops-welcome 2>/dev/null || true"+ },+ {+ "type": "command",+ "command": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh 2>/dev/null | grep '✗' | head -3 || true"+ }+ ]+ }+ ],+ "PreToolUse": [+ {+ "matcher": "Bash",+ "hooks": [+ {+ "type": "command",+ "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/ops-pretool-wacli-health \"$TOOL_INPUT\" 2>/dev/null || true"+ }+ ]+ }+ ],+ "Stop": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/ops-post-session-cleanup 2>/dev/null || true"+ }+ ]+ }+ ]+ }+}+```++| Event | Matcher | Current use |+|---|---|---|+| `SessionStart` | (all) | Run `ops-welcome` banner + surface any setup health failures |+| `PreToolUse` | `Bash` | Check wacli health before any Bash call |+| `Stop` | (all) | Post-session cleanup |++Hook commands must always exit `0` (note the `|| true` suffix). A failing hook causes Claude Code to surface an error — never let hooks fail loudly.++The `$CLAUDE_PLUGIN_ROOT` environment variable is injected by Claude Code at runtime and resolves to the `claude-ops/claude-ops/` directory.++---++## CLAUDE.md Rules++`claude-ops/claude-ops/CLAUDE.md` defines six rules that apply to every skill and agent. They cannot be overridden by individual skill instructions.++| Rule | Name | Summary |+|---|---|---|+| Rule 0 | PUBLIC REPO — No personal data ever | Never commit real names, emails, tokens, org names, store URLs, or hardcoded paths. Use placeholders (`owner`, `[email protected]`, `<YOUR_TOKEN>`). Run `tests/test-no-secrets.sh` before every commit. |+| Rule 1 | Max 4 options per AskUserQuestion | The `AskUserQuestion` tool enforces a hard limit of `<=4` items. Paginate larger lists at 4 per page using `[More options...]` as a bridge. |+| Rule 2 | Never delegate commands to the user | Run all commands via the `Bash` tool. Use `run_in_background: true` for OAuth flows and long-running installs. The only exception is QR-based auth (`wacli auth`). |+| Rule 3 | Never auto-skip channels or integrations | If auto-scan returns empty for a credential, always present an explicit `AskUserQuestion` with `[Paste manually]`, `[Deep hunt]`, `[Skip]`. Never silently skip. |+| Rule 4 | Background by default during setup | Use `run_in_background: true` on every Bash call in setup flows unless the result is immediately needed for the next decision. |+| Rule 5 | Destructive actions require per-action confirmation | Never execute `delete-*`, `stop-*`, `terminate-*`, force-push, or any infrastructure destruction without an explicit `AskUserQuestion` confirmation per action. |++When writing a new skill or agent, verify each of these rules applies correctly before submitting a PR.++---++## Build Commands++The plugin has no compilation step — all skills and agents are plain markdown. The `package.json` at `claude-ops/claude-ops/package.json` manages runtime dependencies for the `.mjs` autolink scripts only.++| Command | What it does |+|---|---|+| `bash tests/run-all.sh` | Run all six test suites and report pass/fail |+| `bash tests/test-no-secrets.sh` | Scan for leaked secrets, tokens, or personal data |+| `bash tests/test-skills-lint.sh` | Lint all SKILL.md files for required frontmatter fields |+| `bash tests/test-bin-scripts.sh` | Validate bin scripts are executable and have correct shebangs |+| `bash tests/test-hooks.sh` | Validate hooks.json structure |+| `bash tests/test-claude-md.sh` | Verify CLAUDE.md contains all required rules |+| `bash tests/test-template.sh` | Validate Shopify scaffolding template |++All commands run from the `claude-ops/claude-ops/` directory.++---++## Pre-commit Checklist++There is no automated pre-commit hook wired to git. Before every commit, run these manually:++```bash+cd claude-ops/claude-ops++# Required — scan for secrets and personal data+bash tests/test-no-secrets.sh++# Recommended — run the full suite+bash tests/run-all.sh+```++If `test-no-secrets.sh` fails, the commit must not proceed. This is enforced by Rule 0 in CLAUDE.md.++---++## Coding Conventions++**Shell scripts (`bin/`):**+- Always start with `#!/usr/bin/env bash` and `set -euo pipefail`+- Include a one-line comment after the shebang: `# ops-scriptname — what it does`+- Emit JSON to stdout; emit errors to stderr (`2>/dev/null` at the call site silences them)+- Scripts must be idempotent — calling them multiple times must not cause side effects+- Never hardcode paths; use `$HOME`, `~`, `$CLAUDE_PLUGIN_ROOT`, or `$CLAUDE_PLUGIN_DATA_DIR`++**Skills (`skills/`):**+- One skill per directory; one `SKILL.md` per skill directory+- Frontmatter `name` must match directory name exactly+- Never include personal data, real org names, store URLs, or tokens in examples (Rule 0)+- Use pre-execution shell blocks (`!` fences) to gather data before model context loads — this is the primary token-saving pattern used across all 22 skills++**Agents (`agents/`):**+- Agents are read-only by default — add `Write` and `Edit` to `disallowedTools` unless the agent genuinely needs to write files+- C-suite agents run on `claude-opus-4-6`; scanner and fix agents run on `claude-sonnet-4-6`+- Agents must not call other agents (`Agent` in `disallowedTools`) to prevent recursive spawning++**Secrets and credentials:**+- Never committed to the repo+- Stored in `$PREFS_PATH` (preferences.json, gitignored), `scripts/registry.json` (gitignored), Claude Code's encrypted `userConfig` (`~/.claude.json`), or the credential resolution chain: Doppler → 1Password/Dashlane/Bitwarden → macOS Keychain → env vars++---++## Branch Conventions++- `main` is the only long-lived branch+- Feature branches: `feat/description` or `fix/description`+- All changes go through a PR targeting `main`+- No direct pushes to `main` (enforced at repo and org level)+- Merge via `gh pr merge --merge --admin` (maintainers); external contributors require 1 approval++See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full PR workflow.diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.mdnew file mode 100644index 00000000..e5ebdb71--- /dev/null+++ b/docs/GETTING-STARTED.md@@ -0,0 +1,186 @@+<!-- generated-by: gsd-doc-writer -->+# Getting Started with claude-ops++claude-ops v0.8.0 — Business Operating System for Claude Code. This guide takes you from zero to your first morning briefing in under five minutes.++---++## Prerequisites++- **Claude Code 1.0+** — the only hard requirement. Install from [claude.ai/code](https://claude.ai/code).++Everything else (CLIs, tools, integrations) is installed automatically by `/ops:setup` via Homebrew on macOS, apt on Linux, or winget on Windows. No manual dependency management required.++---++## Installation++### Option 1 — Marketplace (recommended)++Install directly from the Claude Code plugin marketplace in two commands:++```bash+# Add the marketplace source+/plugin marketplace add Lifecycle-Innovations-Limited/claude-ops++# Install the plugin+/plugin install ops@lifecycle-innovations-limited-claude-ops+```++### Option 2 — Local development++Clone the repo and point Claude Code at the inner plugin directory:++```bash+git clone https://github.com/Lifecycle-Innovations-Limited/claude-ops.git+claude --plugin-dir ./claude-ops/claude-ops+```++> **Why the nested `claude-ops/claude-ops/` path?** Claude Code's marketplace system requires a two-level layout. The repo root is the marketplace container; the inner `claude-ops/` directory is the actual plugin root that Claude Code loads. See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full explanation.++To reload after making changes in local dev mode:++```bash+/reload-plugins+```++---++## Setup Wizard (`/ops:setup`)++Run the guided wizard immediately after installing:++```+/ops:setup+```++The wizard walks you through every integration in a conversational, step-by-step flow:++1. **Preflight** — detects already-configured CLIs, credentials, and MCP servers. Reads from `/tmp/ops-preflight/` cache so no probe runs twice.+2. **Core CLIs** — installs `jq`, `git`, `gh`, `aws`, and `node` if missing.+3. **Daemon install** — installs `briefing-pre-warm` early (Step 2c) so it begins pre-fetching ECS health, git state, PRs, CI, and unread counts while you answer the remaining wizard questions. By the time setup finishes, your first `/ops:go` loads in **<3 seconds** from warm cache instead of ~30 seconds cold.+4. **Channels** — configures each integration you choose: Telegram, WhatsApp, Gmail, Slack, Linear, Sentry, Vercel, Stripe, RevenueCat, Shopify, and more.+5. **Project registry** — scans your local directories and builds `scripts/registry.json` with your project list.+6. **Preferences** — saves your name, timezone, and default channels to `preferences.json` in Claude Code's plugin data directory.++**Rules the wizard enforces:**++- Never skips a channel silently — if a credential isn't found, you are always offered `[Paste manually]`, `[Deep hunt]`, or `[Skip]`.+- Never installs anything without your confirmation.+- Runs all probes in parallel and in the background — the conversation keeps moving while tools install.++For credentials, the wizard resolves secrets in this order: Doppler → 1Password/Dashlane/Bitwarden → macOS Keychain → environment variables. If none are found, it asks you directly.++See [CONFIGURATION.md](./CONFIGURATION.md) for the full list of configurable values and their plugin.json `userConfig` keys.++---++## Health Check (`/ops:doctor`)++After setup, verify the plugin is healthy:++```+/ops:doctor+```++The doctor runs a diagnostic script and displays a report:++```+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━+ OPS ► DOCTOR — 2026-04-14 09:00+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━++ Plugin: 0.8.0 at /path/to/plugin+ Skills: 22 defined+ Agents: 12 defined+ Bin scripts: 8 available++ ERRORS 0+ WARNINGS 0++ TOOLS+ [table of CLI tool availability]++ ENV VARS+ [table of env var status]++ Registry: 19 projects+ Preferences: configured+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━+```++If errors or warnings are found, the doctor automatically spawns a repair agent to fix them. After the agent completes, diagnostics re-run to confirm the fix. To check without auto-repairing:++```+/ops:doctor --check-only+```++---++## First Briefing (`/ops:go`)++Once the doctor reports all checks passing, run your first briefing:++```+/ops:go+```++Output looks like this:++```+╭──────────────────────────────────────────────────────────────────────────────╮+│ /ops:go ► MORNING BRIEFING 2026-04-14 09:03 │+├─────────────────────────────────┬────────────────────────────────────────────┤+│ INFRA ████████████████ ok │ ECS: 4/4 healthy RDS: ok Redis: ok │+│ CI/CD ████████████░░░░ 75% │ 3 passing 1 failing (my-api #847) │+│ INBOX ░░░░░░░░░░░░░░░░ 14 │ Slack: 9 Telegram: 3 Gmail: 2 unread │+│ PRs ████████████████ 3 │ 3 ready to merge 1 needs review │+│ SPRINT ████████████░░░░ 67% │ Sprint 24 — 8 of 12 issues complete │+│ REVENUE ████████████████ $ │ $2,847 MTD ↑12% vs last month │+├─────────────────────────────────┴────────────────────────────────────────────┤+│ Next action: merge feat/user-profile · fix my-api CI · reply @alice │+╰──────────────────────────────────────────────────────────────────────────────╯+```++Each section (INFRA, CI/CD, INBOX, PRs, SPRINT, REVENUE) is pre-gathered by shell scripts before model context loads — no extra latency. The `briefing-pre-warm` daemon runs every 2 minutes in the background so data is always warm.++From here, explore the other 21 skills — see the full command table in the root [README.md](../README.md).++---++## Common Issues++### Plugin not found after marketplace install++The marketplace cache can lag by a few seconds. Try:++```bash+/plugin list+/plugin install ops@lifecycle-innovations-limited-claude-ops+```++If the plugin still does not appear, confirm Claude Code is version 1.0 or later: `claude --version`.++### `/ops:setup` hangs on a credential scan++Background probes run in parallel during setup. If a step appears stuck for more than 30 seconds, it is likely waiting on a slow network probe (Doppler, keychain, password manager). You can safely answer the current `AskUserQuestion` — the wizard will resume when the background result arrives. If a probe never completes, `/ops:doctor` will flag the affected integration.++### `/ops:go` shows cold load (~30s) on first run++This means the `briefing-pre-warm` daemon was not installed during setup, or has not yet completed its first cycle. Run `/ops:setup` again and confirm the daemon step (Step 2c). After installation, pre-warm runs every 2 minutes — subsequent briefings will be fast.++### Missing integration data in `/ops:go`++Each integration only appears if its credential is configured. Run `/ops:doctor` to see which env vars or API keys are unset, then run `/ops:setup <section>` (e.g., `/ops:setup slack`) to configure just that integration.++### WhatsApp shows `needs_auth`++WhatsApp authentication requires a QR code scan on your phone — this is the one step that cannot be automated. Run `/ops:setup whatsapp` and point your phone camera at the QR code shown in the terminal.++---++## Next Steps++- [ARCHITECTURE.md](./ARCHITECTURE.md) — how the plugin is structured, the daemon, and the two-level directory layout+- [CONFIGURATION.md](./CONFIGURATION.md) — full reference for every configurable value, credential key, and userConfig field+- [../CONTRIBUTING.md](../CONTRIBUTING.md) — branch rules, PR workflow, and how to add new skillsdiff --git a/docs/TESTING.md b/docs/TESTING.mdnew file mode 100644index 00000000..3d55bd12--- /dev/null+++ b/docs/TESTING.md@@ -0,0 +1,94 @@+<!-- generated-by: gsd-doc-writer -->+# Testing++## Test framework and setup++claude-ops uses a custom Bash-based test framework. There is no external test runner dependency — all tests are plain shell scripts executed directly with `bash`. Each script follows a consistent pattern: `ok()` / `err()` helpers accumulate pass/fail counts and the script exits non-zero if any check fails.++Before running tests, install Node dependencies (required by `test-bin-scripts.sh` when `shellcheck` lints `.mjs` files indirectly, and by the CI syntax checks):++```bash+cd claude-ops+npm ci+```++`shellcheck` is used by `test-bin-scripts.sh` when available. Install it with:++```bash+brew install shellcheck # macOS+apt-get install shellcheck # Debian/Ubuntu+```++## Running tests++Run the full test suite from the `claude-ops/` directory:++```bash+bash tests/run-all.sh+```++Run a single suite in isolation:++```bash+bash tests/test-skills-lint.sh+bash tests/test-bin-scripts.sh+bash tests/test-hooks.sh+bash tests/test-template.sh+bash tests/test-claude-md.sh+bash tests/test-no-secrets.sh+```++`run-all.sh` executes all six suites in the order listed above, prints per-suite pass/fail, and exits 1 if any suite fails.++## Writing new tests++Test files live in `claude-ops/tests/` and are named `test-<area>.sh`. Each script must:++1. Start with `#!/usr/bin/env bash` and `set -euo pipefail`.+2. Resolve `PLUGIN_ROOT` relative to `$0` so the script is location-independent:+ ```bash+ PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"+ ```+3. Use the `ok()` / `err()` helper pattern and exit with code 1 when `$fail > 0`.+4. Be registered in `run-all.sh` via a `run_suite "$TESTS_DIR/test-<area>.sh"` call.++No shared test helper file exists — each script is self-contained.++## Coverage requirements++No line/branch/function coverage thresholds are configured. Coverage is structural: each test suite validates a specific area of the plugin (skills, bin scripts, hooks, templates, CLAUDE.md rules, secrets). A new feature is considered covered when a corresponding `test-<area>.sh` check exists for its key invariants.++## CI integration++**Workflow:** `.github/workflows/ci.yml` — "CI"++**Triggers:** push to `dev`; pull requests targeting `dev` or `main`++**Steps run in CI (in order):**++1. Install Node dependencies: `cd claude-ops && npm ci`+2. Syntax check Node scripts (`node --check`) for `ops-slack-autolink.mjs`, `ops-telegram-autolink.mjs`, and `telegram-server/index.js`+3. Syntax check shell scripts (`bash -n`) for `ops-merge-scan`, `ops-prs`, `ops-ci`, `ops-git`, `ops-infra`, `ops-unread`, `ops-gather`, `ops-setup-detect`, `ops-setup-install`+4. Prettier format check: `npx prettier --check "**/*.{js,mjs,json}"`+5. Secret scanning: gitleaks v8.30.1 using `claude-ops/.gitleaks.toml`++Note: the six `tests/` suite scripts are not currently invoked in CI — they run locally and in the pre-commit hook. The CI job focuses on syntax validity, formatting, and secret detection.++## Pre-commit hook++`.githooks/pre-commit` runs automatically on `git commit`. It:++- Scans the staged diff for secrets and personal data (tokens, API keys, emails, hardcoded paths, phone numbers, IP addresses)+- Invokes `tests/test-no-secrets.sh` against the full working tree++To install the hook:++```bash+git config core.hooksPath .githooks+```++To bypass in an emergency (not recommended for this public repo):++```bash+git commit --no-verify+```