Coding Assistant

The lab's implementation arm. Delegates code-writing tasks to a sandboxed coding sub-agent through scoped prompts. Reviews, integrates, and tests the result.

Status

Implemented. The Coding Assistant is the lab's mechanism for delegating implementation tasks. It is a thin wrapper that the Coordinator invokes when the user asks for code.

Role

The Coding Assistant is responsible for:

Receiving a code-writing task from the Coordinator.
Drafting a prompt that describes the goal and the boundaries (NOT the implementation).
Invoking the coding sub-agent with the prompt.
Reviewing the code the sub-agent produces.
Integrating the code into the target project.
Running the project's tests.
Reporting the result to the Coordinator.

The Coding Assistant does not write code directly. It is an architect and a reviewer, not a coder. The coding sub-agent is the coder.

Architecture

The Coding Assistant is a process that orchestrates the coding sub-agent:

Loading diagram…

Component	Purpose
Prompt Drafter	Compose the prompt from the task and the project context.
Coding Sub-agent	The external coder. The Assistant never writes code.
Reviewer	Inspect the code for obvious issues.
Integrator	Move the code into the project.
Test Runner	Run the project's tests.

Coding sub-agent

The coding sub-agent is an external command-line tool (Codex, in the lab's case). It has the following properties:

Runs in a sandboxed environment.
Has its own context window.
Can read the project's files (within the sandbox).
Can run shell commands (within the sandbox).
Has its own memory (separate from the Coordinator's).

The Assistant communicates with the sub-agent through the sub-agent's CLI. The CLI is documented in Cheatsheet → Codex CLI.

Sandbox and trust

The coding sub-agent runs in a sandbox. The sandbox level is configurable per invocation:

Level	What the sub-agent can do
`read-only`	Read files; cannot modify anything.
`workspace-write`	Read and write within the project directory.
`full`	Read and write anything the host can.

The default is workspace-write for code-generation tasks. The full level is reserved for tasks that require production access (rare; only with explicit user authorization).

The sandbox is configured per project. The configuration lives in the framework's main configuration file. A project that does not have a configuration falls back to read-only.

For the lab's projects, the configuration is in {workspace-root}/{project}/.agents/config.toml (or the framework's global config). The format is:

[projects."{workspace-root}/{project}"]
trust_level = "trusted"

The trusted level is equivalent to workspace-write.

Prompting

The Coding Assistant drafts the prompt. The prompt has the following structure:

# Goal
What the task is. One paragraph.
 
# Context
The relevant files, the relevant skills, the relevant
architecture decisions. Citations to the project's
`AGENTS.md`, `SKILL.md`, and `TOOL.md`.
 
# Constraints
What the sub-agent must NOT do. Examples: do not modify
unrelated files, do not commit, do not push.
 
# Acceptance criteria
How the result will be evaluated. Examples: the tests
pass, the lint passes, the documentation is updated.
 
# Reference
Links to relevant docs in the project.

The prompt describes what to build, not how to build it. Pre-written code is never included; the sub-agent writes original code from the description.

The prompt is written in English. The user-facing explanation (what the Assistant is doing and why) is in the user's language (Spanish for Kone).

Workflow

The Coding Assistant's workflow is the canonical "design → prompt → code → review → integrate → test" loop.

Loading diagram…

The Assistant loops on the "review" and "test" steps until the result is acceptable. The loop is bounded by a maximum number of iterations (default 3).

Code review

The Assistant reviews the code before integrating. The review is informal but consistent:

The code follows the project's conventions.
The code does what the prompt asked.
The code does not introduce new dependencies without justification.
The code does not modify unrelated files.
The code includes tests (if the project has tests).
The code includes documentation (if the project has documentation requirements).
The code does not contain secrets, credentials, or personal data.

If the review fails, the Assistant sends the review back to the sub-agent with a clear explanation of what needs to change. The sub-agent revises and returns the code.

Integration

The Assistant integrates the code by:

Reading the files the sub-agent wrote.
Moving them to the correct location in the project.
Updating any related files (imports, configs).
Updating the documentation (if the project has a documentation rule).
Verifying the project still builds.

The Assistant uses the project's directory layout and file-naming conventions. The conventions are documented in the project's AGENTS.md or README.md.

Test running

The Assistant runs the project's tests after integration. The test command is project-specific:

Node project: npm test or pnpm test.
Python project: pytest or unittest.
Mixed project: both.

The Assistant runs the tests and parses the output. If the tests pass, the task is complete. If the tests fail, the Assistant sends the failure back to the sub-agent with the error output.

The coding sub-agent can be killed by the OS (SIGKILL) when its task is too large. The symptom is exit code 137 and a log line containing Killed. This is a hard constraint of the sub-agent's environment.

Recovery procedure

When the sub-agent is killed, the Assistant follows this procedure:

Do not write the code by hand. The recovery rule is absolute. The Assistant never writes code directly.
Identify the task that killed the sub-agent. It is usually the largest file or the most complex phase.
Split the task into smaller prompts. The recommended rule: one file per prompt. Smaller prompts have lower memory and lower latency.
Re-run with a longer timeout (recommended: 120-180s for small tasks).
If the sub-agent still dies, consider a more aggressive split: header-only file first, then implementation, then tests.

If the sub-agent cannot be recovered after three attempts with progressively smaller prompts, the Assistant stops and asks the Coordinator for help. The Coordinator may need to adjust the environment (memory, swap) or use a different execution path.

The recovery rule is documented in Runbook → Coding Assistant killed by timeout.

Git

The Coding Assistant never commits, pushes, or pulls. Git is the Coordinator's responsibility. The Assistant leaves the changes uncommitted; the user decides when to commit and what to write in the commit message.

The Assistant can use git status and git diff to verify the changes; it does not run git commit, git push, or git pull.

Configuration

The Coding Assistant's configuration:

Field	Type	Default	Purpose
`coding_assistant.subagent_cli`	string	`codex`	The sub-agent's CLI command.
`coding_assistant.max_iterations`	integer	`3`	Max review/test iterations.
`coding_assistant.timeout_s`	integer	`180`	Per-invocation timeout.
`coding_assistant.prompt_template`	string	(see above)	The prompt template.
`coding_assistant.trust_level`	string	`workspace-write`	The default sandbox level.

Failure modes

Failure	Assistant response
Sub-agent is killed by timeout	Apply the recovery procedure (split prompts).
Sub-agent returns invalid code	Send the review back; iterate.
Tests fail	Send the failure back; iterate.
Project does not have a configuration	Fall back to `read-only`; surface a warning.
Git conflict	Surface the conflict; ask the user to resolve.
Sub-agent is unavailable	Surface the error; offer to retry later.
Sub-agent introduces a security issue	Reject the code; surface the issue to the user.

The full failure catalog is in Failure Catalog.

Future work

Multi-file prompts. Support prompts that span multiple files in a single invocation, with explicit boundaries.
Patch mode. Support sending a diff back to the sub-agent instead of the full file.
Test-driven prompts. Generate the prompt from a test file.
Sub-agent failover. Support multiple sub-agents with automatic failover.