sddx-workflow 0.6.0 → 0.8.0

package/README.md

@@ -1,8 +1,12 @@
 # sddx-workflow
 
+[![npm](https://img.shields.io/npm/v/sddx-workflow)](https://www.npmjs.com/package/sddx-workflow)
+[![node](https://img.shields.io/node/v/sddx-workflow)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/sddx-workflow)](LICENSE)
+
 Spec-Driven Development CLI for AI-assisted projects. Installs a structured workflow system that guides AI agents (Claude, Cursor, Copilot) through planning, execution, and review — without letting them run loose.
 
-Works with any project: Next.js, Python, React, Django, Go, Rails — the workflow is universal.
+Works with any project: Next.js, Python, React, Django, Go, Rails.
 
 ```bash
 npx sddx-workflow init
@@ -10,91 +14,97 @@ npx sddx-workflow init
 
 ---
 
-## The problem
+## Why this exists
 
 AI agents tend to implement without validating assumptions, refactor more than asked, and don't have a mental model of when to stop and ask for approval. This system enforces explicit ceremony levels and stop points.
 
 ---
 
-## Installation
+## Quick start
 
 ```bash
-# Initialize in any project
+# 1. Initialize the workflow in your project
 npx sddx-workflow init
 
-# Overwrite existing files
-npx sddx-workflow init --force
+# 2. Populate project context (run with your AI agent)
+/bootstrap
+
+# 3. Build a feature
+/spec-new      # scaffold a spec folder
+/spec-plan     # generate a technical plan — stops for your approval
+/spec-tasks    # execute one atomic task at a time
+/finish        # stage files + generate a conventional commit
+```
+
+---
+
+## CLI reference
+
+```bash
+npx sddx-workflow init                  # Initialize in current project
+npx sddx-workflow init --force          # Overwrite existing files
 
-# Add a domain file to an existing installation
-npx sddx-workflow add domain auth
+npx sddx-workflow add domain auth       # Add a domain file
 npx sddx-workflow add domain payments
 npx sddx-workflow add domain storage
 npx sddx-workflow add domain email
+
+npx sddx-workflow status                # Show current workflow state
+npx sddx-workflow update                # Update workflow templates
 ```
 
-Files are **copied locally** — your project owns them. No runtime dependency. Edit them freely.
+Files are **copied locally** — your project owns them. No runtime dependency. Edit freely.
 
 ---
 
-## What it generates
+## Generated structure
 
 ```
 .sdd/
   workflow.md          # Commands, ceremony levels, stop points
-  project-overview.md  # What this app is (populated by /bootstrap)
-  conventions.md       # Stack and patterns (populated by /bootstrap)
+  project-overview.md  # What this app is — populated by /bootstrap
+  conventions.md       # Stack and patterns — populated by /bootstrap
   domains/             # Domain-specific rules (auth, payments, etc.)
 specs/
   _template/
     1-requirements.md  # Problem, goals, acceptance criteria (BDD)
     2-plan.md          # Technical plan — requires approval before coding
     3-tasks.md         # Atomic task checklist with TDD gate
-CLAUDE.md              # Entry point — points the agent to .sdd/
+CLAUDE.md              # Agent entry point — points to .sdd/
 ```
 
 ---
 
-## First thing to do after init
-
-Run `/bootstrap` with your AI agent to populate the project context:
-
-- **New project** — the agent interviews you with 6 targeted questions (problem, stack, non-goals, architecture decisions, domains, definition of done) and writes `.sdd/project-overview.md` and `.sdd/conventions.md`
-- **Existing project** — run `/bootstrap --scan` and the agent reads your codebase first, infers what it can, then asks only about what the code can't answer
-
-The agent presents a full draft for your approval before writing anything.
-
----
-
-## Workflow commands
+## Agent commands
 
 | Command | Purpose |
 |---|---|
-| `/bootstrap` | Populate project context — interview or codebase scan |
+| `/bootstrap` | Populate project context via interview or codebase scan |
 | `/ask` | Research and exploration — no code changes |
-| `/assume` | Surface all assumptions before acting — stops for confirmation |
+| `/assume` | Surface all assumptions before acting |
 | `/bugfix` | Reproduce → diagnose → fix → validate |
-| `/refactor` | Restructure without behavior change — green baseline required |
+| `/refactor` | Restructure without behavior change (green baseline required) |
 | `/spec-new` | Scaffold a spec folder for a feature |
 | `/spec-plan` | Generate technical plan — **stops for approval before any code** |
 | `/spec-tasks` | Execute plan one atomic task at a time, TDD-first |
-| `/review` | Final audit — verifies goals, scenarios, no scope creep |
-| `/finish` | Stage files and generate a conventional commit message for approval |
+| `/review` | Final audit — verifies goals, no scope creep |
+| `/finish` | Stage files + generate conventional commit message |
 
 ### Ceremony levels
 
-| Change | Flow |
+| Change type | Flow |
 |---|---|
 | Typo / comment | Direct |
 | Bug | `/bugfix` → `/finish` |
 | Refactor | `/refactor` → `/finish` |
 | Feature | `/spec-new` → `/spec-plan` → `/spec-tasks` → `/review` → `/finish` |
-| Architecture | `/spec-new` → `/spec-plan` (mandatory human review) → `/spec-tasks` → `/review` → `/finish` |
+| Architecture | `/spec-new` → `/spec-plan` (mandatory review) → `/spec-tasks` → `/review` → `/finish` |
 
 ---
 
 ## Execution principles
 
-Built into the workflow — every command enforces these:
+Enforced by every command:
 
 1. **Surface assumptions** — list them before acting, not mid-execution
 2. **Minimum code** — only what was asked; no "while I'm here" changes
@@ -105,17 +115,27 @@ Built into the workflow — every command enforces these:
 
 ## Spec structure
 
-Each feature gets a folder under `specs/<name>/` with three files:
+Each feature lives in `specs/<name>/` with three files:
 
 **`1-requirements.md`** — Problem, measurable goals (G1, G2…), BDD acceptance criteria, constraints, open questions (blocking vs. non-blocking).
 
-**`2-plan.md`** — Goals coverage, assumptions (confirmed via `/assume`), approach + tradeoffs, components affected, abort criteria, verification per task. Requires explicit approval before execution starts.
+**`2-plan.md`** — Goals coverage, assumptions confirmed via `/assume`, approach + tradeoffs, components affected, abort criteria. Requires explicit approval before execution starts.
 
-**`3-tasks.md`** — One task at a time. Each task has: test to write first (red→green), files to change, goal ID, acceptance scenario, and optional tradeoff. Completed specs move to `specs/_done/`.
+**`3-tasks.md`** — One task at a time. Each has: test to write first (red → green), files to change, goal ID, and acceptance scenario. Completed specs move to `specs/_done/`.
 
 ---
 
-## Updating
+## Development
+
+```bash
+git clone https://github.com/MarcosCamara01/sddx-workflow.git
+cd sddx-workflow
+npm install
+npm run dev      # watch mode
+npm run build    # production build
+```
+
+### Publishing
 
 ```bash
 npm version patch   # bug fix:     0.1.0 → 0.1.1
@@ -123,9 +143,7 @@ npm version minor   # new feature: 0.1.0 → 0.2.0
 npm publish
 ```
 
-Users running `npx sddx-workflow init` always get the latest version automatically.
-
-Since files are copied to your project, existing `.sdd/` files are never overwritten on update — use `--force` to explicitly replace them.
+Users running `npx sddx-workflow init` always get the latest version. Existing `.sdd/` files are never overwritten on update — use `--force` to explicitly replace them.
 
 ---
 

package/dist/cli.js

@@ -107,6 +107,34 @@ var PROVIDERS = {
       { src: "copilot-prompts/finish.prompt.md", dest: ".github/prompts/finish.prompt.md" },
       { src: "copilot-instructions.md", dest: ".github/copilot-instructions.md" }
     ]
+  },
+  codex: {
+    name: "OpenAI Codex",
+    dirs: [
+      ".agents/skills/bootstrap",
+      ".agents/skills/ask",
+      ".agents/skills/assume",
+      ".agents/skills/bugfix",
+      ".agents/skills/refactor",
+      ".agents/skills/spec-new",
+      ".agents/skills/spec-plan",
+      ".agents/skills/spec-tasks",
+      ".agents/skills/review",
+      ".agents/skills/finish"
+    ],
+    files: [
+      { src: "AGENTS.md", dest: "AGENTS.md" },
+      { src: "codex-skills/bootstrap/SKILL.md", dest: ".agents/skills/bootstrap/SKILL.md" },
+      { src: "codex-skills/ask/SKILL.md", dest: ".agents/skills/ask/SKILL.md" },
+      { src: "codex-skills/assume/SKILL.md", dest: ".agents/skills/assume/SKILL.md" },
+      { src: "codex-skills/bugfix/SKILL.md", dest: ".agents/skills/bugfix/SKILL.md" },
+      { src: "codex-skills/refactor/SKILL.md", dest: ".agents/skills/refactor/SKILL.md" },
+      { src: "codex-skills/spec-new/SKILL.md", dest: ".agents/skills/spec-new/SKILL.md" },
+      { src: "codex-skills/spec-plan/SKILL.md", dest: ".agents/skills/spec-plan/SKILL.md" },
+      { src: "codex-skills/spec-tasks/SKILL.md", dest: ".agents/skills/spec-tasks/SKILL.md" },
+      { src: "codex-skills/review/SKILL.md", dest: ".agents/skills/review/SKILL.md" },
+      { src: "codex-skills/finish/SKILL.md", dest: ".agents/skills/finish/SKILL.md" }
+    ]
   }
 };
 var ALL_PROVIDER_IDS = Object.keys(PROVIDERS);
@@ -141,6 +169,7 @@ async function initCommand(options) {
     }
   }
   const claudeExisted = import_fs2.default.existsSync(import_path2.default.join(cwd, "CLAUDE.md"));
+  const agentsExisted = import_fs2.default.existsSync(import_path2.default.join(cwd, "AGENTS.md"));
   for (const file of CORE_FILES) {
     copyTemplate(file.src, import_path2.default.join(cwd, file.dest), force);
   }
@@ -160,6 +189,13 @@ async function initCommand(options) {
   } else {
     console.log("  2. CLAUDE.md already exists \u2014 add a reference to .sdd/ files manually");
   }
+  if (selectedProviders.includes("codex")) {
+    if (!agentsExisted) {
+      console.log("     AGENTS.md was created \u2014 Codex will read it automatically");
+    } else {
+      console.log("     AGENTS.md already exists \u2014 add a reference to .sdd/ files manually");
+    }
+  }
   console.log(`  3. Slash commands are ready in: ${providerNames}. Type / to see them.
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sddx-workflow",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Spec-Driven Development CLI — installs an SDD system in any project",
   "keywords": [
     "sdd",

package/templates/AGENTS.md

@@ -0,0 +1,37 @@
+# Codex — Project Context
+
+This project uses the SDD Protocol. Read these files before starting any task:
+
+1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, ceremony levels, and stop points
+2. **[.sdd/project-overview.md](.sdd/project-overview.md)** — what this app is, its non-goals, domains, and definition of done
+3. **[.sdd/conventions.md](.sdd/conventions.md)** — project-specific conventions and patterns
+
+## Available Skills
+
+Type `/skills` or `$skill-name` to invoke. Skills are defined in `.agents/skills/`.
+
+| Intent | Skill |
+|---|---|
+| Initialize project context | `$bootstrap` (new) · `$bootstrap --scan` (existing) |
+| Explore / research | `$ask` |
+| Surface and validate assumptions | `$assume` |
+| Fix a confirmed bug | `$bugfix` → `$finish` |
+| Restructure without behavior change | `$refactor` → `$finish` |
+| New feature | `$spec-new` → `$spec-plan` → `$spec-tasks` → `$review` → `$finish` |
+| Stage + commit after any work | `$finish` |
+
+## Active Specs
+
+<!-- List specs currently in progress — completed specs live in specs/_done/ and are not active context.
+- specs/auth-refresh/ — in spec-tasks (task 3 of 5)
+- specs/payments-v2/ — plan pending approval
+-->
+
+## Domain Files
+
+Relevant domain context lives in `.sdd/domains/`. Read the relevant domain file before working in that area.
+
+<!-- List domains present in this project, e.g.:
+- [.sdd/domains/auth.md](.sdd/domains/auth.md)
+- [.sdd/domains/payments.md](.sdd/domains/payments.md)
+-->

package/templates/codex-skills/ask/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: ask
+description: Research and exploration only — no code changes. Use when understanding a system, gathering context, analyzing options, or investigating a bug without touching files.
+---
+
+Execute the /ask command defined in .sdd/workflow.md.
+
+Research and exploration only — no code changes. Read files, analyze, and summarize findings with explicit options or recommendations.

package/templates/codex-skills/assume/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: assume
+description: Surface all assumptions before acting on a task. Use before spec-plan, before complex diagnosis, or any time an unstated guess is being made about requirements or codebase state.
+---
+
+Execute the /assume command defined in .sdd/workflow.md.
+
+List every assumption being made about the task, codebase state, and technical decisions.
+For each: what you're assuming, why, and what changes if it's wrong.
+Stop and wait for confirmation before proceeding.

package/templates/codex-skills/bootstrap/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: bootstrap
+description: Populate .sdd/project-overview.md and .sdd/conventions.md with real project context. Use when initializing a new project or onboarding to an existing codebase.
+---
+
+Execute the /bootstrap command defined in .sdd/workflow.md.
+
+Populate .sdd/project-overview.md and .sdd/conventions.md with real project context.
+If the request contains --scan, analyze the existing codebase first before asking questions.
+Present the full draft for approval before writing any file.

package/templates/codex-skills/bugfix/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: bugfix
+description: Lightweight flow for confirmed bugs. Use when fixing a known bug that fits within ~1 file or ~50 lines. Follows Reproduce → Diagnose → Fix → Validate stages.
+---
+
+Execute the /bugfix command defined in .sdd/workflow.md.
+
+Follow the stages in order: Reproduce → Diagnose → Fix → Validate.
+Do not skip stages. Stop after Reproduce if the bug cannot be confirmed.

package/templates/codex-skills/finish/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: finish
+description: Stage changed files and produce a conventional commit message for approval. Use after completing any unit of work — bug fix, refactor, or feature tasks.
+---
+
+Execute the /finish command defined in .sdd/workflow.md.
+
+Run git status and git diff. Stage all relevant files. Determine the commit type.
+Draft a conventional commit message following the format in workflow.md.
+Stop and present the staged files and commit message for approval before committing.

package/templates/codex-skills/refactor/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: refactor
+description: Restructure code without changing external behavior. Use when cleaning up internals while keeping all observable behavior identical. Requires a green test baseline first.
+---
+
+Execute the /refactor command defined in .sdd/workflow.md.
+
+Restructure code without changing external behavior. Establish a green test baseline first.
+Every observable behavior before the refactor must be identical after it.

package/templates/codex-skills/review/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: review
+description: Final audit before closing a spec or merging. Use after all spec tasks are complete to verify goals are met, tests pass, and no scope creep was introduced.
+---
+
+Execute the /review command defined in .sdd/workflow.md.
+
+Audit the spec before closing. Verify all goals (G1, G2…) are satisfied, every acceptance scenario has a passing test, no out-of-scope changes were introduced, and the implementation is the simplest that meets requirements.

package/templates/codex-skills/spec-new/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: spec-new
+description: Scaffold a spec folder for a new feature or significant change. Use at the start of any feature work to create the requirements, plan, and tasks files.
+---
+
+Execute the /spec-new command defined in .sdd/workflow.md.
+
+Create a specs/<name>/ folder by copying the three template files from specs/_template/.
+Replace <Feature Name> in each file title with the actual feature name.

package/templates/codex-skills/spec-plan/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: spec-plan
+description: Generate a technical plan from an approved requirements doc. Use after filling out 1-requirements.md. Stops for explicit approval before any code is written.
+---
+
+Execute the /spec-plan command defined in .sdd/workflow.md.
+
+Read specs/<name>/1-requirements.md, run /assume, then draft the technical plan in specs/<name>/2-plan.md.
+Stop for explicit approval before writing any implementation code.

package/templates/codex-skills/spec-tasks/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: spec-tasks
+description: Execute an approved technical plan as atomic tasks, one at a time. Use after spec-plan is approved. Follows TDD: write test first (red), implement until green, run full suite.
+---
+
+Execute the /spec-tasks command defined in .sdd/workflow.md.
+
+Read the approved specs/<name>/2-plan.md and execute tasks one at a time.
+Write the test first (red), implement until green, run the full suite, then move to the next task.
+Stop if tests fail or if a task reveals new scope.