From add061e1d45d5a395f2fe00a3cede2de2917ddd5 Mon Sep 17 00:00:00 2001 From: show <10173746+showxu@users.noreply.github.com> Date: Mon, 5 Oct 2026 05:19:01 +0800 Subject: [PATCH] Adopt the canonical agent guide and code owners The agent guide now carries the shared first-principles and canonical artifact sections, with routes and authority for the profile, the shared conventions, the design system and the community files. The repository's existing guardrails are unchanged. MAINTENANCE.md states that every agent guide carries those shared sections, and CODEOWNERS assigns review ownership like the other repositories. --- .github/CODEOWNERS | 1 + AGENTS.md | 157 +++++++++++++++++++++++++++++++++++++++++---- MAINTENANCE.md | 3 +- 3 files changed, 149 insertions(+), 12 deletions(-) create mode 100644 .github/CODEOWNERS diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..d63d464 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @showxu diff --git a/AGENTS.md b/AGENTS.md index 0903a49..07c27c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,154 @@ -# Agent guide +# Organization Agent Guide -This repository owns Computer MCP's organization profile, the cross-repository -conventions in `MAINTENANCE.md`, the default community files, and the visual -identity: `DESIGN.md`, the renderer and exports in `Brand/`, and the reusable -brand check. -Product meaning stays with the main repository's ProductIdentity; text rendered -into images must match it. Preserve repository visibility and integration -ownership. +Read `README.md` first for repository purpose and entry points. +Apply this guide before making changes. +## First-Principles Work + +Before changing code, docs, schemas, scripts, templates, examples, governance, +or automation, reduce the task to observable behavior, root cause, invariant, +owner, data flow, and validation. + +- Do not silently choose among plausible interpretations. State assumptions, + surface conflicts, and ask when the decision materially changes the result. +- Deliver the complete requested behavior with bounded design. Do not stop at a + toy result when production behavior is requested, and do not add abstraction, + configurability, workflow machinery, or future-facing features unless the + request, source evidence, or owning invariant requires them. +- Change the owning layer, not the nearest convenient file. +- Keep changes traceable to the request, source evidence, or owning invariant. +- Do not clean up, reformat, rename, or refactor unrelated nearby material + unless it is required by the request or owning invariant. +- Use the strongest feasible validation for the result. If validation is + skipped, say what was skipped and why. + +Use this check: + +1. What behavior is wrong, missing, or at risk? +2. What root cause explains it? +3. What invariant must hold? +4. Which artifact, layer, or workflow owns it? +5. What data or decision flows into that owner? +6. What remains variable, configurable, or case-local? +7. What evidence proves the result beyond one literal case? + +## Canonical Artifacts + +- Treat conversation, review feedback, plans, and intermediate attempts as + editing input. Recompute the complete accepted result before finalizing. +- Active artifacts depend only on that result and their repository role, not + on the editing path. Apply this to code, symbols, files, wrappers, branches, + configuration, schemas, defaults, generated sources, scripts, templates, + automation, comments, DocC, diagrams, tests, fixtures, snapshots, examples, + and normative docs. +- If an intermediate result is `A + B` and the accepted result is `A`, express + `A` directly. Remove `B` and its residual surface rather than retaining names + such as `AOnly` or `AWithoutB`, or prose such as "B was removed." +- Normalize by semantic identity and artifact role, not by token. A rejected + current capability does not invalidate a distinct historical fact, + migration, ownership record, or safety boundary that uses the same term. +- Keep a negative constraint only when excluding `B` is independently required + by a current compatibility, safety, or ownership invariant. +- A disabled B flag, skipped B test, dead B branch, retained B fixture, or + "do not add B" rule is residue when it exists only because B was attempted; + disabled state alone is not an invariant. +- Keep change history only in commits, pull requests, changelogs, release + records, migrations, archives, or accepted decision records with durable + value. Do not create a history artifact merely to preserve a correction. +- Preserve role-owned facts unless separate evidence changes them; do not + rewrite history or ownership merely to make a rejected term disappear. +- Leave an already-correct history, migration, provenance, ownership, or safety + artifact unchanged when the task does not change its facts. Do not polish or + restate it merely because it is relevant to the current edit. +- Comments explain non-obvious current semantics and invariants, not the + sequence of edits. +- Before handoff, verify that a new agent with no editing conversation can + derive the complete current behavior, boundaries, and operating guidance + without mentally subtracting a rejected concept. + +## Task Route + +- For the public organization entry point, edit `profile/README.md`. +- For conventions shared by every repository, read `MAINTENANCE.md`. +- For visual identity, read `DESIGN.md`; the renderer, its configuration and + the rendered exports live in `Brand/`, and `README.md` describes rendering + and delivery. +- For positioning, the tagline and other text rendered into images, read the + main repository's + [ProductIdentity](https://github.com/computer-mcp/computer-mcp/blob/master/Documentation/Architecture/ProductIdentity.md). +- For the default community files, use the root governance files, + `.github/ISSUE_TEMPLATE/` and the pull request template. +- Stop and clarify before mixing route instructions into `README` files or + index text into `AGENTS.md`. + +## Authority + +- `AGENTS.md` is the agent guide: first-principles guardrails, task + route, authority boundaries, and boundary guardrails. +- `README.md` indexes scope, brand rendering and delivery. +- `MAINTENANCE.md` is current truth for cross-repository conventions; each + repository owns its own version and release rules. +- `DESIGN.md` and `Brand/config.json` are current truth for visual identity. + `Brand/Exports/` and `profile/brand/` are rendered from them. +- The main repository's ProductIdentity is current truth for product meaning. +- Root governance files and `.github/*` are GitHub-facing governance and the + organization's default community files. + +## Boundary Guardrails + +After the owner and invariant are clear, classify concrete values by stability, +variability, and ownership before writing reusable artifacts. + +Do not promote context-bound values into reusable artifacts. A value is +context-bound if it depends on the current machine, local workspace, current +input, one fixture, one runtime run, one user-specific path, or temporary +execution state. + +Keep shipped documentation focused on current product facts, supported behavior, +and operating guidance. Keep temporary implementation notes, local evidence, +local paths, run-specific artifacts, and historical comparison notes out of +README files, the profile, `MAINTENANCE.md`, `DESIGN.md` and the community +files. Change history belongs in commits and pull requests. + +Use this decision test: + +- If a value changes by input, get it from input, spec, config, parameters, or + an explicit user decision. +- If a value changes by environment, get it from configuration, runtime state, + environment variables, or local execution notes. +- If a value belongs only to one example, fixture, or run, keep it there. Do + not generalize it into reusable docs, schemas, templates, scripts, + validation rules, or automation. +- If the artifact being edited is not the source of truth for the value, do not + hardcode it there. Pass it in, derive it, configure it, or link to the + owning artifact. +- Only stable invariants and values owned by the current artifact may be fixed + in reusable artifacts. + +Classify concrete values before writing: + +1. Name the variable parts. +2. Decide which artifact owns each variable. +3. Replace context-bound literals with placeholders, parameters, config keys, + derived values, or links to the owning artifact. +4. Keep concrete literals only inside the artifact that owns them. + +When in doubt, use a placeholder, parameter, configuration key, or repo-owned +source of truth instead of a literal value. + +## Operating Notes + +- Keep Agent Guide and Index separate. + +## Repository Guardrails + +- Text rendered into images must match ProductIdentity. Preserve repository + visibility and integration ownership. - Change `DESIGN.md` or `Brand/config.json`, re-render, and commit the exports with their manifest. Never edit exports by hand. - Before committing, run `npm --prefix Brand run lint` and `python3 Brand/brand.py check`. - Deliver artwork to other repositories only with `python3 Brand/brand.py sync`, through a pull request in each repository. - -Keep `.agent/` local and untracked. Profile content must be understandable from -committed artifacts alone. +- Keep `.agent/` local and untracked. Profile content must be understandable + from committed artifacts alone. diff --git a/MAINTENANCE.md b/MAINTENANCE.md index bcc3c57..4a75af1 100644 --- a/MAINTENANCE.md +++ b/MAINTENANCE.md @@ -60,7 +60,8 @@ plugin catalog. `Documentation/Decisions/` accepted rationale. - Scripts live in `Scripts/`. Executable scripts use kebab-case names with an extension; imported Python modules use snake_case. -- `AGENTS.md` routes agents through the repository's own documents. +- `AGENTS.md` carries the shared first-principles and canonical-artifact + sections, then routes agents through the repository's own documents. `.agent/` stays local and untracked. ## Community files