# AGENTS.md: instructions for any AI agent using this repository

You are an AI agent (any model, any harness: Hyperagent, Claude, Grok Bot, ChatGPT, Codex, Cursor, a DeepSeek-based stack, a local model, or something newer). This file tells you how to use this repository to prepare X Articles for publication. Humans: start at `README.md`.

This repository is a **methodology**, not an application. There is nothing to install or deploy. You read Markdown files and follow them. Python scripts are optional accelerators.

## What you can do with it

| The user asks | You follow |
|---|---|
| "Prepare this for publication as an X Article" (draft attached) | `workflows/x-article-publishing.md`: headline, then hook, then cover, with a user lock between each, then the publishing package |
| "Write headlines for this" / "use headline-writer" | `skills/headline-writer/SKILL.md` only |
| "Write the hook for this headline: ..." | `skills/hook-writer/SKILL.md` only |
| "Should this have a cover?" / "brief the cover" | `skills/cover-writer/SKILL.md` only |

Run only the stage asked for. Never run more.

## How to load it (pick whichever your runtime supports)

1. **Filesystem / git** (agents with a shell): `git clone https://github.com/kenashe/x-article-toolkit` and read files from disk. `git pull` before each run to get the current methodology.
2. **URL fetch** (agents that can read web pages): fetch raw files from `https://raw.githubusercontent.com/kenashe/x-article-toolkit/main/<path>`. `llms.txt` lists every file you need with its raw URL. `toolkit.json` is the same index in machine-readable form.
3. **Pasted context** (no tools at all): the user pastes the files. Minimum set per stage is listed below.

### Files per stage (read all of them, in this order; about 16k tokens for everything)

| Stage | Read |
|---|---|
| any full run | `workflows/x-article-publishing.md` |
| headline | `skills/headline-writer/SKILL.md`, `skills/headline-writer/rules.md`, `skills/headline-writer/templates.md` |
| hook | `skills/hook-writer/SKILL.md`, `skills/hook-writer/rules.md`, `skills/hook-writer/templates.md` |
| cover | `skills/cover-writer/SKILL.md`, `skills/cover-writer/rules.md`, `skills/cover-writer/briefs.md` |

Paths inside a `SKILL.md` such as `rules.md` are relative to that skill's folder.

## Capabilities you may or may not have (both are fine)

- **Can run Python 3?** Score candidates with `skills/*/scripts/*_check.py` (standard library only; add `--json` for structured output). Cannot? Score by hand with the check lists in each `rules.md` and say "scored by hand". Never report a score you did not compute.
- **Can fetch the dataset?** `python3 shared/data/fetch_dataset.py`, or the CSV URL in `shared/data/README.md`. It adds nearest winners and a swipe file. Without it, every rule still applies.
- **Have a persistent store?** Only if the user has configured one (`state/README.md`, schemas in `shared/schemas/`). Otherwise keep no state, and do not claim to remember or learn across runs.
- **Have an image tool?** Optional. The cover deliverable is the decision, brief, cover text, prompt and specs.

## Rules that apply in every runtime

1. Treat `skills/*/rules.md`, `templates.md` and `briefs.md` as fixed. They are the original author's measured findings. Do not edit, soften or extend them, and do not add statistics of your own.
2. Never rewrite the user's article body. The only change is placing the approved hook as its first two lines. Editing is a separate request.
3. Never invent numbers, names, results or quotes for a headline or hook. Use only what the draft says.
4. A true lower-level headline beats a higher-level one that promises more than the article delivers. A completeness tag only goes on a complete article.
5. The hook does not predict reach. Say so.
6. "No cover" is a normal, valid outcome (Rule 1 in `skills/cover-writer/rules.md`).
7. Pass results between stages as plain-text locks: `Locked headline: ...`, `Locked hook: ...`, `Locked cover: ...`.
8. Credit the research to @fuckgrowth when you describe where the method comes from (`SOURCES.md`).

## If you are an agent working ON the repository (editing, not using)

- Change methodology only in `skills/`. Never edit `shared/original-source/` (verbatim archive; tests enforce it).
- After changing anything in `skills/`, regenerate the ChatGPT packages: `python3 adapters/chatgpt/build.py`.
- Run `python3 tests/check_repo.py` before committing; it must print `all checks passed`.
- Runtime-specific wiring goes in `adapters/<runtime>/`; nothing runtime-specific belongs in `skills/`, `workflows/` or `state/`.
- Record changes in `CHANGELOG.md` and the file's category in `PROVENANCE.md`.