Skip to content

Ogekuri/useReq

BranchesTags

Repository files navigation

useReq/req (0.56.0)

Python 3.11+ License: GPL-3.0 Platforms Docs uv

The req script provides CLI prompts for requirements-driven software development.
The defined prompts are exposed as /req- commands within various CLIs and Agents.
This allows them to be run both as a Python package (installed as req, usereq, or use-req) and directly using uvx.

Quick Start | Feature Highlights | Prompts and Agents | Default Workflow | Supported CLIs, Agents, and Extensions | Known Issues | Legacy Mode


🚧 DRAFT: 👾 Alpha Development 👾 - Work in Progress 🏗️ 🚧
⚠️ IMPORTANT NOTICE: Created with useReq/req 🤖✨ ⚠️

Requirements

  • Astral uv tool is required to run scripts/req.sh and project CLI workflows.
  • When needed, you can generate a requirements.txt file with uv export --format requirements-txt > requirements.txt.
  • Supported environment: linux
  • Python 3.11+

Feature Highlights

  • You will no longer need to read the codebase.
  • It stops the Agent from asking more questions and makes it just do it.
  • Drives development through requirement changes.
  • Keeps development under control.
  • Usable as skills, or agents, or prompts.
  • Creates a common interface for different vendor CLIs and Agents.
  • Creates Software Requirements Specification [SRS] file, optimized for LLM Agents, for new or existing projects.
  • Keeps source code documentation updated and optimized for LLM Agents reasoning.
  • Optimized credits usage.
  • Use git worktree to parallelize tasks (only on clean git repositories)
  • Provide source-code analysis tool, that supports different programming languages: Python, C, C++, C#, Rust, JavaScript, TypeScript, Java, Go, Ruby, PHP, Swift, Kotlin, Scala, Lua, Shell, Perl, Haskell, Zig, Elixir.
  • Support static-code analysis with Pylance, Ruff or customizable Command-Line commands.
  • Support customizable guidelines.
  • Supports Conventional Commit Standards and is compatible with release-changelog-builder-action.
  • Compatible with G/Git-Alias CLI.

Prompts and Agents

Prompt Description
write Produce a SRS draft based on the User Request description
create Write a Software Requirements Specification using the project's source code
recreate Reorganize and update the Software Requirements Specification based on source code analysis (preserve requirement IDs)
renumber Deterministically renumber requirement IDs in the Software Requirements Specification without changing requirement text or order
analyze Produce an analysis report
change Update the requirements and implement the corresponding changes
check Run the requirements check
cover Implement minimal changes to cover uncovered existing requirements
fix Fix a defect without changing the requirements
implement Implement source code from requirements (from scratch)
new Implement a new requirement and the corresponding source code changes
refactor Perform a refactor without changing the requirements
readme Write README.md from user-visible implementation evidence
references Write a REFERENCES.md using the project's source code
workflow Write a WORKFLOW.md using the project's source code

Default Workflow

Click to zoom flowchart image.

Flowchart

Quick Start

Prerequisites

Project's Tree

Here the typical project's tree, except for .req directory you can configurare the other directories according your project layout:

.
├── .req/
│   └── useReq/req files
├── docs/
│   ├── REQUIREMENTS.md
│   ├── REFERENCES.md
│   └── WORKFLOW.md
├── guidelines/
│   └── User's guidelines
├── src/
│   └── Source code
└── tests/
    └── Unit tests suite

Run useReq/req with uvx

uvx --from git+https://github.com/Ogekuri/useReq.git req \
  --base myproject/ \
  --docs-dir myproject/docs/ \
  --guidelines-dir myproject/guidelines_docs/ \
  --tests-dir myproject/tests/ \
  --src-dir myproject/src/ \
  --provider codex:prompts \
  --verbose --debug

Install/Uninstall useReq/req with uv

Install

uv tool install usereq --force --from git+https://github.com/Ogekuri/useReq.git

Uninstall

uv tool uninstall usereq

Quick Install

  1. Install on a project in path project_path, where docs/, guidelines/, src/, and tests/ already created:
  • Typical Install:
req \
--base "project_path" --docs-dir "docs/" --guidelines-dir "guidelines/" \
--src-dir "src/" --tests-dir "tests/" \
--provider claude:prompts,agents,skills \
--provider codex:prompts \
--provider github:prompts,agents,skills
  • Full-Features Install:
req \
--base "project_path" --docs-dir "docs/" --guidelines-dir "guidelines/" \
--src-dir "src/" --tests-dir "tests/" \
--upgrade-guidelines \
--provider claude:prompts,agents,skills:enable-models,enable-tools \
--provider codex:prompts,skills \
--provider gemini:prompts,skills \
--provider github:prompts,agents,skills:enable-models,enable-tools \
--provider kiro:prompts,agents,skills:enable-models,enable-tools \
--provider opencode:prompts,agents,skills:enable-models,enable-tools \
--enable-static-check C=Command,cppcheck,--error-exitcode=1,\"--enable=warning,style,performance,portability\",--std=c11 \
--enable-static-check C=Command,clang-format,--dry-run,--Werror \
--enable-static-check C++=Command,cppcheck,--error-exitcode=1,\"--enable=warning,style,performance,portability\",--std=c++20 \
--enable-static-check C++=Command,clang-format,--dry-run,--Werror \
--enable-static-check Python=Pylance \
--enable-static-check Python=Ruff
  1. Use /req-write or /req-create to create requirements
  2. Use /req-implement to implement source-code from requirements, or /req-cover to cover new requirements (documentation).
  3. Use /req-workflow and/or /req-references to update project's documentation.
  4. Star to use /req-change, /req-new, and /req-fix.

Usage

  • Run req to create or recreate useReq resources in your project repository (depending on enabled providers and artifact types). This can include: .codex, .claude, .github, .gemini, .kiro, .opencode, .req, and .vscode.
    • You can run req from any directory:
      • Use --base <project-folder> to target a specific project directory.
      • Use --here to target the current working directory as the project root.
      • If you run it from inside the project directory, use --here (you cannot omit both --base and --here for initialization); you must still provide --guidelines-dir, --docs-dir, --tests-dir, and --src-dir (all must exist under the project base) unless you use --update.
    • --docs-dir is the requirements documentation directory (must exist under the project base); if it is empty, REQUIREMENTS.md is generated from the packaged template.
    • --guidelines-dir must be an existing directory under the project base, and can contain the user's guideline files.
    • --src-dir is repeatable and can be provided multiple times to include multiple source directories (each must exist under the project base).
    • Use one or more --provider SPEC parameters (at least one is required) to configure provider activation, artifact types, and options:
      • SPEC format: PROVIDER:ARTIFACTS[:OPTIONS]
      • PROVIDER: codex, claude, gemini, github, kiro, or opencode.
      • ARTIFACTS: comma-separated list from {prompts, agents, skills}.
      • OPTIONS: (optional) comma-separated list from {enable-models, enable-tools, prompts-use-agents, legacy}.
      • Example: --provider github:prompts,agents:enable-models,enable-tools
    • Artifact types (specified within the --provider spec):
      • skills artifact generates skill resources for the provider.
      • prompts artifact generates prompts/commands resources for the provider.
      • agents artifact generates agent resources for the provider.
    • --enable-static-check SPEC Enable static check configuration for a language (repeatable). SPEC format: LANG=MODULE[,CMD[,PARAM...]].
      • Supported MODULE values: Dummy, Pylance, Ruff, Command (case-insensitive).
      • Entries are merged into .req/config.json without replacing existing ones: existing entries are preserved, identity-duplicates are ignored, and only new non-duplicate entries are appended per language.
  • You need to run req again if you add or remove requirement-related files in the documentation directory or any files in the guidelines/ directory.
  • Option prompts-use-agents (within a --provider spec) generates prompt files as agent-only references (adds an agent: front matter field) where supported (GitHub prompts, Claude commands, and OpenCode commands).
  • Add --verbose and --debug to get detailed and diagnostic output.
  • Add --update to update an existing installation (requires an existing .req/config.json under the project base).
    • Add --preserve-models to use and preserve .req/models.json during installation.
  • Option legacy (within a --provider spec) enables the legacy mode support (see below).
  • Options enable-models and enable-tools (within a --provider spec) include model: and tools: fields when available from centralized models configuration.
  • Add --add-guidelines to copy packaged guideline templates into --guidelines-dir without overwriting existing files.
  • Add --upgrade-guidelines to copy packaged guideline templates into --guidelines-dir and overwrite existing files.
  • Add -h / --help to print command help and exit.
  • Add --ver / --version to print the installed package version and exit.
  • Add --remove to remove resources generated by useReq from the target project (requires --base or --here and an existing .req/config.json; removes .req/ and generated provider artifacts).
  • Add --upgrade to self-upgrade useReq via uv.
  • Add --uninstall to uninstall useReq via uv.

Embedded Utility

  • Count tokens and chars for the given files (standalone, no --base/--here required). --files-tokens FILE [FILE ...]

  • Generate LLM reference markdown for the given files (standalone, no --base/--here required). --files-references FILE [FILE ...]

  • Generate compressed output for the given files (standalone, no --base/--here required).
    --files-compress FILE [FILE ...]

  • Find and extract specific constructs from the given files (standalone, no --base/--here required). --files-find TAG PATTERN FILE [FILE ...]

  • Run static analysis on the given files using tools configured in .req/config.json (standalone, no --base/--here required). --files-static-check FILE [FILE ...]

  • Count tokens and chars for files directly under configured docs-dir (here-only project scan: --here is implied when omitted, --base is not allowed, and explicit --docs-dir is ignored). --tokens

  • Generate LLM reference markdown for git-tracked source files under configured src-dir directories (here-only project scan: --here is implied when omitted, --base is not allowed). --references

  • Generate compressed output for git-tracked source files under configured src-dir directories (here-only project scan: --here is implied when omitted, --base is not allowed).
    --compress

  • Find and extract specific constructs from git-tracked source files under configured src-dir directories (here-only project scan: --here is implied when omitted, --base is not allowed). --find TAG PATTERN

  • Run static analysis on git-tracked source files under configured src-dir directories using tools configured in .req/config.json (here-only project scan: --here is implied when omitted, --base is not allowed). --static-check

  • Check repository integrity for the configured git path: clean working tree and valid HEAD (here-only project scan: --here is implied when omitted, --base is not allowed). --git-check

  • Check canonical docs presence in configured docs-dir: REQUIREMENTS.md, WORKFLOW.md, REFERENCES.md (here-only project scan: --here is implied when omitted, --base is not allowed). --docs-check

  • Create an isolated git worktree and branch with the provided name; also copies .req/ and active provider directories into the new worktree context (here-only project scan: --here is implied when omitted, --base is not allowed). --git-wt-create WT_NAME

  • Remove the git worktree and branch identified by name (here-only project scan: --here is implied when omitted, --base is not allowed). --git-wt-delete WT_NAME

  • Print the configured git-path value from .req/config.json; if .req/config.json is missing, the command fails with Error: .req/config.json not found in the project root (here-only project scan: --here is implied when omitted, --base is not allowed). --git-path

  • Print the configured base-path value from .req/config.json; if .req/config.json is missing, the command fails with Error: .req/config.json not found in the project root (here-only project scan: --here is implied when omitted, --base is not allowed). --get-base-path

  • Add --enable-line-numbers to include <n>: prefixes in --files-compress, --compress, --files-find, and --find output.

  • Test static check configuration and execution (standalone). --test-static-check {dummy,pylance,ruff,command} [FILES...]

Supported in --find commands

  • Python: CLASS, FUNCTION, DECORATOR, IMPORT, VARIABLE
  • C: STRUCT, UNION, ENUM, TYPEDEF, MACRO, FUNCTION, IMPORT, VARIABLE
  • C++: CLASS, STRUCT, ENUM, NAMESPACE, FUNCTION, MACRO, IMPORT, TYPE_ALIAS
  • C#: CLASS, INTERFACE, STRUCT, ENUM, NAMESPACE, FUNCTION, PROPERTY, IMPORT, DECORATOR, CONSTANT
  • Rust: FUNCTION, STRUCT, ENUM, TRAIT, IMPL, MODULE, MACRO, CONSTANT, TYPE_ALIAS, IMPORT, DECORATOR
  • JavaScript: CLASS, FUNCTION, COMPONENT, CONSTANT, IMPORT, MODULE
  • TypeScript: INTERFACE, TYPE_ALIAS, ENUM, CLASS, FUNCTION, NAMESPACE, MODULE, IMPORT, DECORATOR
  • Java: CLASS, INTERFACE, ENUM, FUNCTION, IMPORT, MODULE, DECORATOR, CONSTANT
  • Go: FUNCTION, METHOD, STRUCT, INTERFACE, TYPE_ALIAS, CONSTANT, IMPORT, MODULE
  • Ruby: CLASS, MODULE, FUNCTION, CONSTANT, IMPORT, DECORATOR
  • PHP: CLASS, INTERFACE, TRAIT, FUNCTION, NAMESPACE, IMPORT, CONSTANT
  • Swift: CLASS, STRUCT, ENUM, PROTOCOL, EXTENSION, FUNCTION, IMPORT, CONSTANT, VARIABLE
  • Kotlin: CLASS, INTERFACE, ENUM, FUNCTION, CONSTANT, VARIABLE, MODULE, IMPORT, DECORATOR
  • Scala: CLASS, TRAIT, MODULE, FUNCTION, CONSTANT, VARIABLE, TYPE_ALIAS, IMPORT
  • Lua: FUNCTION, VARIABLE
  • Shell: FUNCTION, VARIABLE, IMPORT
  • Perl: FUNCTION, MODULE, IMPORT, CONSTANT
  • Haskell: MODULE, TYPE_ALIAS, STRUCT, CLASS, FUNCTION, IMPORT
  • Zig: FUNCTION, STRUCT, ENUM, UNION, CONSTANT, VARIABLE, IMPORT
  • Elixir: MODULE, FUNCTION, PROTOCOL, IMPL, STRUCT, IMPORT

Supported CLIs, Agents, and Extensions

High-Level Assessment

  • 🌟 GitHub Copilot 🌟 - Many models available
  • 👍 OpenCode 👍 - Many models available. Does not support tools: on agents/prompts.
  • ⚖️ Claude Code ⚖️ - Only supports Claude/Anthropic models.
  • 🆗 OpenAI Codex 🆗 - Only supports OpenAI models. Does not support agents, model:, or tools: on prompts.
  • 👎 Kiro CLI 👎 - Only supports Claude/Anthropic models. Does not support $ARGUMENTS on prompts.
  • ☢️ Gemini Code Assist ☢️ - Only supports Google models. Does not support agents, model:, or tools:. VS Code extension does not support agents or prompts.

useReq/req Support

  • ✅ OpenAI Codex
    • set environment variable CODEX_HOME to project's home before running the codex CLI
  • ✅ Claude Code
  • ✅ GitHub Copilot
  • ✅ OpenCode
  • ✔️ Gemini Code Assist
  • ✔️ Kiro CLI

| ✅ supported | ✔️ partially supported | ❌ issues | ⛔ not supported |

Skills Details

  • ✅ OpenAI Codex: [$req-create]
  • ✅ Claude Code: [/req-create]
  • ✅ GitHub Copilot: [/req-create]
  • ✅ OpenCode: [/req-create]
  • ✅ Gemini: [$req-create]
  • ❌ Kiro: Does not work as expected

CLI Prompt Details

CLI Agents Details

  • ❌ OpenAI Codex
  • ✅ Claude Code: [@agent-req-create]
  • ❌ GitHub Copilot
  • ✔️ OpenCode: [<TAB> ➡️ Req.Create ↩️]
    • Starts a new session (/new) for every prompt.
  • ✔️ Kiro: [/agent swap; select agent ➡️ /req-create; ↩️]
    • Does not work as expected
    • Clears the context (/clear) for every prompt.

Visual Studio Code Extension Details

  • ✅ OpenAI Codex Extension for Visual Studio Code
    • Skills: [/ ➡️ Req.Create ↩️]
    • Prompts: [/prompts:/req-create]
    • set environment variable CODEX_HOME to project's home before running VS Code
  • ✅ Claude Extension for Visual Studio Code
    • Skills: [/req-create]
    • Prompts: [@agent-req-create] (does not highlight agent like the CLI)
  • ✔️ GitHub Copilot Agent Chat in Visual Studio Code
    • Agents: [gui; select agent ➡️ /req-create; ↩️]
    • Starts a new chat for every prompt.
  • ✔️ OpenCode in Visual Studio Code
    • Supported with a windowed CLI
  • ✔️ Gemini Code Assist Extension for Visual Studio Code
    • Skills: [$req-create] (does not highlight skills like the CLI)
    • Prompts/Agents not supported by the VS Code extension
  • ❌ Kiro in VS Code is not supported

Known Issues

Enable model and tools on prompts/agents

The enable-tools option (within a --provider spec) adds a tools: specification to prompts based on read/write requirements.

The enable-models option (within a --provider spec) adds a model: specification to prompts as detailed in the tables below.

Models Specs

Model Context Length Reasoning [1]
Grok Code Fast 0 256K
Claude Haiku 4.5 200K
Claude Sonnet 4.5 1M
Claude Opus 4.5 200K Yes
Gemini 3 Flash (Preview) 1.05M
Gemini 3.1 Pro (Preview) 1.05M Yes
GPT-4.1 1.05M No
GPT-5 mini 400K Yes
GPT-5.1 400K Yes
GPT-5.1-Codex-Mini (Preview) 400K
GPT-5.1-Codex 400K
GPT-5.1-Codex-Max 400K
GPT-5.2 400K Yes
GPT-5.2-Codex 400K Yes

[1] Reasoning availability according to openrouter.ai [2] Claude Sonnet 4.5 supports a 1M token context window when using the context-1m-2025-08-07 beta header. Long context pricing applies to requests exceeding 200K tokens.

GitHub Copilot

Available Models and Costs

Model Cost
Grok Code Fast 0 0x
Claude Haiku 4.5 0.33x
Claude Sonnet 4.5 1x
Claude Opus 4.5 3x
Gemini 3 Flash (Preview) 0.33x
Gemini 3.1 Pro (Preview) 1x
GPT-5 mini 0x
GPT-5.1 1x
GPT-5.1-Codex-Mini (Preview) 0.33x
GPT-5.1-Codex 1x
GPT-5.1-Codex-Max 1x
GPT-5.2 1x
GPT-5.2-Codex 1x

Configured Models

Prompt Model
analyze Gemini 3.1 Pro (Preview) (copilot)
change GPT-5.3-Codex (copilot)
check Gemini 3.1 Pro (Preview) (copilot)
cover GPT-5.3-Codex (copilot)
create Gemini 3.1 Pro (Preview) (copilot)
fix GPT-5.3-Codex (copilot)
implement GPT-5.3-Codex (copilot)
new GPT-5.3-Codex (copilot)
readme Gemini 3.1 Pro (Preview) (copilot)
recreate Gemini 3.1 Pro (Preview) (copilot)
refactor GPT-5.3-Codex (copilot)
renumber GPT-5.3-Codex (copilot)
workflow GPT-5.3-Codex (copilot)
write Gemini 3.1 Pro (Preview) (copilot)

Claude Code

Available Models and Costs

Model Cost
Claude Haiku 4.5 low
Claude Sonnet 4.6 mid
Claude Opus 4.6 high

Long Context Pricing

When using Claude Sonnet 4 or Sonnet 4.5 with the 1M token context window enabled, requests that exceed 200K input tokens are automatically charged at premium long context rates. [3]

# Example of using a full model name with the [1m] suffix
/model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]

[3] The 1M token context window is currently in beta for organizations in usage tier 4 and organizations with custom rate limits. The 1M token context window is only available for Claude Sonnet 4 and Sonnet 4.5.

Configured Models

Prompt Model
analyze haiku
change sonnet
check haiku
cover opus
create haiku
fix opus
implement opus
new sonnet
readme haiku
recreate haiku
refactor opus
renumber opus
workflow haiku
write haiku

Kiro CLI

Available Models and Costs

Model Cost
Claude Sonnet 4.5 1.3x credit
Claude Sonnet 4 1.3x credit
Claude Haiku 4.5 0.4x credit
Claude Opus 4.5 2.2x credit

Configured Models

Prompt Model
analyze claude-haiku-4.5
change claude-sonnet-4.5
check claude-haiku-4.5
cover claude-sonnet-4.5
create claude-haiku-4.5
fix claude-sonnet-4.5
implement claude-sonnet-4.5
new claude-sonnet-4.5
readme claude-haiku-4.5
recreate claude-haiku-4.5
refactor claude-sonnet-4.5
renumber claude-sonnet-4.5
workflow claude-haiku-4.5
write claude-haiku-4.5

OpenCode CLI

Models depend on the user's provider; useReq config uses the GitHub provider. OpenCode CLI does not support "tools:" on agents/prompts.

Available GitHub Models

  • github-copilot/claude-haiku-4.5
  • github-copilot/claude-opus-4.5
  • github-copilot/claude-opus-41
  • github-copilot/claude-sonnet-4
  • github-copilot/claude-sonnet-4.5
  • github-copilot/gemini-3-flash-preview
  • github-copilot/gpt-5-mini
  • github-copilot/gpt-5.1
  • github-copilot/gpt-5.1-codex
  • github-copilot/gpt-5.1-codex-max
  • github-copilot/gpt-5.2
  • github-copilot/claude-opus-4.6
Not Working GitHub Models
  • github-copilot/gemini-2.5-pro
  • github-copilot/gemini-3-pro-preview
  • github-copilot/gpt-5.1-codex-mini
Not Tested GitHub Models
  • github-copilot/gpt-4.1
  • github-copilot/gpt-4o
  • github-copilot/gpt-5
  • github-copilot/gpt-5-codex
  • github-copilot/grok-code-fast-1
  • github-copilot/oswe-vscode-prime

Configured Models

Prompt Model
analyze github-copilot/gemini-3.1-pro-preview
change github-copilot/claude-opus-4.6
check github-copilot/gemini-3.1-pro-preview
cover github-copilot/claude-opus-4.6
create github-copilot/gemini-3.1-pro-preview
fix github-copilot/claude-opus-4.6
implement github-copilot/claude-opus-4.6
new github-copilot/claude-opus-4.6
readme github-copilot/gemini-3.1-pro-preview
recreate github-copilot/gemini-3.1-pro-preview
refactor github-copilot/claude-opus-4.6
renumber github-copilot/claude-opus-4.6
workflow github-copilot/claude-opus-4.6
write github-copilot/gemini-3.1-pro-preview

Gemini CLI

Gemini CLI does not support "model:" or "tools:" on prompts.

OpenAI Codex CLI

OpenAI Codex CLI does not support "model:" or "tools:" on prompts.

Note on Git usage

This section describes the Git behavior when executing the commands provided by the scripts.

  • Required state before execution:

    • Execute commands from a working branch (not in detached HEAD).
    • Preferably, the working tree should be clean: avoid unintended changes in the repository before starting the scripts.
    • Save all files and verify that you are in the correct project directory.
    • IMPORTANT: useReq/req uses the .req/ directory (including .req/config.json). Keep .req/ tracked in the Git repository (do not ignore it), so git worktree checkouts include the same configuration; otherwise commands that depend on project configuration can fail.

  • What the scripts do to the repository:

    • The scripts may modify, create, or remove files in the working tree (files on disk).
    • They do not modify Git history (HEAD), branches, or tags automatically.
    • The index (staging area) and history remain unchanged until the user manually performs staging/commit operations.

  • How to commit (recommended practice):

    • Review changes generated by the scripts before including them in a commit.
    • Manually add files to commit using git add <file...>.
    • Execute the commit with a structured message, for example: git commit -m "change(<COMPONENT>): <SHORT-DESCRIPTION> [<DATE>]".
    • Staging and commit operations are under the user's control; the scripts do not perform automatic commits or update Git references.

  • Practical warnings:

    • Do not use destructive commands (e.g., git reset --hard, git clean -fd) to "clean" the repository without verifying the impact.
    • If you prefer to isolate changes, execute commands in a branch or a copy of the repository.

Legacy Mode

The Legacy Mode can be enabled with --legacy.

GitHub Copilot

In Legacy Mode the unsupported model: is not added to agents. See: Defect #980 Model from agent.md isn't recognized #980

About

📋 Requirements (SRS) driven software development with LLM 📋

Resources

Readme

License

GPL-3.0 license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 88

useReq v0.56.0 Latest
Apr 3, 2026
+ 87 releases

Packages

 
 
 

Contributors

Languages