Skip to main content

Agent Plugin Production Loop

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

Before You Write​

  1. State any file-writing side effects, including .codex/workflows, screenshots, logs, generated reports, or local harness output.
  2. Read AGENTS.md, N3PLUGINS_SOURCE_OF_TRUTH.md, and the docs for the nearest plugin pattern.
  3. Inspect git status --short --branch and relevant diffs.
  4. Use CodeGraph to locate source symbols before making API claims. Use rg for literal text, configuration, and documentation searches.

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 depends on 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 has many states, UI, async work, or testable runtime boundaries
TaskPipelineA fixed sequence needs one successful step to advance to the next
AutomationStateMachineNamed states branch, loop, recover, or terminate
Domain workflow builderExisting combat, production, banking, enchanting, or loadout builders fit the task

Do not use a pipeline for stateless dialogue or other visible-this-tick work.

Phase 3: SDK Map​

For each state, cite a real source symbol:

  1. InteractionApi.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 do not cover the primitive.
  5. RuneLite API as the last layer.

Write gaps plainly. The planner decides whether a gap stays 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.

Keep unrelated cleanup out of the plan.

Phase 5: Implement​

  • Touch only the files in scope.
  • Preserve Java 11 and local style.
  • Use InteractionApi.actions.* and inspect InteractionResult.
  • Keep suite-level ActionPacer.onTick(...) and Walker.tick() inside PacketUtilsPlugin.
  • While active, register account setup with PacketUtilsPlugin.requireAccountBootstrap(this) and gate gameplay actions on the returned readiness. Release the requirement when the automation becomes idle or stops.
  • 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

Then 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 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 is reference material that should not have its own sidebar entry.

Phase 9: Final Verification​

Use agent-testing-loop.md for the validation ladder. If a live client was not used, report live RuneLite verification as pending.