docs: implementation plan for the mcp server, and creation tools in the spec

docs/superpowers/specs/2026-09-08-mcp-server-design.md

@@ -30,8 +30,13 @@ Out of scope, deliberately:
 - **An approval queue.** Writes are gated by an explicit scope, not by a
   human-in-the-loop workflow. A pending-action subsystem is a real feature and
   would roughly double this one.
-- **Agent-authored workflows.** Generating and saving a workflow from natural
-  language is compelling and separable. Not here.
+- **Editing or deleting existing workflows, steps and monitors.** Creation is
+  in scope; changing or removing something a human already made is not. An agent
+  that can only add leaves every existing definition intact, and an unwanted new
+  one is deleted in a click.
+- **Secret-referencing steps.** A created step may not declare `secret_refs`.
+  Composing a script around a secret reference is how a credential ends up
+  echoed into a log, and the human step editor already does this safely.
 
 ## Current state
 
@@ -224,6 +229,9 @@ write.
 | `apply_updates` | `servers:write` | yes |
 | `update_agent` | `servers:write` | yes |
 | `assign_key` | `keys:write` | yes |
+| `create_step` | `workflows:write` | yes |
+| `create_workflow` | `workflows:write` | yes |
+| `create_monitor` | `monitors:write` | yes |
 
 Rules every tool follows:
 
@@ -242,12 +250,41 @@ Rules every tool follows:
   many it would have touched. Cheap insurance against a mis-parsed selector
   reaching the whole fleet.
 
+### Creation tools
+
+`create_step`, `create_workflow` and `create_monitor` let an agent build the
+thing it is about to propose, rather than describing a script in prose that a
+human then retypes. They are the tools that make the surface generative instead
+of merely observational, and they are also the ones most able to surprise
+someone, so they carry extra rules on top of the ordinary write gates:
+
+- **Creation only.** No update and no delete tool exists. An agent may add a
+  definition; it may never alter or remove one a human wrote.
+- **Nothing is armed on creation.** `create_workflow` refuses a `schedule`, and
+  `create_monitor` sets `enabled` false. A created definition sits inert until a
+  human enables it, so creating and acting stay two decisions. An agent that
+  wants to run what it just made calls `run_workflow`, which is separately
+  gated, separately audited, and subject to the fan-out guard.
+- **No secret references.** `create_step` rejects a non-empty `secret_refs`.
+- **Marked as agent-authored.** `models.WorkflowStep` already carries a `Source`
+  field; created steps set it to `mcp`, so the UI can badge them and a human can
+  tell at a glance what a model wrote. Workflows and monitors get the same
+  treatment through their audit event rather than a new field.
+- **Script validation.** `create_step` runs the same parse and scan the existing
+  step-create route runs (`services.CreateStep` already does this) — an agent
+  gets no laxer a path than the UI.
+
 ## Audit
 
 Every tool call writes an audit event through `services.LogEvent`, reads
 included. The point of an agent-facing surface is being able to reconstruct
 afterwards what the agent looked at, not only what it changed.
 
+Creation tools log a distinct event type, `mcp.created`, naming what was made
+and its ID. A generic tool-call row buried among reads is not enough for the
+question a human will actually ask, which is "what has this agent added to my
+instance".
+
 Event type `mcp.tool_call`; actor is the token name, as REST token actions
 already record; detail is the tool name, a compact argument summary, and the
 number of servers affected. Failures record `mcp.tool_denied` with the gate that