reyson-spec-gate

A spec-first installer for coding-agent workflow rules, docs, and skills.

reyson-spec-gate is designed to install a consistent pre-coding workflow into a workspace so that agents do not jump directly from a loose request into implementation.

Its central rule is simple:

No coding before the spec is clear, the task list exists, and the checklist exists.

Recommended usage

Do not rely on global installation as the primary path.

The recommended way to use this package is:

npx reyson-spec-gate

This launches the interactive installer directly and avoids depending on a permanently global npm installation.

What it installs

The installer always installs the shared workflow assets:

• docs/spec-workflow.md
• skills/generate-task-list/SKILL.md
• skills/generate-checklist/SKILL.md

It also installs RULES.md only for selected agents.

It does not install:

• AGENTS.md
• CLAUDE.md

All agent-specific rule entrypoints are normalized to RULES.md.

Supported agents

The interactive installer currently supports these agent targets:

1. Codex
2. Trae
3. Claude Code
4. Cursor
5. Antigravity

You can select one or more targets in the same run.

If you do not select anything, the installer will:

• default to Codex
• print a message explaining that Codex was chosen by default

Interactive behavior

Run:

npx reyson-spec-gate

The installer will ask:

1. which directory to install into
2. which agent targets to install for

Agent selection is multi-select.

Example:

• 1,3,4 installs for Codex, Claude Code, and Cursor

If you press ENTER without choosing an agent, it falls back to Codex.

Output structure

The installer writes the shared assets into the target directory and installs rule files per agent under agents/<agent>/RULES.md.

Example output:

my-project/
├── docs/
│   └── spec-workflow.md
├── skills/
│   ├── generate-task-list/
│   │   └── SKILL.md
│   └── generate-checklist/
│       └── SKILL.md
└── agents/
    ├── codex/
    │   └── RULES.md
    ├── claude-code/
    │   └── RULES.md
    └── cursor/
        └── RULES.md

This structure avoids filename collisions when multiple agents are installed in one run.

Non-interactive usage

If you want a scriptable path, you can still run the installer non-interactively.

Default to Codex

npx reyson-spec-gate install --yes --dir ./my-project

Install multiple agent targets

npx reyson-spec-gate install --yes --dir ./my-project --agents codex,trae,claude,cursor,antigravity

Why npx is preferred

The purpose of this package is to run an installation workflow, not simply to sit globally on a machine.

Using npx reyson-spec-gate is preferable because:

• it is explicit
• it is easy to run in any repository
• it avoids stale global versions
• it keeps the install workflow lightweight

Global installation can still work, but it is no longer the recommended entrypoint.

Workflow model

This package is based on a spec-first coding workflow.

The intended flow is:

1. The agent reads docs/spec-workflow.md
2. The agent checks whether the current work has:
   • a working spec
   • a task list
   • a checklist
3. If the task list is missing, the agent uses generate-task-list
4. If the checklist is missing, the agent uses generate-checklist
5. Only after both artifacts exist does coding begin
6. After coding, the checklist is revisited before claiming completion

Responsibilities

docs/spec-workflow.md

This file is the workflow knowledge source.

It defines:

• the pre-coding gate
• artifact ordering
• task-list requirements
• checklist requirements
• coding readiness rules
• post-coding verification rules

skills/generate-task-list

This skill generates or normalizes an explicit task list from a spec or plan.

skills/generate-checklist

This skill generates a checklist from the working spec and task list.

agents/<agent>/RULES.md

Each selected agent receives a RULES.md entrypoint.

Its job is to remind the target agent to:

• read the workflow doc first
• check for task list and checklist presence
• generate missing artifacts before implementation
• avoid coding before the pre-coding gate passes

Example installation commands

Install for Codex only

npx reyson-spec-gate install --yes --dir ./my-project --agents codex

Install for Trae and Cursor

npx reyson-spec-gate install --yes --dir ./my-project --agents trae,cursor

Install for all supported agents

npx reyson-spec-gate install --yes --dir ./my-project --agents codex,trae,claude,cursor,antigravity

Development

Run locally:

node bin/reyson-spec-gate.js --help
node bin/reyson-spec-gate.js install

Package identity

Current npm package:

reyson-spec-gate

Recommended invocation:

npx reyson-spec-gate

Notes

This repository intentionally standardizes every agent rule entrypoint to RULES.md.

That means:

• no AGENTS.md
• no CLAUDE.md
• a single normalized rules filename for all supported agent targets

This keeps the workflow easier to reason about and easier to extend.