Skip to content

Q4: roll out shared agent instructions (AGENTS.md + CLAUDE.md import) #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaldengusiak merged 2 commits into from
Oct 12, 2026
Merged

Q4: roll out shared agent instructions (AGENTS.md + CLAUDE.md import) #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
45f180a
docs: roll out shared agent instructions (AGENTS.md, CLAUDE.md import)
michaldengusiak Oct 12, 2026
875edf6
docs: record the agent instructions rollout evidence
michaldengusiak Oct 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 106 additions & 14 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,38 +19,74 @@ Do not rely on previous conversation memory.
Before making significant changes:

1. Read this `AGENTS.md`.
2. Read `PROJECT_PROGRESS.md`, and the PR record document and
PR description of any open PR you are continuing.
2. Inspect the headings in `PROJECT_PROGRESS.md`, then read the latest
dated Q4 closeout and the sections relevant to this task. Read the
record document and live description of any PR you are continuing.
3. Understand the relevant existing code, architecture, tests, and conventions.
4. Review the current Git branch and working tree.
4. Review the current Git branch and working tree; preserve existing local changes.
5. Continue from the documented current state.

Prefer small, safe, targeted changes consistent with existing conventions.
Avoid unrelated refactoring unless it is required for the task.

## Repository operations and context

- Validate fetch and push URLs before network operations; target only
`github.com/SAM-BIM/<repository>`. Use explicit SAM-BIM repository/API
targets; avoid automatic fork-parent discovery. Do not contact HoareLea
repositories or request their access/SAML authorization.
- Preserve historical attribution, legacy records and external integration
references; changes to integrations require a separate migration decision.
- Treat dated bootstrap/Q2/Q3 entries as historical evidence. Check Git and
live PR metadata before acting on old status/next-step text. Read earlier
evidence when the task depends on it; do not load whole histories by default.
- Section position is not a period marker: active-quarter closeouts may appear
beneath a historical heading. Scan all dated headings and classify each entry
by its date, PR and base branch, not by the heading it sits under.
- These instructions and `CLAUDE.md` belong on `sow/*` and their feature branches;
never promote internal agent files to `master`.

## Quarter transition (owner-approved release work)

Release, product promotion, quarter freeze and quarter bootstrap each need
explicit owner approval; none is implied by merging an ordinary PR.

- Promote approved Q4 product changes through a reviewed release PR. A normal
merge includes internal files: prepare and verify the promotion tree excludes
`AGENTS.md`, `PROJECT_PROGRESS.md`, `CLAUDE.md` and the internal continuity
records (`documentation/Agent-Continuity-*-Q4.md`).
Classify other documentation separately; retain product documentation
selected for release.
- Complete known-SHA Q4 closeouts before freezing `sow/2026-Q4`. The release-promotion
PR's closeout belongs on the outgoing `sow/2026-Q4`, never on `master`, although
`master` is that PR's base. Preserve the frozen branch as the quarter's record:
no commits, rebase, rename, archive or deletion.
- Create `sow/2027-Q1` from the owner-approved promoted product baseline. Carry
forward useful shared instructions and the Claude import onto Q1 only; update
the active/frozen quarter references and carry unresolved work with evidence.
- Initialize a concise Q1 progress record only as an explicitly authorized
quarter-bootstrap operation, referencing the frozen Q4 commit for history.
This does not widen the ordinary post-merge-only progress-closeout exception.
These steps describe future release work; they are not authorized by this file.

## Project continuity

`PROJECT_PROGRESS.md` is updated only after a PR has merged.
During implementation, keep status/evidence on the PR branch in the
PR record document and PR description. After merge, fetch the base
branch and add the closeout entry, including the merge SHA, as a
direct docs-only commit on the base branch. Do not modify unrelated
stream entries.
direct docs-only commit on the base branch (for a release-promotion
PR into `master`, on the outgoing `sow` branch instead). Do not modify
unrelated stream entries.

The order of work is:

code + tests + evidence → final PR CI → merge →
`PROJECT_PROGRESS.md` closeout commit on the base branch.

Never change `PROJECT_PROGRESS.md` on a PR branch.

The closeout is written only after the merge SHA is known, so it cannot be
part of the reviewed PR; putting it in the PR would force another review/CI
cycle merely for a progress-file update. Direct commits to `sow/2026-Q4`
are therefore allowed for this one case: the post-merge, docs-only
`PROJECT_PROGRESS.md` closeout. This exception does not cover code, tests,
workflows or any other file. All code changes still go through a feature
branch and a PR.
Never change `PROJECT_PROGRESS.md` on a PR branch. The sole direct-Q4
exception is its post-merge docs-only closeout with a known merge SHA
and `[skip ci]`; other changes require a feature branch and owner-reviewed PR.

Do not record trivial actions such as opening files,
searching the repository, or reading documentation.
Expand All @@ -70,6 +106,15 @@ the `PROJECT_PROGRESS.md` closeout entry must contain:
- unresolved issues, risks, or blockers;
- exact recommended next step.

Identify the PR, base branch and tested head SHA. Distinguish local results
from GitHub checks, including failures/skips, required dependency order and
remaining gaps. Give reproducible commands and committed evidence paths; label
machine-local evidence and prerequisites that must be copied or provisioned
elsewhere. Record the validated content SHA in the committed PR record. If a
record-only commit follows, keep that tested SHA and its commands in the record,
validate the final docs diff, and identify the final PR head/checks in the PR
description. The post-merge closeout records the immutable merge SHA.

When updating `PROJECT_PROGRESS.md`, preserve still-relevant information
from previous sessions. Remove or replace information only when it is
obsolete, resolved, or superseded.
Expand All @@ -83,3 +128,50 @@ switching computers, accounts, sessions, or AI agents.

Never assume conversation history, terminal history, generated files,
or uncommitted local changes will exist on another computer.

## Pull requests and merging

- Implementation, tests, workflows and ordinary documentation changes go
through focused feature branches and owner-reviewed PRs into `sow/2026-Q4`.
Continue an existing PR for the task rather than opening a duplicate.
- Merge only after owner/code-owner approval, required checks passing at the
final PR head, and each review finding resolved or explicitly accepted by
the owner.
- Permission for the direct post-merge closeout does not authorize source,
test, workflow or any other file change. A specific owner exception must be
recorded explicitly and kept narrowly scoped.

## Post-merge branch cleanup

Once the owner authorizes a PR merge, cleaning up that task's fully merged
feature branches is included; no separate cleanup approval is needed.

Before deleting a branch:

- verify the remote head SHA is the expected (approved) head;
- verify it is completely merged into the intended base on the remote;
- confirm no unmerged local or remote work remains on it;
- confirm no open PR uses it as head or base;
- exclude protected, default, quarterly (`sow/*`), shared and specifically
protected repository branches.

Delete an eligible remote task branch with a lease guard, for example
`git push origin --force-with-lease=refs/heads/<branch>:<expected-sha> :refs/heads/<branch>`,
then confirm the ref is gone. Return the clean checkout to the active base
and delete the local task branch only when it is fully merged and no worktree
uses it. Never delete or archive worktrees automatically. If any condition
fails, preserve the branch and report why. Never force deletion of unmerged work.

Dependency resolution: downstream CI may select a dependency branch by PR
branch name before falling back to `sow/2026-Q4`. Inspect that resolution. When
a merged task branch would shadow Q4, clean it up first, then rerun downstream
CI and verify in the logs that the intended merged dependency was selected.

This covers only the current task's branches. Older unrelated leftovers need
a separate inventory and authorization.

## Recommendations and handoffs

When recommending a task or writing a prompt or handover, state the model,
effort, new or existing session and Plan or Build mode, with a brief reason.
A recommendation does not mean any setting was changed automatically.
4 changes: 4 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
@AGENTS.md

Keep shared project instructions in AGENTS.md. Read task-specific progress
and PR evidence as directed there; do not import the full progress history.
68 changes: 68 additions & 0 deletions documentation/Agent-Continuity-Rollout-Q4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Agent instructions rollout — Q4 (2026-10-12)

Status: implemented on `docs/agent-instructions-rollout-q4`; owner review required. Not merged.
Kind: Rollout of the shared baseline.
Base: `sow/2026-Q4` at `c0dc4281d87991e2cfc39d7ab4acabe76207f483`.
PR: the live PR for this branch in `SAM-BIM/SAM_Systems` (its number is not committed here).
Tested content SHA: `45f180a73e3b7c4304cc80f34369fc65f27a0fa2` (changes only AGENTS.md, CLAUDE.md).
Final PR head and hosted check results: recorded in the live PR description. A record
cannot contain its own commit SHA, so this file is the only change after the tested SHA.
Baseline: SAM-BIM/SAM#191 (merge `02bbafb8`, closeout `46e96b72`) and SAM-BIM/SAM_OCCT#74
(merge `3d0a4725`, closeout `c825a40`).

## Scope

Documentation only. No product code, build, workflow, dependency pin or tool changed.
`PROJECT_PROGRESS.md` is not changed on this branch; its closeout follows merge.

## Changes

- `AGENTS.md`: moves from the 2026-10-06 bootstrap template to the SAM#191 / SAM_OCCT#74 baseline (task-specific progress reads, SAM-BIM-only operations, quarter transition, evidence rules) plus merge conditions, guarded post-merge branch cleanup and the model/effort handoff rule. The repository's own branch-context line is kept.
- `CLAUDE.md` (new): `@AGENTS.md` import, same convention as the pilots.

Shared rules added or confirmed in `AGENTS.md`: Git and committed records are authoritative; SAM-BIM-only
operations with validated URLs; heading-first, task-specific progress reads; feature branch + owner-reviewed PR
for everything except the post-merge `[skip ci]` progress closeout; tested-SHA, local-versus-hosted,
dependency-order and remaining-gap evidence; merge only after owner approval, final-head checks and resolved
findings; guarded post-merge cleanup of the task's branches (expected-SHA check, full-merge check, no open PR,
lease-guarded delete, no worktree deletion); frozen quarters; internal agent files stay off master promotions;
model/effort/session/mode on every recommendation.

## Preserved repository-specific rules

- No repository-specific rule existed beyond the shared template; the repository's own `master` base SHA in Branch context is kept.

## Validation

Local, documentation checks only (no product build or test was run, none applies):

```bash
base=c0dc4281d87991e2cfc39d7ab4acabe76207f483
tested=45f180a73e3b7c4304cc80f34369fc65f27a0fa2
final=$(git rev-parse HEAD) # must equal the final head in the PR description
for revision in "$tested" "$final"; do
git diff --check "$base" "$revision"; echo "check $revision exit=$?"
git diff --name-only "$base" "$revision"
git diff --quiet "$base" "$revision" -- PROJECT_PROGRESS.md; echo "progress $revision exit=$?"
done
git diff --name-only "$tested" "$final"
git show "$final":CLAUDE.md | grep -n '^@AGENTS.md'
```

Expected: every `exit=` is 0; the full-PR file lists contain only AGENTS.md, CLAUDE.md and this record
(at the tested SHA only AGENTS.md, CLAUDE.md); the tested-to-final list contains only this record; the import
line is found. PowerShell works with `git rev-parse HEAD` and `if ($LASTEXITCODE -ne 0)` checks.

Result at the tested SHA (2026-10-12, Windows, Git for Windows): `git diff --check` exit=0;
`PROJECT_PROGRESS.md` unchanged exit=0; changed files: AGENTS.md, CLAUDE.md; no CR, no BOM, final newline;
no unreplaced template tokens; `sow/2026-Q4` active, `sow/2026-Q3` frozen, no `sow/2026-Q2` reference.
The same checks at the final head and the hosted PR checks are reported in the PR description;
they are not asserted here. No agent-client token/behaviour benchmark was run for this rollout.

## Remaining decisions and next step

- Merge needs owner approval, passing final-head checks and resolved/accepted review findings. Code-owner review is required only for merges to `master` (owner decision recorded in the pilot closeouts).
- After merge: a docs-only `[skip ci]` closeout in `PROJECT_PROGRESS.md` on `sow/2026-Q4` with the merge SHA, then guarded cleanup of `docs/agent-instructions-rollout-q4` per `AGENTS.md`. Stale bootstrap wording already in `PROJECT_PROGRESS.md` is not edited by this PR; labelling it is a closeout matter that needs explicit owner authorization.
- Machine-local: the 29-repository rollout inventory, worktrees and cross-repository status table are in the
local parent `PROJECT_PROGRESS.md` checkpoint (not Git-tracked). The committed cross-repository table is in
SAM-BIM/SAM's `documentation/Agent-Continuity-Rollout-Q4.md` once that PR lists all rollout PRs.
Loading