From ce13603e702760ee69682351c62e1e8de6a2c1fd Mon Sep 17 00:00:00 2001 From: Mandar Nilange Date: Sat, 2 May 2026 11:36:16 +0530 Subject: [PATCH 1/3] docs(skills): add fill-in-the-blanks skill quickstart for first-time users MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A small editable markdown the user edits in place — fills in goal / inputs / constraints / starting point — and pastes into their AI agent to fire agentforge-workflow. Targets agentforge-core users who will typically drop a shared default .agentforge/ folder into their project and customize from there. Linked from the README's Agent Skills section and the Get-started track of the Learn-more index, plus a top-of-page pointer in skills/README.md. --- README.md | 5 +- docs/skill-quickstart.md | 127 +++++++++++++++++++++++++++++++++++++++ skills/README.md | 6 ++ 3 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 docs/skill-quickstart.md diff --git a/README.md b/README.md index a958853..0fd8796 100644 --- a/README.md +++ b/README.md @@ -234,7 +234,9 @@ npx skills add mandarnilange/agentforge | `agentforge-template-author` | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. | | `agentforge-debug` | Operator | Triages stuck or failing pipeline runs from symptom to fix path. | -Trigger phrases live in each skill's frontmatter — e.g. *"help me design an AgentForge pipeline for PR triage"* fires `agentforge-workflow`; *"why is pipeline X stuck?"* fires `agentforge-debug`. Catalog, changelog, and authoring docs: [`skills/`](skills/). +Trigger phrases live in each skill's frontmatter — e.g. *"help me design an AgentForge pipeline for PR triage"* fires `agentforge-workflow`; *"why is pipeline X stuck?"* fires `agentforge-debug`. + +**New here?** The [Skill Quickstart](docs/skill-quickstart.md) is a 5-minute, fill-in-the-blanks markdown you edit, paste into your AI agent, and run. Catalog, changelog, and authoring docs: [`skills/`](skills/). --- @@ -280,6 +282,7 @@ agentforge node start --control-plane-url # Run as a worker (platform) Every deep-dive lives in [`docs/`](docs/). Pick a track: **Get started** +- **[Skill Quickstart](docs/skill-quickstart.md)** — 5-minute, fill-in-the-blanks path from zero to your first run via the `agentforge-workflow` skill. - **[Getting Started](docs/getting-started.md)** — install to first pipeline run, full CLI walkthrough, resume flow. - **[Who Uses It](docs/who-uses-it.md)** — what platform engineers, software engineers, and domain owners each get out of AgentForge. - **[Templates](docs/templates.md)** — catalog of bundled pipeline templates. diff --git a/docs/skill-quickstart.md b/docs/skill-quickstart.md new file mode 100644 index 0000000..b7022c5 --- /dev/null +++ b/docs/skill-quickstart.md @@ -0,0 +1,127 @@ +# Your First AgentForge Run — Skill Quickstart + +> 5-minute path from zero to your first agentic pipeline using the +> [`agentforge-workflow`](../skills/agentforge-workflow/SKILL.md) skill. + +This file is **editable**. Fill in the bracketed sections, paste them into +your AI coding agent (Claude Code / Cursor / Codex), and the skill takes +over. + +--- + +## 1. One-time setup + +```bash +# Install the framework (core is enough for most starter pipelines) +npm install @mandarnilange/agentforge-core + +# Install the skills into your AI coding agent +npx skills add mandarnilange/agentforge + +# Set your LLM key +export ANTHROPIC_API_KEY=sk-ant-... +``` + +> Already have `@mandarnilange/agentforge` (the platform binary) installed? +> The skills work the same way; just use `agentforge` instead of +> `agentforge-core` in the commands below. + +--- + +## 2. Drop in the starter `.agentforge/` (optional) + +If your project owner shared a default `.agentforge/` directory, copy it +into your project root before continuing. + +If not, leave it out — the skill will design one from scratch in step 4. + +--- + +## 3. Fill in your project brief + +✏️ **Edit the section between the markers below.** Anything in `<...>` is +a placeholder. + + + +**Goal** +> + +**Inputs** +> + +**Output artifacts** +> + +**Hard constraints** +> + +**Starting point** +> + + + +--- + +## 4. Trigger the skill + +Open your AI coding agent in this project. Paste: + +> Help me set up my AgentForge workflow. Here is my brief — please use the +> `agentforge-workflow` skill. +> +> *(paste the BRIEF section above)* + +The skill walks through any clarifying questions, recommends a starting +template if one fits, and emits a complete `.agentforge/` directory. + +> **What the skill will and will not do** — by default it *creates new +> files alongside* anything that already exists. It only edits existing +> agents / pipelines / prompts when you explicitly say *update*, *edit*, +> *modify*, *extend*, or *rewrite* (or name a specific file). Per-file +> confirmation before any edit. See the +> [Modification policy](../skills/agentforge-workflow/SKILL.md#modification-policy) +> for the full rules. + +--- + +## 5. Run your first pipeline + +```bash +# Validate the .agentforge/ the skill produced +npx @mandarnilange/agentforge-core list + +# Run it +npx @mandarnilange/agentforge-core run \ + --project my-first-run \ + --input "brief=" + +# Watch it live +npx @mandarnilange/agentforge-core dashboard # → http://localhost:3001 +``` + +--- + +## 6. Iterate + +To evolve the pipeline later, ask the same agent: + +- *"Add a new agent for security review after the architect."* → adds a + new agent file, no existing files touched. +- *"Update the analyst agent to use `claude-haiku-4-5`."* → asks for + per-file confirmation, then edits. +- *"Add a parallel test-generation phase."* → new pipeline file or + modification, with confirmation. +- *"My run is stuck at phase 2."* → fires + [`agentforge-debug`](../skills/agentforge-debug/SKILL.md) to triage. + +--- + +## What success looks like + +- A complete `.agentforge/` directory in your project root. +- A green run with artifacts under `output/`. +- A dashboard view at showing the run timeline. + +If anything looks off, ask your agent: *"why is pipeline `` +failing?"* — `agentforge-debug` takes it from there. diff --git a/skills/README.md b/skills/README.md index dfe98c7..5ae46c0 100644 --- a/skills/README.md +++ b/skills/README.md @@ -17,6 +17,12 @@ The Vercel skills CLI scans the repo's `skills/` directory and installs every sk npx skills add https://github.com/mandarnilange/agentforge/tree/main/skills/agentforge-workflow ``` +## New here? Use the quickstart + +The [Skill Quickstart](../docs/skill-quickstart.md) is a 5-minute, +fill-in-the-blanks markdown you edit, paste into your AI agent, and run. +It's the recommended path for anyone trying the skills for the first time. + ## Available skills | Skill | Audience | What it does | From f97bc79df6101a11e4a7409d60aaa3afa9357b5a Mon Sep 17 00:00:00 2001 From: Mandar Nilange Date: Sat, 2 May 2026 11:41:34 +0530 Subject: [PATCH 2/3] docs(skills): rewrite skill quickstart as a 4-step conversational guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drops the bracketed brief template and the .agentforge starter section. Replaces with a plain four-step flow: install skill → open your AI coding agent → describe what you want (with four sample prompts spanning SDLC / content / code review / something new) → run the commands the skill prints. Adds a "what else you can do" section with conversational follow-up prompts (add agent, tweak agent, add parallelism, insert gate, debug, contribute template) so users see the day-2 surface, not just day 1. Pitched at the @mandarnilange/agentforge-core install path since that's the primary user audience. --- docs/skill-quickstart.md | 151 +++++++++++++++++++-------------------- 1 file changed, 72 insertions(+), 79 deletions(-) diff --git a/docs/skill-quickstart.md b/docs/skill-quickstart.md index b7022c5..d034e4b 100644 --- a/docs/skill-quickstart.md +++ b/docs/skill-quickstart.md @@ -1,127 +1,120 @@ -# Your First AgentForge Run — Skill Quickstart +# Skill Quickstart -> 5-minute path from zero to your first agentic pipeline using the -> [`agentforge-workflow`](../skills/agentforge-workflow/SKILL.md) skill. - -This file is **editable**. Fill in the bracketed sections, paste them into -your AI coding agent (Claude Code / Cursor / Codex), and the skill takes -over. +5 minutes, four steps, zero YAML. You talk; the skill writes the +pipeline. --- -## 1. One-time setup +## 1. Install the skill ```bash -# Install the framework (core is enough for most starter pipelines) npm install @mandarnilange/agentforge-core - -# Install the skills into your AI coding agent npx skills add mandarnilange/agentforge - -# Set your LLM key export ANTHROPIC_API_KEY=sk-ant-... ``` -> Already have `@mandarnilange/agentforge` (the platform binary) installed? -> The skills work the same way; just use `agentforge` instead of -> `agentforge-core` in the commands below. +That installs three skills into your AI coding agent: ---- +| Skill | What it does | +|---|---| +| `agentforge-workflow` | Designs your pipeline and writes `.agentforge/` | +| `agentforge-template-author` | (For contributors) ships a new template upstream | +| `agentforge-debug` | Triages a stuck or failing run | -## 2. Drop in the starter `.agentforge/` (optional) +--- -If your project owner shared a default `.agentforge/` directory, copy it -into your project root before continuing. +## 2. Open your AI coding agent -If not, leave it out — the skill will design one from scratch in step 4. +Any of these works the same way — **Claude Code, Cursor, Codex, Aider, +Continue.dev**. Open the agent in your project folder. The skills +auto-load; no restart needed. --- -## 3. Fill in your project brief +## 3. Tell the skill what you want -✏️ **Edit the section between the markers below.** Anything in `<...>` is -a placeholder. +Type a one- or two-sentence description of what you're trying to build. +The `agentforge-workflow` skill catches the trigger and asks any +follow-ups it needs (inputs, outputs, gates, budgets, parallelism). - +Try one of these as a starting prompt: -**Goal** -> +**Classic SDLC pipeline** +> Help me design an AgentForge pipeline that turns a product brief into +> requirements, an architecture plan, and working code. I want a human +> approval gate after the architecture phase. -**Inputs** -> +**Content generation with self-review** +> Build me an AgentForge workflow for producing research-backed blog +> posts: research the topic, write an outline, draft the post, and +> self-review for quality before handing me the final version. -**Output artifacts** -> +**Code review pipeline** +> I want an AgentForge pipeline that reviews a PR diff and produces +> severity-tagged review comments plus a security risk score. The +> reviewers should run in parallel. -**Hard constraints** -> +**Something brand new** +> Design an AgentForge workflow for triaging incoming customer-support +> tickets — classify by category, draft a response, route urgent ones +> to a human gate. -**Starting point** -> +What the skill does next: - +- Recommends a shipped template if one fits (`simple-sdlc`, + `content-generation`, `code-review`, `data-pipeline`, + `seo-review`, `api-builder`). +- Asks any clarifying questions about your inputs, outputs, gates, + budgets, parallelism. +- Writes a complete `.agentforge/` directory into your project root. --- -## 4. Trigger the skill - -Open your AI coding agent in this project. Paste: - -> Help me set up my AgentForge workflow. Here is my brief — please use the -> `agentforge-workflow` skill. -> -> *(paste the BRIEF section above)* +## 4. Run the pipeline the skill built -The skill walks through any clarifying questions, recommends a starting -template if one fits, and emits a complete `.agentforge/` directory. - -> **What the skill will and will not do** — by default it *creates new -> files alongside* anything that already exists. It only edits existing -> agents / pipelines / prompts when you explicitly say *update*, *edit*, -> *modify*, *extend*, or *rewrite* (or name a specific file). Per-file -> confirmation before any edit. See the -> [Modification policy](../skills/agentforge-workflow/SKILL.md#modification-policy) -> for the full rules. - ---- - -## 5. Run your first pipeline +When the skill finishes it tells you the exact commands. They look like: ```bash -# Validate the .agentforge/ the skill produced +# Validate what got generated npx @mandarnilange/agentforge-core list -# Run it +# Run it (replace the brief with your real input) npx @mandarnilange/agentforge-core run \ --project my-first-run \ - --input "brief=" + --input "brief=Build a freelance invoicing SaaS" -# Watch it live +# Watch the run live npx @mandarnilange/agentforge-core dashboard # → http://localhost:3001 ``` +That's the full loop. + --- -## 6. Iterate +## What else you can do, conversationally -To evolve the pipeline later, ask the same agent: +The skills are designed to keep working with you across sessions. Some +prompts that keep paying off: -- *"Add a new agent for security review after the architect."* → adds a - new agent file, no existing files touched. -- *"Update the analyst agent to use `claude-haiku-4-5`."* → asks for - per-file confirmation, then edits. -- *"Add a parallel test-generation phase."* → new pipeline file or - modification, with confirmation. -- *"My run is stuck at phase 2."* → fires - [`agentforge-debug`](../skills/agentforge-debug/SKILL.md) to triage. +- **Add a new agent** — *"Add a security review agent after the + architect."* → creates a new agent file; existing ones untouched. +- **Tweak an existing agent** — *"Update the analyst agent to use + `claude-haiku-4-5`."* → asks you to confirm per file before editing. +- **Add parallelism** — *"Run the test generator and the code generator + in parallel."* → modifies the pipeline (with confirmation). +- **Insert a gate** — *"I want to review before code generation + starts."* → adds a gate to the relevant phase. +- **Debug a run** — *"Why is pipeline `` stuck at phase 2?"* → + fires `agentforge-debug` to triage. +- **Ship a new template upstream** — *"Help me contribute a new template + for ML pipeline scaffolding."* → fires `agentforge-template-author`. --- -## What success looks like - -- A complete `.agentforge/` directory in your project root. -- A green run with artifacts under `output/`. -- A dashboard view at showing the run timeline. +## Heads up -If anything looks off, ask your agent: *"why is pipeline `` -failing?"* — `agentforge-debug` takes it from there. +By default the workflow skill **creates new files alongside existing +ones** — it never silently overwrites your `.agentforge/`. To edit +something that already exists, say *update / edit / modify / extend* (or +name the file). The skill confirms each edit before writing. Full rules: +[Modification policy](../skills/agentforge-workflow/SKILL.md#modification-policy). From 81d7dc3cab16af78195844448b62631126f5f333 Mon Sep 17 00:00:00 2001 From: Mandar Nilange Date: Sat, 2 May 2026 11:50:33 +0530 Subject: [PATCH 3/3] =?UTF-8?q?feat(skills):=20add=20agentforge-cli=20?= =?UTF-8?q?=E2=80=94=20conversational=20interface=20to=20the=20CLI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fourth skill in the family. Maps natural-language operational asks ("run my pipeline", "approve gate X", "show me logs", "apply this YAML", "list pending gates") to the right agentforge / agentforge-core command, executes via the host agent's shell, and summarises the output instead of dumping raw tables. Discipline matches the rest of the family: - Read-first / confirm-before-mutate. Read-only commands (list, info, templates list, get *, describe node, logs, dashboard start) execute immediately. State-mutating or cost-incurring commands (run, run --continue, exec, gate {approve,reject,revise}, apply, node start) require explicit confirmation via AskUserQuestion or equivalent, with cost ceiling surfaced when visible from agent budgets. - Never invent flags — the command map is sourced from packages/{core,platform}/src/cli/commands/ verbatim. - Long-running commands (dashboard, node start) backgrounded so they don't block the conversation. - Human-readable summaries by default; raw tables only when explicitly requested. Skill family is now: workflow (design) + cli (operate) + debug (triage) + template-author (contribute upstream). Same install command picks up the new skill automatically: npx skills add mandarnilange/agentforge Quickstart, README's Agent Skills table, and skills/README.md updated to surface the new skill alongside the existing three. --- README.md | 5 +- docs/skill-quickstart.md | 25 ++- skills/CHANGELOG.md | 9 + skills/README.md | 3 +- skills/agentforge-cli/CHANGELOG.md | 25 +++ skills/agentforge-cli/SKILL.md | 182 ++++++++++++++++++ .../agentforge-cli/references/command-map.md | 105 ++++++++++ .../references/confirmation-rules.md | 122 ++++++++++++ .../references/output-summary.md | 109 +++++++++++ 9 files changed, 579 insertions(+), 6 deletions(-) create mode 100644 skills/agentforge-cli/CHANGELOG.md create mode 100644 skills/agentforge-cli/SKILL.md create mode 100644 skills/agentforge-cli/references/command-map.md create mode 100644 skills/agentforge-cli/references/confirmation-rules.md create mode 100644 skills/agentforge-cli/references/output-summary.md diff --git a/README.md b/README.md index 0fd8796..db7879d 100644 --- a/README.md +++ b/README.md @@ -231,10 +231,11 @@ npx skills add mandarnilange/agentforge | Skill | Audience | What it does | |---|---|---| | `agentforge-workflow` | End user | Walks through designing an AgentForge workflow and emits a complete `.agentforge/` directory. | -| `agentforge-template-author` | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. | +| `agentforge-cli` | Operator | Conversational interface to the AgentForge CLI — run, monitor, approve gates, apply YAML. | | `agentforge-debug` | Operator | Triages stuck or failing pipeline runs from symptom to fix path. | +| `agentforge-template-author` | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. | -Trigger phrases live in each skill's frontmatter — e.g. *"help me design an AgentForge pipeline for PR triage"* fires `agentforge-workflow`; *"why is pipeline X stuck?"* fires `agentforge-debug`. +Trigger phrases live in each skill's frontmatter — e.g. *"help me design a PR-triage pipeline"* fires `agentforge-workflow`, *"approve the architect gate"* fires `agentforge-cli`, *"why is pipeline X stuck?"* fires `agentforge-debug`. **New here?** The [Skill Quickstart](docs/skill-quickstart.md) is a 5-minute, fill-in-the-blanks markdown you edit, paste into your AI agent, and run. Catalog, changelog, and authoring docs: [`skills/`](skills/). diff --git a/docs/skill-quickstart.md b/docs/skill-quickstart.md index d034e4b..3cb9489 100644 --- a/docs/skill-quickstart.md +++ b/docs/skill-quickstart.md @@ -13,13 +13,14 @@ npx skills add mandarnilange/agentforge export ANTHROPIC_API_KEY=sk-ant-... ``` -That installs three skills into your AI coding agent: +That installs four skills into your AI coding agent: | Skill | What it does | |---|---| | `agentforge-workflow` | Designs your pipeline and writes `.agentforge/` | -| `agentforge-template-author` | (For contributors) ships a new template upstream | +| `agentforge-cli` | Runs the CLI for you — *"run my pipeline"*, *"approve gate X"*, *"show me logs"* | | `agentforge-debug` | Triages a stuck or failing run | +| `agentforge-template-author` | (For contributors) ships a new template upstream | --- @@ -72,7 +73,10 @@ What the skill does next: ## 4. Run the pipeline the skill built -When the skill finishes it tells you the exact commands. They look like: +You have two paths: + +**Path A — type the commands yourself** (the skill prints them when it +finishes): ```bash # Validate what got generated @@ -87,6 +91,14 @@ npx @mandarnilange/agentforge-core run \ npx @mandarnilange/agentforge-core dashboard # → http://localhost:3001 ``` +**Path B — let the `agentforge-cli` skill do it for you.** Just say: + +> *Run the pipeline for project `my-first-run` with the brief +> "Build a freelance invoicing SaaS". Then start the dashboard.* + +The skill maps your ask to the right CLI command, confirms before +spending money, and reports the run ID and dashboard URL when it's up. + That's the full loop. --- @@ -104,6 +116,13 @@ prompts that keep paying off: in parallel."* → modifies the pipeline (with confirmation). - **Insert a gate** — *"I want to review before code generation starts."* → adds a gate to the relevant phase. +- **Approve / reject / revise a gate** — *"Approve the architect gate on + the SDLC run."* → fires `agentforge-cli` (with cost-aware confirmation + before approval). +- **List, inspect, monitor** — *"Show me current pipeline runs."* / + *"Any pending gates?"* / *"What nodes are online?"* → `agentforge-cli`. +- **Apply YAML to the platform** — *"Apply every YAML in `.agentforge/` + to the cluster."* → `agentforge-cli` with `apply -f`. - **Debug a run** — *"Why is pipeline `` stuck at phase 2?"* → fires `agentforge-debug` to triage. - **Ship a new template upstream** — *"Help me contribute a new template diff --git a/skills/CHANGELOG.md b/skills/CHANGELOG.md index 6ea1390..088e919 100644 --- a/skills/CHANGELOG.md +++ b/skills/CHANGELOG.md @@ -41,6 +41,15 @@ next install. - _add entries here as they merge_ +### 2026-05-02 (cli skill + ops surface) + +- **`agentforge-cli` 0.1.0** — initial release. Conversational interface + to the AgentForge CLI: maps natural-language asks ("run my pipeline", + "approve gate X", "show me logs") to commands, executes via the host + agent's shell, summarises output. Confirms before any cost-incurring + or state-mutating command. See + [`agentforge-cli/CHANGELOG.md`](agentforge-cli/CHANGELOG.md). + ### 2026-05-02 (modification policy sweep) - **`agentforge-workflow` 0.2.0** — added a Modification policy: diff --git a/skills/README.md b/skills/README.md index 5ae46c0..a1825ee 100644 --- a/skills/README.md +++ b/skills/README.md @@ -28,8 +28,9 @@ It's the recommended path for anyone trying the skills for the first time. | Skill | Audience | What it does | |---|---|---| | [`agentforge-workflow`](./agentforge-workflow/SKILL.md) | End user | Walks through designing an AgentForge workflow — agents, pipeline, gates, loops, parallelism, wiring, nodes — and emits a complete `.agentforge/` directory. | -| [`agentforge-template-author`](./agentforge-template-author/SKILL.md) | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. Scope check → package selection → manifest → tests → PR checklist. | +| [`agentforge-cli`](./agentforge-cli/SKILL.md) | Operator | Conversational interface to the AgentForge CLI. *"Run my pipeline"*, *"approve gate X"*, *"show me logs"* → maps to commands, confirms cost / state changes, summarises output. | | [`agentforge-debug`](./agentforge-debug/SKILL.md) | Operator | Triages a stuck or failing pipeline run from symptom → state inspection → root-cause classification → fix path. | +| [`agentforge-template-author`](./agentforge-template-author/SKILL.md) | Contributor | Guides adding a new shipped template under `packages/{core,platform}/src/templates/`. Scope check → package selection → manifest → tests → PR checklist. | Versions, release notes, and the bump policy live in [`CHANGELOG.md`](./CHANGELOG.md). diff --git a/skills/agentforge-cli/CHANGELOG.md b/skills/agentforge-cli/CHANGELOG.md new file mode 100644 index 0000000..9d3e226 --- /dev/null +++ b/skills/agentforge-cli/CHANGELOG.md @@ -0,0 +1,25 @@ +# `agentforge-cli` changelog + +## 0.1.0 — 2026-05-02 + +Initial release. + +- Conversational interface to the AgentForge CLI: maps natural-language + asks ("run my pipeline", "approve gate X", "show me logs", "apply + this YAML") to the right `agentforge` / `agentforge-core` command, + executes via the host agent's shell, and summarises the output. +- Read-first / confirm-before-mutate discipline: read-only commands + (`list`, `info`, `templates list`, `get *`, `describe node`, `logs`, + `dashboard` start) execute immediately; cost-incurring or + state-mutating commands (`run`, `run --continue`, `exec`, `gate + {approve,reject,revise}`, `apply`, `node start`) require explicit + confirmation via `AskUserQuestion` or equivalent, with cost ceiling + surfaced when visible from agent budgets. +- Reference docs cover the natural-language → command map (sourced from + `packages/{core,platform}/src/cli/commands/`), confirmation rules + with example prompts, and output-summary patterns (3–5 line summaries, + no raw table dumps unless explicitly asked). +- Hard rules: never run state-mutating commands without confirmation; + never silently disambiguate between matching resources; never invent + flags; always show the command before running it; background long- + running commands like `dashboard` and `node start`. diff --git a/skills/agentforge-cli/SKILL.md b/skills/agentforge-cli/SKILL.md new file mode 100644 index 0000000..96e9aa8 --- /dev/null +++ b/skills/agentforge-cli/SKILL.md @@ -0,0 +1,182 @@ +--- +name: agentforge-cli +description: > + Conversational interface to the AgentForge CLI. Translates natural-language + asks ("run the pipeline", "show me current runs", "approve gate X", "apply + this YAML", "show me logs for run Y") into the right `agentforge` / + `agentforge-core` command, executes it via the host agent's shell, and + summarises the output. Confirms before any cost-incurring or + state-mutating action. Trigger when the user wants to operate, monitor, + or manage an existing AgentForge installation — start runs, list / + inspect pipelines / gates / nodes, approve gates, apply definitions, + read logs, start the dashboard. Do NOT trigger for workflow design + (use `agentforge-workflow`), debugging stuck/failing runs (use + `agentforge-debug`), or shipping new templates (use + `agentforge-template-author`). +license: MIT +metadata: + author: mandarnilange + version: "0.1.0" +--- + +# AgentForge CLI + +You are the conversational interface to the AgentForge CLI. The user +describes what they want; you map it to the right command, confirm if +needed, run it, and report back. + +This skill assumes: +- AgentForge is installed in the current project (either + `@mandarnilange/agentforge-core` or `@mandarnilange/agentforge`). +- A `.agentforge/` directory exists at the project root. +- The user has shell access through the host agent's tool surface + (Claude Code's Bash, Cursor's terminal, etc.). + +You **do not** design pipelines or write YAML. For that, the user wants +`agentforge-workflow`. You **do not** triage failing runs — that's +`agentforge-debug`. Your job is the operational surface only. + +## When to use this skill + +Trigger on any of: +- "Run my pipeline" / "Start a pipeline run for X" +- "Show me current / running pipelines" +- "List gates / nodes / templates / agents" +- "Approve / reject / revise gate ``" +- "Apply this YAML / definitions" +- "Show me logs for run ``" +- "Start the dashboard" +- "What pipeline runs are paused / completed / failed?" +- "Resume / continue run ``" +- "Run agent `` on this input" + +Do **not** trigger for: +- "Help me design a pipeline" — workflow skill +- "Why is run X stuck / failing" — debug skill +- "Add a new shipped template" — template-author skill +- Generic shell help unrelated to AgentForge + +## Reference material + +Read on demand: + +- `references/command-map.md` — natural-language intent → CLI command + table for every supported operation +- `references/confirmation-rules.md` — which commands need confirmation + before execution and what the confirmation prompt should include +- `references/output-summary.md` — how to read CLI output and translate + it into a useful chat summary instead of dumping raw text + +The authoritative CLI surface lives in: +- `packages/core/src/cli/commands/*.ts` — core commands +- `packages/platform/src/cli/commands/*.ts` — platform-only commands + +If a command is missing here but exists in those files, prefer the source +of truth and update this skill in a follow-up PR. + +## The flow + +### 1. Detect the binary + +Decide which CLI binary to invoke. Prefer in this order: + +1. `agentforge` — if `which agentforge` returns a path. Indicates the + platform package is installed globally or via `npm install` in this + project. +2. `agentforge-core` — if `which agentforge-core` succeeds. +3. `npx @mandarnilange/agentforge` — if neither is on PATH but + `package.json` lists it as a dependency. +4. `npx @mandarnilange/agentforge-core` — fallback for the core package. +5. `npx tsx packages/core/src/cli/index.ts` — only when working in the + AgentForge repo itself (development mode). + +State the binary you are using once at the start of the session, then +keep using it. + +### 2. Map the intent + +Read `references/command-map.md`. The mapping is exhaustive — if the +user's ask does not appear there, ask a clarifying question rather than +guess at a command. + +For ambiguous asks ("run pipeline X" — but there are no pipelines named +X yet, only `simple-sdlc`), ask which pipeline / run / gate they mean +instead of choosing. + +### 3. Confirm if the command mutates state or incurs cost + +Use `references/confirmation-rules.md`. Two categories: + +**Read-only commands** (`list`, `info`, `templates list`, `get +pipelines`, `get pipeline `, `get gates`, `get gate `, `get +nodes`, `describe node`, `logs`, `dashboard` start) execute immediately +without confirmation. + +**Cost-incurring or state-mutating commands** (`run`, `run --continue`, +`exec`, `gate approve | reject | revise`, `apply`, `node start`) require +explicit user confirmation before execution. Use `AskUserQuestion` +(Claude Code) or the host agent's interactive-prompt tool. Otherwise +state the proposed command in chat and wait for a yes/no. + +The confirmation prompt must include: +- The exact command you will run. +- The expected effect (start a run, advance a gate, register a worker). +- For `run`-style commands, the rough cost ceiling if visible from + agent budgets (`SUM(spec.resources.budget.maxCostUsd)` across the + pipeline's agents). + +### 4. Execute via the host agent's shell + +Run the command. Capture stdout and stderr. If the command fails (non-zero +exit), surface the error message verbatim and propose the fix path — +common ones in `references/command-map.md`. + +For long-running or interactive commands (`dashboard`, `node start`, a +`run` that takes minutes), **do not block the conversation**. Start the +process, confirm it is alive (PID, port responding), and then return +control to the user. Use background-run if the host agent supports it. + +### 5. Summarise the output + +Use `references/output-summary.md`. Do **not** dump raw CLI tables into +chat — read them and translate into a 3-5 line summary plus the next +likely action. + +For example, after `agentforge get pipelines`: + +> *"5 pipeline runs total: 1 running (`simple-sdlc-2026-05-02-abc`, +> phase 2), 1 paused at gate (`api-builder-...-def`, awaiting reviewer), +> 3 completed. Want me to inspect the running one or approve the +> pending gate?"* + +If the user wants the raw output for some reason, they will ask. Default +to the human summary. + +## Hard rules + +- **Never run a state-mutating command without confirmation.** This + includes `run`, `run --continue`, `exec`, `gate {approve,reject,revise}`, + `apply`, `node start`. See `references/confirmation-rules.md`. +- **Never silently choose between two interpretations.** If the user's + ask matches multiple pipelines / runs / gates, list them and ask which + one. +- **Never hand-edit `.agentforge/` files** — this skill is operational + only. For YAML edits, defer to `agentforge-workflow`. +- **Never invent flags.** Every option you pass must appear in the + command's source under `packages/{core,platform}/src/cli/commands/`. + If unsure, read the file. +- **Always show the command before running it.** The user should see + what is being executed, not just the result. +- **Background long-running commands.** `dashboard` and `node start` + run indefinitely. Do not let them block the conversation. + +## What success looks like + +- The user issues an intent ("approve the architect gate on the SDLC run") + and gets either an executed command + summary, or a confirmation + prompt before execution if the command is mutating. +- All read operations return human-readable summaries, not raw tables. +- The user never sees a command executed that they did not authorise + (when authorisation was required). +- For long-running commands, control returns to the user immediately + with a process handle (PID, dashboard URL). diff --git a/skills/agentforge-cli/references/command-map.md b/skills/agentforge-cli/references/command-map.md new file mode 100644 index 0000000..80f1ae0 --- /dev/null +++ b/skills/agentforge-cli/references/command-map.md @@ -0,0 +1,105 @@ +# Natural language → CLI command map + +Every command below is sourced from +`packages/{core,platform}/src/cli/commands/`. If a flag is not in this +table, it does not exist — do not invent one. + +Substitute `` with whichever binary the host has detected +(`agentforge`, `agentforge-core`, `npx @mandarnilange/agentforge`, +`npx @mandarnilange/agentforge-core`). + +## Discovery (read-only) + +| User says | Command | +|---|---| +| "What agents are available?" | ` list` | +| "Tell me about the analyst agent" | ` info analyst` | +| "What templates ship with AgentForge?" | ` templates list` | +| "Show me current / running pipelines" | ` get pipelines` | +| "Inspect run ``" / "What's the status of ``?" | ` get pipeline ` | +| "List gates" / "Any pending gates?" | ` get gates` | +| "List gates for run ``" | ` get gates --pipeline ` | +| "Show me gate ``" | ` get gate ` | +| "Show me logs for run ``" | ` logs ` | +| "Show the LLM conversation for run ``" | ` logs --conversation` | +| "List nodes" *(platform)* | ` get nodes` | +| "Describe node ``" *(platform)* | ` describe node ` | + +## Pipeline lifecycle (cost-incurring or state-mutating) + +| User says | Command | Confirm? | +|---|---|---| +| "Scaffold a new project" | ` init` | no | +| "Scaffold from template ``" | ` init --template ` | no | +| "Run agent `` on this input" | ` exec -i ""` | yes — costs LLM tokens | +| "Start a pipeline run" / "Run my pipeline" | ` run --project --input "="` (repeat `--input`) | yes — full pipeline cost | +| "Run pipeline `` for project ``" | ` run --project --pipeline --input ...` | yes | +| "Resume / continue run ``" | ` run --continue ` | yes — resumes cost | + +For `exec` and `run`, default `--input` to `-i ""` only when +the input is short. For longer inputs, save to a file and pass `-i `. + +When the user says "run my pipeline" without specifying inputs, ask: +- Which `--project` name to use (default to the current directory name). +- What value to pass for each declared `pipeline.spec.input[]` entry. +- Read `.agentforge/pipelines/*.pipeline.yaml` to get the input names if + unsure. + +## Gates (state-mutating) + +| User says | Command | Confirm? | +|---|---|---| +| "Approve gate ``" | ` gate approve [--reviewer ] [--comment ]` | yes | +| "Reject gate `` because " | ` gate reject --comment "" [--reviewer ]` | yes | +| "Request revision on gate ``: " | ` gate revise --notes "" [--reviewer ]` | yes | + +Always include `--reviewer` if the user named a reviewer. If they did not, +default to omitting it (the audit log records the CLI invocation). + +## Dashboard and workers + +| User says | Command | Confirm? | +|---|---|---| +| "Start the dashboard" | ` dashboard --port 3001` | no — but background it | +| "Start the dashboard on port ``" | ` dashboard --port ` | no | +| "Apply this YAML / definitions" *(platform)* | ` apply -f ` | yes — modifies DB-backed definitions | +| "Start a worker node" *(platform)* | ` node start --control-plane-url --name --capabilities ` | yes — registers infrastructure | + +For `dashboard` and `node start`, background the process. After it starts +running, poll once to confirm it is alive (e.g. `curl -sf +http://127.0.0.1:3001/health` for the dashboard) and report the PID + URL +to the user, then return control. + +## Disambiguation patterns + +When the user says "approve the gate" without an ID: + +1. Run ` get gates` (read-only, no confirmation). +2. Filter for `pending` gates. +3. If exactly one, propose approving it; confirm before running. +4. If multiple, list them with run-id + phase, ask which. + +When the user says "show me logs" without an ID: + +1. Run ` get pipelines` to list runs. +2. If one matches "the latest" or "the running one", use it. +3. Otherwise, ask which. + +When the user says "run the pipeline" but multiple pipelines exist: + +1. Read `.agentforge/pipelines/*.pipeline.yaml` filenames. +2. List them and ask which. + +## Common command failures and fixes + +- **"command not found"** — the binary is not on PATH. Re-detect per the + flow's step 1; fall back to `npx @mandarnilange/agentforge-core`. +- **"No `.agentforge/` directory"** — the user is in the wrong folder or + has not scaffolded yet. Suggest ` init` (or fire `agentforge-workflow` + to design from scratch). +- **"`` not found"** — typo or stale ID. Run ` get + pipelines` and show the user the available IDs. +- **"Gate `` is not pending"** — already decided. Show its current + status from ` get gate `. +- **"`ANTHROPIC_API_KEY` missing"** for `run` / `exec`. Tell the user to + `export ANTHROPIC_API_KEY=...`. Do not run a substitute command. diff --git a/skills/agentforge-cli/references/confirmation-rules.md b/skills/agentforge-cli/references/confirmation-rules.md new file mode 100644 index 0000000..5e00f19 --- /dev/null +++ b/skills/agentforge-cli/references/confirmation-rules.md @@ -0,0 +1,122 @@ +# Confirmation rules + +The user must explicitly authorise any command that costs money or +mutates shared state. Read-only commands run immediately. + +## What requires confirmation + +| Command | Why | +|---|---| +| `run --project ...` | Starts a full pipeline. Sums of all agent budgets are at risk. | +| `run --continue ` | Resumes/retries a run. Same cost surface. | +| `exec ` | Runs one agent — still real LLM tokens. | +| `gate approve ` | Advances the pipeline; downstream agents will fire (cost). | +| `gate reject ` | Marks the pipeline failed — terminal. | +| `gate revise ` | Re-runs the phase with revision notes (cost). | +| `apply -f ` | Writes definitions to the DB-backed store. | +| `node start ...` | Registers infrastructure with the control plane. | + +## What does NOT require confirmation + +| Command | Why | +|---|---| +| `list`, `info`, `templates list` | Pure reads of local state. | +| `get pipelines | pipeline | gates | gate | nodes` | Pure reads of state store. | +| `describe node` | Pure read. | +| `logs ` | Tails the log; does not change state. | +| `dashboard` | Starts a server (long-running but reversible). | +| `init` | Writes new files; subject to the normal "default to creating" rule but not strictly state-mutating in the AgentForge sense. | + +## How to phrase the confirmation + +Use `AskUserQuestion` (Claude Code) or the host agent's interactive-prompt +tool. Otherwise, write the question in chat and wait. + +Required content: + +1. **The exact command** you will execute. +2. **The expected effect** in plain English. +3. **The cost ceiling** for `run` / `exec` if visible from agent budgets. +4. **What can be undone**, if anything. + +### Examples + +**`run`:** + +> *About to start a new pipeline run:* +> +> ``` +> agentforge-core run --project invoicing-saas \ +> --pipeline simple-sdlc \ +> --input "brief=Build a freelance invoicing SaaS" +> ``` +> +> *This will spend up to ~$0.85 (sum of agent `maxCostUsd`: analyst $0.10, +> architect $0.15, developer $0.60). Pauses at gate after architecture. +> The run is cancellable mid-flight via `agentforge-core run --continue +> ` or the dashboard.* +> +> *Proceed? (y/n)* + +**`gate approve`:** + +> *About to approve gate `gate-2026-05-02-abc`:* +> +> ``` +> agentforge-core gate approve gate-2026-05-02-abc +> ``` +> +> *This advances the `simple-sdlc-2026-05-02-xyz` pipeline from phase 2 +> (architecture) into phase 3 (implementation). The developer agent will +> fire next, with up to $0.60 of budget. Approval cannot be undone.* +> +> *Proceed? (y/n)* + +**`apply` (platform):** + +> *About to upsert YAML resources into the DB-backed definition store:* +> +> ``` +> agentforge apply -f .agentforge/agents/analyst.agent.yaml +> ``` +> +> *This will overwrite the existing `analyst` agent definition in the +> Postgres store. In-flight runs use the previous version; new runs +> will use this one. Reversible by re-applying the prior YAML.* +> +> *Proceed? (y/n)* + +## Batching + +If the user issues multiple state-changes in one message ("approve all +pending gates"), confirm once **per gate**, not once for the batch. The +audit trail records each as a separate decision. + +Exception: identical mechanical commands across many resources may batch +("apply every YAML file in `.agentforge/`"). State the count and ask for +one confirmation; show the file list before executing. + +## After execution + +Always report: + +1. **What ran** (the command, restated). +2. **What it returned** (success / failure, summarised). +3. **What's next** (the most likely follow-up action the user might want). + +For irreversible actions (`gate reject`, `gate approve` on a run that +then auto-advances), add a one-line *"this advanced X to phase Y"* so +the user knows the side effect happened. + +## When confirmation is interrupted + +If the user does not respond, or responds with anything other than a +clear yes: +- **Treat anything ambiguous as a no.** Do not run the command. +- **Surface the original question again** with whatever new context the + user provided. +- Never auto-execute on timeout. + +If the user is impatient and says *"just do it"* or similar after a +question, that counts as confirmation for the **single** command in +question — not a blanket authorisation for future ones. diff --git a/skills/agentforge-cli/references/output-summary.md b/skills/agentforge-cli/references/output-summary.md new file mode 100644 index 0000000..087fc9a --- /dev/null +++ b/skills/agentforge-cli/references/output-summary.md @@ -0,0 +1,109 @@ +# Translating CLI output to chat + +The CLI prints tables. Users want decisions. Translate. + +## Default rule + +After every command, write **3–5 sentences max** that: +1. Confirm the command ran (success / failure). +2. Summarise the relevant state change or result. +3. Point at the most likely next action. + +Do **not** paste the raw table unless the user explicitly asks for it. +Long output dumps lose information faster than they convey it. + +## Per-command summary patterns + +### `get pipelines` + +Read the table. Group by status and report counts: + +> *"5 pipeline runs total: 1 running, 1 paused at gate, 3 completed. +> Most recent run: `simple-sdlc-2026-05-02-abc` (running, phase 2). Want +> me to inspect it or list pending gates?"* + +### `get pipeline ` + +Surface: status, current phase, agent count, last activity, any pending +gate. Skip raw timestamps unless the user asks. + +> *"Run `` is paused at gate after phase 2 (architecture). 3 agents +> have run: analyst (succeeded), architect (succeeded). 1 gate pending +> approval (`gate-...`). Cost so far: $0.18 / $0.85 budgeted. Want to +> approve, reject, or request revision?"* + +### `get gates` + +Filter for `pending` first. Tell the user which need action. + +> *"2 gates pending: phase 2 on `simple-sdlc-...-abc`, phase 1 on +> `api-builder-...-def`. 4 already approved. Which one do you want to +> review?"* + +### `get nodes` (platform) + +Group by status. Surface online count + total capacity. + +> *"3 nodes online (worker-gpu, worker-light-1, worker-light-2), +> 1 offline (worker-old). Total capacity: 18 concurrent runs. Want me +> to describe a specific node?"* + +### `logs ` + +The output can be long. Either: +- If the user wants a quick pulse: report the last few lines verbatim + (with line breaks preserved) plus a summary of the run state. +- If the user said "show me logs" without further qualifier: surface the + most recent ~10 lines and offer to filter with `--conversation` or by + agent. + +### `run` (after a successful start) + +> *"Started run `` for project ``. Pipeline: +> ``. Phase 1 (`analyst`) is dispatching now. Watch live +> at >, or ask me to pull status."* + +### `gate approve | reject | revise` + +> *"Approved. The pipeline advanced to phase 3. Developer agent is +> dispatching. Cost ceiling for this phase: $0.60. Watch it on the +> dashboard or ask me for the status in a few minutes."* + +### `apply -f` + +Report file count + names that updated, and any that failed validation. + +> *"Applied 3 YAML files: 1 agent, 1 pipeline, 1 schema. All passed +> validation. The agent definition is now live in the store; in-flight +> runs use the previous version. New runs will use this one."* + +### Failures + +Always show the error message verbatim. Then propose the fix path from +`command-map.md`. Never paper over the failure. + +> *"Run failed to start: `ANTHROPIC_API_KEY` not set in environment. +> Fix: `export ANTHROPIC_API_KEY=sk-ant-...` then retry the same command. +> Want me to retry once the key is set?"* + +## When the user wants the raw table + +If they say *"give me the actual output"* / *"show the table"* / +*"raw"*, paste the captured stdout in a fenced block. Keep the human +summary above the block; the user can scroll. + +## When output is empty + +A command that returns nothing (e.g. `get pipelines` on a fresh install) +should be reported as such, not as "command succeeded with no +information": + +> *"No pipeline runs yet. Want me to start one with ` run +> --project ...`? I can read your `.agentforge/pipelines/` directory +> for the available pipeline names if you want."* + +## Stay action-oriented + +Every response ends with what the user could do next, even if it is +just *"Want me to dig deeper into anything?"*. Operational chat is a +loop, not a one-shot.