Agent Devcontainer Setup

This repository contains a lightweight development container setup for working with coding agents.

Prerequisites

• Docker Engine with Docker Compose plugin
• Visual Studio Code
• VS Code extension: Dev Containers (ms-vscode-remote.remote-containers)

Build the Devcontainer Image

Build parameters are defined in docker/micro_devcon.Dockerfile.

cd /path/to/micro_devcon
docker build -f docker/micro_devcon.Dockerfile -t micro_devcon:1 .

Runtime Model

• The image is built on the host.
• VS Code opens the project with Dev Containers: Reopen in Container.
• The repository is bind-mounted as the container workspace at /workspace.
• The container runs as a non-root user (vscode) with UID/GID synchronization.
• Host SSH agent is not forwarded into the container.
• Git authentication and git push are performed on the host only.

Open in Dev Container (Recommended Workflow)

1. Open this folder in VS Code.
2. Build the image on the host if needed:

   docker build -f docker/micro_devcon.Dockerfile -t micro_devcon:1 .

3. Run Dev Containers: Reopen in Container.
4. Develop and run tooling inside the container workspace.
5. Perform Git authentication and push from the host terminal or host VS Code instance.

VS Code Extensions (Prompt-Based Install)

This repository includes .vscode/extensions.json with recommended extensions. When VS Code opens the workspace, it prompts to install recommended extensions.

Context Handoff for Agent Sessions

Agent chat memory is temporary. Persist working context in files:

• AGENTS.md - baseline rules and workflows
• README.md - architecture and operational guide
• TASKS.md - prioritized backlog and task status
• PROJECT_STATE.md - current state, decisions, and next steps
• .env.example - required environment variables template

Rebuild-Safe Session Flow

Use these steps to preserve intermediate progress when container rebuild/reset is possible:

1. Before rebuild or restart, update PROJECT_STATE.md with current status, decisions, blockers, and the exact next command.
2. Update TASKS.md to mark in-progress and done items, so both a human and an agent can resume without chat history.
3. If runtime behavior changed, update README.md in the same session.
4. Rebuild/reopen the devcontainer.
5. Start the next session by reading AGENTS.md, README.md, PROJECT_STATE.md, and TASKS.md in that order.

Daily Workflow

1. Start session: read AGENTS.md, README.md, PROJECT_STATE.md, TASKS.md.
2. Build/rebuild the container image on the host when configuration changes.
3. Implement scoped changes in the devcontainer workspace.
4. Run Git authentication operations (git push, signing, key usage) on host only.
5. Update PROJECT_STATE.md and TASKS.md before finishing.
6. Commit only relevant files with an English commit message.