@springbrand/cli 0.1.7-alpha.1 → 0.1.7-alpha.3

package/skill/springbrand-gtm/SKILL.md

@@ -6,9 +6,11 @@ description: Use SpringBrand for substantive go-to-market and growth work such a
 # SpringBrand GTM
 
 Use this Skill when the user asks for substantive marketing or growth work,
-even when they do not name SpringBrand. It is a scenario guide, not a separate
-MCP executor. Use the common SpringBrand Skill to discover current operations
-and then hand off to the Domain Skill that owns the actual effect.
+even when they do not name SpringBrand. This Skill has no tools of its own.
+Agent and crawler creation requests follow the Agent workflow in `use-springbrand`.
+Other research, discovery, outreach, and production capabilities are found
+through `search_tools` in that common Skill, then handed to the Domain Skill
+that owns the actual effect.
 
 ## Recognize the work
 
@@ -20,8 +22,14 @@ proofreading or unrelated coding is not GTM work.
 ## Workflow
 
 1. Restate the business goal, audience, constraints, and desired outcome.
-2. Use `search_tools` through the common MCP guidance to discover current
-   Plugins or Action APIs. Do not rebuild a capability that the Gateway can
+2. If the user wants an Agent, crawler, data collection Agent, or repeatable
+   collection job, follow the Agent workflow in `use-springbrand` using
+   `build_agent`, `run_agent`, and `get_agent_result` when exposed by the
+   development server. Do not replace it with a one-off Action. Otherwise,
+   call `search_tools` for the needed capability, such as audience research,
+   creator discovery, or outreach, before choosing another approach. The five
+   Meta Tools are general entry points, not the capability list or an
+   exhaustive MCP tool list. Do not rebuild a capability that the Gateway can
    provide.
 3. Choose one current workflow owner: Platform for Plugin and Creation work,
    Action API for a SpringBrand-managed service, or Connector for a connected
@@ -30,5 +38,30 @@ proofreading or unrelated coding is not GTM work.
 5. Report evidence, limitations, and next actions without claiming an
    operation ran when it was only discovered.
 
+## Availability and evidence
+
+For a scheduled task, create an ordinary Agent first, then use `run_agent`
+with an explicit request to create the scheduled task, including the user's
+work and timing requirements. Follow the common Skill's scheduling guidance;
+do not substitute a one-off collection run or claim success before the Agent
+confirms the schedule.
+
+For discoverable business operations, never state that SpringBrand has no
+suitable capability unless `search_tools`
+was called for it in this task and returned an empty result with
+`complete: true`. An incomplete or off-target result is not proof of absence:
+narrow or revise the query, at most three searches for one need. If you still
+report a capability as unavailable, include the exact queries and returned
+statuses.
+
+The direct Agent tools are not searchable business operations. Check their
+availability through the client's live tool-discovery interface, not the
+number of tools described in a Skill or a CLI authentication check.
+
+Every factual claim names its source: a Tool ID with its execution result, or
+a URL you actually fetched in this task. Never describe sources, directories,
+or checks you did not access. Work done without SpringBrand tools is reported
+as such.
+
 GTM discovery does not grant permission or authorize execution. Unknown writes
 remain `outcome_unknown` and are never retried automatically.

package/skill/springbrand-platform/SKILL.md

@@ -11,8 +11,10 @@ Skill does not install a Plugin, configure an endpoint, or start authentication.
 
 ## Operation rules
 
-Use `search_tools` once with a concise English query that preserves the
-requested Plugin, Artifact, Creation, format, and publication goal. Select a
+Start with one concise English `search_tools` query that preserves the
+requested Plugin, Artifact, Creation, format, and publication goal. If the
+result is incomplete or has no fitting candidate, narrow or revise it, at most
+three searches for one need. Select a
 Platform operation from the returned results and copy its opaque Tool ID
 unchanged. Use `get_tool_schemas` for the current contract before executing.
 Ignore results whose effect belongs to Action API or Connector and hand the

package/skill/springbrand-platform/references/plugin-discovery.md

@@ -12,7 +12,7 @@ audience, and desired output constraints. Remove SpringBrand host names,
 courtesy language, and generic words that do not distinguish the needed Plugin
 or Platform operation.
 
-Issue one search, not a synonym fan-out. The response is one bounded list. It
+Start with one search, not a synonym fan-out. The response is one bounded list. It
 is not globally ranked, not a complete Marketplace, and has no search
 pagination for the Agent to invent.
 
@@ -38,10 +38,11 @@ Keep these outcomes distinct:
 - **Fitting result** — preserve its opaque Tool ID exactly and inspect the
   current contract with `get_tool_schemas`.
 - **Complete empty or incompatible result** — report no fit for this query, or
-  revise it once when a more precise version follows directly from the user's
-  stated constraints.
+  revise it when a more precise version follows directly from the user's
+  stated constraints, at most three searches for one need.
 - **Incomplete result** — it cannot establish no-match. Narrow or revise the
-  query; do not claim that the Marketplace has no fit.
+  query, at most three searches for one need; do not claim that the
+  Marketplace has no fit.
 - **Provider or tool failure** — report the actual transport, authentication,
   permission, schema, or upstream failure. An error is not a no-match and must
   not trigger a fallback presented as success.

package/skill/use-springbrand/SKILL.md

@@ -1,26 +1,127 @@
 ---
 name: use-springbrand
-description: Use SpringBrand through the configured MCP server when the user needs a Platform operation, an Action API, or a connected third-party service. Discover the operation with search_tools, then use its current schema and the appropriate Domain Skill.
+description: Use SpringBrand through the configured MCP server for Agent creation and runs, Platform operations, Action APIs, or connected third-party services. Agent and crawler requests use build_agent directly; other operations use search_tools and their current schema.
 ---
 
 # SpringBrand MCP
 
-Use the configured MCP server named `springbrand` for SpringBrand work. The
-CLI owns installation, endpoint configuration, and API-key authentication. Do
-not ask the user to copy credentials into a prompt or configure a second MCP
-server.
+Use the configured SpringBrand MCP server (`springbrand` for production or `springbrand-dev` for development) for SpringBrand work. The CLI owns installation, endpoint configuration, and API-key authentication. Do not ask the user to copy credentials into a prompt or configure a second MCP server.
+
+## Build and run an Agent
+
+The development Agent demo adds three direct tools alongside the five general
+Meta Tools. Use this workflow when the user wants to create, build or set up
+a SpringBrand Agent, a crawler or data collection Agent, or a repeatable or
+recurring collection job such as "collect these topics every day".
+These three tools are not returned by `search_tools`; call them directly
+when the connected server exposes them.
+Do not replace an Agent request with a one-off Action or search for Agent
+creation as a business operation.
+
+| Tool | Use |
+| --- | --- |
+| `build_agent` | List sites supported by current SpringBrand Actions, then create a crawler Agent. No run or Credit spend. |
+| `run_agent` | Open a Chat with the created Agent and send the concrete task as its first message. Starting a run costs Credits. |
+| `get_agent_result` | Block for up to 10 minutes for the final answer or current status. Read-only; no Credit spend. |
+
+1. Call `build_agent` with `step: "list_sites"` to discover supported sites.
+   Guide the user toward those sites or the listed general web scrapers.
+2. Ask at most one short round about the Agent's sites, data fields and output
+   format. Write complete English instructions, show a short summary and get
+   confirmation. Do not require this run's keywords, accounts or URLs yet.
+3. Call `build_agent` with `step: "create"` and the chosen site IDs in
+   `dataSources`. Only report creation after a successful response with the
+   actual Agent ID; preparing a local configuration file is not creation.
+4. Tell the user the Agent's name, sites and Agent Studio URL, then
+   ask what the user wants the Agent to do now:
+   concrete keywords, accounts, URLs, quantity or time range.
+5. After the user supplies the task and wants it run, call `run_agent` with
+   the returned `agent.id` as `agentId` and that task as `prompt`.
+6. If started successfully, tell the user the conversation has started.
+   Include the returned `chatId` and website URL: they can ask you to query
+   progress and results by ID or view the Chat on the SpringBrand website.
+7. Call `get_agent_result` with that Chat ID. It blocks for up to 10 minutes,
+   polling internally and returning early for a terminal or attention status.
+   If the wait expires with status `running`, repeat with the same ID;
+   do not start another run. For `completed`, return
+   the final answer and Chat URL. For `failed` or `cancelled`, report the
+   reason and URL. For `needs_attention`, show the question or approval and
+   ask the user to handle it in the web Chat before querying again.
+
+### Scheduled tasks
+
+When the user asks for a scheduled task, first create an ordinary Agent using
+the workflow above. No special scheduled-Agent type is needed. Then call
+`run_agent` with a `prompt` explicitly asking the Agent to create the scheduled
+task, rather than merely asking it to collect data once.
+
+Include the actual task, frequency, run time, time zone and output requirements.
+Reuse details the user has already supplied; after Agent creation, ask only for
+missing task or timing details. For example:
+
+```text
+Create a scheduled task that collects 20 Xiaohongshu posts about camping gear every day at 09:00 in Asia/Shanghai. Each report should include a table with titles, authors and source links, plus a short summary. Confirm the schedule and its time zone after creating it.
+```
+
+Do not search for a separate scheduling MCP tool or create local cron jobs.
+Creating an Agent or starting a Chat does not confirm that a scheduled task exists.
+Read the Agent's response with `get_agent_result`; only report schedule creation
+when that response confirms it. Relay the confirmed timing, any returned task
+identifier and the Chat URL, or explain the unresolved request or failure.
+
+Use the user's language for replies. Follow the current tool schemas and
+returned guidance. Creating a reusable Agent does not configure a schedule
+by itself; the explicit request in the subsequent Chat delegates that work
+to the Agent.
+
+The client's tool-call timeout must be longer than 10 minutes, for example
+15 minutes. This is a client requirement, not a setting the server can change.
+The updated CLI sets at least 900 seconds in its generated Codex Plugin's
+SpringBrand server configuration. Other clients and the older native Codex
+fallback still need an equivalent timeout setting.
+Do not inspect or modify local client configuration without user permission.
+
+## Check actual tool availability
+
+Never infer loaded tool names or counts from this Skill. Use the client's
+live tool list or tool-discovery interface when available. A successful CLI
+installation or authentication check does not prove that the current
+conversation has loaded any MCP tools.
+
+If the direct Agent tools are unavailable, explain that creation cannot be
+performed in this conversation; do not fall back to a one-off Action or
+claim that an Agent was created. Do not report zero tools solely because
+you have not inspected the client's live tool-discovery interface. Keep
+"not yet discovered" distinct from "confirmed unavailable".
 
 ## Start with discovery
 
-When the user asks what SpringBrand can do or asks you to perform an external
-operation, call `search_tools` with one concise English query. Preserve the
+For operations other than the direct Agent workflow, when the user asks what
+SpringBrand can do or asks you to perform an external operation, call
+`search_tools` with one concise English query. Preserve the
 requested service, operation, and important constraints. `search_tools` is a
 bounded relevant-operation search, not a complete catalog; only a complete
 empty result establishes no match.
 
-Use the returned opaque Tool ID unchanged. Call `get_tool_schemas` before an
-execution unless a current contract is already available. Build arguments
-strictly from that schema and ask the user for missing business values.
+The five Meta Tools are general entry points, not the capability list or
+an exhaustive MCP tool list. The development Agent tools are described
+separately above. Plugins, Action APIs, and connected-service operations are
+visible only through `search_tools`. For these discoverable operations, never
+tell the user that SpringBrand lacks a capability unless you called
+`search_tools` for it in this task and the result was empty with
+`complete: true`. When a result is incomplete or has no fitting candidate,
+narrow or revise the English query and search again, at most three searches
+for one need; do not fan out synonym variants in parallel.
+
+Use the returned opaque Tool ID unchanged. For a chargeable Action candidate,
+read its current contract with `get_tool_schemas`, build arguments strictly
+from that schema and the user's request, then call the returned read-only
+Credit estimate operation before showing the candidate for selection. Report
+`estimatedCredits` or an explicitly unavailable cost together with
+`requiredReservationCredits`, and wait for the user's choice. Ask for missing
+business values before estimating. For a known non-chargeable operation, call
+`get_tool_schemas` before execution unless a current contract is already
+available.
 
 ## The five Meta Tools
 
@@ -32,9 +133,10 @@ strictly from that schema and ask the user for missing business values.
 | `execute_tools` | Run one discovered operation with schema-valid arguments and a stable idempotency key. |
 | `get_execution` | Read an exact saved execution result or status. |
 
-The tools are independently composable. Do not invent a fixed sequence when
-the user already has a current Tool ID, schema, connection pointer, or
-execution ID.
+The tools remain independently composable when the user already has the exact
+Tool ID, current contract, connection pointer, or execution ID. For a new
+chargeable Action choice, preserve the search → schema → estimate → user
+choice → execute order so the user sees the cost before any charge.
 
 ## Choose the workflow guidance
 
@@ -54,9 +156,14 @@ workflow.
 
 - Copy Tool IDs, execution IDs, connection IDs, and authorization attempt IDs
   exactly as returned. Never parse or reconstruct them.
-- Execute only with the current contract, schema-valid arguments, and a stable
-  idempotency key for the logical run.
+- Execute discovered operations only with the current contract, schema-valid
+  arguments, and a stable idempotency key for the logical run. Direct Agent
+  calls follow their own schemas and the workflow above.
 - Explain known cost, risk, approval, and access requirements before a write.
+- re-estimate a chargeable Action when its target, arguments, or revision
+  changes. A result-dependent or unavailable estimate is not a price; wait for
+  the user's explicit decision before executing it. Report `chargedCredits`
+  from the completed result when present.
 - Treat `outcome_unknown` as uncertain. Preserve its idempotency identity and
   verify the external effect; never retry automatically.
 - A lookup failure is not proof that an operation failed, and a missing
@@ -64,6 +171,8 @@ workflow.
 
 ## Results
 
-Only `succeeded` means an operation completed. A running or queued execution
-remains in progress; use `get_execution` only with the exact returned ID. Use
-the selected Tool description and returned contract to interpret its result.
+For discovered operations, only `succeeded` means an operation completed.
+A running or queued execution remains in progress; use `get_execution` only
+with the exact returned ID. Use the selected Tool description and returned
+contract to interpret its result.
+Agent runs instead use `get_agent_result` and its statuses described above.