Skip to content

Agent Execution Lifecycle

The agent execution lifecycle turns work into governed, reusable capability.

Audited against the current Gas City model. Beads are the durable universal substrate; mail, sessions, and convoys are bead types. Formulas encode reusable methods. Orders trigger formulas. Events provide the observable stream. Packs distribute configuration. Rigs establish project scope. Gas City explicitly treats sessions as disposable while Beads preserve work.

Central Doctrine

A Session performs work. A Bead remembers work. A Convoy groups work. Mail coordinates work. A Formula remembers how work should be performed. An Agent defines who performs it. A Rig defines where it belongs. A Pack distributes the configuration. An Order decides when reusable work runs. Events prove what happened. Bluefly governance determines whether the result becomes durable capability.

Work is not complete when code merges or a Bead closes. Work is complete when the result is verified in canonical state, its durable capability has a clear owner, the evidence survives the Session, and anything worth repeating has been promoted into the appropriate durable form: Capability, Skill, Formula, Agent configuration, Pack, Order, generator, documentation, or policy.

The Pipeline

Prompt
→ Rig
→ Agent / Authority
→ Bead
→ Dependencies / Convoy / Mail
→ Worktree
→ Context / Doctrine / Skills / Pack
→ Formula Discovery
→ Capability Discovery
→ Owner Discovery
→ Evidence
→ Change
→ Test
→ Events / Verification
→ Convergence
→ Merge
→ Post-Merge Verification
→ Capability Record
→ Promote Learning
→ Skill / Formula / Agent / Pack / Order / Generator / Policy
→ Update Bead
→ Close Bead / Convoy
→ Trigger Downstream Work
→ Cleanup Worktree / Session

1. Receive and Situate

  1. Receive the prompt. Understand the requested outcome, constraints, scope, and definition of done.

  2. Resolve the Rig. Determine the Gas City Rig in which the work belongs. The Rig establishes the project/repository, Bead namespace, and agent scope.

  3. Establish Agent identity and authority. Determine which configured Agent is acting, its provider, prompt/role, scope, and applicable Bluefly authority and policy. Do not confuse the durable Agent identity with its current execution Session.

2. Claim Work

  1. Find or create the Bead. Search for the existing durable unit of work before creating another. Create or update the Bead only when necessary so the work graph accurately represents the requested outcome.

  2. Claim the Bead. Transition the work into active ownership using the canonical Beads/Gas City lifecycle. The Bead is the durable work authority; the Session is not.

  3. Inspect the surrounding work graph. Check dependencies, blockers, parent work, related Beads, and the larger Convoy before acting. Dependencies determine when work is actually ready; Convoys group related work into a trackable batch.

  4. Read Mail. Inspect relevant inter-agent Mail attached to the durable Bead store for handoffs, findings, requests, warnings, or coordination from other agents. Mail is not a separate authority; it is another Bead type in Gas City's universal store.

3. Prepare

  1. Create the working environment. Synchronize from the canonical source and create the Bead-scoped worktree or other approved isolated execution environment. Never treat the disposable execution environment as authority.

  2. Gather project context. Search the project and BluCity-Docs with QMD and other approved discovery mechanisms before making assumptions.

  3. Load applicable doctrine. Load project instructions, Engineering Standards, architecture authority, relevant policies, upstream documentation, and current project rules.

  4. Load applicable Skills. Bring in reusable expertise required to perform the work correctly rather than reproducing that expertise ad hoc inside the session.

  5. Inspect the active Pack configuration. Determine which Pack supplies the Agent, Formula, Orders, prompts, configuration, hooks, and supporting behavior relevant to this work. Packs configure behavior; they are not durable work records.

  6. Determine whether a Formula already exists. Before inventing a procedure, check whether the task is already represented by a reusable Formula. A Formula is Gas City's reusable HOW: a written method whose steps materialize into durable Beads when run.

  7. Follow the Formula when one governs the work. Execute the established method rather than creating a competing process. Once materialized, the resulting Bead graph becomes the durable execution state and survives the Formula file and the originating Session.

4. Discover

  1. Identify the capability being changed. State what durable behavior or outcome is actually being provided. Evaluate the capability, not merely the file, script, module, command, or repository being edited.

  2. Discover the current capability owner. Determine whether the capability already belongs to native upstream functionality, configuration, extension/plugin, SDK/API, ecosystem component, organizational governance, or Bluefly.

  3. Prefer existing capability over new implementation. Exhaust native → configuration → extension → SDK/API → ecosystem/composition before adding Bluefly implementation.

5. Build

  1. Build the evidence record. Capture actual searches, upstream documentation, source inspection, CLI output, existing behavior, tests, policy decisions, dependency findings, and contradictions. Assertions from the Agent are not sufficient evidence.

  2. Maintain the Bead as the execution ledger. Continuously update the durable work record with material findings, decisions, evidence references, blockers, changes, and remaining work. Do not leave important state only in the Session's context window.

  3. Send Mail when coordination is required. Communicate findings, handoffs, dependencies, or requests to other Agents through Gas City's durable communication model rather than assuming shared conversational context.

  4. Observe relevant Events. Use the Gas City Event stream to verify activity around Beads, Sessions, Convoys, and Orders. Events are immutable, append-only observations with replayable sequence numbers; they are evidence of activity, not the work authority themselves.

  5. Make the smallest verifiable change. Modify the canonical implementation, integration point, configuration, policy, or generator rather than repairing downstream copies or symptoms.

6. Verify

  1. Test the capability. Demonstrate that the intended behavior exists. A changed file or successful command exit is not by itself proof that the capability works.

  2. Produce authoritative evidence. Prefer test output, GitLab CI, merge-request state, source commits, Gas City Events, Bead state, policy decisions, deployment observations, and other authoritative systems over narrative assertions.

  3. Verify governance. Confirm identity, authority, obligation where applicable, policy, ownership boundaries, approvals, evidence provenance, and chain of custody.

  4. Verify convergence. Ask whether the resulting capability now resides with the smallest stable owner and whether Bluefly-specific implementation or maintenance can be removed.

7. Ship

  1. Update canonical documentation. Change the authoritative documentation when the work changes architectural, operational, behavioral, or governance truth. Do not generate parallel documentation merely to describe the session.

  2. Update the Bead with final evidence. Record exact changes, tests, commits, merge requests, policy results, documentation changes, capability decisions, and verification evidence.

  3. Merge through the governed release path. Push, CI, review, MR, approval, release branch, merge, and preserve GitLab chain of custody.

  4. Verify the canonical merged state. Test the state that future Agents will actually receive, not only the temporary worktree state.

  5. Observe post-merge Events. Confirm expected Bead, Session, Convoy, Order, or other operational transitions through Gas City's Event stream when relevant.

  6. Re-verify the capability after merge. Prove that the capability still exists from its canonical owner and has not become dependent on session-local state or an unmerged artifact.

8. Promote

  1. Classify what was learned. Determine whether the verified result is merely task-specific evidence or whether it represents reusable capability.

  2. Create or update the Capability record. When work establishes, materially changes, transfers, converges, or removes a durable capability, update the canonical capability registry with its owner, consumers, lifecycle state, rationale, and evidence.

  3. Promote reusable procedure into a Formula. When the important result is a repeatable multi-step method, encode it as a Gas City Formula instead of requiring future Agents to reconstruct the procedure from prose or past Beads. Formula = reusable HOW.

  4. Promote recurring triggers into an Order. When a Formula should run because of a cron schedule, cooldown, condition, manual trigger, or Event, define an Order rather than relying on a human or Agent to remember to launch it. Orders automate when Formulas execute.

  5. Promote reusable Agent behavior into Agent configuration. When the lesson changes WHO should perform work or how that role behaves, update the Agent definition/prompt rather than burying the behavior in a one-off Bead.

  6. Promote reusable configuration into a Pack. When Agents, Formulas, Orders, prompts, or support configuration should travel together and be reused across Cities/Rigs, curate them into the appropriate Pack. Packs are the configuration/distribution boundary.

  7. Promote reusable expertise into a Skill. When successful execution depends on repeatable domain knowledge, reasoning, validation practices, tool usage, or conventions that should be available independently of a particular Gas City workflow, curate that expertise into a versioned Skill.

  8. Promote deterministic mechanics into tooling or generators. When the lesson is a repeatable mechanical transformation rather than agent reasoning, implement it once in the canonical CLI, generator, CI job, hook, provider, or other deterministic owner.

  9. Promote governance rules into policy. When the lesson defines what an actor may, must, must not, or is obligated to do, encode it in the authoritative policy/standard rather than relying on a prompt, Formula, or Agent memory.

  10. Update the Pack when orchestration configuration changed. If the new capability changes Agents, Formulas, Orders, hooks, prompts, or reusable City configuration, update the owning Pack rather than making a local City-only copy unless the behavior truly is local.

9. Close

  1. Complete dependent Beads. Close the work units produced by the Formula or task graph only when their individual completion criteria and dependencies are actually satisfied.

  2. Allow the Convoy to converge. Related work remains grouped until the complete batch is done. The Convoy should provide durable visibility into whether the larger objective actually completed.

  3. Close the Bead. Close durable work only after the requested outcome, required evidence, and governance conditions are satisfied.

  4. Allow dependent work to become ready. Closing a Bead may unblock dependencies elsewhere in the graph. Gas City uses those durable edges rather than a central task list to determine readiness.

  5. Allow Orders and Events to continue the lifecycle. Completion may emit Events that trigger subsequent Orders and Formulas, allowing verified capability to participate in autonomous factory operation rather than ending with a human handoff.

10. Cleanup

  1. Remove the worktree. Destroy the disposable execution environment once the canonical result and evidence are safely preserved.

  2. End the Session. The Session may disappear without losing the work. Gas City explicitly treats Sessions as disposable and keeps durable state in Beads.

  3. Preserve the factory improvement. What remains should be the Bead graph, Convoy history, Mail, Events, source change, evidence, capability record, documentation, Skill, Formula, Order, Pack configuration, policy, and provenance necessary for another Agent to continue without reconstructing the previous Session.

Content Becomes Capability

Information discovered during execution only graduates into doctrine when it is:

  • Verified — tested, not merely asserted
  • Generalized — applicable beyond the single task
  • Assigned an owner — placed with the smallest stable canonical owner
  • Located in the correct durable form — Capability, Skill, Formula, Agent configuration, Pack, Order, generator, documentation, or policy
  • Reusable by future executions — the next Agent can use it without the previous Agent's memory or Session

This fits Gas City's architecture because it does not invent a parallel learning lifecycle. It uses Gas City's existing machinery for durable execution and makes capability promotion the governance layer on top of it. Beads are the durable universal substrate; Formulas materialize methods as Bead graphs; Orders automate those methods; Events make execution observable; and Sessions can disappear without taking the work with them.