Skip to content
jackin'

Per-directory README + AGENTS.md

Status: Open — Phase 1, no confirmation needed

Problem

Section titled “Problem”

AI coding agents (Claude Code, Copilot, Cursor) load README.md automatically when they enter a directory context. Without these files, agents must open source files to get orientation. After the Cargo workspace split, each crate also needs an AGENTS.md for crate-specific agent rules.

Target directories

Section titled “Target directories”
DirectoryREADME should say
src/Top-level module map + entry points (load_agent, run_console, validate). Link to PROJECT_STRUCTURE.md.
src/runtime/Container bootstrap pipeline. Entry: load_agent() in launch.rs. 4-step sequence.
src/console/Operator console TUI. Entry: run_console(). Two subsystems: manager/ and widgets/. Note: has 2 production dependencies on runtime/ (register_agent_repo, RepoError).
src/console/manager/Workspace manager TUI. 3-layer: state.rs (data), input/ (dispatch), render/ (drawing).
src/console/widgets/Reusable TUI widget library. Each widget is a self-contained state machine.
src/config/Configuration loading, persistence, editing. TOML schema, migrations, workspace files.
src/instance/Per-instance state: container identity, auth provisioning, manifests. 5 agent-specific provision functions.
src/isolation/Mount isolation: materialize, finalize, cleanup, state records.
docs/Astro Starlight docs site. Public docs live in src/content/docs/.

AGENTS.md per crate (after workspace split)

Section titled “AGENTS.md per crate (after workspace split)”

When the Cargo workspace split creates crates/jackin-console/, crates/jackin-runtime/, etc., each crate should get its own AGENTS.md with crate-specific rules — shorter and more focused than the root AGENTS.md. Examples:

  • crates/jackin-core/AGENTS.md — “this crate has no I/O, no std::process::Command; keep it that way”
  • crates/jackin-console/AGENTS.md — “no import from jackin-runtime except through the 2 approved call sites; this is enforced by Cargo”
  • crates/jackin-runtime/AGENTS.md — “all Docker operations go through CommandRunner; never shell out directly”

Steps

Section titled “Steps”
  1. Create src/README.md through docs/README.md with the content above.
  2. Keep each file under ~20 lines — orientation only, not comprehensive documentation.
  3. After the workspace split, add AGENTS.md to each crate directory.

Caveats

Section titled “Caveats”

These files are not CI-checked for staleness (that’s the CI gate item). They will drift if modules change significantly — the workspace split is a natural opportunity to refresh them.