AI-assisted specification and implementation system for software development.
IDEA → spec → architecture → stories → implementation → review
codewright orchestrates the full software development lifecycle through AI agents:
- Spec — Capture your idea, goals, and constraints
- Architecture — Design decisions and system structure
- Stories — Break down capabilities into implementable tasks
- Dev — Implement with TDD (RED → GREEN → REFACTOR)
- Review — Parallel code review with specialized agents
It supports Codex, Claude Code, Gemini CLI, GitHub Copilot, OpenCode, Windsurf, Cline, and Cursor from one canonical skill set.
npm install -g codewrightOr use directly with npx:
npx codewright initnpx codewright initIn an interactive terminal, choose one or more agents or select all. For automation:
npx codewright init --agents claude,cursor
npx codewright init --agents all
npx codewright init --agents coreWithout an interactive terminal or --agents, Codewright installs the universal .agents/skills core only.
After init, talk to the agent:
| You say | The agent does |
|---|---|
$codewright-spec |
Creates a specification from your idea |
$codewright-architecture |
Generates architecture decisions |
$codewright-epic |
Breaks spec into epics and stories |
$codewright-story |
Creates stories with I/O Matrix |
$codewright-develop |
Orchestrates readiness → dev → quality → test → review |
$codewright-quality |
Analyzes maintainability with evidence |
$codewright-review |
Reviews a story against its contract |
$codewright-commit |
Previews and creates a scoped local commit |
$codewright-test |
Designs and implements meaningful tests |
$codewright-testgen |
Scaffolds TODO tests from story scenarios |
$codewright-perf |
Designs and analyzes approved performance tests |
| Agent | Native invocation | Installation |
|---|---|---|
| Codex | $codewright-spec |
Universal core |
| Claude Code | /codewright-spec |
.claude/skills adapter |
| Gemini CLI | Natural request / automatic | Universal core |
| GitHub Copilot | /codewright-spec or automatic |
Universal core |
| OpenCode | Automatic | Universal core |
| Windsurf | @codewright-spec |
Universal core |
| Cline | Automatic | .cline/skills adapter |
| Cursor | /codewright-spec |
.cursor/commands adapter |
The adapters are small generated pointers. The workflow remains canonical in .agents/skills, so agent-specific copies cannot drift.
Skills follow the Agent Skills naming standard. Explicit invocation syntax varies by agent as shown above; legacy phrases such as codewright:spec remain recognized by the skill descriptions.
codewright spec my-feature # create spec
codewright story my-feature S001 "Login" # create story
codewright dev my-feature S001 # start implementation
codewright review my-feature S001 # prepare review
codewright commit my-feature S001 # commit to feature branch
codewright status # project health
codewright help # list all skills by phaseRunning npx codewright init creates:
your-project/
├── AGENTS.md # Discoverable project guidance (created only if absent)
├── .codewright/
│ ├── config.yaml # Auto-detected stack & settings
│ ├── agents.yaml # Selected agent targets
│ ├── config.user.yaml # Your personal overrides (gitignored)
│ └── custom/ # Per-skill customization
├── .agents/skills/ # 25 AI agent skills
│ ├── codewright-spec/
│ ├── codewright-story/
│ ├── codewright-dev/
│ └── ... (22 more)
├── .claude/skills/ # Optional generated Claude adapters
├── .cline/skills/ # Optional generated Cline adapters
├── .cursor/commands/ # Optional generated Cursor commands
└── .codewright-output/ # Generated artifacts
└── project-context.md # Auto-generated project context
Auto-detection: The init command detects your framework, test runner, lint tools, and TypeScript strict mode from package.json and tsconfig.json.
npx codewright spec my-featurenpx codewright story my-feature S001 "Create user form"npx codewright dev my-feature S001Implement multiple stories faster using parallel subagents:
# Implement all pending stories in parallel (up to 4 concurrent)
npx codewright develop my-feature --parallel
# Specific stories
npx codewright develop my-feature --stories S001,S002,S003
# Sequential (for stories with dependencies)
npx codewright develop my-feature --sequential
# Adjust max concurrent agents
npx codewright develop my-feature --max 8
# Spawn agents when creating a story
npx codewright story my-feature S001 "Login" --spawn --parallelEach subagent follows the TDD cycle (RED → GREEN → REFACTOR) independently and reports back when done.
npx codewright review my-feature S001| Command | Description |
|---|---|
codewright init |
Initialize project with skills and config |
codewright init --agents <list> |
Initialize for selected agents (all or comma-separated) |
codewright init --agents core |
Install only the universal Agent Skills core |
codewright spec <slug> |
Create a new specification |
codewright spec <slug> --update |
Re-derive SPEC.md from memlog |
codewright spec <slug> --input <file> |
Seed spec from existing document |
codewright spec <slug> --history |
View spec version history |
codewright spec <slug> --snapshot |
Create a version snapshot |
codewright spec <slug> --diff [from] |
Diff between spec versions |
codewright spec <slug> --sync |
Sync spec with code (compare requirements vs implementation) |
codewright story <spec> |
List stories for a spec |
codewright story <spec> <id> "<title>" |
Create a story |
codewright story <spec> --spawn [--parallel] |
Spawn agents for pending stories |
codewright develop <spec> [--parallel] [--sequential] |
Orchestrate stories with parallel subagents |
codewright develop <spec> --stories S001,S002 |
Develop specific stories |
codewright develop <spec> --max <n> |
Max concurrent agents (default: 4) |
codewright dev <spec> <id> |
Start implementing a story |
codewright review <spec> <id> |
Prepare code review |
codewright commit <spec> <id> --dry-run |
Preview a story-scoped commit |
codewright commit <spec> <id> --yes [--push] |
Create a local commit; push only when requested |
codewright perf [setup|run] [k6|artillery] |
Performance testing with k6 |
codewright context |
Regenerate project context |
25 AI-powered skills installed automatically:
| Skill | Description |
|---|---|
$codewright-spec |
Create traceable specifications from ideas |
$codewright-architecture |
Design architecture decisions |
$codewright-epic |
Break specs into value-oriented epics and stories |
$codewright-story |
Create implementation-ready stories |
$codewright-develop |
Orchestrate gated multi-story development |
$codewright-dev |
Implement a single story with TDD |
$codewright-review |
Review a story against its baseline and contract |
$codewright-commit |
Create a safe story-scoped commit |
$codewright-readiness |
Check if a story is ready to implement |
| Skill | Description |
|---|---|
$codewright-quality |
Analyze maintainability with evidence |
$codewright-test |
Design and implement meaningful tests |
$codewright-testgen |
Scaffold TODO tests from I/O Matrix rows |
$codewright-refactor |
Improve structure while preserving behavior |
$codewright-quick-dev |
Fix small reproducible bugs |
$codewright-document |
Generate verified code and API documentation |
$codewright-retrospective |
Turn delivery evidence into actions |
$codewright-perf |
Design, run, and analyze approved load tests |
$codewright-rules |
Manage scoped project rules |
$codewright-init |
Safely initialize or upgrade Codewright |
| Skill | Description |
|---|---|
$codewright-context |
Refresh safe AI-readable project context |
$codewright-ci |
Generate and harden GitHub Actions CI |
$codewright-deps |
Audit dependency freshness and vulnerabilities |
$codewright-env |
Validate environment setup without revealing values |
$codewright-deploy |
Generate secure Docker configuration |
$codewright-hook |
Install, inspect, or remove Git hooks safely |
Skills are .agents/skills/<name>/SKILL.md files following the open Agent Skills format. Agents with native .agents/skills support load them directly. Claude, Cline, and Cursor use generated adapters that point back to the same canonical files. When you request "codewright spec", the selected agent loads the workflow and its resources only when needed.
Specs are not static documents — they evolve with your code:
codewright spec my-feature --history # View version history
codewright spec my-feature --snapshot # Create version snapshot
codewright spec my-feature --diff # Compare versions
codewright spec my-feature --sync # Check requirements vs implementationKeep project-specific rules in .codewright/rules/. These rules are automatically loaded by codewright skills during development.
.codewright/
├── rules/
│ ├── DEFAULT.md # Main rules file
│ ├── testing.md # Testing rules
│ └── style.md # Code style rules
# .codewright/config.yaml (project settings)
project_name: my-app
stack: node
framework: next
test_runner: vitest
communication_language: en
# .codewright/config.user.yaml (your overrides, gitignored)
# Override any field here# .codewright/custom/codewright-dev.toml
[workflow]
tdd_mode = true
auto_commit = false.codewright-output/
├── project-context.md
└── specs/
└── spec-my-feature/
├── .memlog.md # Decision log
├── SPEC.md # Specification
├── architecture.md # Architecture decisions
├── stories/
│ ├── S001-create-form.md
│ └── S002-add-validation.md
└── reviews/
└── review-S001.md
git clone https://github.com/codewright/codewright.git
cd codewright
npm install
npm run build
npm testMIT
Contributions welcome! Please open an issue or PR.