Promptware: agents that keep and improve their own instructions

A promptware is a self-contained agent unit that stores its own instructions, memory, tool permissions, and execution history as files, and that revises its instructions and memory after each run. In Ivy Tendril, every stage of the plan lifecycle, from drafting a plan to opening a pull request, is run by one of these units. The instructions are versioned files in the repository, so they can be reviewed, diffed, rolled back, and shared across the team like any other source file. This article explains the structure of a unit, the run loop, the seven built-in promptwares, and the two failure modes to watch for.

What a promptware unit contains

A promptware unit is a directory with four parts. Each part has one job.

Part	Contents	Who writes it
Program.md	The instructions the agent follows for its stage. Revised by the agent after a run, reviewed by humans.	Agent and humans
Memory/	Persistent learnings about the codebase and the team's conventions. Appended after each run.	Agent
Tools/	The scoped permissions for this stage: which commands, files, and integrations the agent may use.	Humans
Logs/	The execution history: what the agent read, ran, and changed, and what it concluded.	Agent, append only

Program.md is prose, not code. A section for a plan-execution unit might look like this:

## Before opening a pull request

- Run `pnpm lint` and `pnpm test` from the repository root. Do not open a PR if either fails.
- Keep the diff limited to the files named in the plan. If another file must change, say so in the PR description.
- Use the commit message format `type(scope): summary`.

A memory entry records something the agent learned that is not obvious from the code and that a future run should know:

### 2026-08-21, plan #412

The billing module under `src/billing/` has no tests. Add tests before refactoring it.
`pnpm test` runs the database migrations first; a run takes about four minutes on a clean checkout.

The two files differ in kind. The program says what to do. Memory says what is true about this repository. Keeping them separate lets a reviewer accept a new fact without accepting a change to procedure, and the other way around.

The run loop

Every promptware run follows the same four steps.

1. Load the program. The agent reads Program.md and the permissions in Tools/. Nothing outside those permissions is available to it.
2. Read memory. The agent reads Memory/ so that facts learned in earlier runs are in context before it starts.
3. Execute the task. The agent does the stage's work: draft a plan, expand it, execute it in a worktree, or open a pull request. Every tool call and its output is appended to Logs/.
4. Reflect and write back. The agent compares what happened with what the program told it to expect. New facts go to Memory/. If an instruction was wrong, missing, or redundant, the agent revises Program.md.

The fourth step is what makes the instructions improve over time instead of getting worse. It is also the step that needs the most oversight, which the section on risks covers.

The built-in promptwares

Ivy Tendril ships with seven promptwares, one per stage of the lifecycle described in from GitHub issue to pull request. Each has its own program, memory, permissions, and logs.

• CreatePlan turns an idea, a GitHub issue, or a bug report into a draft plan: goal, scope, affected files, verification steps.
• ExpandPlan adds detail to a draft that lacks enough information to execute, such as missing acceptance criteria or unresolved design choices.
• UpdatePlan rewrites a draft in response to inline annotations from the developer.
• SplitPlan divides a plan whose scope has grown into several smaller plans that can run in parallel.
• ExecutePlan runs the approved plan with the chosen coding agent (Claude Code, Codex CLI, Copilot CLI, Gemini CLI, OpenCode, or any CLI agent) inside an isolated git worktree.
• CreatePr opens the pull request after the diff has passed verification and human review.
• CreateIssue files a GitHub issue from a recommendation or a finding during execution.

Because each unit is separate, the memory of CreatePlan (for example, "the team wants plans to name the test files that will change") is not shared with ExecutePlan, and ExecutePlan's permission to run shell commands is not granted to CreatePlan. The promptware documentation lists the default contents of each unit.

Versioned instructions, and the two risks

Why files in the repository beat ad hoc prompts

An ad hoc prompt typed into a chat window exists once, for one person, and is gone when the session ends. A Program.md committed to the repository has four properties that a prompt lacks.

1. Review. A change to the program is a diff in a pull request. A senior engineer can reject an instruction such as "skip tests when the change is small" before it affects any run.
2. Diff. When output quality changes, git log on the promptware directory shows which instruction changed and when.
3. Rollback. A bad revision is reverted with one commit.
4. Sharing. Every developer on the team, and every agent run, uses the same instructions. A convention learned by one run on Monday is applied by everyone on Tuesday.

This is the same argument that moved infrastructure from manual configuration to files under version control, and it holds for the same reasons. Other ways to structure agent work, and how promptware compares with them, are covered in agent orchestration patterns for coding agents.

Risk 1: instruction drift

An agent that can edit its own program can also make it worse. A run that fails on a flaky test might add "retry failing tests up to three times", which hides a real problem the next time. Two things limit this. First, the program is a versioned file, so a revision is a diff that a reviewer sees and can revert. Second, Logs/ records the run that prompted the revision, so the reviewer can check whether the reasoning holds before accepting the change.

Risk 2: memory bloat

Memory that only grows becomes a cost without a benefit. A file with 400 entries, half of them stale, costs tokens on every run and makes the useful entries harder to find. Two practices keep it usable. Date and scope each entry, as in the example above, so stale entries are easy to locate. Prune during review: when a plan touches an area, the reviewer checks the related memory entries and removes those the code no longer supports. Cost and token tracking per plan and per job makes growth visible, because a unit with a bloated memory shows a rising token count with no matching rise in plan size.

How to start

Install Ivy Tendril, open a repository, and create a plan. The seven built-in promptwares are present from the first run.

curl -sSf https://cdn.ivy.app/install-tendril.sh | sh

On Windows, use irm https://cdn.ivy.app/install-tendril.ps1 | iex. Read the Program.md files before running an execution, then review the first memory entries and program revisions with the same care as a code change. After ten or so plans, the memory will reflect the parts of the codebase where the agent had trouble, which is usually also where a human would. The promptware docs have more on the built-in units.

Frequently asked questions

Does the agent change Program.md without asking?

The agent revises its program after a run. Because Program.md is a versioned file, the revision is a diff that you can read, accept, or revert, and the log of the run that caused it is next to it.

Can I write my own promptware?

The seven built-in units cover the lifecycle stages. Their programs, memory, and tool permissions are plain files, so you can edit them to match your team's conventions. Check the documentation at the time of writing for the current extension options.

Where are the memory and logs stored?

On the machine that runs Tendril. They are not uploaded to Ivy. The only network calls Tendril makes are to the LLM API you configured and to GitHub.