Skip to main content

Agent Plugin Production Loop

Verification boundary

This page documents the committed source. Treat revision-sensitive RuneLite UI, packet, or in-game outcomes as pending live-client verification unless the page records direct evidence.

Use this loop to turn a plugin idea into source-backed n3Plugins work. Run it in the main conversation by default. The user can invoke the optional /n3-plugin skill to create local workflow files.

Before You Write​

  1. Read AGENTS.md, N3PLUGINS_SOURCE_OF_TRUTH.md, and the docs for the nearest plugin pattern.
  2. Inspect git status --short --branch and relevant diffs.
  3. Use CodeGraph to locate source symbols before making API claims. Use rg to search for literal text, configuration, and documentation.

Phase 1: Domain Review​

Check the OSRS task before designing code:

  • Game mechanics: ticks, animations, banking, supplies, prayer, run energy, instance entry, teleports, and logout risk.
  • Account gates: quests, skills, items, F2P/P2P, ironman restrictions, GE access, and area access.
  • UI assumptions: widgets, tabs, dialogue, Quest Helper markers, and hidden-widget risk.
  • Detection shape: fixed timing, fixed coordinates, missing idle delays, and route repetition.

Stop for user input when the task requires an unknown account state or a behavior choice the code cannot infer.

Phase 2: Workflow Shape​

Pick the smallest driver:

WorkflowPick when
Plain per-tick handlerLive game state decides the next action each tick
MVC controller/runtimeThe plugin requires many states, UI, async work, or testable runtime boundaries
TaskPipelineA fixed sequence requires one successful step to advance to the next
TypesafeCarouselStateMachineBranching or looping workflows use exhaustive enum states, explicit transition reasons, recovery, and terminal telemetry
Domain workflow builderExisting combat, production, banking, enchanting, or loadout builders fit the task

Skip using a pipeline for stateless dialogue or other visible-this-tick work.

Phase 3: SDK Map​

For each state, cite a real source symbol:

  1. Api.actions.* for game interactions.
  2. sdk.* for widgets, queries, walker, loadouts, and workflows.
  3. GameVars for raw varbits or varplayers.
  4. PacketUtils or Packets only when shared action APIs lack the primitive.
  5. RuneLite API as the last layer.

Write gaps plainly. The planner decides whether a gap remains local or becomes a shared SDK helper.

Phase 4: Plan​

The plan must name:

  • Files to create or modify.
  • Plugin pattern and why it fits.
  • State model, transitions, and stop conditions.
  • Thread boundaries and client-thread calls.
  • InteractionResult handling and pacing behavior.
  • Registration changes, if any.
  • Tests, docs, SOT updates, and live verification steps.

Exclude unrelated cleanup from the plan.

Phase 5: Implement​

  • Touch only the files in scope.
  • Preserve Java 11 and local style.
  • Use Api.actions.* and inspect InteractionResult.
  • Keep suite-level ActionPacer.onTick(...) and Walker.tick() inside PacketUtilsPlugin.
  • Full automation plugins register with Break Handler at startup, track only actionable active work, and pause gameplay actions during planned or active breaks. Helper-style plugins follow the exemption policy recorded in the SOT.
  • Update runelite-plugin.properties only for plugin registration changes.

Phase 6: Test​

Start narrow:

.\gradlew.bat compileJava --console plain
.\gradlew.bat test --tests com.n3plugins.<area>.* --console plain

Broaden when the change touches shared actions, SDK, walker, widgets, workflow builders, or state machines.

Phase 7: Review​

Run a code review and an anti-detection review:

  • Code review: bugs, null paths, stale widget assumptions, packet ownership, bootstrap gates, threading, tests, registration.
  • Anti-detection review: deterministic timing, unpaced interactions, exact repeated targets, direct coordinate pathing, missing idle shaping.
  • Docs review: docs match live source and SOT. Prose stays direct.

Fix Tier 1 issues before finishing docs or completion.

Phase 8: Docs And SOT​

Update the plugin doc when behavior changes. Update API docs when shared surfaces change. Update the SOT only for canonical state: registration, packages, action catalog, dependencies, validation commands, and durable workflow conventions.

Add every new canonical page to docs-site/sidebars.js, or deliberately link it from its owning page when it serves as reference material.

Phase 9: Final Verification​

Inspect the final diff, run the selected validation commands, regenerate generated docs when docs or skills changed, and record any live-client verification that remains pending.