yaaif-plan-usecase

Files (6)

• SKILL.md
• decomposition.md · references/
• chat-only.md · references/examples/
• chat-to-ambient.md · references/examples/
• desktop-ambient.md · references/examples/
• plan-template.md · references/

SKILL.md (first lines)

# Plan and implement a YAA\F use case

Turn a use-case description into an **approved install plan**, then implement it
by delegating to existing plugin skills and `yaaif_*` bridge tools. Do not jump
straight to create tools before the plan is approved.

```
Task Progress:
- [ ] 1. Auth + catalog snapshot
- [ ] 2. Capture intent (interview if vague)
- [ ] 3. Decompose (chat / ambient / desktop / MCP / agents)
- [ ] 4. Write plan file + stop for approval
- [ ] 5. Optional dry-run (yaaif_plan_dry_run) with local_tool_names
- [ ] 6. Save execution checklist (yaaif_plan_execution_save); include yaaif_skill_tools_check before skill create
- [ ] 7. Execute (MCP → API key bind → agents → approvals → ambient → skills → map → desktop)
- [ ] 8. On failure: yaaif_plan_execution_resume and continue
- [ ] 9. Verify (yaaif_plan_verify including local_tool_names) + hand off
```

## Prerequisites

1. `yaaif-auth` (session + non-empty tenant)
2. Read [references/decomposition.md](references/decomposition.md)
3. Emit plans using [references/plan-template.md](references/plan-template.md)
4. Prefer examples in [references/examples/](references/examples/) when shapes match

## Phase A — Propose (always first)

### 1. Auth + catalog

- Ensure auth via `yaaif-auth`
- Call `yaaif_catalog_overview` (includes `local_tools` when reachable)
- Use targeted list tools when needed: `yaaif_agent_list`, `yaaif_skill_list`,
  `yaaif_mcp_tools_list`, `yaaif_ambient_workflow_list`,
  `yaaif_approval_strategies_list`, `yaaif_desktop_workers_list`,
  `yaaif_local_tools_list` (exact platform tool names for skill frontmatter)
- Prefer **reuse** of existing agents / skills / MCP tools / workflows when names
  or purposes clearly overlap
- For chat→ambient skills, resolve real local names via
  `list_ambient_workflows` / `trigger_ambient_workflow` (local tools), not invented aliases
- For file-heavy use cases, include `files_list` / `load_artifacts` / `file_load_context` (and note
  `yaaif_dev_session_ensure` for Cursor authoring; artifact name + version dual identity)

### 2. Capture intent

If the use case is clear, extract fields and ask **at most one** clarifying
question for the biggest gap.

If the use case is **vague** (missing trigger, systems, or HITL), use
**interview mode** — ask these as a short structured list (one message), then
continue once answered:

1. Outcome — what should be true when done?
2. Triggers — chat / schedule / webhook / batch / manual?
3. HITL — any human approval gate? who approves (email)?
4. Systems — SAP OData, SAP GUI, custom APIs, none?
5. Desktop — local GUI / OS automation needed?
6. Chat role — triage only, or chat starts the long-running work?

Confirm in 1–2 sentences, then continue.

### 3. Decompose

Apply [references/decomposition.md](references/decomposition.md). Produce a
component list covering only what is needed:

| Component | When |
|-----------|------|
| MCP tools | Domain APIs missing from catalog |
| Chat agent (`agent_type: skills`) | Interactive chat skills |
| Workflow agent (`agent_type: workflow`) | Host for ambient |
| Desktop agent (`agent_type: desktop`) | Desktop skills need a home |
| Ambient agent + workflow | Async / batch / schedule / HITL graphs |
| Approval strategy | Ambient pattern Linear+approval (or any `approval` node) |
| Chat skill | Triage, Q&A, light tools |
| Chat orchestration skill | Chat → `trigger_ambient_workflow` |
| Desktop skill | SAP GUI / local UI (`classification: desktop`) |
| Desktop worker mapping | After desktop skill exists — map workers |
| Ambient step skill | Only when a graph step needs a dedicated skill |

State the ambient pattern briefly when ambient is in scope (Linear default;
see `yaaif-create-ambient` patterns).

### 4. Write plan + stop

1. Write `yaaif-plans/<slug>-plan.md` in the **user workspace** using the plan
   template (slug = short hyphen-case domain, e.g. `invoice-clearance`).
2. Summarize the plan in chat (components + install order).
3. **Stop.** Ask for explicit approval (`approve`, `go ahead`, or equivalent).
   Offer optional **`dry-run`** before mutate.
4. Do **not** call create/deploy/map/enable tools until the user approves
   (dry-run via `yaaif_plan_dry_run` is allowed — it does not mutate).
5. If the user requests changes, revise the plan file (or `yaaif_agent_update`
   after execute) and stop again.

### 5. Dry-run (optional / when user asks)

Build the intended tool call list from the plan and call `yaaif_plan_dry_run`
with `actions` (+ `verify_catalog: true` and `expected` names from the plan).
Show the dry-run result; wait again for execute approval if not already granted.

## Phase B — Execute (only after approval)

Immediately after approval, persist a platform **Scenario** (Agent Spec) with
`yaaif_agent_spec_create` (slug from the plan, segments from §1–§8 / §10,
architecture slots from §4). Store `spec_id` and the returned `version` as
`spec_version` on the local plan execution (`yaaif_plan_execution_save`). Every subsequent create tool must pass
`spec_id` + `slot_key` so agents, skills, workflows, and MCP servers bind
automatically. Those objects are created from the spec; later changes go
through the spec slot (and `workflow_design` for graphs), not as parallel
catalog edits. Use the `yaaif-scenario` skill / `yaaif_agent_spec_*` tools to
maintain the spec. Use `yaaif_agent_spec_bind` if a reused existing entity
needs mapping. After execute, preview catalog sync with
`yaaif_agent_spec_sync_preview`, explicitly apply it with the current version,
record passing evidence for every `must` requirement, refresh readiness, and
only then publish and transition to `active`. `yaaif_plan_execution_resume`
refreshes readiness/version and halts for conflicts or failed evidence. Later object edits in
Cursor stay on the spec automatically; use `/yaaif-sync-scenario` to pull or
push the full inventory.

From yaaif/cursor-plugin, Apache-2.0.

More from yaaif/cursor-plugin