@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-skills/assets/refactor-safely/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: refactor-safely
+description: "Use when the user wants to plan or execute a refactor — a rename, dead-code removal, decomposition, or restructuring — with dependency-aware confidence before touching code. USE FOR: renaming a function or symbol, checking the impact radius of a change before applying it, previewing every call site an edit touches, decomposing a large function, removing dead code, seeing what breaks before refactoring. DO NOT USE FOR: orienting in an unfamiliar codebase with no refactor in mind (use explore-codebase), chasing the cause of a live bug (use debug-issue), or reviewing someone else's pending diff (use review-changes)."
+disable-model-invocation: false
+---
+
+# Refactor Safely
+
+Use the knowledge graph to plan and execute refactoring with confidence.
+
+## Use When
+
+Planning or executing a refactor — a rename, dead-code removal, or
+decomposition — where you need dependency-aware confidence before touching
+code: an impact radius, the affected execution flows, or a preview of every
+edit location before applying a change.
+
+## Do Not Use When
+
+You are only orienting in an unfamiliar codebase with no refactor in mind —
+use `explore-codebase`. You are chasing the cause of a live bug — use
+`debug-issue`. You are reviewing someone else's pending diff — use
+`review-changes`.
+
+## Steps
+
+1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions.
+2. Use `refactor_tool` with mode="dead_code" to find unreferenced code.
+3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations.
+4. Use `apply_refactor_tool` with the refactor_id to apply renames.
+5. After changes, run `detect_changes_tool` to verify the refactoring impact.
+
+## Safety Checks
+
+- Always preview before applying (rename mode gives you an edit list).
+- Check `get_impact_radius_tool` before major refactors.
+- Use `get_affected_flows_tool` to ensure no critical paths are broken.
+- Run `find_large_functions_tool` to identify decomposition targets.
+
+## Token Efficiency
+
+Follow `explore-codebase`'s **Token Efficiency Rules** — minimal-context
+first, `detail_level="minimal"`, a ≤5-call/≤800-token target, and read the
+real source before editing.

package/packages/agent-skills/assets/review-changes/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: review-changes
+description: Perform a structured code review using change detection and impact
+disable-model-invocation: false
+---
+
+# Review Changes
+
+Perform a thorough, risk-aware code review using the knowledge graph.
+
+## Use When
+
+Reviewing a diff or pending change set and you need a structured, risk-aware
+pass — a risk score, the affected execution paths, test coverage status, and
+the blast radius — before recommending merge.
+
+## Do Not Use When
+
+You are planning your own refactor rather than reviewing one — use
+`refactor-safely`. You are chasing the cause of a live bug — use
+`debug-issue`. You just need to get oriented in an unfamiliar codebase — use
+`explore-codebase`.
+
+## Steps
+
+1. Run `detect_changes_tool` to get risk-scored change analysis.
+2. Run `get_affected_flows_tool` to find impacted execution paths.
+3. For each high-risk function, run `query_graph_tool` with pattern="tests_for" to check test coverage.
+4. Run `get_impact_radius_tool` to understand the blast radius.
+5. For any untested changes, suggest specific test cases.
+
+## Output Format
+
+Provide findings grouped by risk level (high/medium/low) with:
+- What changed and why it matters
+- Test coverage status
+- Suggested improvements
+- Overall merge recommendation
+
+## Token Efficiency
+
+Keep this review token-light per `explore-codebase`'s **Token Efficiency
+Rules**: `get_minimal_context_tool` first, `detail_level="minimal"` on every
+call, ≤5 calls and ≤800 tokens, and confirm findings against the actual source
+and tests.

package/packages/agent-skills/assets/tdd/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+disable-model-invocation: false
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## Use When
+
+- The user wants to build a feature or fix a bug test-first.
+- The user mentions "red-green-refactor" or asks for the TDD loop by name.
+- The user wants integration tests written before the implementation.
+
+## Do Not Use When
+
+- The goal is a throwaway exploration of whether a design feels right, not a kept test suite — use `prototype` instead.
+- The work is a refactor with no behavior change; refactoring belongs to the review stage, not the red-green loop.
+- No stable public seam exists yet to test against — settle the interface first.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [references/tests.md](references/tests.md) for examples and [references/mocking.md](references/mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/packages/agent-skills/assets/tdd/references/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/packages/agent-skills/assets/tdd/references/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

package/packages/agent-skills/assets/testing/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: testing
+description: Select and prove unit, regression, or cross-service tests for a change.
+disable-model-invocation: false
+---
+
+# Testing
+
+## Purpose
+
+Select the smallest test mode that proves the change, preserve a red-green regression trail for bug fixes, and run cross-service behavior through the project's CI-parity environment.
+
+## Use When
+
+- A change needs test coverage or a bug needs a regression proof.
+- Runtime, provider, database, broker, streaming, or end-to-end behavior is involved.
+
+## Do Not Use When
+
+- Behavior is still unknown; resolve the specification first.
+- The request is solely an external pre-landing review rather than test selection or proof.
+
+## Workflow
+
+1. Choose Mode 0 for isolated logic, Mode 1 for a bug-fix red-green cycle, and Mode 2 for cross-service or live behavior.
+2. For Mode 1, run the smallest failing regression test, implement the minimum change, rerun it, then refactor only while green.
+3. For Mode 2, run through the project's CI-parity entrypoint — `just check` in Adl repositories. Isolated containers are advisable in general and **mandatory** where a test crosses a service boundary or needs real runtime (provider, database, broker, streaming); pure/isolated logic may run in-window. Live or billable calls require an explicit project opt-in and must skip cleanly without credentials.
+4. Record the selected command, environment, and evidence in the current task artifact. A runtime bug requires a Mode-2 regression scenario.
+
+## Output
+
+Return the selected mode, changed test or scenario, red/green evidence where required, command output, and environment actually used.
+
+## State Contract
+
+Project repositories own harness paths, service names, credentials, URLs, and opt-in flags. Keep secrets out of fixtures and source; pass them only through environment variables.
+
+## Boundaries
+
+### In scope
+
+Mode selection, regression design, red-green-refactor, harness scenarios, and CI-parity evidence.
+
+### Out of scope
+
+Inventing unspecified behavior, reviewing code quality, or cleaning unrelated implementation residue.
+
+### Fog of war
+
+If behavior cannot be stated precisely, stop before writing a guessed test. If the isolation requirement is unclear, use the stricter Mode-2 path and record the uncertainty.
+
+## Completion
+
+Run the selected project test command in its required environment; `grep -q '^PASS:' <validator-output>` exits 0 for every harness scenario.

package/packages/agent-skills/assets/to-feature/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: to-feature
+description: Turn the current conversation into a feature spec and open it as a Feature work item on Azure DevOps, parented to the plan's Epic — no interview, just synthesis of what you have already discussed.
+disable-model-invocation: true
+---
+
+# To Feature
+
+Open a **Feature** on the board and give it a plan folder to live in.
+
+**A plan is a Feature, and a Feature is a directory** — `plans/features/az<id>-<slug>/spec.md`, named for the work item it is. This skill creates that Feature and that directory; `to-workitems` later fills its `items/` with PBIs and Bugs parented under it. Where the repo carries a `plans/AGENTS.md`, it governs; otherwise follow the global `## Plans and work items` contract in your host's agent instructions.
+
+Do NOT interview the user — synthesize what you already know from the conversation and the codebase.
+
+## Use When
+
+- The current conversation, plus codebase exploration, already gives you enough to synthesize a feature spec, and the Epic it belongs under is known.
+
+## Do Not Use When
+
+- The user's intent is still unclear and needs an interview or clarifying questions first — this skill explicitly skips that; gather requirements before invoking it.
+- The way to the destination is not visible yet — chart the effort with `wayfinder` instead, and come back when the decisions are resolved.
+- `epic:` is unset. **Stop and ask.** `epic:` is authored, never tool-created, and the server refuses `Epic` as a creatable type outright — so a typo must fail here rather than hang the plan off the wrong portfolio branch.
+
+## Process
+
+### 1. Explore the repo
+
+Understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+
+### 2. Sketch the seams
+
+Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better — the ideal number is one.
+
+Check with the user that these seams match their expectations.
+
+### 3. Have the human confirm the Epic
+
+**Stop here and ask.** Show the user the id in `epic:` and the title of the Feature you are about to create under it, and get an explicit confirmation before going on.
+
+This is a human step because **no agent-side check can establish which Epic is the right one — only that the parent named is an Epic at all.** Agents have no access to Epics: fetching one by id is refused, so there is no tool call that reads `epic:` back and confirms it names the Epic you intend. Do not go looking for one, and do not treat a successful create as agreement on identity — it proves the type, never the choice.
+
+Be careful with that refusal if you meet it — it reports only that the id is not a tracked type, which is equally true of a Task and of an id you cannot see. It does **not** say "this is an Epic", and reading it that way turns one observation into a proof it cannot carry.
+
+The access is asymmetric, and step 5 depends on the half that works: you cannot **read** an Epic, but you can **write** a parent link to one. The server checks that write's parent **type** — a PBI or Bug aimed at the wrong level is refused before the request is sent, and a Feature is no longer the exception: `workitem_create_or_update` refuses a wrong-typed parent by name, on create and on update alike (`Feature must be parented to a Epic; work item <id> is a <type>`). What that check cannot do is tell you whether `<id>` is the **right** Epic, only that it is *an* Epic — a Feature parented to the wrong Epic still creates cleanly, no error, silently on the wrong branch of the portfolio. The confirmation you get here is the only thing standing between you and that.
+
+`epic:` is **authored, never tool-created**. If it is unset, that is a stop — ask for it. Never create an Epic to fill the gap; the server refuses `Epic` as a creatable type outright, and a typo must fail loudly rather than quietly spawn a duplicate.
+
+### 4. Draft the spec, but do not write it yet
+
+Draft the spec against the template in [references/FEATURE-SPEC-TEMPLATE.md](references/FEATURE-SPEC-TEMPLATE.md). Hold it in the conversation — it has no folder to live in yet, because it has no id yet.
+
+**The id is the identity: allocate the work item first, then name the file.** A Feature is never written to disk under a placeholder and renamed afterwards. This skill allocates the id itself one step from now, so a placeholder would exist only for the length of a single tool call and buy nothing — it would be a second name for the same thing, and the rename is a step that can fail and leave the folder lying.
+
+### 5. Create the Feature
+
+```
+workitem_create_or_update({
+  type: 'Feature',
+  title: <the outcome, as it reads on the board>,
+  description: <the spec's ## Problem and ## Solution>,
+  acceptanceCriteria: <the spec's ## Acceptance criteria, verbatim>,
+  parentId: <the epic>,
+})
+```
+
+`description` and `acceptanceCriteria` are both advertised arguments — the plan's prose **is** those two fields, so send them on the create call rather than leaving the board holding a title and a parent. If the file and the field differ, the board is lying. `assignedTo`, `priority`, `startDate` and `targetDate` map the same way from the template's frontmatter when the plan sets them.
+
+`parentId` is **always** the Epic — the one adjacent level a Feature may hang from. Omitting it is refused as `requires parentId`, whatever the type; there is no root case to fall back on.
+
+**Set no state and no gate flags.** A Feature carries neither: the six Build flags apply only to Product Backlog Item and Bug, and a Feature's custom fields are empty. Do not carry a `fields: {...}` idiom across from a skill that works on PBIs — that raw-fields escape hatch reaches `System.State` without the dedicated `state` argument the gate matrix reads, which is the trap it exists to close. A new Feature lands in Azure DevOps's own default state, `New`, and moving it is a later, separate pass.
+
+### 6. Record the id, then verify the link landed
+
+Create `plans/features/az<id>-<slug>/` — named with the id the create call just returned, which is the only name it ever has — and write the drafted spec into its `spec.md` with `work_item:` set to that id and `epic:` carried through. Do this **immediately**, before anything else: a crash then leaves a folder that says what exists on the board, rather than a Feature nobody can trace back to a plan.
+
+Leave `items/` uncreated. A Feature whose items do not exist yet is the normal resting state of a fresh plan, not an unfinished one.
+
+Then read the Feature back and confirm `links.parent` is the `epic:` id:
+
+```
+workitem_list_or_get({ id: <the new feature>, raw: true })
+```
+
+`raw: true` is necessary rather than stylistic — the grouped view does not carry `System.WorkItemType` verbatim. This reads the **Feature**, never the Epic, so it stays inside what an agent can see.
+
+Be exact about what it proves: that the link landed on the id the human confirmed. The create having succeeded already proved that id is an Epic — a wrong type would have failed loudly at step 5 with `Feature must be parented to a Epic; work item <id> is a <type>`, before this read ever ran. What no agent-side check proves, here or at step 5, is that it is the **right** Epic. If `links.parent` is anything other than the `epic:` id, say so plainly rather than moving on; the plan is already on the board by then, and a wrong parent is worth raising immediately.
+
+### 7. Stop
+
+Slicing the feature into items is `to-workitems`' job, and it wants item files that do not exist yet. Tell the user the Feature is open and what its id is; do not start creating children in this run.

package/packages/agent-skills/assets/to-feature/references/FEATURE-SPEC-TEMPLATE.md

@@ -0,0 +1,88 @@
+# The plan document
+
+`plans/features/az<id>-<slug>/spec.md`. **This file IS the Feature** — the long form of its work
+item, not a parallel copy. `## Problem` and `## Solution` are its Description; `## Acceptance
+criteria` is its Acceptance Criteria field. If the two ever differ, the board is lying.
+
+Where the repo carries `plans/templates/feature.md`, that file is the source and this one is
+only its shape — author from the repo's copy.
+
+```markdown
+---
+type: Feature
+title: "[the outcome, as it reads on the board]"
+description: "[one line — becomes System.Description]"
+status: draft
+created: YYYY-MM-DD
+epic: <id>
+work_item: <id>
+assigned_to: <email>
+priority: 2
+start_date: YYYY-MM-DD
+target_date: YYYY-MM-DD
+---
+
+# [the outcome]
+
+## Problem
+
+What is wrong today, and what it costs. Evidence, not assertion — the command whose output
+shows it, the file and line, the number.
+
+## Solution
+
+The shape of the fix, from the outside in. What changes for whoever uses this. Not a
+layer-by-layer implementation list — that is the items' job.
+
+## Acceptance criteria
+
+Checkable statements. This is the same text as the work item's Acceptance Criteria field.
+
+- [ ] [something a reviewer can confirm without reading the diff]
+
+## Scope
+
+In: [paths or systems]
+
+Non-goals: [what a reader would wrongly assume is included]
+
+## Decisions
+
+- [decision, and what it rules out]
+
+## Items
+
+Order and dependencies. Each row is the complete source for an item that does not have a file
+until `to-workitems` allocates its id.
+
+| # | Title | Item type | Delivers | Verification | Work item | Predecessor |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | [the outcome this slice delivers] | pbi | [the complete vertical slice] | [a falsifiable check] |  | — |
+
+## Verification
+
+The end-to-end check on the acceptance criteria above. Each item carries its own check — this
+is the one that only means anything once they have all landed.
+
+## Done when
+
+- [ ] Every item is Done on the board.
+- [ ] Acceptance criteria all met, with observed evidence.
+```
+
+## `status:` is about the document
+
+`status: draft` describes this file, not the work. The work's state is the Feature's board
+state, and it lives there alone — there is no `plan_state`, no `approval_state`, and no
+directory that moves to record progress.
+
+## Two rows to leave empty, and one to fill
+
+`work_item:` is filled from the create call's return, in the same step that names the folder.
+
+`epic:` was **authored before this skill ran** — it is never tool-created. If it is unset,
+that is a stop, not a value to allocate.
+
+The `## Items` table's `Work item` column stays empty here. `to-workitems` fills it when it
+creates the children, and that is the only join between the plan and its items: the link runs
+one way, each item naming its `feature:`, and the Feature never lists its items anywhere else.

package/packages/agent-skills/assets/to-workitems/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: to-workitems
+description: Publish a change plan's backlog items to Azure DevOps — one PBI or Bug per item file, parented under the plan's Feature, with each id written back into the file it came from.
+disable-model-invocation: true
+---
+
+# To Work Items
+
+Put a plan's **backlog items** on the board.
+
+**A plan is a Feature. An item file is a PBI or a Bug.** One file each. The plan and its `## Items` table are written before this skill runs; the item files are not, because each is named for an id only this skill allocates. Where the repo carries a `plans/AGENTS.md`, it governs the layout; otherwise follow the global `## Plans and work items` contract in your host's agent instructions. [references/AZURE-DEVOPS-HIERARCHY.md](references/AZURE-DEVOPS-HIERARCHY.md) carries the board rules both depend on.
+
+## Use When
+
+- A plan folder's `spec.md` is approved, its `## Items` table is filled in, and those items need to be on the board.
+
+## Do Not Use When
+
+- The plan has open decisions under `## Decisions` — resolve them first, or chart the effort with `wayfinder` if the destination itself is still unclear.
+- `epic:` or `work_item:` is unset. **Stop and ask.** Those are the plan's Epic id and Feature id respectively. Never create an Epic or Feature to fill the gap: a typo must fail here, not silently spawn a duplicate. The server refuses a stray Epic outright, and refuses a wrong-*typed* parent for any creatable type — but a right-typed id can still be the **wrong** one, and nothing on the board catches that. Identity is on you.
+
+## Process
+
+### 1. Read the plan and check the board
+
+`workitem_list_or_get({ id: <work_item>, raw: true })` and assert:
+
+- `fields['System.WorkItemType']` is `Feature`
+- `links.parent` is `epic`
+
+One call settles both — there is no need to fetch the Epic itself. `parentId` for every item this skill creates is **always** the Feature — never the Epic.
+
+### 2. Read the plan's `## Items` table
+
+**The rows are the source, not files.** A file under `items/` is named `az<work item id>-<slug>.md`, so **the id is the identity** — and it is always a real work item id. An item that has no id yet therefore has no file and cannot have one: allocate the work item first, then write the file. Nothing is drafted under a placeholder and renamed into truth later.
+
+Each row has to carry the whole item before the board sees it: its title, its `item_type` (`pbi` or `bug`), what it delivers, its falsifiable verification, and its predecessors. A row missing any of those is a stop, not a skip — fix the row first.
+
+A row whose `Work item` column is already filled is **already published**. Leave it alone, and confirm its file exists under `items/` with a matching `work_item:`. A filled column with no file means the ids were never written back; a file whose `feature:` names a different plan is a stop.
+
+### 3. Check the items are tracer bullets
+
+Fix the row if not — do not paper over it in the work item body.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+**Wide refactors are the exception.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Sequence it as **expand–contract**: add the new form beside the old, migrate call sites in batches sized by blast radius (each batch its own item, blocked by the expand), then delete the old form in an item blocked by every batch.
+
+### 4. Quiz the user
+
+Present the items as a numbered list — title, blocked by, what it delivers. Ask whether the granularity and the blocking edges are right. Iterate until approved.
+
+### 5. Create the work items
+
+In `## Items` order, predecessors first — that is what makes `predecessors` expressible, since a row's blockers already have ids by the time it is reached.
+
+```
+workitem_create_or_update({
+  type: <item_type: pbi -> 'Product Backlog Item', bug -> 'Bug'>,
+  title: <the item's title>,
+  description: <the row's Delivers plus its source plan and row, per references/TICKET-TEMPLATES.md>,
+  acceptanceCriteria: <the row's Verification, verbatim>,
+  parentId: <the plan's work_item>,
+  predecessors: [<ids of the rows this one lists under Predecessor>],
+  related: [<for a Bug: the id of the PBI it was found in>],
+})
+```
+
+The row's delivery and source become `description`, shaped by [references/TICKET-TEMPLATES.md](references/TICKET-TEMPLATES.md). Its falsifiable verification becomes `acceptanceCriteria` verbatim. Both are advertised arguments and go on the create call, so the board receives the same fields as the row without a follow-up write.
+
+A Bug parents to the **Feature**, exactly as a PBI does, so `related` is the only way to record which item it was found while building.
+
+An item with no `parentId` is refused (`requires parentId`), and one parented to anything but the Feature is refused before the request is sent (see [references/AZURE-DEVOPS-HIERARCHY.md](references/AZURE-DEVOPS-HIERARCHY.md)) — so a wrong or missing feature id in the plan now stops the create rather than silently landing an orphan.
+
+Act on each returned id **immediately**, before creating the next — that is step 6, run once per row rather than once per plan. A crash then leaves a tree that says exactly what exists, rather than a board full of orphans nobody can trace.
+
+### 6. Write the item file the id now names
+
+The create call has returned an id, so the item finally has a name. Write `items/az<id>-<slug>.md` from the repo's `plans/templates/backlog-item.md`, with `work_item:` set to that id, `feature:` naming this plan, and `item_type:` the row's. Then fill that id into the plan's `## Items` row.
+
+The file is **born with its real id** and is never renamed. The `## Items` index is the only join between a plan and its items, and the link runs one way — the item names its `feature:`, the Feature never lists its items anywhere else.
+
+Nothing here moves between directories afterwards, and no directory name records progress. From here, progress lives on the work item as the six Build flags, and setting them is a later, separate pass — not this run, which already created the items and so is the wrong party to also confirm `Plan written` on them. That pass's own mechanics — reference names, what each state requires, who must set a flag independently of whom, and how to read a fenced-write refusal — belong to whichever skill runs it, not to this one.