chore: include documentation for agent builder

Author: rahulrajesh-klarity

docs/docs.json

@@ -59,7 +59,7 @@
               "guides/transformation-thesis",
               "guides/chain-with-connectors",
               "guides/deep-research",
-              "guides/code-and-agents"
+              "guides/agent-builder"
             ]
           },
           {
@@ -88,7 +88,8 @@
               "tools/process-index",
               "tools/observations-and-changes",
               "tools/artifacts",
-              "tools/workspace"
+              "tools/workspace",
+              "tools/agent-builder"
             ]
           }
         ]

docs/guides.mdx

@@ -25,7 +25,7 @@ Each guide is a recipe: an example prompt, the tool chain the assistant should r
   <Card title="Combine with deep research" icon="magnifying-glass-plus" href="/guides/deep-research">
     Your reality vs. external benchmarks — gap analysis with citations on both sides.
   </Card>
-  <Card title="Build agents, skills, and code" icon="robot" href="/guides/code-and-agents">
-    Ground Skills, Custom GPTs, and code generation in your real processes.
+  <Card title="Build an agent with Agent Builder" icon="wand-magic-sparkles" href="/guides/agent-builder">
+    A guided, evidence-grounded workflow from "what should we automate?" to a shipped skill or spec.
   </Card>
 </Columns>

docs/guides/agent-builder.mdx

@@ -0,0 +1,64 @@
+---
+title: "Build an agent with Agent Builder"
+description: "A guided, evidence-grounded workflow that takes you from 'what should we automate?' to a shipped skill or a developer-ready spec."
+icon: "wand-magic-sparkles"
+---
+
+Agent Builder is a guided workflow for turning how your organization actually works into automations. Instead of guessing at what to build, the assistant walks you through a lifecycle — scope an objective, map your current state, diagnose the highest-leverage opportunities, propose a prioritized plan, and then either ship a skill or hand a developer a ready-to-build spec. Every recommendation is grounded in real process evidence from your workspace.
+
+You don't need to memorize the steps. Agent Builder is self-guiding: you ask for the instructions once, and it orients you, figures out where you are, and tells you what to run next.
+
+<Note>
+  Agent Builder is gated per workspace. If the tools below aren't available, ask your Klarity admin to enable agent development for your workspace.
+</Note>
+
+## Start here
+
+Ask your assistant to **get the Agent Builder instructions**, or just tell it what you're trying to do ("help me figure out what to automate in procurement"). Under the hood this calls `get_agent_builder_instructions` with the `begin` step — the orientation step that resolves your workspace, reads your intent, and routes you into the right part of the lifecycle.
+
+From there the assistant self-navigates. It fetches the instructions for each step as it reaches it and pulls in supporting resources on demand with `get_agent_builder_resource`. You stay in the loop at every decision point.
+
+## The lifecycle
+
+Agent Builder follows one lifecycle with two entry paths.
+
+| Step | What happens |
+|---|---|
+| **Objective** | Capture the scope of the project — what you're trying to improve and why. |
+| **Current state** | Map the relevant part of your workspace from real process evidence and confirm the readout with you. |
+| **Diagnose** | Score and rank the automation opportunities, each tied to the kind of artifact it would become. |
+| **Propose** | Present a prioritized plan you review and pick from, then route each choice to the right next step. |
+| **Spec** | For a buildable recommendation, produce a developer-ready specification to hand off. |
+
+There's also a **skill track** — when a recommendation is best expressed as a skill, Agent Builder walks you through discovering, outlining, and building it end-to-end. And a read-only **home** view answers "where am I?" and "what's next?" at any point.
+
+## Two ways in
+
+<Steps>
+  <Step title="Build skills">
+    You already know you want to build something. Agent Builder takes you into the skill track — discover candidate skills, outline the one you pick, and build the bundle.
+  </Step>
+  <Step title="Explore and decide">
+    You're not sure what to build yet. Agent Builder walks the full explore chain — objective → current state → diagnose → propose — and only then routes you to a spec or a skill build, grounded in what it found.
+  </Step>
+</Steps>
+
+## What to expect
+
+<Steps>
+  <Step title="It asks before it assumes">
+    When there's a finite set of choices, the assistant presents them and lets you pick rather than guessing. Human checkpoints are built into the workflow by design.
+  </Step>
+  <Step title="No recommendation without evidence">
+    Every diagnosis and proposal is backed by real process data from your workspace. If the evidence isn't there, Agent Builder won't invent it.
+  </Step>
+  <Step title="Your work stays with you">
+    Project artifacts and intermediate state live in a local `./klarity/` project directory on your machine — not in the Klarity backend. You can revisit or resume a project across sessions, and the assistant reconciles where you are against your saved progress.
+  </Step>
+</Steps>
+
+## Watch for
+
+- **Come back after the plan.** The proposal step is interactive — you review and make your picks, then the assistant continues from your selections. Give it your choices before expecting it to build.
+- **One workspace at a time.** Agent Builder resolves the workspace up front. If you work across multiple workspaces, confirm you're in the right one before you start.
+- **Resuming a project.** If you've done work before, start the same way — ask for the instructions. The `begin` step reads your local project state and picks up where you left off instead of starting over.

docs/guides/code-and-agents.mdx

@@ -0,0 +1,64 @@
+---
+title: "Agent Builder"
+description: "Fetch the guided Agent Builder workflow and its supporting resources, step by step."
+icon: "wand-magic-sparkles"
+---
+
+Agent Builder is a guided workflow for turning how an organization works into automations — scope an objective, map current state, diagnose opportunities, propose a plan, then ship a skill or a developer-ready spec. The methodology is served over these two tools rather than shipped in the client, so the assistant fetches each step's instructions as it reaches it.
+
+<Note>
+  These tools are gated by the `enable_agent_development_mcp` workspace setting. They only appear for workspaces where agent development is enabled.
+</Note>
+
+| Tool | When to use |
+|---|---|
+| `get_agent_builder_instructions` | The entry point and the per-step fetcher. Start with `step="begin"` to orient, then fetch each step as the workflow routes to it. |
+| `get_agent_builder_resource` | Pull a supporting resource (reference, primitive, or template) named in a step's manifest — fetched on demand, not up front. |
+
+## `get_agent_builder_instructions`
+
+Fetches one step's instruction body plus the manifest of supporting resources it may draw on.
+
+- **`step`** — the step to fetch. One of: `begin`, `home`, `start`, `objective`, `current_state`, `diagnose`, `propose`, `spec`, `skill_track`, `skill_discovery`, `skill_outline`, `skill_build`.
+
+Returns:
+
+- **`instructions`** — the step's body, with a "Relevant resources" appendix listing the resources you can fetch on demand.
+- **`resource_manifest`** — the same resources as structured `(type, subtype)` pairs. These are **relevance hints**, not required reads — fetch one only when the conversation calls for it.
+
+Always begin with `step="begin"`. The orientation step resolves the workspace, reads the user's intent, and routes into the right part of the lifecycle. There is no `next` field — routing lives in each step's prose, so the workflow self-navigates from `begin` onward.
+
+## `get_agent_builder_resource`
+
+Fetches a single supporting resource named in a step's `resource_manifest`.
+
+- **`type`** — `reference`, `primitive`, or `template`.
+- **`subtype`** — the specific variant. Must be valid for the given `type`; an invalid pairing is rejected.
+
+Returns:
+
+- **`content`** — the resource payload (markdown, HTML, or YAML).
+- **`version`** — the resource version number.
+- **`subtype`** — the resolved subtype.
+
+## The loop
+
+<Steps>
+  <Step title="Orient">
+    Call `get_agent_builder_instructions` with `step="begin"`. Resolve the workspace and let the step route you to the entry point.
+  </Step>
+  <Step title="Walk the lifecycle">
+    Fetch each step's instructions as the workflow reaches it — `objective`, `current_state`, `diagnose`, `propose`, and then `spec` or the skill track. Follow the body's prose to decide what runs next.
+  </Step>
+  <Step title="Pull resources on demand">
+    When a step's manifest names a resource the current work needs, call `get_agent_builder_resource` for that `(type, subtype)`. Don't fetch the whole manifest up front.
+  </Step>
+</Steps>
+
+## Watch for
+
+- **Begin first.** For MCP-only clients with no skills to auto-load, the convention is that the first call is `get_agent_builder_instructions(step="begin")`. Everything else routes from there.
+- **The manifest is a hint.** `resource_manifest` tells you what a step *may* draw on, not what to load. Fetch resources lazily.
+- **Feature-gated.** If these tools aren't present, the workspace doesn't have agent development enabled.
+
+See the [Build an agent with Agent Builder](/guides/agent-builder) guide for the end-to-end walkthrough.

docs/tools/agent-builder.mdx

@@ -17,6 +17,7 @@ Every workflow reduces to: **find the right process(es) → fetch detail → gat
 | [Process observations](/tools/observations-and-changes) | Recent changes, observations, activity timelines, sessions | "What changed?", "what happened?", "why does this run this way?" |
 | [Artifacts](/tools/artifacts) | Document search, content retrieval, in-document text search | The user names a document or recording |
 | [Workspace](/tools/workspace) | List accessible workspaces | Orienting before drilling in |
+| [Agent Builder](/tools/agent-builder) | `get_agent_builder_instructions`, `get_agent_builder_resource` | Building an agent or skill through the guided workflow (gated feature) |
 
 ## Before you call
 

docs/tools/overview.mdx

@@ -7,5 +7,5 @@
       "url": "https://api.klarity.ai/mcp"
     }
   },
-  "contextFileName": "skills/klarity-agent-builder-using-klarity/SKILL.md"
+  "contextFileName": "skills/agent-builder/SKILL.md"
 }

gemini-extension.json

@@ -95,20 +95,9 @@ class KlarityMCPMetadata:
     repository_url="https://github.com/Klarity-AI/klarity-mcp",
     skills=(
         "klarity-process-context-graph",
-        "klarity-agent-builder-using-klarity",
-        "klarity-agent-builder-start",
-        "klarity-agent-builder-home",
-        "klarity-agent-builder-objective",
-        "klarity-agent-builder-current-state",
-        "klarity-agent-builder-diagnose",
-        "klarity-agent-builder-propose",
-        "klarity-agent-builder-spec",
-        "klarity-agent-builder-skill-track",
-        "klarity-agent-builder-skill-discovery",
-        "klarity-agent-builder-skill-outline",
-        "klarity-agent-builder-skill-build",
+        "agent-builder",
     ),
-    gemini_context_skill="klarity-agent-builder-using-klarity",
+    gemini_context_skill="agent-builder",
 )
 
 

klarity_mcp/metadata.py

@@ -0,0 +1,16 @@
+---
+name: agent-builder
+description: Entry point for all Klarity agent-building work. Guides you from "what should we automate?" through scoping, diagnosis, and a plan to a shipped skill or developer-ready spec. The methodology is served from the Klarity Architect MCP — invoke before any response when the user mentions processes, automation, agents, or ops intelligence.
+---
+
+# Agent Builder
+
+This is the single entry point for all Klarity agent-building work. The methodology is served from the Klarity Architect MCP — do not improvise it. Fetch it before doing anything else, and let it route you through the rest of the lifecycle.
+
+1. FIRST, call `get_agent_builder_instructions(step="begin")` and follow it before any other agent-building work. Workspace resolution, the lifecycle model, the two-door gate, and the next-step routing all come from that call.
+2. Follow the returned `instructions` exactly. They include a **resource manifest** — references, primitives, and templates the step may draw on.
+3. For each manifest entry the current work needs, call `get_agent_builder_resource(type=..., subtype=...)` and use the returned content. Fetch on demand — the manifest is a relevance hint, not a required read.
+4. Move through the lifecycle by following each step's prose. There is no `next` field; `begin` routes you to the entry step and each step's instructions say what runs next. Fetch each step (`objective`, `current_state`, `diagnose`, `propose`, `spec`, or the skill track: `skill_track` → `skill_discovery` → `skill_outline` → `skill_build`) as you reach it.
+5. Write all durable outputs to the local project directory as the instructions specify. The tools are read-only — they only serve methodology; the client owns project state.
+
+See `tools.md` for the full tool catalog and the lifecycle step list.