codexspec 0.2.2__tar.gz → 0.3.0__tar.gz

{codexspec-0.2.2 → codexspec-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.2.2
+Version: 0.3.0
 Summary: CodexSpec - A Spec-Driven Development (SDD) toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec
@@ -165,22 +165,30 @@ Use the `/codexspec.constitution` command to create your project's governing pri
 /codexspec.constitution Create principles focused on code quality, testing standards, and clean architecture
 ```
 
-### 3. Create a Specification
+### 3. Clarify Requirements
 
-Use `/codexspec.specify` to define what you want to build:
+Use `/codexspec.specify` to **explore and clarify** your requirements through interactive Q&A:
 
 ```
-/codexspec.specify Build a task management application with the following features: create tasks, assign to users, set due dates, and track progress
+/codexspec.specify I want to build a task management application
 ```
 
-### 4. Clarify Requirements (Optional but Recommended)
+This command will:
+- Ask clarifying questions to understand your idea
+- Explore edge cases you might not have considered
+- Co-create high-quality requirements through dialogue
+- **NOT** generate files automatically - you stay in control
 
-Use `/codexspec.clarify` to resolve ambiguities before planning:
+### 4. Generate Specification Document
+
+Once requirements are clarified, use `/codexspec.generate-spec` to create the `spec.md` document:
 
 ```
-/codexspec.clarify
+/codexspec.generate-spec
 ```
 
+This command acts as a "requirement compiler" that transforms your clarified requirements into a structured specification document.
+
 ### 5. Create a Technical Plan
 
 Use `/codexspec.spec-to-plan` to define how to implement it:
@@ -252,8 +260,8 @@ After initialization, these slash commands are available in Claude Code:
 | Command | Description |
 |---------|-------------|
 | `/codexspec.constitution` | Create or update project governing principles |
-| `/codexspec.specify` | Define what you want to build (requirements) |
-| `/codexspec.generate-spec` | Generate detailed specification from requirements |
+| `/codexspec.specify` | **Clarify** requirements through interactive Q&A (no file generation) |
+| `/codexspec.generate-spec` | **Generate** `spec.md` document after requirements are clarified |
 | `/codexspec.spec-to-plan` | Convert specification to technical plan |
 | `/codexspec.plan-to-tasks` | Break down plan into actionable tasks |
 | `/codexspec.implement-tasks` | Execute tasks according to breakdown |
@@ -270,7 +278,7 @@ After initialization, these slash commands are available in Claude Code:
 
 | Command | Description |
 |---------|-------------|
-| `/codexspec.clarify` | Clarify underspecified areas before planning |
+| `/codexspec.clarify` | Scan existing spec.md for ambiguities and update with clarifications |
 | `/codexspec.analyze` | Cross-artifact consistency analysis |
 | `/codexspec.checklist` | Generate quality checklists for requirements |
 | `/codexspec.tasks-to-issues` | Convert tasks to GitHub issues |
@@ -285,35 +293,88 @@ After initialization, these slash commands are available in Claude Code:
 │  1. Constitution  ──►  Define project principles             │
 │         │                                                    │
 │         ▼                                                    │
-│  2. Specify  ───────►  Create feature specification          │
+│  2. Specify  ───────►  Interactive Q&A to clarify            │
+│         │             requirements (no file created)         │
 │         │                                                    │
 │         ▼                                                    │
-│  3. Clarify  ───────►  Resolve ambiguities (optional)        │
+│  3. Generate Spec  ─►  Create spec.md document               │
+│         │             (user calls explicitly)                │
 │         │                                                    │
 │         ▼                                                    │
 │  4. Review Spec  ───►  Validate specification                │
 │         │                                                    │
 │         ▼                                                    │
-│  5. Spec to Plan  ──►  Create technical plan                 │
+│  5. Clarify  ───────►  Resolve ambiguities (optional)        │
 │         │                                                    │
 │         ▼                                                    │
-│  6. Review Plan  ───►  Validate technical plan               │
+│  6. Spec to Plan  ──►  Create technical plan                 │
 │         │                                                    │
 │         ▼                                                    │
-│  7. Plan to Tasks  ─►  Generate task breakdown               │
+│  7. Review Plan  ───►  Validate technical plan               │
 │         │                                                    │
 │         ▼                                                    │
-│  8. Analyze  ───────►  Cross-artifact consistency (optional) │
+│  8. Plan to Tasks  ─►  Generate task breakdown               │
 │         │                                                    │
 │         ▼                                                    │
-│  9. Review Tasks  ──►  Validate task breakdown               │
+│  9. Analyze  ───────►  Cross-artifact consistency (optional) │
 │         │                                                    │
 │         ▼                                                    │
-│  10. Implement  ─────►  Execute implementation               │
+│  10. Review Tasks  ─►  Validate task breakdown               │
+│         │                                                    │
+│         ▼                                                    │
+│  11. Implement  ─────►  Execute implementation               │
 │                                                              │
 └──────────────────────────────────────────────────────────────┘
 ```
 
+### Key Concept: Requirement Clarification Workflow
+
+CodexSpec provides **two distinct clarification commands** for different stages of the workflow:
+
+#### specify vs clarify: When to Use Which?
+
+| Aspect | `/codexspec.specify` | `/codexspec.clarify` |
+|--------|----------------------|----------------------|
+| **Purpose** | Initial requirement exploration | Iterative refinement of existing spec |
+| **When to Use** | Starting with a new idea, no spec.md exists | spec.md exists, need to fill gaps |
+| **Input** | Your initial idea or requirement | Existing spec.md file |
+| **Output** | None (dialogue only) | Updates spec.md with clarifications |
+| **Method** | Open-ended Q&A | Structured ambiguity scan (6 categories) |
+| **Question Limit** | Unlimited | Maximum 5 questions |
+| **Typical Use** | "I want to build a todo app" | "The spec is missing error handling details" |
+
+#### Two-Phase Specification
+
+Before generating any documentation:
+
+| Phase | Command | Purpose | Output |
+|-------|---------|---------|--------|
+| **Explore** | `/codexspec.specify` | Interactive Q&A to explore and refine requirements | None (dialogue only) |
+| **Generate** | `/codexspec.generate-spec` | Compile clarified requirements into structured document | `spec.md` |
+
+#### Iterative Clarification
+
+After spec.md is created:
+
+```
+spec.md ──► /codexspec.clarify ──► Updated spec.md (with Clarifications section)
+                │
+                └── Scans for ambiguities in 6 categories:
+                    • Functional Scope & Behavior
+                    • Domain & Data Model
+                    • Interaction & UX Flow
+                    • Non-Functional Quality Attributes
+                    • Edge Cases & Failure Handling
+                    • Conflict Resolution
+```
+
+#### Benefits of This Design
+
+- **Human-AI collaboration**: You actively participate in requirement discovery
+- **Explicit control**: Files are only created when you decide
+- **Quality focus**: Requirements are thoroughly explored before documentation
+- **Iterative refinement**: Specs can be improved incrementally as understanding deepens
+
 ## Project Structure
 
 After initialization, your project will have this structure:
@@ -485,7 +546,8 @@ CodexSpec is inspired by GitHub's spec-kit but with some key differences:
 | CLI Name | `specify` | `codexspec` |
 | Primary AI | Multi-agent support | Claude Code focused |
 | Command Prefix | `/speckit.*` | `/codexspec.*` |
-| Workflow | specify → plan → tasks → implement | constitution → specify → clarify → plan → tasks → analyze → implement |
+| Workflow | specify → plan → tasks → implement | constitution → specify → generate-spec → plan → tasks → analyze → implement |
+| Two-Phase Spec | No | Yes (clarify + generate) |
 | Review Steps | Optional | Built-in review commands |
 | Clarify Command | Yes | Yes |
 | Analyze Command | Yes | Yes |

{codexspec-0.2.2 → codexspec-0.3.0}/README.md

@@ -132,22 +132,30 @@ Use the `/codexspec.constitution` command to create your project's governing pri
 /codexspec.constitution Create principles focused on code quality, testing standards, and clean architecture
 ```
 
-### 3. Create a Specification
+### 3. Clarify Requirements
 
-Use `/codexspec.specify` to define what you want to build:
+Use `/codexspec.specify` to **explore and clarify** your requirements through interactive Q&A:
 
 ```
-/codexspec.specify Build a task management application with the following features: create tasks, assign to users, set due dates, and track progress
+/codexspec.specify I want to build a task management application
 ```
 
-### 4. Clarify Requirements (Optional but Recommended)
+This command will:
+- Ask clarifying questions to understand your idea
+- Explore edge cases you might not have considered
+- Co-create high-quality requirements through dialogue
+- **NOT** generate files automatically - you stay in control
 
-Use `/codexspec.clarify` to resolve ambiguities before planning:
+### 4. Generate Specification Document
+
+Once requirements are clarified, use `/codexspec.generate-spec` to create the `spec.md` document:
 
 ```
-/codexspec.clarify
+/codexspec.generate-spec
 ```
 
+This command acts as a "requirement compiler" that transforms your clarified requirements into a structured specification document.
+
 ### 5. Create a Technical Plan
 
 Use `/codexspec.spec-to-plan` to define how to implement it:
@@ -219,8 +227,8 @@ After initialization, these slash commands are available in Claude Code:
 | Command | Description |
 |---------|-------------|
 | `/codexspec.constitution` | Create or update project governing principles |
-| `/codexspec.specify` | Define what you want to build (requirements) |
-| `/codexspec.generate-spec` | Generate detailed specification from requirements |
+| `/codexspec.specify` | **Clarify** requirements through interactive Q&A (no file generation) |
+| `/codexspec.generate-spec` | **Generate** `spec.md` document after requirements are clarified |
 | `/codexspec.spec-to-plan` | Convert specification to technical plan |
 | `/codexspec.plan-to-tasks` | Break down plan into actionable tasks |
 | `/codexspec.implement-tasks` | Execute tasks according to breakdown |
@@ -237,7 +245,7 @@ After initialization, these slash commands are available in Claude Code:
 
 | Command | Description |
 |---------|-------------|
-| `/codexspec.clarify` | Clarify underspecified areas before planning |
+| `/codexspec.clarify` | Scan existing spec.md for ambiguities and update with clarifications |
 | `/codexspec.analyze` | Cross-artifact consistency analysis |
 | `/codexspec.checklist` | Generate quality checklists for requirements |
 | `/codexspec.tasks-to-issues` | Convert tasks to GitHub issues |
@@ -252,35 +260,88 @@ After initialization, these slash commands are available in Claude Code:
 │  1. Constitution  ──►  Define project principles             │
 │         │                                                    │
 │         ▼                                                    │
-│  2. Specify  ───────►  Create feature specification          │
+│  2. Specify  ───────►  Interactive Q&A to clarify            │
+│         │             requirements (no file created)         │
 │         │                                                    │
 │         ▼                                                    │
-│  3. Clarify  ───────►  Resolve ambiguities (optional)        │
+│  3. Generate Spec  ─►  Create spec.md document               │
+│         │             (user calls explicitly)                │
 │         │                                                    │
 │         ▼                                                    │
 │  4. Review Spec  ───►  Validate specification                │
 │         │                                                    │
 │         ▼                                                    │
-│  5. Spec to Plan  ──►  Create technical plan                 │
+│  5. Clarify  ───────►  Resolve ambiguities (optional)        │
 │         │                                                    │
 │         ▼                                                    │
-│  6. Review Plan  ───►  Validate technical plan               │
+│  6. Spec to Plan  ──►  Create technical plan                 │
 │         │                                                    │
 │         ▼                                                    │
-│  7. Plan to Tasks  ─►  Generate task breakdown               │
+│  7. Review Plan  ───►  Validate technical plan               │
 │         │                                                    │
 │         ▼                                                    │
-│  8. Analyze  ───────►  Cross-artifact consistency (optional) │
+│  8. Plan to Tasks  ─►  Generate task breakdown               │
 │         │                                                    │
 │         ▼                                                    │
-│  9. Review Tasks  ──►  Validate task breakdown               │
+│  9. Analyze  ───────►  Cross-artifact consistency (optional) │
 │         │                                                    │
 │         ▼                                                    │
-│  10. Implement  ─────►  Execute implementation               │
+│  10. Review Tasks  ─►  Validate task breakdown               │
+│         │                                                    │
+│         ▼                                                    │
+│  11. Implement  ─────►  Execute implementation               │
 │                                                              │
 └──────────────────────────────────────────────────────────────┘
 ```
 
+### Key Concept: Requirement Clarification Workflow
+
+CodexSpec provides **two distinct clarification commands** for different stages of the workflow:
+
+#### specify vs clarify: When to Use Which?
+
+| Aspect | `/codexspec.specify` | `/codexspec.clarify` |
+|--------|----------------------|----------------------|
+| **Purpose** | Initial requirement exploration | Iterative refinement of existing spec |
+| **When to Use** | Starting with a new idea, no spec.md exists | spec.md exists, need to fill gaps |
+| **Input** | Your initial idea or requirement | Existing spec.md file |
+| **Output** | None (dialogue only) | Updates spec.md with clarifications |
+| **Method** | Open-ended Q&A | Structured ambiguity scan (6 categories) |
+| **Question Limit** | Unlimited | Maximum 5 questions |
+| **Typical Use** | "I want to build a todo app" | "The spec is missing error handling details" |
+
+#### Two-Phase Specification
+
+Before generating any documentation:
+
+| Phase | Command | Purpose | Output |
+|-------|---------|---------|--------|
+| **Explore** | `/codexspec.specify` | Interactive Q&A to explore and refine requirements | None (dialogue only) |
+| **Generate** | `/codexspec.generate-spec` | Compile clarified requirements into structured document | `spec.md` |
+
+#### Iterative Clarification
+
+After spec.md is created:
+
+```
+spec.md ──► /codexspec.clarify ──► Updated spec.md (with Clarifications section)
+                │
+                └── Scans for ambiguities in 6 categories:
+                    • Functional Scope & Behavior
+                    • Domain & Data Model
+                    • Interaction & UX Flow
+                    • Non-Functional Quality Attributes
+                    • Edge Cases & Failure Handling
+                    • Conflict Resolution
+```
+
+#### Benefits of This Design
+
+- **Human-AI collaboration**: You actively participate in requirement discovery
+- **Explicit control**: Files are only created when you decide
+- **Quality focus**: Requirements are thoroughly explored before documentation
+- **Iterative refinement**: Specs can be improved incrementally as understanding deepens
+
 ## Project Structure
 
 After initialization, your project will have this structure:
@@ -452,7 +513,8 @@ CodexSpec is inspired by GitHub's spec-kit but with some key differences:
 | CLI Name | `specify` | `codexspec` |
 | Primary AI | Multi-agent support | Claude Code focused |
 | Command Prefix | `/speckit.*` | `/codexspec.*` |
-| Workflow | specify → plan → tasks → implement | constitution → specify → clarify → plan → tasks → analyze → implement |
+| Workflow | specify → plan → tasks → implement | constitution → specify → generate-spec → plan → tasks → analyze → implement |
+| Two-Phase Spec | No | Yes (clarify + generate) |
 | Review Steps | Optional | Built-in review commands |
 | Clarify Command | Yes | Yes |
 | Analyze Command | Yes | Yes |

{codexspec-0.2.2 → codexspec-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.2.2"
+version = "0.3.0"
 description = "CodexSpec - A Spec-Driven Development (SDD) toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

codexspec-0.3.0/templates/commands/clarify.md

@@ -0,0 +1,235 @@
+---
+description: Identify underspecified areas in the current feature spec by asking targeted clarification questions and encoding answers back into the spec
+argument-hint: "[path_to_spec.md] (optional, defaults to .codexspec/specs/{feature-id}/)"
+handoffs:
+  - agent: claude
+    step: Ask clarification questions and update spec
+scripts:
+   sh: .codexspec/scripts/check-prerequisites.sh --json --paths-only
+   ps: .codexspec/scripts/check-prerequisites.ps1 -Json -PathsOnly
+---
+
+# Specification Clarifier
+
+## Language Preference
+
+**IMPORTANT**: Before proceeding, read the project's language configuration from `.codexspec/config.yml`.
+- If `language.output` is set to a language other than "en", respond and generate all content in that language
+- If not configured or set to "en", use English as default
+- Technical terms (e.g., API, JWT, OAuth) may remain in English when appropriate
+- All user-facing messages, questions, and generated documents should use the configured language
+
+## User Input
+
+$ARGUMENTS
+
+## Role
+
+You are a **Specification Quality Specialist** with expertise in:
+- Requirement analysis and decomposition
+- Ambiguity detection and resolution
+- Acceptance criteria formulation
+- Cross-functional requirement identification
+
+Your responsibility is to identify gaps and ambiguities in existing specifications and resolve them through targeted clarification questions.
+
+## When to Use This Command
+
+**Use `/codexspec.clarify` when:**
+- A `spec.md` already exists and needs incremental improvement
+- You want to address specific issues identified during review
+- You need to refine requirements before technical planning
+- New information requires updating the specification
+
+**Do NOT use this command for:**
+- Initial requirement gathering → Use `/codexspec.specify`
+- Document generation from scratch → Use `/codexspec.generate-spec`
+- Quality assessment without modification → Use `/codexspec.review-spec`
+
+## Instructions
+
+### File Resolution
+
+- **With argument**: Treat the argument as the path to `spec.md`
+- **Without argument**: Run `{SCRIPT}` from repo root and parse JSON for:
+  - `FEATURE_DIR` - The feature directory path
+  - `FEATURE_SPEC` - Path to spec.md
+
+If no valid spec.md is found, abort and instruct user to run `/codexspec.generate-spec` first.
+
+### Execution Steps
+
+#### 1. Initialize Context & Load Review Findings
+
+Load and analyze:
+- The feature specification from the located path
+
+**Review-Spec Integration** (if `review-spec.md` exists in the same directory as `spec.md`):
+- Read the review findings
+- Prioritize questions based on issues marked as "Critical" or "Warning"
+- Reference the review in your introduction: "Based on recent review findings..."
+
+This ensures clarification addresses known quality issues first.
+
+#### 2. Ambiguity & Coverage Scan
+
+Scan the specification using these **4 focused categories**:
+
+| Category | What to Look For |
+|----------|-----------------|
+| **Completeness Gaps** | Missing sections, empty content, unnumbered requirements, absent acceptance criteria |
+| **Specificity Issues** | Vague terms ("fast", "scalable", "user-friendly"), undefined technical terms, missing constraints or boundaries |
+| **Behavioral Clarity** | Error handling gaps, undefined state transitions, edge cases without expected behavior |
+| **Measurability Problems** | Non-functional requirements without metrics, untestable acceptance criteria, subjective quality standards |
+
+#### 3. Generate Clarification Questions
+
+Create a prioritized queue of **maximum 5 questions**:
+- Questions must be answerable with multiple-choice (2-4 options) OR a short answer (≤5 words)
+- Only include questions whose answers materially impact implementation
+- Ensure category coverage balance
+- Prioritize questions addressing Critical/Warning issues from review-spec.md (if exists)
+
+#### 4. Sequential Questioning Loop
+
+Present **EXACTLY ONE** question at a time.
+
+**For Multiple-Choice Questions:**
+
+```markdown
+## Question [N/M]: [Category]
+
+**Context**: [Quote the relevant section from spec.md that needs clarification]
+
+**Question**: [Clear, specific question]
+
+| Option | Description | Impact |
+|--------|-------------|--------|
+| A | [Option description] | [How this choice affects implementation] |
+| B | [Option description] | [How this choice affects implementation] |
+| Custom | Provide a different answer | - |
+
+**Recommendation**: Option [X] - [Brief reasoning for recommendation]
+```
+
+Note: Use only as many options (A, B, C, D) as needed (2-4), plus "Custom".
+
+**For Short-Answer Questions:**
+
+```markdown
+## Question [N/M]: [Category]
+
+**Context**: [Quote the relevant section from spec.md that needs clarification]
+
+**Question**: [Clear, specific question]
+
+**Format**: Short answer, maximum 5 words
+
+**Suggestion**: [Proposed answer with reasoning]
+```
+
+#### 5. Integration After Each Answer
+
+After the user provides an answer:
+
+1. **Update Clarifications Section** in spec.md:
+   ```markdown
+   ## Clarifications
+
+   ### Session [YYYY-MM-DD HH:MM]
+
+   **Q1**: [Question asked]
+   **A1**: [User's answer]
+   **Impact**: [Which requirements/sections are affected]
+
+   ---
+   ```
+
+2. **Apply to Relevant Sections**: Update Functional Requirements, Non-Functional Requirements, Edge Cases, etc. based on the answer
+
+3. **Save Immediately**: Write all changes to `spec.md`
+
+#### 6. User Control Commands
+
+During questioning, support these commands:
+| Command | Action | Saved Answers |
+|---------|--------|---------------|
+| `skip` | Skip current question, move to next | Already saved |
+| `done` | End session early, generate report | Already saved |
+| `stop` | End session immediately, no report | Already saved |
+
+All previously answered questions are saved to spec.md regardless of how the session ends.
+
+#### 7. Completion Report
+
+After the session ends (all questions answered, or user used `done`), output this report to the console (do NOT save to a file):
+
+```markdown
+# Clarification Session Report
+
+## Summary
+- **Specification**: {feature-id}/spec.md
+- **Session Date**: {YYYY-MM-DD HH:MM}
+- **Questions Asked**: X/5
+- **Questions Answered**: Y
+- **Questions Skipped**: Z
+
+## Modifications
+
+| Section | Changes Made | Requirements Affected |
+|---------|--------------|----------------------|
+| [Section name] | [Brief description] | REQ-001, REQ-002 |
+| [Section name] | [Brief description] | NFR-001 |
+
+## Requirements Impact
+
+### Added
+- [REQ-XXX]: [New requirement description]
+
+### Modified
+- [REQ-XXX]: [What changed]
+
+### Clarified (No structural change)
+- [REQ-XXX]: [What was clarified]
+
+## Quality Improvement
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Completeness | X% | Y% |
+| Specificity | X% | Y% |
+| Behavioral Clarity | X% | Y% |
+| Measurability | X% | Y% |
+
+## Deferred Items
+
+The following areas were identified but not addressed (question quota reached):
+- [ ] [Category]: [Specific issue description]
+- [ ] [Category]: [Specific issue description]
+
+## Available Follow-up Commands
+
+Based on the clarification session, the user may consider:
+- `/codexspec.review-spec` - to validate the improvements made
+- `/codexspec.spec-to-plan` - to proceed with technical planning
+- `/codexspec.clarify` - to address deferred items in another session
+```
+
+## Behavior Rules
+
+1. **Maximum 5 Questions**: Never exceed the question limit
+2. **Save After Each Answer**: Immediately persist all changes to `spec.md` - the Clarifications section and any updated requirement sections
+3. **No Meaningful Ambiguities**: If scan finds no critical issues, output: "No critical ambiguities detected. The specification appears sufficiently clear for technical planning." and suggest `/codexspec.spec-to-plan`
+4. **Deferred Tracking**: If quota is reached with unresolved high-impact items, list them in the completion report under Deferred Items
+5. **Review Integration**: If review-spec.md exists, always mention it in your introduction and prioritize its Critical/Warning issues
+
+## Workflow Position
+
+```
+specify → generate-spec → [clarify] → review-spec → spec-to-plan
+                               ↑______________|
+                               (iterative)
+```
+
+> [!NOTE]
+> This command is designed to run AFTER `/codexspec.generate-spec` and BEFORE `/codexspec.spec-to-plan`. It incrementally improves existing specifications rather than creating new ones.