Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

Normalize Codex command templates to the scripts-based schema and auto-upgrade generated commands.

honjo-hiroaki-gtta39185c8bed2
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index 934405bfc..f28443d51 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -70,48 +70,154 @@ CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"
# Embedded fallback command templates for Codex (used only if packaged templates are unavailable)
CODEX_CMD_SPECIFY = """---
-name: specify
-description: "Start a new feature by creating a specification and feature branch."
+description: Create or update the feature specification from a natural language feature description.
+scripts:
+ sh: scripts/bash/create-new-feature.sh --json "{ARGS}"
+ ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"
---
-Start a new feature by creating a specification and feature branch.
-
Given the feature description provided as an argument, do this:
-1. Run the script `scripts/create-new-feature.sh --json "{ARGS}"` from the repo root and parse its JSON for BRANCH_NAME and SPEC_FILE. All future paths must be absolute.
-2. Load `templates/spec-template.md` and create the initial specification at SPEC_FILE, filling in the placeholders with concrete details derived from the arguments while preserving headings/order.
-3. Report completion with the new branch name and spec file path.
+1. Run the script `{SCRIPT}` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.
"""
CODEX_CMD_PLAN = """---
-name: plan
-description: "Plan how to implement the specified feature."
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+scripts:
+ sh: scripts/bash/setup-plan.sh --json
+ ps: scripts/powershell/setup-plan.ps1 -Json
---
-Plan how to implement the specified feature.
-
Given the implementation details provided as an argument, do this:
-1. Run `scripts/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. Use absolute paths in all steps.
-2. Read the feature specification (FEATURE_SPEC) and `memory/constitution.md`.
-3. Copy `templates/plan-template.md` to IMPL_PLAN if not already present and fill in all sections using the specification and {ARGS} as Technical Context.
-4. Ensure the plan includes phases and produces research.md, data-model.md (if needed), contracts/, quickstart.md as appropriate.
-5. Report results with BRANCH and generated artifact paths.
+1. Run `{SCRIPT}` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+ - The feature requirements and user stories
+ - Functional and non-functional requirements
+ - Success criteria and acceptance criteria
+ - Any technical constraints or dependencies mentioned
+
+3. Read the constitution at `memory/constitution.md` to understand constitutional requirements.
+
+4. Execute the implementation plan template:
+ - Load `templates/plan-template.md` (already copied to IMPL_PLAN path)
+ - Set Input path to FEATURE_SPEC
+ - Run the Execution Flow (main) function steps 1-9
+ - The template is self-contained and executable
+ - Follow error handling and gate checks as specified
+ - Let the template guide artifact generation in $SPECS_DIR:
+ * Phase 0 generates research.md
+ * Phase 1 generates data-model.md, contracts/, quickstart.md
+ * Phase 2 generates tasks.md
+ - Incorporate user-provided details from arguments into Technical Context: {ARGS}
+ - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+ - Check Progress Tracking shows all phases complete
+ - Ensure all required artifacts were generated
+ - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.
"""
CODEX_CMD_TASKS = """---
-name: tasks
-description: "Break down the plan into executable tasks."
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+scripts:
+ sh: scripts/bash/check-task-prerequisites.sh --json
+ ps: scripts/powershell/check-task-prerequisites.ps1 -Json
---
-Break down the plan into executable tasks.
-
-1. Run `scripts/check-task-prerequisites.sh --json` and parse FEATURE_DIR and AVAILABLE_DOCS.
-2. Read plan.md and any available docs to derive concrete tasks.
-3. Use `templates/tasks-template.md` as the base, generating numbered tasks (T001, T002, …) with clear file paths and dependency notes. Mark tasks that can run in parallel with [P].
-4. Write the result to FEATURE_DIR/tasks.md.
+Given the context provided as an argument, do this:
+
+1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+ - Always read plan.md for tech stack and libraries
+ - IF EXISTS: Read data-model.md for entities
+ - IF EXISTS: Read contracts/ for API endpoints
+ - IF EXISTS: Read research.md for technical decisions
+ - IF EXISTS: Read quickstart.md for test scenarios
+
+ Note: Not all projects have all documents. For example:
+ - CLI tools might not have contracts/
+ - Simple libraries might not need data-model.md
+ - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+ - Use `templates/tasks-template.md` as the base
+ - Replace example tasks with actual tasks based on:
+ * **Setup tasks**: Project init, dependencies, linting
+ * **Test tasks [P]**: One per contract, one per integration scenario
+ * **Core tasks**: One per entity, service, CLI command, endpoint
+ * **Integration tasks**: DB connections, middleware, logging
+ * **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+ - Each contract file β†’ contract test task marked [P]
+ - Each entity in data-model β†’ model creation task marked [P]
+ - Each endpoint β†’ implementation task (not parallel if shared files)
+ - Each user story β†’ integration test marked [P]
+ - Different files = can be parallel [P]
+ - Same file = sequential (no [P])
+
+5. Order tasks by dependencies:
+ - Setup before everything
+ - Tests before implementation (TDD)
+ - Models before services
+ - Services before endpoints
+ - Core before integration
+ - Everything before polish
+
+6. Include parallel execution examples:
+ - Group [P] tasks that can run together
+ - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with:
+ - Correct feature name from implementation plan
+ - Numbered tasks (T001, T002, etc.)
+ - Clear file paths for each task
+ - Dependency notes
+ - Parallel execution guidance
+
+Context for task generation: {ARGS}
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
"""
+
+# Utility to ensure Codex command templates use the modern schema (with scripts mapping)
+def ensure_codex_command_templates_current(commands_dir: Path) -> None:
+ expected = {
+ "specify.md": CODEX_CMD_SPECIFY,
+ "plan.md": CODEX_CMD_PLAN,
+ "tasks.md": CODEX_CMD_TASKS,
+ }
+
+ def needs_upgrade(content: str) -> bool:
+ # Old templates lacked the scripts: mapping and {SCRIPT} placeholder
+ return "scripts:" not in content or "{SCRIPT}" not in content
+
+ for filename, template_text in expected.items():
+ target_file = commands_dir / filename
+ if target_file.exists():
+ try:
+ current = target_file.read_text(encoding="utf-8")
+ except Exception:
+ target_file.write_text(template_text, encoding="utf-8")
+ else:
+ if needs_upgrade(current):
+ target_file.write_text(template_text, encoding="utf-8")
+ else:
+ target_file.parent.mkdir(parents=True, exist_ok=True)
+ target_file.write_text(template_text, encoding="utf-8")
+
+
# ASCII Art Banner
BANNER = """
β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•—β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•— β–ˆβ–ˆβ•—
@@ -972,6 +1078,7 @@ def init(
# Ensure scripts are executable (POSIX)
ensure_executable_scripts(project_path, tracker=tracker)
+ # Codex only: if commands/ is missing, copy from template (with embedded fallback)
if selected_ai == "codex":
tracker.start("commands")
try:
@@ -985,13 +1092,20 @@ def init(
break
if commands_src is not None:
shutil.copytree(commands_src, target_cmds, dirs_exist_ok=True)
+ ensure_codex_command_templates_current(target_cmds)
tracker.complete("commands", "added")
else:
- target_cmds.mkdir(parents=True, exist_ok=True)
- (target_cmds / "specify.md").write_text(CODEX_CMD_SPECIFY, encoding="utf-8")
- (target_cmds / "plan.md").write_text(CODEX_CMD_PLAN, encoding="utf-8")
- (target_cmds / "tasks.md").write_text(CODEX_CMD_TASKS, encoding="utf-8")
- tracker.complete("commands", "bootstrapped")
+ template_commands = project_path / ".specify" / "templates" / "commands"
+ if template_commands.exists():
+ shutil.copytree(template_commands, target_cmds, dirs_exist_ok=True)
+ ensure_codex_command_templates_current(target_cmds)
+ tracker.complete("commands", "added from template")
+ else:
+ target_cmds.mkdir(parents=True, exist_ok=True)
+ (target_cmds / "specify.md").write_text(CODEX_CMD_SPECIFY, encoding="utf-8")
+ (target_cmds / "plan.md").write_text(CODEX_CMD_PLAN, encoding="utf-8")
+ (target_cmds / "tasks.md").write_text(CODEX_CMD_TASKS, encoding="utf-8")
+ tracker.complete("commands", "bootstrapped minimal")
else:
tracker.skip("commands", "already present")
except Exception as codex_error:
diff --git a/templates/commands/plan.md b/templates/commands/plan.md
index 18a0b5c64..6315d0ee8 100644
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -14,10 +14,10 @@ Given the implementation details provided as an argument, do this:
- Success criteria and acceptance criteria
- Any technical constraints or dependencies mentioned
-3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.
+3. Read the constitution at `memory/constitution.md` to understand constitutional requirements.
4. Execute the implementation plan template:
- - Load `/templates/plan-template.md` (already copied to IMPL_PLAN path)
+ - Load `templates/plan-template.md` (already copied to IMPL_PLAN path)
- Set Input path to FEATURE_SPEC
- Run the Execution Flow (main) function steps 1-9
- The template is self-contained and executable
diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md
index 29b4cd25e..fe89b9581 100644
--- a/templates/commands/tasks.md
+++ b/templates/commands/tasks.md
@@ -21,7 +21,7 @@ Given the context provided as an argument, do this:
- Generate tasks based on what's available
3. Generate tasks following the template:
- - Use `/templates/tasks-template.md` as the base
+ - Use `templates/tasks-template.md` as the base
- Replace example tasks with actual tasks based on:
* **Setup tasks**: Project init, dependencies, linting
* **Test tasks [P]**: One per contract, one per integration scenario