Dev

Project Instructions

Problems with a kendex-owned skill go through kendex report; check ownership in the file first.

Dev Workflows

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

Review and QA-review belong to the reviewer skill: ../reviewer/workflows/review.md, ../reviewer/workflows/qa-review.md. Command shapes are orch's ../orch/SKILL.md § Harness-Safe Shell; literal format tags and round mechanics are its ../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 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.
• 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 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: 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 § 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).

• --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. 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 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.