reyson-spec-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skill-reyson contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# skill-reyson
+
+An interactive npm installer for a spec-first coding workflow.
+
+`skill-reyson` helps teams install a lightweight scaffold that makes coding agents slower in the right place: **before implementation starts**.
+
+It enforces a simple rule:
+
+> No coding before the spec is clear, the task list exists, and the checklist exists.
+
+---
+
+## What this package installs
+
+By default, the installer copies only the core workflow assets into your target directory:
+
+- `docs/spec-workflow.md`
+- `skills/generate-task-list/SKILL.md`
+- `skills/generate-checklist/SKILL.md`
+
+By default, it **does not** install agent guidance files.
+
+If you choose to install agent guidance files during setup, it can also add one or more of:
+
+- `AGENTS.md` for Codex-style workflows
+- `CLAUDE.md` for Claude Code-style workflows
+- `RULES.md` as a generic rules entrypoint
+
+---
+
+## Installation
+
+```bash
+npm i -g reyson-spec-gate
+```
+
+## Quick start
+
+Install globally, then run the interactive installer:
+
+```bash
+skill-reyson
+```
+
+Fast path examples:
+
+```bash
+# install only docs + skills into the current project
+skill-reyson install --yes --dir .
+
+# install docs + skills + Codex AGENTS.md
+skill-reyson install --yes --dir . --with-agent-files --agents codex
+```
+
+Then run:
+
+```bash
+skill-reyson
+```
+
+or:
+
+```bash
+skill-reyson install
+```
+
+---
+
+## Interactive setup
+
+The CLI is interactive by default.
+
+It asks:
+1. where to install the scaffold
+2. whether to install agent guidance files
+3. which agent adapters to install
+
+### Default behavior
+
+If you accept the defaults:
+- docs and skills are installed
+- `AGENTS.md` / `CLAUDE.md` / `RULES.md` are **not** installed
+
+This matches your desired safe default: **no agent behavior file unless the user opts in**.
+
+---
+
+## Non-interactive setup
+
+You can also run the installer non-interactively.
+
+### Install core files only
+
+```bash
+skill-reyson install --yes --dir ./my-project
+```
+
+### Install core files plus Codex adapter
+
+```bash
+skill-reyson install --yes --dir ./my-project --with-agent-files --agents codex
+```
+
+### Install multiple agent adapters
+
+```bash
+skill-reyson install --yes --dir ./my-project --with-agent-files --agents codex,claude,generic
+```
+
+---
+
+## Why this exists
+
+In many spec-driven workflows, an agent may produce a decent spec and still move into coding too early.
+
+Typical failure modes:
+- the task list is implicit instead of explicit
+- the checklist is missing or too generic
+- the agent starts coding before execution and verification artifacts are aligned
+
+`skill-reyson` fixes this by separating the workflow into three responsibilities:
+
+- **agent guidance files** tell the agent how to behave
+- **docs** explain the workflow and readiness gate
+- **skills** generate missing artifacts
+
+---
+
+## Repository structure
+
+```text
+skill-reyson/
+├── AGENTS.md
+├── LICENSE
+├── README.md
+├── package.json
+├── bin/
+│   └── skill-reyson.js
+├── docs/
+│   └── spec-workflow.md
+├── examples/
+│   ├── example-derived-artifacts.md
+│   └── example-input-spec.md
+├── skills/
+│   ├── generate-task-list/
+│   │   └── SKILL.md
+│   └── generate-checklist/
+│       └── SKILL.md
+└── templates/
+    └── adapters/
+        ├── AGENTS.md
+        ├── CLAUDE.md
+        └── RULES.md
+```
+
+---
+
+## Responsibility split
+
+### 1. Agent guidance files
+
+Optional files such as `AGENTS.md`, `CLAUDE.md`, or `RULES.md` act as the enforcement layer.
+
+Their job is to tell the agent:
+- read the workflow doc before coding
+- check whether task list and checklist exist
+- generate missing artifacts before implementation
+- revisit the checklist after coding
+
+### 2. `docs/spec-workflow.md`
+
+This is the workflow knowledge layer.
+
+It defines:
+- the pre-coding gate
+- artifact ordering rules
+- task-list expectations
+- checklist expectations
+- coding readiness rules
+- post-coding review rules
+
+### 3. Skills
+
+The two included skills are execution helpers.
+
+#### `generate-task-list`
+Use this when the workflow has a spec or plan but no explicit task list.
+
+#### `generate-checklist`
+Use this when the workflow has a spec and task list but no explicit checklist.
+
+---
+
+## Core workflow
+
+1. Read the workflow document
+2. Check whether the current task has a working spec
+3. Check whether a task list exists
+4. Check whether a checklist exists
+5. If task list is missing, generate it
+6. If checklist is missing, generate it
+7. Start coding only after the readiness gate is satisfied
+8. Revisit the checklist after coding
+
+---
+
+## Included examples
+
+See:
+- `examples/example-input-spec.md`
+- `examples/example-derived-artifacts.md`
+
+These show how a spec can lead to an explicit task list and checklist before coding begins.
+
+---
+
+## Development
+
+Run locally without publishing:
+
+```bash
+node bin/skill-reyson.js --help
+node bin/skill-reyson.js install
+```
+
+---
+
+## Open-source intent
+
+This project is meant to stay small, composable, and easy to adapt.
+
+Good future extensions:
+- additional agent adapters
+- a readiness report skill
+- templates for Working Spec output
+- project-specific workflow variants
+- validation fixtures and smoke tests
+
+---
+
+## Publish checklist
+
+Before publishing to GitHub or npm, verify:
+
+- `node bin/skill-reyson.js --help` works
+- `skill-reyson install --yes --dir /tmp/somewhere` copies the expected files
+- default install does **not** copy agent guidance files
+- `--with-agent-files --agents ...` copies the selected adapter files
+- `README.md` matches current CLI behavior
+- `package.json` name, version, license, and bin entry are correct
+
+### Suggested GitHub steps
+
+```bash
+cd /Users/bytedance/Desktop/coding/skill-reyson
+git remote add origin <your-github-repo-url>
+git push -u origin master
+```
+
+### Suggested npm publish steps
+
+```bash
+cd /Users/bytedance/Desktop/coding/skill-reyson
+npm login
+npm publish
+```
+
+If you want a safer dry run first:
+
+```bash
+npm pack
+```

package/bin/skill-reyson.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const DOC_SOURCE = path.join(PACKAGE_ROOT, 'docs', 'spec-workflow.md');
+const SKILL_SOURCES = [
+  {
+    source: path.join(PACKAGE_ROOT, 'skills', 'generate-task-list', 'SKILL.md'),
+    relativeTarget: path.join('skills', 'generate-task-list', 'SKILL.md'),
+  },
+  {
+    source: path.join(PACKAGE_ROOT, 'skills', 'generate-checklist', 'SKILL.md'),
+    relativeTarget: path.join('skills', 'generate-checklist', 'SKILL.md'),
+  },
+];
+const ADAPTERS = {
+  codex: {
+    label: 'Codex',
+    source: path.join(PACKAGE_ROOT, 'templates', 'adapters', 'AGENTS.md'),
+    target: 'AGENTS.md',
+  },
+  claude: {
+    label: 'Claude Code',
+    source: path.join(PACKAGE_ROOT, 'templates', 'adapters', 'CLAUDE.md'),
+    target: 'CLAUDE.md',
+  },
+  generic: {
+    label: 'Generic rules',
+    source: path.join(PACKAGE_ROOT, 'templates', 'adapters', 'RULES.md'),
+    target: 'RULES.md',
+  },
+};
+
+function printHelp() {
+  console.log(`skill-reyson
+
+Usage:
+  skill-reyson                Start interactive installer
+  skill-reyson install        Start interactive installer
+  skill-reyson install --dir <path> [--agents codex,claude,generic] [--with-agent-files]
+  skill-reyson install --yes [--dir <path>] [--agents codex,claude,generic] [--with-agent-files]
+  skill-reyson --help         Show help
+
+Defaults:
+  - Installs docs/spec-workflow.md
+  - Installs skills/generate-task-list/SKILL.md
+  - Installs skills/generate-checklist/SKILL.md
+  - Does NOT install agent guidance files unless requested
+`);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const options = { command: 'install', dir: process.cwd(), yes: false, withAgentFiles: false, agents: [] };
+  if (args[0] && !args[0].startsWith('-')) {
+    options.command = args.shift();
+  }
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') {
+      options.command = 'help';
+    } else if (arg === '--yes' || arg === '-y') {
+      options.yes = true;
+    } else if (arg === '--with-agent-files') {
+      options.withAgentFiles = true;
+    } else if (arg === '--dir') {
+      options.dir = path.resolve(args[i + 1] || process.cwd());
+      i += 1;
+    } else if (arg.startsWith('--dir=')) {
+      options.dir = path.resolve(arg.split('=')[1]);
+    } else if (arg === '--agents') {
+      options.agents = (args[i + 1] || '').split(',').map((s) => s.trim()).filter(Boolean);
+      i += 1;
+    } else if (arg.startsWith('--agents=')) {
+      options.agents = arg.split('=')[1].split(',').map((s) => s.trim()).filter(Boolean);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function copyFile(source, target) {
+  ensureDir(path.dirname(target));
+  fs.copyFileSync(source, target);
+}
+
+function copyCoreArtifacts(targetDir) {
+  const docTarget = path.join(targetDir, 'docs', 'spec-workflow.md');
+  copyFile(DOC_SOURCE, docTarget);
+  for (const skill of SKILL_SOURCES) {
+    copyFile(skill.source, path.join(targetDir, skill.relativeTarget));
+  }
+  return [
+    path.relative(targetDir, docTarget),
+    ...SKILL_SOURCES.map((skill) => skill.relativeTarget),
+  ];
+}
+
+function copyAgentFiles(targetDir, selectedAgents) {
+  const copied = [];
+  for (const key of selectedAgents) {
+    const adapter = ADAPTERS[key];
+    if (!adapter) continue;
+    copyFile(adapter.source, path.join(targetDir, adapter.target));
+    copied.push(adapter.target);
+  }
+  return copied;
+}
+
+function normalizeAgents(agentKeys) {
+  return Array.from(new Set(agentKeys.filter((key) => ADAPTERS[key])));
+}
+
+function createInterface() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function runInteractive(defaults) {
+  const rl = createInterface();
+  try {
+    console.log('\nskill-reyson interactive installer\n');
+    const dirAnswer = await ask(rl, `Target directory [${defaults.dir}]: `);
+    const targetDir = path.resolve(dirAnswer.trim() || defaults.dir);
+
+    const includeAgentAnswer = await ask(rl, 'Install agent guidance files (AGENTS.md / CLAUDE.md / RULES.md)? [y/N]: ');
+    const withAgentFiles = /^y(es)?$/i.test(includeAgentAnswer.trim());
+
+    let agents = [];
+    if (withAgentFiles) {
+      console.log('\nSelect agent adapters (comma-separated numbers):');
+      console.log('  1) Codex -> AGENTS.md');
+      console.log('  2) Claude Code -> CLAUDE.md');
+      console.log('  3) Generic rules -> RULES.md');
+      const agentAnswer = await ask(rl, 'Choice(s) [1]: ');
+      const tokens = (agentAnswer.trim() || '1').split(',').map((s) => s.trim());
+      const mapping = { '1': 'codex', '2': 'claude', '3': 'generic' };
+      agents = normalizeAgents(tokens.map((token) => mapping[token] || token.toLowerCase()));
+      if (agents.length === 0) {
+        agents = ['codex'];
+      }
+    }
+
+    const confirmation = await ask(rl, `\nProceed installing into ${targetDir}? [Y/n]: `);
+    const ok = confirmation.trim() === '' || /^y(es)?$/i.test(confirmation.trim());
+    if (!ok) {
+      console.log('Installation cancelled.');
+      return;
+    }
+
+    const result = performInstall({ targetDir, withAgentFiles, agents });
+    printSummary(result);
+  } finally {
+    rl.close();
+  }
+}
+
+function performInstall({ targetDir, withAgentFiles, agents }) {
+  ensureDir(targetDir);
+  const coreFiles = copyCoreArtifacts(targetDir);
+  const agentFiles = withAgentFiles ? copyAgentFiles(targetDir, normalizeAgents(agents)) : [];
+  return { targetDir, coreFiles, agentFiles };
+}
+
+function printSummary(result) {
+  console.log('\nInstalled skill-reyson scaffold:\n');
+  console.log(`Target: ${result.targetDir}`);
+  console.log('\nCore files:');
+  for (const file of result.coreFiles) {
+    console.log(`  - ${file}`);
+  }
+  if (result.agentFiles.length > 0) {
+    console.log('\nAgent guidance files:');
+    for (const file of result.agentFiles) {
+      console.log(`  - ${file}`);
+    }
+  } else {
+    console.log('\nAgent guidance files: none (default)');
+  }
+  console.log('\nNext steps:');
+  console.log('  1) Open docs/spec-workflow.md');
+  console.log('  2) Ensure your agent knows to read the workflow before coding');
+  console.log('  3) Use generate-task-list and generate-checklist when artifacts are missing');
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv);
+  } catch (error) {
+    console.error(error.message);
+    printHelp();
+    process.exit(1);
+  }
+
+  if (options.command === 'help' || options.command === '--help' || options.command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (options.command !== 'install') {
+    console.error(`Unknown command: ${options.command}`);
+    printHelp();
+    process.exit(1);
+  }
+
+  if (options.yes) {
+    const result = performInstall({
+      targetDir: options.dir,
+      withAgentFiles: options.withAgentFiles,
+      agents: options.agents,
+    });
+    printSummary(result);
+    return;
+  }
+
+  await runInteractive(options);
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/docs/spec-workflow.md

@@ -0,0 +1,171 @@
+# Spec Workflow
+
+This document defines the workflow for spec-driven coding.
+
+Its purpose is to prevent the agent from jumping directly from a user request or a loose spec into implementation without first establishing explicit execution and verification artifacts.
+
+---
+
+## 1. Core principle
+
+Before coding starts, the implementation must be constrained by three artifacts:
+
+1. a working spec
+2. a task list
+3. a checklist
+
+If any required artifact is missing, it must be generated before coding begins.
+
+---
+
+## 2. Pre-coding gate
+
+Before any implementation work, the agent must verify whether the current task already has:
+
+- a clear working spec
+- an explicit task list
+- an explicit checklist
+
+If one or more artifacts are missing, the agent must generate the missing artifacts in the required order.
+
+---
+
+## 3. Required order
+
+### Case A: task list missing and checklist missing
+
+The agent must:
+1. generate or normalize the working spec if needed
+2. generate the task list first
+3. generate the checklist second
+4. assess coding readiness
+5. only then proceed to coding
+
+### Case B: task list exists but checklist missing
+
+The agent must:
+1. validate that the current task list still matches the spec
+2. generate the checklist from the spec and task list
+3. assess coding readiness
+4. only then proceed to coding
+
+### Case C: checklist exists but task list missing
+
+The agent must:
+1. generate the task list first
+2. validate whether the existing checklist still matches the spec and new task list
+3. refine or regenerate the checklist if necessary
+4. assess coding readiness
+5. only then proceed to coding
+
+### Case D: both exist
+
+The agent must:
+1. verify both artifacts still align with the current spec
+2. assess coding readiness
+3. proceed to coding only if no critical ambiguity remains
+
+---
+
+## 4. Working spec requirements
+
+The working spec should be compact but explicit.
+
+It should include:
+- Goal
+- Scope
+- Non-goals
+- Constraints
+- Risks / ambiguities
+
+If a spec already exists, the agent should normalize it instead of rewriting it unnecessarily.
+
+---
+
+## 5. Task list requirements
+
+The task list is the execution plan.
+
+It must:
+- use concrete implementation tasks
+- separate implementation from validation
+- make dependency order visible
+- expose blockers and unresolved decisions
+- be specific enough that each task can be independently checked
+
+Minimum sections:
+- Implementation Tasks
+- Validation Tasks
+- Open Questions / Blockers
+
+---
+
+## 6. Checklist requirements
+
+The checklist is the verification plan.
+
+It must be derived from the working spec and the task list.
+
+It must include:
+- Functional Acceptance
+- Edge Cases
+- Regression Checks
+- Testing
+- Non-functional Checks
+
+Checklist items must be testable, reviewable, or otherwise verifiable.
+
+The checklist must not be a vague rewrite of the task list.
+
+---
+
+## 7. Coding readiness
+
+Coding may begin only when:
+- the spec is clear enough for implementation
+- the task list is explicit
+- the checklist is explicit
+- no critical ambiguity remains
+
+Recommended output:
+- Ready / Not Ready
+- Reason
+- Next action
+
+---
+
+## 8. Post-coding review
+
+After implementation, the agent must revisit the checklist.
+
+Each relevant item should be treated as:
+- completed
+- partially completed
+- not yet verified
+
+The agent should not claim the work is complete if critical checklist items remain unresolved.
+
+---
+
+## 9. Notes for spec workflows without built-in task management
+
+Some spec-first approaches produce a spec or plan without a strong task-management layer.
+
+Examples may include:
+- lightweight planning mode flows
+- open spec style flows
+- antigravity style flows
+- codex plan style flows
+- superpower style flows
+
+For these workflows, the missing task list must be explicitly backfilled before coding.
+
+---
+
+## 10. Summary rule
+
+No coding before:
+1. spec is clear
+2. task list exists
+3. checklist exists
+4. readiness is confirmed

package/examples/example-derived-artifacts.md

@@ -0,0 +1,43 @@
+# Example Derived Artifacts
+
+## Task List
+
+### Implementation Tasks
+- add multi-select state to the task list page
+- add bulk archive action trigger in the UI
+- implement batch archive request handling in the action layer
+- preserve single-task archive behavior
+- surface partial-failure and full-success feedback
+
+### Validation Tasks
+- test archive with one item, multiple items, and zero selected items
+- verify filters and pagination still behave correctly after archive
+- verify existing single-task archive flow still works
+
+### Open Questions / Blockers
+- should archived items disappear immediately or only after refresh?
+
+## Checklist
+
+### Functional Acceptance
+- user can select multiple tasks and archive them in one action
+- success feedback appears after a successful bulk archive
+- failures are visible and do not silently pass
+
+### Edge Cases
+- zero selected items does not trigger archive
+- partial API failure is surfaced clearly
+- archiving items across multiple pages is either supported or explicitly blocked
+
+### Regression Checks
+- single-task archive still works
+- filters remain stable after archive
+- pagination state does not break unexpectedly
+
+### Testing
+- add unit or integration coverage for batch archive behavior
+- verify UI state resets correctly after success and failure
+
+### Non-functional Checks
+- bulk archive does not create duplicate requests
+- loading and error states are observable to the user

package/examples/example-input-spec.md

@@ -0,0 +1,17 @@
+# Example Input Spec
+
+## Goal
+Add a bulk archive action to the task list page.
+
+## Scope
+- allow selecting multiple tasks
+- allow archiving selected tasks in one action
+- show success and error feedback
+
+## Non-goals
+- no permanent delete
+- no redesign of the task page layout
+
+## Constraints
+- preserve existing single-task archive behavior
+- do not break current filters or pagination

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "reyson-spec-gate",
+  "version": "0.1.0",
+  "description": "Interactive installer for a spec-first workflow scaffold with docs, skills, and optional agent guidance files.",
+  "type": "commonjs",
+  "bin": {
+    "skill-reyson": "bin/skill-reyson.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "skills",
+    "templates",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "codex",
+    "agents",
+    "skills",
+    "spec-first",
+    "checklist",
+    "task-list",
+    "workflow"
+  ],
+  "license": "MIT"
+}

package/skills/generate-checklist/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: generate-checklist
+description: Generate an explicit implementation checklist from a working spec and task list before coding. Use when acceptance criteria, edge cases, regression checks, testing scope, or non-functional checks are missing or still implicit in a spec-first workflow.
+---
+
+# Generate Checklist
+
+## Purpose
+
+This skill generates a concrete checklist that constrains implementation and verification before coding begins.
+
+It should be used after the working spec is available and preferably after the task list has been generated or normalized.
+
+## Preferred inputs
+
+Use these inputs in order:
+1. Working spec
+2. Explicit task list
+3. Existing acceptance notes or review notes
+
+If the task list is missing, request or trigger task-list generation first unless the caller explicitly overrides the process.
+
+## Required output
+
+Produce a checklist with these sections:
+- Functional Acceptance
+- Edge Cases
+- Regression Checks
+- Testing
+- Non-functional Checks
+
+## Rules
+
+- Every checklist item must be testable, reviewable, or otherwise verifiable
+- Derive checklist items from actual spec commitments and task-list implications
+- Do not rewrite the task list as vague checklist bullets
+- Include boundary conditions and negative paths when relevant
+- Include migration, compatibility, rollback, observability, performance, security, or documentation checks when relevant
+- Refine generic items until they become implementation-relevant
+
+## Quality bar
+
+A good checklist should:
+- define what “done” really means
+- reduce implementation drift
+- catch omissions before and after coding
+- force attention to edge cases and regressions
+
+## Output template
+
+### Checklist
+
+#### Functional Acceptance
+- ...
+
+#### Edge Cases
+- ...
+
+#### Regression Checks
+- ...
+
+#### Testing
+- ...
+
+#### Non-functional Checks
+- ...

package/skills/generate-task-list/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: generate-task-list
+description: Generate or normalize an explicit task list from a working spec, plan, or user requirement before coding. Use when a spec-first workflow lacks a concrete task list, when an implicit plan needs to be made executable, or when validation tasks and blockers need to be separated clearly.
+---
+
+# Generate Task List
+
+## Purpose
+
+This skill converts a working spec, plan, or user requirement into an explicit task list that can guide implementation safely.
+
+Use it when the workflow has a spec but no concrete task-management layer, or when the existing task list is too vague to support reliable coding.
+
+## Inputs
+
+Prefer these inputs in order:
+1. Working spec
+2. Existing plan or outline
+3. User request and clarified constraints
+
+## Required output
+
+Produce a task list with these sections:
+- Implementation Tasks
+- Validation Tasks
+- Open Questions / Blockers
+
+## Rules
+
+- Use concrete, implementation-relevant tasks
+- Order tasks by execution dependency
+- Split build work from validation work
+- Do not hide ambiguity inside tasks; surface it under blockers or open questions
+- Make each task independently checkable
+- If the input plan is already good, normalize rather than rewrite aggressively
+
+## Quality bar
+
+A good task list should:
+- make coding order obvious
+- expose missing decisions early
+- reduce the chance of skipping validation
+- be specific enough that another agent could execute from it
+
+## Output template
+
+### Task List
+
+#### Implementation Tasks
+- ...
+
+#### Validation Tasks
+- ...
+
+#### Open Questions / Blockers
+- ...

package/templates/adapters/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md
+
+## Spec-first workflow rules
+
+Before any implementation task, read `docs/spec-workflow.md`.
+
+Before coding begins, verify whether the current work includes:
+- an explicit task list
+- an explicit checklist
+
+If the task list is missing, generate it first.
+If the checklist is missing, generate it second.
+If both are missing, generate both before coding.
+
+Do not begin implementation until the pre-coding gate is satisfied.
+After coding, revisit the checklist before claiming completion.

package/templates/adapters/CLAUDE.md

@@ -0,0 +1,16 @@
+# CLAUDE.md
+
+## Spec-first workflow rules
+
+Before any implementation task, read `docs/spec-workflow.md`.
+
+Before coding begins, verify whether the current work includes:
+- an explicit task list
+- an explicit checklist
+
+If the task list is missing, generate it first.
+If the checklist is missing, generate it second.
+If both are missing, generate both before coding.
+
+Do not begin implementation until the pre-coding gate is satisfied.
+After coding, revisit the checklist before claiming completion.

package/templates/adapters/RULES.md

@@ -0,0 +1,16 @@
+# RULES.md
+
+## Spec-first workflow rules
+
+Before any implementation task, read `docs/spec-workflow.md`.
+
+Before coding begins, verify whether the current work includes:
+- an explicit task list
+- an explicit checklist
+
+If the task list is missing, generate it first.
+If the checklist is missing, generate it second.
+If both are missing, generate both before coding.
+
+Do not begin implementation until the pre-coding gate is satisfied.
+After coding, revisit the checklist before claiming completion.