From 28608beb9debb7061f146a61a6e2df7898c266d0 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 1/9] Port AI Transformation playbook pages onto rebranded main Bring the docs/transformation pages from PR #11 (add-transformation-playbook) forward onto current main, and sweep Klarity -> Within in prose so they match the rebranded site. Nav wiring and the new pages (readouts, opportunity loops) follow in later commits. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/transformation.mdx | 38 ++++++ docs/transformation/company-brain.mdx | 72 ++++++++++ docs/transformation/maintain-agents.mdx | 28 ++++ docs/transformation/non-technical-track.mdx | 66 ++++++++++ docs/transformation/objective.mdx | 43 ++++++ docs/transformation/technical-track.mdx | 139 ++++++++++++++++++++ docs/transformation/use-case-selection.mdx | 35 +++++ docs/transformation/what-you-can-build.mdx | 41 ++++++ docs/transformation/where-you-build.mdx | 39 ++++++ 9 files changed, 501 insertions(+) create mode 100644 docs/transformation.mdx create mode 100644 docs/transformation/company-brain.mdx create mode 100644 docs/transformation/maintain-agents.mdx create mode 100644 docs/transformation/non-technical-track.mdx create mode 100644 docs/transformation/objective.mdx create mode 100644 docs/transformation/technical-track.mdx create mode 100644 docs/transformation/use-case-selection.mdx create mode 100644 docs/transformation/what-you-can-build.mdx create mode 100644 docs/transformation/where-you-build.mdx diff --git a/docs/transformation.mdx b/docs/transformation.mdx new file mode 100644 index 0000000..98537ce --- /dev/null +++ b/docs/transformation.mdx @@ -0,0 +1,38 @@ +--- +title: "Drive AI transformation" +description: "The motion that turns how your organization runs into skills, agents, and automations." +icon: "compass" +--- + +The motion has three phases. [Discover](/transformation/company-brain) captures how work happens, [Structure](/transformation/company-brain#structure) makes sense of it, and Improve builds skills and agents on top. Within runs this as a continuous loop rather than a one-time project. See [Discover → Structure → Improve](/concepts/discover-structure-improve) for the model itself; these pages are how you run it. + +Start by naming a high-level business objective and the technology stack you want to build within. Within respects the enterprise stack and won't recommend a competitor's tools. + +## The Company Brain + +These pages use **Company Brain** for the living map of how your organization actually runs. It is what the portal's two intelligence layers add up to: the [Process Index](/concepts/process-index), which holds every process with its steps, dependencies, and versions, and [Artifacts](/concepts/artifacts), the source documents and recordings behind them. + +Everything you build draws on it. That is what separates a build grounded in how your business actually works from one built against a generic template. + +## Where to start + + + + Name the outcome in business terms before choosing any technology. + + + Turn on Companion, then spend time in what it captures. + + + Choosing the right problem beats choosing how to build it. + + + Skills, Integration Flows, Managed Agents, and context bundles. + + + Four surfaces, split across a non-technical and a technical track. + + + A build is a product. Refresh it as the business moves. + + diff --git a/docs/transformation/company-brain.mdx b/docs/transformation/company-brain.mdx new file mode 100644 index 0000000..85328ac --- /dev/null +++ b/docs/transformation/company-brain.mdx @@ -0,0 +1,72 @@ +--- +title: "Build the Company Brain" +description: "Turn on Companion to capture how work actually happens, then spend time in what it captures before building anything." +icon: "brain" +--- + +The Company Brain is what everything else is built on. This page covers the first two phases of the motion: capturing how work happens, and making sense of it. + +## Discover + +[Companion](/concepts/discover-structure-improve) is how you build the Company Brain. Your team turns it on and works normally. There is nothing to learn and no documentation to write. As they work, Companion observes how the work actually gets done, scrubs PII and user attribution, and assembles a living, queryable map of how the organization really operates, down to the button-click level and packaged into value streams. + +Because capture runs in parallel across everyone in scope, you cover a whole function in days. That is a picture months of one-on-one interviews could never produce. The Interviewer fills the gaps Companion can't observe. + +Running Discover well is a real motion, not a switch you flip. + + + + People run it in the background of their normal work. There is nothing new to learn. + + + + Choose the people who actually perform the work in the processes you care about. They are who you learn from. + + + + Include enough people, and enough of the natural variation, that the Company Brain comes out rich rather than thin. One user gives a sliver. A representative cross-section gives the real picture. + + + + Bring everyone together on a call, ideally in person, and start as a group. A shared start drives shared momentum. + + + + Be transparent about how it works and what's in it for them: no SOPs to write, no interviews to sit, PII scrubbed and nothing attributed to them, and making their work visible is what lets AI take the grunt work off their plate. + + Naming the fear directly, that this is not about automating people out of a job but about taking the drudgery off their plate, is what turns skeptics into participants. + + + + Frame this as something they are shaping, not something done to them. The people doing the work are the experts, and their input directly shapes what gets built. + + + + Ask people to contribute Signals during sessions, flagging what they already do well. Signals surface the bright spots and repeated practices that make the best skills. + + + + Run Companion for at least two weeks per cycle, and repeat at least four times a year. Work changes, and a recurring cadence keeps the Company Brain a live picture rather than a one-time snapshot. + + + +## Structure + +Once Companion has run, the platform turns the captured activity into your Company Brain. Before building anything, spend time in it. The teams that explore first make far better build choices later. + +**Explore the visualizations.** Within packages thousands of process nodes into value streams and maps you can navigate. Start at the value-stream level and drill down. + +**Review the process steps.** Go to the button-click level to see how work actually happens: where time goes, where handoffs drop, where tools multiply. + +**Ask Advisor.** When something looks off or interesting, ask. Advisor can drive process-excellence analysis, surface cost optimizations, generate visualizations, and run time-and-motion views. + +```text +How does our vendor-onboarding process actually work today, and where do we +lose the most time? +``` + +The point of Structure is to build intuition for your own operation before you build anything on top of it. + + + You can ask the same questions from any MCP client. [Help a process performer](/guides/process-performer) and [State-of-the-team report](/guides/state-of-team) show the tool chains behind this kind of exploration. + diff --git a/docs/transformation/maintain-agents.mdx b/docs/transformation/maintain-agents.mdx new file mode 100644 index 0000000..a3be8cd --- /dev/null +++ b/docs/transformation/maintain-agents.mdx @@ -0,0 +1,28 @@ +--- +title: "Keep agents current" +description: "An agent built against last quarter's process drifts. Diff it against the Company Brain and refresh what moved." +icon: "arrows-rotate" +--- + +A build is a product, not a one-time artifact. As the business changes, an agent built against last quarter's process drifts out of step with reality and its accuracy degrades. + +## The update step + +Point your assistant at a repository of your existing agents and run it against the Company Brain. It pulls fresh process data, diffs it against what each agent was built on, classifies the drift, and proposes the rebuild. + +Classification matters here. A renamed field is noise. A new compliance step is not. + +```text +Our process changed. Run this agent's repo against the company brain and tell +me what's drifted and what to refresh. +``` + +## Why this compounds + +Because [Companion](/transformation/company-brain) keeps running, the Company Brain always reflects current reality. Transformation compounds instead of decaying. + +That is also why Discover is worth running on a recurring cadence rather than once. The refresh is only as good as the picture behind it. + + + [Recent process changes](/tools/observations-and-changes) is the tool your assistant reaches for to see what moved since a given date. + diff --git a/docs/transformation/non-technical-track.mdx b/docs/transformation/non-technical-track.mdx new file mode 100644 index 0000000..59847c4 --- /dev/null +++ b/docs/transformation/non-technical-track.mdx @@ -0,0 +1,66 @@ +--- +title: "The non-technical track" +description: "Business users building skills and simple agents in Advisor or from a chat app." +icon: "users" +--- + +This track is for business users building in Advisor, or reaching the Company Brain from [ChatGPT](/install/chatgpt) or [Claude](/install/claude) via the MCP. + +The core idea: the people who do the work understand their pain points better than anyone. Empowering them to build is both the fastest path to useful skills and the single best way to drive cultural change. + +This track builds skills and simple agents. Compound agents are [the technical track](/transformation/technical-track). + +## Run a recurring hackathon ritual + +Bring people together on a regular cadence, in person or virtual, to build. In the session they use Advisor and the MCP to turn their own repeated work into skills and reusable prompts. The act of building together is what creates fluency and buy-in. It cannot be lectured into a team. + +```text +Find the thing my team repeats most in monthly close that a skill could take +off our plate. +``` + +```text +Turn the best version of how we handle a customer refund into a reusable +skill, and show me the before-and-after workflow. +``` + +## Choose your surface + +Either works, with a clear tradeoff. + +**Advisor** has strong awareness of what makes a good skill and how to spot repeated usage worth formalizing, and it produces a before-and-after diagram of the workflow so the value is visible. Best when you want guidance and a clean artifact. + +**The MCP** brings the Company Brain into the chat app a person already uses, so the build can also draw on the other context and connectors they have there. Best when the work reaches beyond Within. + +```text +From Claude, using the Within MCP plus my email and Slack, draft a skill that +handles an inbound vendor request end to end. +``` + +[Chain with other connectors](/guides/chain-with-connectors) covers that pattern in more detail. + +## Stand up an AI committee + +A small cross-functional committee reviews the use cases and skills coming out of sessions and identifies the best ones to formalize and promote. It's a lightweight governance layer that keeps quality high and surfaces the highest-value builds. + +## Make it recurring + +Run the build ritual and the committee review on a regular cadence. Both cultural change and skill quality compound with repetition. A one-off event does not move an organization. + +## Keep a skills repository + +Store the good skills in one place. A simple GitHub repository works well. + +## Ship the skills + +Two options. Ship them directly into your AI platform as organizational skills available to everyone, or publish them to a separate repository people can download from. Either way, recommend the best ones so adoption spreads. + +## Within support + +Within's FDEs can facilitate the hackathon, curate the skills that come out of it, and take the best ones to production with your team. + +## Why this drives culture + +For AI to succeed it has to be adopted by people, and this track is the best way to drive that. Two patterns separate the organizations that make it stick: leadership actually using AI themselves rather than only sponsoring it, and a recurring hands-on ritual. + +The act of doing is paramount. Fluency comes from building, not from a workshop or a lecture. diff --git a/docs/transformation/objective.mdx b/docs/transformation/objective.mdx new file mode 100644 index 0000000..67aa4f0 --- /dev/null +++ b/docs/transformation/objective.mdx @@ -0,0 +1,43 @@ +--- +title: "Set the objective" +description: "Name the enterprise outcome in plain business terms before choosing any technology." +icon: "bullseye" +--- + +It's worth being deliberate about the objective before anything else. AI, agents, and skills are powerful means. The objective itself is an enterprise outcome: growing revenue, lowering cost, or reducing risk. Naming that outcome in plain business terms early gives the whole effort a clear yardstick and keeps the work pointed at results that matter to the business. + +## What a well-formed objective does + +**Leads with the outcome, not the means.** Start from the problem and the result you want rather than the technology. Say "our month-end close takes eight days and three late nights" rather than "we want a close agent." Keeping the objective means-agnostic lets the best solution emerge, whether that turns out to be a skill, an Integration Flow, an agent, a process change, or no build at all. + +**Connects to a lever of enterprise value.** The clearest objectives ladder up to growing revenue, lowering cost, or reducing risk, the outcomes leadership is already working toward. Anchoring there keeps the effort focused on what moves the business. + +**Is measurable, with a baseline and a target.** Name the metric, where it stands today, where you'd like it to be, and by when. "Cut the close from 8 days to 5 within two quarters." You'll quantify the baseline precisely in [Discover](/transformation/company-brain); it helps to commit to the metric now. + +**Has an owner.** Tie the objective to the executive who owns the outcome, the CFO for the close, the CRO for pipeline, so it stays anchored as the work progresses. + +**Is scoped to something winnable.** Bound it to a value stream, function, or process family. "Order-to-cash in the North America billing team" rather than "transform finance." Big enough to matter, small enough to show a result in a quarter. + +**Names constraints up front.** Non-negotiables shape which solutions fit, so it helps to state them early: "no net-new engineering," "must run inside our existing stack," "human approval for anything customer-facing," along with any regulatory, data-residency, budget, or timeline limits. These become the guardrails the assistant works within. + +**Stays separate from the use cases.** One objective usually points to several possible use cases, so there's no need to commit to a specific build yet. Selection comes later, in [Pick the right use case](/transformation/use-case-selection). The objective is the destination, the use cases are the route. + +## A simple test + +A good objective fits in one sentence. + +```text +[outcome + metric] for [scope], by [when], within [constraints], owned by [executive] +``` + +Vaguer: + +> Deploy AI agents in finance this year. + +Sharper: + +> Cut month-end close from 8 days to 5 within two quarters, without adding headcount or net-new engineering. Owned by the Controller. + + + The [technical track](/transformation/technical-track) opens with this same step. If you're building in a coding harness, your assistant can help you frame the objective and its constraints before anything else happens. + diff --git a/docs/transformation/technical-track.mdx b/docs/transformation/technical-track.mdx new file mode 100644 index 0000000..93ca380 --- /dev/null +++ b/docs/transformation/technical-track.mdx @@ -0,0 +1,139 @@ +--- +title: "The technical track" +description: "Build compound agents in the coding harness your engineers already use, grounded in how your business actually runs." +icon: "code" +--- + +This track is for technical builders, a developer or your AI Center of Excellence. What makes it distinct isn't a single tool. It's that you work in the coding harness your engineers already use, [Codex](/install/codex), [Claude Code](/install/claude-code), or the [Gemini CLI](/install/gemini-cli), iterating at the code level to build compound agents. + +The non-technical track builds skills and simple agents. This track builds the compound ones. + +## The Agent Development Kit + +The Agent Development Kit (ADK) is the throughline. It's a disciplined sequence that runs from a business objective to a tested, deployed agent, grounded at every step in your [Company Brain](/concepts/process-index) rather than guesswork. + + + There is nothing separate to install. The ADK methodology is served from the MCP itself. Once Within is connected in your harness, ask your assistant to build something and it calls [`get_agent_builder_instructions`](/tools/agent-builder), then follows what comes back, fetching supporting material with `get_agent_builder_resource` as it needs it. + + +That has a practical consequence worth knowing. There is no plugin version to track and nothing to keep updated. The methodology your assistant follows is whatever the MCP is serving right now, so improvements reach you the next time you build. + +```mermaid +flowchart LR + H[Coding harness] --> M[Within MCP] + M --> A[Agent Builder tools serve the methodology] + M --> C[Company Brain: processes and artifacts] + A --> B[Your agent] + C --> B +``` + +## The sequence + +At every step the assistant can do the work, or your team can do it themselves. The ADK brings rigor and speed. The Company Brain is what unleashes it, because every step is grounded in observed work. + +The prompts below are what a builder types in their harness with Within connected. + + + + Define the business objective and the technology stack the solution should live within. Giving both the goal and the stack constraints up front makes recommendations far more useful and deployable. + + ```text + I want to optimize order-to-cash on AWS Bedrock with the Claude Agent SDK. + Help me frame the objective and constraints. + ``` + + See [Set the objective](/transformation/objective) for what a well-formed one looks like. + + + + Make sure the Company Brain covers the area in question. Where coverage is thin, deploy [Companion](/concepts/discover-structure-improve) against it before building. + + ```text + Does our Company Brain have enough coverage of accounts payable to build + against? Where is it thin? + ``` + + + + Produce a current-state read from observed data: pain points, bottlenecks, time and motion, systems in use, and bright spots. + + ```text + Give me a current-state read of procure-to-pay: pain points, bottlenecks, + time-and-motion, systems, and bright spots. + ``` + + + + Generate candidate use cases and screen them down to the highest-leverage one that is feasible now. + + ```text + Find the highest-leverage automation opportunities in this process, rank + them, and flag which are feasible to ship now. + ``` + + Apply the screens in [Pick the right use case](/transformation/use-case-selection). The [Find transformation opportunities](/guides/find-opportunities) guide covers the tool chain behind this step. + + + + Produce the agent specification, effectively a PRD for the agent: scope, governance, credentials, and flow. + + ```text + Spec this out: what should the invoice-exception agent do, which tools and + credentials, and where are the human approval points? + ``` + + + + Generate the agent: code, skills, and configuration. + + ```text + Build it. Generate the agent against this spec. + ``` + + + + Generate and run evaluations. This is the hard but essential work of putting an agent through its paces before it ships. + + ```text + Test this. Generate an eval suite with edge cases and should-not-fire cases, + run it against real data, and ship on pass. + ``` + + + + Ship into your environment. + + ```text + Deploy this. Set it up as a Managed Agent in our environment. + ``` + + + +## What you build + +Compound agents, managed, orchestrated, or custom SDK-built, and deterministic Integration Flows. See [What you can build](/transformation/what-you-can-build) for how the primitives differ and when each one fits. + +Two disciplines run throughout. Every recommendation cites observed data, and a human signs off at each step. + +## Artifacts are part of the value + +The current-state reads and recommendations come out as clear, visual HTML artifacts. The assistant generates them as it works. Showing these to non-technical stakeholders is one of the best ways to win business buy-in for a build. + +## Keeping agents current + +An agent built against last quarter's process drifts as the business changes. See [Keep agents current](/transformation/maintain-agents) for how to diff a repository of existing agents against the Company Brain and refresh what has moved. + +## Within support + +Within's FDEs can work alongside your engineers to build the agents, get them into production, and define the test and eval suites. + +## Related + + + + The two tools that serve the methodology. + + + The same flow from any MCP client, not just a coding harness. + + diff --git a/docs/transformation/use-case-selection.mdx b/docs/transformation/use-case-selection.mdx new file mode 100644 index 0000000..df82561 --- /dev/null +++ b/docs/transformation/use-case-selection.mdx @@ -0,0 +1,35 @@ +--- +title: "Pick the right use case" +description: "Choosing the right problem is higher-leverage than choosing how to build it." +icon: "list-check" +--- + +> The hard part isn't building agents. It's knowing which agents to build. +> +> Heard in a public company boardroom. + +Selection comes first. Choosing the right problem is higher-leverage than how you build it, and it's where most of the value, or the wasted effort, is decided. + +## The screens + +**Mind the jagged frontier.** AI is unevenly capable, strong at one task and surprisingly weak at an adjacent one. Don't assume a use case is feasible because a neighbor is. Carry several candidates and test each. + +**Favor problems that don't demand multiple nines of accuracy.** The best early candidates are high-volume and repeatable, have data already in the Company Brain, and carry an error cost a human gate can absorb. + +**Qualify each candidate** against three tests: + +| Test | What it means | +|---|---| +| Evidence | Grounded in observed work, not assumption | +| Deployment readiness | Ships without new procurement, IT, or vendor review | +| Materiality | Clears a meaningful value threshold | + +**Know what not to touch.** Irreducible human judgment, a regulatory floor on human review, or volume too low to pay back are signs to decline rather than force. + +**Apply an enterprise bar.** Prioritize work that spans more than one team or touches a system of record and has a durable, named owner, rather than personal-productivity hacks. + +## Finding the candidates + +The screens above tell you what to keep. To generate the candidates in the first place, [Find transformation opportunities](/guides/find-opportunities) covers the tool chain for scanning the process tree and ranking what comes back. [Form a transformation thesis](/guides/transformation-thesis) goes deeper on a single candidate, including its blast radius. + +Once you know what to solve, choose the shape it should take in [What you can build](/transformation/what-you-can-build). diff --git a/docs/transformation/what-you-can-build.mdx b/docs/transformation/what-you-can-build.mdx new file mode 100644 index 0000000..7f6a0ca --- /dev/null +++ b/docs/transformation/what-you-can-build.mdx @@ -0,0 +1,41 @@ +--- +title: "What you can build" +description: "Skills, Integration Flows, Managed Agents, and MCP context bundles, and when each one fits." +icon: "cubes" +--- + +Once you know what to solve, choose the shape it should take. Four primitives cover most of what teams build on Within. + +## Skill + +The simplest primitive: an instruction manual, or recipe, for an agent. Governable, composable, and small. A skill runs in any AI tool and is interoperable across providers. A skill is the canonical simple agent. + +## Integration Flow + +Deterministic, rule-based automation on a fixed, predictable, auditable path. It does not use AI reasoning, so it is not an agent. Best where the process is stable and every step must be explainable. + +## Managed Agent + +An AI agent that reasons and plans its own path under a human gate. It handles variable inputs a fixed flow can't. Chained across multiple tasks and tools, it becomes a compound agent. + +## MCP context bundle + +Packaged Company-Brain context that grounds an external AI tool, custom GPT, or code-generation build. + +## Simple and compound + +Simple versus compound agents is the line between the two tracks. A simple agent does one thing, which is a skill. A compound agent chains multiple tasks and tools, and needs an SDK. + +| | Simple | Compound | +|---|---|---| +| What it does | One task | Chains tasks and tools | +| Built on | [The non-technical track](/transformation/non-technical-track) | [The technical track](/transformation/technical-track) | +| Typical primitive | Skill | Managed Agent | + +Compound agents scale further as orchestrated or multi-agent systems, custom SDK-built agents, and, as a horizon, fully autonomous agents. + +## Oversight + +Set oversight by stakes. Every build carries a human gate, and you graduate from more review to more autonomy as evaluation results prove out. + +Next, see [Where you build](/transformation/where-you-build) for the surfaces each of these is built on. diff --git a/docs/transformation/where-you-build.mdx b/docs/transformation/where-you-build.mdx new file mode 100644 index 0000000..e66db96 --- /dev/null +++ b/docs/transformation/where-you-build.mdx @@ -0,0 +1,39 @@ +--- +title: "Where you build" +description: "Four surfaces, split across a non-technical and a technical track." +icon: "table-columns" +--- + +Four surfaces, each mapped to a track. The MCP carries the Company Brain into the AI tools people already use, reached one way by non-technical builders and another by technical ones. + +## The surfaces + +**Advisor**, in-product and low-code, for non-technical builders. Recommends and generates builds, dashboards, and current-state analysis, with before-and-after diagrams. + +**MCP from a chat platform**, [ChatGPT](/install/chatgpt) or [Claude](/install/claude), for non-technical builders. Ask the Company Brain and build simple skills and reusable prompts, drawing on the other context in your chat app. + +**MCP from a coding harness**, [Codex](/install/codex), [Claude Code](/install/claude-code), or [Cursor](/install/cursor), for technical builders. Feed live Company-Brain context into compound builds. + +**ADK**, the methodology served through the MCP in [Codex](/install/codex), [Claude Code](/install/claude-code), or the [Gemini CLI](/install/gemini-cli), for technical builders. Scaffolds compound agents end to end. See [The technical track](/transformation/technical-track). + +## The build grid + +Read it by track. If you're non-technical you use the top two, if you're technical the bottom two. + +| Track | Surface | What you build | +|---|---|---| +| Non-technical | Advisor (in-product, low-code) | Skills and simple agents; before-and-after workflow diagrams | +| Non-technical | MCP from a chat platform (ChatGPT, Claude) | Ask the Company Brain; build simple skills and reusable prompts, with your other chat context | +| Technical | MCP from a coding harness (Codex, Claude Code, Cursor) | Feed live Company-Brain context into compound builds | +| Technical | ADK, served through the MCP | Scaffold compound agents end to end: design, build, evals, deploy | + +## Pick your track + + + + Business users building skills and simple agents in Advisor or from a chat app. + + + Developers and AI Centers of Excellence building compound agents in a coding harness. + + From 8328f05c63382ed3eb157a9d0d7ec0fe9e78c4b3 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 2/9] Add high-quality readouts guide New docs/transformation/readouts.mdx: how to produce a defensible, evidence-backed readout (business case first, observed vs inferred, depth before compression, interactive diagrams, pre- vs post-sale), with a synthetic prompt/output and a learnings section. Drafted by GPT 5.6 via Codex from REQUIREMENTS-FOR-CODEX.md (W1); verified against the brief's acceptance checks. Nav wiring follows in the nav commit. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/transformation/readouts.mdx | 169 +++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/transformation/readouts.mdx diff --git a/docs/transformation/readouts.mdx b/docs/transformation/readouts.mdx new file mode 100644 index 0000000..34669f3 --- /dev/null +++ b/docs/transformation/readouts.mdx @@ -0,0 +1,169 @@ +--- +title: "Build defensible readouts" +description: "Turn process evidence into a concise case for change, with the business context and uncertainty made explicit." +icon: "presentation-screen" +--- + +A readout is a concise, evidence-backed brief that makes the case for change. It connects a business objective to what people actually do, sizes the impact, and gives the audience a clear next decision. It is not a list of Within features or everything found during analysis. + +The short version comes last. First, do enough analysis to know which facts, assumptions, and gaps belong in the final narrative. + +## Start with the business case + +Business context belongs at the front of the readout and at the start of the analysis. A readout without a stated objective has no reliable way to rank findings or decide what matters. + + + If the objective is missing, say "No stated objective" and stop short of a recommendation. Ask the sponsor to define the outcome before compressing the analysis into a deck. + + +Capture the following inputs before you assess the process: + +- The business objective and the outcome used to judge progress +- The value hypothesis, including how a process change could affect that outcome +- The solution space: trigger, agency, autonomy, compoundedness, and which harness parts are in scope, such as memory, tools, and integrations +- Current volume and time metrics, with their period and source +- A blended full-time-equivalent (FTE) rate when it is available and appropriate for the audience + +Volume and rate inputs let you translate minutes of friction into capacity or cost. Keep the arithmetic visible. If an input is missing, show the formula with the missing value instead of substituting an industry estimate. + +## Make every claim defensible + +Use [`get_process_details`](/tools/process-index) to ground claims about the documented process. For claims about how work was performed, follow the relevant [`get_process_observations`](/tools/observations-and-changes) result to [`get_observation_citation`](/tools/observations-and-changes). Cite the process resource key and the observation resource key or timestamp so another person can audit the claim. + + + + State what the process definition or captured activity shows. Include the evidence pointer next to the claim. + + + State the interpretation and the evidence behind it. Label the claim as an inference, especially when it sizes future impact. + + + +Lead each section with the impact, then show the evidence that sizes it. A reader should be able to distinguish a measured fact from a planning assumption without checking an appendix. + +Surface uncertainty in the same way. Record what is unknown, why it matters, and what additional capture would resolve it. This turns an unseen risk into a named question and makes the value of continued capture concrete. + +## Analyze at depth, then compress + + + + Write down the objective, value hypothesis, solution space, intended audience, and the decision the readout should support. + + + Pull the current process, its dependencies, and the observations behind behavioral claims. Record identifiers, timestamps, volume inputs, and source notes as you work. + + + Save the full analysis to a working file before creating slides. Include calculations, counterevidence, assumptions, uncertainty, and findings that may not appear in the final readout. + + + Check that each conclusion follows from the cited evidence and that the narrative stays tied to the stated outcome. Resolve factual gaps or label them before editing for length. + + + Reduce the analysis to the impact, supporting evidence, recommendation, uncertainty, and next decision. Keep the deep analysis as the audit trail. + + + +Generating the deck first forces the analysis to fit a slide before the evidence has been tested. The result may be tidy, but it is often shallow. + +## Keep complex diagrams interactive + +Put dense current-state maps, dependency graphs, and before-and-after flows in an HTML artifact that supports scrolling and zooming. Link to the artifact from the readout and keep only the decision-relevant portion on the slide. + +Review diagrams twice: first as a person checking readability and meaning, then with a structural check for missing nodes, broken connections, clipping, and overflow. A slide image of a large diagram makes both review and later investigation harder. + + + A diagram earns its place when it helps the audience make the next decision. Move supporting detail to the interactive artifact instead of shrinking it until labels are unreadable. + + +## Match the readout to the stage + + + + Make the case in dollar terms when the inputs support it. Be prescriptive about the proposed change, show the calculation, and label every rate or adoption assumption. + + + Describe the current state and direction of travel. Focus on observed behavior, coverage gaps, and the decisions required to move from evidence to a tested build. + + + +The evidence rules do not change between stages. What changes is the decision being supported and how precisely the available evidence can size the outcome. + +## Synthetic example + +The example below uses a fictional shipment-exception process and fictional evidence identifiers. + +### Sample prompt + +```text +Use only evidence available in the Within workspace. Cite the process resource key +for process claims and the observation resource key or timestamp for behavioral +claims. Separate observed facts, inferences, assumptions, and unknowns. Keep +evidence gaps explicit rather than replacing them with benchmarks. + +Create a readout for the synthetic "Resolve shipment exceptions" process. The stated +objective is to reduce delayed shipments and avoidable customer contacts. Test the +value hypothesis that preparing exception context before human review will return +handling capacity without weakening approval controls. Use a monthly volume of 1,200 +cases and a blended FTE rate of $58 per hour as planning assumptions. + +First write the deep analysis to a working file. Then produce a concise readout that +leads with impact, shows the arithmetic, describes the solution-space dimensions, +surfaces uncertainty, and ends with the next decision. Treat any proposed impact as +an inference until it has been tested. +``` + +### Sample output + +```text +Resolve shipment exceptions + +Objective +Reduce delayed shipments and avoidable customer contacts. + +Impact +Observed review time is 11 minutes per case. At the assumed volume of 1,200 cases +per month, the process uses about 220 hours per month. At the assumed blended FTE +rate of $58 per hour, that is $153,120 in annual handling capacity. +[observation-example-101 through observation-example-105] + +Evidence +Observed: The documented process has seven steps, including manual collection of +case context before review. [process-example-001] +Observed: Five captured runs show 9 to 14 minutes of review activity, with a median +of 11 minutes. [observation-example-101 through observation-example-105] +Inferred: Preparing the context before review may reduce handling time by 40% to +60%. This range is a hypothesis, not a measured result. + +Proposed solution space +Trigger: a new exception enters the queue. +Agency: prepare context and recommend a disposition. +Autonomy: a person approves every disposition. +Compoundedness: one bounded preparation flow; no agent-to-agent delegation. +Harness: read tools and the case integration are in scope. Persistent memory is out +of scope until retention requirements are approved. + +Assumptions and uncertainty +The monthly volume and $58 rate are planning assumptions. Five observations do not +show seasonal variation or the full exception mix. The annual figure describes +capacity, not booked savings. + +Next decision +Capture 20 more runs across exception types, confirm volume and rate inputs, then +test the preparation flow with human approval. Use measured handling time and error +rates to accept, revise, or stop the proposed change. +``` + +## Review before sharing + +Use a small set of standard sections so reviewers know where to find the objective, impact, evidence, assumptions, recommendation, and next decision. The narrative should still follow the sponsor's stated outcome rather than the order in which the analysis happened. + +### Learnings + +- Business context belongs first. "No stated objective" is the most serious failure because it leaves the readout without a decision frame. +- Write the deep analysis to a file before producing the deck. Early compression hides weak evidence and unresolved questions. +- State assumptions and uncertainty in the main narrative, not only in footnotes. +- Keep a clear line from the stated outcome through the evidence to the proposed next action. +- Put complex diagrams in scrollable, zoomable HTML artifacts rather than slide images. +- Use dollar-denominated, prescriptive framing for pre-sale decisions when the inputs support it; use a more directional, current-state framing for post-sale readouts. +- Treat Advisor output as a scope and a head start for builders, not as a finished agent. The files still need to move through build, test, and deployment. See [Where you build](/transformation/where-you-build). +- Use stage gates between analysis, review, and compression. Each gate should leave the builder with an explicit next action. From 0526fed08e908870abc4c6c9da85c25a36e3f3d9 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 3/9] Add evidence-backed opportunity loops Document a bounded recurring scan, add a synthetic ranked opportunity output, and make the readout evidence pull reproducible. The transformation overview now links the new evidence and readout paths. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/guides/find-opportunities.mdx | 16 ++- docs/transformation.mdx | 9 ++ docs/transformation/opportunity-loops.mdx | 118 ++++++++++++++++++++++ docs/transformation/readouts.mdx | 32 +++++- 4 files changed, 169 insertions(+), 6 deletions(-) create mode 100644 docs/transformation/opportunity-loops.mdx diff --git a/docs/guides/find-opportunities.mdx b/docs/guides/find-opportunities.mdx index 1adba21..a0989ee 100644 --- a/docs/guides/find-opportunities.mdx +++ b/docs/guides/find-opportunities.mdx @@ -16,7 +16,7 @@ A platform lead, AI architect, or transformation owner asks where to focus next. - Call [`list_accessible_workspaces`](/tools/workspace) and switch if needed. + Call [`list_accessible_workspaces`](/tools/workspace). If the wrong workspace is active, reconnect with OAuth or use an API key created in the intended workspace before continuing. Call [`get_process_hierarchy`](/tools/process-index) — the whole tree, or filtered to the value stream of interest. The leaves become your work queue. @@ -27,7 +27,7 @@ A platform lead, AI architect, or transformation owner asks where to focus next. - [`get_process_observations`](/tools/observations-and-changes) — exception volume per process (default summary verbosity). - The MCP is stateless per call. There's no penalty for parallel reads — fan out aggressively. + The MCP is stateless per call, so independent reads can run in parallel. Cap each batch so the scan stays within the routine's time and output budget. @@ -46,6 +46,18 @@ A platform lead, AI architect, or transformation owner asks where to focus next. +## Sample output + +The candidate set below is synthetic. Its identifiers and counts show the shape of a useful result, not customer data. + +| Rank | Process | Observations | Dependency depth | Pattern signal | Evidence pointer | +|---|---|---:|---:|---|---| +| 1 | Resolve shipment exceptions | 12 | 3 | Staff gathered the same context manually in 9 of 12 captured runs | `process-example-001`; `observation-example-101` to `observation-example-109` | +| 2 | Reconcile supplier statements | 8 | 2 | Six runs repeated an export, comparison, and re-entry sequence | `process-example-002`; `observation-example-201` to `observation-example-206` | +| 3 | Review temporary access requests | 15 | 1 | Ten runs paused while reviewers looked for the same missing approval evidence | `process-example-003`; `observation-example-301` to `observation-example-310` | + +The first candidate ranks highest because the repeated pattern has the broadest downstream reach. The evidence does not yet prove that an agent is the right answer. The next step is to inspect representative activity timelines, confirm the required system access, and compare a skill, a deterministic flow, and a process change. + ## What to surface in the brief - A ranked list of candidate processes diff --git a/docs/transformation.mdx b/docs/transformation.mdx index 98537ce..270d727 100644 --- a/docs/transformation.mdx +++ b/docs/transformation.mdx @@ -23,6 +23,15 @@ Everything you build draws on it. That is what separates a build grounded in how Turn on Companion, then spend time in what it captures. + + Scan the process tree and rank candidates against the evidence. + + + Re-scan as capture grows and report newly supported signals. + + + Connect the objective, impact, evidence, uncertainty, and next decision. + Choosing the right problem beats choosing how to build it. diff --git a/docs/transformation/opportunity-loops.mdx b/docs/transformation/opportunity-loops.mdx new file mode 100644 index 0000000..81a6ead --- /dev/null +++ b/docs/transformation/opportunity-loops.mdx @@ -0,0 +1,118 @@ +--- +title: "Run opportunity-scanning loops" +description: "Re-scan the Process Index as capture grows and report newly supported transformation signals." +icon: "arrows-rotate" +--- + +An opportunity-scanning loop is a scheduled evidence review. On each tick, an AI client re-runs a bounded scan of the Process Index, compares the result with its last checkpoint, and reports signals that are new or better supported. + +This is not workflow automation. The loop watches for opportunities; it does not perform the work inside a candidate process. The schedule, checkpoint, and notification live in your AI client or automation platform. The Within MCP supplies read-only process evidence. + +## When the loop fits + + + + A transformation owner wants to know when new capture changes the opportunity set, without repeating a manual review of the whole index. + + + If the goal is to perform a known workflow on a schedule, build an Integration Flow or agent instead. An opportunity loop only identifies and sizes candidates. + + + +## Define the optimization function + +The prompt needs a stable answer to "what do I care to look for?" Without it, each tick can rank the same evidence differently and create noise. + +Define: + +- The business objective the scan should support +- The process scope and patterns worth looking for +- The evidence threshold for reporting a signal +- The constraints that disqualify a candidate +- What counts as a meaningful change from the prior checkpoint + + + Keep the optimization function stable between ticks. If the objective changes, start a new baseline instead of comparing unlike scans. + + +## Sample routine prompt + +This prompt uses a fictional logistics workspace. The scheduler supplies `cycle_index`, `max_cycles`, and the prior checkpoint to the routine; those are routine state, not Within MCP arguments. + +```text +Run one bounded opportunity scan for the synthetic "Shipment operations" value +stream. The objective is to reduce delayed shipments without removing human approval +for customer-facing decisions. + +Look for repeated manual context gathering, duplicate entry, retries, and handoffs that +affect two or more downstream processes. Report a signal only when it appears in at +least three observations. Treat observation counts and dependency depth as evidence, +not as proof that automation is the right solution. + +Compare this tick with the supplied checkpoint. Return only new candidates, candidates +whose evidence crossed the threshold, and material changes to a previously reported +candidate. For each result, include the process, observation count, dependency depth, +pattern, evidence pointer, uncertainty, and next validation step. + +Run at most max_cycles remediation cycles. On each cycle, return one outcome: +- clear: save the new checkpoint and finish +- remediate: correct a recoverable input or retrieval problem, increment cycle_index, + and try again +- escalate: stop and name the missing access, evidence, or capability + +Escalate when cycle_index reaches max_cycles. Do not rerun a step that cannot succeed +with the tools or evidence available. +``` + +## Tool-call chain for each tick + +The example calls below use synthetic resource keys. The argument names match the Within MCP tool contract. + +```javascript +get_process_hierarchy({ + "root": { "node_name": "Shipment operations" }, + "max_depth": 3 +}) + +get_process_details({ + "process_resource_key": "process-example-001", + "scope": ["tasks", "dependencies", "attributes"] +}) + +get_process_observations({ + "process_resource_key": "process-example-001", + "limit": 20, + "offset": 0, + "verbosity": "summary" +}) + +get_observation_citation({ + "observation_resource_key": "observation-example-101", + "verbosity": "medium", + "activity_block_index": 0 +}) +``` + +Run the detail and observation calls for each leaf in bounded parallel batches. Use `get_observation_citation` only for the strongest signals rather than loading every activity timeline. The routine compares returned observation keys or timestamps with its saved checkpoint; the MCP does not store loop state. + +If hierarchy browsing is too broad, start with [`search_processes`](/tools/process-index) using a pattern query and then run the same detail and observation calls on the matches. The full one-time scan is documented in [Find transformation opportunities](/guides/find-opportunities). + +## Bound every tick + +Each tick needs an exit rule as well as a schedule. + +| Outcome | Use it when | Action | +|---|---|---| +| `clear` | The scan completed with enough evidence to update or preserve the candidate set | Save the checkpoint and finish the tick | +| `remediate` | A recoverable input, paging, or retrieval problem blocked the scan | Correct it, increment `cycle_index`, and retry within `max_cycles` | +| `escalate` | Authentication, permission, missing evidence, or an unavailable capability makes the step structurally incapable of succeeding | Stop and ask for the specific human action required | + +Repeated retries do not create new evidence. When the maximum cycle count is reached, escalate with the last valid checkpoint intact. + +## Limits + + + The loop's value tracks capture. When capture stops, the candidate set stops learning. A routine can keep running against old evidence and still produce a fresh timestamp, so every result should state the newest observation it used. + + +Sparse coverage is a result, not a reason to fill the gap with assumptions. Report which processes lack enough observations and what additional capture would make the next scan useful. diff --git a/docs/transformation/readouts.mdx b/docs/transformation/readouts.mdx index 34669f3..e8cb5b4 100644 --- a/docs/transformation/readouts.mdx +++ b/docs/transformation/readouts.mdx @@ -43,6 +43,30 @@ Lead each section with the impact, then show the evidence that sizes it. A reade Surface uncertainty in the same way. Record what is unknown, why it matters, and what additional capture would resolve it. This turns an unseen risk into a named question and makes the value of continued capture concrete. +For a client-neutral evidence pull, the sequence looks like this: + +```javascript +get_process_details({ + "process_resource_key": "process-example-001", + "scope": ["tasks", "dependencies", "attributes"] +}) + +get_process_observations({ + "process_resource_key": "process-example-001", + "limit": 20, + "offset": 0, + "verbosity": "summary" +}) + +get_observation_citation({ + "observation_resource_key": "observation-example-101", + "verbosity": "medium", + "activity_block_index": 0 +}) +``` + +Start citations at low or medium verbosity and request one `activity_block_index` when the timeline is large. The citation tool only returns activity for sessions owned by the authenticated user. If the timeline is unavailable, cite the observation timestamp and limit the claim to the observation-level evidence rather than reconstructing missing actions. + ## Analyze at depth, then compress @@ -78,10 +102,10 @@ Review diagrams twice: first as a person checking readability and meaning, then ## Match the readout to the stage - - Make the case in dollar terms when the inputs support it. Be prescriptive about the proposed change, show the calculation, and label every rate or adoption assumption. + + Size the case in dollar terms when the inputs support it. Describe the proposed change, show the calculation, and label every rate or adoption assumption. - + Describe the current state and direction of travel. Focus on observed behavior, coverage gaps, and the decisions required to move from evidence to a tested build. @@ -164,6 +188,6 @@ Use a small set of standard sections so reviewers know where to find the objecti - State assumptions and uncertainty in the main narrative, not only in footnotes. - Keep a clear line from the stated outcome through the evidence to the proposed next action. - Put complex diagrams in scrollable, zoomable HTML artifacts rather than slide images. -- Use dollar-denominated, prescriptive framing for pre-sale decisions when the inputs support it; use a more directional, current-state framing for post-sale readouts. +- Before an investment decision, use dollar-denominated and prescriptive framing when the inputs support it. During delivery, use a more directional, current-state framing. - Treat Advisor output as a scope and a head start for builders, not as a finished agent. The files still need to move through build, test, and deployment. See [Where you build](/transformation/where-you-build). - Use stage gates between analysis, review, and compression. Each gate should leave the builder with an explicit next action. From 70fcc1a76bb134f32241856dd4198fc4bd9aca61 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 4/9] Clarify solution and skill build paths Document the solution as dimensions instead of named tiers. Add the full customer-facing skill walkthrough because the existing track did not show the approval gates, package shape, or a concrete configuration. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/transformation/non-technical-track.mdx | 113 ++++++++++++++++++-- docs/transformation/what-you-can-build.mdx | 40 +++++-- 2 files changed, 138 insertions(+), 15 deletions(-) diff --git a/docs/transformation/non-technical-track.mdx b/docs/transformation/non-technical-track.mdx index 59847c4..1158eb8 100644 --- a/docs/transformation/non-technical-track.mdx +++ b/docs/transformation/non-technical-track.mdx @@ -6,7 +6,7 @@ icon: "users" This track is for business users building in Advisor, or reaching the Company Brain from [ChatGPT](/install/chatgpt) or [Claude](/install/claude) via the MCP. -The core idea: the people who do the work understand their pain points better than anyone. Empowering them to build is both the fastest path to useful skills and the single best way to drive cultural change. +The people who do the work know the exceptions, judgment calls, and source material that a useful skill must handle. Giving them a direct build path reduces the distance between the process evidence and the instructions the skill follows. This track builds skills and simple agents. Compound agents are [the technical track](/transformation/technical-track). @@ -28,9 +28,9 @@ skill, and show me the before-and-after workflow. Either works, with a clear tradeoff. -**Advisor** has strong awareness of what makes a good skill and how to spot repeated usage worth formalizing, and it produces a before-and-after diagram of the workflow so the value is visible. Best when you want guidance and a clean artifact. +**Advisor** guides the build inside Within and produces a before-and-after workflow diagram. Use it when you want the analysis and resulting artifact to remain in Within. -**The MCP** brings the Company Brain into the chat app a person already uses, so the build can also draw on the other context and connectors they have there. Best when the work reaches beyond Within. +**The MCP** brings Company Brain evidence into the chat app a person already uses. Use it when the build also needs files or connectors available in that client. ```text From Claude, using the Within MCP plus my email and Slack, draft a skill that @@ -39,13 +39,108 @@ handles an inbound vendor request end to end. [Chain with other connectors](/guides/chain-with-connectors) covers that pattern in more detail. +## Build one skill + +A skill fits a repeated task with a bounded outcome: prepare a brief, check an input against a policy, classify a request, or draft from known source material. The assistant should use the Agent Builder instructions served by the MCP rather than inventing its own build method. + +### Sample prompt + +This example uses a fictional shipment-exception process. + +```text +Use Within Agent Builder to create a reusable skill for the synthetic "Resolve +shipment exceptions" process. The skill should prepare a review brief from the +exception record and the documented process, then stop for human approval. It must +not approve a disposition, update the case system, or invent a missing policy. + +Ground the instructions in the current process and representative observations. +Separate documented rules from behavior inferred from captured runs. Show me the +proposed scope, inputs, output, and refusal conditions before writing the package. +``` + +The assistant begins with the MCP-served method. A client-neutral representation of the first call is: + +```javascript +get_agent_builder_instructions({ "step": "skill_track" }) +``` + +The returned instructions identify the resources needed for that build. The assistant first gathers current process evidence and drafts the proposed scope. You approve that outline before it writes the package. After the package is built, you review the result and its smoke-test evidence before installation. + +### Sample output + +```text +Proposed skill: shipment-exception-brief + +Scope +Prepare one review brief for a shipment exception. A person decides the disposition. + +Inputs +- Exception record +- Current documented process +- Available shipment and contact context + +Output +- Facts found in the source records +- Missing information +- Applicable process rules +- Recommended questions for the reviewer + +Refuse when +- The current process cannot be retrieved +- The exception record is missing +- The request asks the skill to approve or update the case + +Grounding +- Current "Resolve shipment exceptions" process +- Five synthetic representative observations + +Package +- skills/shipment-exception-brief/SKILL.md +- skills/shipment-exception-brief/decision-rules.md +- skills/shipment-exception-brief/caveats.md +- skills/shipment-exception-brief/examples.md +- skills/shipment-exception-brief/README.md +- skills/shipment-exception-brief/evals/positive.md +- skills/shipment-exception-brief/evals/negative.md +- skills/shipment-exception-brief/evals/neighbor.md +- INSTALL.md +``` + +The package keeps its evidence references in the working audit trail rather than placing internal citation tokens in the files people install. The generated `SKILL.md` should be short enough to inspect and flexible enough to apply the documented judgment to a new case. For example: + +```md +--- +name: shipment-exception-brief +description: Load when preparing a shipment-exception review brief. Do not load for approving a disposition or updating the case system. +--- + +# Shipment exception brief + +Prepare a review brief from the supplied exception record and the current +documented process. + +## Required content + +- Separate source-backed facts from missing information. +- Apply only rules stated in the current process. +- Draft questions and a non-binding recommendation for the reviewer. + +## Decision boundaries + +- Stop if the process or exception record cannot be retrieved. +- Treat conflicting evidence as an issue for the reviewer. +- Do not approve a disposition or change the case system. +``` + +Test the package with ordinary cases, missing inputs, conflicting evidence, and requests that should be refused. A useful skill is defined as much by where it stops as by what it produces. + ## Stand up an AI committee -A small cross-functional committee reviews the use cases and skills coming out of sessions and identifies the best ones to formalize and promote. It's a lightweight governance layer that keeps quality high and surfaces the highest-value builds. +A small cross-functional committee can review the use cases and skills coming out of sessions, decide which ones are safe to distribute, and assign an owner for maintenance. ## Make it recurring -Run the build ritual and the committee review on a regular cadence. Both cultural change and skill quality compound with repetition. A one-off event does not move an organization. +Run the build session and committee review on a regular cadence. Repetition gives people time to improve the skills, add evaluations, and retire packages that no longer match the process. ## Keep a skills repository @@ -53,14 +148,14 @@ Store the good skills in one place. A simple GitHub repository works well. ## Ship the skills -Two options. Ship them directly into your AI platform as organizational skills available to everyone, or publish them to a separate repository people can download from. Either way, recommend the best ones so adoption spreads. +Ship approved skills through your AI platform's organization controls or publish them in a repository your team manages. Record an owner, version, and evaluation set for each distributed skill. ## Within support -Within's FDEs can facilitate the hackathon, curate the skills that come out of it, and take the best ones to production with your team. +Within's team can facilitate the build session, help review the resulting skills, and work with you on production readiness. ## Why this drives culture -For AI to succeed it has to be adopted by people, and this track is the best way to drive that. Two patterns separate the organizations that make it stick: leadership actually using AI themselves rather than only sponsoring it, and a recurring hands-on ritual. +This track works when leaders use the same tools they ask teams to adopt and when people have a recurring place to build, test, and improve skills from their own work. -The act of doing is paramount. Fluency comes from building, not from a workshop or a lecture. +Hands-on building gives teams direct experience with what the tools can do, where they fail, and which controls they need. diff --git a/docs/transformation/what-you-can-build.mdx b/docs/transformation/what-you-can-build.mdx index 7f6a0ca..a7de3a8 100644 --- a/docs/transformation/what-you-can-build.mdx +++ b/docs/transformation/what-you-can-build.mdx @@ -1,6 +1,6 @@ --- title: "What you can build" -description: "Skills, Integration Flows, Managed Agents, and MCP context bundles, and when each one fits." +description: "When to use a Skill, Integration Flow, Managed Agent, or MCP context bundle." icon: "cubes" --- @@ -8,11 +8,11 @@ Once you know what to solve, choose the shape it should take. Four primitives co ## Skill -The simplest primitive: an instruction manual, or recipe, for an agent. Governable, composable, and small. A skill runs in any AI tool and is interoperable across providers. A skill is the canonical simple agent. +The simplest primitive: an instruction package for one bounded task. Skills are small enough to review directly and can move between clients that support the same skill format. A skill is the canonical simple agent. ## Integration Flow -Deterministic, rule-based automation on a fixed, predictable, auditable path. It does not use AI reasoning, so it is not an agent. Best where the process is stable and every step must be explainable. +Deterministic, rule-based automation on a fixed, predictable, auditable path. It does not use AI reasoning, so it is not an agent. Use it where the process is stable and every step must be explainable. ## Managed Agent @@ -22,9 +22,37 @@ An AI agent that reasons and plans its own path under a human gate. It handles v Packaged Company-Brain context that grounds an external AI tool, custom GPT, or code-generation build. +## Describe the solution space + +The solution space records the choices a build is allowed to make. It is a set of dimensions, not a maturity score or a named tier. + +| Dimension | Question to answer | Common options | +|---|---|---| +| Trigger | What starts the work? | A person, an event, or a schedule | +| Agency | What may the system do? | Retrieve, draft, recommend, decide within a rule, or act | +| Autonomy | Where does a person approve or intervene? | Review every result, review defined exceptions, or monitor a bounded unattended step | +| Compoundedness | How many reasoning steps and handoffs are required? | One bounded operation, a fixed sequence, or an orchestrated chain of tasks and tools | +| Harness components | What does the runtime need? | Memory, tools, and integrations, each included only when the task requires it | + +Write the constraints beside those dimensions: approved systems, permissions, data residency, latency, cost ceiling, required controls, and the technology already in use. Then compare the available primitives. A scheduled trigger does not automatically require an agent, and a multi-step process does not make every step a model task. + +```text +Trigger: +Agency: +Autonomy: +Compoundedness: +Harness components: +Constraints: +Technology options considered: +``` + + + Choose the smallest shape that can produce the required outcome and pass its controls. The result may be a process change or an Integration Flow rather than an AI build. + + ## Simple and compound -Simple versus compound agents is the line between the two tracks. A simple agent does one thing, which is a skill. A compound agent chains multiple tasks and tools, and needs an SDK. +Simple versus compound agents is the line between the two tracks. A simple agent does one thing, which is a skill. A compound agent chains multiple tasks and tools and typically needs an orchestration layer or SDK. | | Simple | Compound | |---|---|---| @@ -32,10 +60,10 @@ Simple versus compound agents is the line between the two tracks. A simple agent | Built on | [The non-technical track](/transformation/non-technical-track) | [The technical track](/transformation/technical-track) | | Typical primitive | Skill | Managed Agent | -Compound agents scale further as orchestrated or multi-agent systems, custom SDK-built agents, and, as a horizon, fully autonomous agents. +Compound agents may use orchestration, multiple specialized agents, or a custom SDK. Each additional step and tool creates another failure path that the design and evaluations must cover. ## Oversight -Set oversight by stakes. Every build carries a human gate, and you graduate from more review to more autonomy as evaluation results prove out. +Set oversight by stakes. Every build needs human approval before release. Runtime approvals should remain wherever an action is irreversible, regulated, or expensive to correct. Reduce review only when evaluation and production evidence support the change. Next, see [Where you build](/transformation/where-you-build) for the surfaces each of these is built on. From 08abfc9bb7fc5f9648d0a12c625eda112faef0f0 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 5/9] Clarify where customers build Fold Derrick's Advisor and MCP positioning into the existing page. Separate Advisor, the read-only Within MCP, and client-owned actions, and correct ADK's role from a surface to a builder method. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/transformation/where-you-build.mdx | 104 ++++++++++++++++++------ 1 file changed, 78 insertions(+), 26 deletions(-) diff --git a/docs/transformation/where-you-build.mdx b/docs/transformation/where-you-build.mdx index e66db96..3b70e4f 100644 --- a/docs/transformation/where-you-build.mdx +++ b/docs/transformation/where-you-build.mdx @@ -1,39 +1,91 @@ --- title: "Where you build" -description: "Four surfaces, split across a non-technical and a technical track." +description: "Choose whether to build in Within or bring read-only Company Brain evidence into your AI client." icon: "table-columns" --- -Four surfaces, each mapped to a track. The MCP carries the Company Brain into the AI tools people already use, reached one way by non-technical builders and another by technical ones. +You can build inside Within with Advisor or in an external AI client connected through the Within MCP. The right location depends on where the work, tools, and resulting files need to live. -## The surfaces +## Advisor, the MCP, and your AI client -**Advisor**, in-product and low-code, for non-technical builders. Recommends and generates builds, dashboards, and current-state analysis, with before-and-after diagrams. +These components have separate responsibilities. -**MCP from a chat platform**, [ChatGPT](/install/chatgpt) or [Claude](/install/claude), for non-technical builders. Ask the Company Brain and build simple skills and reusable prompts, drawing on the other context in your chat app. +| Component | Responsibility | Boundary | +|---|---|---| +| Advisor | Analyze process evidence and create Within-native outputs inside Within | Work remains in the Within product experience | +| Within MCP | Give an authorized AI client read-only access to Company Brain context and builder methods | It retrieves from Within; it does not write to Within or another system | +| Your AI client | Reason over the retrieved context and use the client's tools to create files, code, skills, or actions outside Within | The client's permissions and approval controls govern those actions | -**MCP from a coding harness**, [Codex](/install/codex), [Claude Code](/install/claude-code), or [Cursor](/install/cursor), for technical builders. Feed live Company-Brain context into compound builds. +This boundary matters when a build uses several systems. The MCP supplies Within context. If the assistant drafts a document, commits code, or calls another connector, the AI client performs that action through its own tools. -**ADK**, the methodology served through the MCP in [Codex](/install/codex), [Claude Code](/install/claude-code), or the [Gemini CLI](/install/gemini-cli), for technical builders. Scaffolds compound agents end to end. See [The technical track](/transformation/technical-track). +## Build inside Within -## The build grid +Use Advisor when the work should stay in Within and the builder wants a guided product experience. Advisor can analyze the Company Brain, help shape a build, and produce Within-native artifacts such as current-state analysis and before-and-after workflow diagrams. -Read it by track. If you're non-technical you use the top two, if you're technical the bottom two. +This is the usual path for a business user building a skill or exploring a process without working in a code repository. Continue with [the non-technical track](/transformation/non-technical-track). -| Track | Surface | What you build | -|---|---|---| -| Non-technical | Advisor (in-product, low-code) | Skills and simple agents; before-and-after workflow diagrams | -| Non-technical | MCP from a chat platform (ChatGPT, Claude) | Ask the Company Brain; build simple skills and reusable prompts, with your other chat context | -| Technical | MCP from a coding harness (Codex, Claude Code, Cursor) | Feed live Company-Brain context into compound builds | -| Technical | ADK, served through the MCP | Scaffold compound agents end to end: design, build, evals, deploy | - -## Pick your track - - - - Business users building skills and simple agents in Advisor or from a chat app. - - - Developers and AI Centers of Excellence building compound agents in a coding harness. - - +## Build from your AI client + +Use the MCP when the build needs context or tools available in another client. A business user might combine Company Brain evidence with files available to ChatGPT or Claude. A developer might use Codex, Claude Code, Cursor, or the Gemini CLI to create and test a compound agent in a repository. + +The client can also combine Within with other connectors. Keep the source boundary explicit in the prompt so the result states which claims came from Within and which came from another system. See [Chain with other connectors](/guides/chain-with-connectors). + +## A developer pull pattern + +Start with the smallest useful process scope, then retrieve more detail only when the task requires it. + + + + Use [`search_processes`](/tools/process-index) when you know the topic, or [`get_process_hierarchy`](/tools/process-index) when you need to browse the process tree. + + ```javascript + search_processes({ "query": "shipment exceptions", "top_k": 5 }) + ``` + + + + Retrieve the process record and request only the scopes needed for the build. + + ```javascript + get_process_details({ + "process_resource_key": "", + "scope": ["tasks", "dependencies", "policies", "history"] + }) + ``` + + + + Scan summaries first. Open the underlying activity timeline only for the observations needed to confirm a material claim. + + ```javascript + get_process_observations({ + "process_resource_key": "", + "limit": 10, + "offset": 0, + "verbosity": "summary" + }) + + get_observation_citation({ + "observation_resource_key": "", + "verbosity": "medium", + "activity_block_index": 3 + }) + ``` + + + +Activity timelines can be large. Use low or medium verbosity and request one `activity_block_index` returned by the tool at a time. The citation tool can return timelines only for the authenticated user's own sessions; if it cannot retrieve one, state that limitation rather than treating the observation summary as primary evidence. + +## Choose the build method + +For a bounded task, ask the assistant to load the Agent Builder skill method through [`get_agent_builder_instructions`](/tools/agent-builder). [The non-technical track](/transformation/non-technical-track#build-one-skill) includes a complete example. + +For a compound build, use the Agent Development Kit sequence served through the MCP. The method guides objective setting, evidence review, design, implementation, evaluation, and deployment in the coding harness. Continue with [the technical track](/transformation/technical-track). + +## Connect securely + +Use OAuth for interactive clients that support it. Use a workspace-scoped API key for headless or automated connections, store it outside the repository, and rotate it if exposed. Both methods preserve the permissions of the Within user and workspace behind the connection. See [Authentication](/authentication) and the setup page for your client. + + + Connecting the Within MCP does not authorize an external action. Configure write access, approvals, and credentials in the AI client or destination system that performs the action. + From fee1ae274607c1cac245f76098b0047fa897f660 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 6/9] Raise the customer-facing transformation bar Replace internal shorthand, promotional claims, and unsupported absolutes with explicit evidence and control guidance. Correct maintenance to match the read-only MCP contract: the client owns baselines and diffs, while Within supplies current process data. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/guides/find-opportunities.mdx | 23 ++++---- docs/transformation.mdx | 10 ++-- docs/transformation/company-brain.mdx | 36 ++++++------ docs/transformation/maintain-agents.mdx | 61 +++++++++++++++++---- docs/transformation/non-technical-track.mdx | 16 ++++-- docs/transformation/objective.mdx | 30 +++++++--- docs/transformation/opportunity-loops.mdx | 4 +- docs/transformation/readouts.mdx | 11 ++-- docs/transformation/technical-track.mdx | 28 +++++----- docs/transformation/use-case-selection.mdx | 28 ++++++---- docs/transformation/what-you-can-build.mdx | 6 +- 11 files changed, 161 insertions(+), 92 deletions(-) diff --git a/docs/guides/find-opportunities.mdx b/docs/guides/find-opportunities.mdx index a0989ee..714002f 100644 --- a/docs/guides/find-opportunities.mdx +++ b/docs/guides/find-opportunities.mdx @@ -1,14 +1,14 @@ --- title: "Find transformation opportunities" -description: "Rank the highest-leverage automation and transformation candidates across the index." +description: "Find and rank automation and transformation candidates across the process index." icon: "magnifying-glass-chart" --- -A platform lead, AI architect, or transformation owner asks where to focus next. This is the "spin up multiple agents to scan the entire process tree" use case — agents should fan out in parallel across the hierarchy. +Use this pattern when a platform lead, AI architect, or transformation owner needs a broad scan of the process tree. Independent process reads can run in parallel, but the scan still needs a bounded scope, evidence threshold, and stopping condition. ## Example prompts -- "Find the highest-leverage automation opportunities in our P2P value stream." +- "Find the automation opportunities with the strongest evidence and expected impact in our procure-to-pay value stream." - "Where in our close cycle should we focus next?" - "Scan our org for duplicate invoice processing across geographies." @@ -23,14 +23,14 @@ A platform lead, AI architect, or transformation owner asks where to focus next. For each leaf: - - [`get_process_details`](/tools/process-index) — current version, steps, dependencies. Note step count, manual vs system steps, exception count. - - [`get_process_observations`](/tools/observations-and-changes) — exception volume per process (default summary verbosity). + - [`get_process_details`](/tools/process-index) — current version, steps, dependencies, and relevant attributes. + - [`get_process_observations`](/tools/observations-and-changes) — a bounded set of captured runs in summary mode. Record the returned count without treating it as total process volume. The MCP is stateless per call, so independent reads can run in parallel. Cap each batch so the scan stays within the routine's time and output budget. - + Call [`search`](/tools/entry-points) directly on the index with pattern queries: "manual approval", "duplicate entry", "data re-keying", "exception handling", "swivel-chair workflow". For each hit, [`fetch`](/tools/entry-points) the process to confirm the pattern is real, not just a name match. @@ -38,11 +38,12 @@ A platform lead, AI architect, or transformation owner asks where to focus next. For each top candidate: - - [`get_process_observations`](/tools/observations-and-changes) with `verbosity="full"` — confirm the deviation or manual pattern with concrete evidence. + - [`get_process_observations`](/tools/observations-and-changes) with `verbosity="summary"` — identify representative runs and competing evidence. + - [`get_observation_citation`](/tools/observations-and-changes) at low or medium verbosity — inspect one activity block at a time for the material behavioral claims the brief will make. - Read the `dependencies` field already returned by [`get_process_details`](/tools/process-index) for a first cut at blast radius. - Process IDs, observation counts, dependency depth, similarity to known patterns, evidence trail. + Include process identifiers, the bounded observation count, dependency depth, pattern signal, counterevidence, uncertainty, and the next validation step. @@ -50,7 +51,7 @@ A platform lead, AI architect, or transformation owner asks where to focus next. The candidate set below is synthetic. Its identifiers and counts show the shape of a useful result, not customer data. -| Rank | Process | Observations | Dependency depth | Pattern signal | Evidence pointer | +| Rank | Process | Observations reviewed | Dependency depth | Pattern signal | Evidence pointer | |---|---|---:|---:|---|---| | 1 | Resolve shipment exceptions | 12 | 3 | Staff gathered the same context manually in 9 of 12 captured runs | `process-example-001`; `observation-example-101` to `observation-example-109` | | 2 | Reconcile supplier statements | 8 | 2 | Six runs repeated an export, comparison, and re-entry sequence | `process-example-002`; `observation-example-201` to `observation-example-206` | @@ -61,6 +62,6 @@ The first candidate ranks highest because the repeated pattern has the broadest ## What to surface in the brief - A ranked list of candidate processes -- For each: observation count, dependency depth, pattern signal -- Citable process IDs and observation timestamps +- For each: bounded observation count, dependency depth, pattern signal, and counterevidence +- Citable process resource keys and observation resource keys or timestamps - Gaps where the workspace doesn't have enough evidence yet diff --git a/docs/transformation.mdx b/docs/transformation.mdx index 270d727..3424a2b 100644 --- a/docs/transformation.mdx +++ b/docs/transformation.mdx @@ -6,13 +6,13 @@ icon: "compass" The motion has three phases. [Discover](/transformation/company-brain) captures how work happens, [Structure](/transformation/company-brain#structure) makes sense of it, and Improve builds skills and agents on top. Within runs this as a continuous loop rather than a one-time project. See [Discover → Structure → Improve](/concepts/discover-structure-improve) for the model itself; these pages are how you run it. -Start by naming a high-level business objective and the technology stack you want to build within. Within respects the enterprise stack and won't recommend a competitor's tools. +Start by naming a business objective and the technology constraints the solution must satisfy. These constraints keep the recommendation tied to systems your organization can approve and operate. ## The Company Brain -These pages use **Company Brain** for the living map of how your organization actually runs. It is what the portal's two intelligence layers add up to: the [Process Index](/concepts/process-index), which holds every process with its steps, dependencies, and versions, and [Artifacts](/concepts/artifacts), the source documents and recordings behind them. +These pages use Company Brain for the living map of how your organization operates. It combines the [Process Index](/concepts/process-index), which holds processes with their steps, dependencies, and versions, with [Artifacts](/concepts/artifacts), the source documents and recordings behind them. -Everything you build draws on it. That is what separates a build grounded in how your business actually works from one built against a generic template. +Use this evidence to test assumptions about the process instead of relying on a generic template. ## Where to start @@ -33,13 +33,13 @@ Everything you build draws on it. That is what separates a build grounded in how Connect the objective, impact, evidence, uncertainty, and next decision. - Choosing the right problem beats choosing how to build it. + Screen candidates against evidence, feasibility, controls, and materiality. Skills, Integration Flows, Managed Agents, and context bundles. - Four surfaces, split across a non-technical and a technical track. + Choose between Advisor and an AI client connected through the MCP. A build is a product. Refresh it as the business moves. diff --git a/docs/transformation/company-brain.mdx b/docs/transformation/company-brain.mdx index 85328ac..579a8de 100644 --- a/docs/transformation/company-brain.mdx +++ b/docs/transformation/company-brain.mdx @@ -4,19 +4,19 @@ description: "Turn on Companion to capture how work actually happens, then spend icon: "brain" --- -The Company Brain is what everything else is built on. This page covers the first two phases of the motion: capturing how work happens, and making sense of it. +The Company Brain provides the process context used throughout the transformation workflow. This page covers the first two phases: capturing how work happens and reviewing what was captured. ## Discover -[Companion](/concepts/discover-structure-improve) is how you build the Company Brain. Your team turns it on and works normally. There is nothing to learn and no documentation to write. As they work, Companion observes how the work actually gets done, scrubs PII and user attribution, and assembles a living, queryable map of how the organization really operates, down to the button-click level and packaged into value streams. +[Companion](/concepts/discover-structure-improve) captures work as participating team members perform it. It processes the captured activity to remove detected PII and user attribution, then organizes the result into a queryable map of processes and value streams. -Because capture runs in parallel across everyone in scope, you cover a whole function in days. That is a picture months of one-on-one interviews could never produce. The Interviewer fills the gaps Companion can't observe. +Capture can run across several people at once, which helps reveal process variation that interviews and written procedures may miss. The Interviewer can add context for work Companion cannot observe. -Running Discover well is a real motion, not a switch you flip. +Discover still needs a defined scope, clear communication, and enough coverage to support the decisions you plan to make. - People run it in the background of their normal work. There is nothing new to learn. + Follow the deployment guidance for your environment, then have participating team members use it while they perform the work in scope. @@ -24,25 +24,23 @@ Running Discover well is a real motion, not a switch you flip. - Include enough people, and enough of the natural variation, that the Company Brain comes out rich rather than thin. One user gives a sliver. A representative cross-section gives the real picture. + Include enough people and natural variation to support the intended analysis. A single person's sessions may not represent the process across roles, regions, or exception types. - Bring everyone together on a call, ideally in person, and start as a group. A shared start drives shared momentum. + Explain the scope, collection period, support path, and expected participation before capture begins. - Be transparent about how it works and what's in it for them: no SOPs to write, no interviews to sit, PII scrubbed and nothing attributed to them, and making their work visible is what lets AI take the grunt work off their plate. - - Naming the fear directly, that this is not about automating people out of a job but about taking the drudgery off their plate, is what turns skeptics into participants. + Be transparent about what Companion captures, how the data is processed, who can access the result, and how the analysis will be used. Address questions about privacy and role impact directly rather than leaving participants to infer the answers. - Frame this as something they are shaping, not something done to them. The people doing the work are the experts, and their input directly shapes what gets built. + Give the people doing the work a way to correct missing context and review conclusions that affect their process. - Ask people to contribute Signals during sessions, flagging what they already do well. Signals surface the bright spots and repeated practices that make the best skills. + Ask people to contribute Signals during sessions, including effective practices and recurring friction that may not be clear from the activity sequence alone. @@ -52,13 +50,19 @@ Running Discover well is a real motion, not a switch you flip. ## Structure -Once Companion has run, the platform turns the captured activity into your Company Brain. Before building anything, spend time in it. The teams that explore first make far better build choices later. +Once Companion has run, review the resulting Company Brain before selecting a build. This is where you check whether the available evidence supports the scope and assumptions behind the objective. + +### Explore the visualizations + +Start at the value-stream level and drill down to the processes relevant to the objective. + +### Review the process steps -**Explore the visualizations.** Within packages thousands of process nodes into value streams and maps you can navigate. Start at the value-stream level and drill down. +Inspect the captured activities to see where time goes, handoffs fail, or people move repeatedly between tools. -**Review the process steps.** Go to the button-click level to see how work actually happens: where time goes, where handoffs drop, where tools multiply. +### Ask Advisor -**Ask Advisor.** When something looks off or interesting, ask. Advisor can drive process-excellence analysis, surface cost optimizations, generate visualizations, and run time-and-motion views. +When a pattern needs explanation, ask Advisor to analyze it, generate a visualization, or prepare a time-and-motion view. ```text How does our vendor-onboarding process actually work today, and where do we diff --git a/docs/transformation/maintain-agents.mdx b/docs/transformation/maintain-agents.mdx index a3be8cd..4bbf755 100644 --- a/docs/transformation/maintain-agents.mdx +++ b/docs/transformation/maintain-agents.mdx @@ -1,28 +1,67 @@ --- title: "Keep agents current" -description: "An agent built against last quarter's process drifts. Diff it against the Company Brain and refresh what moved." +description: "Compare an existing build with current process evidence and retest what changed." icon: "arrows-rotate" --- -A build is a product, not a one-time artifact. As the business changes, an agent built against last quarter's process drifts out of step with reality and its accuracy degrades. +A released agent depends on process assumptions, source material, tool contracts, and controls that can change. Maintenance starts by recording those dependencies when the agent ships, then checking them on a defined schedule or after a known process change. -## The update step +## Record the baseline -Point your assistant at a repository of your existing agents and run it against the Company Brain. It pulls fresh process data, diffs it against what each agent was built on, classifies the drift, and proposes the rebuild. +Keep the following with the agent's code and evaluations: -Classification matters here. A renamed field is noise. A new compliance step is not. +- the process resource key and version used for the build +- the observation set or evidence summary used to justify behavior +- the policies, dependencies, tools, and model configuration the agent relies on +- the evaluation set and release result +- the owner and next review date + +This gives the next review a known comparison point. The Within MCP supplies the current process evidence; your repository or AI client stores the prior baseline and performs the comparison. + +## Review current evidence + +Start with the recent workspace change feed, then retrieve the current details for processes used by the agent. + +```javascript +get_recent_process_changes({ "limit": 50 }) + +get_process_details({ + "process_resource_key": "", + "scope": ["tasks", "dependencies", "policies", "history"] +}) +``` + +`get_recent_process_changes` returns a bounded feed of recent changes. It does not accept a date cutoff, so do not treat it as proof that nothing changed before the returned window. Use the saved resource keys and versions to check each process the agent depends on. + +Where behavior matters, review current observations as well. Captured activity can show that the documented process stayed the same while execution, exceptions, or systems changed. + +## Classify the change + +Not every difference requires the same response. + +| Change | Example | Response | +|---|---|---| +| Presentation | A field or step was renamed without changing its meaning | Update references and rerun affected evaluations | +| Behavioral | A rule, exception, input, or handoff changed | Revise the build and rerun the full evaluation set | +| Structural | The objective, owner, system boundary, or required approval changed | Return to use-case selection and design before rebuilding | + +The classification is a review decision, not an MCP verdict. Confirm material changes with the process owner before changing production behavior. + +## Ask for a maintenance review ```text -Our process changed. Run this agent's repo against the company brain and tell -me what's drifted and what to refresh. +Compare this agent's saved process baseline with the current Company Brain. +List the changes, classify each as presentation, behavioral, or structural, +and identify the evaluations that must run again. Do not modify the agent until +I approve the proposed response. ``` -## Why this compounds +## Use a recurring cadence -Because [Companion](/transformation/company-brain) keeps running, the Company Brain always reflects current reality. Transformation compounds instead of decaying. +Run [Companion](/transformation/company-brain) often enough to cover the process and exceptions the agent depends on. A maintenance review is only as current as the underlying capture and published process version. -That is also why Discover is worth running on a recurring cadence rather than once. The refresh is only as good as the picture behind it. +After an approved update, save the new baseline, run the required evaluations, and record the release result. Keep the previous version available for rollback according to your deployment controls. - [Recent process changes](/tools/observations-and-changes) is the tool your assistant reaches for to see what moved since a given date. + [Process observations](/tools/observations-and-changes) documents the change feed, observation summaries, and activity timelines used in this review. diff --git a/docs/transformation/non-technical-track.mdx b/docs/transformation/non-technical-track.mdx index 1158eb8..87c8c6f 100644 --- a/docs/transformation/non-technical-track.mdx +++ b/docs/transformation/non-technical-track.mdx @@ -10,9 +10,9 @@ The people who do the work know the exceptions, judgment calls, and source mater This track builds skills and simple agents. Compound agents are [the technical track](/transformation/technical-track). -## Run a recurring hackathon ritual +## Run recurring build sessions -Bring people together on a regular cadence, in person or virtual, to build. In the session they use Advisor and the MCP to turn their own repeated work into skills and reusable prompts. The act of building together is what creates fluency and buy-in. It cannot be lectured into a team. +Bring people together on a regular cadence, in person or virtual, to build. In each session, they use Advisor or an MCP-connected client to turn repeated work into skills and reusable prompts. Repeated practice gives the team direct experience reviewing instructions, finding failure cases, and deciding what is safe to share. ```text Find the thing my team repeats most in monthly close that a skill could take @@ -28,9 +28,13 @@ skill, and show me the before-and-after workflow. Either works, with a clear tradeoff. -**Advisor** guides the build inside Within and produces a before-and-after workflow diagram. Use it when you want the analysis and resulting artifact to remain in Within. +### Advisor -**The MCP** brings Company Brain evidence into the chat app a person already uses. Use it when the build also needs files or connectors available in that client. +Advisor guides the build inside Within and produces a before-and-after workflow diagram. Use it when you want the analysis and resulting artifact to remain in Within. + +### MCP-connected client + +The MCP brings Company Brain evidence into the chat app a person already uses. Use it when the build also needs files or connectors available in that client. ```text From Claude, using the Within MCP plus my email and Slack, draft a skill that @@ -134,7 +138,7 @@ documented process. Test the package with ordinary cases, missing inputs, conflicting evidence, and requests that should be refused. A useful skill is defined as much by where it stops as by what it produces. -## Stand up an AI committee +## Create a review group A small cross-functional committee can review the use cases and skills coming out of sessions, decide which ones are safe to distribute, and assign an owner for maintenance. @@ -154,7 +158,7 @@ Ship approved skills through your AI platform's organization controls or publish Within's team can facilitate the build session, help review the resulting skills, and work with you on production readiness. -## Why this drives culture +## Support adoption This track works when leaders use the same tools they ask teams to adopt and when people have a recurring place to build, test, and improve skills from their own work. diff --git a/docs/transformation/objective.mdx b/docs/transformation/objective.mdx index 67aa4f0..5d6124e 100644 --- a/docs/transformation/objective.mdx +++ b/docs/transformation/objective.mdx @@ -4,23 +4,37 @@ description: "Name the enterprise outcome in plain business terms before choosin icon: "bullseye" --- -It's worth being deliberate about the objective before anything else. AI, agents, and skills are powerful means. The objective itself is an enterprise outcome: growing revenue, lowering cost, or reducing risk. Naming that outcome in plain business terms early gives the whole effort a clear yardstick and keeps the work pointed at results that matter to the business. +Define the objective before choosing a technology. State the business outcome, how it will be measured, who owns it, and the constraints the solution must satisfy. ## What a well-formed objective does -**Leads with the outcome, not the means.** Start from the problem and the result you want rather than the technology. Say "our month-end close takes eight days and three late nights" rather than "we want a close agent." Keeping the objective means-agnostic lets the best solution emerge, whether that turns out to be a skill, an Integration Flow, an agent, a process change, or no build at all. +### Lead with the outcome, not the means -**Connects to a lever of enterprise value.** The clearest objectives ladder up to growing revenue, lowering cost, or reducing risk, the outcomes leadership is already working toward. Anchoring there keeps the effort focused on what moves the business. +Start from the problem and the result you want rather than the technology. Say "our month-end close takes eight days and three late nights" rather than "we want a close agent." This leaves room for a skill, Integration Flow, agent, process change, or a decision not to build. -**Is measurable, with a baseline and a target.** Name the metric, where it stands today, where you'd like it to be, and by when. "Cut the close from 8 days to 5 within two quarters." You'll quantify the baseline precisely in [Discover](/transformation/company-brain); it helps to commit to the metric now. +### Connect to enterprise value -**Has an owner.** Tie the objective to the executive who owns the outcome, the CFO for the close, the CRO for pipeline, so it stays anchored as the work progresses. +State whether the objective is expected to grow revenue, lower cost, reduce risk, or affect another metric your organization already tracks. -**Is scoped to something winnable.** Bound it to a value stream, function, or process family. "Order-to-cash in the North America billing team" rather than "transform finance." Big enough to matter, small enough to show a result in a quarter. +### Set a baseline and target -**Names constraints up front.** Non-negotiables shape which solutions fit, so it helps to state them early: "no net-new engineering," "must run inside our existing stack," "human approval for anything customer-facing," along with any regulatory, data-residency, budget, or timeline limits. These become the guardrails the assistant works within. +Name the metric, where it stands today, the target, and the deadline. For example: "Cut the close from 8 days to 5 within two quarters." Confirm the baseline with current evidence during [Discover](/transformation/company-brain). -**Stays separate from the use cases.** One objective usually points to several possible use cases, so there's no need to commit to a specific build yet. Selection comes later, in [Pick the right use case](/transformation/use-case-selection). The objective is the destination, the use cases are the route. +### Assign an owner + +Tie the objective to the executive or process owner accountable for the outcome. + +### Bound the scope + +Name the value stream, function, or process family. "Order-to-cash in the North America billing team" is testable; "transform finance" is not. + +### Name constraints up front + +State regulatory, data-residency, budget, timeline, human-approval, and technology constraints. These determine which solutions can move forward. + +### Keep use cases separate + +One objective may point to several possible use cases, so do not commit to a build yet. Selection comes later in [Pick the right use case](/transformation/use-case-selection). ## A simple test diff --git a/docs/transformation/opportunity-loops.mdx b/docs/transformation/opportunity-loops.mdx index 81a6ead..97860bc 100644 --- a/docs/transformation/opportunity-loops.mdx +++ b/docs/transformation/opportunity-loops.mdx @@ -21,7 +21,7 @@ This is not workflow automation. The loop watches for opportunities; it does not ## Define the optimization function -The prompt needs a stable answer to "what do I care to look for?" Without it, each tick can rank the same evidence differently and create noise. +The prompt needs a stable answer to "What should this scan prioritize?" Without it, each tick can rank the same evidence differently and create noise. Define: @@ -89,7 +89,7 @@ get_process_observations({ get_observation_citation({ "observation_resource_key": "observation-example-101", "verbosity": "medium", - "activity_block_index": 0 + "activity_block_index": 3 }) ``` diff --git a/docs/transformation/readouts.mdx b/docs/transformation/readouts.mdx index e8cb5b4..61cdc12 100644 --- a/docs/transformation/readouts.mdx +++ b/docs/transformation/readouts.mdx @@ -61,7 +61,7 @@ get_process_observations({ get_observation_citation({ "observation_resource_key": "observation-example-101", "verbosity": "medium", - "activity_block_index": 0 + "activity_block_index": 3 }) ``` @@ -145,9 +145,10 @@ Objective Reduce delayed shipments and avoidable customer contacts. Impact -Observed review time is 11 minutes per case. At the assumed volume of 1,200 cases -per month, the process uses about 220 hours per month. At the assumed blended FTE -rate of $58 per hour, that is $153,120 in annual handling capacity. +Median review activity across five captured runs was 11 minutes. Applied to the +assumed volume of 1,200 cases per month, the process uses about 220 hours per month. +At the assumed blended FTE rate of $58 per hour, that is $153,120 in annualized +labor capacity value. [observation-example-101 through observation-example-105] Evidence @@ -181,7 +182,7 @@ rates to accept, revise, or stop the proposed change. Use a small set of standard sections so reviewers know where to find the objective, impact, evidence, assumptions, recommendation, and next decision. The narrative should still follow the sponsor's stated outcome rather than the order in which the analysis happened. -### Learnings +### Quality checks - Business context belongs first. "No stated objective" is the most serious failure because it leaves the readout without a decision frame. - Write the deep analysis to a file before producing the deck. Early compression hides weak evidence and unresolved questions. diff --git a/docs/transformation/technical-track.mdx b/docs/transformation/technical-track.mdx index 93ca380..46968d1 100644 --- a/docs/transformation/technical-track.mdx +++ b/docs/transformation/technical-track.mdx @@ -4,19 +4,19 @@ description: "Build compound agents in the coding harness your engineers already icon: "code" --- -This track is for technical builders, a developer or your AI Center of Excellence. What makes it distinct isn't a single tool. It's that you work in the coding harness your engineers already use, [Codex](/install/codex), [Claude Code](/install/claude-code), or the [Gemini CLI](/install/gemini-cli), iterating at the code level to build compound agents. +This track is for developers and AI platform teams. You work in the coding harness your engineers already use, such as [Codex](/install/codex), [Claude Code](/install/claude-code), or the [Gemini CLI](/install/gemini-cli), and build compound agents at the code level. The non-technical track builds skills and simple agents. This track builds the compound ones. ## The Agent Development Kit -The Agent Development Kit (ADK) is the throughline. It's a disciplined sequence that runs from a business objective to a tested, deployed agent, grounded at every step in your [Company Brain](/concepts/process-index) rather than guesswork. +The Agent Development Kit (ADK) defines the build sequence from a business objective to a tested, deployed agent. Each stage uses current [Company Brain](/concepts/process-index) evidence where the process is relevant to the decision. - There is nothing separate to install. The ADK methodology is served from the MCP itself. Once Within is connected in your harness, ask your assistant to build something and it calls [`get_agent_builder_instructions`](/tools/agent-builder), then follows what comes back, fetching supporting material with `get_agent_builder_resource` as it needs it. + You do not install a separate ADK package. The method is served through the MCP. Once Within is connected in your harness, the assistant calls [`get_agent_builder_instructions`](/tools/agent-builder) and follows the returned method, retrieving the supporting resources it names. -That has a practical consequence worth knowing. There is no plugin version to track and nothing to keep updated. The methodology your assistant follows is whatever the MCP is serving right now, so improvements reach you the next time you build. +Because the method is served at build time, start each new build by retrieving the current instructions. Version the code, configuration, evaluations, and evidence baseline that the build produces in your own repository. ```mermaid flowchart LR @@ -29,7 +29,7 @@ flowchart LR ## The sequence -At every step the assistant can do the work, or your team can do it themselves. The ADK brings rigor and speed. The Company Brain is what unleashes it, because every step is grounded in observed work. +The assistant guides the sequence and produces the build artifacts in your harness. Your team supplies the objective, constraints, approvals, and technical judgment. Company Brain evidence grounds process claims, but it does not replace security review, system documentation, or runtime testing. The prompts below are what a builder types in their harness with Within connected. @@ -64,11 +64,11 @@ The prompts below are what a builder types in their harness with Within connecte - Generate candidate use cases and screen them down to the highest-leverage one that is feasible now. + Generate candidate use cases and screen them against evidence, expected impact, feasibility, and required controls. ```text - Find the highest-leverage automation opportunities in this process, rank - them, and flag which are feasible to ship now. + Find automation opportunities in this process, rank them by evidence and + expected impact, and flag which are feasible to ship now. ``` Apply the screens in [Pick the right use case](/transformation/use-case-selection). The [Find transformation opportunities](/guides/find-opportunities) guide covers the tool chain behind this step. @@ -92,11 +92,11 @@ The prompts below are what a builder types in their harness with Within connecte - Generate and run evaluations. This is the hard but essential work of putting an agent through its paces before it ships. + Generate and run evaluations before release. Include ordinary cases, edge cases, malformed or missing inputs, and requests the agent should refuse. ```text Test this. Generate an eval suite with edge cases and should-not-fire cases, - run it against real data, and ship on pass. + run it against approved test data, and report the evidence for each result. ``` @@ -113,19 +113,19 @@ The prompts below are what a builder types in their harness with Within connecte Compound agents, managed, orchestrated, or custom SDK-built, and deterministic Integration Flows. See [What you can build](/transformation/what-you-can-build) for how the primitives differ and when each one fits. -Two disciplines run throughout. Every recommendation cites observed data, and a human signs off at each step. +Two controls run throughout. Material process claims cite observed data, and a person approves the design and release gates. ## Artifacts are part of the value -The current-state reads and recommendations come out as clear, visual HTML artifacts. The assistant generates them as it works. Showing these to non-technical stakeholders is one of the best ways to win business buy-in for a build. +The current-state read and recommendation can be generated as visual HTML artifacts. Use them to review the evidence, assumptions, controls, and proposed change with stakeholders before implementation. ## Keeping agents current -An agent built against last quarter's process drifts as the business changes. See [Keep agents current](/transformation/maintain-agents) for how to diff a repository of existing agents against the Company Brain and refresh what has moved. +An agent can drift as the process changes. See [Keep agents current](/transformation/maintain-agents) for how to compare an existing build with current Company Brain evidence and decide what needs to be retested. ## Within support -Within's FDEs can work alongside your engineers to build the agents, get them into production, and define the test and eval suites. +Within's team can work with your engineers on implementation, production readiness, and evaluation design. ## Related diff --git a/docs/transformation/use-case-selection.mdx b/docs/transformation/use-case-selection.mdx index df82561..094ba5f 100644 --- a/docs/transformation/use-case-selection.mdx +++ b/docs/transformation/use-case-selection.mdx @@ -1,22 +1,24 @@ --- title: "Pick the right use case" -description: "Choosing the right problem is higher-leverage than choosing how to build it." +description: "Screen candidate use cases against evidence, feasibility, controls, and materiality." icon: "list-check" --- -> The hard part isn't building agents. It's knowing which agents to build. -> -> Heard in a public company boardroom. - -Selection comes first. Choosing the right problem is higher-leverage than how you build it, and it's where most of the value, or the wasted effort, is decided. +Select the problem before choosing the implementation. A technically successful build still fails its purpose if the use case is unsupported by process evidence, difficult to control, or too small to justify its operating cost. ## The screens -**Mind the jagged frontier.** AI is unevenly capable, strong at one task and surprisingly weak at an adjacent one. Don't assume a use case is feasible because a neighbor is. Carry several candidates and test each. +### Account for uneven model capability + +AI can perform well on one task and fail on an adjacent one. Do not assume a use case is feasible because a similar one worked. Carry several candidates into testing. + +### Account for the required accuracy -**Favor problems that don't demand multiple nines of accuracy.** The best early candidates are high-volume and repeatable, have data already in the Company Brain, and carry an error cost a human gate can absorb. +Early candidates are easier to test when the work is frequent, the inputs already appear in the Company Brain, and a person can catch likely errors before they cause harm. Work that requires near-perfect accuracy needs stronger deterministic controls and may not suit an agent. -**Qualify each candidate** against three tests: +### Qualify each candidate + +Apply three tests: | Test | What it means | |---|---| @@ -24,9 +26,13 @@ Selection comes first. Choosing the right problem is higher-leverage than how yo | Deployment readiness | Ships without new procurement, IT, or vendor review | | Materiality | Clears a meaningful value threshold | -**Know what not to touch.** Irreducible human judgment, a regulatory floor on human review, or volume too low to pay back are signs to decline rather than force. +### Know when to decline + +Decline a candidate when the work depends on irreducible human judgment, regulations require human review, or the expected benefit cannot justify the build and operating cost. + +### Apply an enterprise bar -**Apply an enterprise bar.** Prioritize work that spans more than one team or touches a system of record and has a durable, named owner, rather than personal-productivity hacks. +Prioritize work with a durable, named owner and a measurable effect on a team, value stream, or system of record. Separate that from improvements that benefit only one person's working style. ## Finding the candidates diff --git a/docs/transformation/what-you-can-build.mdx b/docs/transformation/what-you-can-build.mdx index a7de3a8..edf4ad5 100644 --- a/docs/transformation/what-you-can-build.mdx +++ b/docs/transformation/what-you-can-build.mdx @@ -8,7 +8,7 @@ Once you know what to solve, choose the shape it should take. Four primitives co ## Skill -The simplest primitive: an instruction package for one bounded task. Skills are small enough to review directly and can move between clients that support the same skill format. A skill is the canonical simple agent. +An instruction package for one bounded task. Skills are small enough to review directly and can move between clients that support the same skill format. ## Integration Flow @@ -52,7 +52,7 @@ Technology options considered: ## Simple and compound -Simple versus compound agents is the line between the two tracks. A simple agent does one thing, which is a skill. A compound agent chains multiple tasks and tools and typically needs an orchestration layer or SDK. +A simple agent handles one bounded task and can often be packaged as a skill. A compound agent chains tasks and tools and typically needs an orchestration layer or SDK. | | Simple | Compound | |---|---|---| @@ -66,4 +66,4 @@ Compound agents may use orchestration, multiple specialized agents, or a custom Set oversight by stakes. Every build needs human approval before release. Runtime approvals should remain wherever an action is irreversible, regulated, or expensive to correct. Reduce review only when evaluation and production evidence support the change. -Next, see [Where you build](/transformation/where-you-build) for the surfaces each of these is built on. +Next, see [Where you build](/transformation/where-you-build) to choose between building in Advisor and building from an MCP-connected AI client. From 6bb2d88934fe265da7035545189ba4cc00bc525d Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 7/9] Document L3 and L4 retrieval layers Add the hierarchy-node drill-down and name the boundary between the L3 process graph and L4 activity timelines so developers can choose the smallest evidence pull. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/transformation/where-you-build.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/transformation/where-you-build.mdx b/docs/transformation/where-you-build.mdx index 3b70e4f..f2b95d6 100644 --- a/docs/transformation/where-you-build.mdx +++ b/docs/transformation/where-you-build.mdx @@ -32,14 +32,18 @@ The client can also combine Within with other connectors. Keep the source bounda ## A developer pull pattern -Start with the smallest useful process scope, then retrieve more detail only when the task requires it. +Within exposes two useful levels of process evidence. L3 is the process graph: the process definition, hierarchy, tasks, dependencies, policies, and observation summaries. L4 is the activity timeline behind a specific observation. Start at L3 with the smallest useful process scope, then retrieve L4 evidence only for a claim that needs it. - Use [`search_processes`](/tools/process-index) when you know the topic, or [`get_process_hierarchy`](/tools/process-index) when you need to browse the process tree. + Use [`search_processes`](/tools/process-index) when you know the topic, or [`get_process_hierarchy`](/tools/process-index) when you need to browse the process tree. If the result is a hierarchy node rather than a leaf process, inspect it with `get_hierarchy_node_details` before choosing a process. ```javascript search_processes({ "query": "shipment exceptions", "top_k": 5 }) + + get_hierarchy_node_details({ + "node": { "node_resource_key": "" } + }) ``` From e61c9be0947baea4d6706494a3cebb01a9a73b81 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 8/9] Polish transformation guide copy Remove two negative-parallelism phrases flagged in review without changing the verified MCP examples or page flow. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/guides/find-opportunities.mdx | 2 +- docs/transformation/technical-track.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/find-opportunities.mdx b/docs/guides/find-opportunities.mdx index 714002f..d52261c 100644 --- a/docs/guides/find-opportunities.mdx +++ b/docs/guides/find-opportunities.mdx @@ -31,7 +31,7 @@ Use this pattern when a platform lead, AI architect, or transformation owner nee - Call [`search`](/tools/entry-points) directly on the index with pattern queries: "manual approval", "duplicate entry", "data re-keying", "exception handling", "swivel-chair workflow". For each hit, [`fetch`](/tools/entry-points) the process to confirm the pattern is real, not just a name match. + Call [`search`](/tools/entry-points) directly on the index with pattern queries: "manual approval", "duplicate entry", "data re-keying", "exception handling", "swivel-chair workflow". For each hit, [`fetch`](/tools/entry-points) the process to confirm the pattern appears in the process itself rather than only in its name. Inspect the `attributes` field already returned by [`get_process_details`](/tools/process-index) — "automation status", "system of record", "control level", or similar attributes that help rank candidates. diff --git a/docs/transformation/technical-track.mdx b/docs/transformation/technical-track.mdx index 46968d1..0e41dda 100644 --- a/docs/transformation/technical-track.mdx +++ b/docs/transformation/technical-track.mdx @@ -134,6 +134,6 @@ Within's team can work with your engineers on implementation, production readine The two tools that serve the methodology. - The same flow from any MCP client, not just a coding harness. + Use the same flow from any MCP client. From e38bad1c2007439191dfc93c8da74ec99d7ff7b0 Mon Sep 17 00:00:00 2001 From: Rohith Sathyanarayana Date: Thu, 10 Sep 2026 17:52:15 +0530 Subject: [PATCH 9/9] Add the transformation guide group Create the in-Guides navigation variant with the same page order as the tab branch and remove the duplicated opportunity guide. Readouts precede selection because they convert evidence into the decision brief. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/docs.json | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index 7d7d7b5..f5d4a42 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -72,12 +72,28 @@ "concepts/artifacts" ] }, + { + "group": "Drive AI transformation", + "pages": [ + "transformation", + "transformation/objective", + "transformation/company-brain", + "guides/find-opportunities", + "transformation/opportunity-loops", + "transformation/readouts", + "transformation/use-case-selection", + "transformation/what-you-can-build", + "transformation/where-you-build", + "transformation/non-technical-track", + "transformation/technical-track", + "transformation/maintain-agents" + ] + }, { "group": "How-to guides", "pages": [ "guides/process-performer", "guides/state-of-team", - "guides/find-opportunities", "guides/transformation-thesis", "guides/chain-with-connectors", "guides/deep-research",