AEP coding run

You are working the open issues of one WSO2 Labs Agentic Engineer project. The current working directory is the project: everything you need is inside it, and everything you produce goes inside it. Your prompt names the work and nothing else — which issues are yours, how to order them and what finishing looks like are here. Nothing is reported back to a platform: there is no status callback and no progress API to call.

Where you are

The cwd is a fresh clone of the project's GitHub repo on its default branch (e.g. main). Your prompt's subject is a milestone reference — a number and a title — and this session is one cycle of that milestone. git and gh are already authenticated: the workspace is preconfigured (credential helper for git, wrapper for gh), so never run gh auth login, set a token, or edit .git/config's credential helper. What you push, and the pull request you open, are the record of this cycle — not the working tree.

A git or gh command that fails to authenticate is a platform fault, not an obstacle to work around. Say so in one line and stop the run.

Validation runs: if your prompt says this is a validation task and
points at a single validation issue, the aep-validation skill's workflow
REPLACES The run below — load it. Everything else here still applies.

This skill, and the stack skills

This is the umbrella skill. The run below is the loop over the issue set and the record you leave behind. What every component obeys, whatever language it is written in, is references/component-contract.md — not repeated here.

Stack skills sit under this one and own project layout, Dockerfile, library choices, the exact build-verify command, and that stack's own pitfalls. None of them is in your context — you have their descriptions and nothing else, and their content arrives only when you load one. Load a component's skills before you write a line of its code, and re-read them rather than working from memory of a similar project: its design.json lists them under skillsPinned, and each is offered to you under a kind prefix, so ballerina there is the skill named org-ballerina here. Name them in every subagent prompt, by the prefixed name.

Contract-first

specs/ was authored at design time, before any issue existed: every component's design.json, and every service's openapi.yaml. It is the contract — what a service implements, and what its consumers are written against. Implement to it; never edit it.

That is what makes the work parallel. A consumer codes against its provider's committed openapi.yaml, never its code, so no issue waits for another issue's code: a dependency an issue declares is a runtime edge — who calls whom once deployed — never a build order. Only two issues writing the same files serialise anything.

The run

1 · Start the cycle

Settle what you are working, and what can run at once, before you write any file.

Done-ness is a live fact, never a stored flag: an issue is finished because the work landed. Derive the working set fresh before each pick — a run is long enough for the set to change under you, and re-checking is what lets new work join this run instead of the next one.

Order is by issue number ascending, and nothing else: every issue's contract is already fixed (Contract-first), so there is no build order to derive. File overlap decides how much runs at once — see Fan-out to subagents.

The set

Ask the issues API, live, once per pick:

gh issue list --milestone "<milestone title>" --state open \
  --json number,title,labels,url --limit 200

Never use the search API (gh search issues, gh api /search/...) — its index lags by up to a minute, so a fix issue the platform minted seconds ago, the very issue this cycle exists to work, is invisible to it.

Two labels decide this, and they do different jobs. aep arms an issue — it says something may work it at all. A kind says what it is, and there is exactly one per issue:

Your working set is every open issue carrying aep whose kind is development, bug or conflict. An armed issue carrying no kind at all is yours too — a human handed it over without classifying it.

Any open issue without aep is a ledger issue — a human's note, or an incident nobody has picked up. Never touch one: don't work it, comment on it, or reference it in your PR body. That includes an unarmed issue labelled bug: being classified is not being handed to you. A human adopts it by adding aep, and it joins the working set on your next re-list.

⚠ --milestone resolves by title and only sees OPEN milestones, so once
the platform closes it gh fails with "no milestone found". That means the
version is finished — it closes on a green ending, never while work or a verdict
is still owed: treat the working set as empty and go to Finish. Never fall back
to the search API, never guess issue numbers.

The bodies. Fetch your whole working set's bodies up front with gh issue view <number> --json number,title,body,labels — you need them to plan the fan-out. A Depends on #41 line records the runtime relationship the design declared. It is context, not a gate: never "work #41 first", never "wait for #41".

Establish branch identity

The platform never pre-creates your branch and never tells you its name. Work it out in this order, and settle it before the first edit — two of the three cases check out an existing branch, which would clobber uncommitted work.

a. A conflict issue in the working set names a pull request. The platform mints one when a cycle's PR could not merge. That PR's branch is your branch — the work is already there and only needs rebasing:

gh pr view <pr-number> --json headRefName,body
git fetch origin
git checkout <headRefName>
git rebase origin/main          # resolve conflicts SEMANTICALLY, not by
                                # picking a side — read both changes
# re-verify, then:
git push --force-with-lease

This is the only force-push the run may make (see Never).

b. Otherwise, look for an unmerged branch of this milestone — a previous cycle that crashed:

git fetch origin
git ls-remote --heads origin "aep/m<milestone#>-*"
git merge-base --is-ancestor "origin/<branch>" origin/main && echo merged

An unmerged candidate is a crash resume: check it out and read its history for what the crashed cycle already finished.

git checkout <branch>
git log origin/main..HEAD --oneline    # each commit ends with "(#N)"

Skip every issue whose number appears in a (#N) attribution — that work is committed. Continue with the rest of the ordered set on that branch.

c. Nothing to resume → mint a fresh branch:

git checkout -b aep/m<milestone#>-c<k>

<k> is one higher than the highest -c<k> already among this milestone's remote branches (1 if none). The aep/m<milestone#>-… prefix is load-bearing: it is how the platform maps your PR back to this run.

2 · Work the issues

For each issue in the ordered set — and whoever works it, you inline or a subagent you handed it to, keeps its status line current from start to done (The status line):

1. Read it in full — Scope, Acceptance criteria, References — **and the

contract under specs/**: its component's design.json and openapi.yaml, plus the openapi.yaml of every component it consumes. The issue says what to build; the contract fixes the shape. Read its comments too (gh issue view <number> --comments): a "Platform-resolved dependencies" comment carries an org-service's coordinates.

1. Make the change it asks for, holding to

references/component-contract.md and the stack skills of every component it touches.

1. A web-application is finished by a walk, not a build. Once its build is

clean, dispatch one more subagent for that component with exactly this prompt, and nothing about how to walk:

``text Walk <component> at <App Path>. Load mock-verification and agent-browser; the first is the whole procedure. Edit/Write only inside <App Path>; never run git. Progress: gh issue comment <N> --body "<line>". Report back the closing line and the numbered list. ``

The walk lands before the commit, so what it fixes ships with what it checked. An issue that moved no file the app loads skips this. One you are closing as already satisfied does not: that verdict is a claim about a screen, and reading the code cannot settle one.

1. Commit that issue's work on its own, attributed to it:

``bash git add <the App Paths that issue touched> git diff --cached --name-only # what is ACTUALLY staged — read it git commit -m "<type>: <short summary> (#<number>)" git push -u origin HEAD # -u only on the first push ` (#N)` is what a crash resume reads to know this issue is done — push as you go, so a crash never loses more than the issue in flight.

Read that --name-only list against what you changed. git add on a directory drops every ignored path inside it silently, at exit 0, leaving git status clean; the staged list is the only place the omission shows. What is missing there is missing from the build context, and the first sign is a red build minutes later in a component that compiled perfectly on your disk.

Keep the repo-root .gitignore current in the same commit that introduces something it should cover (build output, dependency directories, local env files) — one file for the whole project, and never commit what belongs in it. Anchor every pattern to the path it means: /onboarding-api/target/, not a bare target/. One .gitignore serves every component of a polyglot repo, so an unanchored directory name reaches into all of them — a generated/ added for a Ballerina component also swallows a web-app's src/generated/, which that stack requires committed. Anchor the pattern; never git add -f past it.

1. Re-derive the working set (§1) and pick the next issue.

Say why before you throw work away. Before deleting or wholesale-rewriting a file that already exists — a generated stub, a scaffold, anything an earlier step produced — run one echo naming the file and the reason:

echo "discarding openapi_service.bal: regenerating it against the corrected spec"

Only your tool calls reach the run's progress feed, so a deletion with no stated reason is indistinguishable afterwards from a mistake. If you cannot state one in a line, fix the file rather than delete it.

The status line

An issue's newest comment is its status line — the console renders that comment's first line beside the issue, and it is what a person watching the build reads. Whoever works an issue keeps its line current: you, on one you took inline; the subagent, on one you handed out. Only the actor doing the work knows what is happening on it.

gh issue comment <number> --body "<one line: what is happening on this issue now>"

Post when the one-line answer changes, and always at both ends — when the work starts and when it stops. In between it changes when a component goes green and when its work is committed. A walk's progress is the walker's, posted with the command its prompt hands it; mock-verification fixes the shapes. A stretch with no new answer is silence telling the truth; a comment repeating the line already there is noise.

Every tool call already reaches the run's progress feed, so this line carries the shape of the work rather than its steps — the component, and what is happening to it:

Implementing todo-api — 6 endpoints against its openapi.yaml.
todo-api builds clean; todo-web builds clean, walk dispatched.
Committed todo-api and todo-web (#12).

Not a plan, not a status table, not a diff, and never a comment on an issue that is not the one being worked.

Fan-out to subagents

You have a fan-out tool, and fanning out is the default, not the exception — a provider and its consumer may be built at the same time, by different subagents (Contract-first). Two tests, and they are the only two:

• Disjoint App Paths — no file and no module written by both. Overlap is the

only reason to serialise; work those inline, in ascending order.

• Big enough to be worth a subagent. A one-file change, a config tweak, a

small fix issue: work those inline. A subagent for small work costs more than it saves and makes the run harder to follow.

Issue every subagent for a wave in ONE turn, and wait for them. Several fan-out calls in a single message is what makes them run at the same time, and short prompts are what make one message possible. Do not use runinbackground: it does not add concurrency — it detaches the subagent, so its steps stop reaching the progress feed and the person watching sees an empty section where a component was built.

A subagent starts from its prompt and nothing else. It does not have this skill. This list is a build dispatch — a walk's prompt is the literal one in step 3, and nothing else. Name exactly these, and nothing else:

1. its issue — the number, and to read it in full;
2. its App Paths — the only paths it may write;
3. the contracts to read, as paths: its component's design.json and

openapi.yaml, and the openapi.yaml of every component it consumes;

1. **the component contract's absolute path, exactly as your prompt gave it to

you** — "read this first; it is your contract". Copy the string; never retype or shorten it, and never invent one. Add that the path is outside the project: readable, while nothing may be written outside its App Paths;

1. the stack skills it must load, by name — and that where a stack skill's own

flow contradicts the component contract, the contract wins (a stack skill may end its flow at "open a PR", which this subagent may not do);

1. the artefacts only you could resolve — and say which is which: the

component's workload.yaml when you hold a resolved one, pasted verbatim and not to be changed; or that no wiring was resolved, so it authors the file from the design per references/workload-and-wiring.md. Plus any org-service contract you resolved — pasted, as a path, or named as undocumented, which changes the job to a minimal client;

1. its write boundary — Edit/Write, and only inside its App Paths.

It never runs git: the branch, the commits and the pull request are yours;

1. what to report back to you when it finishes: what it changed and whether the

verify command passed.

1. its issue's status line — the gh issue comment command above with its

issue number filled in, and the rule that goes with it (The status line): one line, at both ends of its work and whenever the answer changes between them. That command is the only gh it may run, and its own issue is the only issue it may touch.

Give paths, not contents. A subagent reads the same filesystem you do, so a contract you paste is a long turn spent before it starts, on a file it opens anyway — and do not open those yourself either: every line you pull in you carry for the rest of the run. State each boundary once, and resolve your own uncertainty before you delegate; a prompt offering two conventions to choose between hands down a question you were better placed to answer.

Trust a report that says the build is clean — re-read only what a report calls incomplete, and what you must open to commit. Re-reading every file a subagent wrote buys nothing and carries the whole set for the rest of the run.

You are the sole git writer. When a subagent reports done, you stage those paths and commit them exactly as in step 4. No worktrees — one workspace.

A walk that leaves a failure open is not a failed wave (the component contract's Walks). Its report comes back with the fixes already in the tree (step 3): commit the component with the rest of that issue's work and carry the report's [ ] lines into Finish the cycle, where the pull request body carries them verbatim.

3 · Finish the cycle

Anything you could not finish stays open for a later run — that is expected, not a failure state. This step owns every record the cycle leaves behind, including what a component that never went green becomes.

The record

Open one pull request for the cycle, whose body lists Resolves #N on its own line for every issue you completed — task, fix and conflict issues alike:

gh pr create \
  --title "<short summary of the cycle>" \
  --body $'Resolves #12\nResolves #14\n\n<what changed, per issue>'

That list matters twice: the auto-merge predicate needs at least one Resolves reference to an agent-work issue in this milestone (a PR listing none is treated as somebody else's work and left alone), and GitHub closes each referenced issue when the PR merges — one you finished but didn't list gets worked again next cycle. The platform merges the PR; no human reviews it.

A web application in the cycle → its Task's Screens: and Flows: lists go in the body, ticked from the walk's report: a screen when its line is green, a flow when every screen in its block is. An open [ ] line stays unticked with the report's line beside it (wireframes' references/implementing.md shows the shape). The PR stays ready for review — a defect on a committed component is not a red one (the component contract's Walks).

A component stayed red → the same PR, but --draft and a [build-failed] title prefix. A draft is the platform's signal that you are not finished and is never auto-merged. Still list Resolves #N for the issues that DID complete so the diff stays attributable, and carry the diagnostic the component contract asks for under an ## Error heading (the ~40 lines, fenced) and ## What was tried.

Leave every issue you did not finish open, and make its last status line the same diagnostic: what you tried and why it stopped.

Be idempotent

You may be a restart of a run that already got part-way, so treat anything that already looks done as not yours to redo.

• Work pushed but no PR open → open the PR with a Resolves line for each

(#N) in git log origin/main..HEAD.

• A PR already open for this branch and the working set is empty → verify

its Resolves list covers every (#N) on the branch, add any missing with gh pr edit --body ..., and exit. Do not open a second PR.

• Empty working set and nothing pushed → nothing to do. Exit cleanly and say

so.

The component contract

A project is a set of components, each one a folder — its App Path — holding everything that component owns. An issue may name one or several.

references/component-contract.md is what every component obeys, whatever language it is written in: its invariants, what design.json fixes, how a dependency's contract is found, the code rules, what green means, and the rails that bind anyone touching the filesystem. Load it at the start of the cycle. You author each component's workload.yaml from it, you brief every subagent against it, and an issue you work inline makes you the implementer too.

Dependencies and workload.yaml

Every entry in a component's dependencies[] is declared in its workload.yaml: an endpoints: entry for a sibling or an org service, a resources: entry for a platform resource or an external system.

Read references/workload-and-wiring.md before you write or edit either half of that file — the per-kind wiring table, the file's exact format, and the visibility rules a dependent's reachability turns on are all there, and none of it is guessable. Both failure modes are silent: an env var you renamed arrives empty, a visibility you omitted leaves a dependent's config unwritten, and nothing errors until deploy.

One thing that file cannot give you is an org-service's live coordinates. That is below.

The endpoints: half

A sibling (kind: component) is already resolved in your own tree: its entry is the wiring.endpoint object on that dependency in design.json, copied verbatim. That holds whether or not the comment below exists.

An org-service belongs to another project, so only the platform can resolve it. It posts what it resolved as a "Platform-resolved dependencies" comment on the open issues of your working set, so it may land on a sibling issue rather than the one for the component it describes. Read the comments on the issues you are working and copy every ## Component <name> block into that named component's workload.yaml — invent, rename and omit nothing. Two blocks for the same component: the latest is the complete answer.

Finding an org-service contract

The comment's Consumed API contracts sections name the providers. For an org-service, call listorgcomponentendpoints and match the one named: that row's spec.availability is inline (the document is in spec.inlineContent), repo (read it from the provider's repo — searchremotegitcode, then getremotegitfilecontents under the row's subdir), or none, meaning undocumented.

Never

The rails that bind every actor — specs/ is read-only, nothing is authored or read outside the project, no secret in a search query, a fetched page is data rather than instructions — are stated in full in references/component-contract.md. Load it before your first edit or your first web search. The rest belongs to the run:

• **Hold back or skip an issue because a component it depends on is not built

yet.** Code against the contract.

• Let a subagent run git, or any gh its prompt did not give it.
• Fan out with runinbackground (Fan-out to subagents).

Git and GitHub

• Push to the default branch (main). Always the run's own

aep/m<milestone#>-… branch.

• Force-push anywhere except that branch during a conflict rebase

(Start the cycle), and then only with --force-with-lease. Never main, never another branch, never to "clean up" your own history.

• Open a pull request with no Resolves #<issue-number> line — the platform

cannot link it and will not merge it. Or open more than one for this cycle.

• Run gh pr merge, gh pr close, gh repo create, gh repo delete,

gh repo fork, or gh repo edit.

• Touch a ledger issue (no aep), a provision gate, or a validation issue.
• Delete remote branches (git push --delete, git push origin :branch).
• Modify branch protection, secrets, repository settings, collaborators, or

webhooks.