---
title: Develop Lenso with an Agent
description: Install Lenso's six development skills, route work to the right owner, and drive a coding agent from source inspection to observable delivery.
---

This is the recommended starting point when a coding agent will build or change
something in Lenso. The six Lenso skills give the agent an ordered workflow for
product planning, Capability contracts, Plugin behavior, App configuration,
and Host mechanics. They do not replace repository source, `--help`, tests, or
review; they tell the agent which evidence to inspect and what “done” means.

By the end of this guide you can give an agent one concrete request, watch it
select the owning workflow, and require an inspectable implementation and
delivery report.

## 1. Install the skill pack

Inspect the published catalog:

```sh
npx skills add LioRael/lenso --list
```

Install all six skills for the project agents detected by the installer:

```sh
npx skills add LioRael/lenso --all
```

For a user-level Codex installation:

```sh
npx skills add LioRael/lenso \
  --skill '*' \
  --agent codex \
  --global \
  --yes
```

The canonical source is the
[Lenso skill pack](https://github.com/LioRael/lenso/tree/main/skills). Installed
copies are derived artifacts. Refresh them later with `npx skills update`.

Installation is complete when the agent can see these exact names:

```text
lenso-start
lenso-business-planning
lenso-capability-authoring
lenso-plugin-authoring
lenso-app-configuration
lenso-runtime-extension
```

If `lenso-app-composition` appears instead of `lenso-app-configuration`, the
installed pack is stale. Update it before asking the agent to change an App.

## 2. Start with a bounded request

Give the agent four inputs:

| Input | What to say | Why it matters |
| --- | --- | --- |
| Outcome | What a person or another Plugin can do afterward | Prevents architecture-only output |
| Authority | Repository, package, current Host, and existing contract when known | Keeps source selection explicit |
| Constraints | Language, target, compatibility, security, and allowed delivery actions | Prevents scope expansion |
| Completion | Behavior, honest failure, removal, checks, and delivery state | Prevents premature completion |

Copy this template and replace the brackets:

```text
Use $lenso-start to route and complete this Lenso task.

Outcome: [one observable user or Plugin result]
Authority: [repository, package, Host, Capability, or say unknown]
Constraints: [language, target, compatibility, security, and delivery scope]
Completion:
- [success that must be exercised]
- [honest failure that must remain distinguishable]
- [configuration, lifecycle, or removal proof when applicable]
- [checks and commit/PR/merge state requested]

Before editing, report the selected primary workflow, owning repository,
current source APIs, and any missing prerequisite. Then continue unless the
missing prerequisite would materially change the requested product result.
```

The last paragraph creates an early review point without forcing the agent to
stop for routine implementation choices.

## 3. Let `lenso-start` route the work

Use one primary workflow for the current ownership question:

| Requested result | Primary skill | Completion boundary |
| --- | --- | --- |
| Turn an unclear outcome into vertical product behavior | `lenso-business-planning` | Plugin cards, explicit Capability edges, and one tracer slice |
| Define or evolve a cross-Plugin role | `lenso-capability-authoring` | Descriptor, Schemas, generated bindings, compatibility and freshness proof |
| Implement removable behavior | `lenso-plugin-authoring` | Plugin Contract, supported implementation, real consumer path, and removal proof |
| Configure packages and Instances in one App | `lenso-app-configuration` | Reviewed `plugins/` differences, derived App, behavior and removal proof |
| Add scheduling, process, transport, endpoint, or Host mechanics | `lenso-runtime-extension` | Narrow Driver, Adapter, Runner, or Generation change with conformance and Host proof |
| Decide which row owns the request | `lenso-start` | One primary workflow and one checkable completion state |

A feature can cross several rows. The agent should finish one owner boundary,
then hand off to the next workflow. For example, a new Web API may require a
business Plugin, an HTTP Endpoint provider, and App configuration; it does not
make all three one package.

Kernel semantics are not a routine seventh workflow. Graph validation,
lifecycle, admission, invocation, readiness, supervision, or diagnostic
changes require the relevant architecture decision and portable conformance
proof.

## 4. Require source inspection before implementation

The agent should inspect, in this order:

1. repository instructions and the dirty worktree;
2. package manifests, locks, and exact dependency versions;
3. the Capability source and generated Provider/Client projections;
4. existing Plugin descriptors, factories, entrypoints, and Host registration;
5. the App's Host Catalog and visible `plugins/` differences; and
6. repository CI or local commands that prove the affected path.

This step is complete only when every API and command in the proposed change
comes from current source or installed `--help`. An ADR may explain intent, but
it is not evidence that a package, command, scaffold, or remote service ships.

Ask for a short routing report before the first edit:

```text
Return the routing report now:
- primary skill;
- owner and deletion boundary;
- current source files and package versions;
- provided and required Capabilities;
- App/Host changes;
- first success, honest failure, and removal proof;
- unsupported or missing prerequisites.
```

## 5. Use a prompt for the actual task

### Add one Plugin behavior

```text
Use $lenso-plugin-authoring to add company.uppercase as one removable Agent
Tool Plugin in Rust.

Use the current CLI scaffold and installed --help. Keep one Plugin Contract
across every packaged implementation. Exercise a successful uppercase call,
invalid arguments, package the supported implementations, install the Bundle
into the maintained Agent Host, invoke it through a real Agent Turn, then
remove it and resolve the App again. Report exact paths and commands.
```

Continue with [Give the Agent a new Tool](/docs/agent/first-app) for the matching
manual tutorial.

### Configure an existing App

```text
Use $lenso-app-configuration to change only the visible plugins/ differences
for this App.

Outcome: the review Profile uses the semantic Session presentation Instance.
Inspect the exact Host Catalog and current derived App first. Add the smallest
Instance TOML and Profile selection, keep secret values external, run app show
and app check, exercise one new Session, then remove the difference and prove
the Host default becomes visible again.
```

Continue with [Configure a Plugin](/docs/core/plugin-configuration) and
[Configure an Agent](/docs/agent/agent-configuration) for the file and publication
models.

### Build a Web backend

```text
Use $lenso-start, then the selected Plugin and App workflows, to add a JSON Web
backend with POST /greetings and GET /greetings/{greeting_id}.

Use the current lenso.http.endpoint@1 authoring API and the existing Host's
linked Web Ingress. Keep route shape in the HTTP Endpoint provider, keep
transport limits in Ingress configuration, reject malformed JSON before the
handler, prove 201, 200, 400, 404, and 405 through a real socket, and prove a
route collision fails readiness. Do not invent a generic web scaffold if the
installed CLI does not ship one.
```

Continue with [Build a Web backend](/docs/web) for the complete manual
sequence and the current compatibility boundary.

### Add Host mechanics

```text
Use $lenso-runtime-extension to add the missing Host mechanism.

Show why no existing Driver, Execution Adapter, Runner, or Plugin can own the
result. Keep the portable Kernel unchanged unless the invariant itself is
portable. Add conformance, a real Host-boundary proof, cancellation and
shutdown behavior, then report which product Plugins can now use the mechanism.
```

## 6. Control how far the agent may deliver

Say which delivery level is authorized:

| Level | Agent stops after |
| --- | --- |
| Investigate | Source-grounded findings and a proposed owner boundary; no product edits |
| Implement | Working-tree changes and proportionate checks; no commit or external publication |
| Deliver | Requested commit, PR, required checks, merge verification, and safe cleanup |

“Review” or “explain” does not authorize a PR. “Implement” does not imply
publishing packages. For delivery, state the repository and whether the agent
must stop before merge.

## 7. Review checkpoints instead of activity logs

### After routing

- primary skill and why it owns the next decision;
- owner repository and deletion boundary;
- exact current API, command, and package evidence;
- missing prerequisites that would change the requested result.

### After implementation

- changed artifact paths and generated-file freshness;
- success, Domain Error, runtime/startup failure, and lifecycle evidence;
- real consumer-to-provider or Host-boundary execution;
- configuration and Resolved Plan effects;
- optional behavior removal proof.

### After delivery

- commit and remote branch;
- PR and required checks;
- merge commit or remote tree proof;
- retained dirty or unmerged work that was deliberately not cleaned.

Architecture vocabulary, file counts, and “tests passed” without exact commands
are not completion evidence.

## 8. Recover when the agent goes in the wrong direction

Use a focused correction rather than restarting the entire task:

```text
Pause implementation and rerun $lenso-start.

The current direction appears to put [behavior] in [wrong owner]. Reinspect the
Plugin deletion boundary, Capability source, Host Catalog, and existing
Adapters. Return the corrected primary workflow and the smallest reversible
slice before continuing.
```

Common corrections:

| Symptom | Correction |
| --- | --- |
| Agent proposes Kernel work for ordinary product behavior | Route to Plugin authoring |
| Agent writes bindings by hand | Route to Capability authoring and regenerate |
| Agent changes implementation selection in App files | Keep Host policy authoritative; use App configuration only for visible differences |
| Agent treats checks as the feature | Restate the observable outcome, then keep checks as completion evidence |
| Agent claims an unshipped remote service or scaffold | Require package source, installed `--help`, or an executable owner example |

The workflow is successful when the agent can identify the owner, make the
smallest source-backed change, exercise the result through its real consumer,
and return enough evidence for another developer to rerun or review it.