development-implementation

Files (9)

• README.md
• SKILL.md
• evals.json · evals/
• claude.md · intelligence/
• codex.md · intelligence/
• gemini.md · intelligence/
• hf.md · intelligence/
• ollama.md · intelligence/
• launcher.md

SKILL.md (first lines)

# Development Implementation

## Purpose

Execute a `tl_instruction.md` produced by `development-plan` — implement each task from failing tests, in controlled per-task TDD cycles, with verification and a self-owned closing commit, or a pause commit when a chain's context cap is passed.

The instruction is a **pure scaffold**: module responsibilities, behaviours to verify, and hints for complex tasks. It carries no commit choreography and no execution metadata. This skill owns the commit structure (per-task TDD commits, then the closing commit, or a pause commit when a chain's context cap is passed) and sources execution context from `system/projects/<project>/project.md`. A run that pauses finishes the task it is on and stops there. The chain starts a fresh run at the next task, and that run's launch prompt says where to start (Step 2).

**Own the finished result, including the work you inherit.** Step 2 § *Work and repair* governs implementation, verification and correction. § *Deferring a task* governs external impediments; § *When to Stop* governs run-level halts.

The developer's job is **not to transcribe the instruction into code** — it is to critically review what they received and produce a better-implemented result than the scaffold alone prescribes. The developer is the last quality gate before the code lands, exactly as the Tech Lead is the last quality gate before the developer. Improvements are made, and every improvement is logged — same discipline `development-plan` applies to the architect's design.

**Announce at start:** "I'm using the development-implementation skill to execute the `tl_instruction.md`."

## When to Use

- Stage 5 (Developer) of the iteration pipeline — after `development-plan` has produced and committed `tl_instruction.md`, and, when the design's `Publishes text:` line reads `yes`, after `development-content` has committed `change_text.md`.
- Auto-invoked in any execution session running a `tl_instruction.md`, whether headless or Docker sandbox.

## Enter the worktree

The upstream stages ran inside an isolated worktree for this change — development-specs created it and landed `change_spec.md` on the branch, development-design and development-plan added `change_design.md` and `tl_instruction.md` there. None of it is on `main`. This is the **only** stage that writes code, so landing on the wrong branch silently breaks the worktree isolation every upstream stage preserved — entering correctly is not optional.

- **Headless runs (host terminal):** derive the worktree from the **change key** and `cd` into it before reading anything; operate inside it for the whole run.
- **Docker sandbox runs:** the launcher mounts the checked-out branch at `/workdir` — skip this derivation; `$WORKTREE` is `/workdir` and the Docker startup gate (Step 1) verifies it.

The **change key** is `<YYYY-MM-DD>_<slug>` — the Tobiishi folder (`journey/tobiishi/<key>/`) / branch name. You know it from the invocation (the change you were asked to execute). If multiple worktrees exist under `<repo>/.worktrees/` and the intended change is ambiguous, ask which one — once.

```bash
# Run this FIRST, from the instance root, before any `cd` — it answers from the CWD.
REPO_ROOT=$(git rev-parse --show-toplevel)        # the INSTANCE repo
WORKTREE="$REPO_ROOT/.worktrees/<key>"
test -d "$WORKTREE" || echo "No worktree for <key> — the upstream stages must run first."
cd "$WORKTREE"
```

If `$WORKTREE` does not exist, **halt** (§ *When to Stop*, first case — no task could land): the upstream stages have not run for this change. Do not create it here and do not fall back to `main`.

**Write `$WORKTREE`'s value down — the absolute path, in your own prose — before you `cd` anywhere.** Two things make the variable alone unsafe. A shell variable does not survive from one command to the next: each command runs in a fresh shell, so `$WORKTREE` in a later command expands to the empty string and `git -C ""` silently means *here*. And for an **external product** this run spends most of itself inside the *product* worktree, which carries a `.worktrees/<key>` of its own on a branch of the same name — so re-deriving from `git rev-parse --show-toplevel` after that `cd` answers with the product worktree and nothing looks wrong. Every `$WORKTREE` below means the instance path you wrote down at entry.

**From here on, `$WORKTREE` is the working root (the CWD):** read every input from `$WORKTREE/` (`tl_instruction.md`, `change_design.md` under `system/projects/<project>/journey/tobiishi/<key>/`), write all code under `$WORKTREE/`, and commit from inside it. The change arc stays on the branch, never `main`. The path is derived from the key alone — identical convention to development-specs Step 4, development-design, development-plan, and `ad-hoc-plan`; nothing is handed between sessions.

**Locate the project.** The orchestrator passes the **project name** `<project>` alongside the change key; the change-work folder (pipeline-side) is `$WORKTREE/system/projects/<project>/journey/tobiishi/<key>/`. The product root is separate (`<name>` below — it may differ from `<project>` and may even be external). The project's code and decision files are **not** assumed to be at the worktree root — a repo may hold more than one project, each owning its own `docs/` and source tree.

**Resolve `PROJECT_DOCS`**, then derive the project root from it. The step resolves it itself, every
run, from the path tool's contract — the one call § *Where each commit goes* makes at entry — and never
composes a product path by hand:

```bash
# From the contract's product_path, product_repo and product_worktree:
#   <sub>        = product_path when it is relative, else product_path relative to product_repo ('.' when the same)
#   PROJECT_DOCS = "<product_worktree>/<sub>/docs"
#     in-repo:  product_worktree is $WORKTREE, so PROJECT_DOCS="$WORKTREE/<sub>/docs"
#     external: product_worktree is the product worktree create_change_worktree.py opened for this change;
#               never the product's primary checkout
PROJECT_ROOT="$(dirname "$PROJECT_DOCS")"                     # e.g. $WORKTREE/<product> or $WORKTREE
```

Do **not** re-derive `PROJECT_DOCS` from any header in the change_spec (the `Project:` header is retired). `<name>` (used throughout below as the project root) is the path from the worktree root to `$PROJECT_ROOT` — `<product>` for the multi-project playground, `.` for a single-project repo. **All code and tests live under `$PROJECT_ROOT/` (the test command is the one exception, § *Execution context* below); every `<name>/docs/<file>` reference resolves to `$PROJECT_DOCS/<file>`** — never the worktree-root `docs/` unless `PROJECT_DOCS` points there.

## Roots and paths

This skill operates across **two roots**, both resolved in **Enter the worktree** above — the same separation `project-*` skills use, rebased onto the change worktree (the same `PROJECT_DOCS` resolution development-design and development-plan use):

| Root | Holds | Where it is |
|---|---|---|
| **pipeline-root** = `$WORKTREE` (the CWD) | `system/projects/<project>/journey/tobiishi/` | `<repo>/.worktrees/<key>` (headless) or `/workdir` (Docker mount) |
| **project-root** = `<name>` = `$PROJECT_ROOT` | `docs/adr/`, code, tests | `$(dirname "$PROJECT_DOCS")` — `$WORKTREE/<product>` (multi-project) or `$WORKTREE` (single-project) |

Every project-side path is qualified with `<name>/`; every pipeline-side path is bare from the CWD (which is `$WORKTREE`).

- **Project-side** (qualified with `<name>/`): `<name>/docs/adr/`, code, tests. Read `docs/adr/` and write all code here. The test command is the one exception: it runs from the root of the product's change worktree, not from `<name>/` — `$WORKTREE` for an in-repo product, the product worktree for an external one (§ *Execution context*).
- **Pipeline-side** (bare from the CWD = `$WORKTREE`): `system/projects/<project>/journey/tobiishi/<key>/{tl_instruction,change_design}.md`.

If `PROJECT_DOCS` is unresolved (the `project.md` resolution above yields nothing) and `<name>` cannot be derived from the instruction's `## Project layout` top directory, **halt** (§ *When to Stop*, first case), and in an interactive session ask for the project root — do not guess.

## Where each commit goes

A change's product is either **in-repo** (code inside `$WORKTREE`) or **external** (code in its own git
repo). Which it is, and which repo takes which commit, is not read by hand — ask the path tool once, at
entry, after writing `$WORKTREE` down:

```bash
python3 "<CORE>/tools/development_path.py" resolve --format json \
  --worktree "$WORKTREE" --project <project> --key <key>
```

It reads `Product path:` from `project.md` (the single source) and returns, among the rest,
`code_worktree` and `pipeline_worktree`, and the `product_path`, `product_repo` and `product_worktree`
that `PROJECT_DOCS` above is built from. A non-zero exit is a halt (§ *When to Stop*), with the tool's
`message` in the report.

- **Code commits → `code_worktree`.** It is the worktree `$PROJECT_ROOT` sits in. For an external
  product that is the **product** worktree (the contract's `product_worktree`, where `PROJECT_DOCS` above
  sits): `cd` there for the per-task TDD cycles so
  `test-driven-development`'s commits land on the **product** branch.
- **Pipeline commits → `pipeline_worktree`** — the instance worktree, `$WORKTREE`. The closing commit is
  one: its `--repo` is the instance worktree you wrote down at entry, and for an external product it is
  **not** the `--repo` every per-task commit of this run carried.

For an in-repo product the two are one path — a single repo, CWD stays `$WORKTREE`, nothing differs.
For an external product they are two repos, and that is the whole difference. A write into a third repository is neither kind of commit: Step 2 § *A write into another repository*.

## Inputs

All inputs are **read-only**. Read the instruction, design and specification together; implement the change from their combined contract and record corrections to the instruction in Developer Review Notes.

| File | Root | Role | How it is used |
|---|---|---|---|
| `system/projects/<project>/journey/tobiishi/<key>/tl_instruction.md` | pipeline | **execution plan** | task sequence, scaffold, test cases and verification gates |
| `system/projects/<project>/journey/tobiishi/<key>/change_design.md` | pipeline | **technical contract** | implement the interfaces, topology and technical decisions; recover details the instruction omits |
| `system/projects/<project>/journey/tobiishi/<key>/change_spec.md` | pipeline | **behavioural contract** | implement the scope, business rules and acceptance criteria; recover details the instruction omits |
| `system/projects/<project>/journey/tobiishi/<key>/change_text.md` | pipeline | **the published words** | present only when the design's `Publishes text:` line read `yes` and the Content Editor ran. Every published string this run places comes verbatim from it; read it with the rest of Step 1's inputs |
| `<name>/docs/adr/` | project | **the decision log** | consulted on demand for the *why* behind a topology or import boundary, read headline-first through its index. An **Accepted** record is binding; one still **Proposed** is context |
| `<name>/docs/nfdr.md` | project | **the constraint set** | § 1.2 for the module set and the import graph, on demand |
| `<name>/docs/SDD.md` § 3 | project | **the parts table** | for every task that adds logic: `Owns` and `Must not own` say which part owns it, and `Lives in` where that part's code is (Step 1b). A product with none says so in the `Step 1b review:` block |
| Language packets, resolved per `<CORE>/doctrine/engineering/languages/README.md` | project | **required** | resolved every run and the result recorded, whatever it is — every concern the packet's router lists accounted for, and every clause the implementation turns on quoted verbatim with its line, never summarised (Step 1 sub-step 3). A packet that exists is read for the run's language practice and binds over the surrounding file's own style; no packet for the resolved language means proceed on `<CORE>/doctrine/engineering/languages/developer_standards.md` — still recorded, still never a STOP |

Follow cited product-document sources when needed to resolve a detail or constraint; a prior upstream review does not replace the developer's judgment. Step 1b owns how omissions and disagreements are resolved.

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp