Skip to content

Commit 0083603

Browse files
Docs cleanup for repository onboarding guidance (#79)
## Summary - fix the broken Git Worktrees cross-link in Repository-Defaults`n- add concise copy-paste starters for AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md`n- restore a repo-local CONTRIBUTING.md so the guidance chain is self-contained ## Notes - kept the change limited to onboarding/docs coherence - aligned the new guidance with the existing pointer-only doc model --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent ece10f3 commit 0083603

2 files changed

Lines changed: 24 additions & 2 deletions

File tree

CONTRIBUTING.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Contributing to PSModule/docs
2+
3+
This repository is the source of truth for PSModule documentation.
4+
5+
## Before you change docs
6+
7+
- Read the relevant page in `src/docs/` first.
8+
- Keep changes small and scoped to one topic.
9+
- Prefer links to canonical docs over duplicating guidance.
10+
11+
## Working in this repository
12+
13+
- Use the current branch or worktree for the change.
14+
- Keep commit messages short and specific.
15+
- Open draft pull requests early for reviewable doc updates.
16+
17+
## Review expectations
18+
19+
- Make wording changes that improve clarity without widening scope.
20+
- Preserve the existing PSModule doc conventions and link patterns.
21+
- If a linked guide is missing, add it here in the repository instead of relying on inheritance.

src/docs/Modules/Repository-Defaults.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Local work should use the organization worktree convention:
5454
- `main/` tracks the default branch.
5555
- Feature worktrees use `<type>-<slug>` directories and `<type>/<slug>` branches.
5656

57-
For branch and worktree details, see [Git Worktrees](../../Ways-of-Working/Git-Worktrees.md).
57+
For branch and worktree details, see [Git Worktrees](https://github.com/MSXOrg/docs/blob/main/src/docs/Ways-of-Working/Git-Worktrees.md).
5858

5959
## Default repository layout
6060

@@ -134,7 +134,8 @@ Every repository must be usable by an agent that has never seen it before, witho
134134

135135
- `AGENTS.md`: the cross-tool entry point, read by the GitHub Copilot coding agent, VS Code, and other AGENTS.md-aware tools. It names what the repository is in a line or two and points to the canonical agent guidance in [`PSModule/docs`](https://github.com/PSModule/docs).
136136
- `CLAUDE.md`: a thin file that imports `AGENTS.md` with `@AGENTS.md` so Claude Code reads the same instructions. Claude-specific notes, if any, go below the import.
137-
- `.github/copilot-instructions.md`: repository instructions for VS Code and GitHub Copilot that point to the same documentation.
137+
138+
See [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule) for a concrete implementation example of `AGENTS.md` and `CLAUDE.md`.
138139

139140
These files are the agent equivalent of the README: pointers, not copies. Keep them short so the linked documentation stays the single source of truth. Like the other governance files, they live in the repository itself so it can stand on its own.
140141

0 commit comments

Comments
 (0)