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
5 changes: 2 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,8 @@ handled-error recovery in `docs/errors.md`, publication mechanics in `RELEASING.
- Changes to the accepted API-contract range, accepted Plan formats, command names or flags, handled `error` values,
exit statuses, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `RELEASING.md`, `.claude/settings.json`, or
`.codex/config.toml` get an independent review through cross-review: `codex-review` from Claude Code,
`$claude-review` from Codex. Pass the service repository's `docs/review-focus.md` as `--focus-file`, fetched
with `gh api` when no sibling checkout exists. Put the reviewer, session id, and verdict in the pull request
body, and leave the findings out.
`$claude-review` from Codex. Pass the service repository's `docs/review-focus.md` as `--focus-file` (see
`CONTRIBUTING.md`). Put the reviewer, session id, and verdict in the pull request body, and leave the findings out.
- `firstdraft plan compile` defaults to local output in the current directory. GitHub publication requires
`--github`; Codespaces is a fallback. Keep Skill callers and recovery instructions aligned with this boundary.
- The service repository coordinates releases and owns their approval and smoke policy. One approved coordinated
Expand Down
5 changes: 2 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,8 @@ This file records changes to the `@firstdraft.com/cli` package, newest first. Ea
An entry is written in the pull request that sets its version, so the newest entry can precede publication. Headings
carry no release status. The `v<version>` tag and npm show whether a version is published.

Entries start with the first version prepared after this file was added, and earlier versions have none. The frozen
[release history](docs/release-history.md) records releases through 0.4.0. The repository's
[tags](https://github.com/firstdraft/cli/tags) identify the source of each published version, including later ones.
Entries start with the first version prepared after this file was added, and earlier versions have none. The
repository's [tags](https://github.com/firstdraft/cli/tags) identify the source of each published version.

## 0.8.1

Expand Down
20 changes: 3 additions & 17 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,22 +53,8 @@ reviews from Claude Code, and Claude Code reviews from Codex. Install both and s
and `codex login`). In Claude Code, ask for a Codex review or run `/codex-review:codex-review`; in Codex, use
`$claude-review`. Neither is a shell command.

- **Claude Code:** the tracked `.claude/settings.json` registers the cross-review marketplace and enables
`codex-review`. It loads once you accept the workspace-trust prompt for the main checkout; linked worktrees use
that trust. A headless `claude -p` run loads it only where you have already trusted the checkout.
- **Codex:** the tracked `.codex/config.toml` declares the marketplace and enables `$claude-review` in a trusted
project. The first trusted session fetches the plugin and the next one loads it;
`codex plugin marketplace upgrade cross-review` fetches it at once. In the Codex desktop app, quit and reopen it
after the first fetch.

If the tracked configuration does not load a plugin, install it yourself:

```sh
claude plugin marketplace add raghubetina/cross-review
claude plugin install codex-review@cross-review
codex plugin marketplace add raghubetina/cross-review
codex plugin add claude-review@cross-review
```
The tracked `.claude/settings.json` and `.codex/config.toml` enable both plugins once you trust the main checkout,
and linked worktrees inherit that trust. The cross-review README covers installing them by hand.

To run a review:

Expand Down Expand Up @@ -115,5 +101,5 @@ in all three repositories: `firstdraft/firstdraft`, `firstdraft/skills`, and `fi

- Test each line of every `AGENTS.md`: would an agent get a task wrong if the line were gone? If not, delete it. In
Claude Code, `/doctor prompt-audit` also suggests lines to cut.
- Shrink each exceptions list, such as `docs/owner-shape-exceptions.json` in `firstdraft/firstdraft`.
- Shrink each exceptions list, such as `currencyBaseline` in `firstdraft/skills`.
- Delete any documentation check that caught nothing that tests or review would not have caught.
19 changes: 9 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,13 +42,13 @@ Run firstdraft --help or a command group's --help for concise terminal syntax.

## Repository layout

| Path | Responsibility |
| -------- | --------------------------------------------------------------------------- |
| bin/ | Published executable entrypoint |
| src/ | Commands, API client, local Plan state, and output contracts |
| test/ | Command, protocol, recovery, and package tests |
| scripts/ | Test runner, package checks, and version sync |
| docs/ | Documentation map, command and error references, and frozen release history |
| Path | Responsibility |
| -------- | ------------------------------------------------------------ |
| bin/ | Published executable entrypoint |
| src/ | Commands, API client, local Plan state, and output contracts |
| test/ | Command, protocol, recovery, and package tests |
| scripts/ | Test runner, package checks, and version sync |
| docs/ | Documentation map and command and error references |

## Development

Expand Down Expand Up @@ -102,6 +102,5 @@ The published package:
- carries npm provenance linking registry bytes to its GitHub workflow and commit.

The package includes this README, the documentation map, the command and error references, and the security
policy. Repository files for maintainers stay out of it: `AGENTS.md`, the release runbook, the changelog, the
release history, and the source-only `release/compatibility.json`. Inspect the packed file list whenever a source or
documentation path moves.
policy. Repository files for maintainers stay out of it: `AGENTS.md`, the release runbook, the changelog, and the
source-only `release/compatibility.json`. Inspect the packed file list whenever a source or documentation path moves.
7 changes: 0 additions & 7 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,6 @@ evidence for implemented behavior; if they contradict a document, surface the co
Start here, then load the one owning document for the task. Follow a cross-link only when the task crosses an
authority boundary. Create another page only for a distinct audience, task, or authority.

The documentation tests cap `AGENTS.md` at 2 KiB, the root README at 6 KiB, and this map at 4 KiB. They also
require every public topic to be reachable from this map or the root README. They check relative links, links to
this repository's `main` on GitHub, and their fragments. Outside the changelog and release history, they reject
retired version identities and release-status labels on the current version. They also reject status labels in
changelog headings. The package check verifies that relative links in packaged Markdown resolve inside the package;
packaged pages link other files on GitHub.

## Work on the repository

Development uses Node.js 24.18.0 and npm 11.16.0, pinned in `.tool-versions`. From a fresh checkout:
Expand Down
78 changes: 0 additions & 78 deletions docs/release-history.md

This file was deleted.

7 changes: 1 addition & 6 deletions test/documentation.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -141,12 +141,7 @@ test("living documentation names only current version identities", () => {

for (const [file, source] of sources) {
const name = path.relative(repository, file);
if (
name === "CHANGELOG.md" ||
name === path.join("docs", "release-history.md")
) {
continue;
}
if (name === "CHANGELOG.md") continue;

findings.push(...staleVersionFindings(name, source, identities));

Expand Down
Loading