Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs(agents): require explicit install consent

David Liucc4095f3992f
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..ec9bcf37
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,57 @@
+# AGENTS.md
+
+Instructions for coding agents working on this repository.
+
+## Installing Archify
+
+Installing, updating, removing, or reinstalling Archify changes live agent
+configuration outside this checkout. Do that only when the user names that exact
+action directly, such as "install Archify" or "update the global Archify Skill."
+An implied need or a request to edit, test, review, commit, push, merge, release,
+publish, or sync this repository is not consent.
+
+Before any live installation mutation:
+
+1. Confirm the exact action, source, agent, and global or project scope. Do not
+ infer `--all`; use `--yes` only after those values are explicit. A reinstall
+ is an update/install operation, not permission to remove unrelated paths.
+2. For a Skills CLI add, first run
+ `npx -y skills add tt-a1i/archify --list --full-depth`. This documented
+ `--list` mode must discover exactly one Skill named `archify`. On a command
+ error, zero matches, or multiple matches, stop and report the output without
+ running a mutating command.
+3. Install from the canonical `tt-a1i/archify` source. Do not use a path under a
+ system temporary directory, a Git worktree, or another session-scoped
+ checkout as a local package source. A deliberate local-source install may
+ use a clean, durable checkout only when the user explicitly asks for it;
+ prefer `--copy` unless they explicitly request managed symlinks.
+4. Before a manual copy or extraction, fail if the destination exists; report
+ the exact path and never delete or replace it unless the user explicitly
+ approves that named path after seeing the conflict. For Skills CLI and
+ package-manager operations, use their own conflict handling,
+ never add an unrequested force flag, and report every skipped, replaced, or
+ failed destination.
+5. Afterward, report the exact command, source, action, skill or package, agent,
+ scope, and result. Never describe a partial installation as success.
+
+For `skills update`, name `archify` and pass `--global` or `--project` explicitly;
+do not run an unscoped bulk update. For `skills remove`, name `archify`, specify
+its scope and requested agents, and never use `--all`. Manual `archify.zip`
+extraction, Claude.ai upload, DSH plugin add/remove, and package-manager
+installation follow the same action/scope confirmation and reporting rules; use
+the documented exact destination or package version and preserve unrelated
+files. The Skill's update checker is notification-only, so an update notice
+never authorizes installation.
+
+## Repository workflow
+
+Follow [`CONTRIBUTING.md`](CONTRIBUTING.md) for planning, compatibility,
+validation, generated artifacts, and pull-request evidence. In particular:
+
+- start from the latest `main` and keep one behavior per pull request;
+- run the narrowest relevant test first and `npm test` from `archify/` before
+ final review;
+- rebuild `archify.zip` only when packaged Skill bytes change;
+- do not claim remote CI passed unless it ran on the current head;
+- never include secrets, private repository content, personal data, or customer
+ data in repository artifacts.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..1024897d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# Claude Code instructions
+
+Read and follow [`AGENTS.md`](AGENTS.md).
+
diff --git a/archify/test/agent-install-consent.test.mjs b/archify/test/agent-install-consent.test.mjs
new file mode 100644
index 00000000..b7a15940
--- /dev/null
+++ b/archify/test/agent-install-consent.test.mjs
@@ -0,0 +1,54 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..', '..');
+const agents = fs.readFileSync(path.join(repoRoot, 'AGENTS.md'), 'utf8');
+const claude = fs.readFileSync(path.join(repoRoot, 'CLAUDE.md'), 'utf8');
+
+const discoveryCommand = 'npx -y skills add tt-a1i/archify --list --full-depth';
+
+test('agent installation requires direct action and explicit scope', () => {
+ assert.match(agents, /only when the user names that exact\s+action directly/i);
+ assert.match(agents, /implied need[\s\S]*is not consent/i);
+ assert.match(agents, /exact action, source, agent, and global or project scope/i);
+ assert.match(agents, /Do not\s+infer `--all`/i);
+ assert.match(agents, /use `--yes` only after those values are explicit/i);
+ assert.match(agents, /A reinstall[\s\S]*not permission to remove unrelated paths/i);
+});
+
+test('Skills CLI discovery is non-mutating and fails closed', () => {
+ assert.ok(agents.includes(discoveryCommand));
+ assert.match(agents, /documented\s+`--list` mode/i);
+ assert.match(agents, /exactly one Skill named `archify`/i);
+ assert.match(agents, /command\s+error, zero matches, or multiple matches[\s\S]*stop[\s\S]*without\s+running a mutating command/i);
+});
+
+test('local and manual installs preserve unrelated destinations', () => {
+ assert.match(agents, /canonical `tt-a1i\/archify` source/i);
+ assert.match(agents, /system temporary directory[\s\S]*Git worktree[\s\S]*session-scoped/i);
+ assert.match(agents, /prefer `--copy` unless they explicitly request managed symlinks/i);
+ assert.match(agents, /Before a manual copy or extraction, fail if the destination exists/i);
+ assert.match(agents, /never delete or replace it unless the user explicitly[\s\S]*approves[\s\S]*named path[\s\S]*conflict/i);
+ assert.match(agents, /never add an unrequested force flag/i);
+ assert.match(agents, /Never describe a partial installation as success/i);
+ assert.match(agents, /exact command, source, action, skill or package, agent,[\s\S]*scope, and result/i);
+});
+
+test('updates and removals stay named and scoped', () => {
+ assert.match(agents, /For `skills update`, name `archify`/i);
+ assert.match(agents, /pass `--global` or `--project` explicitly/i);
+ assert.match(agents, /For `skills remove`, name `archify`/i);
+ assert.match(agents, /specify[\s\S]*scope and requested agents/i);
+ assert.match(agents, /never use `--all`/i);
+ assert.match(agents, /Manual `archify\.zip`[\s\S]*Claude\.ai upload[\s\S]*DSH plugin add\/remove/i);
+ assert.match(agents, /update checker is notification-only[\s\S]*never authorizes installation/i);
+});
+
+test('Claude Code inherits the shared root policy with a plaintext fallback', () => {
+ assert.match(claude, /Read and follow \[`AGENTS\.md`\]\(AGENTS\.md\)/);
+ assert.match(claude, /^@AGENTS\.md$/m);
+});