Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions .agents/skills/socratic/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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 -- <file>` from `WORKSPACE`. Also run `git diff -- <file>` 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.

Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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. |
Expand All @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions test/skill-checks.js
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand Down
Loading