1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
# 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.
|
