AGENTS.md: keep only what is necessary — metadata-application principle first, rules not narratives, no hand-copied inventories; add a one-line CLAUDE.md pointer (maintainer 2026-09-09)

Maintainer direct instruction to the skills seat (session session_01MoTv7pn338AZ71owsp19gQ, GitHub os-justin), given in that PM session's chat on 2026-09-09 at 13:3xZ and 13:4xZ, verbatim, untranslated:

「看一下 hotcrm 的agents.md 写的太乱了。只留下必要的。包括同时同时审核 hotcrm 的skills 任务，合并派发处理。」

「首先要明确 hotcrm 是元数据应用，平台功能应该在 objectstack中开发。其次 claude.md 是不是直接让他阅读 agents.md 即可，没必要维护两套。所有仓库都有类似的问题」

Program anchor: objectstack-ai/objectstack#17161. Filed and claimed by the skills seat under the direct instruction; the repo:hotcrm seat's R58 close (5602546839, 13:21Z) reads 「AGENTS.md is FREE. Serial queue: #1745 → #1620 → #1618」 — that queue is consumed by this fold.

Deliverable — one rewrite of `AGENTS.md` (651 lines / 40 KB on `965933b`) down to what is necessary, plus a one-line `CLAUDE.md`

First principle first, verbatim-anchored. The file opens with the maintainer's sentence — HotCRM is a metadata application; platform capability is developed in objectstack — and the existing 🚫 Scope rules 1–4 become that opening chapter. Nothing in the file may contradict it.
Rules, not narratives. Each kept rule is one to three lines with its failure mode. Measurement stories, superseded-claim histories (「this file used to say…」, per-method measurement tables), origin anecdotes and precedent rosters leave the file; the cards and ADRs they cite are the archive and a rule may keep one short ref.
No hand-copied inventories — documentation-discipline rule 5 applies to this file too: the File Suffix Protocol's 12-suffix roster (AGENTS.md File Suffix Protocol is an inventory that drifted both ways: 4 of its 12 declared suffixes have zero instances in src/, and 8 suffixes the app really authors are absent from it #1745, drifted both ways), rule 5's own drift count and ledger (AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620), the chart-type list; point at src/{type}/ and the referenced cards instead.
Rule 6 stated at its real width (AGENTS.md rule 6 says "UI nouns take the zh-CN pack wording", but a pack-carried noun that is not a list view must stay English — and only an ablation reveals it #1618): list view names take the zh-CN pack wording; other pack-carried nouns keep their English spelling; the ablation is the discriminator.
Platform Upgrades keeps its steps compact and gains step 5 in the shape AGENTS.md → Platform Upgrades has no step for re-scoping the claims that name the old pin — which is why #1460, #1467 and #1676 are the same card three times #1681's thread settled (version-agnostic, cross-line, candidates not answers, honest about what a grep cannot see, identifiers and labels alike) in at most two lines.
The two briefs still teaching *.workflow.ts are corrected (.github/instructions/automation.md §1 and .github/tasks/autonomous_feature_dev.md:17 still teach a *.workflow.ts metadata type no installed package defines — #852's class, two surviving sites #1818): .github/instructions/automation.md §1 and .github/tasks/autonomous_feature_dev.md:17.
A root CLAUDE.md that is a pointer to AGENTS.md and nothing else, modelled on .github/copilot-instructions.md (11 lines).

Budget: AGENTS.md at most 250 lines after (a cut of at least 60%); every kept line names its reader; the PR's 维护者速读 lists every removed section as either 「rule kept at …」 or 「narrative, dropped」. ⛔ Not in this card: .github/tasks/new-package.md (#1819, decision box — the maintainer answers it); the other .github/instructions/*.md beyond #1818's sites (their overlap with AGENTS.md is reported, not edited); docs/**, content/**.

Governed (AGENTS.md, CLAUDE.md, .github/instructions/**; .github/tasks/** treated as governed conservatively) ⇒ draft PR, human merge, skip-changeset. Fold: chain head of #1745 · #1620 · #1618 · #1818 · #1681 on the instruction 「合并派发处理」 — all land in the one rewrite of one file plus #1818's two sites.

Generated by Claude Code

Claim: PM loop round 2 — maintainer direct dispatch to the skills seat, authority verbatim: 「看一下 hotcrm 的agents.md 写的太乱了。只留下必要的。包括同时同时审核 hotcrm 的skills 任务，合并派发处理。」 and 「首先要明确 hotcrm 是元数据应用，平台功能应该在 objectstack中开发。其次 claude.md 是不是直接让他阅读 agents.md 即可，没必要维护两套。所有仓库都有类似的问题」. Chain head of the fold #1823 · #1745 · #1620 · #1618 · #1818 · #1681: one rewrite of AGENTS.md to what is necessary (metadata-application principle first; rules not narratives; no hand-copied inventories; rule 6 at its real width; Platform Upgrades step 5 in its settled shape), the two *.workflow.ts briefs corrected, and a one-line CLAUDE.md pointer.
Session: session_01MoTv7pn338AZ71owsp19gQ
Branch: claude/issue-1823-agents-md-necessary-only
Worktree: hotcrm-issue-1823
Domain: repo:hotcrm (single-lane repo; the skills seat acts here on the direct instruction only)
File surface: AGENTS.md (whole-file rewrite) + new CLAUDE.md (pointer only) + .github/instructions/automation.md §1 and .github/tasks/autonomous_feature_dev.md:17 (the *.workflow.ts sites only); ⛔ not .github/tasks/new-package.md (#1819, decision box), ⛔ no src/**, docs/**, content/** (stop on breach; explain in the report)
Container & model: L (a 651-line instruction file rewritten to ≤250 lines + five folded cards + a new CLAUDE.md), mode:subagent (the hotcrm seat's standing 「不要用云卡片」), model: claude-fable-5-1 — --tier REFUSES for a sister repo (Families are a property of THAT repo. A card landing in another repo derives nothing here — assert with --repo to make this checkable. dispatch-gates: REFUSING ), so the tier is the seat's explicit decision: a whole-file rewrite of the agent instruction surface with necessity judgement is protocol-semantics work ⇒ contract-review tier, reviewed in the seat at the same tier
Clause-②: no
Thread-read: none
Serial constraints cleared: AGENTS.md free per the repo:hotcrm seat's R58 close (5602546839, 13:21Z: 「AGENTS.md is FREE. Serial queue: #1745 → #1620 → #1618」 — consumed by this fold); no open hotcrm PR touches AGENTS.md, CLAUDE.md, .github/instructions/** or .github/tasks/** (6 open PRs' file lists read 2026-09-09T13:51Z); newest AGENTS.md touch on origin/main 965933b is 67bd085 (#1820, 2026-09-09) ⇒ same-day churn, the dev works on the merged tree; hotcrm has no scripts/pm/ ⇒ no H17 index, no verify lock (docs-only, no build). Fold gates: the fold is ordered by the instruction 「合并派发处理」; every member lands in the one rewrite (or, for #1818, in the two sites named); each member keeps its own acceptance line in the PR body; excluded: #1819 (decision box, ⛔ gate ③) and #1822 (a translation-surface producer question, not an instruction-file edit).

Generated by Claude Code

os-dev-report

{
  "issue": 1823,
  "status": "done",
  "branch": "claude/issue-1823-agents-md-necessary-only",
  "pr": "https://github.com/objectstack-ai/hotcrm/pull/1830",
  "premise_still_valid": true,
  "summary": "One fold of six cards landed as draft PR #1830 (governed; skip-changeset applied and read back). AGENTS.md rewritten top-down from the necessity test, 651 -> 248 lines (61% cut): the maintainer's two rulings open the file verbatim with Scope rules 1-4 as the first chapter; every kept rule is one to three lines with its failure mode; measurement transcripts, superseded-claim histories, origin anecdotes, Supersedes trailers and precedent rosters left; the 12-suffix roster (#1745), rule 5's drift tally and ledger (#1620), the chart-type list and the crm_ roster history left; rule 6 states its real width (#1618); Platform Upgrades gains step 5 in #1681's settled shape in two source lines. New root CLAUDE.md is a 6-line pointer to AGENTS.md and nothing else. #1818's two *.workflow.ts sites corrected in their own commit 0f446c1, mirroring AGENTS.md wording; nothing else in those files moved. #1620's premise re-checked: PR #1809 moved the bullet to AGENTS.md:412-418, substance intact. #1681's absorbed half (b) (#1688, already closed) resolved by removal of the (17.2.0) pin sentence. Assignee was pre-set by the PM dispatch; never written by me.",
  "tests": "All at 0f446c1, docs-only diff. pnpm hygiene: exit 0, 'source hygiene clean' (byte scan reads AGENTS.md via ROOT_TEXT_FILES). pnpm validate: exit 0, 'Validation passed', 'Data: 18 Objects 331 Fields', 'Runtime: 0 plugins' (unchanged). Targeted vitest under the shared verify lock (OS_VERIFY_LOCK_SLOT=hotcrm-1823) on the five suites that read or cite AGENTS.md (docs-zh-hant-justification, docs-src-tree-paths, docs-role-hierarchy, docs-declared-versions, docs-object-coverage): 'Test Files 5 passed (5)', 'Tests 80 passed (80)', 'os-verify-lock: VERDICT command-exit 0'. First run was 1 red: my wording 'subordinate to this one' tripped docs-role-hierarchy's vocabulary guard; reworded before commit, rerun green. Control-byte self-scan of the four changed files: no hits (grep exit 1). #1818 probes re-measured before editing: WorkflowRuleSchema under node_modules/@objectstack = 0 (control FlowSchema in spec/dist = 34); *.workflow.ts under src = 0 (control *.flow.ts = 23). No ablation applies (no guard or code changed). NOT MEASURED: link-check (markdown-link-check not installed in this container; the workflow's action is not runnable locally) -> CI on the PR; pnpm verify in full not run -> declared narrowing: typecheck/lint/build/full test read src/ and test/, untouched by this diff; the three AGENTS.md-parsing suites plus two citing suites ran.",
  "mcp_calls": "0 - every GitHub read and write went through the repo-scoped REST channel (probe: GET issues/1823/comments HTTP 200, rate limit 15000/h)",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #1832: .github/instructions/security.md (*.role.ts / *.permission.ts / *.rls.ts, 0 instances each; unprefixed object), metadata.md section 3 (validation: singular with formula: -> ObjectSchema.create rejects 'unknown key(s) - validation'; control validations[] accepted), ui.md (default-export view/action literals, unprefixed objects) and automation.md section 3 (*.trigger.ts, 0 instances, TriggerSchema exists in spec - a question) still teach forms the app authors nowhere - #1818's class; dedup read declared with its gap (REST listing pages 2-3 empty twice; control hit #1818 found)",
    "filed as #1833 (Blocked-by: #1830): CLAUDE.md is a new root text file outside scripts/lib/source-hygiene-surface.mjs ROOT_TEXT_FILES, so the hygiene byte scan does not read it; the list's own comment says a new first-class root file must be added there; one-line fix, outside this fold's declared surface",
    "noted, not filed (承接者: whoever takes #1819 or #1832): src/objects/index.ts header comment still says '*.state.ts state machines are auto-associated by naming convention' - 0 such files exist",
    "noted, not filed (承接者: none - repo-wide pagination behaviour, already recorded in objectstack's rest-channel reference): REST issues listing returned 0 rows on pages 2-3 while pages 1, 4, 5 returned 100 each, on two attempts"
  ],
  "gates": {
    "pnpm_hygiene": "exit 0 at 0f446c1 - source hygiene clean",
    "pnpm_validate": "exit 0 at 0f446c1 - Validation passed; 18 Objects 331 Fields; Runtime 0 plugins (unchanged)",
    "vitest_targeted_under_lock": "5 files / 80 tests passed at 0f446c1 - VERDICT command-exit 0 (docs-zh-hant-justification, docs-src-tree-paths, docs-role-hierarchy, docs-declared-versions, docs-object-coverage)",
    "control_byte_scan": "no hits in AGENTS.md, CLAUDE.md, automation.md, autonomous_feature_dev.md",
    "link_check": "MEASURED by CI at 0f446c1: link-check completed, conclusion success (not runnable locally - tool absent)",
    "pnpm_verify_full": "not run - declared narrowing (src/ and test/ untouched)",
    "ci": "at report time (0f446c1): CodeQL success; Analyze Code (javascript) success; Playwright success; Label Pull Request success; link-check success; Check Changeset skipped under skip-changeset (an earlier pre-label run of the same check shows failure - superseded by the labelled re-run); Build and Test (22.x) in_progress"
  },
  "line_budget": {
    "AGENTS.md": {
      "before": 651,
      "after": 248,
      "budget": 250,
      "cut_percent": 61
    },
    "CLAUDE.md": {
      "before": 0,
      "after": 6
    },
    ".github/instructions/automation.md": {
      "before": 64,
      "after": 46
    },
    ".github/tasks/autonomous_feature_dev.md": {
      "before": 23,
      "after": 23,
      "lines_rewritten": 1
    }
  },
  "deviations": [
    "#1620: the repo:hotcrm seat's grading (5555833480) ruled the rule-5 ledger be kept and extended; this fold's ruling 3 (drop the count and the ledger, keep one ref) was executed as the later maintainer-backed instruction; stated on the PR's #1620 acceptance line for the maintainer",
    "narrowing declared: pnpm verify not run in full; link-check NOT MEASURED locally",
    "the platform relocated the PR body's '---' + '_Generated by ...' block to the tail after the harness attribution lines; the block survived whole (read back); no re-paste",
    "dedup read carries a declared gap (REST listing pages 2-3 empty on two attempts; 300 of the most recent rows read, control hit found)",
    "skip-changeset label used per ruling C; precedent PRs #1820 / #1798 used an empty-frontmatter changeset, which the workflow treats as equivalent - noted on the PR",
    "worktree was created with the PM's exact command (tracking origin/main, no --no-track); push -u then set upstream to the issue branch - no effect on the diff",
    ".github/tasks/** treated as governed per ruling C; #1818's two-file change is its own commit 0f446c1"
  ],
  "files_changed": [
    "AGENTS.md (rewritten, 651 -> 248 lines)",
    "CLAUDE.md (new, 6 lines, pointer only)",
    ".github/instructions/automation.md (section 1 replaced, 64 -> 46 lines)",
    ".github/tasks/autonomous_feature_dev.md (line 17 rewritten)"
  ]
}

Generated by Claude Code

ACCEPT — fold #1823 · #1745 · #1620 · #1618 · #1818 · #1681 (skills seat on the maintainer's direct dispatch, session `session_01MoTv7pn338AZ71owsp19gQ`, review taken 14:27–14:35Z at `claude-fable-5-1`, comment posted 2026-09-09T14:30Z)

PR #1830 (Fixes ×6, head 0f446c1 on base 965933b, two commits: the rewrite 9da6bbc and #1818's two sites 0f446c1), draft, targets main, four files (+182/−597): AGENTS.md 651 → 248 lines, new CLAUDE.md (6 lines, pointer only), .github/instructions/automation.md §1 (64 → 46), .github/tasks/autonomous_feature_dev.md :17. Verified against GitHub and the fetched head in this seat's own worktree, not the report (5603513xxx-series on this card):

Path face: governed per this repo's own AGENTS.md 「How a green PR lands」 list (AGENTS.md, CLAUDE.md, .github/instructions/**; .github/tasks/** treated as governed) ⇒ draft at the human terminal; this seat does not flip, queue, arm or approve. git merge-tree --write-tree origin/main × head: clean. Control-byte scan of the four files: clean.
The new AGENTS.md read in full at tier. Ruling 1 holds: both maintainer sentences open the file verbatim and Scope rules 1–4 are the first chapter, with 「merged is not available in the pin」 folded into rule 2. Ruling 2 holds: every kept rule is one to three lines with its failure mode; the where/filter measurement story, the bogusUnknownKey transcript, the rc.1/rc.2 log block, the origin anecdote, every 「Supersedes」 trailer and every precedent roster are gone, each rule keeping at most one ref. Ruling 3 holds: no suffix roster (AGENTS.md File Suffix Protocol is an inventory that drifted both ways: 4 of its 12 declared suffixes have zero instances in src/, and 8 suffixes the app really authors are absent from it #1745), no drift count or ledger in rule 5 (AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 — 「measured it drifting repeatedly … This rule binds this file too」), no chart-type list, no crm_ roster history; the directory tree stays because test/docs-src-tree-paths.test.ts parses it — a load-bearing line, kept and said. Ruling 4 holds: rule 6 now separates list view names (pack wording) from every other pack-carried noun (English), names the guard's ablation as the discriminator and states that measures are unguarded (AGENTS.md rule 6 says "UI nouns take the zh-CN pack wording", but a pack-carried noun that is not a list view must stay English — and only an ablation reveals it #1618). Ruling 5 holds: Platform Upgrades step 5 in two source lines carries all five settled requirements (AGENTS.md → Platform Upgrades has no step for re-scoping the claims that name the old pin — which is why #1460, #1467 and #1676 are the same card three times #1681). Ruling 6 holds: the two briefs teach no *.workflow.ts — automation.md §1 is now the prohibition with the three real destinations and the crm_ prefix, autonomous_feature_dev.md:17 names .flow.ts (residue grep over .github/instructions, .github/tasks and AGENTS.md: only the new prohibition heading matches). Ruling 7 holds: CLAUDE.md is a pointer and nothing else. .github/tasks/new-package.md untouched (.github/tasks/new-package.md still prescribes the retired packages/ scaffold — #1518's class, the site that card did not reach #1819 stays the maintainer's).
Budget: 248 ≤ 250 (61% cut). The PR body's removed-sections table lists every old section as 「rule kept at …」 or 「narrative, dropped」 — read against the old file by this seat; no rule in the old file is missing from the new one (the Autonomous Iteration phases and the Development Workflow list were procedure duplicates of the suffix and Tech Stack rules; Tone was not a rule).
Gates from the report, spot-checked: pnpm hygiene clean, pnpm validate unchanged (18 objects / 331 fields / 0 plugins), the five AGENTS.md-reading test suites 80/80 under the shared verify lock (one wording tripped docs-role-hierarchy's vocabulary guard and was reworded before commit — the right order), link-check measured by CI. CI on 0f446c1 at 14:28Z: 8 distinct checks, 7 success / 1 skipped (Check Changeset under skip-changeset) / 0 failed, all complete; mergeable_state: clean.
Closing keywords: six Fixes lines, one per member, and no other keyword-number pair. skip-changeset read back (the repo's own exception; precedent PRs used an empty-frontmatter changeset, which the workflow treats the same — noted on the PR). Two footers on the body — the platform relocated the block; left as-is.
Deviation accepted and put to the maintainer: the repo:hotcrm seat's grading of AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 (5555833480) had ruled the rule-5 ledger be kept and extended; the maintainer's later instruction 「只留下必要的」 and this fold's ruling 3 supersede it — precedence 维护者裁决 > seat grading — and the cards remain the archive. Stated on the PR's AGENTS.md:348 counts the drift its own rule forbids as "four times", and the ledger at :353 has not been incremented since #1620 acceptance line.
## Acceptance notes and out_of_scope_findings read: two cards filed by the dev in this repo — .github/instructions/security.md, metadata.md §3 and ui.md still teach forms this app authors nowhere or the spec rejects (*.role.ts / *.permission.ts / *.rls.ts, validation: singular, default-export views) — #1818's class, the sites that fold did not reach #1832 (four more .github/instructions/*.md sections teaching forms the app authors nowhere; .github/instructions/automation.md §1 and .github/tasks/autonomous_feature_dev.md:17 still teach a *.workflow.ts metadata type no installed package defines — #852's class, two surviving sites #1818's class) and CLAUDE.md (new root instruction file, PR #1830) is outside ROOT_TEXT_FILES — the hygiene byte scan does not read it #1833 (CLAUDE.md is a new root text file outside source-hygiene-surface.mjs's ROOT_TEXT_FILES; one-line fix, Blocked-by: #1830) — both exist (read back), both unlabelled for the repo:hotcrm seat's first-touch grading (single-lane repo self-serves; this seat acts here on the direct instruction only). Two noted-not-filed items (a stale src/objects/index.ts header comment; the REST listing's empty middle pages) carry their 承接者.

Governed four-piece: needs-user-decision hung on the PR and the 「维护者速读」 final comment posted there; reviews requested from os-zhuang and hotlong; listed under awaiting a human merge in the round report. All six cards stay pm:dispatched with this seat as assignee until the merge lands (landing records then).

Generated by Claude Code

Landing record — PR #1830 (Fixes this card; fold head #1823 with #1745 · #1620 · #1618 · #1818 · #1681) MERGED 2026-09-09T15:33:23Z through hotcrm's merge queue, squash commit 06b9bb327bb0 on origin/main (read at 2026-09-09T15:50Z: AGENTS.md 248 lines, CLAUDE.md is the 6-line pointer). GOVERNED (AGENTS.md, CLAUDE.md, .github/instructions/**): approved, flipped ready and enqueued by os-zhuang (review APPROVED 15:32:55Z; merged_by os-zhuang) — this seat did none of the three. In-seat review ACCEPT 5603569687 on #1823; 速读 5603571614 on the PR. Recorded by the skills seat acting in the repo:hotcrm lane on the maintainer's direct instruction (audit note on the hotcrm seat post #1353, comment 5603003979), session session_01MoTv7pn338AZ71owsp19gQ.

Same stroke: pm:dispatched removed and the assignee (os-justin, this seat) cleared on this auto-closed card; documentation stays. Left untouched by design and still open: hotcrm#1819 (.github/tasks/new-package.md) — with this PR merged, its answer lands as a new card, not a rider.

Generated by Claude Code

Navigation Menu

Repository navigation

AGENTS.md: keep only what is necessary — metadata-application principle first, rules not narratives, no hand-copied inventories; add a one-line CLAUDE.md pointer (maintainer 2026-09-09) #1823

Deliverable — one rewrite of `AGENTS.md` (651 lines / 40 KB on `965933b`) down to what is necessary, plus a one-line `CLAUDE.md`

ACCEPT — fold #1823 · #1745 · #1620 · #1618 · #1818 · #1681 (skills seat on the maintainer's direct dispatch, session `session_01MoTv7pn338AZ71owsp19gQ`, review taken 14:27–14:35Z at `claude-fable-5-1`, comment posted 2026-09-09T14:30Z)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

AGENTS.md: keep only what is necessary — metadata-application principle first, rules not narratives, no hand-copied inventories; add a one-line CLAUDE.md pointer (maintainer 2026-09-09) #1823

Description

Deliverable — one rewrite of AGENTS.md (651 lines / 40 KB on 965933b) down to what is necessary, plus a one-line CLAUDE.md

Activity

os-justin commented on Sep 9, 2026

os-justin commented on Sep 9, 2026

os-justin commented on Sep 9, 2026

ACCEPT — fold #1823 · #1745 · #1620 · #1618 · #1818 · #1681 (skills seat on the maintainer's direct dispatch, session session_01MoTv7pn338AZ71owsp19gQ, review taken 14:27–14:35Z at claude-fable-5-1, comment posted 2026-09-09T14:30Z)

os-justin commented on Sep 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Deliverable — one rewrite of `AGENTS.md` (651 lines / 40 KB on `965933b`) down to what is necessary, plus a one-line `CLAUDE.md`

ACCEPT — fold #1823 · #1745 · #1620 · #1618 · #1818 · #1681 (skills seat on the maintainer's direct dispatch, session `session_01MoTv7pn338AZ71owsp19gQ`, review taken 14:27–14:35Z at `claude-fable-5-1`, comment posted 2026-09-09T14:30Z)