Skip to content
Engineering Standards

AI change workflow

How coding agents claim Ready work, stay inside scope, open draft pull requests, and hand back evidence.

Updated View as MarkdownView on Github

A coding agent can implement a change. It cannot decide that work is ready, approve its own change, or declare delivery done.

NinjaTrader’s Definition of Ready is the entry gate. The Definition of Done is the exit gate. This page covers the agent’s work between them.

Put Ready work in a tracked queue

Every change intended for a pull request starts from a tracked work item in NinjaTrader Jira or the repository’s approved issue tracker. Direct prompts may be used for research, diagnosis, or review that will not change the repository.

The work item meets the Definition of Ready and names a human owner. A reader who missed every prior conversation can still find:

  • The user or business outcome.
  • What is in scope and out of scope.
  • Bulleted, testable, observable acceptance criteria.
  • Known edge cases and linked source material.
  • Dependencies and affected systems.
  • The test approach.
  • Feature-flag, rollout, and rollback decisions where they apply.

The existing variations for dev-only work and hotfixes still apply. Coding agents do not create another exception path.

flowchart LR
Brief[Tracked work item] --> Ready{Ready?}
Ready -- no --> Triage[Return for triage]
Ready -- yes --> Human[Human accepts]
Human --> Queue[ready-for-agent]

Use the standard labels

Every covered repository configures five triage roles. They are intake labels, not substitutes for Jira or GitHub workflow statuses.

Label Meaning May an agent start?
needs-triage A maintainer must evaluate the work. No
needs-info A fact, decision, or dependency is missing. No
ready-for-agent A human approved the Ready, unblocked work for agent pickup. Yes
ready-for-human The work is clear but requires human execution or authority. No
wontfix The owning team will not action the work. No

Run setup-nt-agent-skills during repository AI-readiness setup. It configures NinjaTrader Jira or repository GitHub Issues and records any tracker-specific mapping in docs/agents/triage-labels.md.

The owning team keeps the mapping accurate. A repository readiness check fails when a configured label no longer resolves in the tracker.

Only a human may apply ready-for-agent. An agent may remove readiness by applying needs-info or ready-for-human, but it cannot certify its own task. After clarification, a human rechecks the work and reapplies ready-for-agent. A new comment alone does not restart execution.

flowchart TD
T[needs-triage] -->|missing facts| I[needs-info]
T -->|human work| H[ready-for-human]
T -->|declined| W[wontfix]
T -->|Ready and approved| A[ready-for-agent]
I -->|human rechecks| A
A -->|agent finds a gap| I
A -->|agent lacks authority| H

Claim before editing

ready-for-agent means that approved automation may begin without another prompt. Automatic queue watchers are optional. A human, scheduled worker, or provider integration may claim the work.

The claim protocol is the same:

  1. Re-read the work item, linked sources, and current repository instructions.
  2. Confirm that dependencies remain resolved and the code has not invalidated the plan.
  3. Confirm that required access and test environments are available.
  4. Acquire a tracker-visible claim that prevents another worker from starting.
  5. Remove ready-for-agent, move the item to the tracker’s in-progress state, and record the branch or run identifier.

The named human remains accountable. A worker identity or hosted-agent run does not replace that owner.

sequenceDiagram
participant H as Human owner
participant T as Tracker
participant A as Agent
H->>T: Apply ready-for-agent
A->>T: Read and recheck task
A->>T: Claim and remove label
T-->>A: In progress
A->>A: Begin work

Plan before the first source edit

Write a plan when a change:

  • Has dependent implementation steps that must occur in order.
  • Crosses a subsystem or repository boundary.
  • Changes a contract, schema, security boundary, data handling, infrastructure, or rollout behavior.
  • Has an uncertain test or migration path.
  • Meets a trigger for a design document, RFC, or ADR.

A small, well-scoped change may proceed from the accepted work item. A working plan does not replace a required design document, RFC, or ADR.

Use each agent’s supported planning path for the same outcome:

Record a routine plan in the tracked work item or link an accessible provider session. Copy the approved plan into the work item when reviewers cannot access that session. Do not commit temporary agent plans or progress ledgers. Durable decisions belong in their existing design document, RFC, or ADR locations.

A human approves the plan before implementation when the change affects:

  • Security or regulated data handling.
  • Money movement.
  • Production infrastructure.
  • A published contract.
  • Work that requires a design document, RFC, or ADR.

For other multi-step work, the agent records the plan and may proceed under the original authorization. If implementation departs from the plan, update it. Another approval is required only when the change crosses one of the approval triggers above.

flowchart TD
Work[Claimed work] --> Plan{Plan required?}
Plan -- no --> Build[Implement]
Plan -- yes --> Draft[Write plan]
Draft --> Gate{Approval trigger?}
Gate -- no --> Record[Record plan]
Gate -- yes --> Approve[Human approves]
Record --> Build
Approve --> Build

Keep the change inside its boundary

Open the task in its own worktree or disposable clone as described in Development environment. One tracked work item normally produces one branch and one pull request. Keep unrelated cleanup out of the branch.

When dependent pull requests make the change easier to review, use a stack linked to the same work item and explain its order. If the authored diff is about 1500 lines or more, the pull request size rule requires a stack. Generated files, lockfiles, vendored trees, and other machine-written output do not count toward that threshold.

Implementation details may change inside the accepted outcome and boundaries. Stop when continuing would change:

  • An acceptance criterion.
  • In-scope or out-of-scope behavior.
  • A published contract or dependency.
  • Required permissions or data classification.
  • Migration, rollout, or rollback behavior.
  • The requested user outcome.

Set needs-info, describe the decision, and wait for a human to re-authorize the work.

flowchart LR
Discovery[New fact] --> Scope{Inside accepted scope?}
Scope -- yes --> Update[Update plan if needed]
Update --> Continue[Continue work]
Scope -- no --> Stop[Stop editing]
Stop --> Info[Apply needs-info]
Info --> Decision[Human decides]

Build the verification record as you work

Use the narrow-to-wide feedback loop in Testing and feedback and the commands defined by Task automation. Before opening a pull request, the agent:

  1. Runs the focused and affected checks.
  2. Runs full local verification.
  3. Reviews the complete diff against the base branch.
  4. Inspects the rendered, returned, generated, or planned result.
  5. Records checks that can run only in CI or another environment.

The work item remains the source of accepted behavior. A green test does not authorize the agent to rewrite an acceptance criterion, weaken a test, or hide an unresolved failure.

Open a draft pull request

An implementation task authorizes the agent to commit and to open or update a draft pull request. It does not authorize the agent to:

  • Mark the pull request ready for review.
  • Approve or merge it.
  • Dismiss a human review finding.
  • Bypass a check, hook, approval, or branch rule.

Use gh stack submit --auto for a stack. It creates draft pull requests by default.

Keep the pull request useful to a reviewer:

Pull request handoffmarkdown
**Context:** What this changes and why.
**Work item:** NT-12345
**Business impact:** The user or operational result.

**Acceptance criteria:**
- [x] Observable outcome one
- [x] Observable outcome two

**Verification:**
- `scripts/task test <selector>`: passed, 12 tests
- `scripts/task verify`: passed
- CI-only contract check: pending

**Known limitations and unresolved risks:**
- None

Do not add generated-by notices, tool attribution, or AI co-author trailers to commits or pull requests. A provider transcript is not required evidence. Link one only when review needs it, Security and data permits it, and every intended reviewer can access it.

Stay for the review loop

A human checks the handoff and marks the pull request ready. CODEOWNERS supplies path reviewers. Add QA, PM, SRE, Security, or contract-owner review when the Definition of Done, security policy, or an approved design record requires it.

For each accepted review finding, the agent:

  1. Makes the scoped correction.
  2. Adds or updates tests when behavior changes.
  3. Reruns affected checks and final verification.
  4. Updates the evidence record.
  5. Leaves stale-approval handling to branch protection and the human reviewer.

If a requested fix expands scope, stop and follow the scope-change path. An automated review is advisory. It does not replace four-eyes review.

flowchart TD
Draft[Draft pull request] --> Check[Human checks handoff]
Check --> Ready[Mark ready]
Ready --> Review[Independent review]
Review --> Changes{Changes requested?}
Changes -- yes --> Fix[Agent fixes and verifies]
Fix --> Review
Changes -- no --> Merge[Human merges]

Leave blocked work legible

When the agent cannot reach merge readiness, leave a tracker comment with:

  • The blocking condition.
  • What was completed.
  • The exact failing or unavailable check.
  • The branch or draft pull request containing useful work.
  • The decision or access needed next.
Blocked handofftext
BLOCKED: The staging contract test needs an account the task does not provide.
COMPLETED: Parser change, focused tests, and documentation.
FAILED: scripts/task integration-check contracts/staging
WORK: Draft PR #456
NEEDED: Human owner supplies an approved test account or removes staging from scope.
LABEL: needs-info

Use needs-info when a fact or decision is missing. Use ready-for-human when the task is clear but requires human execution or authority. Never leave ready-for-agent on claimed or blocked work.

Hand back into Definition of Done

The agent stays engaged until the pull request is merge-ready:

  • Required checks are accounted for.
  • Review findings are resolved or handed back explicitly.
  • Verification evidence is current.
  • Known limitations and unresolved risks are recorded.
  • The final diff still matches the accepted scope.

Merge readiness is not Done. The human owner carries the work through every remaining Definition of Done gate that applies.

flowchart LR
Agent[Agent handoff] --> Merge[Human merge]
Merge --> QA[QA validation]
QA --> UAT[PM or UAT]
UAT --> Release[Release readiness]
Release --> Prod[Production validation]
Prod --> Done[Done]

Keep review evidence in the pull request. Keep delivery status and formal sign-offs in the tracked work item. Link between them instead of copying logs or repeating the same narrative.

References

NinjaTrader workflow

Provider workflows

Navigation

Type to search…

↑↓ navigate↵ selectEsc close