From ddc1ea30d039f73fd65be856ad01b5569f8d4935 Mon Sep 17 00:00:00 2001 From: Rob Masson Date: Sun, 12 Apr 2026 19:13:24 -0700 Subject: [PATCH] feat: bring skill content to parity with archagents (closes #15) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename, update, and add skills so both repos have the same 10 concepts with consistent naming and content. Renames: - agent_authoring → author-agent (kebab-case, verb-first) - agent_deploy → deploy-agent (kebab-case, verb-first) Updated existing skills (ported from archagents): - author-agent: verb-first commands, local-config-dir routing section - deploy-agent: verb-first commands, configs routing section - chat: quick reference command table, ergonomics improvements - impersonate: already at parity from earlier PRs - auth: minor phrasing alignment - install: minor phrasing alignment New skills (4): - build-script: AgentScript authoring, syntax reference, deployment - build-skill: skill authoring, SKILL.md format, publishing - build-workflow: workflow authoring, node types, deployment - manage-configs: local config management, init, sync, deploy All 10 sources produce 21 outputs (8 Claude skills + 3 Claude commands + 10 Codex skills). Version bumped 0.3.1 → 0.3.2. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 4 +- .../archastro/.claude-plugin/plugin.json | 4 +- .claude-plugins/archastro/commands/auth.md | 64 ++-- .../archastro/commands/impersonate.md | 167 +++++++++- .claude-plugins/archastro/commands/install.md | 28 +- .../SKILL.md | 41 ++- .../archastro/skills/build-script/SKILL.md | 299 +++++++++++++++++ .../archastro/skills/build-skill/SKILL.md | 175 ++++++++++ .../archastro/skills/build-workflow/SKILL.md | 283 ++++++++++++++++ .../archastro/skills/chat/SKILL.md | 55 +++- .../{agent_deploy => deploy-agent}/SKILL.md | 20 +- .../archastro/skills/impersonate/SKILL.md | 33 +- .../archastro/skills/manage-configs/SKILL.md | 229 +++++++++++++ plugins/archastro/.codex-plugin/plugin.json | 10 +- plugins/archastro/skills/auth/SKILL.md | 62 ++-- .../SKILL.md | 41 ++- .../archastro/skills/build-script/SKILL.md | 299 +++++++++++++++++ plugins/archastro/skills/build-skill/SKILL.md | 175 ++++++++++ .../archastro/skills/build-workflow/SKILL.md | 283 ++++++++++++++++ plugins/archastro/skills/chat/SKILL.md | 55 +++- .../{agent_deploy => deploy-agent}/SKILL.md | 20 +- plugins/archastro/skills/impersonate/SKILL.md | 33 +- plugins/archastro/skills/install/SKILL.md | 26 +- .../archastro/skills/manage-configs/SKILL.md | 229 +++++++++++++ sources/auth.md | 65 ++-- .../{agent_authoring.md => author-agent.md} | 47 +-- sources/build-script.md | 304 ++++++++++++++++++ sources/build-skill.md | 180 +++++++++++ sources/build-workflow.md | 288 +++++++++++++++++ sources/chat.md | 57 +++- sources/{agent_deploy.md => deploy-agent.md} | 26 +- sources/impersonate.md | 71 ++-- sources/install.md | 29 +- sources/manage-configs.md | 234 ++++++++++++++ 34 files changed, 3569 insertions(+), 367 deletions(-) rename .claude-plugins/archastro/skills/{agent_authoring => author-agent}/SKILL.md (73%) create mode 100644 .claude-plugins/archastro/skills/build-script/SKILL.md create mode 100644 .claude-plugins/archastro/skills/build-skill/SKILL.md create mode 100644 .claude-plugins/archastro/skills/build-workflow/SKILL.md rename .claude-plugins/archastro/skills/{agent_deploy => deploy-agent}/SKILL.md (88%) create mode 100644 .claude-plugins/archastro/skills/manage-configs/SKILL.md rename plugins/archastro/skills/{agent_authoring => author-agent}/SKILL.md (73%) create mode 100644 plugins/archastro/skills/build-script/SKILL.md create mode 100644 plugins/archastro/skills/build-skill/SKILL.md create mode 100644 plugins/archastro/skills/build-workflow/SKILL.md rename plugins/archastro/skills/{agent_deploy => deploy-agent}/SKILL.md (88%) create mode 100644 plugins/archastro/skills/manage-configs/SKILL.md rename sources/{agent_authoring.md => author-agent.md} (71%) create mode 100644 sources/build-script.md create mode 100644 sources/build-skill.md create mode 100644 sources/build-workflow.md rename sources/{agent_deploy.md => deploy-agent.md} (86%) create mode 100644 sources/manage-configs.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index dfc53e4..250ae1f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,8 +13,8 @@ { "name": "archastro", "source": "./.claude-plugins/archastro", - "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author and deploy agents, chat with running agents, and impersonate agents from Claude Code.", - "version": "0.3.1", + "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author agents, build scripts and workflows, manage configs, deploy agents, chat with running agents, and impersonate agents from Claude Code.", + "version": "0.3.2", "category": "development", "tags": [ "archastro", diff --git a/.claude-plugins/archastro/.claude-plugin/plugin.json b/.claude-plugins/archastro/.claude-plugin/plugin.json index b7fd777..886a7c3 100644 --- a/.claude-plugins/archastro/.claude-plugin/plugin.json +++ b/.claude-plugins/archastro/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "archastro", - "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author and deploy agents, chat with running agents, and impersonate agents from Claude Code.", - "version": "0.3.1", + "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author agents, build scripts and workflows, manage configs, deploy agents, chat with running agents, and impersonate agents from Claude Code.", + "version": "0.3.2", "author": { "name": "ArchAstro" }, "license": "MIT", "keywords": [ diff --git a/.claude-plugins/archastro/commands/auth.md b/.claude-plugins/archastro/commands/auth.md index 8a9e663..41fe2c4 100644 --- a/.claude-plugins/archastro/commands/auth.md +++ b/.claude-plugins/archastro/commands/auth.md @@ -1,77 +1,53 @@ --- -description: Authenticate with the ArchAstro developer platform (org mode by default) +description: Authenticate with the ArchAstro developer platform allowed-tools: ["Bash(archastro:*)"] --- # ArchAstro CLI Authentication -Authenticate the user with the ArchAstro developer platform via browser-based login. Defaults to org mode (Agent Network). +Authenticate the user with the ArchAstro developer platform via browser-based login. -## Instructions +## Workflow 1. **Read the compatibility contract first**: - - Use `plugin-compatibility.json`. - - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`. - - Treat that resolved value as the minimum supported CLI version for every check below. + - Use `plugin-compatibility.json` from the plugin root. + - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. + - Treat the resolved value as the minimum supported CLI version for every check below. 2. **Check the installed CLI version first**: ``` archastro --version ``` - If the command is missing, or the version is older than the resolved minimum version, tell the user to run `/archastro:install`. + If the command is missing, or the version is older than the resolved minimum, tell the user to run `/archastro:install`. -3. **Check if already authenticated**: +3. **Check whether the user is already authenticated**: ``` archastro auth status ``` - If the user is already authenticated, show their status and ask if they want to re-authenticate. + If the user is already authenticated, show their status and ask whether they want to re-authenticate. -4. **Determine the auth mode**: - - The default is **org mode** (Agent Network). Only use developer mode if the user explicitly asks to log in as a developer or app builder. - - - **Org mode** (default): For users within an organization. No app slug needed — defaults to Agent Network. - - **Developer mode**: For building and managing apps on the platform. Requires the `--dev` flag. - -5. **Reset any stale settings overrides** that may point to localhost: +4. **Reset any stale settings overrides that may point to localhost**: ``` archastro settings reset ``` This ensures the CLI uses the production URLs. -6. **Start the login flow**: - - **Org mode (default):** +5. **Start the login flow**: ``` archastro auth login ``` + Keep the session responsive while the browser-based auth flow runs. - **Org mode for a specific app** (if the user specifies a different app slug): - ``` - archastro auth login --app - ``` - - **Developer mode** (only if explicitly requested): - ``` - archastro auth login --dev - ``` - - Use `run_in_background: true` so the browser-based auth flow runs while you remain responsive. - - The CLI will open the user's browser to https://developers.archastro.ai for authentication and print a URL in case the browser doesn't open automatically. +6. **Tell the user the auth flow is running** and they should complete login in their browser. The CLI opens `https://developers.archastro.ai` and prints a URL if the browser does not open automatically. -7. **Tell the user** the auth flow is running and they should complete login in their browser. Let them know you're available to keep working on other things while waiting. - -8. **When the user says they've logged in** (or you're ready to check), wait for the command to finish and then re-check status. - -9. **On success**, confirm authentication succeeded and show their status: +7. **When the user says they have logged in**, or when it is time to re-check, wait for the login command to finish and then run: ``` archastro auth status ``` - For org mode, verify the output shows `Auth mode: org` and the correct app/org name. -10. **On failure**, show the error and suggest: - - Check their internet connection - - Try `archastro settings reset` if URLs look wrong - - `no-access` error means the user doesn't have org access — verify with an org admin for an invite - - Try again with `archastro auth login` +8. **On success**, confirm authentication succeeded and show the user their status. + +9. **On failure**, show the error and suggest: + - Check their internet connection. + - Try `archastro settings reset` if URLs look wrong. + - Try again with `archastro auth login`. diff --git a/.claude-plugins/archastro/commands/impersonate.md b/.claude-plugins/archastro/commands/impersonate.md index 90b897f..9467e43 100644 --- a/.claude-plugins/archastro/commands/impersonate.md +++ b/.claude-plugins/archastro/commands/impersonate.md @@ -1,29 +1,164 @@ --- -description: Run an archastro impersonate CLI command directly +description: Start, inspect, refresh, or stop ArchAstro impersonation through the ArchAstro CLI allowed-tools: ["Bash(archastro:*)"] --- -# ArchAstro Agent Impersonation (CLI passthrough) +# ArchAstro Impersonation -Pass arguments directly to `archastro impersonate`. +Manage ArchAstro impersonation from Claude Code and keep the current session aligned with the active identity file. + +Command aliases: ```text -/archastro:impersonate start +/archastro:impersonate start /archastro:impersonate status /archastro:impersonate sync /archastro:impersonate stop -/archastro:impersonate list skills -/archastro:impersonate install skill [--harness codex] [--install-scope project] ``` -## Instructions +## Always Start with State + +Every invocation must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. + +``` +archastro impersonate status --json +``` + +Then route based on the combination of current state and user intent. + +## Routing + +### CLI not installed or too old + +Before any impersonation work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. +- If authentication or app selection is missing, direct the user to `/archastro:auth`. + +### Inactive + user wants to start + +``` +archastro impersonate start +``` + +Then: + +``` +archastro impersonate status --json +``` + +Read the `identity_file` path from the returned state. Open and read that file. Adopt the identity for the current Claude Code session while retaining your normal capabilities. + +After adoption, check `state.skills`. If the agent has linked skills, tell the user what's available and offer to install them: + +``` +archastro impersonate list skills --json +``` + +### Active + user asks about status (or no specific intent) + +Summarize the current state from the JSON already fetched: + +- Agent name and ID +- App ID +- Tool count and skill count +- Loaded (installed) skills and their invocations +- Timestamps + +If the identity file has not been read in this session yet, read it and adopt the identity. + +### Active + user wants to sync/refresh + +``` +archastro impersonate sync +``` + +Then: + +``` +archastro impersonate status --json +``` + +Re-read the `identity_file` and re-adopt the refreshed identity. Report what changed (new/removed tools or skills). + +### Active + user wants to stop + +``` +archastro impersonate stop +``` + +Drop the impersonated identity from the current session. Confirm that local state was removed. + +### Active + user asks about tools + +List the impersonated agent's tools: + +``` +archastro impersonate list tools --json +``` + +To execute a tool directly: + +``` +archastro impersonate run tool --input '' --json +``` + +### Active + user asks about skills + +List available skills: + +``` +archastro impersonate list skills --json +``` + +Show what's available vs what's already installed (from `state.loaded_skills`). + +To install a skill: + +``` +archastro impersonate install skill +``` + +After install, report the invocation command (e.g., `/`) so the user knows how to use it. + +For Codex or OpenCode targets: + +``` +archastro impersonate install skill --harness codex --install-scope project +``` + +### Inactive + user asks about status + +Report that no impersonation is active and offer to start one. + +## Adopting the Identity + +When you read the identity file, you must **become that agent** for the rest of the session. This is not cosmetic — it changes how you behave: + +- **Personality and tone.** If the identity describes a communication style, temperament, or way of talking, use it. Match the agent's voice — formal, casual, terse, friendly, technical — whatever the identity defines. +- **Background and expertise.** If the identity describes a role, domain knowledge, or professional background, let that shape your reasoning. Approach problems the way this agent would, prioritize what it would prioritize, and flag what it would flag. +- **Scope and boundaries.** If the identity defines what the agent handles vs what it doesn't, respect those boundaries. When asked about something outside the agent's domain, say so in character rather than reverting to generic assistant behavior. +- **Stay in character across turns.** Do not drop the persona between messages. Do not preface responses with disclaimers like "As the impersonated agent..." — just be the agent. +- **Keep your capabilities.** You still have full tool access (file read/write, bash, search, etc.). The identity shapes how and when you use them, not whether you can. + +After `stop`, fully drop the persona and return to your normal behavior. + +## Limitations + +- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. +- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. + +## Session Integration + +- After `start` or `sync`, always read the identity file and adopt it as described above +- After `stop`, always drop the identity and revert to normal behavior +- When showing status, always include loaded skill invocations so the user knows what commands are available +- When skills are available but not installed, proactively mention them + +## Response Rules -1. Read `plugin-compatibility.json`. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. -2. Run `archastro --version`. If missing or too old, tell the user to run `/archastro:install`. -3. Run: - ``` - archastro impersonate $ARGUMENTS - ``` -4. If the command was `start` or `sync`, also run `archastro impersonate status --json`, read the `identity_file`, and adopt the identity for the current session. -5. If the command was `stop`, drop any impersonated identity from the current session. -6. If auth or app selection fails, direct the user to `/archastro:auth` or `--app `. +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick a subcommand — infer the action from their message and the current state. +- If the CLI reports an auth or app error, route to `/archastro:auth` or suggest `--app `. +- Keep responses concise — state the outcome, not the process. diff --git a/.claude-plugins/archastro/commands/install.md b/.claude-plugins/archastro/commands/install.md index 1f8340d..a646c48 100644 --- a/.claude-plugins/archastro/commands/install.md +++ b/.claude-plugins/archastro/commands/install.md @@ -1,5 +1,5 @@ --- -description: Install the ArchAstro developer platform CLI +description: Install the ArchAstro platform CLI allowed-tools: ["Bash(archastro:*)", "Bash(brew:*)", "Bash(curl:*)", "Bash(bash:*)", "Bash(sh:*)", "Bash(pwsh:*)", "Bash(powershell:*)"] --- @@ -7,12 +7,12 @@ allowed-tools: ["Bash(archastro:*)", "Bash(brew:*)", "Bash(curl:*)", "Bash(bash: Install or upgrade the public `archastro` binary from Homebrew or GitHub Releases. -## Instructions +## Workflow 1. **Read the compatibility contract first**: - - Use `plugin-compatibility.json`. - - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`. - - Treat that resolved value as the minimum supported CLI version for every check below. + - Use `plugin-compatibility.json` from the plugin root. + - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. + - Treat the resolved value as the minimum supported CLI version for every check below. 2. **Check whether the CLI is already installed**: ``` @@ -20,9 +20,9 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release ``` If this succeeds, record the version. -3. **If the CLI is present and meets the resolved minimum version**, confirm the version and stop unless the user explicitly asked to upgrade. +3. **If the CLI is present and meets the resolved minimum**, confirm the version and stop unless the user explicitly asked to upgrade. -4. **If the CLI is missing or older than the resolved minimum version**, install it using the public distribution path: +4. **If the CLI is missing or older than the resolved minimum**, install it using the public distribution path: - On macOS, if Homebrew is available: ``` brew install ArchAstro/tools/archastro @@ -44,12 +44,12 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release ``` archastro --version ``` - Confirm that the version now meets the resolved minimum version. + Confirm that the version now meets the resolved minimum. -6. **On success**, tell the user the CLI is ready and suggest `/archastro:auth`. +6. **On failure, help troubleshoot the public install path**: + - Missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh`. + - `Permission denied` usually means they need `--install-dir` or a user-writable target directory. + - `command not found: archastro` after install usually means the install directory is not on `PATH`. + - Release download failures usually mean the target release asset has not been published yet. -7. **On failure**, help troubleshoot the public install path: - - missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh` - - `Permission denied` usually means they need `--install-dir` or a user-writable target directory - - `command not found: archastro` after install usually means the install directory is not on `PATH` - - release download failures usually mean the target release asset has not been published yet +7. **On success**, tell the user the CLI is ready and suggest `/archastro:auth`. diff --git a/.claude-plugins/archastro/skills/agent_authoring/SKILL.md b/.claude-plugins/archastro/skills/author-agent/SKILL.md similarity index 73% rename from .claude-plugins/archastro/skills/agent_authoring/SKILL.md rename to .claude-plugins/archastro/skills/author-agent/SKILL.md index b70be00..c1c0998 100644 --- a/.claude-plugins/archastro/skills/agent_authoring/SKILL.md +++ b/.claude-plugins/archastro/skills/author-agent/SKILL.md @@ -1,5 +1,5 @@ --- -name: agent_authoring +name: author-agent description: Use when the user wants to create or edit an ArchAstro agent's config files before deployment, including AgentTemplate files, Script configs, custom tools, routines, and environment setup. Trigger phrases include "build this agent", "write the template", "create the scripts", "set up the routines", "author this agent config". allowed-tools: ["Bash(archastro:*)"] --- @@ -31,19 +31,23 @@ Before any authoring work, verify the CLI: - Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. - If authentication or app selection is missing, direct the user to `/archastro:auth`. +### Local config directory not initialized + +If the user doesn't have a `configs/` directory set up yet, route to the `manage-configs` skill first. That skill owns `archastro init --enable-configs`, local file layout, and the sync/deploy workflow. + ### User wants to author or modify agent configs 1. **Start from CLI-backed templates, not memory**: - For new config objects, use: ``` - archastro configs sample + archastro describe configsample ``` - For Script configs, always use: ``` - archastro configs script-reference - archastro configs sample Script + archastro describe scriptdocs + archastro describe configsample Script ``` - The script reference is the live source of truth. Do not invent or paraphrase the language from memory. + The script docs are the live source of truth. Do not invent or paraphrase the language from memory. 2. **Use the standard config-driven model**: - Script logic lives in `kind: Script` configs. @@ -56,14 +60,14 @@ Before any authoring work, verify the CLI: 3. **Validate early**: ``` - archastro configs validate + archastro validate config -k -f ``` Run validation before deploy whenever the user changes Script or template files. 4. **Deploy through the normal flow after authoring**: - If the agent has Script configs or other supporting files, sync them first: ``` - archastro configs deploy + archastro deploy configs ``` This pushes local config files (Scripts, templates) but does not create agents. Skip this step if the agent only has a single AgentTemplate file — `deploy agent` handles its own config upload. @@ -72,15 +76,16 @@ Before any authoring work, verify the CLI: archastro deploy agent ``` This uploads the template config and creates the agent with its routines, tools, and installations. - - **Important:** `configs deploy` and `deploy agent` are different commands. - Use `configs deploy` to sync a directory of config files; use `deploy agent` to create an agent from a template. + - **Important:** `deploy configs` and `deploy agent` are different commands. + Use `deploy configs` to sync a directory of config files; use `deploy agent` to create an agent from a template. ## Authoring Rules ### Script configs +- **Load the `build-script` skill for detailed script authoring guidance**, including syntax examples, common mistakes, and the validation/test/deploy workflow. - Treat the script language as a functional expression language, not a general-purpose imperative language. -- Use `archastro configs script-reference` for exact syntax and available namespaces. +- Use `archastro describe scriptdocs` for exact syntax and available namespaces. - If a script fails validation, prefer rewriting toward the sample/reference instead of trial-and-error improvisation. ### Routine configs inside templates @@ -89,6 +94,12 @@ Before any authoring work, verify the CLI: - `schedule: ""` - `event_type: schedule.cron` - Do not put schedules under nested `event_config.schedule`. +- To discover valid event types and their payload schemas: + ``` + archastro list events + archastro describe event + ``` + The payload schema from `describe event` shows what `$` contains in the routine's script handler. ### Config references @@ -102,16 +113,14 @@ Before any authoring work, verify the CLI: ## Recovery Rules -- If the user asks for a brand-new Script and the language shape is unclear, run `archastro configs script-reference` before drafting. +- If the user asks for a brand-new Script and the language shape is unclear, run `archastro describe scriptdocs` before drafting. - If validation fails, surface the exact failing field or syntax problem. Do not immediately switch to lower-level provisioning commands. -- If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to `agent_deploy`. +- If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to `deploy-agent`. ## Command Conventions -- Config management uses two patterns: - - **Noun-first** for workflow commands: `archastro configs deploy`, `archastro configs sync`, `archastro configs validate` - - **Verb-first** for CRUD: `archastro list configs`, `archastro describe config `, `archastro create config` -- Do not use `archastro configs list` or `archastro configs describe` — those are not valid. Use the verb-first form. +- All config commands are **verb-first**: `archastro list configs`, `archastro create config`, `archastro deploy configs`, `archastro sync configs`, `archastro validate config`, etc. +- There is no `archastro configs` namespace. Do not use `archastro configs ` — always put the verb first. ## Response Rules diff --git a/.claude-plugins/archastro/skills/build-script/SKILL.md b/.claude-plugins/archastro/skills/build-script/SKILL.md new file mode 100644 index 0000000..26a44fa --- /dev/null +++ b/.claude-plugins/archastro/skills/build-script/SKILL.md @@ -0,0 +1,299 @@ +--- +name: build-script +description: Use when the user wants to write, test, or deploy an ArchAstro script — custom logic for agent tools, workflow nodes, and routines. Trigger phrases include "build a script", "write a script", "create a script", "test a script", "script syntax", "script reference", "script language". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Script Builder + +Write, test, and deploy scripts — custom logic that powers agent tools, workflow nodes, and routines. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill. + +## What is a Script? + +Scripts are expression-oriented custom logic written in the ArchAstro script language. They can be used as: +- **Custom tool handlers**: Agent calls a tool → script runs → result returned to agent +- **Workflow graph script steps**: Script logic used inside a workflow graph +- **Routine handlers**: A scheduled routine runs the script directly + +Scripts are first-class resources with their own CRUD, validation, and execution commands. +Use the dedicated top-level script resource for the normal authoring loop: `archastro list scripts`, `describe script`, `create script`, `update script`, `validate script`, `run script`, and `describe scriptdocs`. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list scripts +``` + +Determine: +- Is the user creating a new script or editing an existing one? +- What will this script be used for? (tool, workflow node, routine) +- What external APIs or data does it need to access? + +## Routing + +### CLI not installed or too old + +Before any script work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. +- If authentication or app selection is missing, direct the user to `/archastro:auth`. + +### User wants to write a new script + +**Phase 1: Get the language reference** + +Always start by fetching the live reference — do not write scripts from memory: +``` +archastro describe scriptdocs +``` + +Use the top-level script commands, not `describe configsample`/`validate config`, for the normal authoring loop. + +Create a script from a local source file: +``` +archastro create script --id my-script --file ./scripts/my-script.agentscript +``` + +Or let the CLI start from its built-in sample if you do not pass `--source` or `--file`: +``` +archastro create script --id my-script +``` + +**Phase 2: Understand the requirements** + +Ask the user: +- What should the script do? +- What inputs will it receive? (accessible via `$` JSONPath) +- Does it need environment variables? (accessible via `env.KEY`) +- Does it need to make HTTP calls? + +If the script will handle a routine event, discover what `$` contains by checking the event's payload schema: +``` +archastro list events +archastro describe event +``` + +`describe event` returns the JSON schema and a sample payload. Every field in the payload is accessible via `$` in the script (e.g., `$.thread_id`, `$.message.content`). Always check the event schema before writing scripts that consume routine payloads — do not guess the shape from memory. + +**Phase 3: Author the script** + +Key language concepts: + +- **Input**: Access via `$` (JSONPath). E.g., `$.order_id`, `$.user.email` +- **Environment**: Access via `env.KEY`. E.g., `env.API_TOKEN` +- **Imports**: `import("requests")`, `import("array")`, `import("string")`, etc. +- **Error handling**: `unwrap(result)` or `unwrap(result, default_value)` +- **No loops**: Use `array.map`, `array.filter`, `array.reduce` +- **Expression-oriented**: The last expression in the script is the return value +- **Debugging**: Use `println()` to inspect values + +Example — HTTP lookup script: +``` +let http = import("requests") +let arr = import("array") + +let response = http.get(env.API_URL + "/orders/" + $.order_id, { + headers: { "Authorization": "Bearer " + env.API_TOKEN } +}) +let body = unwrap(response) + +{ + order_id: $.order_id, + status: body.status, + items: arr.map(body.line_items, fn(item) { + { name: item.name, qty: item.quantity } + }) +} +``` + +Available namespaces: +- `requests` — HTTP client (`get`, `post`, `put`, `patch`, `delete`) +- `array` — Collection operations (`map`, `filter`, `reduce`, `find`, `sort`, `flat_map`) +- `string` — String operations (`split`, `join`, `trim`, `lowercase`, `uppercase`, `contains`) +- `map` — Object operations (`keys`, `values`, `merge`, `get`) +- `datetime` — Date/time operations (`now`, `format`, `parse`, `add`) +- `math` — Math operations (`round`, `floor`, `ceil`, `abs`) +- `result` — Result type operations (`ok`, `err`, `is_ok`, `is_err`) +- `email` — Email sending +- `jwt` — JWT token operations +- `slack` — Slack API operations + +**Phase 4: Validate** + +Validate the script syntax: +``` +archastro validate script --file ./scripts/my-script.agentscript +``` + +Or validate as a config: +``` +archastro validate config -k Script -f ./configs/scripts/my-script.yaml +``` + +Fix any validation errors before proceeding. + +**Phase 5: Test** + +Run the script locally with test input: +``` +archastro run script --file ./scripts/my-script.agentscript --input '{"order_id": "ORD-123"}' +``` + +For scripts that need env vars, ensure they are set on the platform: +``` +archastro list orgenvvars +archastro create orgenvvar -k API_TOKEN -v "sk-..." +``` + +**Phase 6: Deploy** + +Scripts can be deployed two ways: + +**As a standalone script resource:** +``` +archastro create script --id order-lookup -n "Order Lookup" --file ./scripts/my-script.agentscript +``` + +Update an existing script resource: +``` +archastro update script order-lookup --file ./scripts/my-script.agentscript +``` + +**Via `deploy configs`** (for config-managed repos): + +Place `.agentscript` files in `configs/scripts/` and deploy: +``` +archastro deploy configs +``` + +The `scripts/` directory enforces that only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed — other file types are rejected. See the `manage-configs` skill for setting up the configs directory. + +**Phase 7: Wire it up** + +Connect the script to where it will be used: + +**As a custom tool on an agent:** + +The API requires `--config-id` pointing at the script's config ID even for script-handler tools: +``` +archastro create agenttool --agent \ + --kind custom \ + --name "lookup_order" \ + --description "Look up an order by ID" \ + --handler-type script \ + --config-id \ + --instruction "Use this tool when the user asks to look up an order." \ + --parameters '{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}' +``` + +Get the script's config ID from `archastro describe script --output json` (the `configId` field). + +**In a workflow graph:** Follow the real `WorkflowGraph` shape from `archastro describe workflowdocs` and the `build-workflow` skill. + +**As a routine handler** (reference by config ID — preferred for production): +``` +archastro create agentroutine --agent \ + --name "My scheduled script" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --config-id +``` + +Get the script's config ID from `archastro describe script --output json` (the `configId` field). + +Or inline for quick prototyping: +``` +archastro create agentroutine --agent \ + --name "Quick test" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --script 'println("hello")' +``` + +Prefer `--config-id` for production — it keeps the routine linked to a versioned script resource that can be updated independently. + +### User wants to edit an existing script + +1. **Inspect the current script**: + ``` + archastro list scripts + archastro describe script + ``` + +2. **Edit locally**, validate, and update: + ``` + archastro validate script --file ./scripts/my-script.agentscript + archastro update script --file ./scripts/my-script.agentscript + ``` + +## Common Mistakes + +**Do not write JSON — use script object syntax:** +``` +// WRONG — JSON syntax causes "unexpected token :" errors +{ "status": "ok", "count": 5 } + +// CORRECT — script uses unquoted keys +{ status: "ok", count: 5 } +``` + +**Do not use `return` — the last expression is the return value:** +``` +// WRONG +return { status: "ok" } + +// CORRECT +{ status: "ok" } +``` + +**Always import namespaces before using them:** +``` +// WRONG — "Unknown identifier" error +let now = datetime.now() + +// CORRECT +let dt = import("datetime") +let now = dt.now() +``` + +**No imperative loops — use array functions:** +``` +// WRONG — for/while don't exist +for item in items { ... } + +// CORRECT +let arr = import("array") +arr.map(items, fn(item) { ... }) +``` + +## Script Authoring Rules + +- **Always fetch `archastro describe scriptdocs` before writing scripts.** Do not invent syntax from memory. +- Prefer the dedicated top-level script commands over the generic `configs` resource unless the user explicitly wants config-managed files. +- Treat the language as functional and expression-oriented, not imperative. +- The last expression is the return value — there is no `return` keyword. +- Use `unwrap()` for error handling — never assume HTTP calls succeed. +- Use `println()` liberally while debugging, remove before deploying. +- If validation fails, rewrite toward the sample/reference instead of trial-and-error. + +## Recovery Rules + +- If a script fails validation, show the exact error. Common issues: missing imports, wrong function signatures, trying to use imperative loops. +- If `archastro run script` fails at runtime, check: are env vars set? Is the input JSON valid? Is the API reachable? +- If the user is unsure about syntax, always fall back to `archastro describe scriptdocs`. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Show the user a concrete script draft they can review, not abstract syntax explanations. diff --git a/.claude-plugins/archastro/skills/build-skill/SKILL.md b/.claude-plugins/archastro/skills/build-skill/SKILL.md new file mode 100644 index 0000000..fb19391 --- /dev/null +++ b/.claude-plugins/archastro/skills/build-skill/SKILL.md @@ -0,0 +1,175 @@ +--- +name: build-skill +description: Use when the user wants to create, edit, or publish an ArchAstro skill — a reusable package of instructions and supporting files that agents can use. Trigger phrases include "build a skill", "create a skill", "write a skill", "author a skill", "new skill", "skill template", "SKILL.md". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Skill Builder + +Create, edit, and publish skills — reusable instruction packages that agents invoke at runtime. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill. + +## What is a Skill? + +A skill is a file-backed bundle anchored by a `SKILL.md` root file with optional supporting files. Skills use the same managed virtual-path model as scripts and workflows: skills live under `skills//...`, scripts under `scripts/...`, and workflows under `workflows/...`. Agents invoke skills at runtime via the `get_skill` tool to load instructions on demand. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list skills +``` + +Determine whether the user wants to: +- create a brand-new skill, +- edit an existing skill, +- or inspect a skill before modifying it. + +## Routing + +### CLI not installed or too old + +Before any skill work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. +- If authentication or app selection is missing, direct the user to `/archastro:auth`. + +### User wants to create a new skill + +Walk through the authoring flow step by step. + +1. **Gather requirements**: + - What should the skill do? (purpose and scope) + - What trigger phrases should activate it? (for the description field) + - Does it need supporting files (templates, schemas, reference docs)? + - Which agent(s) will use it? + +2. **Choose a slug**: Short, lowercase, hyphen-separated identifier (e.g., `order-lookup`, `weekly-report`). This becomes the skill's permanent key. + +3. **Author the SKILL.md file locally**: + + Create a directory structure: + ``` + skills// + ├── SKILL.md # Root file (required) + └── references/ # Optional supporting files + └── example.md + ``` + + The SKILL.md must have YAML frontmatter: + ```yaml + --- + name: + description: + --- + + # Skill Title + + Detailed instructions for the agent... + ``` + +4. **Write effective skill instructions**: + - **Be concrete**: Provide exact CLI commands, API calls, or code patterns the agent should use. + - **Use phases**: Break complex workflows into numbered phases with clear entry/exit criteria. + - **Include routing**: Tell the agent how to handle different user intents within the skill's scope. + - **Add recovery rules**: What to do when things fail. + - **Set response rules**: How terse or verbose the agent should be. + - **Keep it narrow**: One skill, one job. If it's doing two things, split into two skills. + +5. **Publish the skill to the platform**: + + **Option A — Via `deploy configs`** (recommended when working with a configs/ directory): + + Place the skill directory under `configs/skills//` and deploy: + ``` + archastro deploy configs + ``` + This automatically creates the skill with name and description from the SKILL.md frontmatter, and publishes all supporting files as File configs. See the `manage-configs` skill for setting up the configs directory. + + **Option B — Via dedicated commands:** + ``` + archastro create skill -n "" -d "" -s --file ./skills//SKILL.md + ``` + + If there are supporting files, add them: + ``` + archastro create skillfile references/example.md --file ./skills//references/example.md + ``` + +6. **Verify the skill was created**: + ``` + archastro describe skill + archastro describe skillfile SKILL.md + ``` + +7. **Link the skill to an agent**: Skills are linked to agents via the agent's tools configuration. The agent needs a `get_skill` tool or the skill needs to be included in the agent's skill list. If the user has an agent they want to link: + ``` + archastro list agents + ``` + Then update the agent's config to reference the skill. + +### User wants to edit an existing skill + +1. **Inspect the current state**: + ``` + archastro describe skill + archastro describe skillfile SKILL.md + ``` + +2. **Make edits locally**, then update: + ``` + archastro update skillfile SKILL.md --file ./skills//SKILL.md + ``` + + For supporting files: + ``` + archastro update skillfile --file ./local/path + ``` + +3. **Verify the update**: + ``` + archastro describe skillfile SKILL.md + ``` + +### User wants to install a skill into their local coding harness + +Skills can be installed locally for use in Claude Code, Codex, or OpenCode: + +``` +archastro impersonate start +archastro impersonate list skills +archastro impersonate install skill --harness claude +archastro impersonate install skill --harness codex --install-scope project +archastro impersonate install skill --harness opencode +``` + +After installation, the skill appears in the local `.claude/skills/`, `.codex/skills/`, or `.opencode/skills/` directory. + +## Skill Authoring Best Practices + +- **Narrow scope**: Each skill should do one thing well. Split broad skills into composable pieces. +- **Concrete instructions**: Provide exact commands and patterns, not vague guidance. +- **Trigger phrases**: The description field is how agents route to the skill — make trigger phrases specific and varied. +- **Version awareness**: When updating a skill, keep in mind that running agents pick up changes on next invocation. +- **Review before publishing**: Skills are executable instructions — review them like code. +- **Supporting files**: Use `references/` subdirectories for large reference material the skill can load on demand. + +## Recovery Rules + +- If `archastro create skill` fails with a duplicate slug error, the skill already exists — offer to update it instead. +- If the user is unsure about the skill format, show them the SKILL.md template above. +- If the user asks for a "sample skill", generate one from the template with placeholder content tailored to their use case. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Prefer showing the user a concrete SKILL.md draft they can review over abstract guidance. diff --git a/.claude-plugins/archastro/skills/build-workflow/SKILL.md b/.claude-plugins/archastro/skills/build-workflow/SKILL.md new file mode 100644 index 0000000..4b01bfa --- /dev/null +++ b/.claude-plugins/archastro/skills/build-workflow/SKILL.md @@ -0,0 +1,283 @@ +--- +name: build-workflow +description: Use when the user wants to create, edit, or deploy a workflow — a multi-step process with branching, loops, HTTP calls, script execution, approvals, or scheduled routines. Trigger phrases include "build a workflow", "create a workflow", "design a workflow", "add a routine", "schedule a task", "automate this process", "set up a cron job", "workflow nodes". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Workflow Builder + +Create, edit, and deploy workflows — multi-step processes that agents execute via routines. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill. + +## What is a Workflow? + +A workflow is a directed graph of nodes that defines a multi-step process. Use the dedicated top-level workflow resource for authoring: `archastro list workflows`, `describe workflow`, `create workflow`, `update workflow`, `validate workflow`, and `describe workflowdocs`. Workflows are then attached to agent routines for execution. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list agents +``` + +Determine: +- Which agent will run this workflow? +- Is this a new workflow or an update to an existing one? +- What trigger should start it? (schedule, webhook, manual, message event) + +## Routing + +### CLI not installed or too old + +Before any workflow work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. +- If authentication or app selection is missing, direct the user to `/archastro:auth`. + +### Workflow commands not exposed in the current `archastro` build + +The source tree has dedicated top-level workflow commands, but some `archastro` builds may not expose them yet. Verify first: + +``` +archastro list workflows +archastro describe workflowdocs +``` + +If those commands are unavailable, do not keep insisting on them. Fall back to the config-managed workflow path and explain that the dedicated workflow resource exists in source but is not wired into the current binary. + +### User wants to create a new workflow + +**Phase 1: Gather requirements** + +Understand the workflow before writing any config: +- What triggers it? (cron schedule, webhook, message, manual) +- What are the steps? (in plain language) +- Are there branches or conditions? +- Does it need to call external APIs? +- Does it need to send emails, Slack messages, or other notifications? +- Does it loop over a collection? + +**Discover available events** to understand what can trigger the workflow and what data the trigger provides: +``` +archastro list events +``` + +Once the user picks an event type, show them the payload schema so they know what `$` contains in downstream scripts: +``` +archastro describe event +``` + +This returns the JSON schema and a sample payload. The payload fields are accessible via `$` in scripts (e.g., `$.thread_id`, `$.message.content`). + +**Phase 2: Scaffold the workflow** + +Use the top-level workflow commands, not `describe configsample`/`validate config`, for the normal authoring loop when the current `archastro` build exposes them. + +Create a workflow from a local JSON file: +``` +archastro create workflow --id my-workflow --file ./workflows/my-workflow.json +``` + +Or let the CLI start from its built-in sample if you do not pass `--graph` or `--file`: +``` +archastro create workflow --id my-workflow +``` + +**Phase 3: Author the workflow** + +A workflow is a `WorkflowGraph` JSON config under the hood, but the user-facing authoring path should go through the top-level workflow commands. + +A minimal workflow graph looks more like: +```json +{ + "kind": "WorkflowGraph", + "version": 1, + "name": "My Workflow", + "start_node": "trigger_1", + "nodes": [ + { + "kind": "WorkflowTrigger", + "id": "trigger_1", + "trigger": "workflow.scheduled", + "on_success": "script_1" + }, + { + "kind": "WorkflowScript", + "id": "script_1", + "script": "default-script" + } + ], + "data": [ + { + "kind": "Script", + "id": "default-script", + "script": "true" + } + ] +} +``` + +Use the live workflow docs when the graph shape is unclear: +``` +archastro describe workflowdocs +``` + +If `workflowdocs` is not available in the current binary, say so explicitly and fall back to the config-managed path instead of pretending the command exists. + +### Available node types + +Do not hard-code a node taxonomy in this skill. The supported graph/node model is owned by the workflow implementation and `archastro describe workflowdocs`. + +**Phase 4: Write supporting scripts** + +If the workflow needs script logic, author and validate that script first. Route to the `build-script` skill for detailed script authoring guidance, or get the reference directly: +``` +archastro describe scriptdocs +archastro describe configsample Script +``` + +**Phase 5: Validate** + +Validate the workflow graph through the dedicated workflow command: +``` +archastro validate workflow --file ./workflows/my-workflow.json +``` + +Validate any referenced scripts: +``` +archastro validate script --file ./scripts/my-script.agentscript +``` + +Fix any validation errors before deploying. + +**Phase 6: Deploy** + +Creating or updating the workflow through the top-level workflow commands persists it directly: +``` +archastro create workflow --id my-workflow --file ./workflows/my-workflow.json +archastro update workflow my-workflow --file ./workflows/my-workflow.json +``` + +If the top-level workflow commands are unavailable in the current binary, or if the user is working inside a broader config-managed repo and explicitly wants that flow, route to `manage-configs` instead. Do not claim the dedicated workflow commands are available unless you verified them in the running CLI. + +**Phase 7: Attach to a routine** + +Workflows run via agent routines. Create or update a routine to use the workflow: + +For a **scheduled** routine (cron): +``` +archastro create agentroutine --agent \ + --name "Daily report" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type workflow_graph \ + --config-id +``` + +For a **webhook-triggered** routine: +``` +archastro create agentroutine --agent \ + --name "Inbound webhook handler" \ + --event-type webhook.inbound \ + --handler-type workflow_graph \ + --config-id +``` + +To update an existing routine to use a workflow: +``` +archastro update agentroutine \ + --handler-type workflow_graph \ + --config-id +``` + +**Phase 8: Test and monitor** + +Check routine runs: +``` +archastro list agentroutineruns --routine +``` + +Use `println()` in scripts for debugging output. + +### User wants to edit an existing workflow + +1. **Inspect the current workflow**: + ``` + archastro list workflows + archastro describe workflow + ``` + +2. **Edit locally**, then validate and update: + ``` + archastro validate workflow --file ./workflows/my-workflow.json + archastro update workflow --file ./workflows/my-workflow.json + ``` + + The workflow resource versions on update; the agent picks up the linked workflow config on the next run. + +### User wants to set up a simple scheduled routine (no workflow) + +Not everything needs a full workflow graph. For simple scheduled tasks, a routine can use a script directly. + +**Reference a script resource** (preferred for production): +``` +archastro create script --id daily-check --file ./scripts/daily-check.agentscript +archastro create agentroutine --agent \ + --name "Daily check" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --config-id +``` +Get the config ID from `archastro describe script daily-check --output json` (the `configId` field). + +**Or inline for quick prototyping:** +``` +archastro create agentroutine --agent \ + --name "Daily check" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --script 'println("hello")' +``` + +Or include the routine in the AgentTemplate: +```yaml +routines: + - name: daily-check + event_type: schedule.cron + schedule: "0 9 * * 1-5" + handler_type: script + config_ref: daily-check-script +``` + +**Important**: Scheduled routines need both `schedule` and `event_type: schedule.cron`. Do not put schedules under nested `event_config.schedule`. + +## Workflow Design Best Practices + +- **Start simple**: Begin with a linear flow, add branching only when needed. +- **Name nodes clearly**: Use descriptive IDs (`fetch_orders`, `check_status`) not generic ones (`step1`, `step2`). +- **Handle errors**: Follow the real graph schema from `workflowdocs` and the sample config. Don't assume every HTTP call succeeds. +- **Use scripts for logic**: Keep business logic in Script resources or embedded workflow script data instead of improvising unsupported fields. +- **Test scripts independently**: Use `archastro run script --file ` to test scripts before wiring them into a workflow. +- **Cron syntax**: Standard 5-field cron. Use https://crontab.guru for help. + +## Recovery Rules + +- If workflow validation fails, show the exact error — it usually points to a specific node or field. +- If a routine run fails, check `archastro list agentroutineruns` for the error details. +- If a workflow depends on script logic that does not exist yet, create and validate that script first. +- If the user is unsure about workflow vs. simple routine, ask how many steps the process has. One step = simple routine. Multiple steps with branching = workflow. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- When authoring workflows, show the user a concrete JSON graph draft they can review. +- Prefer showing the full workflow structure over explaining node types abstractly. diff --git a/.claude-plugins/archastro/skills/chat/SKILL.md b/.claude-plugins/archastro/skills/chat/SKILL.md index c34943f..bff867d 100644 --- a/.claude-plugins/archastro/skills/chat/SKILL.md +++ b/.claude-plugins/archastro/skills/chat/SKILL.md @@ -10,6 +10,21 @@ Send messages to agents and view their responses. This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill. +## Quick Reference + +| Task | Command | +|------|---------| +| Ask agent a question | `archastro create agentsession --agent --instructions "..." --wait` | +| Create a thread | `archastro create thread --title "..." --owner-type agent --owner-id --json` | +| Create a test user | `archastro create user --system-user --name "..." --json` | +| Add member to thread | `archastro create threadmember --thread --user-id --json` | +| Add agent to thread | `archastro create threadmember --thread --agent-id --json` | +| Send message (wait for reply) | `archastro create threadmessage --thread --user-id -c "..." --wait --json` | +| View conversation | `archastro list threadmessages --thread --full` | +| List agent sessions | `archastro list agentsessions --agent --json` | + +Use `--help` on any command for full options. + ## Always Start with State Every invocation must begin by understanding the current context. Determine: @@ -81,14 +96,7 @@ Use `describe --follow` to stream updates on a session created without `--wait`. ### User wants to send a thread message -1. **Determine the sender ID**: - - **Org mode**: Get the user's ID from `archastro auth status`. - - **Developer mode**: Look up thread members: - ``` - archastro list threadmembers --thread - ``` +1. **Determine the sender ID**: Get the user's ID from `archastro auth status`. 2. **Send the message and wait for the response**: ``` @@ -110,14 +118,39 @@ Always use `--full` — the default table view truncates content. ### User needs a new thread +**Agent-owned thread** (recommended when an agent should participate): + +1. Create the thread owned by the agent: + ``` + archastro create thread --title "..." --owner-type agent --owner-id --json + ``` + +2. Create a test user (if needed) and add them to the thread: + ``` + archastro create user --system-user --name "Test User" --json + archastro create threadmember --thread --user-id --json + ``` + +3. Send a message and wait for the agent to respond: + ``` + archastro create threadmessage --thread --user-id -c "Hello" --wait --json + ``` + +4. View the conversation: + ``` + archastro list threadmessages --thread --full + ``` + +**User-owned thread** (when a user starts the conversation): + 1. Create the thread: ``` - archastro create thread --title "..." --user + archastro create thread --title "..." --user --json ``` -2. Add members: +2. Add the agent: ``` - archastro create threadmember --thread --agent-id + archastro create threadmember --thread --agent-id --json ``` ## Response Rules diff --git a/.claude-plugins/archastro/skills/agent_deploy/SKILL.md b/.claude-plugins/archastro/skills/deploy-agent/SKILL.md similarity index 88% rename from .claude-plugins/archastro/skills/agent_deploy/SKILL.md rename to .claude-plugins/archastro/skills/deploy-agent/SKILL.md index c917771..03e45a9 100644 --- a/.claude-plugins/archastro/skills/agent_deploy/SKILL.md +++ b/.claude-plugins/archastro/skills/deploy-agent/SKILL.md @@ -1,5 +1,5 @@ --- -name: agent_deploy +name: deploy-agent description: Use when the user wants to deploy an ArchAstro agent, turn a config-driven agent repo into a running agent, or get an existing agent running in a thread. Trigger phrases include "deploy agent", "deploy this agent", "set up an agent", "launch agent", "ship this agent", "get this agent running". allowed-tools: ["Bash(archastro:*)"] --- @@ -35,13 +35,17 @@ Before any deployment work, verify the CLI: - Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. - If authentication or app selection is missing, direct the user to `/archastro:auth`. +### Local config directory not initialized + +If the user has config files but no `configs/` directory set up, route to the `manage-configs` skill first. That skill owns local config management. + ### User wants to deploy a new agent Use the config-driven golden path. Do not skip straight to `create agent`. 1. **Deploy configs first**: ``` - archastro configs deploy + archastro deploy configs ``` This pushes Script and AgentTemplate configs to the server. For config-driven agents, this should happen before provisioning the agent itself. @@ -62,10 +66,10 @@ Use the config-driven golden path. Do not skip straight to `create agent`. ### User needs help creating or editing the config files first -Route to the `agent_authoring` skill before deploying. That skill owns: +Route to the `author-agent` skill before deploying. That skill owns: - `AgentTemplate` and Script config creation -- `archastro configs sample` -- `archastro configs script-reference` +- `archastro describe configsample` +- `archastro describe scriptdocs` - routine scheduling shape - env-var scope guidance @@ -100,11 +104,11 @@ Summarize what's deployed and offer to deploy a new one or add an existing one t ## Recovery Rules - If `archastro deploy agent` fails with a validation-style error, inspect the exact CLI output first. Do not immediately fall back to lower-level provisioning commands. -- If the problem appears to be in the config files, route to `agent_authoring`. +- If the problem appears to be in the config files, route to `author-agent`. - If a script-related validation error appears, use: ``` - archastro configs script-reference - archastro configs sample Script + archastro describe scriptdocs + archastro describe configsample Script ``` Do not invent script syntax from memory. - Prefer human-readable `config_ref` names that match deployed config lookup keys. Do not rewrite refs to raw `cfg_...` IDs unless explicitly debugging a broken environment. diff --git a/.claude-plugins/archastro/skills/impersonate/SKILL.md b/.claude-plugins/archastro/skills/impersonate/SKILL.md index ba4e4f3..7f6e9ea 100644 --- a/.claude-plugins/archastro/skills/impersonate/SKILL.md +++ b/.claude-plugins/archastro/skills/impersonate/SKILL.md @@ -4,15 +4,15 @@ description: Use when the user wants to impersonate an ArchAstro agent, asks abo allowed-tools: ["Bash(archastro:*)"] --- -# ArchAstro Agent Impersonation +# ArchAstro Impersonation -Manage ArchAstro agent impersonation and keep the Claude Code session aligned with the active identity. +Manage ArchAstro impersonation through the ArchAstro CLI and keep the Claude Code session aligned with the active identity file. This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill. ## Always Start with State -Every invocation of this skill must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. +Every invocation must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. ``` archastro impersonate status --json @@ -26,8 +26,7 @@ Then route based on the combination of current state and user intent. Before any impersonation work, verify the CLI: -- Read `plugin-compatibility.json` from the plugin root. -- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Read `plugin-compatibility.json` from the plugin root. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. - Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. - If authentication or app selection is missing, direct the user to `/archastro:auth`. @@ -85,6 +84,20 @@ archastro impersonate stop Drop the impersonated identity from the current session. Confirm that local state was removed. +### Active + user asks about tools + +List the impersonated agent's tools: + +``` +archastro impersonate list tools --json +``` + +To execute a tool directly: + +``` +archastro impersonate run tool --input '' --json +``` + ### Active + user asks about skills List available skills: @@ -125,6 +138,11 @@ When you read the identity file, you must **become that agent** for the rest of After `stop`, fully drop the persona and return to your normal behavior. +## Limitations + +- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. +- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. + ## Session Integration - After `start` or `sync`, always read the identity file and adopt it as described above @@ -132,11 +150,6 @@ After `stop`, fully drop the persona and return to your normal behavior. - When showing status, always include loaded skill invocations so the user knows what commands are available - When skills are available but not installed, proactively mention them -## Limitations - -- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. -- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. - ## Response Rules - Do not inspect or edit credential files directly — use the CLI only. diff --git a/.claude-plugins/archastro/skills/manage-configs/SKILL.md b/.claude-plugins/archastro/skills/manage-configs/SKILL.md new file mode 100644 index 0000000..1b4b00c --- /dev/null +++ b/.claude-plugins/archastro/skills/manage-configs/SKILL.md @@ -0,0 +1,229 @@ +--- +name: manage-configs +description: Use when the user wants to set up or manage local config files for an ArchAstro project — initialize a configs directory, edit configs locally, sync from the server, or deploy local changes. Trigger phrases include "set up configs", "init configs", "configs directory", "sync configs", "deploy configs", "edit config locally", "local config management". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Local Config Management + +Set up and manage a local `configs/` directory for editing agent configs as files, syncing with the server, and deploying changes. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill. + +## What is Local Config Management? + +Instead of creating and editing configs one-by-one through CLI CRUD commands, you can manage them as local files in a `configs/` directory. This enables: +- **Edit configs in your editor** with syntax highlighting and version control +- **Batch deploy** all changes in dependency order +- **Sync** server configs down to local files +- **Browser editor** for visual editing of individual configs + +The CLI tracks the mapping between local files and server configs in a manifest file. + +## Always Start with State + +Every invocation must begin by understanding the current project state: + +``` +archastro auth status +ls configs/ 2>/dev/null || echo "No configs directory" +``` + +Determine: +- Does a `configs/` directory already exist? +- Is the user starting a new project or working with an existing one? +- Do they want to pull configs from the server or push local changes? + +## Routing + +### CLI not installed or too old + +Before any config work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`. +- If authentication or app selection is missing, direct the user to `/archastro:auth`. + +### User wants to set up a configs directory for the first time + +1. **Initialize the config directory**: + ``` + archastro init --enable-configs + ``` + This enables local config management and creates the configured `configs/` directory if needed. It does not automatically sync remote configs; use `archastro sync configs` next when you want local files. + +2. **Explain the layout**: After init, the directory looks like: + ``` + configs/ + ├── .archastro-manifest.json # Maps local files to server configs (do not edit manually) + ├── agents/ # AgentTemplate configs + ├── skills/ # Skill bundles + ├── scripts/ # Script configs + ├── workflows/ # Workflow configs + └── ... # Other config kinds + ``` + + Managed virtual paths also follow these prefixes on the server: `skills/`, `scripts/`, and `workflows/`. + +3. **Offer next steps**: Ask if the user wants to create a new config (`archastro describe configsample `) or sync existing configs from the server. + +### User wants to pull configs from the server + +Sync server configs to local files: +``` +archastro sync configs +``` + +This downloads all configs for the current app — including skills, scripts, and workflows — and writes them as local files in the correct directories. The manifest tracks the file-to-config mapping. + +After syncing, the directory structure reflects server state: +``` +configs/ +├── agents/ # AgentTemplate configs (.yaml) +├── skills/my-skill/ # Skill bundles (SKILL.md + supporting files) +├── scripts/ # Script configs (.agentscript) +├── workflows/ # Workflow configs (.json) +└── ... # Other config kinds +``` + +You can then edit any file locally and run `archastro deploy configs` to push changes back. + +### User wants to create a new config locally + +For **scripts**, **skills**, and **workflows**, prefer the dedicated commands or create files directly in the correct directory: + +- **Script**: Write a `.agentscript` file in `configs/scripts/`: + ``` + configs/scripts/my-script.agentscript + ``` +- **Skill**: Create a `SKILL.md` (with frontmatter) in `configs/skills//`: + ``` + configs/skills/my-skill/SKILL.md + configs/skills/my-skill/prompts/greeting.liquid # optional supporting files + ``` +- **Workflow**: Write a `.json` file in `configs/workflows/`: + ``` + configs/workflows/my-workflow.json + ``` + +For **other config kinds** (AgentTemplate, Persona, etc.), get a sample: +``` +archastro list configkinds +archastro describe configsample --to-file ./configs//.yaml +``` + +You can also use the browser editor: +``` +archastro edit config ./configs//.yaml +``` + +### User wants to validate local configs + +Validate a specific config file: +``` +archastro validate config -k -f ./configs//.yaml +``` + +For scripts specifically, use the dedicated validator: +``` +archastro validate script --file ./configs/scripts/my-script.agentscript +``` + +### User wants to deploy local changes + +Push all local config changes to the server: +``` +archastro deploy configs +``` + +This: +- Compares local files against the manifest +- Uploads new and changed configs in dependency order +- Updates the manifest with new server IDs + +#### Managed directory conventions + +`deploy configs` enforces conventions for three managed directories: + +| Directory | Convention | +|-----------|-----------| +| `skills//` | All files become `File` kind. `SKILL.md` is the root — name and description are extracted from its YAML frontmatter. Other files (`.liquid`, `.yaml`, `.js`, etc.) become supporting skill files. | +| `scripts/` | Only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed. Other file types are rejected. | +| `workflows/` | Only `.json` files and `.yaml` with a `Workflow*` kind are allowed. Other file types are rejected. | + +Files outside these directories use standard kind inference from file extension or YAML content. + +**Important**: `deploy configs` syncs config files only. It does not create agents. To provision an agent from a template, use `archastro deploy agent ` separately. + +### User wants to move or rename a config file + +If a local config file is moved or renamed: +``` +archastro update configpath +``` + +This updates the manifest mapping without affecting the server config. + +### User has manifest issues + +If the manifest gets out of sync: +``` +archastro validate configmanifest +``` + +This re-normalizes the manifest and resolves any inconsistencies. + +## Typical Workflows + +### New project from scratch +``` +archastro init --enable-configs +archastro describe configsample AgentTemplate --to-file ./configs/agents/my-agent.yaml +# Edit the file... +archastro validate config -k AgentTemplate -f ./configs/agents/my-agent.yaml +archastro deploy configs +archastro deploy agent ./configs/agents/my-agent.yaml +``` + +### Create a skill via local files +``` +archastro init --enable-configs +mkdir -p configs/skills/my-skill +# Write SKILL.md with frontmatter (name, description) +# Add supporting files (prompts, references, etc.) +archastro deploy configs +# Skill is now visible via: archastro list skills +``` + +### Create a script via local files +``` +archastro init --enable-configs +# Write script source directly +echo 'println("hello")' > configs/scripts/my-script.agentscript +archastro deploy configs +# Script is now visible via: archastro describe script my-script +``` + +### Pull existing project and make changes +``` +archastro init --enable-configs +archastro sync configs +# Edit files locally... +archastro deploy configs +``` + +### Quick edit via browser +``` +archastro edit config ./configs/agents/my-agent.yaml +# Opens in browser with live validation +# Changes are saved to the server and synced back to the local file +``` + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not manually edit `.archastro-manifest.json` — use CLI commands. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Always recommend `deploy configs` over individual `create config` calls when working with local files. diff --git a/plugins/archastro/.codex-plugin/plugin.json b/plugins/archastro/.codex-plugin/plugin.json index 7c96f4e..dbecc02 100644 --- a/plugins/archastro/.codex-plugin/plugin.json +++ b/plugins/archastro/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "archastro", - "version": "0.3.1", - "description": "Deploy, manage, chat with, and impersonate ArchAstro agents from Codex through the ArchAstro CLI.", + "version": "0.3.2", + "description": "Author, deploy, manage, chat with, and impersonate ArchAstro agents from Codex through the ArchAstro CLI.", "author": { "name": "ArchAstro", "email": "dev@archastro.com", @@ -22,8 +22,8 @@ "skills": "./skills/", "interface": { "displayName": "ArchAstro", - "shortDescription": "Complete ArchAstro workflows for Codex: authoring, deployment, chat, and impersonation.", - "longDescription": "Use the public ArchAstro CLI from Codex to author agent configs, deploy agents, chat with running agents, and impersonate deployed ArchAstro agents from the current session.", + "shortDescription": "Complete ArchAstro workflows for Codex: authoring, deployment, scripts, workflows, configs, chat, and impersonation.", + "longDescription": "Use the public ArchAstro CLI from Codex to author agent configs, manage local config files, build scripts, skills, and workflows, deploy agents, chat with running agents, and impersonate deployed ArchAstro agents from the current session.", "developerName": "ArchAstro", "category": "Development", "capabilities": [ @@ -34,7 +34,7 @@ "websiteURL": "https://github.com/ArchAstro/archastro-cli", "defaultPrompt": [ "Author a config-driven ArchAstro agent.", - "Deploy an ArchAstro agent.", + "Set up local configs for this repo.", "Chat with a deployed ArchAstro agent.", "Start impersonating an ArchAstro agent." ], diff --git a/plugins/archastro/skills/auth/SKILL.md b/plugins/archastro/skills/auth/SKILL.md index 1de997d..5e2d0c7 100644 --- a/plugins/archastro/skills/auth/SKILL.md +++ b/plugins/archastro/skills/auth/SKILL.md @@ -6,73 +6,49 @@ allowed-tools: ["Bash(archastro:*)"] # ArchAstro CLI Authentication -Authenticate the user with the ArchAstro developer platform via browser-based login. Defaults to org mode (Agent Network). +Authenticate the user with the ArchAstro developer platform via browser-based login. -## Instructions +## Workflow 1. **Read the compatibility contract first**: - - Use `plugin-compatibility.json`. - - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`. - - Treat that resolved value as the minimum supported CLI version for every check below. + - Use `plugin-compatibility.json` from the plugin root. + - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. + - Treat the resolved value as the minimum supported CLI version for every check below. 2. **Check the installed CLI version first**: ``` archastro --version ``` - If the command is missing, or the version is older than the resolved minimum version, instruct the user to install or upgrade `archastro`. + If the command is missing, or the version is older than the resolved minimum, instruct the user to install or upgrade `archastro`. -3. **Check if already authenticated**: +3. **Check whether the user is already authenticated**: ``` archastro auth status ``` - If the user is already authenticated, show their status and ask if they want to re-authenticate. + If the user is already authenticated, show their status and ask whether they want to re-authenticate. -4. **Determine the auth mode**: - - The default is **org mode** (Agent Network). Only use developer mode if the user explicitly asks to log in as a developer or app builder. - - - **Org mode** (default): For users within an organization. No app slug needed — defaults to Agent Network. - - **Developer mode**: For building and managing apps on the platform. Requires the `--dev` flag. - -5. **Reset any stale settings overrides** that may point to localhost: +4. **Reset any stale settings overrides that may point to localhost**: ``` archastro settings reset ``` This ensures the CLI uses the production URLs. -6. **Start the login flow**: - - **Org mode (default):** +5. **Start the login flow**: ``` archastro auth login ``` + Keep the session responsive while the browser-based auth flow runs. - **Org mode for a specific app** (if the user specifies a different app slug): - ``` - archastro auth login --app - ``` - - **Developer mode** (only if explicitly requested): - ``` - archastro auth login --dev - ``` - - Use `run_in_background: true` so the browser-based auth flow runs while you remain responsive. - - The CLI will open the user's browser to https://developers.archastro.ai for authentication and print a URL in case the browser doesn't open automatically. +6. **Tell the user the auth flow is running** and they should complete login in their browser. The CLI opens `https://developers.archastro.ai` and prints a URL if the browser does not open automatically. -7. **Tell the user** the auth flow is running and they should complete login in their browser. Let them know you're available to keep working on other things while waiting. - -8. **When the user says they've logged in** (or you're ready to check), wait for the command to finish and then re-check status. - -9. **On success**, confirm authentication succeeded and show their status: +7. **When the user says they have logged in**, or when it is time to re-check, wait for the login command to finish and then run: ``` archastro auth status ``` - For org mode, verify the output shows `Auth mode: org` and the correct app/org name. -10. **On failure**, show the error and suggest: - - Check their internet connection - - Try `archastro settings reset` if URLs look wrong - - `no-access` error means the user doesn't have org access — verify with an org admin for an invite - - Try again with `archastro auth login` +8. **On success**, confirm authentication succeeded and show the user their status. + +9. **On failure**, show the error and suggest: + - Check their internet connection. + - Try `archastro settings reset` if URLs look wrong. + - Try again with `archastro auth login`. diff --git a/plugins/archastro/skills/agent_authoring/SKILL.md b/plugins/archastro/skills/author-agent/SKILL.md similarity index 73% rename from plugins/archastro/skills/agent_authoring/SKILL.md rename to plugins/archastro/skills/author-agent/SKILL.md index 9574897..1e0ab62 100644 --- a/plugins/archastro/skills/agent_authoring/SKILL.md +++ b/plugins/archastro/skills/author-agent/SKILL.md @@ -1,5 +1,5 @@ --- -name: agent_authoring +name: author-agent description: Use when the user wants to create or edit an ArchAstro agent's config files before deployment, including AgentTemplate files, Script configs, custom tools, routines, and environment setup. Trigger phrases include "build this agent", "write the template", "create the scripts", "set up the routines", "author this agent config". allowed-tools: ["Bash(archastro:*)"] --- @@ -31,19 +31,23 @@ Before any authoring work, verify the CLI: - Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. - If authentication or app selection is missing, instruct the user to run `archastro auth login`. +### Local config directory not initialized + +If the user doesn't have a `configs/` directory set up yet, route to the `manage-configs` skill first. That skill owns `archastro init --enable-configs`, local file layout, and the sync/deploy workflow. + ### User wants to author or modify agent configs 1. **Start from CLI-backed templates, not memory**: - For new config objects, use: ``` - archastro configs sample + archastro describe configsample ``` - For Script configs, always use: ``` - archastro configs script-reference - archastro configs sample Script + archastro describe scriptdocs + archastro describe configsample Script ``` - The script reference is the live source of truth. Do not invent or paraphrase the language from memory. + The script docs are the live source of truth. Do not invent or paraphrase the language from memory. 2. **Use the standard config-driven model**: - Script logic lives in `kind: Script` configs. @@ -56,14 +60,14 @@ Before any authoring work, verify the CLI: 3. **Validate early**: ``` - archastro configs validate + archastro validate config -k -f ``` Run validation before deploy whenever the user changes Script or template files. 4. **Deploy through the normal flow after authoring**: - If the agent has Script configs or other supporting files, sync them first: ``` - archastro configs deploy + archastro deploy configs ``` This pushes local config files (Scripts, templates) but does not create agents. Skip this step if the agent only has a single AgentTemplate file — `deploy agent` handles its own config upload. @@ -72,15 +76,16 @@ Before any authoring work, verify the CLI: archastro deploy agent ``` This uploads the template config and creates the agent with its routines, tools, and installations. - - **Important:** `configs deploy` and `deploy agent` are different commands. - Use `configs deploy` to sync a directory of config files; use `deploy agent` to create an agent from a template. + - **Important:** `deploy configs` and `deploy agent` are different commands. + Use `deploy configs` to sync a directory of config files; use `deploy agent` to create an agent from a template. ## Authoring Rules ### Script configs +- **Load the `build-script` skill for detailed script authoring guidance**, including syntax examples, common mistakes, and the validation/test/deploy workflow. - Treat the script language as a functional expression language, not a general-purpose imperative language. -- Use `archastro configs script-reference` for exact syntax and available namespaces. +- Use `archastro describe scriptdocs` for exact syntax and available namespaces. - If a script fails validation, prefer rewriting toward the sample/reference instead of trial-and-error improvisation. ### Routine configs inside templates @@ -89,6 +94,12 @@ Before any authoring work, verify the CLI: - `schedule: ""` - `event_type: schedule.cron` - Do not put schedules under nested `event_config.schedule`. +- To discover valid event types and their payload schemas: + ``` + archastro list events + archastro describe event + ``` + The payload schema from `describe event` shows what `$` contains in the routine's script handler. ### Config references @@ -102,16 +113,14 @@ Before any authoring work, verify the CLI: ## Recovery Rules -- If the user asks for a brand-new Script and the language shape is unclear, run `archastro configs script-reference` before drafting. +- If the user asks for a brand-new Script and the language shape is unclear, run `archastro describe scriptdocs` before drafting. - If validation fails, surface the exact failing field or syntax problem. Do not immediately switch to lower-level provisioning commands. -- If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to `agent_deploy`. +- If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to `deploy-agent`. ## Command Conventions -- Config management uses two patterns: - - **Noun-first** for workflow commands: `archastro configs deploy`, `archastro configs sync`, `archastro configs validate` - - **Verb-first** for CRUD: `archastro list configs`, `archastro describe config `, `archastro create config` -- Do not use `archastro configs list` or `archastro configs describe` — those are not valid. Use the verb-first form. +- All config commands are **verb-first**: `archastro list configs`, `archastro create config`, `archastro deploy configs`, `archastro sync configs`, `archastro validate config`, etc. +- There is no `archastro configs` namespace. Do not use `archastro configs ` — always put the verb first. ## Response Rules diff --git a/plugins/archastro/skills/build-script/SKILL.md b/plugins/archastro/skills/build-script/SKILL.md new file mode 100644 index 0000000..bd0253d --- /dev/null +++ b/plugins/archastro/skills/build-script/SKILL.md @@ -0,0 +1,299 @@ +--- +name: build-script +description: Use when the user wants to write, test, or deploy an ArchAstro script — custom logic for agent tools, workflow nodes, and routines. Trigger phrases include "build a script", "write a script", "create a script", "test a script", "script syntax", "script reference", "script language". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Script Builder + +Write, test, and deploy scripts — custom logic that powers agent tools, workflow nodes, and routines. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated. + +## What is a Script? + +Scripts are expression-oriented custom logic written in the ArchAstro script language. They can be used as: +- **Custom tool handlers**: Agent calls a tool → script runs → result returned to agent +- **Workflow graph script steps**: Script logic used inside a workflow graph +- **Routine handlers**: A scheduled routine runs the script directly + +Scripts are first-class resources with their own CRUD, validation, and execution commands. +Use the dedicated top-level script resource for the normal authoring loop: `archastro list scripts`, `describe script`, `create script`, `update script`, `validate script`, `run script`, and `describe scriptdocs`. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list scripts +``` + +Determine: +- Is the user creating a new script or editing an existing one? +- What will this script be used for? (tool, workflow node, routine) +- What external APIs or data does it need to access? + +## Routing + +### CLI not installed or too old + +Before any script work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. +- If authentication or app selection is missing, instruct the user to run `archastro auth login`. + +### User wants to write a new script + +**Phase 1: Get the language reference** + +Always start by fetching the live reference — do not write scripts from memory: +``` +archastro describe scriptdocs +``` + +Use the top-level script commands, not `describe configsample`/`validate config`, for the normal authoring loop. + +Create a script from a local source file: +``` +archastro create script --id my-script --file ./scripts/my-script.agentscript +``` + +Or let the CLI start from its built-in sample if you do not pass `--source` or `--file`: +``` +archastro create script --id my-script +``` + +**Phase 2: Understand the requirements** + +Ask the user: +- What should the script do? +- What inputs will it receive? (accessible via `$` JSONPath) +- Does it need environment variables? (accessible via `env.KEY`) +- Does it need to make HTTP calls? + +If the script will handle a routine event, discover what `$` contains by checking the event's payload schema: +``` +archastro list events +archastro describe event +``` + +`describe event` returns the JSON schema and a sample payload. Every field in the payload is accessible via `$` in the script (e.g., `$.thread_id`, `$.message.content`). Always check the event schema before writing scripts that consume routine payloads — do not guess the shape from memory. + +**Phase 3: Author the script** + +Key language concepts: + +- **Input**: Access via `$` (JSONPath). E.g., `$.order_id`, `$.user.email` +- **Environment**: Access via `env.KEY`. E.g., `env.API_TOKEN` +- **Imports**: `import("requests")`, `import("array")`, `import("string")`, etc. +- **Error handling**: `unwrap(result)` or `unwrap(result, default_value)` +- **No loops**: Use `array.map`, `array.filter`, `array.reduce` +- **Expression-oriented**: The last expression in the script is the return value +- **Debugging**: Use `println()` to inspect values + +Example — HTTP lookup script: +``` +let http = import("requests") +let arr = import("array") + +let response = http.get(env.API_URL + "/orders/" + $.order_id, { + headers: { "Authorization": "Bearer " + env.API_TOKEN } +}) +let body = unwrap(response) + +{ + order_id: $.order_id, + status: body.status, + items: arr.map(body.line_items, fn(item) { + { name: item.name, qty: item.quantity } + }) +} +``` + +Available namespaces: +- `requests` — HTTP client (`get`, `post`, `put`, `patch`, `delete`) +- `array` — Collection operations (`map`, `filter`, `reduce`, `find`, `sort`, `flat_map`) +- `string` — String operations (`split`, `join`, `trim`, `lowercase`, `uppercase`, `contains`) +- `map` — Object operations (`keys`, `values`, `merge`, `get`) +- `datetime` — Date/time operations (`now`, `format`, `parse`, `add`) +- `math` — Math operations (`round`, `floor`, `ceil`, `abs`) +- `result` — Result type operations (`ok`, `err`, `is_ok`, `is_err`) +- `email` — Email sending +- `jwt` — JWT token operations +- `slack` — Slack API operations + +**Phase 4: Validate** + +Validate the script syntax: +``` +archastro validate script --file ./scripts/my-script.agentscript +``` + +Or validate as a config: +``` +archastro validate config -k Script -f ./configs/scripts/my-script.yaml +``` + +Fix any validation errors before proceeding. + +**Phase 5: Test** + +Run the script locally with test input: +``` +archastro run script --file ./scripts/my-script.agentscript --input '{"order_id": "ORD-123"}' +``` + +For scripts that need env vars, ensure they are set on the platform: +``` +archastro list orgenvvars +archastro create orgenvvar -k API_TOKEN -v "sk-..." +``` + +**Phase 6: Deploy** + +Scripts can be deployed two ways: + +**As a standalone script resource:** +``` +archastro create script --id order-lookup -n "Order Lookup" --file ./scripts/my-script.agentscript +``` + +Update an existing script resource: +``` +archastro update script order-lookup --file ./scripts/my-script.agentscript +``` + +**Via `deploy configs`** (for config-managed repos): + +Place `.agentscript` files in `configs/scripts/` and deploy: +``` +archastro deploy configs +``` + +The `scripts/` directory enforces that only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed — other file types are rejected. See the `manage-configs` skill for setting up the configs directory. + +**Phase 7: Wire it up** + +Connect the script to where it will be used: + +**As a custom tool on an agent:** + +The API requires `--config-id` pointing at the script's config ID even for script-handler tools: +``` +archastro create agenttool --agent \ + --kind custom \ + --name "lookup_order" \ + --description "Look up an order by ID" \ + --handler-type script \ + --config-id \ + --instruction "Use this tool when the user asks to look up an order." \ + --parameters '{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}' +``` + +Get the script's config ID from `archastro describe script --output json` (the `configId` field). + +**In a workflow graph:** Follow the real `WorkflowGraph` shape from `archastro describe workflowdocs` and the `build-workflow` skill. + +**As a routine handler** (reference by config ID — preferred for production): +``` +archastro create agentroutine --agent \ + --name "My scheduled script" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --config-id +``` + +Get the script's config ID from `archastro describe script --output json` (the `configId` field). + +Or inline for quick prototyping: +``` +archastro create agentroutine --agent \ + --name "Quick test" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --script 'println("hello")' +``` + +Prefer `--config-id` for production — it keeps the routine linked to a versioned script resource that can be updated independently. + +### User wants to edit an existing script + +1. **Inspect the current script**: + ``` + archastro list scripts + archastro describe script + ``` + +2. **Edit locally**, validate, and update: + ``` + archastro validate script --file ./scripts/my-script.agentscript + archastro update script --file ./scripts/my-script.agentscript + ``` + +## Common Mistakes + +**Do not write JSON — use script object syntax:** +``` +// WRONG — JSON syntax causes "unexpected token :" errors +{ "status": "ok", "count": 5 } + +// CORRECT — script uses unquoted keys +{ status: "ok", count: 5 } +``` + +**Do not use `return` — the last expression is the return value:** +``` +// WRONG +return { status: "ok" } + +// CORRECT +{ status: "ok" } +``` + +**Always import namespaces before using them:** +``` +// WRONG — "Unknown identifier" error +let now = datetime.now() + +// CORRECT +let dt = import("datetime") +let now = dt.now() +``` + +**No imperative loops — use array functions:** +``` +// WRONG — for/while don't exist +for item in items { ... } + +// CORRECT +let arr = import("array") +arr.map(items, fn(item) { ... }) +``` + +## Script Authoring Rules + +- **Always fetch `archastro describe scriptdocs` before writing scripts.** Do not invent syntax from memory. +- Prefer the dedicated top-level script commands over the generic `configs` resource unless the user explicitly wants config-managed files. +- Treat the language as functional and expression-oriented, not imperative. +- The last expression is the return value — there is no `return` keyword. +- Use `unwrap()` for error handling — never assume HTTP calls succeed. +- Use `println()` liberally while debugging, remove before deploying. +- If validation fails, rewrite toward the sample/reference instead of trial-and-error. + +## Recovery Rules + +- If a script fails validation, show the exact error. Common issues: missing imports, wrong function signatures, trying to use imperative loops. +- If `archastro run script` fails at runtime, check: are env vars set? Is the input JSON valid? Is the API reachable? +- If the user is unsure about syntax, always fall back to `archastro describe scriptdocs`. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Show the user a concrete script draft they can review, not abstract syntax explanations. diff --git a/plugins/archastro/skills/build-skill/SKILL.md b/plugins/archastro/skills/build-skill/SKILL.md new file mode 100644 index 0000000..8648c81 --- /dev/null +++ b/plugins/archastro/skills/build-skill/SKILL.md @@ -0,0 +1,175 @@ +--- +name: build-skill +description: Use when the user wants to create, edit, or publish an ArchAstro skill — a reusable package of instructions and supporting files that agents can use. Trigger phrases include "build a skill", "create a skill", "write a skill", "author a skill", "new skill", "skill template", "SKILL.md". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Skill Builder + +Create, edit, and publish skills — reusable instruction packages that agents invoke at runtime. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated. + +## What is a Skill? + +A skill is a file-backed bundle anchored by a `SKILL.md` root file with optional supporting files. Skills use the same managed virtual-path model as scripts and workflows: skills live under `skills//...`, scripts under `scripts/...`, and workflows under `workflows/...`. Agents invoke skills at runtime via the `get_skill` tool to load instructions on demand. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list skills +``` + +Determine whether the user wants to: +- create a brand-new skill, +- edit an existing skill, +- or inspect a skill before modifying it. + +## Routing + +### CLI not installed or too old + +Before any skill work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. +- If authentication or app selection is missing, instruct the user to run `archastro auth login`. + +### User wants to create a new skill + +Walk through the authoring flow step by step. + +1. **Gather requirements**: + - What should the skill do? (purpose and scope) + - What trigger phrases should activate it? (for the description field) + - Does it need supporting files (templates, schemas, reference docs)? + - Which agent(s) will use it? + +2. **Choose a slug**: Short, lowercase, hyphen-separated identifier (e.g., `order-lookup`, `weekly-report`). This becomes the skill's permanent key. + +3. **Author the SKILL.md file locally**: + + Create a directory structure: + ``` + skills// + ├── SKILL.md # Root file (required) + └── references/ # Optional supporting files + └── example.md + ``` + + The SKILL.md must have YAML frontmatter: + ```yaml + --- + name: + description: + --- + + # Skill Title + + Detailed instructions for the agent... + ``` + +4. **Write effective skill instructions**: + - **Be concrete**: Provide exact CLI commands, API calls, or code patterns the agent should use. + - **Use phases**: Break complex workflows into numbered phases with clear entry/exit criteria. + - **Include routing**: Tell the agent how to handle different user intents within the skill's scope. + - **Add recovery rules**: What to do when things fail. + - **Set response rules**: How terse or verbose the agent should be. + - **Keep it narrow**: One skill, one job. If it's doing two things, split into two skills. + +5. **Publish the skill to the platform**: + + **Option A — Via `deploy configs`** (recommended when working with a configs/ directory): + + Place the skill directory under `configs/skills//` and deploy: + ``` + archastro deploy configs + ``` + This automatically creates the skill with name and description from the SKILL.md frontmatter, and publishes all supporting files as File configs. See the `manage-configs` skill for setting up the configs directory. + + **Option B — Via dedicated commands:** + ``` + archastro create skill -n "" -d "" -s --file ./skills//SKILL.md + ``` + + If there are supporting files, add them: + ``` + archastro create skillfile references/example.md --file ./skills//references/example.md + ``` + +6. **Verify the skill was created**: + ``` + archastro describe skill + archastro describe skillfile SKILL.md + ``` + +7. **Link the skill to an agent**: Skills are linked to agents via the agent's tools configuration. The agent needs a `get_skill` tool or the skill needs to be included in the agent's skill list. If the user has an agent they want to link: + ``` + archastro list agents + ``` + Then update the agent's config to reference the skill. + +### User wants to edit an existing skill + +1. **Inspect the current state**: + ``` + archastro describe skill + archastro describe skillfile SKILL.md + ``` + +2. **Make edits locally**, then update: + ``` + archastro update skillfile SKILL.md --file ./skills//SKILL.md + ``` + + For supporting files: + ``` + archastro update skillfile --file ./local/path + ``` + +3. **Verify the update**: + ``` + archastro describe skillfile SKILL.md + ``` + +### User wants to install a skill into their local coding harness + +Skills can be installed locally for use in Claude Code, Codex, or OpenCode: + +``` +archastro impersonate start +archastro impersonate list skills +archastro impersonate install skill --harness claude +archastro impersonate install skill --harness codex --install-scope project +archastro impersonate install skill --harness opencode +``` + +After installation, the skill appears in the local `.claude/skills/`, `.codex/skills/`, or `.opencode/skills/` directory. + +## Skill Authoring Best Practices + +- **Narrow scope**: Each skill should do one thing well. Split broad skills into composable pieces. +- **Concrete instructions**: Provide exact commands and patterns, not vague guidance. +- **Trigger phrases**: The description field is how agents route to the skill — make trigger phrases specific and varied. +- **Version awareness**: When updating a skill, keep in mind that running agents pick up changes on next invocation. +- **Review before publishing**: Skills are executable instructions — review them like code. +- **Supporting files**: Use `references/` subdirectories for large reference material the skill can load on demand. + +## Recovery Rules + +- If `archastro create skill` fails with a duplicate slug error, the skill already exists — offer to update it instead. +- If the user is unsure about the skill format, show them the SKILL.md template above. +- If the user asks for a "sample skill", generate one from the template with placeholder content tailored to their use case. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Prefer showing the user a concrete SKILL.md draft they can review over abstract guidance. diff --git a/plugins/archastro/skills/build-workflow/SKILL.md b/plugins/archastro/skills/build-workflow/SKILL.md new file mode 100644 index 0000000..5a667c3 --- /dev/null +++ b/plugins/archastro/skills/build-workflow/SKILL.md @@ -0,0 +1,283 @@ +--- +name: build-workflow +description: Use when the user wants to create, edit, or deploy a workflow — a multi-step process with branching, loops, HTTP calls, script execution, approvals, or scheduled routines. Trigger phrases include "build a workflow", "create a workflow", "design a workflow", "add a routine", "schedule a task", "automate this process", "set up a cron job", "workflow nodes". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Workflow Builder + +Create, edit, and deploy workflows — multi-step processes that agents execute via routines. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated. + +## What is a Workflow? + +A workflow is a directed graph of nodes that defines a multi-step process. Use the dedicated top-level workflow resource for authoring: `archastro list workflows`, `describe workflow`, `create workflow`, `update workflow`, `validate workflow`, and `describe workflowdocs`. Workflows are then attached to agent routines for execution. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list agents +``` + +Determine: +- Which agent will run this workflow? +- Is this a new workflow or an update to an existing one? +- What trigger should start it? (schedule, webhook, manual, message event) + +## Routing + +### CLI not installed or too old + +Before any workflow work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. +- If authentication or app selection is missing, instruct the user to run `archastro auth login`. + +### Workflow commands not exposed in the current `archastro` build + +The source tree has dedicated top-level workflow commands, but some `archastro` builds may not expose them yet. Verify first: + +``` +archastro list workflows +archastro describe workflowdocs +``` + +If those commands are unavailable, do not keep insisting on them. Fall back to the config-managed workflow path and explain that the dedicated workflow resource exists in source but is not wired into the current binary. + +### User wants to create a new workflow + +**Phase 1: Gather requirements** + +Understand the workflow before writing any config: +- What triggers it? (cron schedule, webhook, message, manual) +- What are the steps? (in plain language) +- Are there branches or conditions? +- Does it need to call external APIs? +- Does it need to send emails, Slack messages, or other notifications? +- Does it loop over a collection? + +**Discover available events** to understand what can trigger the workflow and what data the trigger provides: +``` +archastro list events +``` + +Once the user picks an event type, show them the payload schema so they know what `$` contains in downstream scripts: +``` +archastro describe event +``` + +This returns the JSON schema and a sample payload. The payload fields are accessible via `$` in scripts (e.g., `$.thread_id`, `$.message.content`). + +**Phase 2: Scaffold the workflow** + +Use the top-level workflow commands, not `describe configsample`/`validate config`, for the normal authoring loop when the current `archastro` build exposes them. + +Create a workflow from a local JSON file: +``` +archastro create workflow --id my-workflow --file ./workflows/my-workflow.json +``` + +Or let the CLI start from its built-in sample if you do not pass `--graph` or `--file`: +``` +archastro create workflow --id my-workflow +``` + +**Phase 3: Author the workflow** + +A workflow is a `WorkflowGraph` JSON config under the hood, but the user-facing authoring path should go through the top-level workflow commands. + +A minimal workflow graph looks more like: +```json +{ + "kind": "WorkflowGraph", + "version": 1, + "name": "My Workflow", + "start_node": "trigger_1", + "nodes": [ + { + "kind": "WorkflowTrigger", + "id": "trigger_1", + "trigger": "workflow.scheduled", + "on_success": "script_1" + }, + { + "kind": "WorkflowScript", + "id": "script_1", + "script": "default-script" + } + ], + "data": [ + { + "kind": "Script", + "id": "default-script", + "script": "true" + } + ] +} +``` + +Use the live workflow docs when the graph shape is unclear: +``` +archastro describe workflowdocs +``` + +If `workflowdocs` is not available in the current binary, say so explicitly and fall back to the config-managed path instead of pretending the command exists. + +### Available node types + +Do not hard-code a node taxonomy in this skill. The supported graph/node model is owned by the workflow implementation and `archastro describe workflowdocs`. + +**Phase 4: Write supporting scripts** + +If the workflow needs script logic, author and validate that script first. Route to the `build-script` skill for detailed script authoring guidance, or get the reference directly: +``` +archastro describe scriptdocs +archastro describe configsample Script +``` + +**Phase 5: Validate** + +Validate the workflow graph through the dedicated workflow command: +``` +archastro validate workflow --file ./workflows/my-workflow.json +``` + +Validate any referenced scripts: +``` +archastro validate script --file ./scripts/my-script.agentscript +``` + +Fix any validation errors before deploying. + +**Phase 6: Deploy** + +Creating or updating the workflow through the top-level workflow commands persists it directly: +``` +archastro create workflow --id my-workflow --file ./workflows/my-workflow.json +archastro update workflow my-workflow --file ./workflows/my-workflow.json +``` + +If the top-level workflow commands are unavailable in the current binary, or if the user is working inside a broader config-managed repo and explicitly wants that flow, route to `manage-configs` instead. Do not claim the dedicated workflow commands are available unless you verified them in the running CLI. + +**Phase 7: Attach to a routine** + +Workflows run via agent routines. Create or update a routine to use the workflow: + +For a **scheduled** routine (cron): +``` +archastro create agentroutine --agent \ + --name "Daily report" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type workflow_graph \ + --config-id +``` + +For a **webhook-triggered** routine: +``` +archastro create agentroutine --agent \ + --name "Inbound webhook handler" \ + --event-type webhook.inbound \ + --handler-type workflow_graph \ + --config-id +``` + +To update an existing routine to use a workflow: +``` +archastro update agentroutine \ + --handler-type workflow_graph \ + --config-id +``` + +**Phase 8: Test and monitor** + +Check routine runs: +``` +archastro list agentroutineruns --routine +``` + +Use `println()` in scripts for debugging output. + +### User wants to edit an existing workflow + +1. **Inspect the current workflow**: + ``` + archastro list workflows + archastro describe workflow + ``` + +2. **Edit locally**, then validate and update: + ``` + archastro validate workflow --file ./workflows/my-workflow.json + archastro update workflow --file ./workflows/my-workflow.json + ``` + + The workflow resource versions on update; the agent picks up the linked workflow config on the next run. + +### User wants to set up a simple scheduled routine (no workflow) + +Not everything needs a full workflow graph. For simple scheduled tasks, a routine can use a script directly. + +**Reference a script resource** (preferred for production): +``` +archastro create script --id daily-check --file ./scripts/daily-check.agentscript +archastro create agentroutine --agent \ + --name "Daily check" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --config-id +``` +Get the config ID from `archastro describe script daily-check --output json` (the `configId` field). + +**Or inline for quick prototyping:** +``` +archastro create agentroutine --agent \ + --name "Daily check" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --script 'println("hello")' +``` + +Or include the routine in the AgentTemplate: +```yaml +routines: + - name: daily-check + event_type: schedule.cron + schedule: "0 9 * * 1-5" + handler_type: script + config_ref: daily-check-script +``` + +**Important**: Scheduled routines need both `schedule` and `event_type: schedule.cron`. Do not put schedules under nested `event_config.schedule`. + +## Workflow Design Best Practices + +- **Start simple**: Begin with a linear flow, add branching only when needed. +- **Name nodes clearly**: Use descriptive IDs (`fetch_orders`, `check_status`) not generic ones (`step1`, `step2`). +- **Handle errors**: Follow the real graph schema from `workflowdocs` and the sample config. Don't assume every HTTP call succeeds. +- **Use scripts for logic**: Keep business logic in Script resources or embedded workflow script data instead of improvising unsupported fields. +- **Test scripts independently**: Use `archastro run script --file ` to test scripts before wiring them into a workflow. +- **Cron syntax**: Standard 5-field cron. Use https://crontab.guru for help. + +## Recovery Rules + +- If workflow validation fails, show the exact error — it usually points to a specific node or field. +- If a routine run fails, check `archastro list agentroutineruns` for the error details. +- If a workflow depends on script logic that does not exist yet, create and validate that script first. +- If the user is unsure about workflow vs. simple routine, ask how many steps the process has. One step = simple routine. Multiple steps with branching = workflow. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- When authoring workflows, show the user a concrete JSON graph draft they can review. +- Prefer showing the full workflow structure over explaining node types abstractly. diff --git a/plugins/archastro/skills/chat/SKILL.md b/plugins/archastro/skills/chat/SKILL.md index 7bd558a..79eeb51 100644 --- a/plugins/archastro/skills/chat/SKILL.md +++ b/plugins/archastro/skills/chat/SKILL.md @@ -10,6 +10,21 @@ Send messages to agents and view their responses. This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated. +## Quick Reference + +| Task | Command | +|------|---------| +| Ask agent a question | `archastro create agentsession --agent --instructions "..." --wait` | +| Create a thread | `archastro create thread --title "..." --owner-type agent --owner-id --json` | +| Create a test user | `archastro create user --system-user --name "..." --json` | +| Add member to thread | `archastro create threadmember --thread --user-id --json` | +| Add agent to thread | `archastro create threadmember --thread --agent-id --json` | +| Send message (wait for reply) | `archastro create threadmessage --thread --user-id -c "..." --wait --json` | +| View conversation | `archastro list threadmessages --thread --full` | +| List agent sessions | `archastro list agentsessions --agent --json` | + +Use `--help` on any command for full options. + ## Always Start with State Every invocation must begin by understanding the current context. Determine: @@ -81,14 +96,7 @@ Use `describe --follow` to stream updates on a session created without `--wait`. ### User wants to send a thread message -1. **Determine the sender ID**: - - **Org mode**: Get the user's ID from `archastro auth status`. - - **Developer mode**: Look up thread members: - ``` - archastro list threadmembers --thread - ``` +1. **Determine the sender ID**: Get the user's ID from `archastro auth status`. 2. **Send the message and wait for the response**: ``` @@ -110,14 +118,39 @@ Always use `--full` — the default table view truncates content. ### User needs a new thread +**Agent-owned thread** (recommended when an agent should participate): + +1. Create the thread owned by the agent: + ``` + archastro create thread --title "..." --owner-type agent --owner-id --json + ``` + +2. Create a test user (if needed) and add them to the thread: + ``` + archastro create user --system-user --name "Test User" --json + archastro create threadmember --thread --user-id --json + ``` + +3. Send a message and wait for the agent to respond: + ``` + archastro create threadmessage --thread --user-id -c "Hello" --wait --json + ``` + +4. View the conversation: + ``` + archastro list threadmessages --thread --full + ``` + +**User-owned thread** (when a user starts the conversation): + 1. Create the thread: ``` - archastro create thread --title "..." --user + archastro create thread --title "..." --user --json ``` -2. Add members: +2. Add the agent: ``` - archastro create threadmember --thread --agent-id + archastro create threadmember --thread --agent-id --json ``` ## Response Rules diff --git a/plugins/archastro/skills/agent_deploy/SKILL.md b/plugins/archastro/skills/deploy-agent/SKILL.md similarity index 88% rename from plugins/archastro/skills/agent_deploy/SKILL.md rename to plugins/archastro/skills/deploy-agent/SKILL.md index 03c7029..af10ba0 100644 --- a/plugins/archastro/skills/agent_deploy/SKILL.md +++ b/plugins/archastro/skills/deploy-agent/SKILL.md @@ -1,5 +1,5 @@ --- -name: agent_deploy +name: deploy-agent description: Use when the user wants to deploy an ArchAstro agent, turn a config-driven agent repo into a running agent, or get an existing agent running in a thread. Trigger phrases include "deploy agent", "deploy this agent", "set up an agent", "launch agent", "ship this agent", "get this agent running". allowed-tools: ["Bash(archastro:*)"] --- @@ -35,13 +35,17 @@ Before any deployment work, verify the CLI: - Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. - If authentication or app selection is missing, instruct the user to run `archastro auth login`. +### Local config directory not initialized + +If the user has config files but no `configs/` directory set up, route to the `manage-configs` skill first. That skill owns local config management. + ### User wants to deploy a new agent Use the config-driven golden path. Do not skip straight to `create agent`. 1. **Deploy configs first**: ``` - archastro configs deploy + archastro deploy configs ``` This pushes Script and AgentTemplate configs to the server. For config-driven agents, this should happen before provisioning the agent itself. @@ -62,10 +66,10 @@ Use the config-driven golden path. Do not skip straight to `create agent`. ### User needs help creating or editing the config files first -Route to the `agent_authoring` skill before deploying. That skill owns: +Route to the `author-agent` skill before deploying. That skill owns: - `AgentTemplate` and Script config creation -- `archastro configs sample` -- `archastro configs script-reference` +- `archastro describe configsample` +- `archastro describe scriptdocs` - routine scheduling shape - env-var scope guidance @@ -100,11 +104,11 @@ Summarize what's deployed and offer to deploy a new one or add an existing one t ## Recovery Rules - If `archastro deploy agent` fails with a validation-style error, inspect the exact CLI output first. Do not immediately fall back to lower-level provisioning commands. -- If the problem appears to be in the config files, route to `agent_authoring`. +- If the problem appears to be in the config files, route to `author-agent`. - If a script-related validation error appears, use: ``` - archastro configs script-reference - archastro configs sample Script + archastro describe scriptdocs + archastro describe configsample Script ``` Do not invent script syntax from memory. - Prefer human-readable `config_ref` names that match deployed config lookup keys. Do not rewrite refs to raw `cfg_...` IDs unless explicitly debugging a broken environment. diff --git a/plugins/archastro/skills/impersonate/SKILL.md b/plugins/archastro/skills/impersonate/SKILL.md index ef7c10b..4eaeb7e 100644 --- a/plugins/archastro/skills/impersonate/SKILL.md +++ b/plugins/archastro/skills/impersonate/SKILL.md @@ -4,15 +4,15 @@ description: Use when the user wants to impersonate an ArchAstro agent, asks abo allowed-tools: ["Bash(archastro:*)"] --- -# ArchAstro Agent Impersonation +# ArchAstro Impersonation -Manage ArchAstro agent impersonation and keep the Codex session aligned with the active identity. +Manage ArchAstro impersonation through the ArchAstro CLI and keep the Codex session aligned with the active identity file. This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated. ## Always Start with State -Every invocation of this skill must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. +Every invocation must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. ``` archastro impersonate status --json @@ -26,8 +26,7 @@ Then route based on the combination of current state and user intent. Before any impersonation work, verify the CLI: -- Read `plugin-compatibility.json` from the plugin root. -- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Read `plugin-compatibility.json` from the plugin root. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. - Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. - If authentication or app selection is missing, instruct the user to run `archastro auth login`. @@ -85,6 +84,20 @@ archastro impersonate stop Drop the impersonated identity from the current session. Confirm that local state was removed. +### Active + user asks about tools + +List the impersonated agent's tools: + +``` +archastro impersonate list tools --json +``` + +To execute a tool directly: + +``` +archastro impersonate run tool --input '' --json +``` + ### Active + user asks about skills List available skills: @@ -125,6 +138,11 @@ When you read the identity file, you must **become that agent** for the rest of After `stop`, fully drop the persona and return to your normal behavior. +## Limitations + +- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. +- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. + ## Session Integration - After `start` or `sync`, always read the identity file and adopt it as described above @@ -132,11 +150,6 @@ After `stop`, fully drop the persona and return to your normal behavior. - When showing status, always include loaded skill invocations so the user knows what commands are available - When skills are available but not installed, proactively mention them -## Limitations - -- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. -- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. - ## Response Rules - Do not inspect or edit credential files directly — use the CLI only. diff --git a/plugins/archastro/skills/install/SKILL.md b/plugins/archastro/skills/install/SKILL.md index 74286e2..1d64724 100644 --- a/plugins/archastro/skills/install/SKILL.md +++ b/plugins/archastro/skills/install/SKILL.md @@ -8,12 +8,12 @@ allowed-tools: ["Bash(archastro:*)", "Bash(brew:*)", "Bash(curl:*)", "Bash(bash: Install or upgrade the public `archastro` binary from Homebrew or GitHub Releases. -## Instructions +## Workflow 1. **Read the compatibility contract first**: - - Use `plugin-compatibility.json`. - - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`. - - Treat that resolved value as the minimum supported CLI version for every check below. + - Use `plugin-compatibility.json` from the plugin root. + - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. + - Treat the resolved value as the minimum supported CLI version for every check below. 2. **Check whether the CLI is already installed**: ``` @@ -21,9 +21,9 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release ``` If this succeeds, record the version. -3. **If the CLI is present and meets the resolved minimum version**, confirm the version and stop unless the user explicitly asked to upgrade. +3. **If the CLI is present and meets the resolved minimum**, confirm the version and stop unless the user explicitly asked to upgrade. -4. **If the CLI is missing or older than the resolved minimum version**, install it using the public distribution path: +4. **If the CLI is missing or older than the resolved minimum**, install it using the public distribution path: - On macOS, if Homebrew is available: ``` brew install ArchAstro/tools/archastro @@ -45,12 +45,12 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release ``` archastro --version ``` - Confirm that the version now meets the resolved minimum version. + Confirm that the version now meets the resolved minimum. -6. **On success**, tell the user the CLI is ready and suggest they run `archastro auth login` to authenticate. +6. **On failure, help troubleshoot the public install path**: + - Missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh`. + - `Permission denied` usually means they need `--install-dir` or a user-writable target directory. + - `command not found: archastro` after install usually means the install directory is not on `PATH`. + - Release download failures usually mean the target release asset has not been published yet. -7. **On failure**, help troubleshoot the public install path: - - missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh` - - `Permission denied` usually means they need `--install-dir` or a user-writable target directory - - `command not found: archastro` after install usually means the install directory is not on `PATH` - - release download failures usually mean the target release asset has not been published yet +7. **On success**, tell the user the CLI is ready and suggest they run `archastro auth login` to authenticate. diff --git a/plugins/archastro/skills/manage-configs/SKILL.md b/plugins/archastro/skills/manage-configs/SKILL.md new file mode 100644 index 0000000..5fcb022 --- /dev/null +++ b/plugins/archastro/skills/manage-configs/SKILL.md @@ -0,0 +1,229 @@ +--- +name: manage-configs +description: Use when the user wants to set up or manage local config files for an ArchAstro project — initialize a configs directory, edit configs locally, sync from the server, or deploy local changes. Trigger phrases include "set up configs", "init configs", "configs directory", "sync configs", "deploy configs", "edit config locally", "local config management". +allowed-tools: ["Bash(archastro:*)"] +--- + +# ArchAstro Local Config Management + +Set up and manage a local `configs/` directory for editing agent configs as files, syncing with the server, and deploying changes. + +This skill assumes the ArchAstro CLI is already installed and authenticated. Install or upgrade `archastro` if missing, and run `archastro auth login` if not authenticated. + +## What is Local Config Management? + +Instead of creating and editing configs one-by-one through CLI CRUD commands, you can manage them as local files in a `configs/` directory. This enables: +- **Edit configs in your editor** with syntax highlighting and version control +- **Batch deploy** all changes in dependency order +- **Sync** server configs down to local files +- **Browser editor** for visual editing of individual configs + +The CLI tracks the mapping between local files and server configs in a manifest file. + +## Always Start with State + +Every invocation must begin by understanding the current project state: + +``` +archastro auth status +ls configs/ 2>/dev/null || echo "No configs directory" +``` + +Determine: +- Does a `configs/` directory already exist? +- Is the user starting a new project or working with an existing one? +- Do they want to pull configs from the server or push local changes? + +## Routing + +### CLI not installed or too old + +Before any config work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, instruct the user to install or upgrade `archastro`. +- If authentication or app selection is missing, instruct the user to run `archastro auth login`. + +### User wants to set up a configs directory for the first time + +1. **Initialize the config directory**: + ``` + archastro init --enable-configs + ``` + This enables local config management and creates the configured `configs/` directory if needed. It does not automatically sync remote configs; use `archastro sync configs` next when you want local files. + +2. **Explain the layout**: After init, the directory looks like: + ``` + configs/ + ├── .archastro-manifest.json # Maps local files to server configs (do not edit manually) + ├── agents/ # AgentTemplate configs + ├── skills/ # Skill bundles + ├── scripts/ # Script configs + ├── workflows/ # Workflow configs + └── ... # Other config kinds + ``` + + Managed virtual paths also follow these prefixes on the server: `skills/`, `scripts/`, and `workflows/`. + +3. **Offer next steps**: Ask if the user wants to create a new config (`archastro describe configsample `) or sync existing configs from the server. + +### User wants to pull configs from the server + +Sync server configs to local files: +``` +archastro sync configs +``` + +This downloads all configs for the current app — including skills, scripts, and workflows — and writes them as local files in the correct directories. The manifest tracks the file-to-config mapping. + +After syncing, the directory structure reflects server state: +``` +configs/ +├── agents/ # AgentTemplate configs (.yaml) +├── skills/my-skill/ # Skill bundles (SKILL.md + supporting files) +├── scripts/ # Script configs (.agentscript) +├── workflows/ # Workflow configs (.json) +└── ... # Other config kinds +``` + +You can then edit any file locally and run `archastro deploy configs` to push changes back. + +### User wants to create a new config locally + +For **scripts**, **skills**, and **workflows**, prefer the dedicated commands or create files directly in the correct directory: + +- **Script**: Write a `.agentscript` file in `configs/scripts/`: + ``` + configs/scripts/my-script.agentscript + ``` +- **Skill**: Create a `SKILL.md` (with frontmatter) in `configs/skills//`: + ``` + configs/skills/my-skill/SKILL.md + configs/skills/my-skill/prompts/greeting.liquid # optional supporting files + ``` +- **Workflow**: Write a `.json` file in `configs/workflows/`: + ``` + configs/workflows/my-workflow.json + ``` + +For **other config kinds** (AgentTemplate, Persona, etc.), get a sample: +``` +archastro list configkinds +archastro describe configsample --to-file ./configs//.yaml +``` + +You can also use the browser editor: +``` +archastro edit config ./configs//.yaml +``` + +### User wants to validate local configs + +Validate a specific config file: +``` +archastro validate config -k -f ./configs//.yaml +``` + +For scripts specifically, use the dedicated validator: +``` +archastro validate script --file ./configs/scripts/my-script.agentscript +``` + +### User wants to deploy local changes + +Push all local config changes to the server: +``` +archastro deploy configs +``` + +This: +- Compares local files against the manifest +- Uploads new and changed configs in dependency order +- Updates the manifest with new server IDs + +#### Managed directory conventions + +`deploy configs` enforces conventions for three managed directories: + +| Directory | Convention | +|-----------|-----------| +| `skills//` | All files become `File` kind. `SKILL.md` is the root — name and description are extracted from its YAML frontmatter. Other files (`.liquid`, `.yaml`, `.js`, etc.) become supporting skill files. | +| `scripts/` | Only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed. Other file types are rejected. | +| `workflows/` | Only `.json` files and `.yaml` with a `Workflow*` kind are allowed. Other file types are rejected. | + +Files outside these directories use standard kind inference from file extension or YAML content. + +**Important**: `deploy configs` syncs config files only. It does not create agents. To provision an agent from a template, use `archastro deploy agent ` separately. + +### User wants to move or rename a config file + +If a local config file is moved or renamed: +``` +archastro update configpath +``` + +This updates the manifest mapping without affecting the server config. + +### User has manifest issues + +If the manifest gets out of sync: +``` +archastro validate configmanifest +``` + +This re-normalizes the manifest and resolves any inconsistencies. + +## Typical Workflows + +### New project from scratch +``` +archastro init --enable-configs +archastro describe configsample AgentTemplate --to-file ./configs/agents/my-agent.yaml +# Edit the file... +archastro validate config -k AgentTemplate -f ./configs/agents/my-agent.yaml +archastro deploy configs +archastro deploy agent ./configs/agents/my-agent.yaml +``` + +### Create a skill via local files +``` +archastro init --enable-configs +mkdir -p configs/skills/my-skill +# Write SKILL.md with frontmatter (name, description) +# Add supporting files (prompts, references, etc.) +archastro deploy configs +# Skill is now visible via: archastro list skills +``` + +### Create a script via local files +``` +archastro init --enable-configs +# Write script source directly +echo 'println("hello")' > configs/scripts/my-script.agentscript +archastro deploy configs +# Script is now visible via: archastro describe script my-script +``` + +### Pull existing project and make changes +``` +archastro init --enable-configs +archastro sync configs +# Edit files locally... +archastro deploy configs +``` + +### Quick edit via browser +``` +archastro edit config ./configs/agents/my-agent.yaml +# Opens in browser with live validation +# Changes are saved to the server and synced back to the local file +``` + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not manually edit `.archastro-manifest.json` — use CLI commands. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Always recommend `deploy configs` over individual `create config` calls when working with local files. diff --git a/sources/auth.md b/sources/auth.md index 836d081..199548e 100644 --- a/sources/auth.md +++ b/sources/auth.md @@ -7,80 +7,55 @@ skill: description: Use when the user wants to authenticate with or log in to the ArchAstro developer platform, or when the CLI reports an authentication error. Trigger phrases include "authenticate archastro", "archastro auth login", "log in to archastro", "archastro not authenticated", "archastro auth status", "sign in to archastro". allowed-tools: ["Bash(archastro:*)"] command: - description: Authenticate with the ArchAstro developer platform (org mode by default) + description: Authenticate with the ArchAstro developer platform allowed-tools: ["Bash(archastro:*)"] --- - # ArchAstro CLI Authentication -Authenticate the user with the ArchAstro developer platform via browser-based login. Defaults to org mode (Agent Network). +Authenticate the user with the ArchAstro developer platform via browser-based login. -## Instructions +## Workflow 1. **Read the compatibility contract first**: - - Use `plugin-compatibility.json`. - - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`. - - Treat that resolved value as the minimum supported CLI version for every check below. + - Use `plugin-compatibility.json` from the plugin root. + - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. + - Treat the resolved value as the minimum supported CLI version for every check below. 2. **Check the installed CLI version first**: ``` archastro --version ``` - If the command is missing, or the version is older than the resolved minimum version, {{#CLAUDE_COMMAND}}tell the user to run `/archastro:install`{{/CLAUDE_COMMAND}}{{#SKILL}}instruct the user to install or upgrade `archastro`{{/SKILL}}. + If the command is missing, or the version is older than the resolved minimum, {{#CLAUDE_COMMAND}}tell the user to run `/archastro:install`{{/CLAUDE_COMMAND}}{{#SKILL}}instruct the user to install or upgrade `archastro`{{/SKILL}}. -3. **Check if already authenticated**: +3. **Check whether the user is already authenticated**: ``` archastro auth status ``` - If the user is already authenticated, show their status and ask if they want to re-authenticate. - -4. **Determine the auth mode**: - - The default is **org mode** (Agent Network). Only use developer mode if the user explicitly asks to log in as a developer or app builder. - - - **Org mode** (default): For users within an organization. No app slug needed — defaults to Agent Network. - - **Developer mode**: For building and managing apps on the platform. Requires the `--dev` flag. + If the user is already authenticated, show their status and ask whether they want to re-authenticate. -5. **Reset any stale settings overrides** that may point to localhost: +4. **Reset any stale settings overrides that may point to localhost**: ``` archastro settings reset ``` This ensures the CLI uses the production URLs. -6. **Start the login flow**: - - **Org mode (default):** +5. **Start the login flow**: ``` archastro auth login ``` + Keep the session responsive while the browser-based auth flow runs. - **Org mode for a specific app** (if the user specifies a different app slug): - ``` - archastro auth login --app - ``` +6. **Tell the user the auth flow is running** and they should complete login in their browser. The CLI opens `https://developers.archastro.ai` and prints a URL if the browser does not open automatically. - **Developer mode** (only if explicitly requested): - ``` - archastro auth login --dev - ``` - - Use `run_in_background: true` so the browser-based auth flow runs while you remain responsive. - - The CLI will open the user's browser to https://developers.archastro.ai for authentication and print a URL in case the browser doesn't open automatically. - -7. **Tell the user** the auth flow is running and they should complete login in their browser. Let them know you're available to keep working on other things while waiting. - -8. **When the user says they've logged in** (or you're ready to check), wait for the command to finish and then re-check status. - -9. **On success**, confirm authentication succeeded and show their status: +7. **When the user says they have logged in**, or when it is time to re-check, wait for the login command to finish and then run: ``` archastro auth status ``` - For org mode, verify the output shows `Auth mode: org` and the correct app/org name. -10. **On failure**, show the error and suggest: - - Check their internet connection - - Try `archastro settings reset` if URLs look wrong - - `no-access` error means the user doesn't have org access — verify with an org admin for an invite - - Try again with `archastro auth login` +8. **On success**, confirm authentication succeeded and show the user their status. + +9. **On failure**, show the error and suggest: + - Check their internet connection. + - Try `archastro settings reset` if URLs look wrong. + - Try again with `archastro auth login`. diff --git a/sources/agent_authoring.md b/sources/author-agent.md similarity index 71% rename from sources/agent_authoring.md rename to sources/author-agent.md index ed663b3..8d51703 100644 --- a/sources/agent_authoring.md +++ b/sources/author-agent.md @@ -1,11 +1,11 @@ --- targets: - claude-skill: agent_authoring - codex-skill: agent_authoring + claude-skill: author-agent + codex-skill: author-agent skill: - name: agent_authoring + name: author-agent description: Use when the user wants to create or edit an ArchAstro agent's config files before deployment, including AgentTemplate files, Script configs, custom tools, routines, and environment setup. Trigger phrases include "build this agent", "write the template", "create the scripts", "set up the routines", "author this agent config". - allowed-tools: ['Bash(archastro:*)'] + allowed-tools: ["Bash(archastro:*)"] --- @@ -36,19 +36,23 @@ Before any authoring work, verify the CLI: - Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. - If authentication or app selection is missing, {{AUTH_ROUTE}}. +### Local config directory not initialized + +If the user doesn't have a `configs/` directory set up yet, route to the `manage-configs` skill first. That skill owns `archastro init --enable-configs`, local file layout, and the sync/deploy workflow. + ### User wants to author or modify agent configs 1. **Start from CLI-backed templates, not memory**: - For new config objects, use: ``` - archastro configs sample + archastro describe configsample ``` - For Script configs, always use: ``` - archastro configs script-reference - archastro configs sample Script + archastro describe scriptdocs + archastro describe configsample Script ``` - The script reference is the live source of truth. Do not invent or paraphrase the language from memory. + The script docs are the live source of truth. Do not invent or paraphrase the language from memory. 2. **Use the standard config-driven model**: - Script logic lives in `kind: Script` configs. @@ -61,14 +65,14 @@ Before any authoring work, verify the CLI: 3. **Validate early**: ``` - archastro configs validate + archastro validate config -k -f ``` Run validation before deploy whenever the user changes Script or template files. 4. **Deploy through the normal flow after authoring**: - If the agent has Script configs or other supporting files, sync them first: ``` - archastro configs deploy + archastro deploy configs ``` This pushes local config files (Scripts, templates) but does not create agents. Skip this step if the agent only has a single AgentTemplate file — `deploy agent` handles its own config upload. @@ -77,15 +81,16 @@ Before any authoring work, verify the CLI: archastro deploy agent ``` This uploads the template config and creates the agent with its routines, tools, and installations. - - **Important:** `configs deploy` and `deploy agent` are different commands. - Use `configs deploy` to sync a directory of config files; use `deploy agent` to create an agent from a template. + - **Important:** `deploy configs` and `deploy agent` are different commands. + Use `deploy configs` to sync a directory of config files; use `deploy agent` to create an agent from a template. ## Authoring Rules ### Script configs +- **Load the `build-script` skill for detailed script authoring guidance**, including syntax examples, common mistakes, and the validation/test/deploy workflow. - Treat the script language as a functional expression language, not a general-purpose imperative language. -- Use `archastro configs script-reference` for exact syntax and available namespaces. +- Use `archastro describe scriptdocs` for exact syntax and available namespaces. - If a script fails validation, prefer rewriting toward the sample/reference instead of trial-and-error improvisation. ### Routine configs inside templates @@ -94,6 +99,12 @@ Before any authoring work, verify the CLI: - `schedule: ""` - `event_type: schedule.cron` - Do not put schedules under nested `event_config.schedule`. +- To discover valid event types and their payload schemas: + ``` + archastro list events + archastro describe event + ``` + The payload schema from `describe event` shows what `$` contains in the routine's script handler. ### Config references @@ -107,16 +118,14 @@ Before any authoring work, verify the CLI: ## Recovery Rules -- If the user asks for a brand-new Script and the language shape is unclear, run `archastro configs script-reference` before drafting. +- If the user asks for a brand-new Script and the language shape is unclear, run `archastro describe scriptdocs` before drafting. - If validation fails, surface the exact failing field or syntax problem. Do not immediately switch to lower-level provisioning commands. -- If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to `agent_deploy`. +- If the user asks to "just create the agent" while configs are still incomplete, finish authoring and validation first, then route to `deploy-agent`. ## Command Conventions -- Config management uses two patterns: - - **Noun-first** for workflow commands: `archastro configs deploy`, `archastro configs sync`, `archastro configs validate` - - **Verb-first** for CRUD: `archastro list configs`, `archastro describe config `, `archastro create config` -- Do not use `archastro configs list` or `archastro configs describe` — those are not valid. Use the verb-first form. +- All config commands are **verb-first**: `archastro list configs`, `archastro create config`, `archastro deploy configs`, `archastro sync configs`, `archastro validate config`, etc. +- There is no `archastro configs` namespace. Do not use `archastro configs ` — always put the verb first. ## Response Rules diff --git a/sources/build-script.md b/sources/build-script.md new file mode 100644 index 0000000..0c4242a --- /dev/null +++ b/sources/build-script.md @@ -0,0 +1,304 @@ +--- +targets: + claude-skill: build-script + codex-skill: build-script +skill: + name: build-script + description: Use when the user wants to write, test, or deploy an ArchAstro script — custom logic for agent tools, workflow nodes, and routines. Trigger phrases include "build a script", "write a script", "create a script", "test a script", "script syntax", "script reference", "script language". + allowed-tools: ["Bash(archastro:*)"] +--- + + +# ArchAstro Script Builder + +Write, test, and deploy scripts — custom logic that powers agent tools, workflow nodes, and routines. + +This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}} + +## What is a Script? + +Scripts are expression-oriented custom logic written in the ArchAstro script language. They can be used as: +- **Custom tool handlers**: Agent calls a tool → script runs → result returned to agent +- **Workflow graph script steps**: Script logic used inside a workflow graph +- **Routine handlers**: A scheduled routine runs the script directly + +Scripts are first-class resources with their own CRUD, validation, and execution commands. +Use the dedicated top-level script resource for the normal authoring loop: `archastro list scripts`, `describe script`, `create script`, `update script`, `validate script`, `run script`, and `describe scriptdocs`. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list scripts +``` + +Determine: +- Is the user creating a new script or editing an existing one? +- What will this script be used for? (tool, workflow node, routine) +- What external APIs or data does it need to access? + +## Routing + +### CLI not installed or too old + +Before any script work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. +- If authentication or app selection is missing, {{AUTH_ROUTE}}. + +### User wants to write a new script + +**Phase 1: Get the language reference** + +Always start by fetching the live reference — do not write scripts from memory: +``` +archastro describe scriptdocs +``` + +Use the top-level script commands, not `describe configsample`/`validate config`, for the normal authoring loop. + +Create a script from a local source file: +``` +archastro create script --id my-script --file ./scripts/my-script.agentscript +``` + +Or let the CLI start from its built-in sample if you do not pass `--source` or `--file`: +``` +archastro create script --id my-script +``` + +**Phase 2: Understand the requirements** + +Ask the user: +- What should the script do? +- What inputs will it receive? (accessible via `$` JSONPath) +- Does it need environment variables? (accessible via `env.KEY`) +- Does it need to make HTTP calls? + +If the script will handle a routine event, discover what `$` contains by checking the event's payload schema: +``` +archastro list events +archastro describe event +``` + +`describe event` returns the JSON schema and a sample payload. Every field in the payload is accessible via `$` in the script (e.g., `$.thread_id`, `$.message.content`). Always check the event schema before writing scripts that consume routine payloads — do not guess the shape from memory. + +**Phase 3: Author the script** + +Key language concepts: + +- **Input**: Access via `$` (JSONPath). E.g., `$.order_id`, `$.user.email` +- **Environment**: Access via `env.KEY`. E.g., `env.API_TOKEN` +- **Imports**: `import("requests")`, `import("array")`, `import("string")`, etc. +- **Error handling**: `unwrap(result)` or `unwrap(result, default_value)` +- **No loops**: Use `array.map`, `array.filter`, `array.reduce` +- **Expression-oriented**: The last expression in the script is the return value +- **Debugging**: Use `println()` to inspect values + +Example — HTTP lookup script: +``` +let http = import("requests") +let arr = import("array") + +let response = http.get(env.API_URL + "/orders/" + $.order_id, { + headers: { "Authorization": "Bearer " + env.API_TOKEN } +}) +let body = unwrap(response) + +{ + order_id: $.order_id, + status: body.status, + items: arr.map(body.line_items, fn(item) { + { name: item.name, qty: item.quantity } + }) +} +``` + +Available namespaces: +- `requests` — HTTP client (`get`, `post`, `put`, `patch`, `delete`) +- `array` — Collection operations (`map`, `filter`, `reduce`, `find`, `sort`, `flat_map`) +- `string` — String operations (`split`, `join`, `trim`, `lowercase`, `uppercase`, `contains`) +- `map` — Object operations (`keys`, `values`, `merge`, `get`) +- `datetime` — Date/time operations (`now`, `format`, `parse`, `add`) +- `math` — Math operations (`round`, `floor`, `ceil`, `abs`) +- `result` — Result type operations (`ok`, `err`, `is_ok`, `is_err`) +- `email` — Email sending +- `jwt` — JWT token operations +- `slack` — Slack API operations + +**Phase 4: Validate** + +Validate the script syntax: +``` +archastro validate script --file ./scripts/my-script.agentscript +``` + +Or validate as a config: +``` +archastro validate config -k Script -f ./configs/scripts/my-script.yaml +``` + +Fix any validation errors before proceeding. + +**Phase 5: Test** + +Run the script locally with test input: +``` +archastro run script --file ./scripts/my-script.agentscript --input '{"order_id": "ORD-123"}' +``` + +For scripts that need env vars, ensure they are set on the platform: +``` +archastro list orgenvvars +archastro create orgenvvar -k API_TOKEN -v "sk-..." +``` + +**Phase 6: Deploy** + +Scripts can be deployed two ways: + +**As a standalone script resource:** +``` +archastro create script --id order-lookup -n "Order Lookup" --file ./scripts/my-script.agentscript +``` + +Update an existing script resource: +``` +archastro update script order-lookup --file ./scripts/my-script.agentscript +``` + +**Via `deploy configs`** (for config-managed repos): + +Place `.agentscript` files in `configs/scripts/` and deploy: +``` +archastro deploy configs +``` + +The `scripts/` directory enforces that only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed — other file types are rejected. See the `manage-configs` skill for setting up the configs directory. + +**Phase 7: Wire it up** + +Connect the script to where it will be used: + +**As a custom tool on an agent:** + +The API requires `--config-id` pointing at the script's config ID even for script-handler tools: +``` +archastro create agenttool --agent \ + --kind custom \ + --name "lookup_order" \ + --description "Look up an order by ID" \ + --handler-type script \ + --config-id \ + --instruction "Use this tool when the user asks to look up an order." \ + --parameters '{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}' +``` + +Get the script's config ID from `archastro describe script --output json` (the `configId` field). + +**In a workflow graph:** Follow the real `WorkflowGraph` shape from `archastro describe workflowdocs` and the `build-workflow` skill. + +**As a routine handler** (reference by config ID — preferred for production): +``` +archastro create agentroutine --agent \ + --name "My scheduled script" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --config-id +``` + +Get the script's config ID from `archastro describe script --output json` (the `configId` field). + +Or inline for quick prototyping: +``` +archastro create agentroutine --agent \ + --name "Quick test" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --script 'println("hello")' +``` + +Prefer `--config-id` for production — it keeps the routine linked to a versioned script resource that can be updated independently. + +### User wants to edit an existing script + +1. **Inspect the current script**: + ``` + archastro list scripts + archastro describe script + ``` + +2. **Edit locally**, validate, and update: + ``` + archastro validate script --file ./scripts/my-script.agentscript + archastro update script --file ./scripts/my-script.agentscript + ``` + +## Common Mistakes + +**Do not write JSON — use script object syntax:** +``` +// WRONG — JSON syntax causes "unexpected token :" errors +{ "status": "ok", "count": 5 } + +// CORRECT — script uses unquoted keys +{ status: "ok", count: 5 } +``` + +**Do not use `return` — the last expression is the return value:** +``` +// WRONG +return { status: "ok" } + +// CORRECT +{ status: "ok" } +``` + +**Always import namespaces before using them:** +``` +// WRONG — "Unknown identifier" error +let now = datetime.now() + +// CORRECT +let dt = import("datetime") +let now = dt.now() +``` + +**No imperative loops — use array functions:** +``` +// WRONG — for/while don't exist +for item in items { ... } + +// CORRECT +let arr = import("array") +arr.map(items, fn(item) { ... }) +``` + +## Script Authoring Rules + +- **Always fetch `archastro describe scriptdocs` before writing scripts.** Do not invent syntax from memory. +- Prefer the dedicated top-level script commands over the generic `configs` resource unless the user explicitly wants config-managed files. +- Treat the language as functional and expression-oriented, not imperative. +- The last expression is the return value — there is no `return` keyword. +- Use `unwrap()` for error handling — never assume HTTP calls succeed. +- Use `println()` liberally while debugging, remove before deploying. +- If validation fails, rewrite toward the sample/reference instead of trial-and-error. + +## Recovery Rules + +- If a script fails validation, show the exact error. Common issues: missing imports, wrong function signatures, trying to use imperative loops. +- If `archastro run script` fails at runtime, check: are env vars set? Is the input JSON valid? Is the API reachable? +- If the user is unsure about syntax, always fall back to `archastro describe scriptdocs`. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Show the user a concrete script draft they can review, not abstract syntax explanations. diff --git a/sources/build-skill.md b/sources/build-skill.md new file mode 100644 index 0000000..4be3317 --- /dev/null +++ b/sources/build-skill.md @@ -0,0 +1,180 @@ +--- +targets: + claude-skill: build-skill + codex-skill: build-skill +skill: + name: build-skill + description: Use when the user wants to create, edit, or publish an ArchAstro skill — a reusable package of instructions and supporting files that agents can use. Trigger phrases include "build a skill", "create a skill", "write a skill", "author a skill", "new skill", "skill template", "SKILL.md". + allowed-tools: ["Bash(archastro:*)"] +--- + + +# ArchAstro Skill Builder + +Create, edit, and publish skills — reusable instruction packages that agents invoke at runtime. + +This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}} + +## What is a Skill? + +A skill is a file-backed bundle anchored by a `SKILL.md` root file with optional supporting files. Skills use the same managed virtual-path model as scripts and workflows: skills live under `skills//...`, scripts under `scripts/...`, and workflows under `workflows/...`. Agents invoke skills at runtime via the `get_skill` tool to load instructions on demand. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list skills +``` + +Determine whether the user wants to: +- create a brand-new skill, +- edit an existing skill, +- or inspect a skill before modifying it. + +## Routing + +### CLI not installed or too old + +Before any skill work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. +- If authentication or app selection is missing, {{AUTH_ROUTE}}. + +### User wants to create a new skill + +Walk through the authoring flow step by step. + +1. **Gather requirements**: + - What should the skill do? (purpose and scope) + - What trigger phrases should activate it? (for the description field) + - Does it need supporting files (templates, schemas, reference docs)? + - Which agent(s) will use it? + +2. **Choose a slug**: Short, lowercase, hyphen-separated identifier (e.g., `order-lookup`, `weekly-report`). This becomes the skill's permanent key. + +3. **Author the SKILL.md file locally**: + + Create a directory structure: + ``` + skills// + ├── SKILL.md # Root file (required) + └── references/ # Optional supporting files + └── example.md + ``` + + The SKILL.md must have YAML frontmatter: + ```yaml + --- + name: + description: + --- + + # Skill Title + + Detailed instructions for the agent... + ``` + +4. **Write effective skill instructions**: + - **Be concrete**: Provide exact CLI commands, API calls, or code patterns the agent should use. + - **Use phases**: Break complex workflows into numbered phases with clear entry/exit criteria. + - **Include routing**: Tell the agent how to handle different user intents within the skill's scope. + - **Add recovery rules**: What to do when things fail. + - **Set response rules**: How terse or verbose the agent should be. + - **Keep it narrow**: One skill, one job. If it's doing two things, split into two skills. + +5. **Publish the skill to the platform**: + + **Option A — Via `deploy configs`** (recommended when working with a configs/ directory): + + Place the skill directory under `configs/skills//` and deploy: + ``` + archastro deploy configs + ``` + This automatically creates the skill with name and description from the SKILL.md frontmatter, and publishes all supporting files as File configs. See the `manage-configs` skill for setting up the configs directory. + + **Option B — Via dedicated commands:** + ``` + archastro create skill -n "" -d "" -s --file ./skills//SKILL.md + ``` + + If there are supporting files, add them: + ``` + archastro create skillfile references/example.md --file ./skills//references/example.md + ``` + +6. **Verify the skill was created**: + ``` + archastro describe skill + archastro describe skillfile SKILL.md + ``` + +7. **Link the skill to an agent**: Skills are linked to agents via the agent's tools configuration. The agent needs a `get_skill` tool or the skill needs to be included in the agent's skill list. If the user has an agent they want to link: + ``` + archastro list agents + ``` + Then update the agent's config to reference the skill. + +### User wants to edit an existing skill + +1. **Inspect the current state**: + ``` + archastro describe skill + archastro describe skillfile SKILL.md + ``` + +2. **Make edits locally**, then update: + ``` + archastro update skillfile SKILL.md --file ./skills//SKILL.md + ``` + + For supporting files: + ``` + archastro update skillfile --file ./local/path + ``` + +3. **Verify the update**: + ``` + archastro describe skillfile SKILL.md + ``` + +### User wants to install a skill into their local coding harness + +Skills can be installed locally for use in Claude Code, Codex, or OpenCode: + +``` +archastro impersonate start +archastro impersonate list skills +archastro impersonate install skill --harness claude +archastro impersonate install skill --harness codex --install-scope project +archastro impersonate install skill --harness opencode +``` + +After installation, the skill appears in the local `.claude/skills/`, `.codex/skills/`, or `.opencode/skills/` directory. + +## Skill Authoring Best Practices + +- **Narrow scope**: Each skill should do one thing well. Split broad skills into composable pieces. +- **Concrete instructions**: Provide exact commands and patterns, not vague guidance. +- **Trigger phrases**: The description field is how agents route to the skill — make trigger phrases specific and varied. +- **Version awareness**: When updating a skill, keep in mind that running agents pick up changes on next invocation. +- **Review before publishing**: Skills are executable instructions — review them like code. +- **Supporting files**: Use `references/` subdirectories for large reference material the skill can load on demand. + +## Recovery Rules + +- If `archastro create skill` fails with a duplicate slug error, the skill already exists — offer to update it instead. +- If the user is unsure about the skill format, show them the SKILL.md template above. +- If the user asks for a "sample skill", generate one from the template with placeholder content tailored to their use case. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Prefer showing the user a concrete SKILL.md draft they can review over abstract guidance. diff --git a/sources/build-workflow.md b/sources/build-workflow.md new file mode 100644 index 0000000..56fb72a --- /dev/null +++ b/sources/build-workflow.md @@ -0,0 +1,288 @@ +--- +targets: + claude-skill: build-workflow + codex-skill: build-workflow +skill: + name: build-workflow + description: Use when the user wants to create, edit, or deploy a workflow — a multi-step process with branching, loops, HTTP calls, script execution, approvals, or scheduled routines. Trigger phrases include "build a workflow", "create a workflow", "design a workflow", "add a routine", "schedule a task", "automate this process", "set up a cron job", "workflow nodes". + allowed-tools: ["Bash(archastro:*)"] +--- + + +# ArchAstro Workflow Builder + +Create, edit, and deploy workflows — multi-step processes that agents execute via routines. + +This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}} + +## What is a Workflow? + +A workflow is a directed graph of nodes that defines a multi-step process. Use the dedicated top-level workflow resource for authoring: `archastro list workflows`, `describe workflow`, `create workflow`, `update workflow`, `validate workflow`, and `describe workflowdocs`. Workflows are then attached to agent routines for execution. + +## Always Start with State + +Every invocation must begin by understanding the current context: + +``` +archastro auth status +archastro list agents +``` + +Determine: +- Which agent will run this workflow? +- Is this a new workflow or an update to an existing one? +- What trigger should start it? (schedule, webhook, manual, message event) + +## Routing + +### CLI not installed or too old + +Before any workflow work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. +- If authentication or app selection is missing, {{AUTH_ROUTE}}. + +### Workflow commands not exposed in the current `archastro` build + +The source tree has dedicated top-level workflow commands, but some `archastro` builds may not expose them yet. Verify first: + +``` +archastro list workflows +archastro describe workflowdocs +``` + +If those commands are unavailable, do not keep insisting on them. Fall back to the config-managed workflow path and explain that the dedicated workflow resource exists in source but is not wired into the current binary. + +### User wants to create a new workflow + +**Phase 1: Gather requirements** + +Understand the workflow before writing any config: +- What triggers it? (cron schedule, webhook, message, manual) +- What are the steps? (in plain language) +- Are there branches or conditions? +- Does it need to call external APIs? +- Does it need to send emails, Slack messages, or other notifications? +- Does it loop over a collection? + +**Discover available events** to understand what can trigger the workflow and what data the trigger provides: +``` +archastro list events +``` + +Once the user picks an event type, show them the payload schema so they know what `$` contains in downstream scripts: +``` +archastro describe event +``` + +This returns the JSON schema and a sample payload. The payload fields are accessible via `$` in scripts (e.g., `$.thread_id`, `$.message.content`). + +**Phase 2: Scaffold the workflow** + +Use the top-level workflow commands, not `describe configsample`/`validate config`, for the normal authoring loop when the current `archastro` build exposes them. + +Create a workflow from a local JSON file: +``` +archastro create workflow --id my-workflow --file ./workflows/my-workflow.json +``` + +Or let the CLI start from its built-in sample if you do not pass `--graph` or `--file`: +``` +archastro create workflow --id my-workflow +``` + +**Phase 3: Author the workflow** + +A workflow is a `WorkflowGraph` JSON config under the hood, but the user-facing authoring path should go through the top-level workflow commands. + +A minimal workflow graph looks more like: +```json +{ + "kind": "WorkflowGraph", + "version": 1, + "name": "My Workflow", + "start_node": "trigger_1", + "nodes": [ + { + "kind": "WorkflowTrigger", + "id": "trigger_1", + "trigger": "workflow.scheduled", + "on_success": "script_1" + }, + { + "kind": "WorkflowScript", + "id": "script_1", + "script": "default-script" + } + ], + "data": [ + { + "kind": "Script", + "id": "default-script", + "script": "true" + } + ] +} +``` + +Use the live workflow docs when the graph shape is unclear: +``` +archastro describe workflowdocs +``` + +If `workflowdocs` is not available in the current binary, say so explicitly and fall back to the config-managed path instead of pretending the command exists. + +### Available node types + +Do not hard-code a node taxonomy in this skill. The supported graph/node model is owned by the workflow implementation and `archastro describe workflowdocs`. + +**Phase 4: Write supporting scripts** + +If the workflow needs script logic, author and validate that script first. Route to the `build-script` skill for detailed script authoring guidance, or get the reference directly: +``` +archastro describe scriptdocs +archastro describe configsample Script +``` + +**Phase 5: Validate** + +Validate the workflow graph through the dedicated workflow command: +``` +archastro validate workflow --file ./workflows/my-workflow.json +``` + +Validate any referenced scripts: +``` +archastro validate script --file ./scripts/my-script.agentscript +``` + +Fix any validation errors before deploying. + +**Phase 6: Deploy** + +Creating or updating the workflow through the top-level workflow commands persists it directly: +``` +archastro create workflow --id my-workflow --file ./workflows/my-workflow.json +archastro update workflow my-workflow --file ./workflows/my-workflow.json +``` + +If the top-level workflow commands are unavailable in the current binary, or if the user is working inside a broader config-managed repo and explicitly wants that flow, route to `manage-configs` instead. Do not claim the dedicated workflow commands are available unless you verified them in the running CLI. + +**Phase 7: Attach to a routine** + +Workflows run via agent routines. Create or update a routine to use the workflow: + +For a **scheduled** routine (cron): +``` +archastro create agentroutine --agent \ + --name "Daily report" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type workflow_graph \ + --config-id +``` + +For a **webhook-triggered** routine: +``` +archastro create agentroutine --agent \ + --name "Inbound webhook handler" \ + --event-type webhook.inbound \ + --handler-type workflow_graph \ + --config-id +``` + +To update an existing routine to use a workflow: +``` +archastro update agentroutine \ + --handler-type workflow_graph \ + --config-id +``` + +**Phase 8: Test and monitor** + +Check routine runs: +``` +archastro list agentroutineruns --routine +``` + +Use `println()` in scripts for debugging output. + +### User wants to edit an existing workflow + +1. **Inspect the current workflow**: + ``` + archastro list workflows + archastro describe workflow + ``` + +2. **Edit locally**, then validate and update: + ``` + archastro validate workflow --file ./workflows/my-workflow.json + archastro update workflow --file ./workflows/my-workflow.json + ``` + + The workflow resource versions on update; the agent picks up the linked workflow config on the next run. + +### User wants to set up a simple scheduled routine (no workflow) + +Not everything needs a full workflow graph. For simple scheduled tasks, a routine can use a script directly. + +**Reference a script resource** (preferred for production): +``` +archastro create script --id daily-check --file ./scripts/daily-check.agentscript +archastro create agentroutine --agent \ + --name "Daily check" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --config-id +``` +Get the config ID from `archastro describe script daily-check --output json` (the `configId` field). + +**Or inline for quick prototyping:** +``` +archastro create agentroutine --agent \ + --name "Daily check" \ + --event-type schedule.cron \ + --schedule "0 9 * * 1-5" \ + --handler-type script \ + --script 'println("hello")' +``` + +Or include the routine in the AgentTemplate: +```yaml +routines: + - name: daily-check + event_type: schedule.cron + schedule: "0 9 * * 1-5" + handler_type: script + config_ref: daily-check-script +``` + +**Important**: Scheduled routines need both `schedule` and `event_type: schedule.cron`. Do not put schedules under nested `event_config.schedule`. + +## Workflow Design Best Practices + +- **Start simple**: Begin with a linear flow, add branching only when needed. +- **Name nodes clearly**: Use descriptive IDs (`fetch_orders`, `check_status`) not generic ones (`step1`, `step2`). +- **Handle errors**: Follow the real graph schema from `workflowdocs` and the sample config. Don't assume every HTTP call succeeds. +- **Use scripts for logic**: Keep business logic in Script resources or embedded workflow script data instead of improvising unsupported fields. +- **Test scripts independently**: Use `archastro run script --file ` to test scripts before wiring them into a workflow. +- **Cron syntax**: Standard 5-field cron. Use https://crontab.guru for help. + +## Recovery Rules + +- If workflow validation fails, show the exact error — it usually points to a specific node or field. +- If a routine run fails, check `archastro list agentroutineruns` for the error details. +- If a workflow depends on script logic that does not exist yet, create and validate that script first. +- If the user is unsure about workflow vs. simple routine, ask how many steps the process has. One step = simple routine. Multiple steps with branching = workflow. + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- When authoring workflows, show the user a concrete JSON graph draft they can review. +- Prefer showing the full workflow structure over explaining node types abstractly. diff --git a/sources/chat.md b/sources/chat.md index 1f6a046..3b63008 100644 --- a/sources/chat.md +++ b/sources/chat.md @@ -5,7 +5,7 @@ targets: skill: name: chat description: Use when the user wants to send a message to an ArchAstro agent, ask an agent a question, view a thread conversation, check for agent responses, or interact with an agent. Trigger phrases include "send a message", "ask the agent", "what did the agent say", "show the conversation", "check the thread", "talk to the agent", "message the agent", "create a session". - allowed-tools: ['Bash(archastro:*)'] + allowed-tools: ["Bash(archastro:*)"] --- @@ -15,6 +15,21 @@ Send messages to agents and view their responses. This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}} +## Quick Reference + +| Task | Command | +|------|---------| +| Ask agent a question | `archastro create agentsession --agent --instructions "..." --wait` | +| Create a thread | `archastro create thread --title "..." --owner-type agent --owner-id --json` | +| Create a test user | `archastro create user --system-user --name "..." --json` | +| Add member to thread | `archastro create threadmember --thread --user-id --json` | +| Add agent to thread | `archastro create threadmember --thread --agent-id --json` | +| Send message (wait for reply) | `archastro create threadmessage --thread --user-id -c "..." --wait --json` | +| View conversation | `archastro list threadmessages --thread --full` | +| List agent sessions | `archastro list agentsessions --agent --json` | + +Use `--help` on any command for full options. + ## Always Start with State Every invocation must begin by understanding the current context. Determine: @@ -86,14 +101,7 @@ Use `describe --follow` to stream updates on a session created without `--wait`. ### User wants to send a thread message -1. **Determine the sender ID**: - - **Org mode**: Get the user's ID from `archastro auth status`. - - **Developer mode**: Look up thread members: - ``` - archastro list threadmembers --thread - ``` +1. **Determine the sender ID**: Get the user's ID from `archastro auth status`. 2. **Send the message and wait for the response**: ``` @@ -115,14 +123,39 @@ Always use `--full` — the default table view truncates content. ### User needs a new thread +**Agent-owned thread** (recommended when an agent should participate): + +1. Create the thread owned by the agent: + ``` + archastro create thread --title "..." --owner-type agent --owner-id --json + ``` + +2. Create a test user (if needed) and add them to the thread: + ``` + archastro create user --system-user --name "Test User" --json + archastro create threadmember --thread --user-id --json + ``` + +3. Send a message and wait for the agent to respond: + ``` + archastro create threadmessage --thread --user-id -c "Hello" --wait --json + ``` + +4. View the conversation: + ``` + archastro list threadmessages --thread --full + ``` + +**User-owned thread** (when a user starts the conversation): + 1. Create the thread: ``` - archastro create thread --title "..." --user + archastro create thread --title "..." --user --json ``` -2. Add members: +2. Add the agent: ``` - archastro create threadmember --thread --agent-id + archastro create threadmember --thread --agent-id --json ``` ## Response Rules diff --git a/sources/agent_deploy.md b/sources/deploy-agent.md similarity index 86% rename from sources/agent_deploy.md rename to sources/deploy-agent.md index 349c691..8b098c2 100644 --- a/sources/agent_deploy.md +++ b/sources/deploy-agent.md @@ -1,11 +1,11 @@ --- targets: - claude-skill: agent_deploy - codex-skill: agent_deploy + claude-skill: deploy-agent + codex-skill: deploy-agent skill: - name: agent_deploy + name: deploy-agent description: Use when the user wants to deploy an ArchAstro agent, turn a config-driven agent repo into a running agent, or get an existing agent running in a thread. Trigger phrases include "deploy agent", "deploy this agent", "set up an agent", "launch agent", "ship this agent", "get this agent running". - allowed-tools: ['Bash(archastro:*)'] + allowed-tools: ["Bash(archastro:*)"] --- @@ -40,13 +40,17 @@ Before any deployment work, verify the CLI: - Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. - If authentication or app selection is missing, {{AUTH_ROUTE}}. +### Local config directory not initialized + +If the user has config files but no `configs/` directory set up, route to the `manage-configs` skill first. That skill owns local config management. + ### User wants to deploy a new agent Use the config-driven golden path. Do not skip straight to `create agent`. 1. **Deploy configs first**: ``` - archastro configs deploy + archastro deploy configs ``` This pushes Script and AgentTemplate configs to the server. For config-driven agents, this should happen before provisioning the agent itself. @@ -67,10 +71,10 @@ Use the config-driven golden path. Do not skip straight to `create agent`. ### User needs help creating or editing the config files first -Route to the `agent_authoring` skill before deploying. That skill owns: +Route to the `author-agent` skill before deploying. That skill owns: - `AgentTemplate` and Script config creation -- `archastro configs sample` -- `archastro configs script-reference` +- `archastro describe configsample` +- `archastro describe scriptdocs` - routine scheduling shape - env-var scope guidance @@ -105,11 +109,11 @@ Summarize what's deployed and offer to deploy a new one or add an existing one t ## Recovery Rules - If `archastro deploy agent` fails with a validation-style error, inspect the exact CLI output first. Do not immediately fall back to lower-level provisioning commands. -- If the problem appears to be in the config files, route to `agent_authoring`. +- If the problem appears to be in the config files, route to `author-agent`. - If a script-related validation error appears, use: ``` - archastro configs script-reference - archastro configs sample Script + archastro describe scriptdocs + archastro describe configsample Script ``` Do not invent script syntax from memory. - Prefer human-readable `config_ref` names that match deployed config lookup keys. Do not rewrite refs to raw `cfg_...` IDs unless explicitly debugging a broken environment. diff --git a/sources/impersonate.md b/sources/impersonate.md index 65b0545..efbd8e9 100644 --- a/sources/impersonate.md +++ b/sources/impersonate.md @@ -8,19 +8,28 @@ skill: description: Use when the user wants to impersonate an ArchAstro agent, asks about the active impersonation state, wants to refresh or stop impersonation, or refers to working as a specific ArchAstro agent inside {{HARNESS_NAME}}. Trigger phrases include "impersonate agent", "act as this agent", "be this agent", "start impersonation", "sync impersonation", "stop impersonation", "what agent am I impersonating", and "use the active agent identity". allowed-tools: ["Bash(archastro:*)"] command: - description: Run an archastro impersonate CLI command directly + description: Start, inspect, refresh, or stop ArchAstro impersonation through the ArchAstro CLI allowed-tools: ["Bash(archastro:*)"] --- -{{#SKILL}}# ArchAstro Agent Impersonation +# ArchAstro Impersonation -Manage ArchAstro agent impersonation and keep the {{SESSION}} aligned with the active identity. +{{#SKILL}}Manage ArchAstro impersonation through the ArchAstro CLI and keep the {{SESSION}} aligned with the active identity file. -This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}} +This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}}{{/SKILL}}{{#CLAUDE_COMMAND}}Manage ArchAstro impersonation from Claude Code and keep the current session aligned with the active identity file. + +Command aliases: + +```text +/archastro:impersonate start +/archastro:impersonate status +/archastro:impersonate sync +/archastro:impersonate stop +```{{/CLAUDE_COMMAND}} ## Always Start with State -Every invocation of this skill must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. +Every invocation must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent. ``` archastro impersonate status --json @@ -34,8 +43,7 @@ Then route based on the combination of current state and user intent. Before any impersonation work, verify the CLI: -- Read `plugin-compatibility.json` from the plugin root. -- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Read `plugin-compatibility.json` from the plugin root. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. - Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. - If authentication or app selection is missing, {{AUTH_ROUTE}}. @@ -93,6 +101,20 @@ archastro impersonate stop Drop the impersonated identity from the current session. Confirm that local state was removed. +### Active + user asks about tools + +List the impersonated agent's tools: + +``` +archastro impersonate list tools --json +``` + +To execute a tool directly: + +``` +archastro impersonate run tool --input '' --json +``` + ### Active + user asks about skills List available skills: @@ -133,6 +155,11 @@ When you read the identity file, you must **become that agent** for the rest of After `stop`, fully drop the persona and return to your normal behavior. +## Limitations + +- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. +- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. + ## Session Integration - After `start` or `sync`, always read the identity file and adopt it as described above @@ -140,37 +167,9 @@ After `stop`, fully drop the persona and return to your normal behavior. - When showing status, always include loaded skill invocations so the user knows what commands are available - When skills are available but not installed, proactively mention them -## Limitations - -- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available. -- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent --wait`) instead of impersonation. - ## Response Rules - Do not inspect or edit credential files directly — use the CLI only. - Do not ask the user to pick a subcommand — infer the action from their message and the current state. - If the CLI reports an auth or app error, {{AUTH_ROUTE_SHORT}} or suggest `--app `. -- Keep responses concise — state the outcome, not the process.{{/SKILL}}{{#CLAUDE_COMMAND}}# ArchAstro Agent Impersonation (CLI passthrough) - -Pass arguments directly to `archastro impersonate`. - -```text -/archastro:impersonate start -/archastro:impersonate status -/archastro:impersonate sync -/archastro:impersonate stop -/archastro:impersonate list skills -/archastro:impersonate install skill [--harness codex] [--install-scope project] -``` - -## Instructions - -1. Read `plugin-compatibility.json`. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. -2. Run `archastro --version`. If missing or too old, tell the user to run `/archastro:install`. -3. Run: - ``` - archastro impersonate $ARGUMENTS - ``` -4. If the command was `start` or `sync`, also run `archastro impersonate status --json`, read the `identity_file`, and adopt the identity for the current session. -5. If the command was `stop`, drop any impersonated identity from the current session. -6. If auth or app selection fails, {{AUTH_ROUTE}} or `--app `.{{/CLAUDE_COMMAND}} +- Keep responses concise — state the outcome, not the process. diff --git a/sources/install.md b/sources/install.md index d34f848..4df467f 100644 --- a/sources/install.md +++ b/sources/install.md @@ -7,21 +7,20 @@ skill: description: Use when the user wants to install, upgrade, or bootstrap the ArchAstro CLI. Trigger phrases include "install archastro", "install the archastro CLI", "set up archastro", "upgrade archastro", "archastro not found", "archastro command not found", "install the CLI", "get archastro running". allowed-tools: ["Bash(archastro:*)", "Bash(brew:*)", "Bash(curl:*)", "Bash(bash:*)", "Bash(sh:*)", "Bash(pwsh:*)", "Bash(powershell:*)"] command: - description: Install the ArchAstro developer platform CLI + description: Install the ArchAstro platform CLI allowed-tools: ["Bash(archastro:*)", "Bash(brew:*)", "Bash(curl:*)", "Bash(bash:*)", "Bash(sh:*)", "Bash(pwsh:*)", "Bash(powershell:*)"] --- - # Install ArchAstro CLI Install or upgrade the public `archastro` binary from Homebrew or GitHub Releases. -## Instructions +## Workflow 1. **Read the compatibility contract first**: - - Use `plugin-compatibility.json`. - - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`. - - Treat that resolved value as the minimum supported CLI version for every check below. + - Use `plugin-compatibility.json` from the plugin root. + - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. + - Treat the resolved value as the minimum supported CLI version for every check below. 2. **Check whether the CLI is already installed**: ``` @@ -29,9 +28,9 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release ``` If this succeeds, record the version. -3. **If the CLI is present and meets the resolved minimum version**, confirm the version and stop unless the user explicitly asked to upgrade. +3. **If the CLI is present and meets the resolved minimum**, confirm the version and stop unless the user explicitly asked to upgrade. -4. **If the CLI is missing or older than the resolved minimum version**, install it using the public distribution path: +4. **If the CLI is missing or older than the resolved minimum**, install it using the public distribution path: - On macOS, if Homebrew is available: ``` brew install ArchAstro/tools/archastro @@ -53,12 +52,12 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release ``` archastro --version ``` - Confirm that the version now meets the resolved minimum version. + Confirm that the version now meets the resolved minimum. -6. **On success**, tell the user the CLI is ready and {{#CLAUDE_COMMAND}}suggest `/archastro:auth`{{/CLAUDE_COMMAND}}{{#SKILL}}suggest they run `archastro auth login` to authenticate{{/SKILL}}. +6. **On failure, help troubleshoot the public install path**: + - Missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh`. + - `Permission denied` usually means they need `--install-dir` or a user-writable target directory. + - `command not found: archastro` after install usually means the install directory is not on `PATH`. + - Release download failures usually mean the target release asset has not been published yet. -7. **On failure**, help troubleshoot the public install path: - - missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh` - - `Permission denied` usually means they need `--install-dir` or a user-writable target directory - - `command not found: archastro` after install usually means the install directory is not on `PATH` - - release download failures usually mean the target release asset has not been published yet +7. **On success**, tell the user the CLI is ready and {{#CLAUDE_COMMAND}}suggest `/archastro:auth`{{/CLAUDE_COMMAND}}{{#SKILL}}suggest they run `archastro auth login` to authenticate{{/SKILL}}. diff --git a/sources/manage-configs.md b/sources/manage-configs.md new file mode 100644 index 0000000..6d37f77 --- /dev/null +++ b/sources/manage-configs.md @@ -0,0 +1,234 @@ +--- +targets: + claude-skill: manage-configs + codex-skill: manage-configs +skill: + name: manage-configs + description: Use when the user wants to set up or manage local config files for an ArchAstro project — initialize a configs directory, edit configs locally, sync from the server, or deploy local changes. Trigger phrases include "set up configs", "init configs", "configs directory", "sync configs", "deploy configs", "edit config locally", "local config management". + allowed-tools: ["Bash(archastro:*)"] +--- + + +# ArchAstro Local Config Management + +Set up and manage a local `configs/` directory for editing agent configs as files, syncing with the server, and deploying changes. + +This skill assumes the ArchAstro CLI is already installed and authenticated. {{ASSUME_INSTALLED}} + +## What is Local Config Management? + +Instead of creating and editing configs one-by-one through CLI CRUD commands, you can manage them as local files in a `configs/` directory. This enables: +- **Edit configs in your editor** with syntax highlighting and version control +- **Batch deploy** all changes in dependency order +- **Sync** server configs down to local files +- **Browser editor** for visual editing of individual configs + +The CLI tracks the mapping between local files and server configs in a manifest file. + +## Always Start with State + +Every invocation must begin by understanding the current project state: + +``` +archastro auth status +ls configs/ 2>/dev/null || echo "No configs directory" +``` + +Determine: +- Does a `configs/` directory already exist? +- Is the user starting a new project or working with an existing one? +- Do they want to pull configs from the server or push local changes? + +## Routing + +### CLI not installed or too old + +Before any config work, verify the CLI: + +- Read `plugin-compatibility.json` from the plugin root. +- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`. +- Run `archastro --version`. If missing or older than the resolved minimum, {{INSTALL_ROUTE}}. +- If authentication or app selection is missing, {{AUTH_ROUTE}}. + +### User wants to set up a configs directory for the first time + +1. **Initialize the config directory**: + ``` + archastro init --enable-configs + ``` + This enables local config management and creates the configured `configs/` directory if needed. It does not automatically sync remote configs; use `archastro sync configs` next when you want local files. + +2. **Explain the layout**: After init, the directory looks like: + ``` + configs/ + ├── .archastro-manifest.json # Maps local files to server configs (do not edit manually) + ├── agents/ # AgentTemplate configs + ├── skills/ # Skill bundles + ├── scripts/ # Script configs + ├── workflows/ # Workflow configs + └── ... # Other config kinds + ``` + + Managed virtual paths also follow these prefixes on the server: `skills/`, `scripts/`, and `workflows/`. + +3. **Offer next steps**: Ask if the user wants to create a new config (`archastro describe configsample `) or sync existing configs from the server. + +### User wants to pull configs from the server + +Sync server configs to local files: +``` +archastro sync configs +``` + +This downloads all configs for the current app — including skills, scripts, and workflows — and writes them as local files in the correct directories. The manifest tracks the file-to-config mapping. + +After syncing, the directory structure reflects server state: +``` +configs/ +├── agents/ # AgentTemplate configs (.yaml) +├── skills/my-skill/ # Skill bundles (SKILL.md + supporting files) +├── scripts/ # Script configs (.agentscript) +├── workflows/ # Workflow configs (.json) +└── ... # Other config kinds +``` + +You can then edit any file locally and run `archastro deploy configs` to push changes back. + +### User wants to create a new config locally + +For **scripts**, **skills**, and **workflows**, prefer the dedicated commands or create files directly in the correct directory: + +- **Script**: Write a `.agentscript` file in `configs/scripts/`: + ``` + configs/scripts/my-script.agentscript + ``` +- **Skill**: Create a `SKILL.md` (with frontmatter) in `configs/skills//`: + ``` + configs/skills/my-skill/SKILL.md + configs/skills/my-skill/prompts/greeting.liquid # optional supporting files + ``` +- **Workflow**: Write a `.json` file in `configs/workflows/`: + ``` + configs/workflows/my-workflow.json + ``` + +For **other config kinds** (AgentTemplate, Persona, etc.), get a sample: +``` +archastro list configkinds +archastro describe configsample --to-file ./configs//.yaml +``` + +You can also use the browser editor: +``` +archastro edit config ./configs//.yaml +``` + +### User wants to validate local configs + +Validate a specific config file: +``` +archastro validate config -k -f ./configs//.yaml +``` + +For scripts specifically, use the dedicated validator: +``` +archastro validate script --file ./configs/scripts/my-script.agentscript +``` + +### User wants to deploy local changes + +Push all local config changes to the server: +``` +archastro deploy configs +``` + +This: +- Compares local files against the manifest +- Uploads new and changed configs in dependency order +- Updates the manifest with new server IDs + +#### Managed directory conventions + +`deploy configs` enforces conventions for three managed directories: + +| Directory | Convention | +|-----------|-----------| +| `skills//` | All files become `File` kind. `SKILL.md` is the root — name and description are extracted from its YAML frontmatter. Other files (`.liquid`, `.yaml`, `.js`, etc.) become supporting skill files. | +| `scripts/` | Only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed. Other file types are rejected. | +| `workflows/` | Only `.json` files and `.yaml` with a `Workflow*` kind are allowed. Other file types are rejected. | + +Files outside these directories use standard kind inference from file extension or YAML content. + +**Important**: `deploy configs` syncs config files only. It does not create agents. To provision an agent from a template, use `archastro deploy agent ` separately. + +### User wants to move or rename a config file + +If a local config file is moved or renamed: +``` +archastro update configpath +``` + +This updates the manifest mapping without affecting the server config. + +### User has manifest issues + +If the manifest gets out of sync: +``` +archastro validate configmanifest +``` + +This re-normalizes the manifest and resolves any inconsistencies. + +## Typical Workflows + +### New project from scratch +``` +archastro init --enable-configs +archastro describe configsample AgentTemplate --to-file ./configs/agents/my-agent.yaml +# Edit the file... +archastro validate config -k AgentTemplate -f ./configs/agents/my-agent.yaml +archastro deploy configs +archastro deploy agent ./configs/agents/my-agent.yaml +``` + +### Create a skill via local files +``` +archastro init --enable-configs +mkdir -p configs/skills/my-skill +# Write SKILL.md with frontmatter (name, description) +# Add supporting files (prompts, references, etc.) +archastro deploy configs +# Skill is now visible via: archastro list skills +``` + +### Create a script via local files +``` +archastro init --enable-configs +# Write script source directly +echo 'println("hello")' > configs/scripts/my-script.agentscript +archastro deploy configs +# Script is now visible via: archastro describe script my-script +``` + +### Pull existing project and make changes +``` +archastro init --enable-configs +archastro sync configs +# Edit files locally... +archastro deploy configs +``` + +### Quick edit via browser +``` +archastro edit config ./configs/agents/my-agent.yaml +# Opens in browser with live validation +# Changes are saved to the server and synced back to the local file +``` + +## Response Rules + +- Do not inspect or edit credential files directly — use the CLI only. +- Do not manually edit `.archastro-manifest.json` — use CLI commands. +- Do not ask the user to pick raw subcommands when intent is clear. +- Keep responses concise and operational. +- Always recommend `deploy configs` over individual `create config` calls when working with local files.