diff --git a/.agents/skills/socratic/setup.md b/.agents/skills/socratic/setup.md index ddc072d..6c0cb86 100644 --- a/.agents/skills/socratic/setup.md +++ b/.agents/skills/socratic/setup.md @@ -16,7 +16,21 @@ Ask which tools to connect: `cursor`, `claude`, `codex`, `copilot`, `windsurf`, If the tool reads a different path, use that path. Point it at `.agents` with a symlink or a one-line import. -If `.cursor`, `.claude`, or `.codex` is already a real directory, leave it. Do not delete it. Add a pointer inside that directory and leave the rest of the files. +If `.cursor`, `.claude`, or `.codex` is already a real directory, leave it. Do not delete it. Write the pointer below only when that file is absent, and leave every other file in the directory alone. + +- Cursor applies a nested `AGENTS.md` only while it is working inside that folder, so do not write `.cursor/AGENTS.md`. Write `.cursor/rules/agents.mdc` if it is absent. If `.cursor/rules` is already a file, leave it and skip this pointer. The file is: + + ```mdc + --- + description: Read the harness in .agents before editing. + alwaysApply: true + --- + + Read AGENTS.md before editing. + ``` + +- Claude: `.claude/CLAUDE.md` containing `@../AGENTS.md`. +- Codex reads the root `AGENTS.md` and loads skills from `.agents/skills`. Do not write `.codex/AGENTS.md`. That file is not on Codex's discovery path. Every ignore file lists `.env`, `.env.*`, `*.pem`, and `*.key`. Do not add project policy to an ignore file. @@ -38,7 +52,7 @@ Show the person the list. This list is input for research and the interview. Do ## A later run -When `.agents/rules` or `.agents/skills` already exist, this is an update. +This is an update when `.agents/rules` already contains a file, or `.agents/skills` contains a directory other than `socratic`. The `socratic` skill the installer copied does not count. Run the git checks below on that update, and only then. For each manifest, run `git log -1 -p -- ` from `WORKSPACE`. Also run `git diff -- ` when the working tree differs from HEAD. Tell the person what was added, removed, or version-changed. A manifest that git has never contained before is the whole file, and the existing rules are the previous record. diff --git a/README.md b/README.md index cd5b1c9..7603724 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ A finished run leaves a harness in the repository: - `AGENTS.md` at the root, if you did not already have one. - `.agents/` holding the rules and skills. -- When `.cursor`, `.claude`, or `.codex` is missing, a symlink from that directory to `.agents`, plus that tool's ignore file. If one of those is already a real directory, it stays and the skill adds a pointer inside it. Copilot and Windsurf get a one-line pointer at `AGENTS.md`. +- When `.cursor`, `.claude`, or `.codex` is missing, a symlink from that directory to `.agents`, plus that tool's ignore file. If one of those is already a real directory, it stays. Cursor gets `.cursor/rules/agents.mdc`. Claude gets `.claude/CLAUDE.md` containing `@../AGENTS.md`, and only when that file is absent. Codex uses the root `AGENTS.md` and does not get `.codex/AGENTS.md`. Copilot and Windsurf get a one-line pointer at `AGENTS.md`. - Rules in `.agents/rules/` and skills in `.agents/skills/` for the practices you accepted. - Vendor skills and MCP entries only where you said yes. @@ -36,7 +36,7 @@ You do not get a decision log. Ownership, incidents, and open questions stay in | Step | What it does | | --- | --- | -| `setup.md` | Asks which tools to connect. Writes `AGENTS.md`, `.agents`, and the links. Reads `package.json` and the other manifests. On a later run, reads `git log -1 -p` for those files. | +| `setup.md` | Asks which tools to connect. Writes `AGENTS.md`, `.agents`, and the links. Reads `package.json` and the other manifests. On a later run, reads `git log -1 -p` for those files. The installed `socratic` skill does not by itself make a run a later run. | | `research.md` | Looks up skills and MCP servers for the dependencies, reads the docs for the version in the manifest, and prepares an offer. It does not install anything. | | `interview.md` | Describes the architecture it can see and asks if that is right. Says which skills may be useful and waits for a yes. Writes a rule in the person's words, with no extra ban. | | `verify.md` | Opens each file again and quotes a line from that read. A declined install, and an MCP the docs say this version cannot use, must be absent. | @@ -49,7 +49,7 @@ Two examples: ## What the skills will not do - Install a skill, an MCP server, or a package before you say yes. -- Delete a file it did not write. An existing `.cursor`, `.claude`, or `.codex` directory stays. The skill adds a pointer inside it. +- Delete a file it did not write. An existing `.cursor`, `.claude`, or `.codex` directory stays. Cursor gets `.cursor/rules/agents.mdc`. Claude gets `.claude/CLAUDE.md` only if it is absent. Codex does not get `.codex/AGENTS.md`. - Read `.env`, `.env.*`, `*.pem`, or `*.key`. - Invent a stack by reading source files. Dependencies come from manifests. Architecture questions come from the directories and entry points the interview names. - Upload your repository. A documentation fetch uses a URL the agent shows you first. diff --git a/test/skill-checks.js b/test/skill-checks.js index 0d6d807..30d454a 100644 --- a/test/skill-checks.js +++ b/test/skill-checks.js @@ -21,6 +21,10 @@ const REQUIRED = [ ["setup.md", "including subfolders"], ["setup.md", "git log -1 -p"], ["setup.md", ".cursor` symlinks to `.agents"], + ["setup.md", "The `socratic` skill the installer copied does not count."], + ["setup.md", ".cursor/rules/agents.mdc"], + ["setup.md", "do not write `.cursor/AGENTS.md`"], + ["setup.md", "Do not write `.codex/AGENTS.md`"], ["research.md", "I see you have Next.js and FastAPI. Here are skills that you may find useful."], ["research.md", "needs a newer version"], ["interview.md", "Silence is a no"],