Skip to content

docs(claude-md): split core-team context into .claude submodule via @import#1470

Merged
dolho merged 2 commits into
devfrom
docs/claude-md-team-context-split
Jul 8, 2026
Merged

docs(claude-md): split core-team context into .claude submodule via @import#1470
dolho merged 2 commits into
devfrom
docs/claude-md-team-context-split

Conversation

@vybe

@vybe vybe commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Summary

CLAUDE.md is the public contributor working agreement, but it carried internal dev-factory context that confuses OSS clones, which don't mount the private .claude submodule (update = none since #1443). This PR moves that content into .claude/TEAM_CONTEXT.md (trinity-dev bcc78be) and @-imports it from CLAUDE.md:

  • Core-team clones: the import auto-loads the internal context exactly as before.
  • OSS clones: the import is silently skipped; everything an external contributor needs stays in the public file.

Moved to .claude/TEAM_CONTEXT.md

  • Current Product Focus (theme tiebreaker rules)
  • Remote Agent (/trinity:sync)
  • Two-tracker routing detail + /roadmap union / --repo trinity-enterprise picking rules
  • Methodology skills table (verification, systematic-debugging, tdd, code-review)

Kept public (reworded where needed)

  • A one-line public-safe summary of the two-tracker model in the SDLC section
  • The four methodology non-negotiables, phrased without submodule dependency
  • All security rules, invariants, dual-track migration rule, submodule setup + external-contributor guidance

The submodule commit also repoints the skill/doc references that parse CLAUDE.md → "Current Product Focus" (/roadmap, /roadmap-plan, /sprint, /read-docs, DEVELOPMENT_WORKFLOW.md, ROADMAP.md) to the new file. Historical docs (GITHUB_ISSUES_MIGRATION.md, PROJECT_BOARD_DEPRECATION_2026-05.md) intentionally untouched as point-in-time records.

Verification

  • Empirical test of the @import mechanism in a scratch project: missing file → silently skipped, no error; existing file → content loads (both directions confirmed headlessly).
  • End-to-end in this repo: a headless session correctly answered theme-reliability for the primary focus — a fact that now exists only in the imported TEAM_CONTEXT.md.
  • Data-loss audit of the full diff: every removed line is either verbatim in TEAM_CONTEXT.md or intentionally retained publicly in generic form.

Note: the .claude pointer bump also picks up 7 already-pushed docs/skill commits that predate this change (301ecb1..caf528b).

🤖 Generated with Claude Code

…import

CLAUDE.md is the public contributor working agreement, but it carried
internal dev-factory context (product focus, tracker routing, remote
agent, methodology skill map) that confuses OSS clones which don't mount
the private .claude submodule. That content now lives in
.claude/TEAM_CONTEXT.md and is @-imported by CLAUDE.md: it auto-loads for
core-team clones and is silently skipped when the submodule is absent
(behavior verified empirically in both directions, plus end-to-end in
this repo).

- Move Current Product Focus, Remote Agent, two-tracker routing detail,
  /roadmap picking rules, and the methodology skills table to
  .claude/TEAM_CONTEXT.md (bumped here; skill references to
  "CLAUDE.md → Current Product Focus" repointed in the same submodule
  commit)
- Keep a public-safe summary of the two-tracker model and the four
  methodology non-negotiables in CLAUDE.md
- Fix the stale .claude/ entry in the project structure tree

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jul 6, 2026

Copy link
Copy Markdown

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

@dolho

dolho commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Review: ✅ Approve on content — ⚠️ rebase + submodule verification before merge

The @import split is the right pattern: core-team clones auto-load .claude/TEAM_CONTEXT.md, OSS clones (no submodule since #1443) silently skip it, and everything an external contributor needs stays in the public CLAUDE.md. The public-side rewordings (two-tracker summary, methodology non-negotiables) preserve the meaning without the submodule dependency. Data-loss audit in the PR body is the right diligence.

Blockers before merge:

  • Branch is CONFLICTING with dev — rebase needed (likely the .claude pointer + the Memory Files table both moved).
  • Submodule bump (301ecb1..bcc78be) — confirm bcc78bee is actually pushed to trinity-dev and that TEAM_CONTEXT.md exists at that commit, otherwise core-team clones get a dangling import. The bump also drags in 7 unrelated already-pushed docs/skill commits (noted in the PR) — fine, just flagging it's not a clean single-purpose pointer move.

@dolho

dolho commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Review (direct, per standing no-workflow preference). Docs/CLAUDE.md split with the internal context moved to .claude/TEAM_CONTEXT.md via @import; OSS clones skip it cleanly. Clean vs dev (no conflicts), CI green (16/16). Verified earlier that the .claude submodule bump (bcc78be) is on trinity-dev main with TEAM_CONTEXT.md present, so the import won't dangle. ✅ Mergeable.

@dolho
dolho merged commit c970d9e into dev Jul 8, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants