Skip to content

Commit 03d4d02

Browse files
ocotsocots
committed
Add philosophy documentation and agent guides
- Add AGENTS.md: Agent navigation guide for CTBase.jl - Add CLAUDE.md: Claude project context with essential rules - Add dev/philosophy/: Code philosophy documentation (modules, types/traits, exceptions, docstrings, testing, docs) - Add dev/planning.md: Implementation plan template - Add dev/RULES.md: Operational rules (MCP, doc build, git, output capture) These documents provide the foundational standards for the control-toolbox ecosystem, adapted from CTFlows to be generic for all packages.
1 parent 7d29959 commit 03d4d02

11 files changed

Lines changed: 1165 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# CTBase.jl — Agent Navigation Guide
2+
3+
Quick-reference for any agent working on this repository.
4+
5+
---
6+
7+
## Project Overview
8+
9+
**CTBase.jl** is the foundational Julia package in the [control-toolbox](https://github.com/control-toolbox) ecosystem.
10+
It provides the **base layer**: shared types, exceptions, extensions infrastructure, and development tools.
11+
12+
---
13+
14+
## Source Architecture
15+
16+
Submodule layout (all public symbols accessed via qualified paths — no top-level exports):
17+
18+
```text
19+
src/
20+
├── CTBase.jl # Top-level manifest — exports nothing
21+
├── Core/ # Core types and utilities
22+
├── Descriptions/ # Type descriptions and metadata
23+
├── Exceptions/ # Structured exception types
24+
├── Extensions/ # Extension infrastructure
25+
└── Unicode/ # Unicode utilities
26+
27+
ext/
28+
├── CoveragePostprocessing.jl # Coverage report postprocessing
29+
├── DocumenterReference.jl # Documenter.jl reference generation
30+
└── TestRunner.jl # Test runner with progress bar
31+
32+
test/suite/ # Tests organised by functionality (not by src layout)
33+
docs/ # Documenter.jl site (auto-generated API)
34+
dev/ # Code philosophy, operational rules, plan template (versioned)
35+
```
36+
37+
---
38+
39+
## Developer resources
40+
41+
| File | Purpose |
42+
|---|---|
43+
| [`dev/philosophy/PHILOSOPHY.md`](dev/philosophy/PHILOSOPHY.md) | Code philosophy — modules, types/traits, exceptions, docstrings, testing, docs |
44+
| [`dev/RULES.md`](dev/RULES.md) | Operational rules — running tests (MCP), building docs, git, output capture |
45+
| [`dev/planning.md`](dev/planning.md) | Plan template — phases, steps, human checkpoints |
46+
47+
---
48+
49+
## Devin Workflows
50+
51+
| Workflow | Trigger | Purpose |
52+
|---|---|---|
53+
| `architecture.md` | — | Introducing new types, restructuring modules, reviewing SOLID/patterns |
54+
| `docstrings.md` | — | Writing or reviewing Julia docstrings |
55+
| `documentation.md` | `glob: docs/**/*` | Documenter.jl layout, `make.jl` template, `api_reference.jl`, `InterLinks` setup |
56+
| `exceptions.md` | — | Adding error paths, contract stubs, argument validation |
57+
| `modules.md` | `glob: src/**/*.jl, ext/**/*.jl` | Submodule conventions: qualified imports, manifest pattern, export policy, DAG ordering |
58+
| `performance.md` | — | Hot paths, inner loops, profiling, benchmarking |
59+
| `plan.md` | — | Writing an implementation plan before coding |
60+
| `testing-creation.md` | — | Writing or reviewing test files under `test/suite/` |
61+
| `testing-execution.md` | `model_decision` | How to run tests (commands, `tee` capture) |
62+
| `type-stability.md` | — | New structs, parametric types, `@inferred` test design |
63+
64+
Workflows live in `.devin/workflows/`.
65+
66+
---
67+
68+
## Key Conventions
69+
70+
- **No top-level exports** — use `CTBase.Submodule.symbol` everywhere.
71+
- **Qualified imports** — `using PackageName: PackageName`, never bare `using`.
72+
- **Fake types at module top-level** — never inside test functions.
73+
- **Plans before code** — write a plan and confirm with the user before touching files. Template: [`dev/planning.md`](dev/planning.md).
74+
- **Docstrings last** — written only after all implementation steps are stable.
75+
- **Never commit or push without explicit user approval.**

‎CLAUDE.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# CTBase.jl — Claude project context
2+
3+
## Essential rules
4+
5+
1. **Never commit or push without explicit approval.** Ask first, every time.
6+
2. **Run tests via the `ct-dev-mcp` MCP** — `get_test_command` → run with `tee` →
7+
`generate_report`. Never invent the test command.
8+
3. **Build docs draft-first** — `draft = true` globally to validate links, then per file
9+
with `Draft = false`, then full build. See `dev/RULES.md`.
10+
4. **Qualify everything** — `Module.symbol` at every call site; `import Pkg: Pkg` not
11+
`using Pkg`; no top-level package exports.
12+
5. **Write a plan before coding** — any task touching more than one file or a public
13+
interface needs a plan confirmed by the user first. Template in `dev/planning.md`.
14+
6. **Docstrings last** — written only after the API is stable.
15+
7. **Fake types at module top-level** — never inside test functions (world-age issues).
16+
17+
## Where to find more
18+
19+
| Topic | File |
20+
| --- | --- |
21+
| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`dev/philosophy/`](dev/philosophy/PHILOSOPHY.md) |
22+
| Operational rules (MCP, doc build, git, output capture) | [`dev/RULES.md`](dev/RULES.md) |
23+
| Plan template | [`dev/planning.md`](dev/planning.md) |
24+
25+
## Project structure (quick reference)
26+
27+
```text
28+
src/CTBase.jl # top-level manifest — exports nothing
29+
src/<Module>/<Module>.jl # submodule manifests
30+
ext/ # weak-dependency extensions (CoveragePostprocessing, DocumenterReference, TestRunner)
31+
test/suite/ # tests by functionality, not by src layout
32+
docs/ # Documenter.jl site
33+
dev/ # philosophy, rules, planning template (versioned)
34+
```

‎dev/RULES.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# RULES — tools and procedures for a development agent
2+
3+
**Generic** rules (valid for any Julia package in the control-toolbox ecosystem, with
4+
no reference to a specific package's code). They describe *how to work*: run tests,
5+
build docs, handle git, capture output. For *how to design*, see
6+
[`philosophy/`](philosophy/PHILOSOPHY.md).
7+
8+
---
9+
10+
## 1. Running tests — via the `ct-dev-mcp` MCP server
11+
12+
Do not invent the test command. Use the MCP server that provides it and can parse the
13+
result.
14+
15+
1. **Get the command**: call the `get_test_command` tool with:
16+
- `cwd` = package root (where `Project.toml` lives) — **required**;
17+
- `test_args` = scope (empty = everything; `["test/suite/<group>"]`; a single file;
18+
a glob `["test/suite/*/*_flow*"]` passed **quoted** — TestRunner expands it, not
19+
the shell).
20+
2. **Run** the returned command verbatim. It already includes
21+
`… 2>&1 | tee /tmp/ct-dev-mcp/<pkg>_<scope>_<id>.log`.
22+
3. **Analyze**: call `generate_report(<log_file>)` on the returned log for a structured
23+
Markdown report (summary, first failures, compilation errors).
24+
25+
Rules:
26+
- **Always `tee` the full log**; never truncate with `tail -N` live — the first error
27+
(often a compilation error) is usually *above* and would be lost, forcing a rerun.
28+
- Inspect the saved log afterwards with `grep`/`rg`/`tail`/`less`, without rerunning.
29+
- Logs go under `/tmp/…`; **never** commit them.
30+
- Run the **targeted** suite first (fast iteration), then the **full** suite before
31+
considering a phase done (regression check).
32+
33+
---
34+
35+
## 2. Building documentation — "draft first" workflow
36+
37+
`docs/make.jl` exposes a `draft` switch. In **draft mode**, the Julia code in
38+
`@example`/`@setup` blocks is **not executed**: the build is fast and validates the
39+
structure, the `@ref`/`@extref` links and the paths. In non-draft mode everything runs
40+
(slow but actually checks the examples).
41+
42+
```julia
43+
# docs/make.jl
44+
draft = true # does not execute Julia cells
45+
```
46+
47+
A **single file** can also be forced to non-draft via a meta block, keeping the rest in
48+
draft — to debug one file quickly:
49+
50+
````markdown
51+
```@meta
52+
Draft = false
53+
```
54+
````
55+
56+
**Recommended procedure**:
57+
58+
1. **`draft = true`** (global) → build once. Fix all broken **links** (`@ref`/`@extref`)
59+
and paths. Fast.
60+
2. **File by file**: set one file to `Draft = false` (meta block), rebuild, debug its
61+
`@example` blocks, fix. Repeat per page. Faster than running everything each time.
62+
3. **`draft = false`** (global) → final full build, zero execution warnings.
63+
64+
On every build, **`tee`** the output to `/tmp/…` and filter (`grep -E
65+
"Error|Warning.*failed|MethodError|UndefVar"`).
66+
67+
---
68+
69+
## 3. Git & commits
70+
71+
- **Never commit or push without explicit user approval.** Even after validated work,
72+
ask before `git commit`/`git push`.
73+
- Do not commit on the default branch: branch off the correct base.
74+
- Interactive flags (`-i`) are not supported in this environment.
75+
- Prefer the `gh` CLI for GitHub operations (PRs, issues).
76+
- End commit messages with the required `Co-Authored-By` trailer; end PR bodies with
77+
the required generation note.
78+
- Do not commit transient files (`/tmp/*.log`, doc-build artifacts).
79+
80+
---
81+
82+
## 4. Editing files
83+
84+
- Prefer the **dedicated tools** (read/edit/write) over `cat`/`sed`/`awk`/`echo` in the
85+
shell for reading or modifying files.
86+
- **Read before editing**; do not overwrite a file you have not read.
87+
- An edit should match the surrounding code (style, naming, comment density).
88+
89+
---
90+
91+
## 5. Capturing long output
92+
93+
- Any verbose command (tests, doc build): `… 2>&1 | tee /tmp/<pkg>_<scope>.log`.
94+
- Name the log by package + scope to avoid collisions between sessions.
95+
- Filter the log *afterwards*; do not rerun just to get more context.
96+
97+
---
98+
99+
## 6. Ask vs proceed
100+
101+
- **Ask** before any hard-to-reverse or outward-facing action (commit, push, sending to
102+
an external service, deleting/overwriting files you did not create).
103+
- **Proceed** on choices with an obvious default (style, conventional location),
104+
stating it, rather than blocking on a question.
105+
- Report outcomes faithfully: if tests fail, say so with the output; if a step was
106+
skipped, say that.
107+
108+
---
109+
110+
## Quick checklist
111+
112+
- [ ] Tests run via `ct-dev-mcp` (`get_test_command` → run+`tee` → `generate_report`).
113+
- [ ] Targeted suite green, then full suite green.
114+
- [ ] Docs built in draft (links OK), then per file, then full.
115+
- [ ] No git action without explicit approval.
116+
- [ ] Dedicated file tools used; files read before editing.
117+
- [ ] Long output captured via `tee` under `/tmp`.

‎dev/philosophy/PHILOSOPHY.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Code philosophy
2+
3+
Design philosophy for the control-toolbox ecosystem, written **abstractly**: the
4+
principles apply to all packages, but the examples and templates stay **generic**
5+
(no package-specific symbols). For *tools and procedures* (tests, docs, git), see
6+
[`../RULES.md`](../RULES.md).
7+
8+
## The tenets on one page
9+
10+
1. **One module per responsibility.** Each submodule has a single role, its own
11+
directory, its own manifest. The package manifest exports **nothing**.
12+
→ [`modules.md`](modules.md)
13+
14+
2. **Everything is qualified.** Import modules, not their symbols; call
15+
`Module.symbol` everywhere. Explicit origin, safe refactors, no shadowing.
16+
→ [`modules.md`](modules.md)
17+
18+
3. **One abstract type per *noun*, one trait-parameter per *adjective*.** Conceptual
19+
variants ("is it an X or a Y") are types; orthogonal axes (autonomous?, in-place?, …)
20+
are traits in a type parameter. Dispatch by extracting the trait.
21+
→ [`types-traits-interfaces.md`](types-traits-interfaces.md)
22+
23+
4. **Program against abstractions.** Methods live on abstract types as much as
24+
possible; contracts are `NotImplemented` stubs; subtypes honor the contract (LSP).
25+
→ [`types-traits-interfaces.md`](types-traits-interfaces.md)
26+
27+
5. **SOLID, DRY, KISS, YAGNI.** Single responsibility, open/closed via dispatch, no
28+
duplication, the simplest thing that works, nothing speculative.
29+
→ [`types-traits-interfaces.md`](types-traits-interfaces.md)
30+
31+
6. **Structured errors.** Seven typed exceptions; sharp rule: single-argument value →
32+
`IncorrectArgument`; relation/state/composition → `PreconditionError`; unimplemented
33+
contract → `NotImplemented`; optional dependency → `ExtensionError`.
34+
→ [`exceptions.md`](exceptions.md)
35+
36+
7. **Type stability by default.** Parametric types, no `Any` in hot paths, function
37+
barriers, verified with `@inferred`.
38+
→ [`types-traits-interfaces.md`](types-traits-interfaces.md#type-stability)
39+
40+
8. **Everything is documented.** A docstring on every symbol, fixed templates,
41+
cross-references `@ref`/`@extref`, safe and reproducible examples.
42+
→ [`docstrings.md`](docstrings.md)
43+
44+
9. **Tests: module + callable function + everything qualified.** Each test file is a
45+
module with an entry function redefined in the outer scope; fakes at module
46+
top-level; categories unit / integration / contract / error.
47+
→ [`testing.md`](testing.md)
48+
49+
10. **Auto-generated API docs, public *and* private; guides separate.** Users reach
50+
internals via qualified paths, so both are documented.
51+
→ [`documentation.md`](documentation.md)
52+
53+
## Index
54+
55+
| File | Content |
56+
|---|---|
57+
| [`modules.md`](modules.md) | Submodule organization, imports/qualification, DAG, exports |
58+
| [`types-traits-interfaces.md`](types-traits-interfaces.md) | Types vs traits, interfaces/contracts, SOLID/DRY/YAGNI, type stability |
59+
| [`exceptions.md`](exceptions.md) | The 7 exceptions and the choice rule |
60+
| [`docstrings.md`](docstrings.md) | Docstring templates, cross-references, example safety |
61+
| [`testing.md`](testing.md) | Categories, fakes/stubs, **module + callable function template** |
62+
| [`documentation.md`](documentation.md) | API generation, guides, draft workflow |

0 commit comments

Comments
 (0)