# Dev

> Load when implementing an issue or applying review fixes as a dev agent.

- Skill: `vanillagreencom/dev` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add vanillagreencom/dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vanillagreencom/dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: vanillagreencom (https://skillmd.com/u/vanillagreencom)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/vanillagreencom/dev

---


# Dev Workflows

orch is the caller and runtime: it owns delegation format, round acceptance, and every shell-shape rule.

| Workflow | Purpose |
|----------|---------|
| `workflows/dev-implement.md` | Implementation: activate → plan → implement → validate → commit → QA labels → summary → artifact → return (§ 1-11) |
| `workflows/dev-fix.md` | Review fixes: evaluate → apply or skip → validate → commit → artifact → return |

Review and QA-review belong to the reviewer skill: [`../reviewer/workflows/review.md`](../reviewer/workflows/review.md), [`../reviewer/workflows/qa-review.md`](../reviewer/workflows/qa-review.md). Command shapes are orch's [`../orch/SKILL.md`](../orch/SKILL.md) § Harness-Safe Shell; literal format tags and round mechanics are its [`../orch/references/skill-rules.md`](../orch/references/skill-rules.md) § Format Tags Are Literal and § Round Closure.

## Engineering Rules

- Scope is the issue's Done-when. A behavioral surface that does not trace to it stays out of this change, and a committed render of a source file you changed traces to whatever its source traces to. Two exceptions:
  - the mechanical enablers of landing it ride without tracing to it: locks, changelog, baselines, dismissal renewals, that list and nothing else, never code that runs at runtime;
  - a defect the change introduces or arms is in scope by definition, unless Step 0 of [`../orch/references/finding-disposition.md`](../orch/references/finding-disposition.md) excludes it.
- Every behavior change ships with a test that runs against the script or program enforcing it, at the smallest surface that fails. A workflow sentence ships no test. A test that pins prose, drives a second implementation, or stubs the function under test does not count as a test.
- A review finding adds a case only when it names a behaviour no existing case reaches. Otherwise it tightens the existing case's assertion, and the item reasoning names that case.
- A second fix round on the same function's guard is recurrence: redesign the rule under test so the class is unrepresentable, and fold the family of cases into one table.
- A test whose premise died is deleted whole in the commit that kills the premise, and the PR body names the deletion.
- Test shape (one control per surface, tables for shaped input, one file per surface) is [code-quality § Tests](../code-quality/SKILL.md#tests).
- A refusal, a validator, a lock, a retry, or a test exists only for an input a real producer emits, this project's code or anything it calls or serves; name that producer beside it, or do not write it.
- When a change deletes a call, apply [code-quality § Cleanup](../code-quality/SKILL.md#cleanup) to its callee. Its deletion maps to the call removal's Done-when item; no internal caller is not proof that a supported external API is unused.
- A field, setting, or view member added by the change has a real producer and consumer. A named and documented external producer or consumer is valid when the change adds its in-repository counterpart; otherwise, add both sides in the change.
- No migration or compat code for this project's own formats, its manifest, settings, lock and cache shapes, never another tool's on-disk state, which an adapter may have to keep recognising: write no reader for an artifact an older version of this project wrote, and decline a finding that asks you to carry one forward. A layout, schema or cache change is one changelog line and a fresh install.
- Before adding a function, parser, stub or loop, grep the repo for the verb it performs; before stating a rule, grep for the rule.
  - A second copy of that verb, in any language, is a twin and never delegation, and so is a second statement of a rule another file owns, in prose, config or a table.
  - Call or cite the one that exists, or escalate in your return. An issue that orders a twin is escalated, not implemented.
- Docs move with the code they describe; the `docs-writing` skill states the rule and the `doc-drift-check` hook names the docs that may need an update.
- Once a commit has been reported to the orchestrator, in a return artifact or in a message naming it, later work adds a commit and never amends, whatever the branch push state. The one exception is a head the orchestrator states is unread: there the kendex-issues fix cycle may amend, only to refresh a required check that cannot be rerun.
- A push that prints `rebase-map:` lines has rewritten the shas the PR's `Fixed in <sha>` replies name: before holding, re-reply each such thread with the new sha, or post the map as one PR comment naming old and new per line; a sha the map reports as `dropped` gets a reply that the fix commit no longer exists on the branch.

Code standards are [`../code-quality/SKILL.md`](../code-quality/SKILL.md): correctness, comments, over-engineering, cleanup.

## Round Contract

Execute workflow sections in order; a "**Skip if**" condition is the workflow's decision, never your own scope assessment. Never push and never open a PR. The orchestrator does that after review passes. A finding on a mechanism this diff introduces or arms is a fix whatever the round, unless Step 0 of the disposition flow excludes it; a `Declined:` there takes one of the reason forms [`../orch/references/finding-disposition.md`](../orch/references/finding-disposition.md) § Decision flow sets out, never a label or a test count.

**The completion artifact is the round.** `dev-return-write` writes it after the commit; never hand-author the JSON (schema: orch [`schemas/dev-return.md`](../orch/schemas/dev-return.md)).

- `--issue` is the delegation's `Artifact Key:` line, the normalized workflow-state key (`issue-N` for GitHub, `PROJ-123` for Linear), never the tracker-native `OWNER/REPO#N` or a bare number. `--round-id` is its `Round ID:` line.
- `--kind` always matches what was delegated. `--validate` matches your commit message and return. `--validate-note` carries the test-only validation-ceiling report when that route applies. Flag constraints and value shapes: `dev-return-write --help`.

**Acceptance is that artifact plus git state, never your message.** Write the artifact, then return exactly once over the harness's agent-to-agent channel; a disk write is not a return. Send the `**Return exactly**` body once and go idle.

- The channel is Claude Code `SendMessage`, Codex `send_input`, OpenCode a resume on the stored `task_id`, Pi background the final assistant message.
- In a Pi persistent pane, follow the return with `complete_subagent`; background agents must not call it.
- On Codex the `send_input` MESSAGE is the durable return, and the runtime's `FINAL_ANSWER` echo of it is expected, not a separate return to author or expand.

## Validation

The validation gate and role ownership are complete in [dev-implement.md § 5. Validate](workflows/dev-implement.md#5-validate). Run no proof, rerun, receipt, isolation step, or approval step that section does not name. That section also owns the one proposed-rule route and the per-rule control for production gate and guard changes.

### Long-Running Validation

**Invariant, every harness:** the completion tail (commit → QA labels → summary → artifact → return) is never dropped, and an interrupted run is never success. Re-check its real outcome and resume the tail.

`.agents/skills/orch/scripts/dev-validate-run` runs the validation command for every harness. It bounds the command with `DEV_VALIDATE_TIMEOUT_SECS`, detaches it so the run outlives the shell that launched it, and records the verdict as one `guard-exit=N at=TIME` line beside the log. The wait's cap is that setting plus the kill grace and one poll interval; never choose any of those numbers yourself. Full contract: `dev-validate-run --help`.

- **Claude Code.** Background the BARE command `.agents/skills/orch/scripts/dev-validate-run --worktree [WORKTREE_PATH]` via `run_in_background`, never piped or chained, and read the `run-dir=` value off its `state=started` line. Then poll in the foreground with `.agents/skills/orch/scripts/dev-validate-run --wait --run-dir [RUN_DIR]`, under the harness's maximum command timeout because one call runs for up to nine minutes, repeating for as long as it exits 3 and prints `state=running`. Never idle for the completion notice and never depend on a background poller for it: the harness can kill your background shell on a low-memory heuristic that fires with free memory to spare, and the notice then never comes. Neither loses the verdict, because the sentinel is on disk. The verdict is the `guard-exit=` value on the `state=done` line; the log holds command output and never an exit status. `state=timeout` and `state=lost` are both failed validations. Then resume the tail.
- **Codex.** Run `.agents/skills/orch/scripts/dev-validate-run --worktree [WORKTREE_PATH]` in the foreground and block. Where the harness's own foreground ceiling cuts that call off, the run and its verdict are still on disk: resume with `--wait --run-dir` on the `run-dir=` value from the `state=started` line, as Claude Code does.
- **Pi.** Run that same command in the foreground, and resume a call the harness cut off the same way.

## Reflect

**Skip if** nothing recurred and nothing surprised you. Otherwise put the lesson where it will be read again: architecture docs when an invariant, boundary or decision changed (the `docs-writing` skill says what belongs there), or the managing project's kendex config (`kendex.toml` at the kendex project root, `kendex-local.toml` in a source-catalog checkout) under `[skill-instructions]`, `[agent-additional-instructions]`, or `[agent-launch-instructions]`. Bar: would this save 5+ minutes in a future session? One surgical addition per lesson, no verbose examples. A config edit takes effect only once it is rendered, which you cannot do from a worktree, so name it, and anything else you cannot update yourself, in your return as `[process]` discovered work.

## Configuration

Agent-type placeholders are project-configurable: `[AGENT_TYPE]` (dev agents receiving implementation delegations), `[REVIEW_AGENT]`, `[QA_AGENT]`. Commit format: `[PREFIX]([ISSUE_ID]): [DESCRIPTION]`. `DEV_VALIDATE_CMD` (`kendex.settings.toml` `[env]`) names the project's full validation command for the Validate step; an empty value is the validation failure [dev-implement.md § 5. Validate](workflows/dev-implement.md#5-validate) states, never a fallback. `DEV_VALIDATE_TIMEOUT_SECS` (same table, default 3600) is how long that command may run, and the only number § Long-Running Validation derives its cap from.