Agent Spec Mini CLI

A small TypeScript CLI prototype for turning a rough software idea into an initial Agent Spec draft.

This project is an early learning-oriented slice of a larger idea: Agent Spec Studio, a requirements clarification layer for agentic software development workflows such as Codex, Claude Code, Cursor, Kiro, and GitHub Spec Kit.

The long-term goal is to help users transform vague product ideas into structured, executable, and verifiable software specifications that can be handed to a human developer or a Coding Agent.

Current Features

• Parses a project idea from CLI arguments
• Builds a typed AgentSpec draft from a ProjectIdea
• Estimates a simple risk level
• Generates clarifying questions
• Formats the spec as Markdown
• Prints Markdown to the terminal
• Optionally writes Markdown to a file with --out

Requirements

• Node.js 20 or newer recommended
• npm

Install

npm install

Usage

Show usage:

npm run dev

or:

npm run dev -- --help

Generate a spec and print it to the terminal:

npm run dev -- "Todo CLI" "A CLI for helping students manage homework" "A lightweight task tool for students"

Generate a spec and write it to a Markdown file:

npm run dev -- "Todo CLI" "A CLI for helping students manage homework" "A lightweight task tool for students" --out spec.md

Scripts

npm run dev
npm run typecheck
npm run build
npm start

Project Structure

src/
  index.ts        CLI entry point
  input.ts        CLI argument parsing
  types.ts        Core TypeScript types
  specBuilder.ts  ProjectIdea -> AgentSpec draft logic
  formatter.ts    AgentSpec -> Markdown formatting

Example Output

# Todo CLI

## Summary
A lightweight task tool for students

## Risk Level
medium

## Goals
- TODO: add goal

## Clarifying Questions
- 你的项目的标题应该如何命名？
- 你的项目的目标用户是哪些人？
- 你的项目的验收标准有哪些？

Roadmap

• Detect product type
• Generate richer follow-up questions
• Identify missing requirements and contradictions
• Generate development tasks
• Generate acceptance criteria
• Export specs for Coding Agent workflows
• Support richer output formats

License

MIT is a reasonable license choice for this project if you want others to freely use, modify, and build on it with minimal restrictions.