|
1 | | -# AGENTS.md |
2 | | - |
3 | | -> AI agent guidance, constraints, and high-level repository context for Spec-Driven Steroids. |
4 | | -
|
5 | 1 | <!-- SpecDriven:managed:start --> |
6 | 2 |
|
7 | | -## Technology Stack |
8 | | - |
9 | | -| Aspect | Tool/Version | |
10 | | -|--------|--------------| |
11 | | -| Runtime | Node.js >=20 | |
12 | | -| Package Manager | pnpm 10.29 | |
13 | | -| Language | TypeScript 5.9 (ESM) | |
14 | | -| Testing | Vitest 2.1.0 | |
15 | | -| CLI Framework | Commander 11.1 | |
16 | | -| Release | Changesets | |
17 | | - |
18 | | -## Build Commands |
19 | | - |
20 | | -```bash |
21 | | -# Install dependencies |
22 | | -pnpm install |
23 | | - |
24 | | -# Build all packages |
25 | | -pnpm build |
26 | | - |
27 | | -# Run all tests |
28 | | -pnpm test |
29 | | - |
30 | | -# Type check all packages |
31 | | -pnpm typecheck |
32 | | - |
33 | | -# Lint all packages |
34 | | -pnpm lint |
35 | | -``` |
36 | | - |
37 | | -## Agent Constraints |
| 3 | +# AGENTS.md |
38 | 4 |
|
39 | | -### Code Comments Policy |
| 5 | +## Project Identity |
40 | 6 |
|
41 | | -Add code comments only when they are highly necessary to explain: |
42 | | -- Non-obvious intent |
43 | | -- Workarounds for platform or library limitations |
44 | | -- Critical constraints or edge case handling |
| 7 | +This is **Spec-Driven Steroids** (`spec-driven-steroids`), a CLI tool and template bundle that injects a strict Spec-Driven Development workflow (requirements → design → tasks → implementation) into AI coding tools. It ships as a single public npm package with a `sds` alias. |
45 | 8 |
|
46 | | -Avoid verbose comments for self-documenting code. |
| 9 | +## Technology Stack |
47 | 10 |
|
48 | | -### Working Directory |
| 11 | +- **Language**: TypeScript 5.9, ES2022 target, NodeNext modules, strict mode |
| 12 | +- **Runtime**: Node.js >=20 |
| 13 | +- **Package Manager**: pnpm 10 (workspace monorepo) |
| 14 | +- **CLI**: Commander.js 11 + Inquirer 9 + Chalk 5 |
| 15 | +- **Testing**: Vitest 2.x with v8 coverage |
| 16 | +- **Build**: `tsc` (no bundler) |
| 17 | +- **Publishing**: Changesets → npm (with provenance) |
49 | 18 |
|
50 | | -All file operations are relative to the repository root. Use explicit paths when working with package-specific code. |
| 19 | +See [ARCHITECTURE.md](ARCHITECTURE.md) for system boundaries and [STYLEGUIDE.md](STYLEGUIDE.md) for code conventions. |
51 | 20 |
|
52 | | -### Project Structure |
| 21 | +## Essential Commands |
53 | 22 |
|
| 23 | +```bash |
| 24 | +pnpm build # Build all packages |
| 25 | +pnpm test # Run all tests (requires prior build) |
| 26 | +pnpm typecheck # Type-check all packages (no emit) |
| 27 | +pnpm lint # Lint all packages |
| 28 | +pnpm test:coverage # Run tests with coverage |
| 29 | +pnpm changeset # Create a changeset entry |
54 | 30 | ``` |
55 | | -packages/ |
56 | | -├── cli/ # Main CLI and injection logic |
57 | | -│ └── src/ |
58 | | -│ ├── cli/ # Injection commands (index.ts, transformation-pipeline.ts) |
59 | | -│ ├── core/validate/ # Validation modules (requirements, design, tasks, structure) |
60 | | -│ └── context-stewardship/ # Knowledge graph system |
61 | | -├── test-utils/ # Shared test fixtures and MockFileSystem |
62 | | -└── landing-page/ # Documentation site |
63 | | -``` |
64 | | - |
65 | | -## Supported Platforms |
66 | | - |
67 | | -The CLI injects into: Antigravity, Claude Code, Gemini CLI, GitHub Copilot CLI, GitHub Copilot (VS Code, JetBrains), OpenCode, OpenAI Codex, Qwen Code. |
68 | 31 |
|
69 | | -## Validation Commands |
| 32 | +When writing code here, always run `pnpm typecheck` before considering a change complete. |
70 | 33 |
|
71 | | -| Command | Purpose | |
72 | | -|---------|---------| |
73 | | -| `sds validate structure` | Validate spec folder structure | |
74 | | -| `sds validate requirements` | Validate EARS requirements | |
75 | | -| `sds validate design` | Validate design and Mermaid diagrams | |
76 | | -| `sds validate tasks` | Validate tasks and traceability | |
77 | | -| `sds validate spec` | Full end-to-end validation | |
| 34 | +## Agent Constraints |
78 | 35 |
|
79 | | -See [TESTING.md](TESTING.md) for test commands and patterns. |
| 36 | +- **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. |
| 37 | +- **Import style**: Use ES module imports only. All packages are `"type": "module"`. Use `.js` extensions in relative imports (TypeScript resolves them correctly). |
| 38 | +- **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/`. |
| 39 | +- **Build before test**: Integration tests import from `dist/`, so `pnpm build` (or `tsc`) must run before `pnpm test`. |
| 40 | +- **Package scope**: The `packages/cli` package is the only public package. `packages/test-utils` and `packages/landing-page` are private. |
| 41 | +- **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. |
| 42 | +- **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. |
| 43 | +- **No direct implementation requests**: Agents must never skip the Spec-Driven phases. Implementation must always follow the full flow (`requirements → design → tasks → implementation`). See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR process. |
80 | 44 |
|
81 | 45 | <!-- SpecDriven:managed:end --> |
82 | | - |
83 | | -## See Also |
84 | | - |
85 | | -- [CONTRIBUTING.md](CONTRIBUTING.md) - PR process and git workflow |
86 | | -- [TESTING.md](TESTING.md) - Testing strategy and patterns |
87 | | -- [STYLEGUIDE.md](STYLEGUIDE.md) - Code conventions |
0 commit comments