@ekanos/cli 0.5.1 → 0.6.0

package/templates/skills/build-agent/references/rollout.md

@@ -0,0 +1,53 @@
+# Who gets the agent: rollout options
+
+Two shapes. Recommend one, and say why in terms of the user's teams.
+
+## Provided for every team (an agent template)
+
+Built with `ekanos agents` by a Source admin.
+
+- **Defined once.** Instructions, model, tools, approvals, skills, which
+  connections it uses, and what teams may add.
+- **Drafts are private.** `apply` stores a numbered version; no team sees it
+  until it is published.
+- **Publishing reaches every team in the Source.** Each sees it under Agents →
+  "Provided for your team". There is no list of chosen teams: every team can
+  see it, and each decides whether to turn it on.
+- **Turning it on** makes the team's own copy. The person who turns it on
+  becomes its owner; the agent uses that person's and that team's
+  connections, so a team that has not connected a `required` product sees
+  "needs setup" instead of a working agent.
+- **Updates.** Each publish updates every team that follows the latest
+  version. A team can **pin** a version instead; it stays there and is told
+  when a newer one is published.
+- **Rollback.** `ekanos agents rollback <key> --to <n> --yes` publishes an
+  earlier version to every team that follows it.
+- **What stays the team's:** whether it is on, its triggers, its own
+  connections, its run history, and whatever `teamCustomization` lets it add.
+- **When a new version needs more access** than a team confirmed (a new
+  product, a tool that now runs without approval), the team's owner is asked
+  to confirm again; until then the agent keeps only what needs no new
+  confirmation.
+
+Good for: the same job done by several teams; a central owner who improves
+it over time; consistent behaviour and approvals.
+
+Piloting: publish, then have one team turn it on first. Teams that never
+turn it on are unaffected. Or keep it as an applied draft until the pilot
+plan is ready.
+
+## A team's own agent
+
+Built by a team in the app (Agents → New). Only that team has it; the Source
+cannot update or roll it back, and nothing about it is visible to other teams.
+
+Good for: one team's own process; experiments a team owns.
+
+## Questions that decide it
+
+- How many teams do this work? The same way?
+- Who should own improvements — one central person, or each team?
+- Must every team follow the same approval rules (e.g. customer-facing
+  replies always reviewed)?
+- Do teams need to add their own tools or knowledge, and should they be
+  allowed to? (`teamCustomization`, all off by default.)

package/templates/skills/build-agent/references/triggers.md

@@ -0,0 +1,47 @@
+# What starts the agent: triggers
+
+Triggers belong to each team. They are not part of the agent template: a team
+adds them on its copy (Agents → the agent → Triggers) after turning it on.
+Your job in the interview is to say which triggers each team will want, and
+what it must connect first, so the team-side checklist is complete.
+
+## Kinds a team can add
+
+- **An integration's event** — any event a connected integration declares
+  (the catalog lists them per product as `agentEvents`). The team picks the
+  event and fills in its filter (the fields the event declares — e.g. labels,
+  a team, a group, tags). When the integration also has a **channel**, the
+  agent answers where the event happened (on the issue, on the ticket), and
+  that reply tool runs on its own by default.
+- **Schedule** — a cron and time zone, with "what to do each time".
+- **Webhook** — a URL any system can call, with "what to do with each
+  request".
+- **Slack** — chosen channels and/or direct messages in a connected Slack.
+
+## Integrations with agent events
+
+Check `ekanos catalog <product> --source <slug> --json` for what is actually
+there; these are the known shapes.
+
+**Linear** (`linear.mentioned`, `linear.assigned`, `linear.issue_labeled`) —
+the agent becomes a teammate in Linear: @mention it, assign it an issue, or
+apply a label. Each team needs two things in the app: each person's own
+Linear connection (for the tools), and the team's own Linear app for the
+agent (client id, secret and webhook signing secret, entered in Ekanos).
+Guide: https://sdk.ekanos.dev/guides/linear-agent
+
+**Zendesk** (`zendesk.ticket_created`, `zendesk.comment_added`; filters such
+as brand, group, tags, organization) — when present in the catalog, each team
+connects its own Zendesk (subdomain plus an OAuth client it creates in
+Zendesk) and adds a Zendesk webhook pointing at its Ekanos endpoint. The agent
+answers on the ticket as a public reply or an internal note — recommend
+internal notes, or approval on public replies, until the team trusts it.
+
+## Checklist to hand each team
+
+1. Agents → "Provided for your team" → Turn on.
+2. Connect every `required` product and sign in to any MCP server that needs
+   it (the agent shows what is missing).
+3. Do each integration's own setup (team app, webhook) from its guide.
+4. Confirm access if asked.
+5. Add the triggers above, then run one real example and review it.

package/templates/skills/ekanos-platform/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ekanos-platform
+description: How Ekanos is organized — Sources, team accounts, seats and roles, products (integrations and experiences), connections, and managed agents — and which of those the ekanos CLI can change. Use whenever a request involves who gets something (one team or every team), who can set it up, whether something is "connected" or "enabled", or explaining Ekanos to the user before building an integration or an agent.
+---
+
+# How Ekanos is organized
+
+Explain these in plain words when a decision depends on them. Docs:
+https://sdk.ekanos.dev/concepts/sources-and-teams (or search the
+`ekanos-sdk-docs` MCP server). Never guess a rule that is not here or in the
+docs — ask, or check the CLI.
+
+## Sources and team accounts
+
+- A **Source** is one Ekanos customer's whole deployment: its brand, domain,
+  users and catalog. Ekanos is white-label, so the people inside a Source see
+  only their own brand.
+- A Source holds many **team accounts**. A team is where the work happens:
+  its members, its data, its connections, its agents. Teams in the same Source
+  do not see each other's data.
+- Team members have one of three team roles — **owner**, **admin**,
+  **member** — which govern that team only. Being a team owner gives no
+  authority over the Source.
+- **"Source" is admin vocabulary.** Team members never see the word. When you
+  describe what a team will see, say "provided for your team", never "the
+  Source's agent". Use "Source" freely with the person you are helping only
+  if they are a Source admin or developer (they are, if the CLI works for
+  them).
+
+## Seats: who can use the CLI on a Source
+
+`npx ekanos sources --json` lists the user's seats.
+
+| Seat | Can |
+|---|---|
+| `developer` | Submit integrations; read the catalog; apply agent **drafts** |
+| `source_admin` | Everything a developer can, plus **publish** agents to every team and manage the Source's roster |
+
+Only an Ekanos super admin grants seats. If the user lacks the seat a step
+needs, say which and stop — there is no way around it from the CLI.
+
+## Products: integrations and experiences
+
+Everything in the catalog (`npx ekanos catalog --source <slug> --json`) is a
+**product** of one of two kinds:
+
+- **Integration** — a connection to a third party (Linear, Zendesk, Slack…).
+  Brings tools an agent can call, and may declare **agent events** that start
+  agents (`linear.mentioned`, `zendesk.ticket_created`…).
+- **Experience** — an Ekanos-native capability (Agents, Workflows, Home…).
+  Never "connected"; it is simply on or off for the Source.
+
+## Is it usable? Four separate facts
+
+Ask them in this order; each catalog product reports where it stands
+(`availability` and `setupSteps`).
+
+1. **Given to the Source** — `availability` is `enabled` (on), `turned-off`
+   (given, but a Source setting or plan has it off) or `available` (Ekanos
+   offers it; this Source has not been given it). A product missing from the
+   catalog altogether is not offered to this Source. Giving a Source a product
+   is an Ekanos super admin's step (`setupSteps` names it with actor
+   `ekanos`) — not something a Source admin or the CLI can do.
+2. **Connected by a team** — a team (or a person, for per-person
+   integrations) signed in to the third party. Connections belong to a team,
+   never to the Source: two teams using Linear each connect their own.
+3. **Set up by the team** where needed — some integrations have each team
+   bring its own app (a team-provided app: client id, secret, webhook signing
+   secret entered in Ekanos). Those secrets are typed into the app, never
+   into a chat or a file.
+4. **Used by an agent** — granted in the agent's tools.
+
+A product that is "enabled" is not therefore "connected". Say which one you
+mean.
+
+## Managed agents
+
+An agent is **data held by Ekanos**, not code: instructions, a model, the
+tools it may use, which calls wait for a person's approval, and skills. It is
+changed through the CLI or the app, with no deploy.
+
+- **Provided for every team** — a Source admin defines it once with
+  `ekanos agents` (a template). Each team sees it under Agents → "Provided for
+  your team" and turns it on; it then runs on that team's own connections.
+  Publishing a new version updates every team that follows it.
+- **A team's own** — built by a team in the app (Agents → New). Only that team
+  has it, and the Source cannot update it.
+
+The `build-agent` skill walks through choosing between these and building one.
+
+## Where each thing is done
+
+| Done by | Where |
+|---|---|
+| Making a product available to a Source; granting seats | Ekanos super admin, in Ekanos's admin |
+| Building or updating an integration | A developer, with `ekanos validate` / `ekanos publish` |
+| Agents provided for every team | A Source admin, with `ekanos agents` |
+| Connecting an integration; turning on a provided agent; its triggers | Each team, in the app |