diff --git a/.agents/skills/socratic/SKILL.md b/.agents/skills/socratic/SKILL.md index 188b220..c82ac2b 100644 --- a/.agents/skills/socratic/SKILL.md +++ b/.agents/skills/socratic/SKILL.md @@ -1,11 +1,11 @@ --- name: socratic -description: Set up a repository after this skill is installed. Asks which agent tools to connect, reads the manifests and the code, and writes rules and skills the person accepts. Use when the person installs this skill, wants a harness, or wants the harness brought up to date. +description: Set up a repository after this skill is installed. Asks which agent tools to connect, reads the manifests and the code, and writes rules and skills the person accepts. Use when the person installs this skill, wants harness instructions, or wants the harness instructions brought up to date. --- # Socratic -You are already the agent. The person installed this skill. This directory is not the repository to wrap. Do not inspect this skill's own folder for the project's manifests, and do not clone the harness repository. +You are already the agent. The person installed this skill. This directory is not the repository to wrap. Do not inspect this skill's own folder for the project's manifests, and do not clone this repository. If they just installed you, set the repository up before you do anything else. @@ -22,11 +22,11 @@ Four steps ship in this folder. They are not separate skills. Read each file and 3. `interview.md` 4. `verify.md` -If one is missing, stop. Do not invent a replacement. Do not run a harness program. There is no CLI. +If one is missing, stop. Do not invent a replacement. Do not run a separate program. There is no CLI. ## Rules for every step -- Do not delete, move, or overwrite a file this harness did not write. You may edit a rule, skill, or MCP entry this harness wrote. You may not delete source files, manifests, `.git`, or a tool directory that was already there. +- Do not delete, move, or overwrite a file this skill did not write. You may edit a rule, skill, or MCP entry this skill wrote. You may not delete source files, manifests, `.git`, or a tool directory that was already there. - Do not create, delete, or modify `.git`. - Do not invent a practice the person did not state. An answer that does not change how an agent should work produces no file. - Do not install a skill, an MCP server, or a package until the person says yes in this chat. Do not treat silence as a yes. diff --git a/.agents/skills/socratic/setup.md b/.agents/skills/socratic/setup.md index 6c0cb86..28d9017 100644 --- a/.agents/skills/socratic/setup.md +++ b/.agents/skills/socratic/setup.md @@ -22,7 +22,7 @@ If `.cursor`, `.claude`, or `.codex` is already a real directory, leave it. Do n ```mdc --- - description: Read the harness in .agents before editing. + description: Read the harness instructions in .agents before editing. alwaysApply: true --- diff --git a/.out-of-scope/no-cli.md b/.out-of-scope/no-cli.md index aa01b61..223a8ff 100644 --- a/.out-of-scope/no-cli.md +++ b/.out-of-scope/no-cli.md @@ -1 +1 @@ -The harness is the socratic skill and the four step files it reads. A program the skill shells out to, and a second command name, are out of scope. +This project is the socratic skill and the four step files it reads. A program the skill shells out to, and a second command name, are out of scope. diff --git a/README.md b/README.md index 7603724..317f595 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ SOC, a black-and-white stick-figure sketch holding a scroll with a question mark

-Human intent becomes a harness an agent can follow. This repository is one skill, `socratic`. You install it, open an agent in your repository, and the agent does the work. There is no CLI. +Human intent becomes harness instructions an agent can follow. This repository is one skill, `socratic`. You install it in a repository you already have. That repository either has harness instructions or it does not. SOC asks about what the code is already doing before anyone writes a rule. The skill does not invent a practice the person did not state. An answer that does not change how an agent should work produces no file. @@ -16,15 +16,26 @@ npx skills add beelarr/soc That installs one skill, `socratic`. Open an agent in the repository you want to wrap. It reads `setup.md`, `research.md`, `interview.md`, and `verify.md` from its own folder and follows them in that order. Those four files are not separate skills, so they do not take the names `setup`, `research`, `interview`, or `verify` in the skill list. -Add `-g` to install the skill for every repository on your machine. Update it later with `npx skills update`. +Add `-g` to install the skill for every repository on your machine. `npx skills update` updates the installed `socratic` skill. It does not by itself improve the harness instructions in the repository. That is another session. + +## Two paths + +Harness instructions are the documentation an agent follows: `AGENTS.md`, the rules in `.agents/rules/`, and the skills in `.agents/skills/`. Those files are the harness instructions. The skill does not create the repository. + +- **No harness instructions yet.** The repository has no `AGENTS.md`, and `.agents/` has no rules and no skills besides `socratic` after the install. The skill writes the harness instructions from what you accept. +- **Harness instructions are already there.** The skill reads the rules and skills it finds, checks the manifests for what changed, and updates a rule, skill, or MCP entry it wrote when your answer says to. An `AGENTS.md` you already wrote stays. If it does not mention `.agents`, the skill adds a short pointer at the end. + +## Any tool + +The harness instructions have one copy, in `.agents`. The skill asks which tools to connect: Cursor, Claude, Codex, Copilot, Windsurf, or all of them. A tool that reads some other path still gets a symlink or a one-line import pointing at `.agents`. It does not get its own copy of the rules and skills. ## What you get -A finished run leaves a harness in the repository: +A first run leaves harness instructions in the repository. A later run leaves the harness instructions that are already there and changes only what you accept: - `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. 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`. +- 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`. Any other tool gets a symlink or a one-line import to `.agents`. - Rules in `.agents/rules/` and skills in `.agents/skills/` for the practices you accepted. - Vendor skills and MCP entries only where you said yes. diff --git a/SCOPE.md b/SCOPE.md index 8a34c43..d40c1a4 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -10,6 +10,6 @@ A wish with no session behind it can wait. Put how-do-I questions in discussions Read .out-of-scope/ before you file. Those notes are decisions, not a backlog. -Also out of scope: a setting that only your tool needs, a branch for one harness, and a change that exists to match one person's habits. Put that in your own AGENTS.md, or fork the skill. +Also out of scope: a setting that only your tool needs, a branch for one tool, and a change that exists to match one person's habits. Put that in your own AGENTS.md, or fork the skill. If an issue is too thin to judge, we will ask once. If there is no reply, we will close it. diff --git a/test/skill-checks.js b/test/skill-checks.js index 30d454a..a9ba465 100644 --- a/test/skill-checks.js +++ b/test/skill-checks.js @@ -14,7 +14,7 @@ const REQUIRED = [ ["SKILL.md", "interview.md"], ["SKILL.md", "verify.md"], ["SKILL.md", "They are not separate skills"], - ["SKILL.md", "Do not delete, move, or overwrite a file this harness did not write"], + ["SKILL.md", "Do not delete, move, or overwrite a file this skill did not write"], ["SKILL.md", "Do not create, delete, or modify `.git`"], ["setup.md", "Do not delete it"], ["setup.md", "package.json"], diff --git a/test/skills.test.js b/test/skills.test.js index 4c15ba8..966e3f7 100644 --- a/test/skills.test.js +++ b/test/skills.test.js @@ -2,7 +2,7 @@ import assert from "node:assert/strict"; import { test } from "node:test"; import { checkSkills } from "./skill-checks.js"; -test("the five skills are the harness, and none of them invokes a CLI", async () => { +test("socratic is the only installable skill, and none of the files invokes a CLI", async () => { const result = await checkSkills(); assert.deepEqual(result.failures, []); });