Develop Lenso with an Agent

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:

npx skills add LioRael/lenso --list

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

npx skills add LioRael/lenso --all

For a user-level Codex installation:

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

The canonical source is the Lenso skill pack. Installed copies are derived artifacts. Refresh them later with npx skills update.

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

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:

Copy this template and replace the brackets:

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:

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:

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

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 for the matching manual tutorial.

Configure an existing App

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 and Configure an Agent for the file and publication models.

Build a Web backend

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 for the complete manual sequence and the current compatibility boundary.

Add Host mechanics

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:

“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:

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:

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.