# Agent Config — modal-shell
*Main entry point. Read this first, every session.*

## Quick Links

| File | Purpose |
|---|---|
| `worklog.md` | Session state: current focus, recently completed, next steps |
| `design.md` | Architecture overview and component map |
| `coding_standards.md` | Shell scripting conventions and testing |
| `mission.md` | Project goals and agent role |
| `narrative.md` | Background and history |
| `preferences.md` | User-specific preferences |
| `docs/adr/` | Architectural decision records |

---

## Core Mandates

### Safety Protocol

1. **Inquiry-Only Default** — Treat every message as research or analysis unless it is an explicit, imperative instruction.
2. **Zero Unsolicited Changes** — Never modify files or scripts based on assumptions about intent.
3. **Strategy Checkpoint** — Research first. Present approach. Wait for explicit approval before touching anything outside `.agent/`.
4. **Verify State First** — Check current state (`ls`, `git status`, `cat` the relevant file) before proposing changes.
5. **Destructive Operations Require Confirmation** — Any change that deletes, overwrites, or resets state must be confirmed explicitly.

### Living Documentation

1. **Update `.agent/` continuously** — When decisions are made, patterns emerge, or preferences are revealed, update the relevant file immediately.
2. **Worklog at start and end** — `worklog.md` reflects what was done this session and what comes next.
3. **ADRs for architecture decisions** — Any significant structural or tooling decision gets an entry in `docs/adr/`.

---

## Workflow

```
Research → Strategy → Execution
```

1. **Research** — Read the relevant mode files and base.sh. Understand the current pattern before proposing changes.
2. **Strategy** — Describe the change and why. For anything beyond a trivial edit, wait for a "go ahead."
3. **Execution**
   - Make the change.
   - Verify it works: run `ms <mode>` in a subshell or with `bash -n` for syntax.
   - Update `worklog.md`.

---

## Project Layout

```
modal-shell/
  ms                  # dispatcher (entry point for users)
  .envrc              # direnv: auto-sources base.sh on cd
  modes/
    base.sh           # sourced by all modes; env, secrets, PROJECT_ROOT
    db.sh             # database shell mode
    build.sh          # build pipeline mode
    reset.sh          # destructive rebuild mode (prompts for confirmation)
    logs.sh           # log streaming mode
  docs/
    adr/              # architectural decision records
  .agent/             # agent configuration (this directory)
  CLAUDE.md           # repo root entry point
```

---

## Essential Commands

| Command | Action |
|---|---|
| `ms <mode>` | Enter a named mode |
| `ms` (no args) | List available modes |
| `bash -n modes/<mode>.sh` | Syntax-check a mode file |
| `direnv allow` | Trust `.envrc` after changes |
| `source modes/base.sh` | Manually load base env |

---

## What NOT to Do

- Do not add logic to the `ms` dispatcher beyond finding and executing mode files.
- Do not store secrets in any file in this repo.
- Do not create modes that silently do destructive things.
- Do not introduce dependencies that aren't already in the base environment.