spec-driven-steroids: Instructions file for Codex

AGENTS.md

Project Identity

This is Spec-Driven Steroids (spec-driven-steroids), a CLI tool and template bundle that injects approval-gated brief and full Spec-Driven workflows into AI coding tools. It ships as a single public npm package with a sds alias.

Technology Stack

• Language: TypeScript 5.9, ES2022 target, NodeNext modules, strict mode
• Runtime: Node.js >=20
• Package Manager: pnpm 10 (workspace monorepo)
• CLI: Commander.js 11 + Inquirer 9 + Chalk 5
• Testing: Vitest 2.x with v8 coverage
• Build: tsc (no bundler)
• Publishing: Changesets → npm (with provenance)

See ARCHITECTURE.md for system boundaries and STYLEGUIDE.md for code conventions.

Essential Commands

pnpm build          # Build all packages
pnpm test           # Run all tests (requires prior build)
pnpm typecheck      # Type-check all packages (no emit)
pnpm lint           # Lint all packages
pnpm test:coverage  # Run tests with coverage
pnpm changeset      # Create a changeset entry

When writing code here, always run pnpm typecheck before considering a change complete.

Agent Constraints

• Code comments policy: Add code comments only when they are highly necessary to explain non-obvious intent, workarounds, or critical constraints. Do not add comments that merely restate what the code does.
• Import style: Use ES module imports only. All packages are "type": "module". Use .js extensions in relative imports (TypeScript resolves them correctly).
• Source layout: The CLI source lives in packages/cli/src/. Tests live in packages/cli/tests/ (not co-located). Shared test utilities are in packages/test-utils/src/.
• Build before test: Integration tests import from dist/, so pnpm build (or tsc) must run before pnpm test.
• Package scope: The packages/cli package is the only public package. packages/test-utils and packages/landing-page are private.
• Platform template changes: When editing template files under packages/cli/templates/, ensure corresponding E2E tests in packages/cli/tests/integration/ are updated because many tests verify template content assertions.
• Template source: When adding or modifying template files, update STEROIDS_SKILL_DIRS and STEROIDS_FILES in packages/cli/src/cli/index.ts if the new files must be tracked for clean and injection.
• Approval-gated SDS invocation: When SDS is selected, implementation must follow an approved brief.md or the approved full flow (requirements → design → tasks → implementation). Direct implementation belongs to the host harness outside SDS. See CONTRIBUTING.md for the PR process.
• Spec artifact exclusion: Never read .specs/changes/<slug>/ artifacts (brief.md, requirements.md, design.md, tasks.md) as context for any task unless:
  • You are explicitly in a spec-driven workflow for that specific <slug>, OR
  • The user explicitly references or asks about that specific spec artifact
  • Treat spec artifacts as ephemeral snapshots of past intent — they do not reflect current codebase state and must never be used as implementation reference outside their own spec-driven flow.