blackpeanut/awesome-sdd

Awesome SDD helps you turn an idea into a specification, a plan, tested code, and a reviewed change. You decide what matters. SDD keeps the documents and tasks up to date as you go. Expand the sections below for setup details, settings and the full workflow—all on this page.

One choice at a time. Questions describe the behavior you're deciding, with technical detail when it helps. You can answer briefly, change your mind, or pick things up later.

SDD: Should people stay signed in after closing the browser?
You: Yes.
SDD: How long should they stay signed in?
You: Thirty days.
SDD: Got it. I'll record that and cover it in the tests.

Install

Choose your app. Use one installation method to avoid duplicate skills.

Claude Code

Run inside Claude Code:

/plugin marketplace add blackPeanut/awesome-sdd
/plugin install awesome-sdd@awesome-sdd

Then ask: “Use SDD to survey this repository.”

Codex desktop or CLI

Run in a terminal with codex available:

codex plugin marketplace add blackPeanut/awesome-sdd
codex plugin add awesome-sdd@awesome-sdd

Restart the desktop app, open Plugins, and find Awesome SDD. Start a chat in your project, select SDD, and ask: “Use SDD to survey this repository.”

This installs the native plugin for both desktop and CLI. SDD itself needs no separate service or API key; it uses your host's model access.

Installation options, updates and removal

Choose one installation

The marketplace and plugin are both named awesome-sdd. Existing .claude/sdd.local.md settings and copied $sdd-* skills keep their names for compatibility. If an upstream SDD copy is installed, remove it separately before installing this version to avoid duplicate skills.

Claude Code

Re-run the install command inside Claude Code, then reload plugins:

/plugin install awesome-sdd@awesome-sdd
/reload-plugins

Use Claude Code's plugin manager to remove the plugin.

Codex desktop and CLI

Update the marketplace and install its current SDD version:

codex plugin marketplace upgrade awesome-sdd
codex plugin add awesome-sdd@awesome-sdd

Restart the desktop app after updating. To remove SDD:

codex plugin remove awesome-sdd@awesome-sdd

Removal leaves the marketplace registered.

Install from a checkout or use project-only skills

Native plugin from this checkout

For the native Codex plugin:

bash install.sh codex-app

This registers and installs the published marketplace version. It is user-wide and does not copy this working tree or write project settings. The helper needs codex on PATH; otherwise set SDD_CODEX_BIN to the full path of your Codex executable, including the app's bundled one.

--prefix, --src and non-main --ref values belong to copied-skill installs, not codex-app.

Copied project skills

Run from the project where you want the skills:

curl -fsSL https://raw.githubusercontent.com/blackPeanut/awesome-sdd/main/install.sh | bash -s -- codex

This writes .agents/skills/ and .codex/agents/. Restart Codex and use $sdd-survey, $sdd-specify, and the other prefixed names. These skills work in desktop and CLI, but do not create a card in the Plugins directory. Python 3 is required to generate the Codex agent files.

From a local checkout, choose a different scope or test your edits:

bash install.sh codex --prefix /path/to/project
bash install.sh codex --global
bash install.sh codex --src . --prefix /path/to/test-project

Re-run the same install command to update. Add --ref <release-tag> to download a particular release. For removal, use the same scope as the original install:

bash install.sh codex --prefix /path/to/project --uninstall

Use --global --uninstall for a global copy. Project settings are retained. If switching to the native plugin, remove the copied installation first.

Windows users can run the Bash helper through Git Bash or WSL in the environment used for Codex.

Troubleshooting and interrupted upgrades

If an upgrade is interrupted

The copied-skill installer downloads, validates and stages the replacement before swapping it in. Ordinary failures and catchable termination signals restore the previous copy. Unrelated agents and existing settings are preserved.

Backups live under .agents/.sdd-installer/ at the installation prefix, outside skill discovery. The installer prints the transaction directory. Keep its previous-skills and previous-agents while you may need to recover; never remove a transaction referenced by pending.

If the process was killed without cleanup:

1. Read lock/pid in that state directory.
2. Confirm that the installer process is no longer running.
3. Remove only the stale lock directory, then rerun the same installer command.

The next run restores the pending swap before attempting a new upgrade. Native plugin updates are managed by the host instead.

Start here

Pick the request closest to where you are. You don't need to learn every command first.

Give each feature a short name such as saved-searches and reuse it throughout the workflow. Its files live in docs/features/saved-searches/.

At the end of a stage, SDD tells you what changed and what to do next:

Saved searches now have a spec, including duplicate handling.
Your decisions are saved in spec.md. Next, we'll check the open questions.

Follow that next step. SDD checks the files a stage needs before proceeding, and adapts handoffs to your app. When fresh context is needed, Codex desktop uses a new chat in the same project; Claude Code uses /clear.

Tip

Want to keep commits in your hands? Before starting, ask “Use SDD config to turn off automatic commits.” By default, SDD commits completed documents and verified implementation tasks.

How it works

Each feature follows the middle path below. Setup tools help you get ready; the tools at the bottom help you resume, adjust decisions, or fix a bug along the way.

imageFull Awesome SDD workflow: preparation, all 13 feature stages, the review loop, and supporting tools

Read down each column, then move right. Blue steps stay in every feature route. Dashed steps depend on what the feature changes and which route you choose. Click the map to zoom in.

Small changes use less detail. Optional steps can be skipped when they don't apply; UI work adds user flows and screen states. SDD explains the next step instead of asking you to run a giant checklist. Pushing or opening a PR needs authorization; merging stays your call.

See the full stage order

For a new codebase, survey plans the foundation and scaffold builds the starting skeleton. For UI work, design-system establishes the shared components and styles before the first feature.

The full per-feature path is:

specify → clarify → ux-flows → design → sequences
    → data-model → api → screens → tasks → plan-tests
    → implement → review → ship

The route determines how optional steps are handled:

The default comes from feature size: XS/S → quick, M → standard, L/XL → full. You can change it with classify-size. The route affects the suggested next step; you can still ask for a skipped stage directly.

specify, design, tasks, implement, review and ship remain part of every feature route. A small feature with a database change still needs its data-model work.

Keep working without losing your place

What the checks cover

Local automated tests cover installation, failed upgrades, malformed settings, implementation recovery and review snapshots. Review checks include changed code, changed requirements, new files and reviewed work that hasn't been committed.

Live Claude/Codex evaluations use disposable projects to exercise conversations and workflow behavior. They consume model usage. Headless text tests don't prove desktop question widgets or all interactive behavior; those need separate human checks.

Make it yours

Ask “Use SDD config”, or name the preference directly:

“Ask me about each meaningful choice, but keep the questions short.”
“Turn off automatic commits.”
“Run implementation one task at a time.”

Codex uses its current session model. Claude model preferences such as judgment_model apply only on hosts that support them. Missing delegation or workflow tools fall back to inline or sequential work, with the limitation stated. An inline self-check is not an independent review.

Discussion depth: how much SDD asks you

For specify, clarify and design, an explicit --depth= wins, then your preference in the conversation, then the saved interview_depth. The default is medium. Changing the pace for one run doesn't change the saved setting; ask config to save it.

For example, in Claude Code: /awesome-sdd:specify saved-searches --depth=easy.

The initial interview skill uses a question limit instead: easy up to 4, medium up to 10, hard up to 15. You can extend the limit. It can stop earlier when there's enough information, and it doesn't invent answers to finish within the limit.

Depth changes how much you discuss, not which requirements must be covered. Accepted answers carry forward, so later stages shouldn't ask you to decide the same thing again.

Agents and parallel work: what implement actually does

The defaults are team_mode: true, workflow_mode: auto and a limit of three parallel agents. Team mode takes priority when supported. Existing settings keep their saved value; this default applies to new settings or a missing key. SDD follows your saved choice and announces the selected mode; it doesn't need to ask again unless authorization or a decision is missing.

Parallel work needs independent tasks, separate Git working folders (isolation: worktree), a limit above one, enough work to justify coordination, and a compatible host backend. Tasks touching the same files are kept in order. The lead combines the changes and verifies them.

max_parallel_agents: 1, isolation: inplace, or auto_commit: off makes implementation sequential. The current parallel recipes need commits so later tasks can start from earlier work.

Current Codex limitation: the team recipes expect TeamCreate or Workflow capabilities. Ordinary subagents alone don't satisfy that requirement, so implementation falls back to sequential work. A separate reviewer can still be used when delegation is available and allowed. Turning team_mode on doesn't remove this limitation.

SDD respects the host's permissions and your existing authorization. A missing tool changes the execution mode, not your saved preferences.

Models, effort and differences between Claude and Codex

The Codex worker defaults are:

An explicit choice for the current invocation takes precedence. inherit leaves a control to the host. Model availability and supported effort levels come from the current host; SDD doesn't translate Claude tiers or assume every account has these models.

These preferences control workers, not the model of your current chat. In sequential Codex implementation, the test author and coder run one at a time when delegation is available and allowed. The lead collects their results, records progress and commits verified work. If workers aren't available, implementation runs inline with the chat's settings. Parallel scheduling is unchanged.

SDD briefly reports what it requests and any fallback. It calls settings confirmed only when the host exposes that information; otherwise it says “requested; host did not expose confirmation.”

On Claude, an unset judgment preference is a minimum preference, not a forced downgrade from a stronger session model. If the comparison is unknown, SDD inherits rather than guessing. If an allowed model or effort override is unavailable, it retries once with host inheritance and tells you. Authentication and permission errors aren't treated as model availability errors.

A separate review requires an available, authorized reviewer. If only an inline self-check is possible, SDD says so. A headless run stops at an unanswered decision instead of claiming you approved it.

The settings file

Settings live in .claude/sdd.local.md for both Claude and Codex. The name is shared for compatibility. The file is per project, gitignored, and created when a writing workflow first needs it. config changes only the preferences you agree to change.

Show all defaults

interview_depth: medium    # easy | medium | hard — plugin-wide default for specify/clarify/design
artifact_language: en      # English only; legacy non-en values are treated as en
tdd: true                  # enforce red→green→refactor
team_mode: true            # true → agent team via TeamCreate
workflow_mode: auto        # auto → dynamic Workflow; off → never
max_parallel_agents: 3     # integer ≥1 — fan-out cap for team/workflow modes (1 = sequential)
isolation: worktree        # worktree | inplace (parallel>1 ⇒ forces worktree)
stop_on_red: true          # halt on a red that survives escalation, vs drop-and-continue
max_red_retries: 3         # integer ≥1 — RED→GREEN attempts before escalation
gate_lint: true            # true | false — include lint in the per-task gate
gate_vet: true             # true | false — include vet / static-analysis in the per-task gate
require_integration: auto  # auto | always | never (Docker-probed)
auto_commit: per_task      # per_task | per_phase | off — off also stops document-stage commits
branch_strategy: feature   # feature | current
cmd_test_unit: ""          # empty = autodetect (escape hatch)
cmd_test_integration: ""
cmd_lint: ""
cmd_vet: ""
model_test_author: sonnet  # per-role model; inherit = session model
model_implementer: sonnet
model_reviewer: opus
judgment_model: opus       # Claude-only preference; Codex uses separate codex_* preferences
effort_test_author: medium # per-role effort; raised to high on escalation
effort_implementer: medium
effort_reviewer: high
codex_model: gpt-6.1-sol       # default Codex worker model; inherit = host choice
codex_model_explorer: gpt-6-luna # lighter model for bounded code exploration
codex_effort_explorer: high
codex_effort_test_author: medium
codex_effort_implementer: medium
codex_effort_reviewer: high
codex_effort_judgment: high    # critic, devils-advocate, strategist and analyst
codex_effort_complex: high     # raise coding/test effort for difficult work or escalation

Legacy non-English artifact_language values still produce English conversation and documents. Existing unrelated content and exact source quotations are preserved.

The settings and implementation-recovery helpers require Python 3.10+ and PyYAML. The review snapshot helper uses Python 3.10+ with no extra packages. A missing required dependency is reported before the workflow proceeds.

Missing files or missing keys use these defaults. Invalid existing settings stop the workflow before writes, commands with side effects, or commits. Unknown keys and your comments are preserved. config changes values individually rather than replacing your whole file.

What each setting controls

Conversation

Implementation and commits

Checks and failures

The current integration check uses Docker availability. A skipped check is never reported as a pass.

Command overrides

An empty string means automatic detection from the repo's Makefile, package scripts and language manifests. Set an override only when that detection doesn't find the right command.

Models and effort

Claude uses model_test_author, model_implementer, model_reviewer, their matching effort_* values, and judgment_model.

Codex uses its own preferences:

For any other role, add codex_model_<role> or codex_effort_<role>, replacing hyphens with underscores—for example, codex_model_test_author. An explicit invocation choice takes precedence. A role effort of inherit is never raised automatically. To inherit every worker model, set codex_model and any role-model overrides (including codex_model_explorer) to inherit. Model and effort choices are independent; only supported values are sent to the worker tool. Missing keys use defaults without rewriting an existing settings file. Nothing changes your global Codex configuration.

Skill reference

SDD includes 24 atomic skills. Use their names in a request, or invoke them directly:

Explore all 24 skills

Get oriented

Shape the feature

Build and check

Use anytime

Where things are saved

The conversation stays brief. The details stay in your project:

docs/
├── idea-brief.md          # The idea and what you decided
├── architecture-map.md    # How the existing system works
├── roadmap.md            # The larger plan, when needed
├── design-system.md      # Shared UI conventions, when needed
└── features/
    └── saved-searches/
        ├── spec.md       # What the feature should do
        ├── sad.md        # How it fits the system
        ├── adr/          # Architectural decision records
        ├── contracts/    # Interface definitions
        ├── tasks.json    # Tasks and dependencies
        ├── tasks/        # Task details, progress and test evidence
        └── _review/      # Review reports and input snapshots

Some files appear only when the feature needs them. UI flows, screen plans, data models and migration files are added by their respective stages.

Help and contributing

• Can't find the plugin? Open “Troubleshooting and interrupted upgrades” under Install.
• A stage won't proceed? Read the missing prerequisite it names and keep the feature name consistent. status can explain what is ready and what still needs work.
• Want the implementation details? Browse skills, shared rules and agent roles.
• Changing the plugin? Start with python3 scripts/validate_plugin.py and the relevant tests. For live Claude/Codex evaluations, see the evaluation guide; those runs use model access and may incur usage costs.
• Found a problem? Open an issue.

Credits and license

Maintained by blackPeanut. Available under the MIT license, with the original copyright notice preserved.

This is a Git-hosted community plugin, not an official OpenAI or Anthropic marketplace listing.