codexspec 0.3.4__tar.gz → 0.3.6__tar.gz

{codexspec-0.3.4 → codexspec-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.3.4
+Version: 0.3.6
 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
@@ -13,6 +13,9 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -161,6 +164,55 @@ uv tool install git+https://github.com/Zts0hg/codexspec.git@main
 uv tool install git+https://github.com/Zts0hg/codexspec.git@v0.2.0
 ```
 
+## Windows Users
+
+### Recommended: Use PowerShell
+
+**Windows users should use PowerShell for installation and running CodexSpec**:
+
+```powershell
+# 1. Install uv (if not already installed)
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 2. Restart PowerShell, then install codexspec
+uv tool install codexspec
+
+# 3. Verify installation
+codexspec --version
+```
+
+### Troubleshooting for CMD Users
+
+If you encounter "Access denied" or "spawn codexspec access denied (OSError 5)" errors in CMD:
+
+**Solution 1: Refresh environment variables**
+```cmd
+# Close all CMD windows and open a new one
+# Or manually refresh PATH
+set PATH=%PATH%;%USERPROFILE%\.local\bin
+codexspec --version
+```
+
+**Solution 2: Use full path**
+```cmd
+%USERPROFILE%\.local\bin\codexspec.exe --version
+```
+
+**Solution 3: Use pipx instead of uv tool**
+```cmd
+pip install pipx
+pipx ensurepath
+# Restart CMD
+pipx install codexspec
+```
+
+### FAQ
+
+**Q: Why does PowerShell work but CMD doesn't?**
+A: PowerShell and CMD handle user environment variables differently. When uv adds paths to user PATH, PowerShell typically recognizes them immediately, while CMD may require a restart or manual refresh.
+
+For more details, see [Windows Troubleshooting Guide](docs/WINDOWS-TROUBLESHOOTING.md).
+
 ## Quick Start
 
 After installation, you can use the CLI:
@@ -405,6 +457,7 @@ After initialization, these slash commands are available in Claude Code:
 |---------|-------------|
 | `/codexspec.commit` | Generate Conventional Commits messages based on git status and session context |
 | `/codexspec.commit-staged` | Generate commit message from staged changes only |
+| `/codexspec.pr` | Generate structured PR (GitHub) or MR (GitLab) descriptions with platform auto-detection |
 
 ## Workflow Overview
 

{codexspec-0.3.4 → codexspec-0.3.6}/README.md

@@ -123,6 +123,55 @@ uv tool install git+https://github.com/Zts0hg/codexspec.git@main
 uv tool install git+https://github.com/Zts0hg/codexspec.git@v0.2.0
 ```
 
+## Windows Users
+
+### Recommended: Use PowerShell
+
+**Windows users should use PowerShell for installation and running CodexSpec**:
+
+```powershell
+# 1. Install uv (if not already installed)
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 2. Restart PowerShell, then install codexspec
+uv tool install codexspec
+
+# 3. Verify installation
+codexspec --version
+```
+
+### Troubleshooting for CMD Users
+
+If you encounter "Access denied" or "spawn codexspec access denied (OSError 5)" errors in CMD:
+
+**Solution 1: Refresh environment variables**
+```cmd
+# Close all CMD windows and open a new one
+# Or manually refresh PATH
+set PATH=%PATH%;%USERPROFILE%\.local\bin
+codexspec --version
+```
+
+**Solution 2: Use full path**
+```cmd
+%USERPROFILE%\.local\bin\codexspec.exe --version
+```
+
+**Solution 3: Use pipx instead of uv tool**
+```cmd
+pip install pipx
+pipx ensurepath
+# Restart CMD
+pipx install codexspec
+```
+
+### FAQ
+
+**Q: Why does PowerShell work but CMD doesn't?**
+A: PowerShell and CMD handle user environment variables differently. When uv adds paths to user PATH, PowerShell typically recognizes them immediately, while CMD may require a restart or manual refresh.
+
+For more details, see [Windows Troubleshooting Guide](docs/WINDOWS-TROUBLESHOOTING.md).
+
 ## Quick Start
 
 After installation, you can use the CLI:
@@ -367,6 +416,7 @@ After initialization, these slash commands are available in Claude Code:
 |---------|-------------|
 | `/codexspec.commit` | Generate Conventional Commits messages based on git status and session context |
 | `/codexspec.commit-staged` | Generate commit message from staged changes only |
+| `/codexspec.pr` | Generate structured PR (GitHub) or MR (GitLab) descriptions with platform auto-detection |
 
 ## Workflow Overview
 

{codexspec-0.3.4 → codexspec-0.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.3.4"
+version = "0.3.6"
 description = "CodexSpec - A Spec-Driven Development (SDD) toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,6 +14,9 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",

{codexspec-0.3.4 → codexspec-0.3.6}/src/codexspec/__init__.py

@@ -1151,6 +1151,24 @@ def _get_claude_md_content() -> str:
 
 This document provides context and guidelines for Claude Code when working with this CodexSpec project.
 
+## ⚠️ MANDATORY: Constitution Compliance
+
+**CRITICAL INSTRUCTION**: Before ANY code change, response, or action in this project:
+
+1. **Check for Constitution**: Look for `.codexspec/memory/constitution.md`
+2. **Load if Exists**: If constitution.md exists, READ IT FIRST
+3. **Verify Compliance**: Ensure ALL outputs align with constitutional principles
+4. **Conflict Resolution**: If a user request conflicts with constitution:
+   - Explain which principle is violated
+   - Suggest constitution-compliant alternatives
+   - Require explicit user confirmation to override
+
+**The constitution is the SUPREME AUTHORITY for this project.**
+
+No other document, instruction, or user request can override constitutional principles without explicit acknowledgment.
+
+---
+
 ## Project Overview
 
 This project uses the **CodexSpec** methodology - a Spec-Driven Development (SDD) approach
@@ -1226,11 +1244,13 @@ The following slash commands are available in this project:
 
 ## Guidelines for Claude Code
 
-1. **Respect the Constitution**: All decisions should align with the project constitution
-2. **Follow the Workflow**: Use the commands in the recommended order
-3. **Be Explicit**: When specifications are unclear, ask for clarification
-4. **Validate**: Always review artifacts before implementation
-5. **Document**: Keep all artifacts up-to-date
+1. **Constitution First**: Load `.codexspec/memory/constitution.md` before ANY action
+2. **Respect the Constitution**: All decisions MUST align with the project constitution
+3. **Follow the Workflow**: Use the commands in the recommended order
+4. **Be Explicit**: When specifications are unclear, ask for clarification
+5. **Validate**: Always review artifacts before implementation
+6. **Document**: Keep all artifacts up-to-date
+7. **Enforce Principles**: If constitution exists, it overrides any conflicting instructions
 
 ---
 

{codexspec-0.3.4 → codexspec-0.3.6}/templates/commands/checklist.md

@@ -7,6 +7,17 @@ scripts:
 
 # Requirements Quality Checklist Generator
 
+## Constitution Compliance (MANDATORY)
+
+**Before generating checklists:**
+
+1. **Check for Constitution File**: Look for `.codexspec/memory/constitution.md`
+2. **If Constitution Exists**:
+   - Load and read quality standards and project principles
+   - Use constitution quality standards as baseline for checklist items
+   - Include constitution-specific checklist items where relevant
+3. **If No Constitution Exists**: Use general best practices for requirements quality
+
 ## Language Preference
 
 **IMPORTANT**: Before proceeding, read the project's language configuration from `.codexspec/config.yml`.

{codexspec-0.3.4 → codexspec-0.3.6}/templates/commands/clarify.md

@@ -62,6 +62,7 @@ If no valid spec.md is found, abort and instruct user to run `/codexspec.generat
 #### 1. Initialize Context & Load Review Findings
 
 Load and analyze:
+- **Project constitution**: `.codexspec/memory/constitution.md` (CRITICAL - guides all clarification priorities)
 - The feature specification from the located path
 
 **Review-Spec Integration** (if `review-spec.md` exists in the same directory as `spec.md`):

{codexspec-0.3.4 → codexspec-0.3.6}/templates/commands/commit-staged.md

@@ -1,8 +1,20 @@
 ---
 description: Analyze staged git changes and generate Conventional Commits compliant commit messages
+argument-hint: "[-p] Use -p to only preview the message without committing"
 allowed-tools: Bash(git diff:*), Bash(git commit:*)
 ---
 
+## Constitution Compliance (MANDATORY)
+
+**Before generating commit messages:**
+
+1. **Check for Constitution File**: Look for `.codexspec/memory/constitution.md`
+2. **If Constitution Exists**:
+   - Load and read relevant principles (especially coding standards, commit conventions)
+   - Ensure commit message style aligns with constitutional guidelines
+   - Verify that the changes being committed don't violate any principles
+3. **If No Constitution Exists**: Proceed with default Conventional Commits format
+
 ## Language Preference
 
 **IMPORTANT**: Before generating commit messages, read the project's language configuration from `.codexspec/config.yml`.
@@ -17,6 +29,12 @@ allowed-tools: Bash(git diff:*), Bash(git commit:*)
 - Only the description part should use the configured language
 - Technical terms (e.g., API, JWT, OAuth) may remain in English when appropriate
 
+## Parameter Check
+
+Check if `$ARGUMENTS` contains `-p`:
+- **If `-p` is present**: Preview mode - only output the commit message, do not execute `git commit`
+- **If `-p` is NOT present**: Execute mode - generate the message and execute `git commit` directly
+
 ## Instructions
 
 1. Execute `git diff --staged` to retrieve staged changes.
@@ -29,12 +47,14 @@ allowed-tools: Bash(git diff:*), Bash(git commit:*)
    - Do not add `Co-Authored-By` lines or any references to AI tools/agents
    - The commit message should focus solely on describing the changes
 
-3. Present the generated commit message to the user and ask for confirmation.
+3. **If preview mode (`-p`)**: Display the generated commit message and stop.
 
-4. If confirmed, execute `git commit -m "..."` with the generated message.
+4. **If execute mode (default)**: Execute `git commit -m "..."` directly with the generated message.
 
 ## Important Notes
 
+- In execute mode (default), execute `git commit` directly after generating the message
+- In preview mode (`-p`), only display the commit message without executing
 - If no staged changes exist, inform the user and suggest using `git add` first
 - For breaking changes, include `BREAKING CHANGE:` in the commit body
 - Keep the description concise and in imperative mood (e.g., "add feature" not "added feature")

{codexspec-0.3.4 → codexspec-0.3.6}/templates/commands/commit.md

@@ -1,8 +1,20 @@
 ---
-description: Generate Conventional Commits compliant commit messages based on git status and session context
+description: Generate and execute Conventional Commits compliant commit messages based on git status and session context
+argument-hint: "[-p] Use -p to only preview the message without committing"
 allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git branch:*), Bash(git add:*), Bash(git commit:*)
 ---
 
+## Constitution Compliance (MANDATORY)
+
+**Before generating commit messages:**
+
+1. **Check for Constitution File**: Look for `.codexspec/memory/constitution.md`
+2. **If Constitution Exists**:
+   - Load and read relevant principles (especially coding standards, commit conventions)
+   - Ensure commit message style aligns with constitutional guidelines
+   - Verify that the changes being committed don't violate any principles
+3. **If No Constitution Exists**: Proceed with default Conventional Commits format
+
 ## Language Preference
 
 **IMPORTANT**: Before generating commit messages, read the project's language configuration from `.codexspec/config.yml`.
@@ -31,6 +43,12 @@ Execute the following commands to gather git context:
 3. **Staged Changes**: `git diff --staged`
 4. **Unstaged Changes**: `git diff`
 
+## Parameter Check
+
+Check if `$ARGUMENTS` contains `-p`:
+- **If `-p` is present**: Preview mode - only output the commit message, do not execute `git commit`
+- **If `-p` is NOT present**: Execute mode - generate the message and execute `git commit` directly
+
 ## Decision Logic
 
 Based on the git context, follow this priority order:
@@ -40,8 +58,8 @@ Based on the git context, follow this priority order:
 1. Ignore unstaged changes
 2. Generate a commit message based on staged changes only
 3. Consider the current session conversation history to understand the intent and context
-4. Present the commit message to user for confirmation
-5. If confirmed, execute `git commit -m "..."`
+4. **If preview mode (`-p`)**: Display the commit message and stop
+5. **If execute mode (default)**: Execute `git commit -m "..."` directly
 
 ### Case B: No Staged Changes, But Unstaged Changes Exist
 
@@ -49,7 +67,9 @@ Based on the git context, follow this priority order:
 2. Analyze the unstaged changes
 3. Generate a **suggested** commit message
 4. **REMINDER**: After displaying the commit message, repeat the reminder: "Remember: You must stage changes with `git add` before committing."
-5. Ask user if they want to stage all changes and commit
+5. **STOP here** - Do NOT execute any git commands. The user must manually stage the appropriate changes first.
+
+**Rationale**: When staging area is empty, we cannot safely assume which changes should be committed. The user may only want to commit a subset of the changes, or may need to split changes into multiple commits. Always require explicit user action to stage changes.
 
 ### Case C: No Changes At All
 
@@ -79,6 +99,7 @@ This context helps generate more meaningful commit messages that reflect the "wh
 
 ## Important Notes
 
-- Always confirm with user before executing `git commit`
-- For Case B, display a prominent reminder at the **beginning** before showing the suggested commit message, AND repeat the reminder at the **end** after displaying the message. This ensures the user is aware that the commit message is generated based on unstaged changes (not staged changes), so they can take appropriate action: proceed if intentional, or re-stage specific files and run the command again if they forgot to stage.
+- In execute mode (default), execute `git commit` directly after generating the message (only for Case A with staged changes)
+- In preview mode (`-p`), only display the commit message without executing
+- For Case B (no staged changes), always display the suggested message and stop - never auto-stage or auto-commit
 - Do not make assumptions about change intent without context

codexspec-0.3.6/templates/commands/pr.md

@@ -0,0 +1,366 @@
+---
+description: Generate structured Pull Request (GitHub) or Merge Request (GitLab) descriptions based on git diff and optional spec.md integration
+allowed-tools: Bash(git branch:*), Bash(git diff:*), Bash(git log:*), Bash(git remote:*), Bash(git rev-parse:*), Bash(ls:*), Bash(cat:*)
+---
+
+## Constitution Compliance (MANDATORY)
+
+**Before generating PR description:**
+
+1. **Check for Constitution File**: Look for `.codexspec/memory/constitution.md`
+2. **If Constitution Exists**:
+   - Load and read relevant principles (especially documentation standards, code review guidelines)
+   - Ensure PR description reflects constitutional principles
+   - Verify that the changes align with project quality standards
+3. **If No Constitution Exists**: Proceed with standard PR generation
+
+## Language Preference
+
+**IMPORTANT**: Before generating PR descriptions, read the project's language configuration from `.codexspec/config.yml`.
+
+**PR description language priority**:
+1. If `language.commit` is set, use that language for the PR description
+2. Otherwise, use `language.output` as fallback
+3. If neither is configured, default to English
+
+**Note**:
+- Technical terms (e.g., API, JWT, OAuth, PR, MR) may remain in English when appropriate
+- The PR title and section headers should follow the configured language
+
+**Examples**:
+- `output: "zh-CN"` + `commit: "en"` → Chinese interactions, English PR descriptions
+- `output: "zh-CN"` + `commit: "zh-CN"` → Chinese for both
+- `output: "zh-CN"` + no `commit` setting → Chinese for both (fallback)
+
+## User Input
+
+```
+$ARGUMENTS
+```
+
+## Parameters
+
+Parse `$ARGUMENTS` for the following optional parameters:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--target-branch <branch>` | `origin/main` | Branch to compare against |
+| `--output <file>` | (none) | Save output to file instead of terminal |
+| `--sections <list>` | `all` | Comma-separated sections to include |
+| `--spec <path>` | (none) | Enable spec.md integration (opt-in) |
+
+### `--sections` Values
+- `context` - Background and problem statement
+- `implementation` - Technical approach
+- `testing` - Test coverage information
+- `verify` - Verification steps
+- `all` - Include all sections (default)
+
+Example: `--sections context,implementation,verify`
+
+### `--spec` Usage (Opt-in)
+
+By default, spec.md is **NOT** used. Use `--spec` to enable SDD workflow integration:
+
+| Value | Behavior |
+|-------|----------|
+| (not specified) | No spec integration, generate from git only |
+| `001-auth` | Use `.codexspec/specs/001-auth/spec.md` |
+| `path/to/spec.md` | Use specified spec.md file path |
+
+**When to use**:
+- Following SDD workflow with existing spec.md
+- Want Context section with user stories and requirements
+- Large feature changes with documented specifications
+
+**When NOT to use**:
+- Small bug fixes or minor changes
+- Quick iterations without formal specification
+- Changes unrelated to existing specs
+
+## Git Context Collection
+
+Execute the following commands to gather git context:
+
+1. **Current Branch**: `git branch --show-current`
+2. **Current Branch (full ref)**: `git rev-parse --abbrev-ref HEAD`
+3. **Remote URL**: `git remote get-url origin` (or error if no remote)
+4. **Commits Ahead**: `git log --oneline --no-merges <target-branch>..HEAD`
+5. **File Changes**: `git diff --name-status <target-branch>...HEAD`
+6. **Full Diff**: `git diff <target-branch>...HEAD`
+7. **Commit Messages**: `git log --pretty=format:"%s" --no-merges <target-branch>..HEAD`
+
+## Platform Detection
+
+Detect the Git platform from the remote URL:
+
+### Detection Rules
+
+1. **GitHub**: URL contains `github.com`
+   - Use "Pull Request" terminology
+   - Title format: `## Pull Request: [Title]`
+
+2. **GitLab**: URL contains `gitlab.com`
+   - Use "Merge Request" terminology
+   - Title format: `## Merge Request: [Title]`
+
+3. **Other/No Remote**: Default to GitHub terminology
+   - Display warning if no remote configured
+
+## Spec.md Integration (Opt-in)
+
+Only when `--spec` is provided, read spec.md for Context section.
+
+### Spec Resolution
+
+1. If `--spec` is a number like `001`, resolve to `.codexspec/specs/001-*/spec.md`
+2. If `--spec` is a directory name like `001-auth`, resolve to `.codexspec/specs/001-auth/spec.md`
+3. If `--spec` is a path, use directly
+
+### Content Extraction (Best-Effort)
+
+Extract content from spec.md with priority order:
+1. **User Stories** - Primary source for Context
+2. **Goals** - Fallback if no User Stories
+3. **Overview** - Fallback if no Goals
+4. **Requirements** - Last resort
+
+**Graceful Degradation**:
+- If spec structure is incomplete, use available sections
+- Do not error or warn on incomplete specs
+- Skip Context section if no spec or extraction fails
+
+### Invalid Spec Path Handling
+
+If `--spec` path doesn't exist:
+1. List available specs: `ls .codexspec/specs/`
+2. Display error: "Spec '[path]' not found. Available specs: [list]"
+3. Continue without Context section
+
+## PR Title Generation
+
+Generate the PR title following **Conventional Commits** specification:
+
+- Format: `type(scope): description`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+- If the project has a `CLAUDE.md` with custom commit conventions, follow those instead
+
+### Generation Process
+
+1. **Primary Source**: Analyze git diff content
+   - Identify main components/modules changed
+   - Understand the nature of changes (feature, fix, refactor, etc.)
+   - Determine the appropriate **type** prefix
+
+2. **Supporting Sources**:
+   - Branch name (extract feature/fix hints)
+   - Commit messages (understand intent, look for existing type prefixes)
+
+3. **Synthesis**:
+   - Combine insights into a single descriptive title
+   - Keep it concise but informative
+   - Use imperative mood (e.g., "Add" not "Added")
+
+### Type Determination Rules
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New feature or functionality |
+| `fix` | Bug fix |
+| `docs` | Documentation changes only |
+| `style` | Code style changes (formatting, semicolons, etc.) |
+| `refactor` | Code refactoring without changing behavior |
+| `perf` | Performance improvements |
+| `test` | Adding or modifying tests |
+| `build` | Build system or dependency changes |
+| `ci` | CI/CD configuration changes |
+| `chore` | Other changes that don't modify src or test files |
+| `revert` | Reverting a previous commit |
+
+### Scope (Optional)
+
+Add scope when changes are focused on a specific module/component:
+- `feat(auth): add OAuth2 support`
+- `fix(api): handle timeout errors`
+- `refactor(core): improve caching mechanism`
+
+**Example**:
+- Branch: `feature/auth-cleanup`
+- First commit: "Add password validation"
+- Actual changes: Full authentication refactor
+- **Generated title**: `refactor(auth): improve authentication system with JWT and session management`
+
+## Test File Discovery
+
+Identify test files using language-agnostic patterns:
+
+### Directory Patterns
+- `tests/`
+- `test/`
+- `__tests__/`
+- `spec/`
+
+### File Name Patterns
+- `*_test.py`, `test_*.py`
+- `*.test.js`, `*.spec.ts`
+- `*_test.go`
+- `*Test.java`, `*Tests.java`
+
+### Combined Approach
+Match files that are:
+- In test directories, OR
+- Match file name patterns
+
+## Project Command Detection
+
+Detect project-specific test commands for "How to Verify" section:
+
+| Detection | Command | Example |
+|-----------|---------|---------|
+| `pyproject.toml` + (`pytest.ini` OR `tests/`) | `pytest` | `uv run pytest` or `pytest` |
+| `package.json` + `jest.config.js` | `npm test` | `npm test` |
+| `package.json` + `vitest.config.ts` | `npm run test` | `npm run test` |
+| `Cargo.toml` | `cargo test` | `cargo test` |
+| `go.mod` | `go test` | `go test ./...` |
+| `Makefile` with `test` target | `make test` | `make test` |
+
+**Fallback**: If no project files detected, use generic steps:
+1. Install dependencies
+2. Run tests
+
+## Section Generation
+
+Generate PR sections based on gathered information:
+
+### Context Section
+- **Include**: Only if `--spec` is provided and spec.md found
+- **Content**: Extract from spec.md (User Stories, Goals, Overview)
+- **Skip**: If no spec or extraction fails
+
+### Implementation Section
+- **Source**: Git diff analysis
+- **Content**:
+  - Summary of technical changes
+  - Key files changed with brief descriptions
+  - Architectural decisions if apparent
+
+### Testing Section
+- **Source**: Test file discovery + commit messages
+- **Content**:
+  - Test files discovered
+  - Test coverage information (if available in commits)
+  - Test commands to run
+
+### How to Verify Section
+- **Source**: Project command detection
+- **Content**:
+  - Step-by-step verification instructions
+  - Project-specific test commands
+  - Manual verification steps if applicable
+
+## Section Selection
+
+If `--sections` is specified, only include listed sections:
+- `context` → Include Context section
+- `implementation` → Include Implementation section
+- `testing` → Include Testing section
+- `verify` → Include How to Verify section
+- `all` → Include all sections (default)
+
+## Output Format
+
+### GitHub PR Format
+
+```markdown
+## Pull Request: type(scope): description
+
+### Context
+[Background from spec.md if --spec used]
+
+### Implementation
+[Technical changes summary]
+
+**Key Files Changed:**
+- `path/to/file.py` - [Brief description]
+- `path/to/another.py` - [Brief description]
+
+### Testing
+[Test coverage and methodology]
+
+**Test Commands:**
+```bash
+[project-specific test commands]
+```
+
+### How to Verify
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+...
+```
+
+**Title Examples**:
+- `feat(auth): add OAuth2 login support`
+- `fix(api): resolve timeout issue in user endpoint`
+- `refactor(core): improve caching mechanism`
+- `docs: update API documentation`
+
+### GitLab MR Format
+
+```markdown
+## Merge Request: type(scope): description
+
+### Context
+...
+
+### Implementation
+...
+
+### Testing
+...
+
+### How to Verify
+...
+```
+
+## Edge Cases
+
+### EC-001: Branch Up to Date with Target
+**Scenario**: No commits ahead of target branch
+**Response**: "No changes detected between current branch and [target]. Nothing to generate."
+
+### EC-002: Invalid Target Branch
+**Scenario**: Target branch doesn't exist
+**Response**: "Target branch '[branch]' not found. Please verify the branch name."
+
+### EC-003: Not a Git Repository
+**Scenario**: Command run outside git repo
+**Response**: "Not a git repository. Please run this command from within a git repository."
+
+### EC-004b: Invalid Spec Path
+**Scenario**: `--spec` path doesn't exist
+**Response**: "Spec '[path]' not found. Available specs: [list specs in .codexspec/specs/]"
+
+### EC-005: Detached HEAD State
+**Scenario**: Repository in detached HEAD
+**Response**: "Cannot determine current branch. Please checkout a branch before generating PR description."
+
+### EC-006: No Remote Configured
+**Scenario**: No git remote configured
+**Handling**: Use GitHub terminology with warning: "No remote configured. Defaulting to GitHub terminology."
+
+## Output Modes
+
+### Terminal Output (Default)
+Print the generated PR description to stdout for copy-paste.
+
+### File Output (`--output`)
+Save the PR description to the specified file path.
+
+## Important Notes
+
+- Always verify the current branch has commits ahead of target before generating
+- The PR description should be self-contained and understandable without external context
+- Include enough detail for reviewers to understand the changes
+- Do not include any AI attribution in the PR description
+- Focus on clarity and usefulness for code reviewers

{codexspec-0.3.4 → codexspec-0.3.6}/templates/commands/tasks-to-issues.md

@@ -7,6 +7,17 @@ scripts:
 
 # Tasks to GitHub Issues Converter
 
+## Constitution Compliance (MANDATORY)
+
+**Before converting tasks to issues:**
+
+1. **Check for Constitution File**: Look for `.codexspec/memory/constitution.md`
+2. **If Constitution Exists**:
+   - Load and read project principles
+   - Ensure issue descriptions align with project principles
+   - Include relevant constitutional context in issues if applicable
+3. **If No Constitution Exists**: Proceed with standard issue generation
+
 ## Language Preference
 
 **IMPORTANT**: Before proceeding, read the project's language configuration from `.codexspec/config.yml`.