diff --git a/docs/dev-practices/README.md b/docs/dev-practices/README.md index bc7209d..dc0bcb5 100644 --- a/docs/dev-practices/README.md +++ b/docs/dev-practices/README.md @@ -1,32 +1,132 @@ +--- +created: 2026-05-11 +last_modified: 2026-05-11 +revisions: 2 +doc_type: [REFERENCE, GUIDE] +lifecycle: active +owner: rmrich5 +title: "dev-practices — working in the m-dev-tools org" +--- + # dev-practices — working in the m-dev-tools org How to *develop* in this org without fighting the tooling. Where the org-wide standards (AI-discoverability, docs-discoverability, CONTRIBUTING, layout conventions) tell you **what** the result has to look like, this section captures **how** to actually get day-to-day -work done across 12+ interconnected sibling repos without git -clashes, leaked edits, or wasted cycles. +work done across 12+ interconnected sibling repos. + +If you remember nothing else, remember the first rule. It catches the +great majority of failure modes that exist; the rest exist for the +residue. + +--- + +## The five rules + +### Rule 1 — One session ↔ one repo + +**Don't run two Claude sessions on the same repo at the same time.** + +With 12+ repos in the org, parallel work means parallel *repos* — not +parallel *sessions on one repo*. Two sessions on `m-cli` will clobber +each other on `main`, on the working tree, on each other's branch +state. Two sessions on `m-cli` + `m-stdlib` will not collide at all — +separate working trees come for free. + +This rule alone catches ~90% of "git problems" people hit working in +this org. Adopt it first; only add the rest if you're already +following this one. + +### Rule 2 — Feature branches, not `main` + +**Start every session on a feature branch.** + +```bash +cd ~/m-dev-tools/m-cli +git switch -c +``` + +If Rule 1 ever slips, at least each session's commits land on its own +branch instead of stacking on `main`. Direct-to-`main` is only safe +when you're certain you're the only actor in this repo today. + +### Rule 3 — Cross-repo features go sequentially, leaves first + +**Two repos, two sessions, two PRs — in dependency order.** + +When `m-cli` needs a new `m-stdlib` primitive: -These are not policies — those live at the repo root (`CONTRIBUTING.md`, -`profile/`, the schemas). These are *practices* a maintainer or agent -follows when sitting down to do the work. +1. Session A in `m-stdlib/` — TDD the primitive, commit, push, tag + if release-bound. +2. Session B in `m-cli/` — bump the m-stdlib reference, implement the + consumer, commit, push. -## Index +Never let one session edit both repos, even when the changes feel +"one feature". + +### Rule 4 — `.github/` is read-only during feature work + +**Don't edit `.github/` from a session whose purpose is implementing +in `m-cli` / `m-stdlib` / etc.** + +`.github/` holds org policy: CONTRIBUTING, schemas, the +AI-discoverability framework, the docs-discoverability spec, layout +conventions. Implementation work in functional repos consumes those — +it shouldn't be modifying them. Change `.github/` in a session whose +explicit purpose is `.github/` work, where you can also bump +`profile/repo.meta.json` and regenerate the catalog intentionally. + +### Rule 5 — Glance at `git status` before saying "commit" + +**Three seconds. If you see files you don't recognize, stop.** + +The agent already runs `git status` before staging. Read what it shows +you. Unfamiliar files (especially from another repo, or on a branch +you didn't expect to be on) are the warning sign — investigate before +committing. This is the backstop for the residual cases where the +rules above slipped. + +--- + +## Going deeper + +The rules above are the practice. The strategic doc carries the +analysis behind them — three-tier model, what's shared at the +filesystem level (workspace pytest cache, scheduler lock, memory dir), +guardrails (workspace-root tripwire, `make scope-check`), diagnostic +recipes for specific failure modes ("Why is sibling-repo X dirty?", +"Two sessions clobbered each other's commits in the same repo", etc.), +and escape hatches like `git worktree` for the rare case you truly +need concurrent sessions on the same repo. - **[`parallel-multi-repo-git-hygiene.md`](parallel-multi-repo-git-hygiene.md)** - — Why parallel Claude sessions across `m-cli`, `m-stdlib`, - `m-test-engine`, … cause "git problems," and the workflow that - eliminates them. Read this first if you run more than one agent - session at once. + — full rules with rationale, three-tier model, filesystem + shared-state inventory, guardrails, diagnostic recipes. + +--- + +## Adding a practice + +A new doc lives in this folder when: + +1. It's a *workflow* concern (how to work), not a content concern + (what the work should produce). +2. It applies across more than one repo in the org. +3. It's stable enough to document — not a one-off experiment. + +New docs follow the +[docs-discoverability spec](../docs-discoverability/docs-discoverability-spec.md) +filename and frontmatter conventions. -## Audience +--- -Anyone (human or agent) doing implementation work across multiple repos -in the m-dev-tools org. If you're only changing one repo and only ever -have one session open, you can probably skip this section — the -per-repo `CLAUDE.md` and the org `CONTRIBUTING.md` cover the basics. +## Audience and relationship to other doc sections -## Relationship to other doc sections +If you only ever change one repo at a time and run one session, this +section is reassurance reading — your default workflow already +respects the rules. If you regularly run more than one session, read +at least the five rules above. | Section | What it answers | |---|---|